Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)
Python
Establish single-owner runtime with stream-safe provider hot swaps (#1036)
Ali Khokhar160d63370bf6
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex 1308740e..b2b827a0 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -35,7 +35,8 @@ flowchart LRProxyAPI --> Handlers[API Product Handlers]Handlers --> Router[ModelRouter]Handlers --> Executor[ProviderExecutionService]- Executor --> Providers[ProviderRuntime]+ Executor --> Lease[Provider Generation Lease]+ Lease --> Providers[ProviderRuntime]Providers --> OpenAIChat[OpenAI Chat Providers]Providers --> NativeAnthropic[Anthropic Messages Providers]```@@ -44,9 +45,9 @@ flowchart LRThe installable wheel packages are declared in [pyproject.toml](pyproject.toml):-- [src/free_claude_code/api/](src/free_claude_code/api/) owns the FastAPI app, route handlers, API product handlers, shared- provider execution, model catalog, admin APIs, local optimizations, and- server-tool handling.+- [src/free_claude_code/api/](src/free_claude_code/api/) is the HTTP adapter. It owns the FastAPI app, routes, API product+ handlers, protocol serialization, local optimizations, and narrow+ consumer-owned runtime ports.- [src/free_claude_code/cli/](src/free_claude_code/cli/) owns console entrypoints, client CLI launchers, process/sessionmanagement, and client adapter contracts.- [src/free_claude_code/config/](src/free_claude_code/config/) owns settings, provider metadata, filesystem paths,@@ -60,6 +61,9 @@ The installable wheel packages are declared in [pyproject.toml](pyproject.toml):- [src/free_claude_code/providers/](src/free_claude_code/providers/) owns provider construction, shared provider baseclasses, upstream transports, rate limiting, model listing, and concreteprovider adapters.+- [src/free_claude_code/runtime/](src/free_claude_code/runtime/) is the process composition root. It owns application+ startup and shutdown, provider generations, Admin runtime operations, and the+ concrete wiring between API, providers, messaging, and managed CLI sessions.[tests/](tests/) contains deterministic unit and contract coverage.[smoke/](smoke/) contains local and live product smoke tests that can launch@@ -121,7 +125,7 @@ new places to add unrelated behavior:dependencies. Inbound turn intake, queued node execution, slash commanddependencies, and tree queue internals live in separate modules so newbehavior has one owner instead of growing the workflow object.-- [api/admin_config/](src/free_claude_code/api/admin_config/) owns Admin UI config behavior. Keep+- [config/admin/](src/free_claude_code/config/admin/) owns Admin UI config behavior. Keepprovider fields catalog-driven, and keep manifest, source loading, validation,env rendering, value presentation, and status metadata in their package owners.@@ -147,22 +151,34 @@ for local pre-push verification.supervised server instance, and can restart the server after admin config changes.On final shutdown it best-effort kills registered child processes.-[api/app.py](src/free_claude_code/api/app.py) builds the FastAPI application. `create_app()` configures-logging, registers admin and API routers, attaches HTTP correlation metadata, and-installs exception handlers for validation failures, provider errors, and-unexpected errors. `GracefulLifespanApp` wraps the app so startup failures are-reported without noisy Starlette tracebacks.--[api/runtime.py](src/free_claude_code/api/runtime.py) owns process-lifetime resources through-`AppRuntime`:--- creates and publishes an app-scoped `ProviderRuntime`;-- validates configured models best-effort without blocking first-run admin access;-- starts provider model-list refresh;-- starts optional Discord or Telegram messaging when configured;-- publishes messaging, CLI, and provider state onto `app.state`;-- shuts down messaging platforms, CLI sessions, provider transports, and rate- limiters with bounded best-effort cleanup.+[runtime/bootstrap.py](src/free_claude_code/runtime/bootstrap.py) is the single production composition function. The CLI+supervisor supplies one settings snapshot and its restart callback; bootstrap+configures logging, constructs the runtime owners, supplies+[api/ports.py](src/free_claude_code/api/ports.py) to the pure API factory, and returns the ASGI application.++[api/app.py](src/free_claude_code/api/app.py) registers routers, HTTP correlation middleware, and exception handlers around+an explicit `ApiServices` value. It does not read global settings or construct+runtime resources. `app.state.services` is the only runtime state published to+FastAPI.++[runtime/application.py](src/free_claude_code/runtime/application.py) owns process startup and shutdown, optional messaging,+the managed CLI session manager, Admin pending state, and the injected restart+callback. [runtime/asgi.py](src/free_claude_code/runtime/asgi.py) drives that owner from ASGI lifespan messages and preserves+the concise startup-failure contract.++[runtime/provider_manager.py](src/free_claude_code/runtime/provider_manager.py) is the only owner that constructs, publishes,+retires, and closes provider generations. Each request acquires a generation+lease before routing. Non-streaming responses release it after aggregation;+streaming responses release it from the response iterator's `finally` path on+completion, failure, cancellation, or disconnect. A provider-only Admin Apply+prepares a candidate and commits configuration before publication. New requests+then use the candidate while old streams finish on the retired generation; its+last lease closes it exactly once.++The manager also owns one application-lifetime provider model catalog and its+single best-effort discovery task. The catalog survives provider replacement.+This keeps the server model inventory stable without extra synchronization;+Claude clients may independently retain the list they fetched at startup.## Configuration Model@@ -201,15 +217,17 @@ Model routing configuration is tiered:parsing and configured `MODEL*` inventory. API routing and provider validationdepend on those helpers instead of adding behavior methods to Settings.-[api/admin_config/](src/free_claude_code/api/admin_config/) owns the Admin UI config manifest and+[config/admin/](src/free_claude_code/config/admin/) owns the Admin UI config manifest andmanaged env writes. Provider credential, local URL, proxy, and display-namemetadata is generated from [config/provider_catalog.py](src/free_claude_code/config/provider_catalog.py);admin-only help text stays beside the admin manifest. The package splits sourceloading, value presentation, validation, persistence, and provider status intoseparate modules. [api/admin_routes.py](src/free_claude_code/api/admin_routes.py) exposes local-only-admin endpoints that load, validate, apply, and test config. After an apply,-settings are cache-cleared. Depending on the changed fields, the server either-replaces the app provider runtime or asks the supervised server to restart.+admin endpoints that load and validate config, then delegate runtime operations+through `AdminRuntimePort`. Provider-only Apply prepares prospective settings,+atomically commits the managed env, and publishes a new provider generation.+Restart-required changes preserve the existing supervisor restart flow and do+not publish an in-process generation first.[.env.example](.env.example) is the single install/init/admin template source.It is packaged as a [src/free_claude_code/config/](src/free_claude_code/config/) resource for `fcc-init` and Admin UI@@ -276,20 +294,26 @@ sequenceDiagramparticipant Handler as ProductHandlerparticipant Router as ModelRouterparticipant Exec as ProviderExecution- participant Runtime as ProviderRuntime+ participant Manager as ProviderRuntimeManager+ participant Lease as ProviderGenerationLease+ participant Runtime as ProviderRuntimeGenerationparticipant ProviderClient->>Route: POST /v1/messagesRoute->>Route: require_api_key+ Route->>Manager: acquire current generation+ Manager-->>Route: Lease(settings, provider resolver)Route->>Handler: create messageHandler->>Router: resolve model and thinkingHandler->>Handler: server tools or optimizationsHandler->>Exec: stream routed request- Exec->>Runtime: resolve provider+ Exec->>Lease: resolve provider+ Lease->>Runtime: cached or new providerRuntime->>Provider: cached or new providerExec->>Provider: preflight_streamExec->>Provider: stream_responseProvider-->>Client: Anthropic SSE events+ Route->>Lease: release after complete body```OpenAI Responses uses the same provider execution primitive without importing@@ -305,7 +329,7 @@ provider execution, then converts Anthropic SSE back to Responses SSE.It supports two forms:- Direct provider model refs such as `nvidia_nim/nvidia/model-name`.-- Gateway model IDs decoded by [api/gateway_model_ids.py](src/free_claude_code/api/gateway_model_ids.py).+- Gateway model IDs decoded by [core/gateway_model_ids.py](src/free_claude_code/core/gateway_model_ids.py).If the incoming model is not direct, `ModelRouter` maps it by Claude tier. Namescontaining `opus`, `sonnet`, or `haiku` use the matching tier override when set,@@ -322,9 +346,10 @@ global setting.- no-thinking variants when appropriate;- built-in Claude model IDs for compatibility with Claude clients.-Provider model discovery is app-scoped through `ProviderRuntime`, which caches-model IDs and optional thinking capability metadata for the model-list route and-admin status.+Provider model discovery and optional thinking metadata live in the+application-level catalog owned by `ProviderRuntimeManager`. The catalog is not+part of an individual provider generation, so a hot replacement does not erase+the last useful model list. Discovery failures retain prior entries.Codex-specific model picker shaping stays out of this route. `fcc-codex` fetchesthe same `/v1/models` response at launch, converts FCC gateway IDs into@@ -339,12 +364,13 @@ Provider metadata is neutral and centralized in`ProviderDescriptor` declares provider ID, transport type, capabilities,credential env var, default base URL, settings attribute names, and proxy support.-[providers/runtime/](src/free_claude_code/providers/runtime/) owns the app-scoped provider runtime.-It validates that descriptors, factories, and supported IDs are in sync, builds-shared `ProviderConfig`, checks required credentials, creates providers lazily,-caches them, refreshes model lists, validates configured models, and cleans up-transports. The package splits factory wiring, config building, provider instance-cache, model metadata cache, discovery, and validation into separate modules.+[providers/runtime/](src/free_claude_code/providers/runtime/) owns construction details for one+closable provider generation: factory wiring, provider configuration, lazy+provider instances, and transport cleanup. Application-level generation+publication, request leases, model metadata, discovery orchestration, and+configured-model validation belong to `ProviderRuntimeManager` in the runtime+package. This separates a single generation's resources from process-lifetime+state.[providers/base.py](src/free_claude_code/providers/base.py) defines:@@ -419,7 +445,7 @@ usage quirks such as DeepSeek prompt-cache counters.and [.env.example](.env.example) when user configurable.3. Let Admin UI provider credential, local URL, and proxy fields come from thecatalog. Add admin-only help text or provider-specific fields under- [api/admin_config/](src/free_claude_code/api/admin_config/) only when the generated manifest is+ [config/admin/](src/free_claude_code/config/admin/) only when the generated manifest isinsufficient.4. Implement the provider under [src/free_claude_code/providers/](src/free_claude_code/providers/) using the appropriateshared transport family.@@ -599,12 +625,17 @@ selects Codex for Discord or Telegram.## Messaging Architecture-Messaging is optional. [api/runtime.py](src/free_claude_code/api/runtime.py) calls+Messaging is optional. [runtime/application.py](src/free_claude_code/runtime/application.py) calls`create_messaging_components()` from[messaging/platforms/factory.py](src/free_claude_code/messaging/platforms/factory.py) during startup.If `MESSAGING_PLATFORM` is `none`, or if the selected platform token is missing,the messaging bridge is skipped.+`ApplicationRuntime` privately owns the selected platform runtime, the+`MessagingWorkflow`, and its managed CLI session manager. The workflow owns+conversation snapshot restoration and final persistence flush. The API sees only+the `SessionControlPort` used to preserve `/stop` behavior.+The platform factory returns a `MessagingPlatformComponents` bundle from[messaging/platforms/ports.py](src/free_claude_code/messaging/platforms/ports.py): a`MessagingRuntime` for lifecycle and inbound callbacks, an `OutboundMessenger`@@ -775,7 +806,7 @@ when maintainers want branch-level assurance.1. Add or expose the setting in [config/settings.py](src/free_claude_code/config/settings.py).2. Add the template key to [.env.example](.env.example) if users configure it.-3. Add a `ConfigFieldSpec` under [api/admin_config/](src/free_claude_code/api/admin_config/), or add+3. Add a `ConfigFieldSpec` under [config/admin/](src/free_claude_code/config/admin/), or addprovider catalog metadata when the setting is provider credential, local URL,proxy, or display-name metadata.4. Mark `restart_required` or `session_sensitive` when runtime state cannot bediff --git a/pyproject.toml b/pyproject.tomlindex 531bdcf2..194e28b4 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "3.4.16"+version = "3.4.17"description = "Middleware between Claude Code CLI (Anthropic API) and NVIDIA NIM"readme = "README.md"requires-python = ">=3.14.0"diff --git a/smoke/capabilities.py b/smoke/capabilities.pyindex 7fa94da8..2f8a46e2 100644--- a/smoke/capabilities.py+++ b/smoke/capabilities.py@@ -112,7 +112,7 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = ("provider_routing","provider_runtime","provider_matrix",- "free_claude_code.providers.runtime.ProviderRuntime",+ "free_claude_code.runtime.provider_manager.ProviderRuntimeManager","provider id and Settings","configured BaseProvider instance","503 for missing credentials; invalid_request_error for unknown provider",@@ -278,6 +278,21 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (("tests/providers/test_provider_rate_limit.py",),("test_client_disconnect_mid_stream_does_not_crash_server",),),+ CapabilityContract(+ "provider_runtime",+ "generation_hot_swap",+ "provider_hot_swap",+ "free_claude_code.runtime.provider_manager.ProviderRuntimeManager",+ "validated Admin provider config and concurrent request streams",+ "atomic generation publication with old-stream completion",+ "failed candidate or persistence leaves current generation unchanged",+ (+ "tests/runtime/test_provider_manager.py",+ "tests/api/test_response_streams.py",+ "tests/api/test_admin.py",+ ),+ ("test_provider_hot_swap_preserves_inflight_stream_e2e",),+ ),CapabilityContract("local_providers","lmstudio_native_messages",diff --git a/smoke/features.py b/smoke/features.pyindex 1bc735e9..1e7823a7 100644--- a/smoke/features.py+++ b/smoke/features.py@@ -192,6 +192,21 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (("configured provider",),"upstream disconnects are skips only when classified upstream_unavailable",),+ FeatureCoverage(+ "provider_hot_swap",+ "Provider config changes preserve active streams while new requests switch",+ "public_surface",+ (+ "tests/runtime/test_provider_manager.py",+ "tests/api/test_response_streams.py",+ "tests/api/test_admin.py",+ ),+ (),+ ("test_provider_hot_swap_preserves_inflight_stream_e2e",),+ ("api",),+ (),+ "credential-free local fake upstreams make the scenario always runnable",+ ),FeatureCoverage("discord_telegram_bot","Discord and Telegram product flows render progress and transcripts",diff --git a/smoke/lib/server.py b/smoke/lib/server.pyindex 81970fe2..553e8c61 100644--- a/smoke/lib/server.py+++ b/smoke/lib/server.py@@ -4,7 +4,7 @@ import osimport socketimport subprocessimport time-from collections.abc import Iterator+from collections.abc import Iterable, Iteratorfrom contextlib import contextmanager, suppressfrom dataclasses import dataclassfrom pathlib import Path@@ -34,6 +34,7 @@ def start_server(config: SmokeConfig,*,env_overrides: dict[str, str] | None = None,+ env_unset: Iterable[str] = (),command: list[str] | None = None,name: str = "server",) -> Iterator[RunningServer]:@@ -42,6 +43,8 @@ def start_server(log_path = config.results_dir / f"{name}-{config.worker_id}-{port}.log"env = os.environ.copy()+ for key in env_unset:+ env.pop(key, None)env.update({"HOST": "127.0.0.1",diff --git a/smoke/product/test_runtime_ownership_product_live.py b/smoke/product/test_runtime_ownership_product_live.pynew file mode 100644index 00000000..3652770a--- /dev/null+++ b/smoke/product/test_runtime_ownership_product_live.py@@ -0,0 +1,311 @@+"""Credential-free subprocess coverage for provider generation replacement."""++import json+import threading+import time+from contextlib import ExitStack+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer+from pathlib import Path+from typing import Any++import httpx+import pytest++from free_claude_code.config.env_template import load_env_template+from free_claude_code.config.provider_catalog import PROVIDER_CATALOG+from smoke.lib.config import SmokeConfig+from smoke.lib.server import RunningServer, start_server++pytestmark = [pytest.mark.live, pytest.mark.smoke_target("api")]+++class FakeOpenAIUpstream:+ """Minimal OpenAI-chat upstream with an optionally held response stream."""++ def __init__(self, label: str, *, hold_stream: bool) -> None:+ self.label = label+ self.hold_stream = hold_stream+ self.chat_started = threading.Event()+ self.release_stream = threading.Event()+ self.chat_requests: list[dict[str, Any]] = []+ self._server: ThreadingHTTPServer | None = None+ self._thread: threading.Thread | None = None++ @property+ def base_url(self) -> str:+ if self._server is None:+ raise RuntimeError("Fake upstream is not running")+ port = int(self._server.server_address[1])+ return f"http://127.0.0.1:{port}/v1"++ def __enter__(self) -> FakeOpenAIUpstream:+ upstream = self++ class Handler(BaseHTTPRequestHandler):+ protocol_version = "HTTP/1.1"++ def log_message(self, format: str, *args: Any) -> None:+ return++ def do_GET(self) -> None:+ if self.path.rstrip("/").endswith("/models"):+ upstream._send_models(self)+ return+ self.send_error(404)++ def do_POST(self) -> None:+ if self.path.rstrip("/").endswith("/chat/completions"):+ upstream._send_chat(self)+ return+ self.send_error(404)++ self._server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)+ self._server.daemon_threads = True+ self._thread = threading.Thread(+ target=self._server.serve_forever,+ name=f"fake-openai-{self.label}",+ daemon=True,+ )+ self._thread.start()+ return self++ def __exit__(self, *_exc: object) -> None:+ self.release_stream.set()+ if self._server is not None:+ self._server.shutdown()+ self._server.server_close()+ if self._thread is not None:+ self._thread.join(timeout=5)++ def _send_models(self, handler: BaseHTTPRequestHandler) -> None:+ payload = json.dumps(+ {+ "object": "list",+ "data": [+ {+ "id": f"model-{self.label}",+ "object": "model",+ "created": 0,+ "owned_by": "smoke",+ }+ ],+ }+ ).encode()+ handler.send_response(200)+ handler.send_header("Content-Type", "application/json")+ handler.send_header("Content-Length", str(len(payload)))+ handler.end_headers()+ handler.wfile.write(payload)++ def _send_chat(self, handler: BaseHTTPRequestHandler) -> None:+ length = int(handler.headers.get("content-length", "0"))+ body = handler.rfile.read(length)+ request = json.loads(body) if body else {}+ self.chat_requests.append(request)+ handler.send_response(200)+ handler.send_header("Content-Type", "text/event-stream")+ handler.send_header("Cache-Control", "no-cache")+ handler.send_header("Connection", "close")+ handler.end_headers()+ try:+ self._write_chunk(+ handler,+ content=f"provider-{self.label}-start ",+ finish_reason=None,+ )+ if self.hold_stream:+ time.sleep(0.85)+ self._write_chunk(+ handler,+ content=f"provider-{self.label}-held ",+ finish_reason=None,+ )+ self.chat_started.set()+ if self.hold_stream and not self.release_stream.wait(timeout=30):+ return+ self._write_chunk(+ handler,+ content=f"provider-{self.label}-finish",+ finish_reason=None,+ )+ self._write_chunk(handler, content=None, finish_reason="stop")+ handler.wfile.write(b"data: [DONE]\n\n")+ handler.wfile.flush()+ except OSError:+ return++ def _write_chunk(+ self,+ handler: BaseHTTPRequestHandler,+ *,+ content: str | None,+ finish_reason: str | None,+ ) -> None:+ delta: dict[str, str] = {}+ if content is not None:+ delta = {"role": "assistant", "content": content}+ payload = {+ "id": f"chatcmpl-{self.label}",+ "object": "chat.completion.chunk",+ "created": 0,+ "model": f"model-{self.label}",+ "choices": [+ {+ "index": 0,+ "delta": delta,+ "finish_reason": finish_reason,+ }+ ],+ }+ handler.wfile.write(f"data: {json.dumps(payload)}\n\n".encode())+ handler.wfile.flush()+++def _message_payload(*, stream: bool) -> dict[str, Any]:+ return {+ "model": "claude-sonnet-4-20250514",+ "max_tokens": 64,+ "messages": [{"role": "user", "content": "generation smoke"}],+ "stream": stream,+ }+++def _write_initial_managed_config(home: Path, upstream: FakeOpenAIUpstream) -> None:+ config_path = home / ".fcc" / ".env"+ config_path.parent.mkdir(parents=True, exist_ok=True)+ config_path.write_text(+ load_env_template()+ + "\n"+ + "\n".join(+ [+ "MODEL=lmstudio/model-a",+ "MODEL_OPUS=",+ "MODEL_SONNET=",+ "MODEL_HAIKU=",+ f"LM_STUDIO_BASE_URL={upstream.base_url}",+ "ANTHROPIC_AUTH_TOKEN=",+ "ENABLE_MODEL_THINKING=false",+ "MESSAGING_PLATFORM=none",+ "",+ ]+ ),+ encoding="utf-8",+ )+++def _wait_for_generation_close(server: RunningServer, generation_id: int) -> None:+ deadline = time.monotonic() + 10+ generation_field = f'"generation_id": {generation_id}'+ while time.monotonic() < deadline:+ text = server.log_path.read_text(encoding="utf-8", errors="replace")+ if "provider_generation.closed" in text and generation_field in text:+ return+ time.sleep(0.1)+ raise AssertionError(+ f"generation {generation_id} close trace was not written:\n"+ + server.log_path.read_text(encoding="utf-8", errors="replace")[-3000:]+ )+++def test_provider_hot_swap_preserves_inflight_stream_e2e(+ smoke_config: SmokeConfig,+ tmp_path: Path,+) -> None:+ home = tmp_path / "home"+ downstream_started = threading.Event()+ old_body: list[str] = []+ old_errors: list[BaseException] = []+ credential_env_keys = {+ descriptor.credential_env+ for descriptor in PROVIDER_CATALOG.values()+ if descriptor.credential_env is not None+ }++ with ExitStack() as stack:+ upstream_a = stack.enter_context(FakeOpenAIUpstream("a", hold_stream=True))+ upstream_b = stack.enter_context(FakeOpenAIUpstream("b", hold_stream=False))+ _write_initial_managed_config(home, upstream_a)+ server = stack.enter_context(+ start_server(+ smoke_config,+ name="runtime-ownership",+ env_overrides={+ "HOME": str(home),+ "USERPROFILE": str(home),+ },+ env_unset=credential_env_keys+ | {+ "ANTHROPIC_AUTH_TOKEN",+ "ENABLE_MODEL_THINKING",+ "FCC_ENV_FILE",+ "LM_STUDIO_BASE_URL",+ "MODEL",+ "MODEL_HAIKU",+ "MODEL_OPUS",+ "MODEL_SONNET",+ },+ )+ )++ def consume_old_stream() -> None:+ try:+ with httpx.stream(+ "POST",+ f"{server.base_url}/v1/messages",+ json=_message_payload(stream=True),+ timeout=30,+ ) as response:+ response.raise_for_status()+ downstream_started.set()+ old_body.append("".join(response.iter_text()))+ except BaseException as exc:+ old_errors.append(exc)+ downstream_started.set()++ old_thread = threading.Thread(+ target=consume_old_stream,+ name="old-generation-consumer",+ )+ old_thread.start()+ assert downstream_started.wait(timeout=10)+ assert upstream_a.chat_started.is_set()+ assert old_errors == []++ apply_response = httpx.post(+ f"{server.base_url}/admin/api/config/apply",+ json={+ "values": {+ "MODEL": "lmstudio/model-b",+ "LM_STUDIO_BASE_URL": upstream_b.base_url,+ }+ },+ timeout=smoke_config.timeout_s,+ )+ assert apply_response.status_code == 200, apply_response.text+ apply_body = apply_response.json()+ assert apply_body["applied"] is True+ assert apply_body["pending_fields"] == []+ assert apply_body["restart"]["required"] is False++ new_response = httpx.post(+ f"{server.base_url}/v1/messages",+ json=_message_payload(stream=False),+ timeout=smoke_config.timeout_s,+ )+ assert new_response.status_code == 200, new_response.text+ new_text = "".join(+ block.get("text", "") for block in new_response.json()["content"]+ )+ assert new_text == "provider-b-start provider-b-finish"+ assert not old_body++ upstream_a.release_stream.set()+ old_thread.join(timeout=10)+ assert not old_thread.is_alive()+ assert old_errors == []+ assert "provider-a-start " in old_body[0]+ assert "provider-a-held " in old_body[0]+ assert "provider-a-finish" in old_body[0]+ assert len(upstream_a.chat_requests) == 1+ assert len(upstream_b.chat_requests) == 1+ _wait_for_generation_close(server, generation_id=1)diff --git a/src/free_claude_code/api/__init__.py b/src/free_claude_code/api/__init__.pyindex 5f6a6e42..df901bfc 100644--- a/src/free_claude_code/api/__init__.py+++ b/src/free_claude_code/api/__init__.py@@ -1,17 +1 @@-"""API layer for Claude Code Proxy."""--from .app import create_app-from .models import (- MessagesRequest,- MessagesResponse,- TokenCountRequest,- TokenCountResponse,-)--__all__ = [- "MessagesRequest",- "MessagesResponse",- "TokenCountRequest",- "TokenCountResponse",- "create_app",-]+"""HTTP API adapter for Free Claude Code."""diff --git a/src/free_claude_code/api/admin_config/__init__.py b/src/free_claude_code/api/admin_config/__init__.pydeleted file mode 100644index cdcdf2a3..00000000--- a/src/free_claude_code/api/admin_config/__init__.py+++ /dev/null@@ -1 +0,0 @@-"""Admin configuration internals."""diff --git a/src/free_claude_code/api/admin_routes.py b/src/free_claude_code/api/admin_routes.pyindex 887ba276..7d785824 100644--- a/src/free_claude_code/api/admin_routes.py+++ b/src/free_claude_code/api/admin_routes.py@@ -1,26 +1,21 @@"""Local admin UI routes and APIs."""-import inspectimport ipaddressfrom pathlib import Pathfrom typing import Anyfrom urllib.parse import urlsplitimport httpx-from fastapi import APIRouter, BackgroundTasks, HTTPException, Request+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Requestfrom fastapi.responses import FileResponsefrom pydantic import BaseModel, Field-from free_claude_code.config.model_refs import parse_provider_type-from free_claude_code.config.settings import Settings-from free_claude_code.config.settings import get_settings as get_cached_settings-from free_claude_code.providers.runtime import ProviderRuntime+from free_claude_code.config.admin.manifest import FIELD_BY_KEY+from free_claude_code.config.admin.persistence import validate_updates+from free_claude_code.config.admin.values import load_config_response-from .admin_config.manifest import FIELD_BY_KEY-from .admin_config.persistence import validate_updates, write_managed_env-from .admin_config.status import provider_config_status-from .admin_config.values import load_config_response-from .admin_urls import local_admin_url+from .dependencies import get_services+from .ports import ApiServicesrouter = APIRouter()@@ -107,50 +102,23 @@ async def apply_admin_config(payload: AdminConfigPayload,request: Request,background_tasks: BackgroundTasks,+ services: ApiServices = Depends(get_services),):require_loopback_admin(request)- result = write_managed_env(_filtered_values(payload.values))- if not result["applied"]:- return result-- get_cached_settings.cache_clear()- restart = _restart_metadata(result["pending_fields"], request)- result["restart"] = restart- if restart["required"] and restart["automatic"]:- callback = request.app.state.admin_restart_callback- background_tasks.add_task(_invoke_admin_restart_callback, callback)- request.app.state.admin_pending_fields = []- return result-- old_runtime = getattr(request.app.state, "provider_runtime", None)- if isinstance(old_runtime, ProviderRuntime):- await old_runtime.cleanup()- request.app.state.provider_runtime = ProviderRuntime(get_cached_settings())- request.app.state.admin_pending_fields = result["pending_fields"]+ result = await services.admin.apply_admin_config(_filtered_values(payload.values))+ restart = result.get("restart")+ if isinstance(restart, dict) and restart.get("automatic"):+ background_tasks.add_task(services.admin.request_restart)return result@router.get("/admin/api/status")-async def admin_status(request: Request):+async def admin_status(+ request: Request,+ services: ApiServices = Depends(get_services),+):require_loopback_admin(request)- settings = get_cached_settings()- runtime = getattr(request.app.state, "provider_runtime", None)- cached_models: dict[str, list[str]] = {}- if isinstance(runtime, ProviderRuntime):- cached_models = {- provider_id: sorted(model_ids)- for provider_id, model_ids in runtime.cached_model_ids().items()- }- return {- "status": "running",- "host": settings.host,- "port": settings.port,- "model": settings.model,- "provider": parse_provider_type(settings.model),- "pending_fields": getattr(request.app.state, "admin_pending_fields", []),- "provider_status": provider_config_status(),- "cached_models": cached_models,- }+ return services.admin.admin_status()@router.get("/admin/api/providers/local-status")@@ -166,84 +134,28 @@ async def local_provider_status(request: Request):@router.post("/admin/api/providers/{provider_id}/test")-async def test_provider(provider_id: str, request: Request):+async def test_provider(+ provider_id: str,+ request: Request,+ services: ApiServices = Depends(get_services),+):require_loopback_admin(request)- settings = get_cached_settings()- runtime = _provider_runtime_for_admin(request, settings)- try:- provider = runtime.resolve_provider(provider_id)- infos = await provider.list_model_infos()- except Exception as exc:- return {- "provider_id": provider_id,- "ok": False,- "error_type": type(exc).__name__,- }- runtime.cache_model_infos(provider_id, infos)- return {- "provider_id": provider_id,- "ok": True,- "models": sorted(info.model_id for info in infos),- }+ return await services.admin.test_provider(provider_id)@router.post("/admin/api/models/refresh")-async def refresh_models(request: Request):+async def refresh_models(+ request: Request,+ services: ApiServices = Depends(get_services),+):require_loopback_admin(request)- settings = get_cached_settings()- runtime = _provider_runtime_for_admin(request, settings)- await runtime.refresh_model_list_cache()- return {- "cached_models": {- provider_id: sorted(model_ids)- for provider_id, model_ids in runtime.cached_model_ids().items()- }- }---def _provider_runtime_for_admin(- request: Request, settings: Settings-) -> ProviderRuntime:- runtime = getattr(request.app.state, "provider_runtime", None)- if isinstance(runtime, ProviderRuntime):- return runtime- runtime = ProviderRuntime(settings)- request.app.state.provider_runtime = runtime- return runtime+ return await services.admin.refresh_models()def _filtered_values(values: dict[str, Any]) -> dict[str, Any]:return {key: value for key, value in values.items() if key in FIELD_BY_KEY}-async def _invoke_admin_restart_callback(callback: Any) -> None:- result = callback()- if inspect.isawaitable(result):- await result---def _restart_metadata(fields: list[str], request: Request) -> dict[str, Any]:- callback = getattr(request.app.state, "admin_restart_callback", None)- automatic = bool(fields and callable(callback))- return {- "required": bool(fields),- "automatic": automatic,- "admin_url": _next_admin_url() if automatic else None,- "fields": fields,- }---def _next_admin_url() -> str:- fields = {- field["key"]: field["value"] for field in load_config_response()["fields"]- }- settings = Settings.model_construct(- host=fields.get("HOST") or "0.0.0.0",- port=int(fields.get("PORT") or 8082),- )- return local_admin_url(settings)--def _local_provider_url(provider_id: str, values: dict[str, str]) -> str:if provider_id == "lmstudio":return values.get("LM_STUDIO_BASE_URL", "")diff --git a/src/free_claude_code/api/app.py b/src/free_claude_code/api/app.pyindex a38858fc..a315f3a4 100644--- a/src/free_claude_code/api/app.py+++ b/src/free_claude_code/api/app.py@@ -1,9 +1,6 @@-"""FastAPI application factory and configuration."""+"""Pure FastAPI application factory."""-import osimport traceback-from contextlib import asynccontextmanager-from pathlib import Pathfrom typing import Anyfrom fastapi import FastAPI, Request@@ -11,11 +8,7 @@ from fastapi.exception_handlers import request_validation_exception_handlerfrom fastapi.exceptions import RequestValidationErrorfrom fastapi.responses import JSONResponsefrom loguru import logger-from starlette.types import Receive, Scope, Send-from free_claude_code.config.logging_config import configure_logging-from free_claude_code.config.paths import server_log_path-from free_claude_code.config.settings import get_settingsfrom free_claude_code.core.anthropic import (anthropic_error_payload,get_user_facing_error_message,@@ -27,6 +20,7 @@ from free_claude_code.core.trace import (from free_claude_code.providers.exceptions import ProviderErrorfrom .admin_routes import router as admin_router+from .ports import ApiServicesfrom .request_ids import (attach_request_id_headers,get_request_id,@@ -34,82 +28,13 @@ from .request_ids import (set_request_id,)from .routes import router-from .runtime import AppRuntime, startup_failure_messagefrom .validation_log import summarize_request_validation_body-@asynccontextmanager-async def lifespan(app: FastAPI):- """Application lifespan manager."""- runtime = AppRuntime.for_app(app, settings=get_settings())- await runtime.startup()-- yield-- await runtime.shutdown()---class GracefulLifespanApp:- """ASGI wrapper that reports startup failures without Starlette tracebacks."""-- def __init__(self, app: FastAPI):- self.app = app-- def __getattr__(self, name: str) -> Any:- return getattr(self.app, name)-- async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:- if scope["type"] != "lifespan":- await self.app(scope, receive, send)- return- await self._lifespan(receive, send)-- async def _lifespan(self, receive: Receive, send: Send) -> None:- settings = get_settings()- runtime = AppRuntime.for_app(self.app, settings=settings)- startup_complete = False- while True:- message = await receive()- if message["type"] == "lifespan.startup":- try:- await runtime.startup()- except Exception as exc:- await send(- {- "type": "lifespan.startup.failed",- "message": startup_failure_message(settings, exc),- }- )- return- startup_complete = True- await send({"type": "lifespan.startup.complete"})- continue-- if message["type"] == "lifespan.shutdown":- if startup_complete:- try:- await runtime.shutdown()- except Exception as exc:- logger.error("Shutdown failed: exc_type={}", type(exc).__name__)- await send({"type": "lifespan.shutdown.failed", "message": ""})- return- await send({"type": "lifespan.shutdown.complete"})- return---def create_app(*, lifespan_enabled: bool = True) -> FastAPI:- """Create and configure the FastAPI application."""- settings = get_settings()- log_path = Path(os.getenv("LOG_FILE", server_log_path()))- configure_logging(log_path, verbose_third_party=settings.log_raw_api_payloads)-- app_kwargs: dict[str, Any] = {- "title": "Claude Code Proxy",- "version": "2.1.0",- }- if lifespan_enabled:- app_kwargs["lifespan"] = lifespan- app = FastAPI(**app_kwargs)+def create_app(services: ApiServices) -> FastAPI:+ """Create the HTTP adapter around explicitly supplied runtime services."""+ app = FastAPI(title="Claude Code Proxy", version="2.1.0")+ app.state.services = services@app.middleware("http")async def trace_http_correlation(request: Request, call_next):@@ -131,22 +56,19 @@ def create_app(*, lifespan_enabled: bool = True) -> FastAPI:)return response- # Register routesapp.include_router(admin_router)app.include_router(router)- # Exception handlers@app.exception_handler(RequestValidationError)async def validation_error_handler(request: Request, exc: RequestValidationError):"""Log request shape for 422 debugging without content values."""body: Anytry:body = await request.json()- except Exception as e:- body = {"_json_error": type(e).__name__}+ except Exception as error:+ body = {"_json_error": type(error).__name__}message_summary, tool_names = summarize_request_validation_body(body)-trace_event(stage="ingress",event="server.request.validation_failed",@@ -163,8 +85,8 @@ def create_app(*, lifespan_enabled: bool = True) -> FastAPI:@app.exception_handler(ProviderError)async def provider_error_handler(request: Request, exc: ProviderError):"""Handle provider-specific errors and return Anthropic format."""- err_settings = get_settings()- if err_settings.log_api_error_tracebacks:+ settings = services.requests.current_settings()+ if settings.log_api_error_tracebacks:logger.error("Provider Error: error_type={} status_code={} message={}",exc.error_type,@@ -191,7 +113,7 @@ def create_app(*, lifespan_enabled: bool = True) -> FastAPI:"""Handle general errors and return Anthropic format."""request_id = get_request_id(request)claude_sid = extract_claude_session_id_from_headers(request.headers)- settings = get_settings()+ settings = services.requests.current_settings()with logger.contextualize(http_method=request.method,http_path=request.url.path,@@ -224,8 +146,3 @@ def create_app(*, lifespan_enabled: bool = True) -> FastAPI:return responsereturn app---def create_asgi_app() -> GracefulLifespanApp:- """Create the server ASGI app with graceful lifespan failure reporting."""- return GracefulLifespanApp(create_app(lifespan_enabled=False))diff --git a/src/free_claude_code/api/dependencies.py b/src/free_claude_code/api/dependencies.pyindex 9553f76a..28c071e3 100644--- a/src/free_claude_code/api/dependencies.py+++ b/src/free_claude_code/api/dependencies.py@@ -1,61 +1,44 @@-"""Dependency injection for FastAPI."""+"""FastAPI dependencies for the explicit runtime service boundary."""import secretsfrom fastapi import Depends, HTTPException, Requestfrom loguru import logger-from starlette.applications import Starlettefrom free_claude_code.config.provider_catalog import PROVIDER_CATALOGfrom free_claude_code.config.settings import Settings-from free_claude_code.config.settings import get_settings as _get_settingsfrom free_claude_code.core.anthropic import get_user_facing_error_messagefrom free_claude_code.providers.base import BaseProviderfrom free_claude_code.providers.exceptions import (AuthenticationError,- ServiceUnavailableError,UnknownProviderTypeError,)-from free_claude_code.providers.runtime import ProviderRuntime+from .ports import ApiServices, RequestRuntimeLease-def get_settings() -> Settings:- """Return cached :class:`~config.settings.Settings` (FastAPI-friendly alias)."""- return _get_settings()--def get_provider_runtime(app: Starlette) -> ProviderRuntime:- """Return the app-scoped provider runtime installed by ``AppRuntime``."""- runtime = getattr(app.state, "provider_runtime", None)- if isinstance(runtime, ProviderRuntime):- return runtime- raise ServiceUnavailableError(- "Provider runtime is not configured. Ensure AppRuntime startup ran "- "or assign app.state.provider_runtime for test apps."- )+def get_services(request: Request) -> ApiServices:+ """Return the complete services supplied when the app was constructed."""+ return request.app.state.services-def maybe_provider_runtime(app: Starlette) -> ProviderRuntime | None:- """Return the app-scoped provider runtime when it is installed."""- runtime = getattr(app.state, "provider_runtime", None)- return runtime if isinstance(runtime, ProviderRuntime) else None+def get_settings(services: ApiServices = Depends(get_services)) -> Settings:+ """Return the current request-runtime settings snapshot."""+ return services.requests.current_settings()def resolve_provider(provider_type: str,*,- app: Starlette,+ lease: RequestRuntimeLease,) -> BaseProvider:- """Resolve a provider through the app-scoped provider runtime."""- runtime = get_provider_runtime(app)- should_log_init = not runtime.is_cached(provider_type)+ """Resolve a provider through one retained generation."""+ should_log_init = not lease.is_provider_cached(provider_type)try:- provider = runtime.resolve_provider(provider_type)- except AuthenticationError as e:- # Provider :class:`~providers.exceptions.AuthenticationError` messages are- # curated configuration hints (env var names, docs links), not upstream noise.- detail = str(e).strip() or get_user_facing_error_message(e)- raise HTTPException(status_code=503, detail=detail) from e+ provider = lease.resolve_provider(provider_type)+ except AuthenticationError as exc:+ detail = str(exc).strip() or get_user_facing_error_message(exc)+ raise HTTPException(status_code=503, detail=detail) from excexcept UnknownProviderTypeError:logger.error("Unknown provider_type: '{}'. Supported: {}",@@ -69,16 +52,12 @@ def resolve_provider(def require_api_key(- request: Request, settings: Settings = Depends(get_settings)+ request: Request,+ settings: Settings = Depends(get_settings),) -> None:- """Require a server API key (Anthropic-style).-- Checks `x-api-key` header or `Authorization: Bearer ...` against- `Settings.anthropic_auth_token`. If `ANTHROPIC_AUTH_TOKEN` is empty, this is a no-op.- """+ """Require the configured Anthropic-style server API key."""anthropic_auth_token = settings.anthropic_auth_token.strip()if not anthropic_auth_token:- # No API key configured -> allowreturnheader = (@@ -89,18 +68,14 @@ def require_api_key(if not header:raise HTTPException(status_code=401, detail="Missing API key")- # Support both raw key in X-API-Key and Bearer token in Authorizationtoken = header.strip()if header.lower().startswith("bearer "):token = header.split(" ", 1)[1].strip()-- # Strip anything after the first colon to handle tokens with appended model namesif token and ":" in token:token = token.split(":", 1)[0].strip()- # Constant-time comparison to avoid leaking the configured token via- # response-time differences on a per-byte mismatch (CWE-208).if not secrets.compare_digest(- token.encode("utf-8"), anthropic_auth_token.encode("utf-8")+ token.encode("utf-8"),+ anthropic_auth_token.encode("utf-8"),):raise HTTPException(status_code=401, detail="Invalid API key")diff --git a/src/free_claude_code/api/handlers/messages.py b/src/free_claude_code/api/handlers/messages.pyindex 799500ff..3d4b4b2e 100644--- a/src/free_claude_code/api/handlers/messages.py+++ b/src/free_claude_code/api/handlers/messages.py@@ -82,6 +82,7 @@ class MessagesHandler:model_router: ModelRouter | None = None,token_counter: TokenCounter = get_token_count,provider_execution: ProviderExecutionService | None = None,+ generation_id: int | None = None,) -> None:self._settings = settingsself._model_router = model_router or ModelRouter(settings)@@ -90,6 +91,7 @@ class MessagesHandler:settings,provider_getter,token_counter=token_counter,+ generation_id=generation_id,)self._message_intercepts: tuple[MessageIntercept, ...] = (self._intercept_web_server_tool,diff --git a/src/free_claude_code/api/handlers/responses.py b/src/free_claude_code/api/handlers/responses.pyindex f9771a4d..3ca2e422 100644--- a/src/free_claude_code/api/handlers/responses.py+++ b/src/free_claude_code/api/handlers/responses.py@@ -39,6 +39,7 @@ class ResponsesHandler:model_router: ModelRouter | None = None,responses_adapter: OpenAIResponsesAdapter | None = None,provider_execution: ProviderExecutionService | None = None,+ generation_id: int | None = None,) -> None:self._settings = settingsself._model_router = model_router or ModelRouter(settings)@@ -46,6 +47,7 @@ class ResponsesHandler:self._provider_execution = provider_execution or ProviderExecutionService(settings,provider_getter,+ generation_id=generation_id,)async def create(diff --git a/src/free_claude_code/api/model_catalog.py b/src/free_claude_code/api/model_catalog.pyindex fecdf9a6..04b89495 100644--- a/src/free_claude_code/api/model_catalog.py+++ b/src/free_claude_code/api/model_catalog.py@@ -2,10 +2,13 @@from free_claude_code.config.model_refs import configured_chat_model_refsfrom free_claude_code.config.settings import Settings-from free_claude_code.providers.runtime import ProviderRuntime+from free_claude_code.core.gateway_model_ids import (+ gateway_model_id,+ no_thinking_gateway_model_id,+)-from .gateway_model_ids import gateway_model_id, no_thinking_gateway_model_idfrom .models.responses import ModelResponse, ModelsListResponse+from .ports import RequestRuntimePortDISCOVERED_MODEL_CREATED_AT = "1970-01-01T00:00:00Z"@@ -50,18 +53,16 @@ SUPPORTED_CLAUDE_MODELS = [def build_models_list_response(- settings: Settings, provider_runtime: ProviderRuntime | None+ settings: Settings, runtime: RequestRuntimePort) -> ModelsListResponse:"""Return configured, cached, and compatibility model ids."""models: list[ModelResponse] = []seen: set[str] = set()for ref in configured_chat_model_refs(settings):- supports_thinking = None- if provider_runtime is not None:- supports_thinking = provider_runtime.cached_model_supports_thinking(- ref.provider_id, ref.model_id- )+ supports_thinking = runtime.cached_model_supports_thinking(+ ref.provider_id, ref.model_id+ )_append_provider_model_variants(models,seen,@@ -69,14 +70,13 @@ def build_models_list_response(supports_thinking=supports_thinking,)- if provider_runtime is not None:- for model_info in provider_runtime.cached_prefixed_model_infos():- _append_provider_model_variants(- models,- seen,- model_info.model_id,- supports_thinking=model_info.supports_thinking,- )+ for model_info in runtime.cached_prefixed_model_infos():+ _append_provider_model_variants(+ models,+ seen,+ model_info.model_id,+ supports_thinking=model_info.supports_thinking,+ )for model in SUPPORTED_CLAUDE_MODELS:_append_unique_model(models, seen, model)diff --git a/src/free_claude_code/api/model_router.py b/src/free_claude_code/api/model_router.pyindex fbadc506..f4a1fa91 100644--- a/src/free_claude_code/api/model_router.py+++ b/src/free_claude_code/api/model_router.py@@ -7,8 +7,8 @@ from loguru import loggerfrom free_claude_code.config.model_refs import parse_model_name, parse_provider_typefrom free_claude_code.config.provider_ids import SUPPORTED_PROVIDER_IDSfrom free_claude_code.config.settings import Settings+from free_claude_code.core.gateway_model_ids import decode_gateway_model_id-from .gateway_model_ids import decode_gateway_model_idfrom .models.anthropic import MessagesRequest, TokenCountRequestdiff --git a/src/free_claude_code/api/ports.py b/src/free_claude_code/api/ports.pynew file mode 100644index 00000000..396e1483--- /dev/null+++ b/src/free_claude_code/api/ports.py@@ -0,0 +1,80 @@+"""Runtime capabilities consumed by the HTTP API adapter."""++from collections.abc import Mapping+from dataclasses import dataclass+from typing import Any, Protocol++from free_claude_code.config.settings import Settings+from free_claude_code.providers.base import BaseProvider+from free_claude_code.providers.model_listing import ProviderModelInfo+++class RequestRuntimeLease(Protocol):+ """One provider generation retained for a complete API response."""++ @property+ def generation_id(self) -> int: ...++ @property+ def settings(self) -> Settings: ...++ def is_provider_cached(self, provider_id: str) -> bool: ...++ def resolve_provider(self, provider_id: str) -> BaseProvider: ...++ async def release(self) -> None: ...+++class RequestRuntimePort(Protocol):+ """Provider generation and model-catalog access required by API requests."""++ async def acquire(self) -> RequestRuntimeLease: ...++ def current_settings(self) -> Settings: ...++ def cached_model_ids(self) -> dict[str, frozenset[str]]: ...++ def cached_model_supports_thinking(+ self, provider_id: str, model_id: str+ ) -> bool | None: ...++ def cached_prefixed_model_infos(self) -> tuple[ProviderModelInfo, ...]: ...+++class AdminRuntimePort(Protocol):+ """Runtime operations exposed by the local Admin API."""++ async def apply_admin_config(+ self, updates: Mapping[str, Any]+ ) -> dict[str, Any]: ...++ def admin_status(self) -> dict[str, Any]: ...++ async def test_provider(self, provider_id: str) -> dict[str, Any]: ...++ async def refresh_models(self) -> dict[str, Any]: ...++ async def request_restart(self) -> None: ...+++@dataclass(frozen=True, slots=True)+class StopResult:+ """Implementation-neutral result retaining the existing `/stop` variants."""++ cancelled_count: int | None = None+ source: str | None = None+++class SessionControlPort(Protocol):+ """Stop managed work without exposing messaging or CLI resources."""++ async def stop_all(self) -> StopResult | None: ...+++@dataclass(frozen=True, slots=True)+class ApiServices:+ """Complete runtime boundary required to construct the API application."""++ requests: RequestRuntimePort+ admin: AdminRuntimePort+ sessions: SessionControlPortdiff --git a/src/free_claude_code/api/provider_execution.py b/src/free_claude_code/api/provider_execution.pyindex 6b13d084..e0c6756c 100644--- a/src/free_claude_code/api/provider_execution.py+++ b/src/free_claude_code/api/provider_execution.py@@ -29,10 +29,12 @@ class ProviderExecutionService:provider_getter: ProviderGetter,*,token_counter: TokenCounter = get_token_count,+ generation_id: int | None = None,) -> None:self._settings = settingsself._provider_getter = provider_getterself._token_counter = token_counter+ self._generation_id = generation_iddef stream(self,@@ -62,6 +64,8 @@ class ProviderExecutionService:}if wire_api == "responses":route_trace["wire_api"] = "responses"+ if self._generation_id is not None:+ route_trace["generation_id"] = self._generation_idtrace_event(**route_trace)trace_event(@@ -95,6 +99,14 @@ class ProviderExecutionService:):yield chunk+ stream_trace: dict[str, Any] = {+ "request_id": request_id,+ "provider_id": routed.resolved.provider_id,+ "gateway_model": routed.request.model,+ }+ if self._generation_id is not None:+ stream_trace["generation_id"] = self._generation_id+return traced_async_stream(provider_body(),stage="egress",@@ -110,9 +122,5 @@ class ProviderExecutionService:else "free_claude_code.api.response.stream_interrupted"),chunk_event=None,- extra={- "request_id": request_id,- "provider_id": routed.resolved.provider_id,- "gateway_model": routed.request.model,- },+ extra=stream_trace,)diff --git a/src/free_claude_code/api/response_streams.py b/src/free_claude_code/api/response_streams.pyindex 6cc31f83..109cdef9 100644--- a/src/free_claude_code/api/response_streams.py+++ b/src/free_claude_code/api/response_streams.py@@ -1,8 +1,15 @@"""FastAPI streaming response wrappers for public API wire formats."""import asyncio-from collections.abc import AsyncGenerator, AsyncIterator, Callable, Mapping-from typing import Any+from collections.abc import (+ AsyncGenerator,+ AsyncIterable,+ AsyncIterator,+ Awaitable,+ Callable,+ Mapping,+)+from typing import Any, Protocol, runtime_checkablefrom fastapi.responses import JSONResponse, Response, StreamingResponse@@ -17,12 +24,49 @@ TERMINAL_EXECUTION_ERROR_HEADERS = {"x-should-retry": "false"}PreStartErrorResponse = Callable[[BaseException], Response]TerminalFrameEmitter = Callable[[BaseException], str]+ReleaseResponseResource = Callable[[], Awaitable[None]]+++@runtime_checkable+class _AsyncCloseable(Protocol):+ async def aclose(self) -> None: ...class EmptyStreamError(RuntimeError):"""Raised when a public stream ends before emitting any protocol chunk."""+async def bind_response_lifetime(+ response: object,+ release: ReleaseResponseResource,+) -> object:+ """Retain a runtime resource until a response body is fully consumed."""+ if isinstance(response, StreamingResponse):+ response.body_iterator = _release_after_stream(+ response.body_iterator,+ release,+ )+ return response+ await release()+ return response+++async def _release_after_stream(+ body: AsyncIterable[Any],+ release: ReleaseResponseResource,+) -> AsyncGenerator[Any]:+ iterator = body.__aiter__()+ try:+ async for chunk in iterator:+ yield chunk+ finally:+ try:+ if isinstance(iterator, _AsyncCloseable):+ await iterator.aclose()+ finally:+ await release()++def terminal_execution_error_response(*, status_code: int, content: dict[str, Any]) -> JSONResponse:diff --git a/src/free_claude_code/api/routes.py b/src/free_claude_code/api/routes.pyindex 1234af65..9c192b64 100644--- a/src/free_claude_code/api/routes.py+++ b/src/free_claude_code/api/routes.py@@ -8,76 +8,90 @@ from free_claude_code.config.settings import Settingsfrom free_claude_code.core.anthropic import get_token_countfrom free_claude_code.core.trace import trace_event-from . import dependencies-from .dependencies import get_settings, require_api_key+from .dependencies import (+ get_services,+ get_settings,+ require_api_key,+ resolve_provider,+)from .handlers import MessagesHandler, ResponsesHandler, TokenCountHandlerfrom .model_catalog import build_models_list_responsefrom .models.anthropic import MessagesRequest, TokenCountRequestfrom .models.openai_responses import OpenAIResponsesRequestfrom .models.responses import ModelsListResponse+from .ports import ApiServices, RequestRuntimeLeasefrom .request_ids import get_request_id+from .response_streams import bind_response_lifetimerouter = APIRouter()-def _provider_getter(request: Request, settings: Settings):- return lambda provider_type: dependencies.resolve_provider(- provider_type, app=request.app- )---def get_messages_handler(- request: Request,- settings: Settings = Depends(get_settings),-) -> MessagesHandler:- """Build the Claude Messages product handler for route handlers."""- return MessagesHandler(- settings,- provider_getter=_provider_getter(request, settings),- token_counter=get_token_count,- )---def get_responses_handler(- request: Request,- settings: Settings = Depends(get_settings),-) -> ResponsesHandler:- """Build the OpenAI Responses product handler for route handlers."""- return ResponsesHandler(- settings,- provider_getter=_provider_getter(request, settings),- )+def _provider_getter(lease: RequestRuntimeLease):+ return lambda provider_type: resolve_provider(provider_type, lease=lease)-def get_token_count_handler(- settings: Settings = Depends(get_settings),-) -> TokenCountHandler:- """Build the token-count product handler for route handlers."""- return TokenCountHandler(settings, token_counter=get_token_count)+async def _create_messages_response(+ services: ApiServices,+ request_data: MessagesRequest,+ *,+ request_id: str,+) -> object:+ lease = await services.requests.acquire()+ try:+ handler = MessagesHandler(+ lease.settings,+ provider_getter=_provider_getter(lease),+ token_counter=get_token_count,+ generation_id=lease.generation_id,+ )+ response = await handler.create(request_data, request_id=request_id)+ except BaseException:+ await lease.release()+ raise+ return await bind_response_lifetime(response, lease.release)+++async def _create_responses_response(+ services: ApiServices,+ request_data: OpenAIResponsesRequest,+ *,+ request_id: str,+) -> object:+ lease = await services.requests.acquire()+ try:+ handler = ResponsesHandler(+ lease.settings,+ provider_getter=_provider_getter(lease),+ generation_id=lease.generation_id,+ )+ response = await handler.create(request_data, request_id=request_id)+ except BaseException:+ await lease.release()+ raise+ return await bind_response_lifetime(response, lease.release)def _probe_response(allow: str) -> Response:- """Return an empty success response for compatibility probes."""return Response(status_code=204, headers={"Allow": allow})-# =============================================================================-# Routes-# =============================================================================@router.post("/v1/messages")async def create_message(request: Request,request_data: MessagesRequest,- handler: MessagesHandler = Depends(get_messages_handler),+ services: ApiServices = Depends(get_services),_auth=Depends(require_api_key),):"""Create a message (streaming by default; stream=false gets aggregated JSON)."""- return await handler.create(request_data, request_id=get_request_id(request))+ return await _create_messages_response(+ services,+ request_data,+ request_id=get_request_id(request),+ )@router.api_route("/v1/messages", methods=["HEAD", "OPTIONS"])async def probe_messages(_auth=Depends(require_api_key)):- """Respond to Claude compatibility probes for the messages endpoint."""return _probe_response("POST, HEAD, OPTIONS")@@ -85,16 +99,19 @@ async def probe_messages(_auth=Depends(require_api_key)):async def create_response(request: Request,request_data: OpenAIResponsesRequest,- handler: ResponsesHandler = Depends(get_responses_handler),+ services: ApiServices = Depends(get_services),_auth=Depends(require_api_key),):"""Create an OpenAI Responses-compatible response through this proxy."""- return await handler.create(request_data, request_id=get_request_id(request))+ return await _create_responses_response(+ services,+ request_data,+ request_id=get_request_id(request),+ )@router.api_route("/v1/responses", methods=["HEAD", "OPTIONS"])async def probe_responses(_auth=Depends(require_api_key)):- """Respond to OpenAI Responses compatibility probes."""return _probe_response("POST, HEAD, OPTIONS")@@ -102,24 +119,24 @@ async def probe_responses(_auth=Depends(require_api_key)):async def count_tokens(request: Request,request_data: TokenCountRequest,- handler: TokenCountHandler = Depends(get_token_count_handler),+ settings: Settings = Depends(get_settings),_auth=Depends(require_api_key),):"""Count tokens for a request."""+ handler = TokenCountHandler(settings, token_counter=get_token_count)return handler.count(request_data, request_id=get_request_id(request))@router.api_route("/v1/messages/count_tokens", methods=["HEAD", "OPTIONS"])async def probe_count_tokens(_auth=Depends(require_api_key)):- """Respond to Claude compatibility probes for the token count endpoint."""return _probe_response("POST, HEAD, OPTIONS")@router.get("/")async def root(- settings: Settings = Depends(get_settings), _auth=Depends(require_api_key)+ settings: Settings = Depends(get_settings),+ _auth=Depends(require_api_key),):- """Root endpoint."""return {"status": "ok","provider": parse_provider_type(settings.model),@@ -129,48 +146,44 @@ async def root(@router.api_route("/", methods=["HEAD", "OPTIONS"])async def probe_root():- """Respond to unauthenticated local compatibility probes for the root endpoint."""return _probe_response("GET, HEAD, OPTIONS")@router.get("/health")async def health():- """Health check endpoint."""return {"status": "healthy"}@router.api_route("/health", methods=["HEAD", "OPTIONS"])async def probe_health():- """Respond to compatibility probes for the health endpoint."""return _probe_response("GET, HEAD, OPTIONS")@router.get("/v1/models", response_model=ModelsListResponse)async def list_models(- request: Request,+ services: ApiServices = Depends(get_services),settings: Settings = Depends(get_settings),_auth=Depends(require_api_key),):- """List the model ids this proxy advertises to Claude-compatible clients."""+ """List the model ids this proxy advertises to compatible clients."""trace_event(stage="ingress", event="free_claude_code.api.models.list", source="api")- provider_runtime = dependencies.maybe_provider_runtime(request.app)- return build_models_list_response(settings, provider_runtime)+ return build_models_list_response(settings, services.requests)@router.post("/stop")-async def stop_cli(request: Request, _auth=Depends(require_api_key)):+async def stop_cli(+ services: ApiServices = Depends(get_services),+ _auth=Depends(require_api_key),+):"""Stop all CLI sessions and pending tasks."""- workflow = getattr(request.app.state, "messaging_workflow", None)- if not workflow:- # Fallback if messaging not initialized- cli_manager = getattr(request.app.state, "cli_manager", None)- if cli_manager:- await cli_manager.stop_all()- logger.info("STOP_CLI: source=cli_manager cancelled_count=N/A")- return {"status": "stopped", "source": "cli_manager"}+ result = await services.sessions.stop_all()+ if result is None:raise HTTPException(status_code=503, detail="Messaging system not initialized")+ if result.source is not None:+ logger.info("STOP_CLI: source={} cancelled_count=N/A", result.source)+ return {"status": "stopped", "source": result.source}- count = await workflow.stop_all_tasks()+ count = result.cancelled_count or 0trace_event(stage="ingress",event="free_claude_code.api.cli.stop_via_messaging_workflow",diff --git a/src/free_claude_code/api/runtime.py b/src/free_claude_code/api/runtime.pydeleted file mode 100644index 41a27f63..00000000--- a/src/free_claude_code/api/runtime.py+++ /dev/null@@ -1,328 +0,0 @@-"""Application runtime composition and lifecycle ownership."""--import asyncio-import logging-import os-import traceback-from dataclasses import dataclass, field-from typing import Any--from fastapi import FastAPI-from loguru import logger--import free_claude_code.cli.managed as cli_managed-import free_claude_code.messaging.limiter as messaging_limiter-import free_claude_code.messaging.session as messaging_session-import free_claude_code.messaging.trees as messaging_trees-import free_claude_code.messaging.workflow as messaging_workflow_module-from free_claude_code.api.admin_urls import local_admin_url-from free_claude_code.config.env_files import (- ANTHROPIC_AUTH_TOKEN_ENV,- process_env_key_is_effective,-)-from free_claude_code.config.paths import default_claude_workspace_path-from free_claude_code.config.settings import Settings, get_settings-from free_claude_code.messaging.platforms import factory as messaging_platform_factory-from free_claude_code.messaging.platforms.factory import MessagingPlatformOptions-from free_claude_code.messaging.platforms.ports import (- MessagingPlatformComponents,- MessagingRuntime,-)-from free_claude_code.providers.exceptions import ServiceUnavailableError-from free_claude_code.providers.runtime import ProviderRuntime--_SHUTDOWN_TIMEOUT_S = 5.0---async def best_effort(- name: str,- awaitable: Any,- timeout_s: float = _SHUTDOWN_TIMEOUT_S,- *,- log_verbose_errors: bool = False,-) -> None:- """Run a shutdown step with timeout; never raise to callers."""- try:- await asyncio.wait_for(awaitable, timeout=timeout_s)- except TimeoutError:- logger.warning("Shutdown step timed out: {} ({}s)", name, timeout_s)- except Exception as e:- if log_verbose_errors:- logger.warning(- "Shutdown step failed: {}: {}: {}",- name,- type(e).__name__,- e,- )- else:- logger.warning(- "Shutdown step failed: {}: exc_type={}",- name,- type(e).__name__,- )---def warn_if_process_auth_token(settings: Settings) -> None:- """Warn when server auth was implicitly inherited from the shell."""- model_config = getattr(settings, "model_config", Settings.model_config)- if process_env_key_is_effective(model_config, ANTHROPIC_AUTH_TOKEN_ENV):- logger.warning(- "ANTHROPIC_AUTH_TOKEN is set in the process environment but not in "- "a configured .env file. The proxy will require that token. Add "- "ANTHROPIC_AUTH_TOKEN= to .env to disable proxy auth, or set the "- "same token in .env to make server auth explicit."- )---def log_startup_failure(settings: Settings, exc: Exception) -> None:- """Log startup failures without traceback noise unless verbose diagnostics are enabled."""- message = startup_failure_message(settings, exc)- logger.error("Startup failed:\n{}", message)---def startup_failure_message(settings: Settings, exc: Exception) -> str:- """Return a concise startup failure message for logs and ASGI lifespan failure."""- if isinstance(exc, ServiceUnavailableError):- return exc.message.strip() or "Server startup failed."-- if settings.log_api_error_tracebacks:- return f"{type(exc).__name__}: {exc}"-- return f"Server startup failed: exc_type={type(exc).__name__}"---@dataclass(slots=True)-class AppRuntime:- """Own optional messaging, CLI, session, and provider runtime resources."""-- app: FastAPI- settings: Settings- _provider_runtime: ProviderRuntime | None = field(default=None, init=False)- messaging_runtime: MessagingRuntime | None = None- messaging_workflow: messaging_workflow_module.MessagingWorkflow | None = None- cli_manager: cli_managed.ManagedClaudeSessionManager | None = None-- @classmethod- def for_app(- cls,- app: FastAPI,- settings: Settings | None = None,- ) -> AppRuntime:- return cls(app=app, settings=settings or get_settings())-- async def startup(self) -> None:- logger.info("Starting Claude Code Proxy...")- admin_url = local_admin_url(self.settings)- self._provider_runtime = ProviderRuntime(self.settings)- self.app.state.provider_runtime = self._provider_runtime- try:- warn_if_process_auth_token(self.settings)- await self._validate_configured_models_best_effort()- self._provider_runtime.start_model_list_refresh()- await self._start_messaging_if_configured()- self._publish_state()- logging.getLogger("uvicorn.error").info(- "Admin UI: %s (local-only)", admin_url- )- except Exception as exc:- log_startup_failure(self.settings, exc)- await best_effort(- "provider_runtime.cleanup",- self._provider_runtime.cleanup(),- log_verbose_errors=self.settings.log_api_error_tracebacks,- )- raise-- async def _validate_configured_models_best_effort(self) -> None:- """Warm validation status without blocking first-run/admin access."""- if self._provider_runtime is None:- return- try:- await self._provider_runtime.validate_configured_models()- except ServiceUnavailableError as exc:- self.app.state.startup_validation_error = exc.message- logger.warning(- "Configured provider model validation failed during startup; "- "server will continue and requests will fail at provider resolution "- "when config is incomplete. {}",- exc.message,- )-- async def shutdown(self) -> None:- verbose = self.settings.log_api_error_tracebacks- if self.messaging_workflow is not None:- try:- self.messaging_workflow.session_store.flush_pending_save()- except Exception as e:- if verbose:- logger.warning("Session store flush on shutdown: {}", e)- else:- logger.warning(- "Session store flush on shutdown: exc_type={}",- type(e).__name__,- )-- logger.info("Shutdown requested, cleaning up...")- if self.messaging_runtime:- await best_effort(- "messaging_runtime.stop",- self.messaging_runtime.stop(),- log_verbose_errors=verbose,- )- if self.cli_manager:- await best_effort(- "cli_manager.stop_all",- self.cli_manager.stop_all(),- log_verbose_errors=verbose,- )- if self._provider_runtime is not None:- await best_effort(- "provider_runtime.cleanup",- self._provider_runtime.cleanup(),- log_verbose_errors=verbose,- )- await self._shutdown_limiter()- logger.info("Server shut down cleanly")-- async def _start_messaging_if_configured(self) -> None:- try:- components = messaging_platform_factory.create_messaging_components(- self.settings.messaging_platform,- MessagingPlatformOptions(- telegram_bot_token=self.settings.telegram_bot_token,- allowed_telegram_user_id=self.settings.allowed_telegram_user_id,- telegram_proxy_url=self.settings.telegram_proxy_url,- discord_bot_token=self.settings.discord_bot_token,- allowed_discord_channels=self.settings.allowed_discord_channels,- voice_note_enabled=self.settings.voice_note_enabled,- whisper_model=self.settings.whisper_model,- whisper_device=self.settings.whisper_device,- huggingface_api_key=self.settings.huggingface_api_key,- nvidia_nim_api_key=self.settings.nvidia_nim_api_key,- messaging_rate_limit=self.settings.messaging_rate_limit,- messaging_rate_window=self.settings.messaging_rate_window,- log_raw_messaging_content=self.settings.log_raw_messaging_content,- log_api_error_tracebacks=self.settings.log_api_error_tracebacks,- ),- )-- if components:- await self._start_messaging_workflow(components)-- except ImportError as e:- if self.settings.log_api_error_tracebacks:- logger.warning("Messaging module import error: {}", e)- else:- logger.warning(- "Messaging module import error: exc_type={}",- type(e).__name__,- )- except Exception as e:- if self.settings.log_api_error_tracebacks:- logger.error("Failed to start messaging platform: {}", e)- logger.error(traceback.format_exc())- else:- logger.error(- "Failed to start messaging platform: exc_type={}",- type(e).__name__,- )-- async def _start_messaging_workflow(- self, components: MessagingPlatformComponents- ) -> None:- workspace = (- os.path.abspath(self.settings.allowed_dir)- if self.settings.allowed_dir- else os.getcwd()- )- os.makedirs(workspace, exist_ok=True)-- data_path = os.path.abspath(default_claude_workspace_path())- os.makedirs(data_path, exist_ok=True)-- api_url = f"http://{self.settings.host}:{self.settings.port}/v1"- allowed_dirs = [workspace] if self.settings.allowed_dir else []- plans_dir_abs = os.path.abspath(os.path.join(data_path, "plans"))- plans_directory = os.path.relpath(plans_dir_abs, workspace)- self.cli_manager = cli_managed.ManagedClaudeSessionManager(- workspace_path=workspace,- api_url=api_url,- allowed_dirs=allowed_dirs,- plans_directory=plans_directory,- auth_token=getattr(self.settings, "anthropic_auth_token", ""),- log_raw_cli_diagnostics=self.settings.log_raw_cli_diagnostics,- log_messaging_error_details=self.settings.log_messaging_error_details,- )-- session_store = messaging_session.SessionStore(- storage_path=os.path.join(data_path, "sessions.json"),- message_log_cap=self.settings.max_message_log_entries_per_chat,- )- self.messaging_runtime = components.runtime- self.messaging_workflow = messaging_workflow_module.MessagingWorkflow(- platform_name=components.name,- outbound=components.outbound,- voice_cancellation=components.voice_cancellation,- cli_manager=self.cli_manager,- session_store=session_store,- debug_platform_edits=self.settings.debug_platform_edits,- debug_subagent_stack=self.settings.debug_subagent_stack,- log_raw_messaging_content=self.settings.log_raw_messaging_content,- log_raw_cli_diagnostics=self.settings.log_raw_cli_diagnostics,- log_messaging_error_details=self.settings.log_messaging_error_details,- )- self._restore_tree_state(session_store)-- components.runtime.on_message(self.messaging_workflow.handle_message)- await components.runtime.start()- logger.info("{} platform started with messaging workflow", components.name)-- def _restore_tree_state(- self, session_store: messaging_session.SessionStore- ) -> None:- conversation_snapshot = session_store.load_conversation_snapshot()- if conversation_snapshot.is_empty:- return- if self.messaging_workflow is None:- return-- logger.info(- "Restoring {} conversation trees...",- len(conversation_snapshot.trees),- )-- self.messaging_workflow.replace_tree_queue(- messaging_trees.TreeQueueManager.from_snapshot(- conversation_snapshot,- queue_update_callback=self.messaging_workflow.update_queue_positions,- node_started_callback=self.messaging_workflow.mark_node_processing,- )- )- if self.messaging_workflow.tree_queue.cleanup_stale_nodes() > 0:- session_store.save_conversation_snapshot(- self.messaging_workflow.tree_queue.snapshot()- )-- def _publish_state(self) -> None:- self.app.state.messaging_runtime = self.messaging_runtime- self.app.state.messaging_workflow = self.messaging_workflow- self.app.state.cli_manager = self.cli_manager-- async def _shutdown_limiter(self) -> None:- verbose = self.settings.log_api_error_tracebacks- try:- await best_effort(- "MessagingRateLimiter.shutdown_instance",- messaging_limiter.MessagingRateLimiter.shutdown_instance(),- timeout_s=2.0,- log_verbose_errors=verbose,- )- except Exception as e:- if verbose:- logger.debug(- "Rate limiter shutdown skipped: {}: {}", type(e).__name__, e- )- else:- logger.debug(- "Rate limiter shutdown skipped: exc_type={}", type(e).__name__- )diff --git a/src/free_claude_code/cli/entrypoints.py b/src/free_claude_code/cli/entrypoints.pyindex e73d994d..c3ba60b0 100644--- a/src/free_claude_code/cli/entrypoints.py+++ b/src/free_claude_code/cli/entrypoints.py@@ -10,8 +10,6 @@ from pathlib import Pathimport uvicorn-from free_claude_code.api.admin_urls import local_admin_url, local_proxy_root_url-from free_claude_code.api.app import GracefulLifespanApp, create_appfrom free_claude_code.cli.launchers.common import preflight_proxyfrom free_claude_code.cli.process_registry import (kill_all_best_effort,@@ -26,7 +24,9 @@ from free_claude_code.config.paths import (legacy_env_paths,managed_env_path,)+from free_claude_code.config.server_urls import local_admin_url, local_proxy_root_urlfrom free_claude_code.config.settings import Settings, get_settings+from free_claude_code.runtime.bootstrap import build_asgi_appSERVER_GRACEFUL_SHUTDOWN_SECONDS = 5@@ -93,9 +93,7 @@ def _run_supervised_server(settings: Settings, *, open_admin_browser: bool) -> bif server := server_holder.get("server"):server.should_exit = True- app = create_app(lifespan_enabled=False)- app.state.admin_restart_callback = request_restart- asgi_app = GracefulLifespanApp(app)+ asgi_app = build_asgi_app(settings, restart_callback=request_restart)config = uvicorn.Config(asgi_app,host=settings.host,diff --git a/src/free_claude_code/cli/launchers/claude.py b/src/free_claude_code/cli/launchers/claude.pyindex 459201ff..6cdbe0fb 100644--- a/src/free_claude_code/cli/launchers/claude.py+++ b/src/free_claude_code/cli/launchers/claude.py@@ -4,12 +4,12 @@ import osimport sysfrom collections.abc import Mapping, Sequence-from free_claude_code.api.admin_urls import local_proxy_root_urlfrom free_claude_code.cli.claude_env import (CLAUDE_BINARY_NAME,CLAUDE_CODE_AUTO_COMPACT_WINDOW,claude_auth_token,)+from free_claude_code.config.server_urls import local_proxy_root_urlfrom free_claude_code.config.settings import get_settingsfrom .common import preflight_proxy, resolve_client_binary, run_client_processdiff --git a/src/free_claude_code/cli/launchers/codex.py b/src/free_claude_code/cli/launchers/codex.pyindex ae459e08..605ff3df 100644--- a/src/free_claude_code/cli/launchers/codex.py+++ b/src/free_claude_code/cli/launchers/codex.py@@ -6,8 +6,8 @@ import sysfrom collections.abc import Mapping, Sequencefrom urllib.request import Request, urlopen-from free_claude_code.api.admin_urls import local_proxy_root_urlfrom free_claude_code.config.paths import codex_model_catalog_path+from free_claude_code.config.server_urls import local_proxy_root_urlfrom free_claude_code.config.settings import Settings, get_settingsfrom .codex_model_catalog import build_codex_model_catalog, write_codex_model_catalogdiff --git a/src/free_claude_code/cli/launchers/codex_model_catalog.py b/src/free_claude_code/cli/launchers/codex_model_catalog.pyindex 85d893ce..94a0e440 100644--- a/src/free_claude_code/cli/launchers/codex_model_catalog.py+++ b/src/free_claude_code/cli/launchers/codex_model_catalog.py@@ -7,11 +7,11 @@ from dataclasses import dataclassfrom pathlib import Pathfrom typing import Any-from free_claude_code.api.gateway_model_ids import (+from free_claude_code.config.provider_ids import SUPPORTED_PROVIDER_IDS+from free_claude_code.core.gateway_model_ids import (GATEWAY_MODEL_ID_PREFIX,NO_THINKING_GATEWAY_MODEL_ID_PREFIX,)-from free_claude_code.config.provider_ids import SUPPORTED_PROVIDER_IDSSUPPORTED_REASONING_LEVELS = [{"effort": "low", "description": "Fast responses with lighter reasoning"},diff --git a/src/free_claude_code/config/admin/__init__.py b/src/free_claude_code/config/admin/__init__.pynew file mode 100644index 00000000..71e00b85--- /dev/null+++ b/src/free_claude_code/config/admin/__init__.py@@ -0,0 +1 @@+"""Admin configuration schema, persistence, and presentation metadata."""diff --git a/src/free_claude_code/api/admin_config/manifest.py b/src/free_claude_code/config/admin/manifest.pysimilarity index 99%rename from src/free_claude_code/api/admin_config/manifest.pyrename to src/free_claude_code/config/admin/manifest.pyindex 319b01c1..0565967d 100644--- a/src/free_claude_code/api/admin_config/manifest.py+++ b/src/free_claude_code/config/admin/manifest.py@@ -1,4 +1,4 @@-"""Admin UI configuration manifest."""+"""Admin configuration manifest."""from collections.abc import Iterablefrom dataclasses import dataclassdiff --git a/src/free_claude_code/api/admin_config/persistence.py b/src/free_claude_code/config/admin/persistence.pysimilarity index 62%rename from src/free_claude_code/api/admin_config/persistence.pyrename to src/free_claude_code/config/admin/persistence.pyindex 66ac80df..5dbd82d8 100644--- a/src/free_claude_code/api/admin_config/persistence.py+++ b/src/free_claude_code/config/admin/persistence.py@@ -2,16 +2,59 @@import osfrom collections.abc import Mapping+from dataclasses import dataclass+from pathlib import Pathfrom typing import Anyfrom free_claude_code.config.paths import managed_env_path+from free_claude_code.config.settings import Settingsfrom .manifest import FIELD_BY_KEY, FIELDS, SECTIONS, ConfigFieldSpecfrom .sources import dotenv_values_from_file, is_locked_source, template_values-from .validation import validate_values+from .validation import settings_from_valuesfrom .values import MASKED_SECRET, load_value_state, normalize_for_env+@dataclass(frozen=True, slots=True)+class PreparedAdminUpdate:+ """Validated Admin update ready for an atomic managed-file commit."""++ target_values: dict[str, str]+ settings: Settings | None+ errors: tuple[str, ...]+ pending_fields: tuple[str, ...]+ path: Path++ @property+ def valid(self) -> bool:+ return self.settings is not None++ def validation_response(self) -> dict[str, Any]:+ return {+ "valid": self.valid,+ "errors": list(self.errors),+ "env_preview": render_env_file(self.target_values, mask_secrets=True),+ }++ def applied_response(self) -> dict[str, Any]:+ if not self.valid:+ return self.validation_response() | {+ "applied": False,+ "pending_fields": [],+ }+ return {+ "applied": True,+ "valid": True,+ "errors": [],+ "env_preview": render_env_file(+ self.target_values,+ mask_secrets=True,+ ),+ "path": str(self.path),+ "pending_fields": list(self.pending_fields),+ }++def target_values_with_updates(updates: Mapping[str, Any]) -> dict[str, str]:"""Return managed env values after applying admin updates."""@@ -60,14 +103,7 @@ def effective_values_for_validation(def validate_updates(updates: Mapping[str, Any]) -> dict[str, Any]:"""Validate partial admin updates and return a masked generated env preview."""- target_values = target_values_with_updates(updates)- effective_values = effective_values_for_validation(target_values)- valid, errors = validate_values(effective_values)- return {- "valid": valid,- "errors": errors,- "env_preview": render_env_file(target_values, mask_secrets=True),- }+ return prepare_admin_update(updates).validation_response()def changed_pending_fields(updates: Mapping[str, Any]) -> list[str]:@@ -85,28 +121,42 @@ def changed_pending_fields(updates: Mapping[str, Any]) -> list[str]:return pending-def write_managed_env(updates: Mapping[str, Any]) -> dict[str, Any]:- """Validate and atomically write the admin-managed env file."""-- validation = validate_updates(updates)- if not validation["valid"]:- return validation | {"applied": False, "pending_fields": []}+def prepare_admin_update(updates: Mapping[str, Any]) -> PreparedAdminUpdate:+ """Validate an update and construct its prospective Settings snapshot."""target_values = target_values_with_updates(updates)- pending_fields = changed_pending_fields(updates)- path = managed_env_path()+ effective_values = effective_values_for_validation(target_values)+ settings, errors = settings_from_values(effective_values)+ pending_fields = (+ tuple(changed_pending_fields(updates)) if settings is not None else ()+ )+ return PreparedAdminUpdate(+ target_values=target_values,+ settings=settings,+ errors=tuple(errors),+ pending_fields=pending_fields,+ path=managed_env_path(),+ )+++def commit_prepared_admin_update(prepared: PreparedAdminUpdate) -> dict[str, Any]:+ """Atomically persist a previously validated Admin update."""++ if not prepared.valid:+ raise ValueError("Cannot commit an invalid Admin update")++ path = prepared.pathpath.parent.mkdir(parents=True, exist_ok=True)temp_path = path.with_suffix(path.suffix + ".tmp")- temp_path.write_text(render_env_file(target_values), encoding="utf-8")- os.replace(temp_path, path)- return {- "applied": True,- "valid": True,- "errors": [],- "env_preview": render_env_file(target_values, mask_secrets=True),- "path": str(path),- "pending_fields": pending_fields,- }+ try:+ temp_path.write_text(+ render_env_file(prepared.target_values),+ encoding="utf-8",+ )+ os.replace(temp_path, path)+ finally:+ temp_path.unlink(missing_ok=True)+ return prepared.applied_response()def quote_env_value(value: str) -> str:diff --git a/src/free_claude_code/api/admin_config/provider_manifest.py b/src/free_claude_code/config/admin/provider_manifest.pysimilarity index 99%rename from src/free_claude_code/api/admin_config/provider_manifest.pyrename to src/free_claude_code/config/admin/provider_manifest.pyindex a8c26a11..0e8f739e 100644--- a/src/free_claude_code/api/admin_config/provider_manifest.py+++ b/src/free_claude_code/config/admin/provider_manifest.py@@ -1,4 +1,4 @@-"""Catalog-derived Admin UI provider fields."""+"""Catalog-derived Admin provider fields."""from typing import Anydiff --git a/src/free_claude_code/api/admin_config/sources.py b/src/free_claude_code/config/admin/sources.pysimilarity index 100%rename from src/free_claude_code/api/admin_config/sources.pyrename to src/free_claude_code/config/admin/sources.pydiff --git a/src/free_claude_code/api/admin_config/status.py b/src/free_claude_code/config/admin/status.pysimilarity index 92%rename from src/free_claude_code/api/admin_config/status.pyrename to src/free_claude_code/config/admin/status.pyindex fad940fe..adfa2a55 100644--- a/src/free_claude_code/api/admin_config/status.py+++ b/src/free_claude_code/config/admin/status.py@@ -9,14 +9,9 @@ from .manifest import FIELDSdef provider_config_status(- state: Mapping[str, Mapping[str, Any]] | None = None,+ state: Mapping[str, Mapping[str, Any]],) -> list[dict[str, Any]]:"""Return provider configuration status without making network calls."""-- if state is None:- from .values import load_value_state-- state = load_value_state()statuses: list[dict[str, Any]] = []for provider_id, descriptor in PROVIDER_CATALOG.items():if descriptor.credential_env is None:diff --git a/src/free_claude_code/api/admin_config/validation.py b/src/free_claude_code/config/admin/validation.pysimilarity index 71%rename from src/free_claude_code/api/admin_config/validation.pyrename to src/free_claude_code/config/admin/validation.pyindex 60b3586f..c37c5d59 100644--- a/src/free_claude_code/api/admin_config/validation.py+++ b/src/free_claude_code/config/admin/validation.py@@ -1,4 +1,4 @@-"""Settings-backed Admin UI config validation."""+"""Settings-backed Admin config validation."""from collections.abc import Mappingfrom typing import Any@@ -13,6 +13,15 @@ from .manifest import FIELDS, field_input_keydef validate_values(values: Mapping[str, str]) -> tuple[bool, list[str]]:"""Validate proposed env values against the Settings model."""+ settings, errors = settings_from_values(values)+ return settings is not None, errors+++def settings_from_values(+ values: Mapping[str, str],+) -> tuple[Settings | None, list[str]]:+ """Build the prospective Settings snapshot without reading dotenv files."""+kwargs: dict[str, Any] = {"_env_file": None}for field in FIELDS:input_key = field_input_key(field)@@ -21,10 +30,9 @@ def validate_values(values: Mapping[str, str]) -> tuple[bool, list[str]]:kwargs[input_key] = values.get(field.key, "")try:- Settings(**kwargs)+ return Settings(**kwargs), []except ValidationError as exc:- return False, format_validation_errors(exc)- return True, []+ return None, format_validation_errors(exc)def format_validation_errors(exc: ValidationError) -> list[str]:diff --git a/src/free_claude_code/api/admin_config/values.py b/src/free_claude_code/config/admin/values.pysimilarity index 100%rename from src/free_claude_code/api/admin_config/values.pyrename to src/free_claude_code/config/admin/values.pydiff --git a/src/free_claude_code/api/admin_urls.py b/src/free_claude_code/config/server_urls.pysimilarity index 77%rename from src/free_claude_code/api/admin_urls.pyrename to src/free_claude_code/config/server_urls.pyindex 34154940..c5414384 100644--- a/src/free_claude_code/api/admin_urls.py+++ b/src/free_claude_code/config/server_urls.py@@ -1,4 +1,4 @@-"""Helpers for presenting local admin URLs."""+"""Browser-friendly local server URLs shared by runtime and launchers."""from free_claude_code.config.settings import Settings@@ -24,9 +24,3 @@ def local_admin_url(settings: Settings) -> str:"""Return a browser-friendly URL for the localhost-only admin UI."""return f"{local_proxy_root_url(settings)}/admin"---def admin_launch_message(settings: Settings) -> str:- """Return the startup message shown by supported launch commands."""-- return f"Admin UI: {local_admin_url(settings)} (local-only)"diff --git a/src/free_claude_code/api/gateway_model_ids.py b/src/free_claude_code/core/gateway_model_ids.pysimilarity index 96%rename from src/free_claude_code/api/gateway_model_ids.pyrename to src/free_claude_code/core/gateway_model_ids.pyindex d02e7024..c7db23e9 100644--- a/src/free_claude_code/api/gateway_model_ids.py+++ b/src/free_claude_code/core/gateway_model_ids.py@@ -1,4 +1,4 @@-"""Gateway-safe model id encoding for Claude Code model discovery."""+"""Gateway-safe model ID encoding shared by API and CLI adapters."""from dataclasses import dataclassdiff --git a/src/free_claude_code/messaging/workflow.py b/src/free_claude_code/messaging/workflow.pyindex 076193ae..2b0eb583 100644--- a/src/free_claude_code/messaging/workflow.py+++ b/src/free_claude_code/messaging/workflow.py@@ -112,6 +112,20 @@ class MessagingWorkflow:self._tree_queue = tree_queueself._wire_tree_callbacks()+ def restore(self) -> None:+ """Restore persisted conversations into this workflow's owned queue."""+ snapshot = self.session_store.load_conversation_snapshot()+ if snapshot.is_empty:+ return+ logger.info("Restoring {} conversation trees...", len(snapshot.trees))+ self.replace_tree_queue(TreeQueueManager.from_snapshot(snapshot))+ if self.tree_queue.cleanup_stale_nodes() > 0:+ self.session_store.save_conversation_snapshot(self.tree_queue.snapshot())++ def close(self) -> None:+ """Flush pending session persistence before runtime shutdown."""+ self.session_store.flush_pending_save()+async def handle_message(self, incoming: IncomingMessage) -> None:"""Main entry point for handling an incoming platform message.diff --git a/src/free_claude_code/providers/runtime/discovery.py b/src/free_claude_code/providers/runtime/discovery.pyindex 8d4453ce..72938d7e 100644--- a/src/free_claude_code/providers/runtime/discovery.py+++ b/src/free_claude_code/providers/runtime/discovery.py@@ -2,7 +2,6 @@import asynciofrom collections.abc import Callable-from contextlib import suppressfrom loguru import logger@@ -53,7 +52,6 @@ class ProviderModelDiscovery:self._settings = settingsself._provider_resolver = provider_resolverself._model_cache = model_cache- self._refresh_task: asyncio.Task[None] | None = Noneasync def refresh_model_list_cache(self, *, only_missing: bool = False) -> None:"""Best-effort refresh of model lists for usable providers."""@@ -66,44 +64,6 @@ class ProviderModelDiscovery:)await self._refresh_model_infos(provider_ids)- def start_model_list_refresh(self) -> None:- """Start a non-blocking cache warmup for missing eligible provider lists."""- if self._refresh_task is not None and not self._refresh_task.done():- return-- provider_ids = tuple(- provider_id- for provider_id in model_list_provider_ids_for_settings(self._settings)- if not self._model_cache.has_provider(provider_id)- )- if not provider_ids:- logger.info(- "Provider model discovery cache already warm: providers={}",- len(self._model_cache.cached_model_ids()),- )- return-- self._refresh_task = asyncio.create_task(self._run_refresh(provider_ids))-- async def cleanup(self) -> None:- """Cancel any background model-list refresh."""- if self._refresh_task is None or self._refresh_task.done():- return- self._refresh_task.cancel()- with suppress(asyncio.CancelledError):- await self._refresh_task-- async def _run_refresh(self, provider_ids: tuple[str, ...]) -> None:- try:- await self._refresh_model_infos(provider_ids)- except asyncio.CancelledError:- raise- except Exception as exc:- logger.warning(- "Provider model discovery task failed: exc_type={}",- type(exc).__name__,- )-async def _refresh_model_infos(self, provider_ids: tuple[str, ...]) -> None:tasks: dict[str, asyncio.Task[frozenset[ProviderModelInfo]]] = {}for provider_id in provider_ids:diff --git a/src/free_claude_code/providers/runtime/runtime.py b/src/free_claude_code/providers/runtime/runtime.pyindex 94c1b375..28a9846e 100644--- a/src/free_claude_code/providers/runtime/runtime.py+++ b/src/free_claude_code/providers/runtime/runtime.py@@ -1,19 +1,15 @@-"""App-scoped provider runtime orchestration."""+"""One closable generation of lazily constructed provider clients."""-from collections.abc import Iterable, MutableMapping+from collections.abc import MutableMappingfrom free_claude_code.config.settings import Settingsfrom free_claude_code.providers.base import BaseProvider-from free_claude_code.providers.model_listing import ProviderModelInfofrom .cache import ProviderCache-from .discovery import ProviderModelDiscovery-from .model_cache import ProviderModelCache-from .validation import ConfiguredModelValidatorclass ProviderRuntime:- """Own provider instances, model discovery, validation, and cleanup."""+ """Own provider instances for one immutable settings snapshot."""def __init__(self,@@ -22,17 +18,6 @@ class ProviderRuntime:) -> None:self.settings = settingsself._provider_cache = ProviderCache(settings, providers)- self._model_cache = ProviderModelCache()- self._discovery = ProviderModelDiscovery(- settings,- self.resolve_provider,- self._model_cache,- )- self._validator = ConfiguredModelValidator(- settings,- self.resolve_provider,- self._model_cache,- )def is_cached(self, provider_id: str) -> bool:"""Return whether a provider for this id is already cached."""@@ -42,50 +27,6 @@ class ProviderRuntime:"""Return an existing provider or create it lazily."""return self._provider_cache.get(provider_id)- def cache_model_ids(self, provider_id: str, model_ids: Iterable[str]) -> None:- """Store raw provider model ids for later instant API responses."""- self._model_cache.cache_model_ids(provider_id, model_ids)-- def cache_model_infos(- self, provider_id: str, model_infos: Iterable[ProviderModelInfo]- ) -> None:- """Store provider model metadata for later instant API responses."""- self._model_cache.cache_model_infos(provider_id, model_infos)-- def cached_model_ids(self) -> dict[str, frozenset[str]]:- """Return cached raw provider model ids by provider."""- return self._model_cache.cached_model_ids()-- def cached_model_supports_thinking(- self, provider_id: str, model_id: str- ) -> bool | None:- """Return cached thinking support when a provider exposes it."""- return self._model_cache.cached_model_supports_thinking(provider_id, model_id)-- def cached_prefixed_model_refs(self) -> tuple[str, ...]:- """Return cached provider models in user-selectable ``provider/model`` form."""- return self._model_cache.cached_prefixed_model_refs()-- def cached_prefixed_model_infos(self) -> tuple[ProviderModelInfo, ...]:- """Return cached provider models with user-selectable prefixed ids."""- return self._model_cache.cached_prefixed_model_infos()-- async def refresh_model_list_cache(self, *, only_missing: bool = False) -> None:- """Best-effort refresh of model lists for usable providers."""- await self._discovery.refresh_model_list_cache(only_missing=only_missing)-- def start_model_list_refresh(self) -> None:- """Start a non-blocking cache warmup for missing eligible provider lists."""- self._discovery.start_model_list_refresh()-- async def validate_configured_models(self) -> None:- """Fail unless every configured chat model exists upstream."""- await self._validator.validate_configured_models()-async def cleanup(self) -> None:- """Cancel discovery, clean provider instances, and clear model metadata."""- try:- await self._discovery.cleanup()- await self._provider_cache.cleanup()- finally:- self._model_cache.clear()+ """Release every provider client constructed by this generation."""+ await self._provider_cache.cleanup()diff --git a/src/free_claude_code/runtime/__init__.py b/src/free_claude_code/runtime/__init__.pynew file mode 100644index 00000000..570f3235--- /dev/null+++ b/src/free_claude_code/runtime/__init__.py@@ -0,0 +1 @@+"""Application composition and process-lifetime resource ownership."""diff --git a/src/free_claude_code/runtime/application.py b/src/free_claude_code/runtime/application.pynew file mode 100644index 00000000..caf6428a--- /dev/null+++ b/src/free_claude_code/runtime/application.py@@ -0,0 +1,440 @@+"""Single owner for application startup, shutdown, and runtime operations."""++import asyncio+import inspect+import logging+import os+import traceback+from collections.abc import Awaitable, Callable, Mapping+from typing import Any++from loguru import logger++import free_claude_code.cli.managed as cli_managed+import free_claude_code.messaging.limiter as messaging_limiter+import free_claude_code.messaging.session as messaging_session+import free_claude_code.messaging.workflow as messaging_workflow_module+from free_claude_code.api.ports import StopResult+from free_claude_code.config.admin.persistence import (+ PreparedAdminUpdate,+ commit_prepared_admin_update,+ prepare_admin_update,+)+from free_claude_code.config.admin.status import provider_config_status+from free_claude_code.config.admin.values import load_value_state+from free_claude_code.config.env_files import (+ ANTHROPIC_AUTH_TOKEN_ENV,+ process_env_key_is_effective,+)+from free_claude_code.config.model_refs import parse_provider_type+from free_claude_code.config.paths import default_claude_workspace_path+from free_claude_code.config.server_urls import local_admin_url+from free_claude_code.config.settings import Settings, get_settings+from free_claude_code.messaging.platforms import factory as messaging_platform_factory+from free_claude_code.messaging.platforms.factory import MessagingPlatformOptions+from free_claude_code.messaging.platforms.ports import (+ MessagingPlatformComponents,+ MessagingRuntime,+)+from free_claude_code.providers.exceptions import ServiceUnavailableError++from .provider_manager import ProviderRuntimeManager++_SHUTDOWN_TIMEOUT_S = 5.0+RestartCallback = Callable[[], Awaitable[None] | None]+++async def best_effort(+ name: str,+ awaitable: Awaitable[Any],+ timeout_s: float = _SHUTDOWN_TIMEOUT_S,+ *,+ log_verbose_errors: bool = False,+) -> None:+ """Run one bounded cleanup step without masking later cleanup."""+ try:+ await asyncio.wait_for(awaitable, timeout=timeout_s)+ except TimeoutError:+ logger.warning("Shutdown step timed out: {} ({}s)", name, timeout_s)+ except Exception as exc:+ if log_verbose_errors:+ logger.warning(+ "Shutdown step failed: {}: {}: {}",+ name,+ type(exc).__name__,+ exc,+ )+ else:+ logger.warning(+ "Shutdown step failed: {}: exc_type={}",+ name,+ type(exc).__name__,+ )+++def warn_if_process_auth_token(settings: Settings) -> None:+ """Warn when server auth was implicitly inherited from the shell."""+ model_config = getattr(settings, "model_config", Settings.model_config)+ if process_env_key_is_effective(model_config, ANTHROPIC_AUTH_TOKEN_ENV):+ logger.warning(+ "ANTHROPIC_AUTH_TOKEN is set in the process environment but not in "+ "a configured .env file. The proxy will require that token. Add "+ "ANTHROPIC_AUTH_TOKEN= to .env to disable proxy auth, or set the "+ "same token in .env to make server auth explicit."+ )+++def startup_failure_message(settings: Settings, exc: Exception) -> str:+ """Return the existing concise ASGI startup failure message."""+ if isinstance(exc, ServiceUnavailableError):+ return exc.message.strip() or "Server startup failed."+ if settings.log_api_error_tracebacks:+ return f"{type(exc).__name__}: {exc}"+ return f"Server startup failed: exc_type={type(exc).__name__}"+++class ApplicationRuntime:+ """Own every process-lifetime resource used by one server instance."""++ def __init__(+ self,+ provider_manager: ProviderRuntimeManager,+ *,+ restart_callback: RestartCallback | None = None,+ ) -> None:+ self.provider_manager = provider_manager+ self._restart_callback = restart_callback+ self._config_lock = asyncio.Lock()+ self._pending_fields: list[str] = []+ self._messaging_runtime: MessagingRuntime | None = None+ self._messaging_workflow: messaging_workflow_module.MessagingWorkflow | None = (+ None+ )+ self._cli_manager: cli_managed.ManagedClaudeSessionManager | None = None+ self._started = False+ self._closed = False++ @property+ def settings(self) -> Settings:+ return self.provider_manager.current_settings()++ async def start(self) -> None:+ if self._started:+ return+ logger.info("Starting Claude Code Proxy...")+ try:+ warn_if_process_auth_token(self.settings)+ await self._validate_configured_models_best_effort()+ self.provider_manager.start_model_list_refresh()+ await self._start_messaging_if_configured()+ logging.getLogger("uvicorn.error").info(+ "Admin UI: %s (local-only)",+ local_admin_url(self.settings),+ )+ self._started = True+ except Exception as exc:+ logger.error(+ "Startup failed:\n{}",+ startup_failure_message(self.settings, exc),+ )+ await self._cleanup_messaging()+ await best_effort(+ "provider_manager.close",+ self.provider_manager.close(),+ log_verbose_errors=self.settings.log_api_error_tracebacks,+ )+ raise++ async def close(self) -> None:+ if self._closed:+ return+ self._closed = True+ logger.info("Shutdown requested, cleaning up...")+ await self._cleanup_messaging()+ await best_effort(+ "provider_manager.close",+ self.provider_manager.close(),+ log_verbose_errors=self.settings.log_api_error_tracebacks,+ )+ await self._shutdown_limiter()+ logger.info("Server shut down cleanly")++ async def apply_admin_config(+ self,+ updates: Mapping[str, Any],+ ) -> dict[str, Any]:+ """Apply one validated config update without splitting runtime ownership."""+ async with self._config_lock:+ prepared = prepare_admin_update(updates)+ if not prepared.valid:+ return prepared.applied_response()+ assert prepared.settings is not None++ if prepared.pending_fields:+ result = self._commit_admin_update(prepared)+ restart = self._restart_metadata(+ prepared.pending_fields,+ prepared.settings,+ )+ result["restart"] = restart+ self._pending_fields = (+ [] if restart["automatic"] else list(prepared.pending_fields)+ )+ return result++ result: dict[str, Any] = {}++ def commit() -> None:+ result.update(self._commit_admin_update(prepared))++ await self.provider_manager.replace(+ prepared.settings,+ commit=commit,+ reason="admin_apply",+ )+ self._pending_fields = []+ result["restart"] = self._restart_metadata((), prepared.settings)+ return result++ def admin_status(self) -> dict[str, Any]:+ settings = self.settings+ return {+ "status": "running",+ "host": settings.host,+ "port": settings.port,+ "model": settings.model,+ "provider": parse_provider_type(settings.model),+ "pending_fields": list(self._pending_fields),+ "provider_status": provider_config_status(load_value_state()),+ "cached_models": {+ provider_id: sorted(model_ids)+ for provider_id, model_ids in self.provider_manager.cached_model_ids().items()+ },+ }++ async def test_provider(self, provider_id: str) -> dict[str, Any]:+ lease = await self.provider_manager.acquire()+ try:+ provider = lease.resolve_provider(provider_id)+ infos = await provider.list_model_infos()+ except Exception as exc:+ return {+ "provider_id": provider_id,+ "ok": False,+ "error_type": type(exc).__name__,+ }+ finally:+ await lease.release()+ self.provider_manager.cache_model_infos(provider_id, infos)+ return {+ "provider_id": provider_id,+ "ok": True,+ "models": sorted(info.model_id for info in infos),+ }++ async def refresh_models(self) -> dict[str, Any]:+ await self.provider_manager.refresh_model_list_cache()+ return {+ "cached_models": {+ provider_id: sorted(model_ids)+ for provider_id, model_ids in self.provider_manager.cached_model_ids().items()+ }+ }++ async def request_restart(self) -> None:+ callback = self._restart_callback+ if callback is None:+ return+ result = callback()+ if inspect.isawaitable(result):+ await result++ async def stop_all(self) -> StopResult | None:+ if self._messaging_workflow is not None:+ count = await self._messaging_workflow.stop_all_tasks()+ return StopResult(cancelled_count=count)+ if self._cli_manager is not None:+ await self._cli_manager.stop_all()+ return StopResult(source="cli_manager")+ return None++ def _commit_admin_update(+ self,+ prepared: PreparedAdminUpdate,+ ) -> dict[str, Any]:+ result = commit_prepared_admin_update(prepared)+ get_settings.cache_clear()+ return result++ def _restart_metadata(+ self,+ fields: tuple[str, ...],+ settings: Settings,+ ) -> dict[str, Any]:+ automatic = bool(fields and self._restart_callback is not None)+ return {+ "required": bool(fields),+ "automatic": automatic,+ "admin_url": local_admin_url(settings) if automatic else None,+ "fields": list(fields),+ }++ async def _validate_configured_models_best_effort(self) -> None:+ try:+ await self.provider_manager.validate_configured_models()+ except ServiceUnavailableError as exc:+ logger.warning(+ "Configured provider model validation failed during startup; "+ "server will continue and requests will fail at provider resolution "+ "when config is incomplete. {}",+ exc.message,+ )++ async def _start_messaging_if_configured(self) -> None:+ try:+ components = messaging_platform_factory.create_messaging_components(+ self.settings.messaging_platform,+ self._messaging_options(),+ )+ if components is not None:+ await self._start_messaging_workflow(components)+ except ImportError as exc:+ await self._cleanup_messaging()+ if self.settings.log_api_error_tracebacks:+ logger.warning("Messaging module import error: {}", exc)+ else:+ logger.warning(+ "Messaging module import error: exc_type={}",+ type(exc).__name__,+ )+ except Exception as exc:+ await self._cleanup_messaging()+ if self.settings.log_api_error_tracebacks:+ logger.error("Failed to start messaging platform: {}", exc)+ logger.error(traceback.format_exc())+ else:+ logger.error(+ "Failed to start messaging platform: exc_type={}",+ type(exc).__name__,+ )++ def _messaging_options(self) -> MessagingPlatformOptions:+ settings = self.settings+ return MessagingPlatformOptions(+ telegram_bot_token=settings.telegram_bot_token,+ allowed_telegram_user_id=settings.allowed_telegram_user_id,+ telegram_proxy_url=settings.telegram_proxy_url,+ discord_bot_token=settings.discord_bot_token,+ allowed_discord_channels=settings.allowed_discord_channels,+ voice_note_enabled=settings.voice_note_enabled,+ whisper_model=settings.whisper_model,+ whisper_device=settings.whisper_device,+ huggingface_api_key=settings.huggingface_api_key,+ nvidia_nim_api_key=settings.nvidia_nim_api_key,+ messaging_rate_limit=settings.messaging_rate_limit,+ messaging_rate_window=settings.messaging_rate_window,+ log_raw_messaging_content=settings.log_raw_messaging_content,+ log_api_error_tracebacks=settings.log_api_error_tracebacks,+ )++ async def _start_messaging_workflow(+ self,+ components: MessagingPlatformComponents,+ ) -> None:+ settings = self.settings+ workspace = (+ os.path.abspath(settings.allowed_dir)+ if settings.allowed_dir+ else os.getcwd()+ )+ os.makedirs(workspace, exist_ok=True)+ data_path = os.path.abspath(default_claude_workspace_path())+ os.makedirs(data_path, exist_ok=True)+ allowed_dirs = [workspace] if settings.allowed_dir else []+ plans_dir_abs = os.path.abspath(os.path.join(data_path, "plans"))++ self._cli_manager = cli_managed.ManagedClaudeSessionManager(+ workspace_path=workspace,+ api_url=f"http://{settings.host}:{settings.port}/v1",+ allowed_dirs=allowed_dirs,+ plans_directory=os.path.relpath(plans_dir_abs, workspace),+ auth_token=settings.anthropic_auth_token,+ log_raw_cli_diagnostics=settings.log_raw_cli_diagnostics,+ log_messaging_error_details=settings.log_messaging_error_details,+ )+ session_store = messaging_session.SessionStore(+ storage_path=os.path.join(data_path, "sessions.json"),+ message_log_cap=settings.max_message_log_entries_per_chat,+ )+ self._messaging_runtime = components.runtime+ self._messaging_workflow = messaging_workflow_module.MessagingWorkflow(+ platform_name=components.name,+ outbound=components.outbound,+ voice_cancellation=components.voice_cancellation,+ cli_manager=self._cli_manager,+ session_store=session_store,+ debug_platform_edits=settings.debug_platform_edits,+ debug_subagent_stack=settings.debug_subagent_stack,+ log_raw_messaging_content=settings.log_raw_messaging_content,+ log_raw_cli_diagnostics=settings.log_raw_cli_diagnostics,+ log_messaging_error_details=settings.log_messaging_error_details,+ )+ self._messaging_workflow.restore()+ components.runtime.on_message(self._messaging_workflow.handle_message)+ await components.runtime.start()+ logger.info("{} platform started with messaging workflow", components.name)++ async def _cleanup_messaging(self) -> None:+ verbose = self.settings.log_api_error_tracebacks+ workflow = self._messaging_workflow+ runtime = self._messaging_runtime+ cli_manager = self._cli_manager+ self._messaging_workflow = None+ self._messaging_runtime = None+ self._cli_manager = None++ if workflow is not None:+ try:+ workflow.close()+ except Exception as exc:+ if verbose:+ logger.warning("Session store flush on shutdown: {}", exc)+ else:+ logger.warning(+ "Session store flush on shutdown: exc_type={}",+ type(exc).__name__,+ )+ if runtime is not None:+ await best_effort(+ "messaging_runtime.stop",+ runtime.stop(),+ log_verbose_errors=verbose,+ )+ if cli_manager is not None:+ await best_effort(+ "cli_manager.stop_all",+ cli_manager.stop_all(),+ log_verbose_errors=verbose,+ )++ async def _shutdown_limiter(self) -> None:+ verbose = self.settings.log_api_error_tracebacks+ try:+ await best_effort(+ "MessagingRateLimiter.shutdown_instance",+ messaging_limiter.MessagingRateLimiter.shutdown_instance(),+ timeout_s=2.0,+ log_verbose_errors=verbose,+ )+ except Exception as exc:+ if verbose:+ logger.debug(+ "Rate limiter shutdown skipped: {}: {}",+ type(exc).__name__,+ exc,+ )+ else:+ logger.debug(+ "Rate limiter shutdown skipped: exc_type={}",+ type(exc).__name__,+ )diff --git a/src/free_claude_code/runtime/asgi.py b/src/free_claude_code/runtime/asgi.pynew file mode 100644index 00000000..37a0ad47--- /dev/null+++ b/src/free_claude_code/runtime/asgi.py@@ -0,0 +1,61 @@+"""ASGI lifespan adapter for the application runtime owner."""++from typing import Any++from loguru import logger+from starlette.types import ASGIApp, Receive, Scope, Send++from .application import ApplicationRuntime, startup_failure_message+++class RuntimeASGIApp:+ """Delegate HTTP to FastAPI and lifespan to `ApplicationRuntime`."""++ def __init__(self, app: ASGIApp, runtime: ApplicationRuntime) -> None:+ self.app = app+ self.runtime = runtime++ def __getattr__(self, name: str) -> Any:+ return getattr(self.app, name)++ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:+ if scope["type"] != "lifespan":+ await self.app(scope, receive, send)+ return+ await self._lifespan(receive, send)++ async def _lifespan(self, receive: Receive, send: Send) -> None:+ started = False+ while True:+ message = await receive()+ if message["type"] == "lifespan.startup":+ try:+ await self.runtime.start()+ except Exception as exc:+ await send(+ {+ "type": "lifespan.startup.failed",+ "message": startup_failure_message(+ self.runtime.settings,+ exc,+ ),+ }+ )+ return+ started = True+ await send({"type": "lifespan.startup.complete"})+ continue++ if message["type"] == "lifespan.shutdown":+ if started:+ try:+ await self.runtime.close()+ except Exception as exc:+ logger.error(+ "Shutdown failed: exc_type={}",+ type(exc).__name__,+ )+ await send({"type": "lifespan.shutdown.failed", "message": ""})+ return+ await send({"type": "lifespan.shutdown.complete"})+ returndiff --git a/src/free_claude_code/runtime/bootstrap.py b/src/free_claude_code/runtime/bootstrap.pynew file mode 100644index 00000000..7206862d--- /dev/null+++ b/src/free_claude_code/runtime/bootstrap.py@@ -0,0 +1,34 @@+"""Single production composition root for the FCC server."""++import os+from pathlib import Path++from free_claude_code.api.app import create_app+from free_claude_code.api.ports import ApiServices+from free_claude_code.config.logging_config import configure_logging+from free_claude_code.config.paths import server_log_path+from free_claude_code.config.settings import Settings++from .application import ApplicationRuntime, RestartCallback+from .asgi import RuntimeASGIApp+from .provider_manager import ProviderRuntimeManager+++def build_asgi_app(+ settings: Settings,+ restart_callback: RestartCallback | None = None,+) -> RuntimeASGIApp:+ """Construct the complete server application and its resource owner."""+ log_path = Path(os.getenv("LOG_FILE", server_log_path()))+ configure_logging(log_path, verbose_third_party=settings.log_raw_api_payloads)+ provider_manager = ProviderRuntimeManager(settings)+ runtime = ApplicationRuntime(+ provider_manager,+ restart_callback=restart_callback,+ )+ services = ApiServices(+ requests=provider_manager,+ admin=runtime,+ sessions=runtime,+ )+ return RuntimeASGIApp(create_app(services), runtime)diff --git a/src/free_claude_code/runtime/provider_manager.py b/src/free_claude_code/runtime/provider_manager.pynew file mode 100644index 00000000..8f5ab014--- /dev/null+++ b/src/free_claude_code/runtime/provider_manager.py@@ -0,0 +1,342 @@+"""Single-owner provider generations and application model catalog."""++import asyncio+from collections.abc import Callable, Iterable+from contextlib import suppress+from dataclasses import dataclass, field++from loguru import logger++from free_claude_code.config.settings import Settings+from free_claude_code.core.trace import trace_event+from free_claude_code.providers.base import BaseProvider+from free_claude_code.providers.exceptions import ServiceUnavailableError+from free_claude_code.providers.model_listing import ProviderModelInfo+from free_claude_code.providers.runtime import ProviderRuntime+from free_claude_code.providers.runtime.discovery import ProviderModelDiscovery+from free_claude_code.providers.runtime.model_cache import ProviderModelCache+from free_claude_code.providers.runtime.validation import ConfiguredModelValidator++ProviderRuntimeFactory = Callable[[Settings], ProviderRuntime]+CommitConfig = Callable[[], None]+++@dataclass(slots=True, eq=False)+class _ProviderGeneration:+ generation_id: int+ settings: Settings+ runtime: ProviderRuntime+ active_leases: int = 0+ retired: bool = False+ closed: bool = False+ drained: asyncio.Event = field(default_factory=asyncio.Event)++ def __post_init__(self) -> None:+ self.drained.set()+++class ProviderGenerationLease:+ """Idempotent lease retaining one provider generation."""++ def __init__(+ self,+ manager: ProviderRuntimeManager,+ generation: _ProviderGeneration,+ ) -> None:+ self._manager = manager+ self._generation = generation+ self._released = False++ @property+ def generation_id(self) -> int:+ return self._generation.generation_id++ @property+ def settings(self) -> Settings:+ return self._generation.settings++ def is_provider_cached(self, provider_id: str) -> bool:+ return self._generation.runtime.is_cached(provider_id)++ def resolve_provider(self, provider_id: str) -> BaseProvider:+ return self._generation.runtime.resolve_provider(provider_id)++ async def release(self) -> None:+ if self._released:+ return+ self._released = True+ await self._manager._release(self._generation)++ async def __aenter__(self) -> ProviderGenerationLease:+ return self++ async def __aexit__(self, *_exc: object) -> None:+ await self.release()+++class ProviderRuntimeManager:+ """Own provider generations, leases, discovery, and model metadata."""++ def __init__(+ self,+ settings: Settings,+ *,+ runtime_factory: ProviderRuntimeFactory = ProviderRuntime,+ ) -> None:+ self._runtime_factory = runtime_factory+ self._replace_lock = asyncio.Lock()+ self._model_cache = ProviderModelCache()+ self._refresh_task: asyncio.Task[None] | None = None+ self._next_generation_id = 2+ self._retired: dict[int, _ProviderGeneration] = {}+ self._closed = False+ self._current = _ProviderGeneration(+ generation_id=1,+ settings=settings,+ runtime=runtime_factory(settings),+ )+ self._trace_published(self._current, previous=None, reason="startup")++ @property+ def current_generation_id(self) -> int:+ return self._current.generation_id++ async def acquire(self) -> ProviderGenerationLease:+ if self._closed:+ raise ServiceUnavailableError("Provider runtime is shutting down.")+ generation = self._current+ generation.active_leases += 1+ generation.drained.clear()+ return ProviderGenerationLease(self, generation)++ def current_settings(self) -> Settings:+ return self._current.settings++ def cached_model_ids(self) -> dict[str, frozenset[str]]:+ return self._model_cache.cached_model_ids()++ def cached_model_supports_thinking(+ self, provider_id: str, model_id: str+ ) -> bool | None:+ return self._model_cache.cached_model_supports_thinking(provider_id, model_id)++ def cached_prefixed_model_infos(self) -> tuple[ProviderModelInfo, ...]:+ return self._model_cache.cached_prefixed_model_infos()++ def cache_model_infos(+ self,+ provider_id: str,+ model_infos: Iterable[ProviderModelInfo],+ ) -> None:+ self._model_cache.cache_model_infos(provider_id, model_infos)++ async def validate_configured_models(self) -> None:+ lease = await self.acquire()+ try:+ validator = ConfiguredModelValidator(+ lease.settings,+ lease.resolve_provider,+ self._model_cache,+ )+ await validator.validate_configured_models()+ finally:+ await lease.release()++ def start_model_list_refresh(self) -> None:+ """Start one non-blocking refresh for the current generation."""+ if self._refresh_task is not None and not self._refresh_task.done():+ return+ generation = self._current+ self._refresh_task = asyncio.create_task(+ self._refresh_generation(generation, only_missing=True)+ )++ async def refresh_model_list_cache(self) -> None:+ """Run an explicit full refresh without racing replacement."""+ async with self._replace_lock:+ await self._cancel_refresh()+ await self._refresh_generation(self._current, only_missing=False)++ async def replace(+ self,+ settings: Settings,+ *,+ commit: CommitConfig,+ reason: str = "admin_apply",+ ) -> int:+ """Prepare, commit, and atomically publish one replacement generation."""+ async with self._replace_lock:+ await self._cancel_refresh()+ candidate_id = self._next_generation_id+ candidate_runtime: ProviderRuntime | None = None+ try:+ candidate_runtime = self._runtime_factory(settings)+ commit()+ except Exception as exc:+ trace_event(+ stage="runtime",+ event="provider_generation.replace_failed",+ source="runtime",+ current_generation_id=self._current.generation_id,+ candidate_generation_id=candidate_id,+ reason=reason,+ exc_type=type(exc).__name__,+ )+ if candidate_runtime is not None:+ await self._cleanup_unpublished(candidate_runtime)+ raise++ self._next_generation_id += 1+ assert candidate_runtime is not None+ previous = self._current+ candidate = _ProviderGeneration(+ generation_id=candidate_id,+ settings=settings,+ runtime=candidate_runtime,+ )+ self._current = candidate+ previous.retired = True+ self._retired[previous.generation_id] = previous+ self._trace_published(candidate, previous=previous, reason=reason)+ self._trace_retired(previous, reason=reason)++ if previous.active_leases == 0:+ await self._close_generation(previous, forced=False)+ self._refresh_task = asyncio.create_task(+ self._refresh_generation(candidate, only_missing=False)+ )+ return candidate.generation_id++ async def close(self) -> None:+ """Reject new leases, drain existing work, and close every generation."""+ async with self._replace_lock:+ if self._closed:+ return+ self._closed = True+ await self._cancel_refresh()+ current = self._current+ if not current.retired:+ current.retired = True+ self._retired[current.generation_id] = current+ self._trace_retired(current, reason="shutdown")+ generations = tuple(self._retired.values())++ await asyncio.gather(*(generation.drained.wait() for generation in generations))+ for generation in generations:+ await self._close_generation(generation, forced=False)+ self._model_cache.clear()++ async def _release(self, generation: _ProviderGeneration) -> None:+ if generation.active_leases <= 0:+ return+ generation.active_leases -= 1+ if generation.active_leases != 0:+ return+ generation.drained.set()+ if generation.retired:+ await self._close_generation(generation, forced=False)++ async def _refresh_generation(+ self,+ generation: _ProviderGeneration,+ *,+ only_missing: bool,+ ) -> None:+ if generation.closed:+ return+ generation.active_leases += 1+ generation.drained.clear()+ try:+ discovery = ProviderModelDiscovery(+ generation.settings,+ generation.runtime.resolve_provider,+ self._model_cache,+ )+ await discovery.refresh_model_list_cache(only_missing=only_missing)+ except asyncio.CancelledError:+ raise+ except Exception as exc:+ logger.warning(+ "Provider model discovery task failed: exc_type={}",+ type(exc).__name__,+ )+ finally:+ await self._release(generation)++ async def _cancel_refresh(self) -> None:+ task = self._refresh_task+ self._refresh_task = None+ if task is None or task.done():+ return+ task.cancel()+ with suppress(asyncio.CancelledError):+ await task++ async def _cleanup_unpublished(self, runtime: ProviderRuntime) -> None:+ try:+ await runtime.cleanup()+ except Exception as exc:+ logger.warning(+ "Unpublished provider generation cleanup failed: exc_type={}",+ type(exc).__name__,+ )++ async def _close_generation(+ self,+ generation: _ProviderGeneration,+ *,+ forced: bool,+ ) -> None:+ if generation.closed or generation.active_leases != 0:+ return+ generation.closed = True+ outcome = "ok"+ try:+ await generation.runtime.cleanup()+ except Exception as exc:+ outcome = "error"+ logger.warning(+ "Provider generation cleanup failed: generation_id={} exc_type={}",+ generation.generation_id,+ type(exc).__name__,+ )+ finally:+ self._retired.pop(generation.generation_id, None)+ trace_event(+ stage="runtime",+ event="provider_generation.closed",+ source="runtime",+ generation_id=generation.generation_id,+ active_leases=generation.active_leases,+ forced=forced,+ outcome=outcome,+ )++ @staticmethod+ def _trace_published(+ generation: _ProviderGeneration,+ *,+ previous: _ProviderGeneration | None,+ reason: str,+ ) -> None:+ trace_event(+ stage="runtime",+ event="provider_generation.published",+ source="runtime",+ generation_id=generation.generation_id,+ previous_generation_id=(+ previous.generation_id if previous is not None else None+ ),+ reason=reason,+ )++ @staticmethod+ def _trace_retired(generation: _ProviderGeneration, *, reason: str) -> None:+ trace_event(+ stage="runtime",+ event="provider_generation.retired",+ source="runtime",+ generation_id=generation.generation_id,+ active_leases=generation.active_leases,+ reason=reason,+ )diff --git a/tests/api/support.py b/tests/api/support.pynew file mode 100644index 00000000..4f21eb20--- /dev/null+++ b/tests/api/support.py@@ -0,0 +1,57 @@+"""Explicit test composition for the API adapter."""++from collections.abc import MutableMapping++from fastapi import FastAPI++from free_claude_code.api.app import create_app+from free_claude_code.api.ports import ApiServices+from free_claude_code.config.settings import Settings+from free_claude_code.providers.base import BaseProvider+from free_claude_code.providers.runtime import ProviderRuntime+from free_claude_code.runtime.application import ApplicationRuntime, RestartCallback+from free_claude_code.runtime.provider_manager import ProviderRuntimeManager+++def create_test_app(+ settings: Settings | None = None,+ *,+ providers: MutableMapping[str, BaseProvider] | None = None,+ restart_callback: RestartCallback | None = None,+) -> FastAPI:+ """Build an API app with explicit in-memory runtime services."""+ settings = settings or Settings()+ if providers is None:+ manager = ProviderRuntimeManager(settings)+ else:+ manager = ProviderRuntimeManager(+ settings,+ runtime_factory=lambda snapshot: ProviderRuntime(+ snapshot,+ dict(providers),+ ),+ )+ runtime = ApplicationRuntime(manager, restart_callback=restart_callback)+ return create_app(+ ApiServices(+ requests=manager,+ admin=runtime,+ sessions=runtime,+ )+ )+++def runtime_for_app(app: FastAPI) -> ApplicationRuntime:+ """Return the runtime supplied by :func:`create_test_app`."""+ runtime = app.state.services.admin+ if not isinstance(runtime, ApplicationRuntime):+ raise TypeError("Test app does not use ApplicationRuntime")+ return runtime+++def provider_manager_for_app(app: FastAPI) -> ProviderRuntimeManager:+ """Return the provider manager supplied by :func:`create_test_app`."""+ manager = app.state.services.requests+ if not isinstance(manager, ProviderRuntimeManager):+ raise TypeError("Test app does not use ProviderRuntimeManager")+ return managerdiff --git a/tests/api/test_admin.py b/tests/api/test_admin.pyindex 5f65930c..fb7a465d 100644--- a/tests/api/test_admin.py+++ b/tests/api/test_admin.py@@ -4,10 +4,10 @@ from unittest.mock import patchimport httpxfrom fastapi.testclient import TestClient-from free_claude_code.api.admin_config.values import MASKED_SECRET-from free_claude_code.api.admin_urls import local_admin_url-from free_claude_code.api.app import create_app+from free_claude_code.config.admin.values import MASKED_SECRET+from free_claude_code.config.server_urls import local_admin_urlfrom free_claude_code.config.settings import Settings+from tests.api.support import create_test_appdef _local_client(app):@@ -44,7 +44,7 @@ def _clear_process_config(monkeypatch) -> None:def test_admin_page_is_loopback_only(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)- app = create_app(lifespan_enabled=False)+ app = create_test_app()assert _local_client(app).get("/admin").status_code == 200remote_client = TestClient(app, client=("203.0.113.10", 50000))@@ -53,7 +53,7 @@ def test_admin_page_is_loopback_only(monkeypatch, tmp_path):def test_admin_page_no_longer_renders_generated_env_panel(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).get("/admin")@@ -64,7 +64,7 @@ def test_admin_page_no_longer_renders_generated_env_panel(monkeypatch, tmp_path)def test_admin_page_no_longer_renders_global_status_header(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).get("/admin")@@ -100,7 +100,7 @@ def test_admin_static_hides_managed_source_label():def test_admin_config_masks_secrets_and_exposes_manifest(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).get("/admin/api/config")@@ -140,7 +140,7 @@ def test_admin_config_preserves_managed_env_source_contract(monkeypatch, tmp_patenv_file = tmp_path / ".fcc" / ".env"env_file.parent.mkdir(parents=True)env_file.write_text("MODEL=open_router/managed-model\n", encoding="utf-8")- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).get("/admin/api/config")@@ -154,7 +154,7 @@ def test_admin_config_preserves_managed_env_source_contract(monkeypatch, tmp_patdef test_admin_apply_masks_telegram_proxy_credentials(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)- app = create_app(lifespan_enabled=False)+ app = create_test_app()proxy_url = "https://user:[email protected]:8443"response = _local_client(app).post(@@ -175,7 +175,7 @@ def test_admin_apply_masks_telegram_proxy_credentials(monkeypatch, tmp_path):def test_admin_validate_rejects_bad_model_shape(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).post("/admin/api/config/validate",@@ -193,7 +193,7 @@ def test_admin_apply_writes_complete_managed_env_and_masks_preview():_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).post("/admin/api/config/apply",@@ -225,7 +225,7 @@ def test_admin_apply_writes_complete_managed_env_and_masks_preview(def test_admin_apply_writes_fireworks_key_and_masks_preview(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).post("/admin/api/config/apply",@@ -250,7 +250,7 @@ def test_admin_apply_writes_fireworks_key_and_masks_preview(monkeypatch, tmp_patdef test_admin_apply_writes_gemini_key_and_masks_preview(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).post("/admin/api/config/apply",@@ -275,7 +275,7 @@ def test_admin_apply_writes_gemini_key_and_masks_preview(monkeypatch, tmp_path):def test_admin_apply_writes_groq_key_and_masks_preview(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).post("/admin/api/config/apply",@@ -300,7 +300,7 @@ def test_admin_apply_writes_groq_key_and_masks_preview(monkeypatch, tmp_path):def test_admin_apply_writes_sambanova_key_and_masks_preview(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).post("/admin/api/config/apply",@@ -325,7 +325,7 @@ def test_admin_apply_writes_sambanova_key_and_masks_preview(monkeypatch, tmp_patdef test_admin_apply_writes_cerebras_key_and_masks_preview(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).post("/admin/api/config/apply",@@ -350,7 +350,7 @@ def test_admin_apply_writes_cerebras_key_and_masks_preview(monkeypatch, tmp_pathdef test_admin_apply_writes_cloudflare_fields_and_masks_preview(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).post("/admin/api/config/apply",@@ -378,7 +378,7 @@ def test_admin_apply_writes_cloudflare_fields_and_masks_preview(monkeypatch, tmpdef test_admin_apply_writes_huggingface_key_and_masks_preview(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).post("/admin/api/config/apply",@@ -403,7 +403,7 @@ def test_admin_apply_writes_huggingface_key_and_masks_preview(monkeypatch, tmp_pdef test_admin_apply_writes_cohere_key_and_masks_preview(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).post("/admin/api/config/apply",@@ -430,7 +430,7 @@ def test_admin_apply_writes_github_models_token_and_masks_preview():_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).post("/admin/api/config/apply",@@ -470,7 +470,7 @@ def test_admin_apply_preserves_hidden_diagnostics_and_smoke_values(),encoding="utf-8",)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).post("/admin/api/config/apply",@@ -502,7 +502,7 @@ def test_admin_apply_omits_stale_zai_base_url(monkeypatch, tmp_path):),encoding="utf-8",)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).post("/admin/api/config/apply",@@ -533,7 +533,7 @@ def test_admin_apply_omits_stale_fixed_claude_runtime_settings(monkeypatch, tmp_),encoding="utf-8",)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).post("/admin/api/config/apply",@@ -552,13 +552,12 @@ def test_admin_apply_omits_stale_fixed_claude_runtime_settings(monkeypatch, tmp_def test_admin_apply_restart_required_reports_automatic_restart(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)- app = create_app(lifespan_enabled=False)callbacks: list[str] = []async def restart_callback() -> None:callbacks.append("restart")- app.state.admin_restart_callback = restart_callback+ app = create_test_app(restart_callback=restart_callback)response = _local_client(app).post("/admin/api/config/apply",@@ -581,7 +580,7 @@ def test_admin_apply_restart_required_reports_automatic_restart(monkeypatch, tmpdef test_admin_apply_restart_required_reports_manual_fallback(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)- app = create_app(lifespan_enabled=False)+ app = create_test_app()response = _local_client(app).post("/admin/api/config/apply",@@ -604,7 +603,7 @@ def test_admin_process_env_values_are_locked_and_not_written(monkeypatch, tmp_pa_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)monkeypatch.setenv("MODEL", "open_router/process-model")- app = create_app(lifespan_enabled=False)+ app = create_test_app()config = _local_client(app).get("/admin/api/config").json()model_field = next(field for field in config["fields"] if field["key"] == "MODEL")@@ -629,7 +628,7 @@ def test_admin_first_apply_migrates_repo_env(monkeypatch, tmp_path):"MODEL=deepseek/deepseek-chat\nDEEPSEEK_API_KEY=deepseek-secret\n",encoding="utf-8",)- app = create_app(lifespan_enabled=False)+ app = create_test_app()config = _local_client(app).get("/admin/api/config").json()model_field = next(field for field in config["fields"] if field["key"] == "MODEL")@@ -650,7 +649,7 @@ def test_admin_first_apply_migrates_repo_env(monkeypatch, tmp_path):def test_admin_local_provider_status_reports_reachable(monkeypatch, tmp_path):_set_home(monkeypatch, tmp_path)_clear_process_config(monkeypatch)- app = create_app(lifespan_enabled=False)+ app = create_test_app()class FakeAsyncClient:def __init__(self, *args, **kwargs):diff --git a/tests/api/test_api.py b/tests/api/test_api.pyindex e9fb41e8..0d9c7522 100644--- a/tests/api/test_api.py+++ b/tests/api/test_api.py@@ -1,9 +1,8 @@-from unittest.mock import AsyncMock, MagicMock, patch+from unittest.mock import MagicMock, patchimport pytestfrom fastapi.testclient import TestClient-from free_claude_code.api.app import create_appfrom free_claude_code.providers.exceptions import (APIError,AuthenticationError,@@ -13,8 +12,9 @@ from free_claude_code.providers.exceptions import (RateLimitError,)from free_claude_code.providers.nvidia_nim import NvidiaNimProvider+from tests.api.support import create_test_app-app = create_app()+app = create_test_app()# Mock providermock_provider = MagicMock(spec=NvidiaNimProvider)@@ -62,16 +62,9 @@ def client():"""HTTP client with provider resolution stubbed; patch only for this file."""with (patch(- "free_claude_code.api.dependencies.resolve_provider",+ "free_claude_code.api.routes.resolve_provider",return_value=mock_provider,),- patch(- "free_claude_code.providers.runtime.ProviderRuntime.validate_configured_models",- new_callable=AsyncMock,- ),- patch(- "free_claude_code.providers.runtime.ProviderRuntime.start_model_list_refresh"- ),TestClient(app) as test_client,):yield test_clientdiff --git a/tests/api/test_app_lifespan_and_errors.py b/tests/api/test_app_lifespan_and_errors.pyindex 1c755509..97999806 100644--- a/tests/api/test_app_lifespan_and_errors.py+++ b/tests/api/test_app_lifespan_and_errors.py@@ -1,7 +1,6 @@-import importlib-from collections.abc import MutableMapping-from types import SimpleNamespace-from typing import Any, cast+import logging+from pathlib import Path+from typing import castfrom unittest.mock import AsyncMock, MagicMock, patchimport pytest@@ -9,56 +8,23 @@ from fastapi import FastAPIfrom fastapi.testclient import TestClientfrom free_claude_code.config.settings import Settings-from free_claude_code.messaging.trees import ConversationSnapshot, TreeSnapshot-from free_claude_code.providers.exceptions import ServiceUnavailableError-from free_claude_code.providers.runtime import ProviderRuntime--_RUNTIME_EXTRAS = {- "model": "nvidia_nim/test-model",- "model_opus": None,- "model_sonnet": None,- "model_haiku": None,- "telegram_proxy_url": "",- "voice_note_enabled": True,- "whisper_model": "base",- "whisper_device": "cpu",- "huggingface_api_key": "",- "nvidia_nim_api_key": "",- "messaging_rate_limit": 1,- "messaging_rate_window": 1.0,- "max_message_log_entries_per_chat": None,- "debug_platform_edits": False,- "debug_subagent_stack": False,- "log_api_error_tracebacks": False,- "log_raw_messaging_content": False,- "log_raw_cli_diagnostics": False,- "log_messaging_error_details": False,-}---def _app_settings(**kwargs):- """Minimal settings namespace for AppRuntime (matches typed :class:`Settings` fields used)."""- data = {**_RUNTIME_EXTRAS, **kwargs}- return SimpleNamespace(**data)---def _fake_messaging_components(runtime: MagicMock | None = None) -> SimpleNamespace:- runtime = runtime or MagicMock()- runtime.name = getattr(runtime, "name", "fake")- runtime.on_message = getattr(runtime, "on_message", MagicMock())- runtime.start = getattr(runtime, "start", AsyncMock())- runtime.stop = getattr(runtime, "stop", AsyncMock())- outbound = MagicMock()- outbound.queue_send_message = AsyncMock(return_value="msg")- outbound.queue_edit_message = AsyncMock()- outbound.queue_delete_messages = AsyncMock()- outbound.fire_and_forget = MagicMock()- return SimpleNamespace(- name=runtime.name,- runtime=runtime,- outbound=outbound,- voice_cancellation=None,- )+from free_claude_code.providers.exceptions import (+ AuthenticationError,+ ServiceUnavailableError,+)+from free_claude_code.runtime.application import (+ ApplicationRuntime,+ startup_failure_message,+ warn_if_process_auth_token,+)+from free_claude_code.runtime.asgi import RuntimeASGIApp+from free_claude_code.runtime.bootstrap import build_asgi_app+from free_claude_code.runtime.provider_manager import ProviderRuntimeManager+from tests.api.support import create_test_app+++def _settings(**updates: object) -> Settings:+ return Settings().model_copy(update=updates)@pytest.fixture(autouse=True)@@ -69,655 +35,258 @@ def _redirect_fcc_home(monkeypatch, tmp_path):def test_warn_if_process_auth_token_logs_warning(monkeypatch):- api_runtime_mod = importlib.import_module("free_claude_code.api.runtime")monkeypatch.setenv("ANTHROPIC_AUTH_TOKEN", "process-token")monkeypatch.setitem(Settings.model_config, "env_file", ())- settings = Settings.model_construct()- with patch.object(api_runtime_mod.logger, "warning") as warning:- api_runtime_mod.warn_if_process_auth_token(settings)+ with patch("free_claude_code.runtime.application.logger.warning") as warning:+ warn_if_process_auth_token(Settings.model_construct())warning.assert_called_once()assert "ANTHROPIC_AUTH_TOKEN" in warning.call_args.args[0]def test_warn_if_process_auth_token_skips_explicit_dotenv_config(monkeypatch, tmp_path):- api_runtime_mod = importlib.import_module("free_claude_code.api.runtime")env_file = tmp_path / ".env"env_file.write_text("ANTHROPIC_AUTH_TOKEN=\n", encoding="utf-8")monkeypatch.setenv("ANTHROPIC_AUTH_TOKEN", "process-token")monkeypatch.setitem(Settings.model_config, "env_file", (env_file,))- settings = Settings.model_construct()- with patch.object(api_runtime_mod.logger, "warning") as warning:- api_runtime_mod.warn_if_process_auth_token(settings)+ with patch("free_claude_code.runtime.application.logger.warning") as warning:+ warn_if_process_auth_token(Settings.model_construct())warning.assert_not_called()@pytest.mark.asyncio-async def test_runtime_startup_logs_admin_url_without_printed_server_banner(tmp_path):- import free_claude_code.api.runtime as api_runtime_mod-- settings = _app_settings(+async def test_runtime_startup_logs_admin_url_without_printed_server_banner():+ settings = _settings(messaging_platform="none",- telegram_bot_token=None,- allowed_telegram_user_id=None,- discord_bot_token=None,- allowed_discord_channels=None,- allowed_dir=str(tmp_path / "workspace"),- claude_workspace=str(tmp_path / "data"),host="127.0.0.1",port=9099,)- runtime = api_runtime_mod.AppRuntime(- app=FastAPI(), settings=cast(Settings, settings)- )+ manager = ProviderRuntimeManager(settings)+ runtime = ApplicationRuntime(manager)uvicorn_logger = MagicMock()with (patch("builtins.print") as printed,- patch.object(- api_runtime_mod.logging, "getLogger", return_value=uvicorn_logger- ) as get_logger,- patch.object(api_runtime_mod.logger, "info") as app_info,- patch.object(ProviderRuntime, "validate_configured_models", new=AsyncMock()),- patch.object(ProviderRuntime, "start_model_list_refresh"),- patch.object(ProviderRuntime, "cleanup", new=AsyncMock()),+ patch.object(manager, "validate_configured_models", new=AsyncMock()),+ patch.object(manager, "start_model_list_refresh") as start_refresh,+ patch.object(manager, "close", new=AsyncMock()),patch(- "free_claude_code.messaging.platforms.factory.create_messaging_components",+ "free_claude_code.runtime.application.messaging_platform_factory.create_messaging_components",return_value=None,),+ patch.object(logging, "getLogger", return_value=uvicorn_logger) as get_logger,):- await runtime.startup()- await runtime.shutdown()+ await runtime.start()+ await runtime.close()printed.assert_not_called()- get_logger.assert_called_with("uvicorn.error")+ start_refresh.assert_called_once()+ get_logger.assert_any_call("uvicorn.error")uvicorn_logger.info.assert_called_once_with("Admin UI: %s (local-only)","http://127.0.0.1:9099/admin",)- logged = " ".join(str(arg) for call in app_info.call_args_list for arg in call.args)- assert "Server URL:" not in loggeddef test_create_app_provider_error_handler_returns_anthropic_format():- from free_claude_code.api.app import create_app- from free_claude_code.providers.exceptions import AuthenticationError-- app = create_app()+ app = create_test_app(_settings(log_api_error_tracebacks=False))@app.get("/raise_provider")async def _raise_provider():raise AuthenticationError("bad key")- api_app_mod = importlib.import_module("free_claude_code.api.app")- settings = _app_settings(- messaging_platform="telegram",- telegram_bot_token=None,- allowed_telegram_user_id=None,- discord_bot_token=None,- allowed_discord_channels=None,- allowed_dir="",- claude_workspace="./agent_workspace",- host="127.0.0.1",- port=8082,- )- with (- patch.object(api_app_mod, "get_settings", return_value=settings),- patch.object(ProviderRuntime, "cleanup", new=AsyncMock()),- ):- with TestClient(app) as client:- resp = client.get("/raise_provider")- assert resp.status_code == 401- body = resp.json()+ response = TestClient(app).get("/raise_provider")++ assert response.status_code == 401+ body = response.json()assert body["type"] == "error"assert body["error"]["type"] == "authentication_error"- assert body["request_id"] == resp.headers["request-id"]- assert "x-should-retry" not in resp.headers-+ assert body["request_id"] == response.headers["request-id"]+ assert "x-should-retry" not in response.headers-def test_create_app_provider_error_default_logs_exclude_provider_message():- """Provider errors must not log exc.message by default."""- from free_claude_code.api.app import create_app- from free_claude_code.providers.exceptions import AuthenticationError- app = create_app()+def test_provider_error_default_log_excludes_provider_message():+ app = create_test_app(_settings(log_api_error_tracebacks=False))secret = "provider-upstream-secret-detail"@app.get("/raise_provider_secret")- async def _raise():+ async def _raise_provider_secret():raise AuthenticationError(secret)- api_app_mod = importlib.import_module("free_claude_code.api.app")- settings = _app_settings(- messaging_platform="telegram",- telegram_bot_token=None,- allowed_telegram_user_id=None,- discord_bot_token=None,- allowed_discord_channels=None,- allowed_dir="",- claude_workspace="./agent_workspace",- host="127.0.0.1",- port=8082,- log_api_error_tracebacks=False,- )- with (- patch.object(api_app_mod, "get_settings", return_value=settings),- patch.object(ProviderRuntime, "cleanup", new=AsyncMock()),- patch.object(api_app_mod.logger, "error") as log_err,- ):- with TestClient(app) as client:- resp = client.get("/raise_provider_secret")- assert resp.status_code == 401+ with patch("free_claude_code.api.app.logger.error") as log_error:+ response = TestClient(app).get("/raise_provider_secret")- blob = " ".join(str(a) for c in log_err.call_args_list for a in c.args)- blob += repr([c.kwargs for c in log_err.call_args_list])+ assert response.status_code == 401+ blob = " ".join(+ str(value) for call in log_error.call_args_list for value in call.args+ )assert secret not in blobassert "authentication_error" in blob-def test_create_app_general_exception_handler_returns_500():- from free_claude_code.api.app import create_app-- app = create_app()+def test_create_app_general_exception_handler_returns_correlated_500():+ app = create_test_app(_settings(log_api_error_tracebacks=False))@app.get("/raise_general")async def _raise_general():raise RuntimeError("boom")- api_app_mod = importlib.import_module("free_claude_code.api.app")- settings = _app_settings(- messaging_platform="telegram",- telegram_bot_token=None,- allowed_telegram_user_id=None,- discord_bot_token=None,- allowed_discord_channels=None,- allowed_dir="",- claude_workspace="./agent_workspace",- host="127.0.0.1",- port=8082,- )- with (- patch.object(api_app_mod, "get_settings", return_value=settings),- patch.object(ProviderRuntime, "cleanup", new=AsyncMock()),- ):- with TestClient(app, raise_server_exceptions=False) as client:- resp = client.get("/raise_general")- assert resp.status_code == 500- body = resp.json()- assert body["type"] == "error"- assert body["error"]["type"] == "api_error"- assert body["request_id"] == resp.headers["request-id"]-+ response = TestClient(app, raise_server_exceptions=False).get("/raise_general")-def test_create_app_general_exception_default_logs_exclude_exception_message():- """Unhandled errors must not log exception text by default (may echo user content)."""- from free_claude_code.api.app import create_app+ assert response.status_code == 500+ body = response.json()+ assert body["type"] == "error"+ assert body["error"]["type"] == "api_error"+ assert body["request_id"] == response.headers["request-id"]- app = create_app()+def test_general_exception_default_log_excludes_exception_message():+ app = create_test_app(_settings(log_api_error_tracebacks=False))secret = "user-provided-secret-token-xyzzy"@app.get("/raise_secret")async def _raise_secret():raise ValueError(secret)- api_app_mod = importlib.import_module("free_claude_code.api.app")- settings = _app_settings(- messaging_platform="telegram",- telegram_bot_token=None,- allowed_telegram_user_id=None,- discord_bot_token=None,- allowed_discord_channels=None,- allowed_dir="",- claude_workspace="./agent_workspace",- host="127.0.0.1",- port=8082,- log_api_error_tracebacks=False,+ with patch("free_claude_code.api.app.logger.error") as log_error:+ response = TestClient(app, raise_server_exceptions=False).get("/raise_secret")++ assert response.status_code == 500+ blob = " ".join(+ str(value) for call in log_error.call_args_list for value in call.args)- with (- patch.object(api_app_mod, "get_settings", return_value=settings),- patch.object(ProviderRuntime, "cleanup", new=AsyncMock()),- patch.object(api_app_mod.logger, "error") as log_err,- ):- with TestClient(app, raise_server_exceptions=False) as client:- resp = client.get("/raise_secret")- assert resp.status_code == 500-- flattened: list[str] = []- for call in log_err.call_args_list:- flattened.extend(str(arg) for arg in call.args)- flattened.append(repr(call.kwargs))- blob = " ".join(flattened)assert secret not in blobassert "ValueError" in blob- "messaging_enabled", [True, False], ids=["with_platform", "no_platform"]-)-def test_app_lifespan_sets_state_and_cleans_up(tmp_path, messaging_enabled):- from free_claude_code.api.app import create_app-- app = create_app()-- settings = _app_settings(- messaging_platform="telegram",- telegram_bot_token="token" if messaging_enabled else None,- allowed_telegram_user_id="123",- discord_bot_token=None,- allowed_discord_channels=None,- allowed_dir=str(tmp_path / "workspace"),- claude_workspace=str(tmp_path / "data"),- host="127.0.0.1",- port=8082,- )-- fake_platform = MagicMock()- fake_platform.name = "fake"- fake_platform.on_message = MagicMock()- fake_platform.start = AsyncMock()- fake_platform.stop = AsyncMock()- fake_components = _fake_messaging_components(fake_platform)-- snapshot = (- ConversationSnapshot(trees={"t": TreeSnapshot(root_id="t", nodes={})})- if messaging_enabled- else ConversationSnapshot()- )- session_store = MagicMock()- session_store.load_conversation_snapshot.return_value = snapshot- session_store.save_conversation_snapshot = MagicMock()-- fake_queue = MagicMock()- fake_queue.cleanup_stale_nodes.return_value = 1- fake_queue.snapshot.return_value = snapshot-- cli_manager = MagicMock()- cli_manager.stop_all = AsyncMock()-- api_app_mod = importlib.import_module("free_claude_code.api.app")-- runtime_cleanup = AsyncMock()- with (- patch.object(api_app_mod, "get_settings", return_value=settings),- patch.object(ProviderRuntime, "cleanup", new=runtime_cleanup),- patch(- "free_claude_code.messaging.platforms.factory.create_messaging_components",- return_value=fake_components if messaging_enabled else None,- ) as create_components,- patch(- "free_claude_code.messaging.session.SessionStore",- return_value=session_store,- ),- patch(- "free_claude_code.cli.managed.ManagedClaudeSessionManager",- return_value=cli_manager,- ),- patch(- "free_claude_code.messaging.trees.TreeQueueManager.from_snapshot",- return_value=fake_queue,- ),- TestClient(app),- ):- pass-- if messaging_enabled:- create_components.assert_called_once()- fake_platform.on_message.assert_called_once()- fake_platform.start.assert_awaited_once()- fake_platform.stop.assert_awaited_once()- cli_manager.stop_all.assert_awaited_once()- assert getattr(app.state, "messaging_workflow", None) is not None- session_store.save_conversation_snapshot.assert_called_once_with(snapshot)- else:- fake_platform.start.assert_not_awaited()- fake_platform.stop.assert_not_awaited()- cli_manager.stop_all.assert_not_awaited()- assert getattr(app.state, "messaging_runtime", "missing") is None-- runtime_cleanup.assert_awaited_once()---def test_app_lifespan_cleanup_continues_if_platform_stop_raises(tmp_path):- from free_claude_code.api.app import create_app-- app = create_app()-- settings = _app_settings(- messaging_platform="telegram",- telegram_bot_token="token",- allowed_telegram_user_id="123",- discord_bot_token=None,- allowed_discord_channels=None,- allowed_dir=str(tmp_path / "workspace"),- claude_workspace=str(tmp_path / "data"),- host="127.0.0.1",- port=8082,- )-- fake_platform = MagicMock()- fake_platform.name = "fake"- fake_platform.on_message = MagicMock()- fake_platform.start = AsyncMock()- fake_platform.stop = AsyncMock(side_effect=RuntimeError("stop failed"))- fake_components = _fake_messaging_components(fake_platform)-- session_store = MagicMock()- session_store.load_conversation_snapshot.return_value = ConversationSnapshot()-- cli_manager = MagicMock()- cli_manager.stop_all = AsyncMock()+async def test_model_validation_failure_does_not_block_runtime_startup():+ settings = _settings(messaging_platform="none")+ manager = ProviderRuntimeManager(settings)+ runtime = ApplicationRuntime(manager)+ validation = AsyncMock(side_effect=ServiceUnavailableError("bad model"))- api_app_mod = importlib.import_module("free_claude_code.api.app")- runtime_cleanup = AsyncMock()with (- patch.object(api_app_mod, "get_settings", return_value=settings),- patch.object(ProviderRuntime, "cleanup", new=runtime_cleanup),+ patch.object(manager, "validate_configured_models", new=validation),+ patch.object(manager, "start_model_list_refresh") as start_refresh,+ patch.object(manager, "close", new=AsyncMock()),patch(- "free_claude_code.messaging.platforms.factory.create_messaging_components",- return_value=fake_components,- ),- patch(- "free_claude_code.messaging.session.SessionStore",- return_value=session_store,- ),- patch(- "free_claude_code.cli.managed.ManagedClaudeSessionManager",- return_value=cli_manager,+ "free_claude_code.runtime.application.messaging_platform_factory.create_messaging_components",+ return_value=None,),- TestClient(app),):- pass+ await runtime.start()+ await runtime.close()- fake_platform.stop.assert_awaited_once()- cli_manager.stop_all.assert_awaited_once()- runtime_cleanup.assert_awaited_once()+ validation.assert_awaited_once()+ start_refresh.assert_called_once()-async def test_runtime_startup_validation_failure_does_not_block_server(tmp_path):- import free_claude_code.api.runtime as api_runtime_mod+def test_startup_failure_message_preserves_existing_concise_contract():+ quiet = _settings(log_api_error_tracebacks=False)+ verbose = _settings(log_api_error_tracebacks=True)- settings = _app_settings(- messaging_platform="none",- telegram_bot_token=None,- allowed_telegram_user_id=None,- discord_bot_token=None,- allowed_discord_channels=None,- allowed_dir=str(tmp_path / "workspace"),- claude_workspace=str(tmp_path / "data"),- host="127.0.0.1",- port=8082,+ assert startup_failure_message(quiet, RuntimeError("secret")) == (+ "Server startup failed: exc_type=RuntimeError")- app = FastAPI()- runtime = api_runtime_mod.AppRuntime(- app=app,- settings=cast(Settings, settings),+ assert startup_failure_message(verbose, RuntimeError("visible")) == (+ "RuntimeError: visible")-- validation = AsyncMock(side_effect=ServiceUnavailableError("bad model"))- cleanup = AsyncMock()- with (- patch.object(ProviderRuntime, "validate_configured_models", new=validation),- patch.object(ProviderRuntime, "cleanup", new=cleanup),- patch.object(api_runtime_mod.logger, "warning") as log_warning,- patch(- "free_claude_code.messaging.platforms.factory.create_messaging_components",- return_value=None,- ) as create_components,- ):- await runtime.startup()- await runtime.shutdown()-- validation.assert_awaited_once_with()- cleanup.assert_awaited_once()- create_components.assert_called_once()- logged = " ".join(- str(arg) for call in log_warning.call_args_list for arg in call.args+ assert (+ startup_failure_message(+ quiet,+ ServiceUnavailableError("configured model is unavailable"),+ )+ == "configured model is unavailable")- assert "validation failed" in logged- assert "bad model" in logged- assert "Traceback" not in logged- assert app.state.startup_validation_error == "bad model"@pytest.mark.asyncio-async def test_graceful_asgi_lifespan_model_validation_failure_starts(tmp_path):- import free_claude_code.api.app as api_app_mod-- settings = _app_settings(- messaging_platform="none",- telegram_bot_token=None,- allowed_telegram_user_id=None,- discord_bot_token=None,- allowed_discord_channels=None,- allowed_dir=str(tmp_path / "workspace"),- claude_workspace=str(tmp_path / "data"),- host="127.0.0.1",- port=8082,+async def test_runtime_asgi_app_starts_and_closes_owner_once():+ runtime = MagicMock(spec=ApplicationRuntime)+ runtime.settings = _settings()+ runtime.start = AsyncMock()+ runtime.close = AsyncMock()+ app = RuntimeASGIApp(AsyncMock(), runtime)+ received = iter(+ [+ {"type": "lifespan.startup"},+ {"type": "lifespan.shutdown"},+ ])- app = api_app_mod.GracefulLifespanApp(FastAPI())- sent: list[MutableMapping[str, Any]] = []- received = [- {"type": "lifespan.startup"},- {"type": "lifespan.shutdown"},- ]+ sent: list[dict[str, str]] = []- async def receive() -> MutableMapping[str, Any]:- return received.pop(0)+ async def receive():+ return next(received)- async def send(message: MutableMapping[str, Any]) -> None:+ async def send(message):sent.append(message)- validation = AsyncMock(side_effect=ServiceUnavailableError("bad model"))- cleanup = AsyncMock()- with (- patch.object(api_app_mod, "get_settings", return_value=settings),- patch.object(ProviderRuntime, "validate_configured_models", new=validation),- patch.object(ProviderRuntime, "cleanup", new=cleanup),- ):- await app({"type": "lifespan"}, receive, send)+ await app({"type": "lifespan"}, receive, send)+ runtime.start.assert_awaited_once()+ runtime.close.assert_awaited_once()assert sent == [{"type": "lifespan.startup.complete"},{"type": "lifespan.shutdown.complete"},]-def test_app_lifespan_messaging_import_error_no_crash(tmp_path, caplog):- """Messaging import failure logs warning and continues without crash."""- from free_claude_code.api.app import create_app-- app = create_app()-- settings = _app_settings(- messaging_platform="telegram",- telegram_bot_token="token",- allowed_telegram_user_id="123",- discord_bot_token=None,- allowed_discord_channels=None,- allowed_dir=str(tmp_path / "workspace"),- claude_workspace=str(tmp_path / "data"),- host="127.0.0.1",- port=8082,- )-- api_app_mod = importlib.import_module("free_claude_code.api.app")- runtime_cleanup = AsyncMock()- with (- patch.object(api_app_mod, "get_settings", return_value=settings),- patch.object(ProviderRuntime, "cleanup", new=runtime_cleanup),- patch(- "free_claude_code.messaging.platforms.factory.create_messaging_components",- side_effect=ImportError("discord not installed"),- ),- TestClient(app),- ):- pass-- assert getattr(app.state, "messaging_runtime", None) is None- runtime_cleanup.assert_awaited_once()---def test_app_lifespan_platform_start_exception_cleanup_still_runs(tmp_path):- """Exception during platform.start() logs error, cleanup still runs."""- from free_claude_code.api.app import create_app+async def test_runtime_asgi_app_reports_concise_startup_failure():+ runtime = MagicMock(spec=ApplicationRuntime)+ runtime.settings = _settings(log_api_error_tracebacks=False)+ runtime.start = AsyncMock(side_effect=RuntimeError("secret"))+ runtime.close = AsyncMock()+ app = RuntimeASGIApp(AsyncMock(), runtime)+ sent: list[dict[str, str]] = []++ async def receive():+ return {"type": "lifespan.startup"}++ async def send(message):+ sent.append(message)- app = create_app()+ await app({"type": "lifespan"}, receive, send)- settings = _app_settings(- messaging_platform="telegram",- telegram_bot_token="token",- allowed_telegram_user_id="123",- discord_bot_token=None,- allowed_discord_channels=None,- allowed_dir=str(tmp_path / "workspace"),- claude_workspace=str(tmp_path / "data"),- host="127.0.0.1",- port=8082,- )-- fake_platform = MagicMock()- fake_platform.name = "fake"- fake_platform.on_message = MagicMock()- fake_platform.start = AsyncMock(side_effect=RuntimeError("start failed"))- fake_platform.stop = AsyncMock()- fake_components = _fake_messaging_components(fake_platform)+ assert sent == [+ {+ "type": "lifespan.startup.failed",+ "message": "Server startup failed: exc_type=RuntimeError",+ }+ ]+ runtime.close.assert_not_awaited()- session_store = MagicMock()- session_store.load_conversation_snapshot.return_value = ConversationSnapshot()- cli_manager = MagicMock()- cli_manager.stop_all = AsyncMock()+def test_bootstrap_configures_default_log_and_publishes_only_services(tmp_path):+ log_path = tmp_path / "server.log"+ settings = _settings()- api_app_mod = importlib.import_module("free_claude_code.api.app")- runtime_cleanup = AsyncMock()with (- patch.object(api_app_mod, "get_settings", return_value=settings),- patch.object(ProviderRuntime, "cleanup", new=runtime_cleanup),- patch(- "free_claude_code.messaging.platforms.factory.create_messaging_components",- return_value=fake_components,- ),- patch(- "free_claude_code.messaging.session.SessionStore",- return_value=session_store,- ),patch(- "free_claude_code.cli.managed.ManagedClaudeSessionManager",- return_value=cli_manager,+ "free_claude_code.runtime.bootstrap.server_log_path",+ return_value=log_path,),- TestClient(app),+ patch("free_claude_code.runtime.bootstrap.configure_logging") as configure,):- pass-- runtime_cleanup.assert_awaited_once()---def test_app_lifespan_flush_pending_save_exception_warning_only(tmp_path):- """Session store flush exception on shutdown is logged as warning, no crash."""- from free_claude_code.api.app import create_app+ asgi_app = build_asgi_app(settings)- app = create_app()-- settings = _app_settings(- messaging_platform="telegram",- telegram_bot_token="token",- allowed_telegram_user_id="123",- discord_bot_token=None,- allowed_discord_channels=None,- allowed_dir=str(tmp_path / "workspace"),- claude_workspace=str(tmp_path / "data"),- host="127.0.0.1",- port=8082,+ configure.assert_called_once_with(+ Path(log_path),+ verbose_third_party=settings.log_raw_api_payloads,)+ api_app = cast(FastAPI, asgi_app.app)+ assert set(api_app.state._state) == {"services"}- fake_platform = MagicMock()- fake_platform.name = "fake"- fake_platform.on_message = MagicMock()- fake_platform.start = AsyncMock()- fake_platform.stop = AsyncMock()- fake_components = _fake_messaging_components(fake_platform)-- session_store = MagicMock()- session_store.load_conversation_snapshot.return_value = ConversationSnapshot()- session_store.flush_pending_save = MagicMock(side_effect=OSError("disk full"))-- cli_manager = MagicMock()- cli_manager.stop_all = AsyncMock()-- api_app_mod = importlib.import_module("free_claude_code.api.app")- runtime_cleanup = AsyncMock()- with (- patch.object(api_app_mod, "get_settings", return_value=settings),- patch.object(ProviderRuntime, "cleanup", new=runtime_cleanup),- patch(- "free_claude_code.messaging.platforms.factory.create_messaging_components",- return_value=fake_components,- ),- patch(- "free_claude_code.messaging.session.SessionStore",- return_value=session_store,- ),- patch(- "free_claude_code.cli.managed.ManagedClaudeSessionManager",- return_value=cli_manager,- ),- TestClient(app),- ):- pass-- session_store.flush_pending_save.assert_called_once()- runtime_cleanup.assert_awaited_once()---def test_create_app_writes_server_log_under_fcc_home(monkeypatch, tmp_path):- """App logging uses ~/.fcc/logs/server.log regardless of cwd."""- from loguru import logger-- import free_claude_code.config.logging_config as logging_config_mod- from free_claude_code.api.app import create_app- from free_claude_code.config.paths import server_log_path-- run_dir = tmp_path / "run"- run_dir.mkdir()- monkeypatch.chdir(run_dir)- monkeypatch.setenv("HOME", str(tmp_path))- monkeypatch.setenv("USERPROFILE", str(tmp_path))- monkeypatch.setattr(logging_config_mod, "_configured", False)-- create_app(lifespan_enabled=False)- logger.info("canonical log path test")- logger.complete()-- canonical_log = server_log_path()- assert canonical_log == tmp_path / ".fcc" / "logs" / "server.log"- assert canonical_log.is_file()- assert "canonical log path test" in canonical_log.read_text(encoding="utf-8")- assert not (run_dir / "logs" / "server.log").exists()---def test_create_app_honors_process_log_file_override(monkeypatch, tmp_path):- """Smoke subprocesses can redirect app logs without changing Settings."""- from loguru import logger-- import free_claude_code.config.logging_config as logging_config_mod- from free_claude_code.api.app import create_app- from free_claude_code.config.paths import server_log_path- custom_log = tmp_path / "smoke" / "server.log"- monkeypatch.setenv("HOME", str(tmp_path))- monkeypatch.setenv("USERPROFILE", str(tmp_path))- monkeypatch.setenv("LOG_FILE", str(custom_log))- monkeypatch.setattr(logging_config_mod, "_configured", False)+def test_bootstrap_honors_process_log_file_override(monkeypatch, tmp_path):+ log_path = tmp_path / "custom.log"+ monkeypatch.setenv("LOG_FILE", str(log_path))- create_app(lifespan_enabled=False)- logger.info("process log path test")- logger.complete()+ with patch("free_claude_code.runtime.bootstrap.configure_logging") as configure:+ build_asgi_app(_settings())- assert custom_log.is_file()- assert "process log path test" in custom_log.read_text(encoding="utf-8")- assert not server_log_path().exists()+ assert configure.call_args.args[0] == log_pathdiff --git a/tests/api/test_auth.py b/tests/api/test_auth.pyindex 4e0c4e55..6e94f2a2 100644--- a/tests/api/test_auth.py+++ b/tests/api/test_auth.py@@ -2,11 +2,11 @@ from unittest.mock import patchfrom fastapi.testclient import TestClient-from free_claude_code.api.app import create_appfrom free_claude_code.api.dependencies import get_settingsfrom free_claude_code.config.settings import Settings+from tests.api.support import create_test_app-app = create_app()+app = create_test_app()def test_anthropic_auth_token_required_and_accepts_x_api_key():diff --git a/tests/api/test_dependencies.py b/tests/api/test_dependencies.pyindex 43123aa0..b7ae11a2 100644--- a/tests/api/test_dependencies.py+++ b/tests/api/test_dependencies.py@@ -1,172 +1,108 @@-from types import SimpleNamespace-from typing import castfrom unittest.mock import MagicMock, patchimport pytest-from fastapi import HTTPException-from starlette.applications import Starlette-from starlette.datastructures import State+from fastapi import HTTPException, Requestfrom free_claude_code.api.dependencies import (- get_provider_runtime,+ get_services,get_settings,- maybe_provider_runtime,require_api_key,resolve_provider,)-from free_claude_code.config.nim import NimSettings-from free_claude_code.providers.exceptions import ServiceUnavailableError-from free_claude_code.providers.nvidia_nim import NvidiaNimProvider-from free_claude_code.providers.runtime import ProviderRuntime---def _make_mock_settings(**overrides):- """Create a mock settings object with provider runtime fields."""- mock = MagicMock()- mock.model = "nvidia_nim/meta/llama3"- mock.model_opus = None- mock.model_sonnet = None- mock.model_haiku = None- mock.nvidia_nim_api_key = "test_key"- mock.open_router_api_key = "test_openrouter_key"- mock.mistral_api_key = "test_mistral_key"- mock.codestral_api_key = "test_codestral_key"- mock.deepseek_api_key = "test_deepseek_key"- mock.wafer_api_key = "test_wafer_key"- mock.minimax_api_key = "test_minimax_key"- mock.opencode_api_key = "test_opencode_key"- mock.zai_api_key = "test_zai_key"- mock.lm_studio_base_url = "http://localhost:1234/v1"- mock.llamacpp_base_url = "http://localhost:8080/v1"- mock.ollama_base_url = "http://localhost:11434"- mock.nvidia_nim_proxy = ""- mock.open_router_proxy = ""- mock.mistral_proxy = ""- mock.codestral_proxy = ""- mock.lmstudio_proxy = ""- mock.llamacpp_proxy = ""- mock.kimi_proxy = ""- mock.kimi_api_key = "test_kimi_key"- mock.wafer_proxy = ""- mock.minimax_proxy = ""- mock.opencode_proxy = ""- mock.opencode_go_proxy = ""- mock.zai_proxy = ""- mock.fireworks_api_key = ""- mock.fireworks_proxy = ""- mock.cloudflare_api_token = ""- mock.cloudflare_account_id = ""- mock.cloudflare_proxy = ""- mock.gemini_api_key = ""- mock.gemini_proxy = ""- mock.groq_api_key = ""- mock.groq_proxy = ""- mock.cerebras_api_key = ""- mock.cerebras_proxy = ""- mock.provider_rate_limit = 40- mock.provider_rate_window = 60- mock.provider_max_concurrency = 5- mock.http_read_timeout = 300.0- mock.http_write_timeout = 10.0- mock.http_connect_timeout = 10.0- mock.enable_model_thinking = True- mock.log_raw_sse_events = False- mock.log_api_error_tracebacks = False- mock.nim = NimSettings()- for key, value in overrides.items():- setattr(mock, key, value)- return mock---def _app_with_runtime(settings=None):- app = SimpleNamespace(state=State())- app.state.provider_runtime = ProviderRuntime(settings or _make_mock_settings())- return cast(Starlette, app)---def _request(headers=None, token: str = ""):- return SimpleNamespace(- headers=headers or {},- ), SimpleNamespace(anthropic_auth_token=token)---def test_get_settings():- settings = get_settings()- assert settings is not None- with patch("free_claude_code.api.dependencies._get_settings") as mock_get:- get_settings()- mock_get.assert_called_once()---def test_get_provider_runtime_returns_app_scoped_runtime() -> None:- app = _app_with_runtime()-- assert isinstance(get_provider_runtime(app), ProviderRuntime)- assert maybe_provider_runtime(app) is get_provider_runtime(app)---def test_get_provider_runtime_missing_runtime_raises_service_unavailable() -> None:- app = cast(Starlette, SimpleNamespace(state=State()))-- assert maybe_provider_runtime(app) is None- with pytest.raises(- ServiceUnavailableError, match="Provider runtime is not configured"- ):- get_provider_runtime(app)---def test_resolve_provider_per_app_uses_separate_runtimes() -> None:- app1 = _app_with_runtime()- app2 = _app_with_runtime()-- with patch(- "free_claude_code.providers.transports.openai_chat.transport.AsyncOpenAI"- ):- p1 = resolve_provider("nvidia_nim", app=app1)- p2 = resolve_provider("nvidia_nim", app=app2)-- assert isinstance(p1, NvidiaNimProvider)- assert isinstance(p2, NvidiaNimProvider)- assert p1 is not p2+from free_claude_code.api.ports import ApiServices, RequestRuntimeLease+from free_claude_code.config.settings import Settings+from free_claude_code.providers.exceptions import AuthenticationError+from tests.api.support import create_test_app+++def _request(*, headers: dict[str, str], token: str) -> tuple[Request, Settings]:+ request = Request(+ {+ "type": "http",+ "method": "GET",+ "path": "/",+ "headers": [+ (key.lower().encode(), value.encode()) for key, value in headers.items()+ ],+ }+ )+ settings = Settings.model_construct(anthropic_auth_token=token)+ return request, settings+++def _lease(*, provider=None, error: Exception | None = None):+ lease = MagicMock(spec=RequestRuntimeLease)+ lease.is_provider_cached.return_value = False+ if error is None:+ lease.resolve_provider.return_value = provider or MagicMock()+ else:+ lease.resolve_provider.side_effect = error+ return lease+++def test_get_services_reads_the_single_app_state_boundary() -> None:+ app = create_test_app()+ request = Request({"type": "http", "app": app})++ services = get_services(request)++ assert services is app.state.services+ assert isinstance(services, ApiServices)+++def test_get_settings_reads_current_request_runtime_settings() -> None:+ app = create_test_app(+ Settings.model_construct(+ model="deepseek/test-model",+ anthropic_auth_token="",+ )+ )++ assert get_settings(app.state.services).model == "deepseek/test-model"+++def test_resolve_provider_uses_retained_lease_and_logs_first_initialization() -> None:+ provider = MagicMock()+ lease = _lease(provider=provider)++ with patch("free_claude_code.api.dependencies.logger.info") as log_info:+ result = resolve_provider("nvidia_nim", lease=lease)++ assert result is provider+ lease.resolve_provider.assert_called_once_with("nvidia_nim")+ log_info.assert_called_once_with("Provider initialized: {}", "nvidia_nim")+++def test_resolve_provider_skips_initialization_log_for_cached_provider() -> None:+ lease = _lease()+ lease.is_provider_cached.return_value = True++ with patch("free_claude_code.api.dependencies.logger.info") as log_info:+ resolve_provider("nvidia_nim", lease=lease)++ log_info.assert_not_called()def test_resolve_provider_missing_key_raises_503() -> None:- app = _app_with_runtime(_make_mock_settings(open_router_api_key=""))+ lease = _lease(+ error=AuthenticationError(+ "OPENROUTER_API_KEY is required. Get one at https://openrouter.ai"+ )+ )with pytest.raises(HTTPException) as exc_info:- resolve_provider("open_router", app=app)+ resolve_provider("open_router", lease=lease)assert exc_info.value.status_code == 503assert "OPENROUTER_API_KEY" in exc_info.value.detailassert "openrouter.ai" in exc_info.value.detail-def test_resolve_provider_missing_runtime_raises_service_unavailable() -> None:- app = cast(Starlette, SimpleNamespace(state=State()))-- with pytest.raises(- ServiceUnavailableError, match="Provider runtime is not configured"- ):- resolve_provider("nvidia_nim", app=app)---def test_resolve_provider_unrelated_value_error_is_not_unknown_provider_log() -> None:- import free_claude_code.api.dependencies as deps-- app = _app_with_runtime()- runtime = get_provider_runtime(app)+def test_resolve_provider_unrelated_error_is_not_reclassified() -> None:+ lease = _lease(error=ValueError("unrelated config"))- with (- patch.object(- runtime,- "resolve_provider",- side_effect=ValueError("unrelated config"),- ),- patch.object(deps.logger, "error") as log_err,- pytest.raises(ValueError, match="unrelated config"),- ):- deps.resolve_provider("nvidia_nim", app=app)- log_err.assert_not_called()+ with pytest.raises(ValueError, match="unrelated config"):+ resolve_provider("nvidia_nim", lease=lease)def test_require_api_key_allows_when_no_token_configured():diff --git a/tests/api/test_model_listing.py b/tests/api/test_model_listing.pyindex d2480356..2b7dfc6f 100644--- a/tests/api/test_model_listing.py+++ b/tests/api/test_model_listing.py@@ -1,10 +1,8 @@from fastapi.testclient import TestClient-from free_claude_code.api.app import create_app-from free_claude_code.api.dependencies import get_settingsfrom free_claude_code.config.settings import Settingsfrom free_claude_code.providers.model_listing import ProviderModelInfo-from free_claude_code.providers.runtime import ProviderRuntime+from tests.api.support import create_test_app, provider_manager_for_appdef _settings(@@ -22,24 +20,28 @@ def _settings()+def _cache_models(app, provider_id: str, *model_ids: str) -> None:+ provider_manager_for_app(app).cache_model_infos(+ provider_id,+ {ProviderModelInfo(model_id) for model_id in model_ids},+ )++def test_models_list_includes_configured_refs_cached_provider_models_and_aliases():- app = create_app(lifespan_enabled=False)- settings = _settings()- runtime = ProviderRuntime(settings)- runtime.cache_model_ids("deepseek", {"deepseek-chat"})- runtime.cache_model_ids("open_router", {"meta/llama-3.3", "anthropic/claude-opus"})- app.state.provider_runtime = runtime- app.dependency_overrides[get_settings] = lambda: settings-- try:- response = TestClient(app).get("/v1/models")- finally:- app.dependency_overrides.clear()+ app = create_test_app(_settings())+ _cache_models(app, "deepseek", "deepseek-chat")+ _cache_models(+ app,+ "open_router",+ "meta/llama-3.3",+ "anthropic/claude-opus",+ )++ response = TestClient(app).get("/v1/models")assert response.status_code == 200data = response.json()ids = [item["id"] for item in data["data"]]-assert ids[:6] == ["anthropic/deepseek/deepseek-chat","claude-3-freecc-no-thinking/deepseek/deepseek-chat",@@ -49,11 +51,7 @@ def test_models_list_includes_configured_refs_cached_provider_models_and_aliases"claude-3-freecc-no-thinking/open_router/meta/llama-3.3",]assert ids.count("anthropic/deepseek/deepseek-chat") == 1- assert ids.count("claude-3-freecc-no-thinking/deepseek/deepseek-chat") == 1assert ids.count("anthropic/open_router/anthropic/claude-opus") == 1- assert (- ids.count("claude-3-freecc-no-thinking/open_router/anthropic/claude-opus") == 1- )display_names = {item["id"]: item["display_name"] for item in data["data"]}assert (display_names["anthropic/open_router/meta/llama-3.3"]@@ -69,25 +67,19 @@ def test_models_list_includes_configured_refs_cached_provider_models_and_aliasesassert data["has_more"] is False-def test_models_list_uses_openrouter_thinking_metadata_for_cached_models():- app = create_app(lifespan_enabled=False)- settings = _settings(model_opus=None)- runtime = ProviderRuntime(settings)- runtime.cache_model_ids("deepseek", {"deepseek-chat"})- runtime.cache_model_infos(+def test_models_list_uses_thinking_metadata_for_cached_models():+ app = create_test_app(_settings(model_opus=None))+ manager = provider_manager_for_app(app)+ _cache_models(app, "deepseek", "deepseek-chat")+ manager.cache_model_infos("open_router",{ProviderModelInfo("reasoning-model", supports_thinking=True),ProviderModelInfo("plain-model", supports_thinking=False),},)- app.state.provider_runtime = runtime- app.dependency_overrides[get_settings] = lambda: settings- try:- response = TestClient(app).get("/v1/models")- finally:- app.dependency_overrides.clear()+ response = TestClient(app).get("/v1/models")assert response.status_code == 200ids = [item["id"] for item in response.json()["data"]]@@ -97,50 +89,38 @@ def test_models_list_uses_openrouter_thinking_metadata_for_cached_models():assert "claude-3-freecc-no-thinking/open_router/plain-model" in ids-def test_models_list_uses_cached_metadata_for_configured_openrouter_refs():- app = create_app(lifespan_enabled=False)- settings = _settings(- model="open_router/plain-model",- model_opus=None,- model_haiku=None,+def test_models_list_uses_cached_metadata_for_configured_refs():+ app = create_test_app(+ _settings(+ model="open_router/plain-model",+ model_opus=None,+ model_haiku=None,+ ))- runtime = ProviderRuntime(settings)- runtime.cache_model_infos(+ provider_manager_for_app(app).cache_model_infos("open_router",{ProviderModelInfo("plain-model", supports_thinking=False)},)- app.state.provider_runtime = runtime- app.dependency_overrides[get_settings] = lambda: settings- try:- response = TestClient(app).get("/v1/models")- finally:- app.dependency_overrides.clear()+ response = TestClient(app).get("/v1/models")- assert response.status_code == 200ids = [item["id"] for item in response.json()["data"]]assert "anthropic/open_router/plain-model" not in idsassert ids[0] == "claude-3-freecc-no-thinking/open_router/plain-model"def test_models_list_includes_cached_wafer_models():- app = create_app(lifespan_enabled=False)- settings = _settings(- model="wafer/DeepSeek-V4-Pro",- model_opus=None,- model_haiku=None,+ app = create_test_app(+ _settings(+ model="wafer/DeepSeek-V4-Pro",+ model_opus=None,+ model_haiku=None,+ ))- runtime = ProviderRuntime(settings)- runtime.cache_model_ids("wafer", {"DeepSeek-V4-Pro", "MiniMax-M2.7"})- app.state.provider_runtime = runtime- app.dependency_overrides[get_settings] = lambda: settings+ _cache_models(app, "wafer", "DeepSeek-V4-Pro", "MiniMax-M2.7")- try:- response = TestClient(app).get("/v1/models")- finally:- app.dependency_overrides.clear()+ response = TestClient(app).get("/v1/models")- assert response.status_code == 200ids = [item["id"] for item in response.json()["data"]]assert "anthropic/wafer/DeepSeek-V4-Pro" in idsassert "claude-3-freecc-no-thinking/wafer/DeepSeek-V4-Pro" in ids@@ -148,15 +128,10 @@ def test_models_list_includes_cached_wafer_models():assert "claude-3-freecc-no-thinking/wafer/MiniMax-M2.7" in ids-def test_models_list_works_without_provider_runtime():- app = create_app(lifespan_enabled=False)- settings = _settings()- app.dependency_overrides[get_settings] = lambda: settings+def test_models_list_works_with_empty_discovery_catalog():+ app = create_test_app(_settings())- try:- response = TestClient(app).get("/v1/models")- finally:- app.dependency_overrides.clear()+ response = TestClient(app).get("/v1/models")assert response.status_code == 200ids = [item["id"] for item in response.json()["data"]]diff --git a/tests/api/test_openai_responses.py b/tests/api/test_openai_responses.pyindex b95bba5a..98a210d1 100644--- a/tests/api/test_openai_responses.py+++ b/tests/api/test_openai_responses.py@@ -4,10 +4,10 @@ from unittest.mock import MagicMock, patchimport pytestfrom fastapi.testclient import TestClient-from free_claude_code.api.app import create_appfrom free_claude_code.core.anthropic.stream_contracts import parse_sse_textfrom free_claude_code.core.anthropic.streaming import format_sse_eventfrom free_claude_code.providers.exceptions import RateLimitError+from tests.api.support import create_test_appclass FakeProvider:@@ -50,11 +50,9 @@ class PostStartFailingProvider(FakeProvider):@pytest.fixturedef responses_client():provider = FakeProvider(_anthropic_text_stream("Hello from provider"))- app = create_app(lifespan_enabled=False)+ app = create_test_app()with (- patch(- "free_claude_code.api.dependencies.resolve_provider", return_value=provider- ),+ patch("free_claude_code.api.routes.resolve_provider", return_value=provider),TestClient(app) as client,):yield client, provider@@ -103,11 +101,9 @@ def test_create_response_stream_routes_through_provider(def test_create_response_pre_start_provider_error_returns_openai_error() -> None:provider = PreStartFailingProvider()- app = create_app(lifespan_enabled=False)+ app = create_test_app()with (- patch(- "free_claude_code.api.dependencies.resolve_provider", return_value=provider- ),+ patch("free_claude_code.api.routes.resolve_provider", return_value=provider),patch("free_claude_code.api.handlers.responses.trace_event") as trace,TestClient(app) as client,):@@ -142,11 +138,9 @@ def test_create_response_pre_start_provider_error_returns_openai_error() -> Nonedef test_create_response_post_start_failure_preserves_response_id() -> None:provider = PostStartFailingProvider()- app = create_app(lifespan_enabled=False)+ app = create_test_app()with (- patch(- "free_claude_code.api.dependencies.resolve_provider", return_value=provider- ),+ patch("free_claude_code.api.routes.resolve_provider", return_value=provider),TestClient(app) as client,):response = client.post(@@ -167,11 +161,9 @@ def test_create_response_post_start_failure_preserves_response_id() -> None:def test_create_response_stream_bypasses_local_message_optimizations() -> None:provider = FakeProvider(_anthropic_text_stream("Provider response"))- app = create_app(lifespan_enabled=False)+ app = create_test_app()with (- patch(- "free_claude_code.api.dependencies.resolve_provider", return_value=provider- ),+ patch("free_claude_code.api.routes.resolve_provider", return_value=provider),patch("free_claude_code.api.handlers.messages.try_optimizations",side_effect=AssertionError("Responses must not use message optimizations"),@@ -215,11 +207,9 @@ def test_create_response_stream_false_returns_openai_error(def test_create_response_stream_preserves_interleaved_reasoning_order() -> None:provider = FakeProvider(_anthropic_interleaved_reasoning_stream())- app = create_app(lifespan_enabled=False)+ app = create_test_app()with (- patch(- "free_claude_code.api.dependencies.resolve_provider", return_value=provider- ),+ patch("free_claude_code.api.routes.resolve_provider", return_value=provider),TestClient(app) as client,):response = client.post(@@ -258,11 +248,9 @@ def test_create_response_stream_preserves_interleaved_reasoning_order() -> None:def test_create_response_tool_stream_emits_function_call() -> None:provider = FakeProvider(_anthropic_tool_stream())- app = create_app(lifespan_enabled=False)+ app = create_test_app()with (- patch(- "free_claude_code.api.dependencies.resolve_provider", return_value=provider- ),+ patch("free_claude_code.api.routes.resolve_provider", return_value=provider),TestClient(app) as client,):response = client.post(@@ -294,11 +282,9 @@ def test_create_response_malformed_provider_function_call_fails_stream() -> Noneprovider = FakeProvider(_anthropic_tool_stream(partial_json='{"value":"FCC" "bad"}'))- app = create_app(lifespan_enabled=False)+ app = create_test_app()with (- patch(- "free_claude_code.api.dependencies.resolve_provider", return_value=provider- ),+ patch("free_claude_code.api.routes.resolve_provider", return_value=provider),TestClient(app) as client,):response = client.post(@@ -328,11 +314,9 @@ def test_create_response_malformed_provider_function_call_fails_stream() -> Nonedef test_create_response_accepts_codex_namespace_tool_request() -> None:provider = FakeProvider(_anthropic_tool_stream(tool_name="mcp__node_repl__js"))- app = create_app(lifespan_enabled=False)+ app = create_test_app()with (- patch(- "free_claude_code.api.dependencies.resolve_provider", return_value=provider- ),+ patch("free_claude_code.api.routes.resolve_provider", return_value=provider),TestClient(app) as client,):response = client.post(@@ -378,11 +362,9 @@ def test_create_response_accepts_codex_custom_tool_request() -> None:partial_json='{"input":"*** Begin Patch"}',))- app = create_app(lifespan_enabled=False)+ app = create_test_app()with (- patch(- "free_claude_code.api.dependencies.resolve_provider", return_value=provider- ),+ patch("free_claude_code.api.routes.resolve_provider", return_value=provider),TestClient(app) as client,):response = client.post(@@ -431,11 +413,9 @@ def test_create_response_stream_provider_error_returns_response_failed() -> None)])- app = create_app(lifespan_enabled=False)+ app = create_test_app()with (- patch(- "free_claude_code.api.dependencies.resolve_provider", return_value=provider- ),+ patch("free_claude_code.api.routes.resolve_provider", return_value=provider),TestClient(app) as client,):response = client.post(@@ -463,11 +443,9 @@ def test_create_response_stream_provider_error_returns_response_failed() -> Nonedef test_create_response_replays_prior_reasoning_as_reasoning_content() -> None:provider = FakeProvider(_anthropic_text_stream("done"))- app = create_app(lifespan_enabled=False)+ app = create_test_app()with (- patch(- "free_claude_code.api.dependencies.resolve_provider", return_value=provider- ),+ patch("free_claude_code.api.routes.resolve_provider", return_value=provider),TestClient(app) as client,):response = client.post(@@ -523,11 +501,9 @@ def test_create_response_replays_prior_reasoning_as_reasoning_content() -> None:def test_create_response_quarantines_malformed_prior_function_call() -> None:provider = FakeProvider(_anthropic_text_stream("done"))- app = create_app(lifespan_enabled=False)+ app = create_test_app()with (- patch(- "free_claude_code.api.dependencies.resolve_provider", return_value=provider- ),+ patch("free_claude_code.api.routes.resolve_provider", return_value=provider),TestClient(app) as client,):response = client.post(@@ -575,11 +551,9 @@ def test_create_response_maps_reasoning_effort_to_thinking_request(expected_enabled: bool,) -> None:provider = FakeProvider(_anthropic_text_stream("done"))- app = create_app(lifespan_enabled=False)+ app = create_test_app()with (- patch(- "free_claude_code.api.dependencies.resolve_provider", return_value=provider- ),+ patch("free_claude_code.api.routes.resolve_provider", return_value=provider),TestClient(app) as client,):response = client.post(@@ -600,11 +574,9 @@ def test_create_response_maps_reasoning_effort_to_thinking_request(def test_create_response_maps_redacted_thinking_to_encrypted_reasoning() -> None:provider = FakeProvider(_anthropic_redacted_thinking_stream())- app = create_app(lifespan_enabled=False)+ app = create_test_app()with (- patch(- "free_claude_code.api.dependencies.resolve_provider", return_value=provider- ),+ patch("free_claude_code.api.routes.resolve_provider", return_value=provider),TestClient(app) as client,):response = client.post(diff --git a/tests/api/test_response_streams.py b/tests/api/test_response_streams.pyindex 45524065..37f54d7a 100644--- a/tests/api/test_response_streams.py+++ b/tests/api/test_response_streams.py@@ -3,12 +3,15 @@import asyncioimport jsonfrom collections.abc import AsyncGenerator+from typing import cast+from unittest.mock import AsyncMockimport pytestfrom fastapi.responses import JSONResponse, StreamingResponsefrom free_claude_code.api.response_streams import (anthropic_sse_streaming_response,+ bind_response_lifetime,terminal_execution_error_response,)from free_claude_code.core.anthropic import anthropic_error_payload@@ -133,3 +136,94 @@ async def test_anthropic_post_start_exception_emits_terminal_error_frame() -> Noevents = parse_sse_text(text)assert [event.event for event in events] == ["message_start", "error"]assert events[-1].data["error"]["message"] == "socket cut"+++async def test_non_streaming_response_releases_resource_before_return() -> None:+ release = AsyncMock()+ response = JSONResponse({"ok": True})++ result = await bind_response_lifetime(response, release)++ assert result is response+ release.assert_awaited_once()+++async def test_streaming_response_releases_after_normal_completion() -> None:+ release = AsyncMock()+ response = StreamingResponse(_body_chunks(["one", "two"]))++ result = await bind_response_lifetime(response, release)++ assert result is response+ release.assert_not_awaited()+ assert await _drain(response) == "onetwo"+ release.assert_awaited_once()+++async def test_streaming_response_releases_after_body_failure() -> None:+ release = AsyncMock()+ response = StreamingResponse(+ _body_then_raises(["one"], RuntimeError("stream failed"))+ )+ await bind_response_lifetime(response, release)++ with pytest.raises(RuntimeError, match="stream failed"):+ await _drain(response)++ release.assert_awaited_once()+++async def test_streaming_response_releases_when_consumer_closes_early() -> None:+ release = AsyncMock()+ source_closed = asyncio.Event()++ async def body() -> AsyncGenerator[str]:+ try:+ yield "one"+ await asyncio.Event().wait()+ finally:+ source_closed.set()++ response = StreamingResponse(body())+ await bind_response_lifetime(response, release)+ iterator = cast(+ AsyncGenerator[str],+ response.body_iterator.__aiter__(),+ )++ assert await anext(iterator) == "one"+ await iterator.aclose()++ assert source_closed.is_set()+ release.assert_awaited_once()+++async def test_streaming_response_releases_when_consumer_is_cancelled() -> None:+ release = AsyncMock()+ entered = asyncio.Event()+ source_closed = asyncio.Event()++ async def body() -> AsyncGenerator[str]:+ try:+ yield "one"+ entered.set()+ await asyncio.Event().wait()+ finally:+ source_closed.set()++ response = StreamingResponse(body())+ await bind_response_lifetime(response, release)+ drain_task = asyncio.create_task(_drain(response))+ await entered.wait()++ drain_task.cancel()+ with pytest.raises(asyncio.CancelledError):+ await drain_task++ assert source_closed.is_set()+ release.assert_awaited_once()diff --git a/tests/api/test_routes_optimizations.py b/tests/api/test_routes_optimizations.pyindex a3e03ebd..b91c2d32 100644--- a/tests/api/test_routes_optimizations.py+++ b/tests/api/test_routes_optimizations.py@@ -3,11 +3,12 @@ from unittest.mock import AsyncMock, MagicMock, patchimport pytestfrom fastapi.testclient import TestClient-from free_claude_code.api.app import create_appfrom free_claude_code.api.dependencies import get_settings+from free_claude_code.api.ports import ApiServices, StopResultfrom free_claude_code.config.settings import Settings+from tests.api.support import create_test_app-app = create_app()+app = create_test_app()@pytest.fixture@@ -151,37 +152,34 @@ def test_count_tokens_error_returns_500(client):def test_stop_cli_with_messaging_workflow(client):- mock_workflow = MagicMock()- # Mock the async method to return a completed future or just mock it since TestClient- # will run the app in a way that respects it?- # Actually, we need to mock it as an async function.- mock_workflow.stop_all_tasks = AsyncMock(return_value=3)- app.state.messaging_workflow = mock_workflow+ session_control = MagicMock()+ session_control.stop_all = AsyncMock(return_value=StopResult(cancelled_count=3))+ services = app.state.services+ app.state.services = ApiServices(+ requests=services.requests,+ admin=services.admin,+ sessions=session_control,+ )response = client.post("/stop")assert response.status_code == 200assert response.json()["cancelled_count"] == 3- mock_workflow.stop_all_tasks.assert_called_once()-- # Cleanup state- if hasattr(app.state, "messaging_workflow"):- del app.state.messaging_workflow+ session_control.stop_all.assert_awaited_once()def test_stop_cli_fallback_to_manager(client):- if hasattr(app.state, "messaging_workflow"):- del app.state.messaging_workflow-- mock_manager = MagicMock()- mock_manager.stop_all = AsyncMock()- app.state.cli_manager = mock_manager+ session_control = MagicMock()+ session_control.stop_all = AsyncMock(return_value=StopResult(source="cli_manager"))+ services = app.state.services+ app.state.services = ApiServices(+ requests=services.requests,+ admin=services.admin,+ sessions=session_control,+ )response = client.post("/stop")assert response.status_code == 200assert response.json()["source"] == "cli_manager"- mock_manager.stop_all.assert_called_once()-- if hasattr(app.state, "cli_manager"):- del app.state.cli_manager+ session_control.stop_all.assert_awaited_once()diff --git a/tests/api/test_runtime_safe_logging.py b/tests/api/test_runtime_safe_logging.pyindex 695f3df2..e6b32ad3 100644--- a/tests/api/test_runtime_safe_logging.py+++ b/tests/api/test_runtime_safe_logging.py@@ -1,69 +1,61 @@-"""Tests for safe default logging in :mod:`api.runtime`."""+"""Safe default logging tests for the application runtime owner."""-import importlibimport logging-from unittest.mock import MagicMock, patch+from unittest.mock import patchimport pytest-from tests.api.test_app_lifespan_and_errors import _app_settings+from free_claude_code.config.settings import Settings+from free_claude_code.runtime.application import ApplicationRuntime, best_effort+from free_claude_code.runtime.provider_manager import ProviderRuntimeManager@pytest.mark.asyncioasync def test_messaging_start_failure_default_logs_exclude_traceback(caplog):- api_runtime_mod = importlib.import_module("free_claude_code.api.runtime")- settings = _app_settings(- messaging_platform="telegram",- telegram_bot_token="t",- allowed_telegram_user_id="1",- discord_bot_token=None,- allowed_discord_channels=None,- allowed_dir="",- claude_workspace="./agent_workspace",- host="127.0.0.1",- port=8082,- log_api_error_tracebacks=False,+ settings = Settings().model_copy(+ update={+ "messaging_platform": "telegram",+ "telegram_bot_token": "t",+ "allowed_telegram_user_id": "1",+ "log_api_error_tracebacks": False,+ })- runtime = api_runtime_mod.AppRuntime(app=MagicMock(), settings=settings)+ runtime = ApplicationRuntime(ProviderRuntimeManager(settings))with (patch(- "free_claude_code.messaging.platforms.factory.create_messaging_components",+ "free_claude_code.runtime.application.messaging_platform_factory.create_messaging_components",side_effect=RuntimeError("SECRET_RUNTIME_DETAIL"),),caplog.at_level(logging.ERROR),):await runtime._start_messaging_if_configured()- blob = " | ".join(r.getMessage() for r in caplog.records)+ blob = " | ".join(record.getMessage() for record in caplog.records)assert "SECRET_RUNTIME_DETAIL" not in blobassert "exc_type=RuntimeError" in blob@pytest.mark.asyncioasync def test_best_effort_default_logs_exclude_exception_text(caplog):- api_runtime_mod = importlib.import_module("free_claude_code.api.runtime")-async def boom():raise ValueError("SECRET_SHUTDOWN")with caplog.at_level(logging.WARNING):- await api_runtime_mod.best_effort("test_step", boom(), log_verbose_errors=False)+ await best_effort("test_step", boom(), log_verbose_errors=False)- blob = " | ".join(r.getMessage() for r in caplog.records)+ blob = " | ".join(record.getMessage() for record in caplog.records)assert "SECRET_SHUTDOWN" not in blobassert "exc_type=ValueError" in blob@pytest.mark.asyncioasync def test_best_effort_verbose_includes_exception_text(caplog):- api_runtime_mod = importlib.import_module("free_claude_code.api.runtime")-async def boom():raise ValueError("VISIBLE_SHUTDOWN")with caplog.at_level(logging.WARNING):- await api_runtime_mod.best_effort("test_step", boom(), log_verbose_errors=True)+ await best_effort("test_step", boom(), log_verbose_errors=True)- blob = " | ".join(r.getMessage() for r in caplog.records)+ blob = " | ".join(record.getMessage() for record in caplog.records)assert "VISIBLE_SHUTDOWN" in blobdiff --git a/tests/cli/test_entrypoints.py b/tests/cli/test_entrypoints.pyindex 9a6d4855..c241db22 100644--- a/tests/cli/test_entrypoints.py+++ b/tests/cli/test_entrypoints.py@@ -2,6 +2,7 @@import jsonimport tomllib+from collections.abc import Callablefrom pathlib import Pathfrom types import SimpleNamespacefrom unittest.mock import MagicMock, patch@@ -183,8 +184,8 @@ def test_schedule_open_admin_browser_opens_when_health_ready() -> None:"""Opening /admin runs after /health preflight succeeds."""monkeypatch.delenv("FCC_OPEN_BROWSER", raising=False)- from free_claude_code.api.admin_urls import local_admin_urlfrom free_claude_code.cli import entrypoints+ from free_claude_code.config.server_urls import local_admin_urlsettings = _launcher_settings(port=31337)opened_urls: list[str] = []@@ -233,6 +234,11 @@ def test_serve_supervisor_restarts_when_app_requests_restart() -> None:get_settings = MagicMock(side_effect=[settings, settings])get_settings.cache_clear = MagicMock()servers: list[object] = []+ restart_callbacks: list[Callable[[], None]] = []++ def build_asgi_app(_settings: Settings, restart_callback: Callable[[], None]):+ restart_callbacks.append(restart_callback)+ return MagicMock()class FakeServer:def __init__(self, config):@@ -242,7 +248,7 @@ def test_serve_supervisor_restarts_when_app_requests_restart() -> None:def run(self):if len(servers) == 1:- self.config.app.app.state.admin_restart_callback()+ restart_callbacks[-1]()assert self.should_exit is Truedef fake_config(app, **kwargs):@@ -252,6 +258,7 @@ def test_serve_supervisor_restarts_when_app_requests_restart() -> None:patch.object(entrypoints, "get_settings", get_settings),patch.object(entrypoints.uvicorn, "Config", side_effect=fake_config),patch.object(entrypoints.uvicorn, "Server", side_effect=FakeServer),+ patch.object(entrypoints, "build_asgi_app", side_effect=build_asgi_app),patch.object(entrypoints, "_schedule_open_admin_browser"),patch.object(entrypoints, "kill_all_best_effort") as kill_all,):diff --git a/tests/contracts/test_admin_provider_manifest.py b/tests/contracts/test_admin_provider_manifest.pyindex 4bc69d88..0212ba1a 100644--- a/tests/contracts/test_admin_provider_manifest.py+++ b/tests/contracts/test_admin_provider_manifest.py@@ -1,6 +1,6 @@"""Ensure admin UI manifest exposes every catalog credential/proxy binding."""-from free_claude_code.api.admin_config.manifest import FIELD_BY_KEY+from free_claude_code.config.admin.manifest import FIELD_BY_KEYfrom free_claude_code.config.provider_catalog import PROVIDER_CATALOGfrom free_claude_code.config.settings import Settings@@ -96,10 +96,12 @@ def test_provider_catalog_proxy_attrs_in_admin_manifest() -> None:def test_provider_catalog_display_names_are_admin_status_source() -> None:- from free_claude_code.api.admin_config.status import provider_config_status+ from free_claude_code.config.admin.status import provider_config_status+ from free_claude_code.config.admin.values import load_value_statestatus_by_provider = {- entry["provider_id"]: entry for entry in provider_config_status()+ entry["provider_id"]: entry+ for entry in provider_config_status(load_value_state())}assert set(status_by_provider) == set(PROVIDER_CATALOG)diff --git a/tests/contracts/test_architecture_contracts.py b/tests/contracts/test_architecture_contracts.pyindex e8532729..c4e60eff 100644--- a/tests/contracts/test_architecture_contracts.py+++ b/tests/contracts/test_architecture_contracts.py@@ -32,16 +32,11 @@ def test_smoke_lib_has_no_sse_shim_module() -> None:assert not (repo_root / "smoke" / "lib" / "sse.py").exists()-def test_api_package_exports() -> None:+def test_api_package_marker_is_import_light() -> None:import free_claude_code.api as api- assert set(api.__all__) == {- "MessagesRequest",- "MessagesResponse",- "TokenCountRequest",- "TokenCountResponse",- "create_app",- }+ assert not hasattr(api, "__all__")+ assert "create_app" not in vars(api)def test_root_env_example_is_the_single_template_source() -> None:diff --git a/tests/contracts/test_import_boundaries.py b/tests/contracts/test_import_boundaries.pyindex d5859f7c..88d8773a 100644--- a/tests/contracts/test_import_boundaries.py+++ b/tests/contracts/test_import_boundaries.py@@ -9,6 +9,7 @@ _API_ALLOWED_PROVIDER_MODULES = frozenset("free_claude_code.providers","free_claude_code.providers.base","free_claude_code.providers.exceptions",+ "free_claude_code.providers.model_listing","free_claude_code.providers.runtime",})@@ -52,14 +53,30 @@ def test_runtime_packages_live_only_under_src_namespace() -> None:package_root = repo_root / "src" / "free_claude_code"assert (package_root / "__init__.py").exists()- for package_name in {"api", "cli", "config", "core", "messaging", "providers"}:+ for package_name in {+ "api",+ "cli",+ "config",+ "core",+ "messaging",+ "providers",+ "runtime",+ }:assert (package_root / package_name).is_dir()assert not (repo_root / package_name).exists()def test_no_old_top_level_first_party_imports_remain() -> None:repo_root = Path(__file__).resolve().parents[2]- forbidden = {"api", "cli", "config", "core", "messaging", "providers"}+ forbidden = {+ "api",+ "cli",+ "config",+ "core",+ "messaging",+ "providers",+ "runtime",+ }offenders: list[str] = []for path in repo_root.rglob("*.py"):@@ -99,6 +116,7 @@ def test_provider_adapters_do_not_import_runtime_layers() -> None:"free_claude_code.api.","free_claude_code.messaging.","free_claude_code.cli.",+ "free_claude_code.runtime.",),)@@ -213,7 +231,7 @@ _MESSAGING_ALLOWED_PROVIDER_MODULES = frozenset(def test_messaging_does_not_import_disallowed_modules() -> None:- """Messaging is wired by ``api.runtime``; narrow provider imports only for NIM voice ASR."""+ """Runtime composition is external; only NIM voice ASR crosses provider bounds."""repo_root = Path(__file__).resolve().parents[2]offenders: list[str] = []for path in (repo_root / "src" / "free_claude_code" / "messaging").rglob("*.py"):@@ -239,6 +257,83 @@ def test_messaging_does_not_import_disallowed_modules() -> None:assert sorted(offenders) == []+def test_single_owner_runtime_dependency_direction() -> None:+ repo_root = Path(__file__).resolve().parents[2]+ package_root = repo_root / "src" / "free_claude_code"+ api_root = package_root / "api"+ cli_root = package_root / "cli"+ runtime_root = package_root / "runtime"++ assert runtime_root.is_dir()+ for removed in {+ api_root / "runtime.py",+ api_root / "admin_urls.py",+ api_root / "gateway_model_ids.py",+ api_root / "admin_config",+ }:+ assert not removed.exists()++ assert (+ _imports_matching(+ [api_root],+ forbidden_prefixes=(+ "free_claude_code.cli",+ "free_claude_code.messaging",+ "free_claude_code.runtime",+ ),+ )+ == []+ )+ assert (+ _imports_matching(+ [cli_root],+ forbidden_prefixes=("free_claude_code.api",),+ )+ == []+ )++ api_text = "\n".join(+ path.read_text(encoding="utf-8") for path in api_root.rglob("*.py")+ )+ for removed_state in {+ "app.state.provider_runtime",+ "app.state.messaging_runtime",+ "app.state.messaging_workflow",+ "app.state.cli_manager",+ "app.state.admin_restart_callback",+ "app.state.admin_pending_fields",+ }:+ assert removed_state not in api_text+ assert "app.state.services" in api_text++ for marker in {api_root / "__init__.py", runtime_root / "__init__.py"}:+ marker_text = marker.read_text(encoding="utf-8")+ assert "from " not in marker_text+ assert "import " not in marker_text+ assert "__all__" not in marker_text+++def test_neutral_moved_helpers_keep_their_dependency_boundaries() -> None:+ repo_root = Path(__file__).resolve().parents[2]+ package_root = repo_root / "src" / "free_claude_code"+ admin_root = package_root / "config" / "admin"+ gateway_ids = package_root / "core" / "gateway_model_ids.py"++ admin_offenders: list[str] = []+ for path in admin_root.rglob("*.py"):+ for imported in _imports_from(path, repo_root):+ if imported is None or not imported.startswith("free_claude_code."):+ continue+ if not imported.startswith("free_claude_code.config"):+ admin_offenders.append(f"{path.relative_to(repo_root)}: {imported}")+ assert admin_offenders == []++ assert all(+ not imported.startswith("free_claude_code.")+ for imported in _imports_from(gateway_ids, repo_root)+ )++def test_api_may_only_import_narrow_provider_facade() -> None:"""HTTP layer must not depend on per-adapter provider subpackages."""repo_root = Path(__file__).resolve().parents[2]@@ -528,9 +623,11 @@ def test_openai_responses_uses_adapter_boundary() -> None:def test_admin_config_uses_package_owners_and_catalog_manifest() -> None:repo_root = Path(__file__).resolve().parents[2]api_root = repo_root / "src" / "free_claude_code" / "api"- admin_config_root = api_root / "admin_config"+ config_root = repo_root / "src" / "free_claude_code" / "config"+ admin_config_root = config_root / "admin"assert not (api_root / "admin_config.py").exists()+ assert not (api_root / "admin_config").exists()for filename in {"__init__.py","manifest.py",@@ -550,10 +647,9 @@ def test_admin_config_uses_package_owners_and_catalog_manifest() -> None:routes_imports = set(_imports_from(api_root / "admin_routes.py", repo_root))assert "free_claude_code.api.admin_config" not in routes_importsfor expected in {- "free_claude_code.api.admin_config.manifest",- "free_claude_code.api.admin_config.persistence",- "free_claude_code.api.admin_config.status",- "free_claude_code.api.admin_config.values",+ "free_claude_code.config.admin.manifest",+ "free_claude_code.config.admin.persistence",+ "free_claude_code.config.admin.values",}:assert expected in routes_imports@@ -636,8 +732,9 @@ def test_messaging_conversation_state_uses_package_owners() -> None:assert offenders == []runtime_text = (- repo_root / "src" / "free_claude_code" / "api" / "runtime.py"+ repo_root / "src" / "free_claude_code" / "runtime" / "application.py").read_text(encoding="utf-8")+ workflow_text = (messaging_root / "workflow.py").read_text(encoding="utf-8")for removed_api in {"get_all_trees","get_node_mapping",@@ -645,6 +742,7 @@ def test_messaging_conversation_state_uses_package_owners() -> None:"TreeQueueManager.from_dict",}:assert removed_api not in runtime_text+ assert removed_api not in workflow_textdef test_messaging_workflow_uses_split_runtime_owners() -> None:@@ -889,6 +987,7 @@ def _text_occurrences(repo_root: Path, needle: str) -> list[str]:repo_root / "src" / "free_claude_code" / "core",repo_root / "src" / "free_claude_code" / "messaging",repo_root / "src" / "free_claude_code" / "providers",+ repo_root / "src" / "free_claude_code" / "runtime",repo_root / "smoke",repo_root / "tests",repo_root / ".env.example",diff --git a/tests/messaging/test_restart_reply_restore.py b/tests/messaging/test_restart_reply_restore.pyindex 52bcf285..c8396a07 100644--- a/tests/messaging/test_restart_reply_restore.py+++ b/tests/messaging/test_restart_reply_restore.py@@ -34,13 +34,7 @@ async def test_reply_to_old_status_message_after_restore_routes_to_parent(# "Restart": new store instance loads from disk, and we restore TreeQueueManager.store2 = SessionStore(storage_path=str(store_path))handler2 = MessagingWorkflow(mock_platform, mock_cli_manager, store2)- handler2.replace_tree_queue(- TreeQueueManager.from_snapshot(- store2.load_conversation_snapshot(),- queue_update_callback=handler2.update_queue_positions,- node_started_callback=handler2.mark_node_processing,- )- )+ handler2.restore()# Prevent background task scheduling; we only want to validate routing/tree mutation.mock_platform.queue_send_message = AsyncMock(return_value="status_reply")@@ -87,13 +81,7 @@ async def test_save_tree_persists_status_message_mapping_without_manual_registerstore2 = SessionStore(storage_path=str(store_path))handler2 = MessagingWorkflow(mock_platform, mock_cli_manager, store2)- handler2.replace_tree_queue(- TreeQueueManager.from_snapshot(- store2.load_conversation_snapshot(),- queue_update_callback=handler2.update_queue_positions,- node_started_callback=handler2.mark_node_processing,- )- )+ handler2.restore()mock_platform.queue_send_message = AsyncMock(return_value="status_reply")reply = IncomingMessage(@@ -170,3 +158,17 @@ async def test_reply_clear_purges_removed_status_mapping_from_persisted_store(assert restored_tree_queue.get_tree_for_node("root_status") is not Noneassert restored_tree_queue.get_tree_for_node("child") is Noneassert restored_tree_queue.get_tree_for_node("child_status") is None+++def test_workflow_close_flushes_owned_session_store(+ mock_platform, mock_cli_manager, mock_session_store+) -> None:+ workflow = MessagingWorkflow(+ mock_platform,+ mock_cli_manager,+ mock_session_store,+ )++ workflow.close()++ mock_session_store.flush_pending_save.assert_called_once()diff --git a/tests/providers/test_model_validation.py b/tests/providers/test_model_validation.pyindex ed13a571..3b3d2f3d 100644--- a/tests/providers/test_model_validation.py+++ b/tests/providers/test_model_validation.py@@ -21,7 +21,9 @@ from free_claude_code.providers.nvidia_nim import NvidiaNimProviderfrom free_claude_code.providers.ollama import OllamaProviderfrom free_claude_code.providers.open_router import OpenRouterProviderfrom free_claude_code.providers.runtime import ProviderRuntime+from free_claude_code.providers.runtime.model_cache import ProviderModelCachefrom free_claude_code.providers.wafer import WaferProvider+from free_claude_code.runtime.provider_manager import ProviderRuntimeManagerdef _settings(@@ -52,6 +54,17 @@ def _settings()+def _manager(+ settings: Settings,+ providers: dict[str, BaseProvider] | None = None,+) -> ProviderRuntimeManager:+ providers = providers or {}+ return ProviderRuntimeManager(+ settings,+ runtime_factory=lambda snapshot: ProviderRuntime(snapshot, dict(providers)),+ )++def _response(status_code: int, payload: object) -> httpx.Response:return httpx.Response(status_code,@@ -341,7 +354,7 @@ class FakeProvider(BaseProvider):@pytest.mark.asyncioasync def test_runtime_validation_succeeds_for_all_configured_models() -> None:settings = _settings(model_opus="open_router/anthropic/claude-opus")- runtime = ProviderRuntime(+ runtime = _manager(settings,{"nvidia_nim": FakeProvider(frozenset({"nim-model"})),@@ -360,7 +373,7 @@ async def test_runtime_validation_succeeds_for_all_configured_models() -> None:@pytest.mark.asyncioasync def test_runtime_validation_reports_missing_model_with_sources() -> None:settings = _settings(model_sonnet="nvidia_nim/nim-model")- runtime = ProviderRuntime(+ runtime = _manager(settings,{"nvidia_nim": FakeProvider(frozenset({"different-model"}))},)@@ -378,7 +391,7 @@ async def test_runtime_validation_reports_missing_model_with_sources() -> None:@pytest.mark.asyncioasync def test_runtime_validation_aggregates_multiple_failures() -> None:settings = _settings(model_opus="open_router/anthropic/claude-opus")- runtime = ProviderRuntime(+ runtime = _manager(settings,{"nvidia_nim": FakeProvider(frozenset({"different-model"})),@@ -405,7 +418,7 @@ async def test_runtime_validation_queries_providers_concurrently() -> None:nim_started = asyncio.Event()router_started = asyncio.Event()settings = _settings(model_opus="open_router/anthropic/claude-opus")- runtime = ProviderRuntime(+ runtime = _manager(settings,{"nvidia_nim": FakeProvider(@@ -432,7 +445,7 @@ async def test_runtime_refresh_model_list_cache_uses_configured_remote_keys_and_model="lmstudio/local-qwen",open_router_api_key="open-router-key",)- runtime = ProviderRuntime(+ runtime = _manager(settings,{"open_router": FakeProvider(frozenset({"anthropic/claude-sonnet"})),@@ -455,11 +468,14 @@ async def test_runtime_refresh_model_list_cache_keeps_prior_cache_on_failure() -model="nvidia_nim/cached-model",nvidia_nim_api_key="nim-key",)- runtime = ProviderRuntime(+ runtime = _manager(settings,{"nvidia_nim": FakeProvider(error=RuntimeError("upstream down"))},)- runtime.cache_model_ids("nvidia_nim", {"cached-model"})+ runtime.cache_model_infos(+ "nvidia_nim",+ {ProviderModelInfo("cached-model")},+ )await runtime.refresh_model_list_cache()@@ -467,8 +483,8 @@ async def test_runtime_refresh_model_list_cache_keeps_prior_cache_on_failure() -def test_runtime_metadata_cache_exposes_ids_and_prefixed_infos() -> None:- runtime = ProviderRuntime(_settings())- runtime.cache_model_infos(+ cache = ProviderModelCache()+ cache.cache_model_infos("open_router",{ProviderModelInfo("reasoning-model", supports_thinking=True),@@ -476,36 +492,36 @@ def test_runtime_metadata_cache_exposes_ids_and_prefixed_infos() -> None:},)- assert runtime.cached_model_ids() == {+ assert cache.cached_model_ids() == {"open_router": frozenset({"reasoning-model", "plain-model"})}assert (- runtime.cached_model_supports_thinking("open_router", "reasoning-model") is True+ cache.cached_model_supports_thinking("open_router", "reasoning-model") is True)- assert runtime.cached_model_supports_thinking("open_router", "plain-model") is False- assert runtime.cached_prefixed_model_infos() == (+ assert cache.cached_model_supports_thinking("open_router", "plain-model") is False+ assert cache.cached_prefixed_model_infos() == (ProviderModelInfo("open_router/plain-model", supports_thinking=False),ProviderModelInfo("open_router/reasoning-model", supports_thinking=True),)def test_runtime_model_id_cache_keeps_unknown_thinking_support() -> None:- runtime = ProviderRuntime(_settings())- runtime.cache_model_ids("open_router", {"plain-model"})+ cache = ProviderModelCache()+ cache.cache_model_ids("open_router", {"plain-model"})- assert runtime.cached_model_ids() == {"open_router": frozenset({"plain-model"})}- assert runtime.cached_model_supports_thinking("open_router", "plain-model") is None- assert runtime.cached_prefixed_model_infos() == (+ assert cache.cached_model_ids() == {"open_router": frozenset({"plain-model"})}+ assert cache.cached_model_supports_thinking("open_router", "plain-model") is None+ assert cache.cached_prefixed_model_infos() == (ProviderModelInfo("open_router/plain-model", supports_thinking=None),)def test_runtime_cached_prefixed_model_refs_are_deterministic() -> None:- runtime = ProviderRuntime(_settings())- runtime.cache_model_ids("deepseek", {"deepseek-chat"})- runtime.cache_model_ids("open_router", {"z-model", "a-model"})+ cache = ProviderModelCache()+ cache.cache_model_ids("deepseek", {"deepseek-chat"})+ cache.cache_model_ids("open_router", {"z-model", "a-model"})- assert runtime.cached_prefixed_model_refs() == (+ assert cache.cached_prefixed_model_refs() == ("open_router/a-model","open_router/z-model","deepseek/deepseek-chat",diff --git a/tests/runtime/test_application_runtime.py b/tests/runtime/test_application_runtime.pynew file mode 100644index 00000000..e8c04d38--- /dev/null+++ b/tests/runtime/test_application_runtime.py@@ -0,0 +1,206 @@+from unittest.mock import AsyncMock, patch++import pytest++from free_claude_code.config.admin.persistence import PreparedAdminUpdate+from free_claude_code.config.settings import Settings+from free_claude_code.providers.runtime import ProviderRuntime+from free_claude_code.runtime.application import ApplicationRuntime+from free_claude_code.runtime.provider_manager import ProviderRuntimeManager+++class TrackingRuntime(ProviderRuntime):+ def __init__(self, settings: Settings) -> None:+ super().__init__(settings)+ self.cleanup_calls = 0++ async def cleanup(self) -> None:+ self.cleanup_calls += 1+ await super().cleanup()+++class TrackingFactory:+ def __init__(self) -> None:+ self.runtimes: list[TrackingRuntime] = []+ self.fail = False+ self.events: list[str] = []++ def __call__(self, settings: Settings) -> ProviderRuntime:+ self.events.append(f"construct:{settings.model}")+ if self.fail:+ raise RuntimeError("candidate failed")+ runtime = TrackingRuntime(settings)+ self.runtimes.append(runtime)+ return runtime+++def _settings(model: str, *, port: int = 8082) -> Settings:+ return Settings().model_copy(update={"model": model, "port": port})+++def _prepared(+ settings: Settings,+ tmp_path,+ *,+ pending_fields: tuple[str, ...] = (),+) -> PreparedAdminUpdate:+ return PreparedAdminUpdate(+ target_values={"MODEL": settings.model},+ settings=settings,+ errors=(),+ pending_fields=pending_fields,+ path=tmp_path / ".env",+ )+++def _applied_response(pending_fields: tuple[str, ...] = ()) -> dict[str, object]:+ return {+ "applied": True,+ "valid": True,+ "errors": [],+ "env_preview": "MODEL=updated\n",+ "path": ".env",+ "pending_fields": list(pending_fields),+ }+++async def test_provider_apply_constructs_before_commit_then_publishes(tmp_path) -> None:+ factory = TrackingFactory()+ manager = ProviderRuntimeManager(+ _settings("nvidia_nim/old"),+ runtime_factory=factory,+ )+ runtime = ApplicationRuntime(manager)+ prepared = _prepared(_settings("nvidia_nim/new"), tmp_path)+ factory.events.clear()++ def commit(_prepared_update: PreparedAdminUpdate) -> dict[str, object]:+ factory.events.append("commit")+ assert manager.current_generation_id == 1+ return _applied_response()++ with (+ patch(+ "free_claude_code.runtime.application.prepare_admin_update",+ return_value=prepared,+ ),+ patch(+ "free_claude_code.runtime.application.commit_prepared_admin_update",+ side_effect=commit,+ ),+ ):+ result = await runtime.apply_admin_config({"MODEL": "nvidia_nim/new"})++ assert factory.events == ["construct:nvidia_nim/new", "commit"]+ assert manager.current_generation_id == 2+ assert manager.current_settings().model == "nvidia_nim/new"+ assert result["restart"] == {+ "required": False,+ "automatic": False,+ "admin_url": None,+ "fields": [],+ }+ await manager.close()+++async def test_candidate_failure_never_commits_and_preserves_current(tmp_path) -> None:+ factory = TrackingFactory()+ manager = ProviderRuntimeManager(+ _settings("nvidia_nim/old"),+ runtime_factory=factory,+ )+ runtime = ApplicationRuntime(manager)+ prepared = _prepared(_settings("nvidia_nim/new"), tmp_path)+ factory.fail = True++ with (+ patch(+ "free_claude_code.runtime.application.prepare_admin_update",+ return_value=prepared,+ ),+ patch(+ "free_claude_code.runtime.application.commit_prepared_admin_update"+ ) as commit,+ pytest.raises(RuntimeError, match="candidate failed"),+ ):+ await runtime.apply_admin_config({"MODEL": "nvidia_nim/new"})++ commit.assert_not_called()+ assert manager.current_generation_id == 1+ assert manager.current_settings().model == "nvidia_nim/old"+ await manager.close()+++async def test_persistence_failure_closes_candidate_and_preserves_current(+ tmp_path,+) -> None:+ factory = TrackingFactory()+ manager = ProviderRuntimeManager(+ _settings("nvidia_nim/old"),+ runtime_factory=factory,+ )+ runtime = ApplicationRuntime(manager)+ prepared = _prepared(_settings("nvidia_nim/new"), tmp_path)++ with (+ patch(+ "free_claude_code.runtime.application.prepare_admin_update",+ return_value=prepared,+ ),+ patch(+ "free_claude_code.runtime.application.commit_prepared_admin_update",+ side_effect=OSError("disk full"),+ ),+ pytest.raises(OSError, match="disk full"),+ ):+ await runtime.apply_admin_config({"MODEL": "nvidia_nim/new"})++ assert manager.current_generation_id == 1+ assert factory.runtimes[0].cleanup_calls == 0+ assert factory.runtimes[1].cleanup_calls == 1+ await manager.close()+++async def test_restart_required_apply_commits_without_hot_publication(tmp_path) -> None:+ factory = TrackingFactory()+ manager = ProviderRuntimeManager(+ _settings("nvidia_nim/old"),+ runtime_factory=factory,+ )+ restart = AsyncMock()+ runtime = ApplicationRuntime(manager, restart_callback=restart)+ prepared = _prepared(+ _settings("nvidia_nim/old", port=9090),+ tmp_path,+ pending_fields=("PORT",),+ )++ with (+ patch(+ "free_claude_code.runtime.application.prepare_admin_update",+ return_value=prepared,+ ),+ patch(+ "free_claude_code.runtime.application.commit_prepared_admin_update",+ return_value=_applied_response(("PORT",)),+ ) as commit,+ ):+ result = await runtime.apply_admin_config({"PORT": "9090"})++ commit.assert_called_once_with(prepared)+ assert manager.current_generation_id == 1+ assert len(factory.runtimes) == 1+ assert result["restart"] == {+ "required": True,+ "automatic": True,+ "admin_url": "http://127.0.0.1:9090/admin",+ "fields": ["PORT"],+ }+ restart.assert_not_awaited()+ await runtime.request_restart()+ restart.assert_awaited_once()+ await manager.close()diff --git a/tests/runtime/test_provider_manager.py b/tests/runtime/test_provider_manager.pynew file mode 100644index 00000000..a0a58933--- /dev/null+++ b/tests/runtime/test_provider_manager.py@@ -0,0 +1,281 @@+import asyncio+from typing import cast+from unittest.mock import AsyncMock, MagicMock, patch++import pytest++from free_claude_code.config.settings import Settings+from free_claude_code.providers.base import BaseProvider+from free_claude_code.providers.exceptions import ServiceUnavailableError+from free_claude_code.providers.model_listing import ProviderModelInfo+from free_claude_code.providers.runtime import ProviderRuntime+from free_claude_code.runtime.provider_manager import ProviderRuntimeManager+++class FakeRuntime(ProviderRuntime):+ def __init__(self, settings: Settings) -> None:+ self.settings = settings+ self.cleanup_calls = 0+ self.cleanup_error: Exception | None = None+ self.provider = MagicMock()+ self.provider.list_model_infos = AsyncMock(return_value=frozenset())++ def is_cached(self, provider_id: str) -> bool:+ return provider_id == "cached"++ def resolve_provider(self, provider_id: str) -> BaseProvider:+ return cast(BaseProvider, self.provider)++ async def cleanup(self) -> None:+ self.cleanup_calls += 1+ if self.cleanup_error is not None:+ raise self.cleanup_error+++class RuntimeFactory:+ def __init__(self) -> None:+ self.runtimes: list[FakeRuntime] = []+ self.error: Exception | None = None++ def __call__(self, settings: Settings) -> ProviderRuntime:+ if self.error is not None:+ raise self.error+ runtime = FakeRuntime(settings)+ self.runtimes.append(runtime)+ return runtime+++def _settings(model: str) -> Settings:+ return Settings().model_copy(update={"model": model})+++async def test_startup_generation_lease_and_shutdown_close_exactly_once() -> None:+ factory = RuntimeFactory()+ settings = _settings("nvidia_nim/one")+ manager = ProviderRuntimeManager(settings, runtime_factory=factory)++ lease = await manager.acquire()++ assert lease.generation_id == 1+ assert lease.settings is settings+ assert lease.is_provider_cached("cached") is True+ assert lease.resolve_provider("nvidia_nim") is factory.runtimes[0].provider+ await lease.release()+ await lease.release()+ await manager.close()+ await manager.close()++ assert factory.runtimes[0].cleanup_calls == 1+ with pytest.raises(ServiceUnavailableError, match="shutting down"):+ await manager.acquire()+++async def test_replacement_keeps_leased_generation_open_until_final_release() -> None:+ factory = RuntimeFactory()+ first_settings = _settings("nvidia_nim/one")+ second_settings = _settings("nvidia_nim/two")+ manager = ProviderRuntimeManager(first_settings, runtime_factory=factory)+ old_lease = await manager.acquire()+ committed: list[str] = []++ generation_id = await manager.replace(+ second_settings,+ commit=lambda: committed.append("persisted"),+ )+ new_lease = await manager.acquire()++ assert generation_id == 2+ assert committed == ["persisted"]+ assert new_lease.generation_id == 2+ assert new_lease.settings is second_settings+ assert factory.runtimes[0].cleanup_calls == 0+ await new_lease.release()+ await old_lease.release()+ assert factory.runtimes[0].cleanup_calls == 1+ await manager.close()+ assert factory.runtimes[1].cleanup_calls == 1+++async def test_replacement_closes_unleased_generation_immediately() -> None:+ factory = RuntimeFactory()+ manager = ProviderRuntimeManager(+ _settings("nvidia_nim/one"),+ runtime_factory=factory,+ )++ await manager.replace(+ _settings("nvidia_nim/two"),+ commit=lambda: None,+ )++ assert factory.runtimes[0].cleanup_calls == 1+ await manager.close()+++async def test_candidate_construction_failure_preserves_current_generation() -> None:+ factory = RuntimeFactory()+ manager = ProviderRuntimeManager(+ _settings("nvidia_nim/one"),+ runtime_factory=factory,+ )+ factory.error = RuntimeError("cannot construct")++ with pytest.raises(RuntimeError, match="cannot construct"):+ await manager.replace(+ _settings("nvidia_nim/two"),+ commit=lambda: None,+ )++ assert manager.current_generation_id == 1+ assert manager.current_settings().model == "nvidia_nim/one"+ assert factory.runtimes[0].cleanup_calls == 0+ await manager.close()+++async def test_persistence_failure_closes_candidate_and_preserves_current() -> None:+ factory = RuntimeFactory()+ manager = ProviderRuntimeManager(+ _settings("nvidia_nim/one"),+ runtime_factory=factory,+ )++ def fail_commit() -> None:+ raise OSError("disk full")++ with pytest.raises(OSError, match="disk full"):+ await manager.replace(+ _settings("nvidia_nim/two"),+ commit=fail_commit,+ )++ assert manager.current_generation_id == 1+ assert factory.runtimes[0].cleanup_calls == 0+ assert factory.runtimes[1].cleanup_calls == 1+ await manager.close()+++async def test_concurrent_replacements_are_serialized_in_call_order() -> None:+ factory = RuntimeFactory()+ manager = ProviderRuntimeManager(+ _settings("nvidia_nim/one"),+ runtime_factory=factory,+ )+ first_entered = asyncio.Event()+ release_first = asyncio.Event()+ cancel_calls = 0+ original_cancel = manager._cancel_refresh++ async def controlled_cancel() -> None:+ nonlocal cancel_calls+ cancel_calls += 1+ if cancel_calls == 1:+ first_entered.set()+ await release_first.wait()+ await original_cancel()++ with patch.object(manager, "_cancel_refresh", side_effect=controlled_cancel):+ first = asyncio.create_task(+ manager.replace(+ _settings("nvidia_nim/two"),+ commit=lambda: None,+ )+ )+ await first_entered.wait()+ second = asyncio.create_task(+ manager.replace(+ _settings("nvidia_nim/three"),+ commit=lambda: None,+ )+ )+ await asyncio.sleep(0)+ assert len(factory.runtimes) == 1+ assert not second.done()+ release_first.set()+ assert await asyncio.gather(first, second) == [2, 3]++ assert manager.current_settings().model == "nvidia_nim/three"+ assert [runtime.cleanup_calls for runtime in factory.runtimes[:2]] == [1, 1]+ await manager.close()+++async def test_shutdown_waits_for_active_lease_then_rejects_new_work() -> None:+ factory = RuntimeFactory()+ manager = ProviderRuntimeManager(+ _settings("nvidia_nim/one"),+ runtime_factory=factory,+ )+ lease = await manager.acquire()++ close_task = asyncio.create_task(manager.close())+ await asyncio.sleep(0)++ assert not close_task.done()+ with pytest.raises(ServiceUnavailableError, match="shutting down"):+ await manager.acquire()+ await lease.release()+ await close_task+ assert factory.runtimes[0].cleanup_calls == 1+++async def test_application_catalog_survives_generation_replacement() -> None:+ factory = RuntimeFactory()+ manager = ProviderRuntimeManager(+ _settings("open_router/one"),+ runtime_factory=factory,+ )+ manager.cache_model_infos(+ "open_router",+ {ProviderModelInfo("persisted", supports_thinking=True)},+ )++ await manager.replace(+ _settings("open_router/two"),+ commit=lambda: None,+ )++ assert manager.cached_model_ids() == {"open_router": frozenset({"persisted"})}+ assert manager.cached_model_supports_thinking("open_router", "persisted") is True+ await manager.close()+++async def test_generation_lifecycle_traces_contain_minimal_correlation_fields() -> None:+ factory = RuntimeFactory()++ with patch("free_claude_code.runtime.provider_manager.trace_event") as trace:+ manager = ProviderRuntimeManager(+ _settings("nvidia_nim/one"),+ runtime_factory=factory,+ )+ lease = await manager.acquire()+ await manager.replace(+ _settings("nvidia_nim/two"),+ commit=lambda: None,+ reason="test_replace",+ )+ await lease.release()+ await manager.close()++ events = [call.kwargs for call in trace.call_args_list]+ names = [event["event"] for event in events]+ assert names == [+ "provider_generation.published",+ "provider_generation.published",+ "provider_generation.retired",+ "provider_generation.closed",+ "provider_generation.retired",+ "provider_generation.closed",+ ]+ assert events[1]["generation_id"] == 2+ assert events[1]["previous_generation_id"] == 1+ assert events[1]["reason"] == "test_replace"+ assert events[2]["active_leases"] == 1+ assert events[3]["forced"] is Falsediff --git a/uv.lock b/uv.lockindex e4664f57..958fd0b7 100644--- a/uv.lock+++ b/uv.lock@@ -561,7 +561,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "3.4.16"+version = "3.4.17"source = { editable = "." }dependencies = [{ name = "aiohttp" },