Skip to content

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.md
index 1308740e..b2b827a0 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -35,7 +35,8 @@ flowchart LR
ProxyAPI --> 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 LR
The 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/session
management, 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 base
classes, upstream transports, rate limiting, model listing, and concrete
provider 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 command
dependencies, and tree queue internals live in separate modules so new
behavior 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. Keep
provider 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 validation
depend 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 and
managed env writes. Provider credential, local URL, proxy, and display-name
metadata 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 source
loading, value presentation, validation, persistence, and provider status into
separate 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 @@ sequenceDiagram
participant Handler as ProductHandler
participant Router as ModelRouter
participant Exec as ProviderExecution
- participant Runtime as ProviderRuntime
+ participant Manager as ProviderRuntimeManager
+ participant Lease as ProviderGenerationLease
+ participant Runtime as ProviderRuntimeGeneration
participant Provider
Client->>Route: POST /v1/messages
Route->>Route: require_api_key
+ Route->>Manager: acquire current generation
+ Manager-->>Route: Lease(settings, provider resolver)
Route->>Handler: create message
Handler->>Router: resolve model and thinking
Handler->>Handler: server tools or optimizations
Handler->>Exec: stream routed request
- Exec->>Runtime: resolve provider
+ Exec->>Lease: resolve provider
+ Lease->>Runtime: cached or new provider
Runtime->>Provider: cached or new provider
Exec->>Provider: preflight_stream
Exec->>Provider: stream_response
Provider-->>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. Names
containing `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` fetches
the 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 the
catalog. 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 is
insufficient.
4. Implement the provider under [src/free_claude_code/providers/](src/free_claude_code/providers/) using the appropriate
shared 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 add
provider 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 be
diff --git a/pyproject.toml b/pyproject.toml
index 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.py
index 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.py
index 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.py
index 81970fe2..553e8c61 100644
--- a/smoke/lib/server.py
+++ b/smoke/lib/server.py
@@ -4,7 +4,7 @@ import os
import socket
import subprocess
import time
-from collections.abc import Iterator
+from collections.abc import Iterable, Iterator
from contextlib import contextmanager, suppress
from dataclasses import dataclass
from 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.py
new file mode 100644
index 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__.py
index 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__.py
deleted file mode 100644
index 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.py
index 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 inspect
import ipaddress
from pathlib import Path
from typing import Any
from urllib.parse import urlsplit
import httpx
-from fastapi import APIRouter, BackgroundTasks, HTTPException, Request
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request
from fastapi.responses import FileResponse
from 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 ApiServices
router = 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.py
index 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 os
import traceback
-from contextlib import asynccontextmanager
-from pathlib import Path
from typing import Any
from fastapi import FastAPI, Request
@@ -11,11 +8,7 @@ from fastapi.exception_handlers import request_validation_exception_handler
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from 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_settings
from 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 ProviderError
from .admin_routes import router as admin_router
+from .ports import ApiServices
from .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_message
from .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 routes
app.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: Any
try:
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 response
return 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.py
index 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 secrets
from fastapi import Depends, HTTPException, Request
from loguru import logger
-from starlette.applications import Starlette
from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
from free_claude_code.config.settings import Settings
-from free_claude_code.config.settings import get_settings as _get_settings
from free_claude_code.core.anthropic import get_user_facing_error_message
from free_claude_code.providers.base import BaseProvider
from 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 exc
except 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 -> allow
return
header = (
@@ -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 Authorization
token = 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 names
if 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.py
index 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 = settings
self._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.py
index 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 = settings
self._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.py
index 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_refs
from 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_id
from .models.responses import ModelResponse, ModelsListResponse
+from .ports import RequestRuntimePort
DISCOVERED_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.py
index 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 logger
from free_claude_code.config.model_refs import parse_model_name, parse_provider_type
from free_claude_code.config.provider_ids import SUPPORTED_PROVIDER_IDS
from 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_id
from .models.anthropic import MessagesRequest, TokenCountRequest
diff --git a/src/free_claude_code/api/ports.py b/src/free_claude_code/api/ports.py
new file mode 100644
index 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: SessionControlPort
diff --git a/src/free_claude_code/api/provider_execution.py b/src/free_claude_code/api/provider_execution.py
index 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 = settings
self._provider_getter = provider_getter
self._token_counter = token_counter
+ self._generation_id = generation_id
def 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_id
trace_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.py
index 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_checkable
from 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.py
index 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 Settings
from free_claude_code.core.anthropic import get_token_count
from 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, TokenCountHandler
from .model_catalog import build_models_list_response
from .models.anthropic import MessagesRequest, TokenCountRequest
from .models.openai_responses import OpenAIResponsesRequest
from .models.responses import ModelsListResponse
+from .ports import ApiServices, RequestRuntimeLease
from .request_ids import get_request_id
+from .response_streams import bind_response_lifetime
router = 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 0
trace_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.py
deleted file mode 100644
index 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.py
index 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 Path
import 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_app
from free_claude_code.cli.launchers.common import preflight_proxy
from 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_url
from free_claude_code.config.settings import Settings, get_settings
+from free_claude_code.runtime.bootstrap import build_asgi_app
SERVER_GRACEFUL_SHUTDOWN_SECONDS = 5
@@ -93,9 +93,7 @@ def _run_supervised_server(settings: Settings, *, open_admin_browser: bool) -> b
if 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.py
index 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 os
import sys
from collections.abc import Mapping, Sequence
-from free_claude_code.api.admin_urls import local_proxy_root_url
from 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_url
from free_claude_code.config.settings import get_settings
from .common import preflight_proxy, resolve_client_binary, run_client_process
diff --git a/src/free_claude_code/cli/launchers/codex.py b/src/free_claude_code/cli/launchers/codex.py
index 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 sys
from collections.abc import Mapping, Sequence
from urllib.request import Request, urlopen
-from free_claude_code.api.admin_urls import local_proxy_root_url
from free_claude_code.config.paths import codex_model_catalog_path
+from free_claude_code.config.server_urls import local_proxy_root_url
from free_claude_code.config.settings import Settings, get_settings
from .codex_model_catalog import build_codex_model_catalog, write_codex_model_catalog
diff --git a/src/free_claude_code/cli/launchers/codex_model_catalog.py b/src/free_claude_code/cli/launchers/codex_model_catalog.py
index 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 dataclass
from pathlib import Path
from 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_IDS
SUPPORTED_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__.py
new file mode 100644
index 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.py
similarity index 99%
rename from src/free_claude_code/api/admin_config/manifest.py
rename to src/free_claude_code/config/admin/manifest.py
index 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 Iterable
from dataclasses import dataclass
diff --git a/src/free_claude_code/api/admin_config/persistence.py b/src/free_claude_code/config/admin/persistence.py
similarity index 62%
rename from src/free_claude_code/api/admin_config/persistence.py
rename to src/free_claude_code/config/admin/persistence.py
index 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 os
from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
from typing import Any
from free_claude_code.config.paths import managed_env_path
+from free_claude_code.config.settings import Settings
from .manifest import FIELD_BY_KEY, FIELDS, SECTIONS, ConfigFieldSpec
from .sources import dotenv_values_from_file, is_locked_source, template_values
-from .validation import validate_values
+from .validation import settings_from_values
from .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.path
path.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.py
similarity index 99%
rename from src/free_claude_code/api/admin_config/provider_manifest.py
rename to src/free_claude_code/config/admin/provider_manifest.py
index 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 Any
diff --git a/src/free_claude_code/api/admin_config/sources.py b/src/free_claude_code/config/admin/sources.py
similarity index 100%
rename from src/free_claude_code/api/admin_config/sources.py
rename to src/free_claude_code/config/admin/sources.py
diff --git a/src/free_claude_code/api/admin_config/status.py b/src/free_claude_code/config/admin/status.py
similarity index 92%
rename from src/free_claude_code/api/admin_config/status.py
rename to src/free_claude_code/config/admin/status.py
index 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 FIELDS
def 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.py
similarity index 71%
rename from src/free_claude_code/api/admin_config/validation.py
rename to src/free_claude_code/config/admin/validation.py
index 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 Mapping
from typing import Any
@@ -13,6 +13,15 @@ from .manifest import FIELDS, field_input_key
def 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.py
similarity index 100%
rename from src/free_claude_code/api/admin_config/values.py
rename to src/free_claude_code/config/admin/values.py
diff --git a/src/free_claude_code/api/admin_urls.py b/src/free_claude_code/config/server_urls.py
similarity index 77%
rename from src/free_claude_code/api/admin_urls.py
rename to src/free_claude_code/config/server_urls.py
index 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.py
similarity index 96%
rename from src/free_claude_code/api/gateway_model_ids.py
rename to src/free_claude_code/core/gateway_model_ids.py
index 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 dataclass
diff --git a/src/free_claude_code/messaging/workflow.py b/src/free_claude_code/messaging/workflow.py
index 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_queue
self._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.py
index 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 asyncio
from collections.abc import Callable
-from contextlib import suppress
from loguru import logger
@@ -53,7 +52,6 @@ class ProviderModelDiscovery:
self._settings = settings
self._provider_resolver = provider_resolver
self._model_cache = model_cache
- self._refresh_task: asyncio.Task[None] | None = None
async 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.py
index 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 MutableMapping
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
from .cache import ProviderCache
-from .discovery import ProviderModelDiscovery
-from .model_cache import ProviderModelCache
-from .validation import ConfiguredModelValidator
class 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 = settings
self._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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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"})
+ return
diff --git a/src/free_claude_code/runtime/bootstrap.py b/src/free_claude_code/runtime/bootstrap.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 manager
diff --git a/tests/api/test_admin.py b/tests/api/test_admin.py
index 5f65930c..fb7a465d 100644
--- a/tests/api/test_admin.py
+++ b/tests/api/test_admin.py
@@ -4,10 +4,10 @@ from unittest.mock import patch
import httpx
from 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_url
from free_claude_code.config.settings import Settings
+from tests.api.support import create_test_app
def _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 == 200
remote_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_pat
env_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_pat
def 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_pat
def 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_pat
def 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_path
def 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, tmp
def 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_p
def 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, tmp
def 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.py
index 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, patch
import pytest
from fastapi.testclient import TestClient
-from free_claude_code.api.app import create_app
from 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 provider
mock_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_client
diff --git a/tests/api/test_app_lifespan_and_errors.py b/tests/api/test_app_lifespan_and_errors.py
index 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 cast
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
@@ -9,56 +8,23 @@ from fastapi import FastAPI
from fastapi.testclient import TestClient
from 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 logged
def 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 blob
assert "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 blob
assert "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_path
diff --git a/tests/api/test_auth.py b/tests/api/test_auth.py
index 4e0c4e55..6e94f2a2 100644
--- a/tests/api/test_auth.py
+++ b/tests/api/test_auth.py
@@ -2,11 +2,11 @@ from unittest.mock import patch
from fastapi.testclient import TestClient
-from free_claude_code.api.app import create_app
from free_claude_code.api.dependencies import get_settings
from 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.py
index 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 cast
from unittest.mock import MagicMock, patch
import pytest
-from fastapi import HTTPException
-from starlette.applications import Starlette
-from starlette.datastructures import State
+from fastapi import HTTPException, Request
from 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 == 503
assert "OPENROUTER_API_KEY" in exc_info.value.detail
assert "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.py
index 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_settings
from free_claude_code.config.settings import Settings
from 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_app
def _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 == 200
data = 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") == 1
assert 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_aliases
assert 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 == 200
ids = [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 == 200
ids = [item["id"] for item in response.json()["data"]]
assert "anthropic/open_router/plain-model" not in ids
assert 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 == 200
ids = [item["id"] for item in response.json()["data"]]
assert "anthropic/wafer/DeepSeek-V4-Pro" in ids
assert "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 == 200
ids = [item["id"] for item in response.json()["data"]]
diff --git a/tests/api/test_openai_responses.py b/tests/api/test_openai_responses.py
index 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, patch
import pytest
from fastapi.testclient import TestClient
-from free_claude_code.api.app import create_app
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
from free_claude_code.core.anthropic.streaming import format_sse_event
from free_claude_code.providers.exceptions import RateLimitError
+from tests.api.support import create_test_app
class FakeProvider:
@@ -50,11 +50,9 @@ class PostStartFailingProvider(FakeProvider):
@pytest.fixture
def 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() -> None
def 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() -> None
provider = 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() -> None
def 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() -> None
def 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.py
index 45524065..37f54d7a 100644
--- a/tests/api/test_response_streams.py
+++ b/tests/api/test_response_streams.py
@@ -3,12 +3,15 @@
import asyncio
import json
from collections.abc import AsyncGenerator
+from typing import cast
+from unittest.mock import AsyncMock
import pytest
from fastapi.responses import JSONResponse, StreamingResponse
from 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() -> No
events = 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.py
index 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, patch
import pytest
from fastapi.testclient import TestClient
-from free_claude_code.api.app import create_app
from free_claude_code.api.dependencies import get_settings
+from free_claude_code.api.ports import ApiServices, StopResult
from 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 == 200
assert 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 == 200
assert 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.py
index 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 importlib
import logging
-from unittest.mock import MagicMock, patch
+from unittest.mock import patch
import 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.asyncio
async 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 blob
assert "exc_type=RuntimeError" in blob
@pytest.mark.asyncio
async 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 blob
assert "exc_type=ValueError" in blob
@pytest.mark.asyncio
async 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 blob
diff --git a/tests/cli/test_entrypoints.py b/tests/cli/test_entrypoints.py
index 9a6d4855..c241db22 100644
--- a/tests/cli/test_entrypoints.py
+++ b/tests/cli/test_entrypoints.py
@@ -2,6 +2,7 @@
import json
import tomllib
+from collections.abc import Callable
from pathlib import Path
from types import SimpleNamespace
from 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_url
from free_claude_code.cli import entrypoints
+ from free_claude_code.config.server_urls import local_admin_url
settings = _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 True
def 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.py
index 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_KEY
from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
from 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_state
status_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.py
index 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.py
index 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_imports
for 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_text
def 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.py
index 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_register
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()
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 None
assert restored_tree_queue.get_tree_for_node("child") is None
assert 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.py
index 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 NvidiaNimProvider
from free_claude_code.providers.ollama import OllamaProvider
from free_claude_code.providers.open_router import OpenRouterProvider
from free_claude_code.providers.runtime import ProviderRuntime
+from free_claude_code.providers.runtime.model_cache import ProviderModelCache
from free_claude_code.providers.wafer import WaferProvider
+from free_claude_code.runtime.provider_manager import ProviderRuntimeManager
def _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.asyncio
async 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.asyncio
async 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.asyncio
async 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 False
diff --git a/uv.lock b/uv.lock
index 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" },