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

Make managed configuration valid by construction (#1414)

Ali Khokhar80593a0159cf
diff --git a/.env.example b/.env.example
index ae3c6f7f..d5953616 100644
--- a/.env.example
+++ b/.env.example
@@ -1,163 +1,163 @@
# NVIDIA NIM Config
-NVIDIA_NIM_API_KEY=""
+# NVIDIA_NIM_API_KEY=<your-token>
# Azure OpenAI (resource-specific OpenAI v1 Chat Completions endpoint)
-AZURE_OPENAI_API_KEY=""
-AZURE_OPENAI_BASE_URL=""
+# AZURE_OPENAI_API_KEY=<your-token>
+# AZURE_OPENAI_BASE_URL=<provider-base-url>
# OpenRouter Config
-OPENROUTER_API_KEY=""
+# OPENROUTER_API_KEY=<your-token>
# Mistral La Plateforme Config (Experiment plan free tier – rate limits; OpenAI-compatible at api.mistral.ai/v1)
-MISTRAL_API_KEY=""
+# MISTRAL_API_KEY=<your-token>
# Mistral Codestral (separate key from La Plateforme; OpenAI-compatible at codestral.mistral.ai/v1)
-CODESTRAL_API_KEY=""
+# CODESTRAL_API_KEY=<your-token>
# DeepSeek Config (OpenAI-compatible Chat Completions at api.deepseek.com)
-DEEPSEEK_API_KEY=""
+# DEEPSEEK_API_KEY=<your-token>
# Kimi Config (OpenAI-compatible Chat Completions at api.moonshot.ai/v1)
-KIMI_API_KEY=""
+# KIMI_API_KEY=<your-token>
# Kimi Code subscription (OpenAI-compatible Chat Completions at api.kimi.com/coding/v1)
-KIMI_CODE_API_KEY=""
+# KIMI_CODE_API_KEY=<your-token>
# Wafer Config (OpenAI-compatible Chat Completions at pass.wafer.ai/v1)
-WAFER_API_KEY=""
+# WAFER_API_KEY=<your-token>
# MiniMax Config (OpenAI-compatible Chat Completions at api.minimax.io/v1)
-MINIMAX_API_KEY=""
+# MINIMAX_API_KEY=<your-token>
# OpenCode Zen (opencode.ai/zen/v1) and OpenCode Go (opencode.ai/zen/go/v1) share OPENCODE_API_KEY
-OPENCODE_API_KEY=""
+# OPENCODE_API_KEY=<your-token>
# Vercel AI Gateway Config (OpenAI-compatible Chat Completions at ai-gateway.vercel.sh/v1)
-AI_GATEWAY_API_KEY=""
+# AI_GATEWAY_API_KEY=<your-token>
# Amazon Bedrock Mantle (region-specific OpenAI-compatible Chat Completions)
-AWS_BEARER_TOKEN_BEDROCK=""
+# AWS_BEARER_TOKEN_BEDROCK=<your-token>
BEDROCK_BASE_URL="https://bedrock-mantle.us-east-1.api.aws/v1"
# Hugging Face Inference Providers Config (OpenAI-compatible Chat Completions at router.huggingface.co/v1)
-HUGGINGFACE_API_KEY=""
+# HUGGINGFACE_API_KEY=<your-token>
# Cohere Config (OpenAI-compatible Chat Completions at api.cohere.ai/compatibility/v1)
-COHERE_API_KEY=""
+# COHERE_API_KEY=<your-token>
# GitHub Models Config (OpenAI-compatible Chat Completions at models.github.ai/inference)
-GITHUB_MODELS_TOKEN=""
+# GITHUB_MODELS_TOKEN=<your-token>
# Z.ai Config (GLM Coding Plan OpenAI-compatible Chat Completions at api.z.ai/api/coding/paas/v4)
-ZAI_API_KEY=""
+# ZAI_API_KEY=<your-token>
# TokenRouter Config (OpenAI-compatible Chat Completions gateway at api.tokenrouter.com/v1)
-TOKENROUTER_API_KEY=""
+# TOKENROUTER_API_KEY=<your-token>
TOKENROUTER_BASE_URL="https://api.tokenrouter.com/v1"
# NaraRoute Config (OpenAI-compatible Chat Completions gateway at router.bynara.id/v1)
-NARAROUTE_API_KEY=""
+# NARAROUTE_API_KEY=<your-token>
NARAROUTE_BASE_URL="https://router.bynara.id/v1"
# Fireworks AI Config (OpenAI-compatible Chat Completions at api.fireworks.ai/inference/v1)
-FIREWORKS_API_KEY=""
+# FIREWORKS_API_KEY=<your-token>
# Novita AI (OpenAI-compatible Chat Completions at api.novita.ai/openai/v1)
-NOVITA_API_KEY=""
+# NOVITA_API_KEY=<your-token>
# Cloudflare Workers AI Config (OpenAI-compatible Chat Completions at api.cloudflare.com/client/v4/accounts/<id>/ai/v1)
-CLOUDFLARE_API_TOKEN=""
-CLOUDFLARE_ACCOUNT_ID=""
+# CLOUDFLARE_API_TOKEN=<your-token>
+# CLOUDFLARE_ACCOUNT_ID=<value>
# Gemini / Google AI Studio (OpenAI-compatible Chat Completions; see https://ai.google.dev/gemini-api/docs/openai)
-GEMINI_API_KEY=""
+# GEMINI_API_KEY=<your-token>
# Google Vertex AI (uses Application Default Credentials; no API key)
# Local setup: gcloud auth application-default login
-VERTEX_PROJECT_ID=""
+# VERTEX_PROJECT_ID=<value>
VERTEX_LOCATION="global"
# Groq Cloud (OpenAI-compatible Chat Completions; see https://console.groq.com/docs/openai)
-GROQ_API_KEY=""
+# GROQ_API_KEY=<your-token>
# xAI / Grok (OpenAI-compatible Chat Completions at api.x.ai/v1)
-XAI_API_KEY=""
+# XAI_API_KEY=<your-token>
# QwenCloud Token Plan (dedicated sk-sp- key; OpenAI-compatible Chat Completions)
-QWENCLOUD_API_KEY=""
+# QWENCLOUD_API_KEY=<your-token>
# Together AI (OpenAI-compatible Chat Completions at api.together.ai/v1)
-TOGETHER_API_KEY=""
+# TOGETHER_API_KEY=<your-token>
# DeepInfra (OpenAI-compatible Chat Completions at api.deepinfra.com/v1/openai)
-DEEPINFRA_API_KEY=""
+# DEEPINFRA_API_KEY=<your-token>
# SiliconFlow (OpenAI-compatible Chat Completions at api.siliconflow.com/v1)
-SILICONFLOW_API_KEY=""
+# SILICONFLOW_API_KEY=<your-token>
# Nebius Token Factory (OpenAI-compatible Chat Completions at api.tokenfactory.nebius.com/v1)
-NEBIUS_API_KEY=""
+# NEBIUS_API_KEY=<your-token>
# Chutes (OpenAI-compatible Chat Completions at llm.chutes.ai/v1)
-CHUTES_API_KEY=""
+# CHUTES_API_KEY=<your-token>
# Featherless AI (OpenAI-compatible Chat Completions at api.featherless.ai/v1)
-FEATHERLESS_API_KEY=""
+# FEATHERLESS_API_KEY=<your-token>
# Agnes AI (OpenAI-compatible Chat Completions at apihub.agnes-ai.com/v1)
-AGNES_API_KEY=""
+# AGNES_API_KEY=<your-token>
# ZenMux (OpenAI-compatible Chat Completions gateway at zenmux.ai/api/v1)
-ZENMUX_API_KEY=""
+# ZENMUX_API_KEY=<your-token>
# SambaNova Cloud (OpenAI-compatible Chat Completions at api.sambanova.ai/v1)
-SAMBANOVA_API_KEY=""
+# SAMBANOVA_API_KEY=<your-token>
# Kilo.ai Config (OpenAI-compatible Chat Completions gateway at api.kilo.ai/api/gateway)
-KILO_API_KEY=""
+# KILO_API_KEY=<your-token>
# Cerebras Inference (OpenAI-compatible Chat Completions; see https://inference-docs.cerebras.ai/resources/openai)
-CEREBRAS_API_KEY=""
+# CEREBRAS_API_KEY=<your-token>
# Ollama Cloud (direct OpenAI-compatible API at ollama.com/v1)
-OLLAMA_API_KEY=""
+# OLLAMA_API_KEY=<your-token>
# LM Studio Config (local provider, no API key required)
@@ -175,63 +175,63 @@ OLLAMA_BASE_URL="http://localhost:11434"
# All Claude model requests are mapped to these models, plain model is fallback
# Format: provider_type/model/name
# Valid providers: "nvidia_nim" | "openai" | "azure_openai" | "open_router" | "gemini" | "vertex" | "deepseek" | "mistral" | "mistral_codestral" | "opencode_zen" | "opencode_go" | "vercel" | "bedrock" | "huggingface" | "cohere" | "github_models" | "wafer" | "kimi" | "kimi_code" | "minimax" | "cerebras" | "groq" | "xai" | "qwencloud" | "together" | "deepinfra" | "siliconflow" | "nebius" | "chutes" | "featherless" | "agnes" | "zenmux" | "sambanova" | "kilo" | "fireworks" | "novita" | "cloudflare" | "zai" | "ollama_cloud" | "lmstudio" | "llamacpp" | "ollama" | "tokenrouter" | "nararoute"
-MODEL_FABLE=
-MODEL_OPUS=
-MODEL_SONNET=
-MODEL_HAIKU=
+# MODEL_FABLE=<provider/model-id>
+# MODEL_OPUS=<provider/model-id>
+# MODEL_SONNET=<provider/model-id>
+# MODEL_HAIKU=<provider/model-id>
MODEL="nvidia_nim/nvidia/nemotron-3-super-120b-a12b"
# Optional live smoke model overrides. Provider smoke runs once per configured
# provider even when MODEL/MODEL_* route to a different provider.
-FCC_SMOKE_MODEL_NVIDIA_NIM=
-FCC_SMOKE_MODEL_OPENAI=
-FCC_SMOKE_MODEL_AZURE_OPENAI=
-FCC_SMOKE_MODEL_OPEN_ROUTER=
-FCC_SMOKE_MODEL_MISTRAL=
-FCC_SMOKE_MODEL_MISTRAL_REASONING=
-FCC_SMOKE_MODEL_MISTRAL_CODESTRAL=
-FCC_SMOKE_MODEL_DEEPSEEK=
-FCC_SMOKE_MODEL_OLLAMA_CLOUD=
-FCC_SMOKE_MODEL_LMSTUDIO=
-FCC_SMOKE_MODEL_LLAMACPP=
-FCC_SMOKE_MODEL_OLLAMA=
-FCC_SMOKE_MODEL_KIMI=
-FCC_SMOKE_MODEL_KIMI_CODE=
-FCC_SMOKE_MODEL_WAFER=
-FCC_SMOKE_MODEL_MINIMAX=
-FCC_SMOKE_MODEL_OPENCODE_ZEN=
-FCC_SMOKE_MODEL_OPENCODE_GO=
-FCC_SMOKE_MODEL_VERCEL=
-FCC_SMOKE_MODEL_BEDROCK=
-FCC_SMOKE_MODEL_HUGGINGFACE=
-FCC_SMOKE_MODEL_COHERE=
-FCC_SMOKE_MODEL_GITHUB_MODELS=
-FCC_SMOKE_MODEL_ZAI=
-FCC_SMOKE_MODEL_TOKENROUTER=
-FCC_SMOKE_MODEL_NARAROUTE=
-FCC_SMOKE_MODEL_FIREWORKS=
-FCC_SMOKE_MODEL_NOVITA=
-FCC_SMOKE_MODEL_CLOUDFLARE=
-FCC_SMOKE_MODEL_GEMINI=
-FCC_SMOKE_MODEL_VERTEX=
-FCC_SMOKE_MODEL_GROQ=
-FCC_SMOKE_MODEL_QWENCLOUD=
-FCC_SMOKE_MODEL_TOGETHER=
-FCC_SMOKE_MODEL_DEEPINFRA=
-FCC_SMOKE_MODEL_SILICONFLOW=
-FCC_SMOKE_MODEL_NEBIUS=
-FCC_SMOKE_MODEL_CHUTES=
-FCC_SMOKE_MODEL_FEATHERLESS=
-FCC_SMOKE_MODEL_AGNES=
-FCC_SMOKE_MODEL_ZENMUX=
-FCC_SMOKE_MODEL_SAMBANOVA=
-FCC_SMOKE_MODEL_KILO=
-FCC_SMOKE_MODEL_CEREBRAS=
-FCC_SMOKE_NIM_MODELS=
-FCC_SMOKE_NIM_EXTRA_MODELS=
-FCC_SMOKE_OPENROUTER_FREE_MODELS=
-FCC_SMOKE_OPENROUTER_FREE_EXTRA_MODELS=
+# FCC_SMOKE_MODEL_NVIDIA_NIM=<provider/model-id>
+# FCC_SMOKE_MODEL_OPENAI=<provider/model-id>
+# FCC_SMOKE_MODEL_AZURE_OPENAI=<provider/model-id>
+# FCC_SMOKE_MODEL_OPEN_ROUTER=<provider/model-id>
+# FCC_SMOKE_MODEL_MISTRAL=<provider/model-id>
+# FCC_SMOKE_MODEL_MISTRAL_REASONING=<provider/model-id>
+# FCC_SMOKE_MODEL_MISTRAL_CODESTRAL=<provider/model-id>
+# FCC_SMOKE_MODEL_DEEPSEEK=<provider/model-id>
+# FCC_SMOKE_MODEL_OLLAMA_CLOUD=<provider/model-id>
+# FCC_SMOKE_MODEL_LMSTUDIO=<provider/model-id>
+# FCC_SMOKE_MODEL_LLAMACPP=<provider/model-id>
+# FCC_SMOKE_MODEL_OLLAMA=<provider/model-id>
+# FCC_SMOKE_MODEL_KIMI=<provider/model-id>
+# FCC_SMOKE_MODEL_KIMI_CODE=<provider/model-id>
+# FCC_SMOKE_MODEL_WAFER=<provider/model-id>
+# FCC_SMOKE_MODEL_MINIMAX=<provider/model-id>
+# FCC_SMOKE_MODEL_OPENCODE_ZEN=<provider/model-id>
+# FCC_SMOKE_MODEL_OPENCODE_GO=<provider/model-id>
+# FCC_SMOKE_MODEL_VERCEL=<provider/model-id>
+# FCC_SMOKE_MODEL_BEDROCK=<provider/model-id>
+# FCC_SMOKE_MODEL_HUGGINGFACE=<provider/model-id>
+# FCC_SMOKE_MODEL_COHERE=<provider/model-id>
+# FCC_SMOKE_MODEL_GITHUB_MODELS=<provider/model-id>
+# FCC_SMOKE_MODEL_ZAI=<provider/model-id>
+# FCC_SMOKE_MODEL_TOKENROUTER=<your-token>
+# FCC_SMOKE_MODEL_NARAROUTE=<provider/model-id>
+# FCC_SMOKE_MODEL_FIREWORKS=<provider/model-id>
+# FCC_SMOKE_MODEL_NOVITA=<provider/model-id>
+# FCC_SMOKE_MODEL_CLOUDFLARE=<provider/model-id>
+# FCC_SMOKE_MODEL_GEMINI=<provider/model-id>
+# FCC_SMOKE_MODEL_VERTEX=<provider/model-id>
+# FCC_SMOKE_MODEL_GROQ=<provider/model-id>
+# FCC_SMOKE_MODEL_QWENCLOUD=<provider/model-id>
+# FCC_SMOKE_MODEL_TOGETHER=<provider/model-id>
+# FCC_SMOKE_MODEL_DEEPINFRA=<provider/model-id>
+# FCC_SMOKE_MODEL_SILICONFLOW=<provider/model-id>
+# FCC_SMOKE_MODEL_NEBIUS=<provider/model-id>
+# FCC_SMOKE_MODEL_CHUTES=<provider/model-id>
+# FCC_SMOKE_MODEL_FEATHERLESS=<provider/model-id>
+# FCC_SMOKE_MODEL_AGNES=<provider/model-id>
+# FCC_SMOKE_MODEL_ZENMUX=<provider/model-id>
+# FCC_SMOKE_MODEL_SAMBANOVA=<provider/model-id>
+# FCC_SMOKE_MODEL_KILO=<provider/model-id>
+# FCC_SMOKE_MODEL_CEREBRAS=<provider/model-id>
+# FCC_SMOKE_NIM_MODELS=<provider/model-id>
+# FCC_SMOKE_NIM_EXTRA_MODELS=<provider/model-id>
+# FCC_SMOKE_OPENROUTER_FREE_MODELS=<provider/model-id>
+# FCC_SMOKE_OPENROUTER_FREE_EXTRA_MODELS=<provider/model-id>
# Reasoning policy
@@ -247,61 +247,63 @@ REASONING_HAIKU=inherit
# Provider config
# Per-provider proxy support: http and socks5, example: "http://username:password@host:port"
-OPENAI_PROXY=""
-XAI_PROXY=""
-QWENCLOUD_PROXY=""
-TOGETHER_PROXY=""
-DEEPINFRA_PROXY=""
-SILICONFLOW_PROXY=""
-NEBIUS_PROXY=""
-CHUTES_PROXY=""
-FEATHERLESS_PROXY=""
-AGNES_PROXY=""
-ZENMUX_PROXY=""
-AZURE_OPENAI_PROXY=""
-NVIDIA_NIM_PROXY=""
-OPENROUTER_PROXY=""
-MISTRAL_PROXY=""
-CODESTRAL_PROXY=""
-LMSTUDIO_PROXY=""
-LLAMACPP_PROXY=""
-KIMI_PROXY=""
-KIMI_CODE_PROXY=""
-WAFER_PROXY=""
-MINIMAX_PROXY=""
-OPENCODE_ZEN_PROXY=""
-OPENCODE_GO_PROXY=""
-VERCEL_AI_GATEWAY_PROXY=""
-BEDROCK_PROXY=""
-HUGGINGFACE_PROXY=""
-COHERE_PROXY=""
-GITHUB_MODELS_PROXY=""
-ZAI_PROXY=""
-TOKENROUTER_PROXY=""
-NARAROUTE_PROXY=""
-FIREWORKS_PROXY=""
-NOVITA_PROXY=""
-CLOUDFLARE_PROXY=""
-GEMINI_PROXY=""
-VERTEX_PROXY=""
-GROQ_PROXY=""
-SAMBANOVA_PROXY=""
-KILO_PROXY=""
-CEREBRAS_PROXY=""
-OLLAMA_CLOUD_PROXY=""
+# OPENAI_PROXY=<http-or-socks-url>
+# XAI_PROXY=<http-or-socks-url>
+# QWENCLOUD_PROXY=<http-or-socks-url>
+# TOGETHER_PROXY=<http-or-socks-url>
+# DEEPINFRA_PROXY=<http-or-socks-url>
+# SILICONFLOW_PROXY=<http-or-socks-url>
+# NEBIUS_PROXY=<http-or-socks-url>
+# CHUTES_PROXY=<http-or-socks-url>
+# FEATHERLESS_PROXY=<http-or-socks-url>
+# AGNES_PROXY=<http-or-socks-url>
+# ZENMUX_PROXY=<http-or-socks-url>
+# AZURE_OPENAI_PROXY=<http-or-socks-url>
+# NVIDIA_NIM_PROXY=<http-or-socks-url>
+# OPENROUTER_PROXY=<http-or-socks-url>
+# MISTRAL_PROXY=<http-or-socks-url>
+# CODESTRAL_PROXY=<http-or-socks-url>
+# LMSTUDIO_PROXY=<http-or-socks-url>
+# LLAMACPP_PROXY=<http-or-socks-url>
+# KIMI_PROXY=<http-or-socks-url>
+# KIMI_CODE_PROXY=<http-or-socks-url>
+# WAFER_PROXY=<http-or-socks-url>
+# MINIMAX_PROXY=<http-or-socks-url>
+# OPENCODE_ZEN_PROXY=<http-or-socks-url>
+# OPENCODE_GO_PROXY=<http-or-socks-url>
+# VERCEL_AI_GATEWAY_PROXY=<http-or-socks-url>
+# BEDROCK_PROXY=<http-or-socks-url>
+# HUGGINGFACE_PROXY=<http-or-socks-url>
+# COHERE_PROXY=<http-or-socks-url>
+# GITHUB_MODELS_PROXY=<http-or-socks-url>
+# ZAI_PROXY=<http-or-socks-url>
+# TOKENROUTER_PROXY=<http-or-socks-url>
+# NARAROUTE_PROXY=<http-or-socks-url>
+# FIREWORKS_PROXY=<http-or-socks-url>
+# NOVITA_PROXY=<http-or-socks-url>
+# CLOUDFLARE_PROXY=<http-or-socks-url>
+# GEMINI_PROXY=<http-or-socks-url>
+# VERTEX_PROXY=<http-or-socks-url>
+# GROQ_PROXY=<http-or-socks-url>
+# SAMBANOVA_PROXY=<http-or-socks-url>
+# KILO_PROXY=<http-or-socks-url>
+# CEREBRAS_PROXY=<http-or-socks-url>
+# OLLAMA_CLOUD_PROXY=<http-or-socks-url>
PROVIDER_RATE_LIMIT=1
-PROVIDER_RATE_WINDOW=3
-PROVIDER_MAX_CONCURRENCY=5
+PROVIDER_RATE_WINDOW=2
+PROVIDER_MAX_CONCURRENCY=2
# HTTP client timeouts (seconds) for provider API requests
-HTTP_READ_TIMEOUT=300
-HTTP_WRITE_TIMEOUT=60
-HTTP_CONNECT_TIMEOUT=60
+HTTP_READ_TIMEOUT=120
+HTTP_WRITE_TIMEOUT=10
+HTTP_CONNECT_TIMEOUT=10
-# Optional proxy bearer token
+# Proxy authentication is an explicit switch. Clients always receive the retained
+# non-empty token, even while server-side enforcement is disabled.
+PROXY_AUTH_ENABLED=false
ANTHROPIC_AUTH_TOKEN="freecc"
@@ -316,35 +318,35 @@ MESSAGING_RATE_WINDOW=1
# Voice Note Transcription
-VOICE_NOTE_ENABLED=false
+VOICE_NOTE_ENABLED=true
# WHISPER_DEVICE: "cpu" | "cuda" | "nvidia_nim"
# - "cpu"/"cuda": Hugging Face transformers Whisper (offline, free; install with: uv sync --extra voice_local)
# - "nvidia_nim": NVIDIA NIM Whisper via Riva gRPC (requires NVIDIA_NIM_API_KEY; install with: uv sync --extra voice)
# (Independent of MODEL=nvidia_nim/...: that selects the *chat* provider; this selects voice STT only.)
-WHISPER_DEVICE="nvidia_nim"
+WHISPER_DEVICE="cpu"
# WHISPER_MODEL:
# - For cpu/cuda: Hugging Face ID or short name (tiny, base, small, medium, large-v2, large-v3, large-v3-turbo)
# - For nvidia_nim: NVIDIA NIM model (e.g., "nvidia/parakeet-ctc-1.1b-asr", "openai/whisper-large-v3")
# - For nvidia_nim, default to "openai/whisper-large-v3" for best performance
-WHISPER_MODEL="openai/whisper-large-v3"
+WHISPER_MODEL="base"
# Telegram Config
-TELEGRAM_BOT_TOKEN=""
-ALLOWED_TELEGRAM_USER_ID=""
+# TELEGRAM_BOT_TOKEN=<your-token>
+# ALLOWED_TELEGRAM_USER_ID=<allowed-id>
# Optional Telegram-only proxy.
# Supported schemes: http, https, socks4, socks5, socks5h.
# Example: "socks5://127.0.0.1:1080" or "https://user:password@host:port"
-TELEGRAM_PROXY_URL=""
+# TELEGRAM_PROXY_URL=<http-or-socks-url>
# Discord Config
-DISCORD_BOT_TOKEN=""
-ALLOWED_DISCORD_CHANNELS=""
+# DISCORD_BOT_TOKEN=<your-token>
+# ALLOWED_DISCORD_CHANNELS=<allowed-id>
# Agent Config
-ALLOWED_DIR=""
+# ALLOWED_DIR=<workspace-path>
FAST_PREFIX_DETECTION=true
ENABLE_NETWORK_PROBE_MOCK=true
ENABLE_TITLE_GENERATION_SKIP=true
@@ -352,8 +354,8 @@ ENABLE_SUGGESTION_MODE_SKIP=true
ENABLE_FILEPATH_EXTRACTION_MOCK=true
-# Local Anthropic web_search / web_fetch handling (performs outbound HTTP; on by default)
-ENABLE_WEB_SERVER_TOOLS=true
+# Local Anthropic web_search / web_fetch handling (outbound HTTP; disabled by default)
+ENABLE_WEB_SERVER_TOOLS=false
WEB_FETCH_ALLOWED_SCHEMES=http,https
WEB_FETCH_ALLOW_PRIVATE_NETWORKS=false
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 498ac10d..f2f9d49e 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -309,68 +309,71 @@ retain the model list they loaded at startup.
## Configuration Model
-[config/settings.py](src/free_claude_code/config/settings.py) owns the flat Pydantic Settings schema:
-raw env fields, validation, and `get_settings()`. It should not own routing,
-model-ref parsing, launcher defaults, or web-tool policy. Dotenv discovery lives
-in [config/env_files.py](src/free_claude_code/config/env_files.py) and uses this order:
-
-1. repo-local `.env`;
-2. managed `~/.fcc/.env`;
-3. optional `FCC_ENV_FILE`, appended when present.
-
-Later dotenv files override earlier dotenv files. Process environment variables
-also participate through Pydantic settings resolution. `ANTHROPIC_AUTH_TOKEN`
-has an extra guard after settings are built: if any configured dotenv file
-defines it, that dotenv value replaces a stale inherited shell token. Auth-token
-source detection for startup warnings also belongs to `src/free_claude_code/config/env_files.py`.
-
-[config/paths.py](src/free_claude_code/config/paths.py) defines managed paths:
-
-- config directory: `~/.fcc`;
-- managed env file: `~/.fcc/.env`;
-- generated Codex model catalog: `~/.fcc/codex-model-catalog.json`;
-- messaging state directory: `~/.fcc/agent_workspace`;
-- server log: `~/.fcc/logs/server.log`.
-
-Model routing configuration is tiered:
-
-- `MODEL` is the fallback provider-prefixed model ref.
-- `MODEL_FABLE`, `MODEL_OPUS`, `MODEL_SONNET`, and `MODEL_HAIKU` override Claude model tiers.
-- `REASONING_POLICY` selects `off`, `client`, `low`, `medium`, `high`, `xhigh`,
- or `max` for the fallback route.
-- `REASONING_FABLE`, `REASONING_OPUS`, `REASONING_SONNET`, and
- `REASONING_HAIKU` accept the same values plus `inherit`.
-
-[config/reasoning.py](src/free_claude_code/config/reasoning.py) owns the typed
-configuration vocabulary. FCC-owned dotenv files receive one-time migrations
-for retired configuration keys and values before Settings loads them. Explicit
-`FCC_ENV_FILE` files are never rewritten and instead receive an actionable
-startup warning.
-
-[config/model_refs.py](src/free_claude_code/config/model_refs.py) owns provider-prefixed model ref
-parsing and configured `MODEL*` inventory. API routing and provider validation
-depend on those helpers instead of adding behavior methods to Settings.
-
-[config/admin/](src/free_claude_code/config/admin/) owns the Admin UI config manifest and
-managed env writes. Provider credential, configurable base 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 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 Admin UI template source. It is
-packaged as a [src/free_claude_code/config/](src/free_claude_code/config/) resource for Admin UI defaults;
-runtime settings do not read it as a live config file. The Admin UI creates and
-atomically replaces `~/.fcc/.env` when configuration is applied; server startup
-only migrates legacy env files when the managed file is absent.
-
-Admin routes call `require_loopback_admin()`, which rejects non-loopback clients
-and non-local origins.
+[config/settings.py](src/free_claude_code/config/settings.py) is a pure Pydantic
+schema. It owns field types, canonical defaults, normalization, and cross-field
+validation, but it never reads process state or files. Required strings are
+always non-empty. Optional strings have exactly one absent state, `None`; blank
+input is normalized to that state before validation.
+
+[config/loader.py](src/free_claude_code/config/loader.py) owns external source
+composition and provenance. The live precedence is Settings defaults, then the
+managed `~/.fcc/.env`, then process environment. The one intentional exception
+is `ANTHROPIC_AUTH_TOKEN`: a non-empty managed value wins over an inherited stale
+process token so FCC-launched clients and the server cannot disagree. Every
+entrypoint uses this loader, and cached settings are invalidated only through
+its public cache accessor.
+
+[config/env_migrations.py](src/free_claude_code/config/env_migrations.py) owns a
+locked, atomic schema-1 consolidation before the first load. When the managed
+file is not yet schema 1, migration selects one base source: existing managed
+state, otherwise a legacy home file, otherwise a verified FCC source-checkout
+file. A legacy `FCC_ENV_FILE` may overlay that base once. Recognized effective
+values are written to the managed file; imported files remain untouched. Once
+the managed schema marker exists, checkout files and `FCC_ENV_FILE` are inert
+and are not live configuration sources.
+
+[config/paths.py](src/free_claude_code/config/paths.py) defines the managed
+config, lock, model catalog, messaging workspace, and log locations under
+`~/.fcc`. Arbitrary current-working-directory `.env` files are never read.
+
+Proxy authentication has two independent settings:
+
+- `PROXY_AUTH_ENABLED` controls whether FCC validates incoming bearer tokens;
+- `ANTHROPIC_AUTH_TOKEN` is a retained, non-empty client credential, exposed
+ internally as `proxy_auth_token`.
+
+Disabling authentication does not erase or replace the token. Claude, Codex,
+Pi, managed messaging, and local model-catalog calls all receive the retained
+token. The API boundary checks the boolean first and uses constant-time token
+comparison only when enforcement is enabled.
+
+Model routing remains tiered: `MODEL` is the fallback route;
+`MODEL_FABLE`, `MODEL_OPUS`, `MODEL_SONNET`, and `MODEL_HAIKU` are optional
+overrides. [config/model_refs.py](src/free_claude_code/config/model_refs.py) owns
+model-ref parsing, while [config/reasoning.py](src/free_claude_code/config/reasoning.py)
+owns the typed reasoning vocabulary.
+
+[config/admin/](src/free_claude_code/config/admin/) owns the Admin manifest,
+presentation, validation, and sparse managed-file persistence. Settings
+metadata supplies runtime defaults; provider and smoke fields are generated
+from [config/provider_catalog.py](src/free_claude_code/config/provider_catalog.py).
+Admin requests are partial updates: omitted keys stay unchanged, `null` removes
+an optional assignment, and required/defaulted values reject `null` or blank
+input. False and zero remain real values. Masked or blank secret submissions
+mean unchanged; an explicit remove action is available only for optional
+secrets. Preview and Apply validate the same prospective Settings snapshot, and
+Apply atomically writes only configured values plus preserved unknown managed
+assignments. Process-owned fields are visible but locked.
+
+The provider composition root narrows optional Settings into provider-ready
+state. Static-key providers receive a non-empty key, Vertex receives renewable
+ADC with `api_key=None`, and optional proxies remain `None` until configured.
+Resolved [ProviderConfig](src/free_claude_code/providers/base.py) has no second
+set of Settings defaults.
+
+[.env.example](.env.example) is documentation only. It is neither packaged nor
+read at runtime. Admin routes call `require_loopback_admin()`, which rejects
+non-loopback clients and non-local origins.
## HTTP Request Flow
@@ -1103,18 +1106,13 @@ adds the configured FCC host and standard loopback names to both `NO_PROXY` and
`no_proxy`. Provider-specific upstream proxies remain provider-owned and do not
participate in this local boundary.
-[cli/proxy_auth.py](src/free_claude_code/cli/proxy_auth.py) owns the neutral
-proxy-auth token policy shared by client launchers. A blank configured token
-becomes the local-only `fcc-no-auth` sentinel so clients cross their login gates
-while FCC continues to run without API authentication.
-
[cli/claude_env.py](src/free_claude_code/cli/claude_env.py) owns the canonical
Claude Code proxy environment used by every FCC-launched Claude process. It
strips inherited `ANTHROPIC_*` variables, sets `ANTHROPIC_BASE_URL`, enables
gateway model discovery, configures the auto-compact window, disables
-nonessential Anthropic traffic, and always sets `ANTHROPIC_AUTH_TOKEN`. Blank
-proxy auth uses the shared local-only sentinel so Claude Code reaches the proxy
-instead of stopping at its login gate.
+nonessential Anthropic traffic, and always sets the retained non-empty
+`ANTHROPIC_AUTH_TOKEN`. Server-side authentication enablement does not alter the
+client environment.
[cli/launchers/claude.py](src/free_claude_code/cli/launchers/claude.py) owns the installed
`fcc-claude` launcher:
diff --git a/README.md b/README.md
index 8637a0c8..de53ab94 100644
--- a/README.md
+++ b/README.md
@@ -99,6 +99,10 @@ Use the port shown in your terminal if it differs from `8082`.
4. Leave `MODEL` on the default `nvidia_nim/nvidia/nemotron-3-super-120b-a12b`, or search the model dropdown and select another model.
5. Click **Validate**, then **Apply**.
+FCC stores Admin settings in `~/.fcc/.env`. To require a bearer token on the
+proxy API, enable **Proxy Authentication** in Admin; disabling enforcement keeps
+the same token available to FCC launchers.
+
<div align="center">
<img src="assets/admin-page.png" alt="Free Claude Code Admin UI" width="700">
</div>
diff --git a/pyproject.toml b/pyproject.toml
index d0ff28ef..e9aa7e60 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "4.30.2"
+version = "5.0.0"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
@@ -18,7 +18,6 @@ dependencies = [
"tiktoken>=0.13.0",
"python-telegram-bot>=22.8",
"discord.py>=2.7.1",
- "pydantic-settings>=2.14.2",
"openai>=2.53.0",
"loguru>=0.7.0",
"aiohttp>=3.14.3",
@@ -54,9 +53,6 @@ voice_local = [
[tool.hatch.build.targets.wheel]
packages = ["src/free_claude_code"]
-[tool.hatch.build.targets.wheel.force-include]
-".env.example" = "free_claude_code/config/env.example"
-
[tool.uv]
required-version = ">=0.11.16"
diff --git a/smoke/README.md b/smoke/README.md
index a6f8a2cc..2a3e08b8 100644
--- a/smoke/README.md
+++ b/smoke/README.md
@@ -121,7 +121,8 @@ uv run pytest smoke/product -n 0 -s --tb=short
## Environment
-- `FCC_ENV_FILE`: explicit dotenv path for startup/config scenarios.
+- Runtime settings use the isolated managed `~/.fcc/.env`; `FCC_ENV_FILE` is
+ exercised only by the one-time legacy migration smoke.
- `FCC_LIVE_SMOKE=1`: enables live smoke execution.
- `FCC_ALLOW_NO_PROVIDER_SMOKE=1`: permits no-provider live smoke for harness work.
- `FCC_SMOKE_TARGETS`: comma-separated targets, or `all`.
diff --git a/smoke/capabilities.py b/smoke/capabilities.py
index 053387e3..19ff43b1 100644
--- a/smoke/capabilities.py
+++ b/smoke/capabilities.py
@@ -258,8 +258,8 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (
"config",
"env_precedence",
"config_env_precedence",
- "free_claude_code.config.settings.Settings",
- "process env, user env file, repo env file, FCC_ENV_FILE",
+ "free_claude_code.config.loader.get_settings",
+ "defaults, managed env, process env, and one-time legacy import",
"deterministic settings values",
"validation error for invalid settings",
("tests/config/test_config.py",),
@@ -268,10 +268,10 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (
"config",
"removed_env_migration",
"removed_env_migration",
- "free_claude_code.config.settings.Settings",
+ "free_claude_code.config.env_migrations.consolidate_managed_config",
"retired ENABLE_MODEL_THINKING or tier override in an FCC-owned dotenv",
"owned dotenv is migrated to the typed reasoning policy",
- "explicit dotenv receives an actionable warning",
+ "legacy source remains untouched after one managed import",
("tests/config/test_env_migrations.py", "tests/config/test_config.py"),
("test_removed_env_migration_e2e",),
),
diff --git a/smoke/features.py b/smoke/features.py
index 850ca690..607fb43d 100644
--- a/smoke/features.py
+++ b/smoke/features.py
@@ -458,13 +458,13 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
),
FeatureCoverage(
"config_env_precedence",
- "FCC_ENV_FILE, dotenv, and process env precedence are deterministic",
- ("tests/config/test_config.py",),
+ "Managed config, process env, and one-time legacy import are deterministic",
+ ("tests/config/test_config.py", "tests/config/test_env_migrations.py"),
(),
("test_env_precedence_e2e",),
("config",),
(),
- "always runnable with isolated env files",
+ "always runnable with an isolated managed home",
),
FeatureCoverage(
"removed_env_migration",
diff --git a/smoke/lib/claude_cli_matrix.py b/smoke/lib/claude_cli_matrix.py
index 5704466f..ad605e7d 100644
--- a/smoke/lib/claude_cli_matrix.py
+++ b/smoke/lib/claude_cli_matrix.py
@@ -101,7 +101,7 @@ def run_claude_cli(
env = build_claude_proxy_env(
proxy_root_url=server.base_url,
- auth_token=config.settings.anthropic_auth_token,
+ auth_token=config.settings.proxy_auth_token,
base_env=os.environ,
)
env["TERM"] = "dumb"
diff --git a/smoke/lib/config.py b/smoke/lib/config.py
index 7ba4ce89..784aabfe 100644
--- a/smoke/lib/config.py
+++ b/smoke/lib/config.py
@@ -5,13 +5,14 @@ from collections.abc import Mapping
from dataclasses import dataclass
from pathlib import Path
+from free_claude_code.config.loader import clear_settings_cache, get_settings
from free_claude_code.config.model_refs import parse_model_name, parse_provider_type
from free_claude_code.config.provider_catalog import (
PROVIDER_CATALOG,
SUPPORTED_PROVIDER_IDS,
ProviderAuthKind,
)
-from free_claude_code.config.settings import Settings, get_settings
+from free_claude_code.config.settings import Settings
from free_claude_code.providers.runtime.config import has_provider_configuration
DEFAULT_TARGETS = frozenset(
@@ -169,7 +170,7 @@ class SmokeConfig:
@classmethod
def load(cls) -> SmokeConfig:
root = Path(__file__).resolve().parents[2]
- get_settings.cache_clear()
+ clear_settings_cache()
settings = get_settings()
return cls(
root=root,
@@ -388,7 +389,7 @@ def openrouter_free_cli_model_refs(
def auth_headers(token: str | None = None) -> dict[str, str]:
settings = get_settings()
- resolved = token if token is not None else settings.anthropic_auth_token
+ resolved = token if token is not None else settings.proxy_auth_token
headers = {
"anthropic-version": "2023-06-01",
"content-type": "application/json",
diff --git a/smoke/lib/e2e.py b/smoke/lib/e2e.py
index cd551e0c..970ed847 100644
--- a/smoke/lib/e2e.py
+++ b/smoke/lib/e2e.py
@@ -7,7 +7,7 @@ import subprocess
import time
import uuid
import wave
-from collections.abc import AsyncGenerator, Awaitable, Callable, Iterator
+from collections.abc import AsyncGenerator, Awaitable, Callable, Iterable, Iterator
from contextlib import contextmanager
from dataclasses import dataclass, field
from pathlib import Path
@@ -59,11 +59,13 @@ class SmokeServerDriver:
*,
name: str,
env_overrides: dict[str, str] | None = None,
+ env_unset: Iterable[str] = (),
command: list[str] | None = None,
) -> None:
self.config = config
self.name = name
self.env_overrides = env_overrides
+ self.env_unset = tuple(env_unset)
self.command = command
@contextmanager
@@ -71,6 +73,7 @@ class SmokeServerDriver:
with start_server(
self.config,
env_overrides=self.env_overrides,
+ env_unset=self.env_unset,
command=self.command,
name=self.name,
) as server:
@@ -278,7 +281,7 @@ class ClientProtocolDriver:
) -> subprocess.CompletedProcess[str]:
env = build_claude_proxy_env(
proxy_root_url=server.base_url,
- auth_token=config.settings.anthropic_auth_token,
+ auth_token=config.settings.proxy_auth_token,
base_env=os.environ,
)
command = [
diff --git a/smoke/prereq/test_auth_prereq_live.py b/smoke/prereq/test_auth_prereq_live.py
index 01396717..4e4108ce 100644
--- a/smoke/prereq/test_auth_prereq_live.py
+++ b/smoke/prereq/test_auth_prereq_live.py
@@ -13,16 +13,24 @@ def test_bearer_auth_is_the_only_supported_header_shape(
smoke_config: SmokeConfig, tmp_path: Path
) -> None:
token = "fcc-smoke-token"
- env_file = tmp_path / "auth.env"
- env_file.write_text(f'ANTHROPIC_AUTH_TOKEN="{token}"\n', encoding="utf-8")
+ home = tmp_path / "home"
+ env_file = home / ".fcc" / ".env"
+ env_file.parent.mkdir(parents=True)
+ env_file.write_text(
+ "FCC_CONFIG_SCHEMA=1\n"
+ "PROXY_AUTH_ENABLED=true\n"
+ f'ANTHROPIC_AUTH_TOKEN="{token}"\n',
+ encoding="utf-8",
+ )
with start_server(
smoke_config,
env_overrides={
- "ANTHROPIC_AUTH_TOKEN": token,
- "FCC_ENV_FILE": str(env_file),
+ "HOME": str(home),
+ "USERPROFILE": str(home),
"MESSAGING_PLATFORM": "none",
},
+ env_unset={"ANTHROPIC_AUTH_TOKEN", "PROXY_AUTH_ENABLED", "FCC_ENV_FILE"},
name="auth",
) as server:
assert httpx.get(f"{server.base_url}/").status_code == 401
diff --git a/smoke/prereq/test_cli_prereq_live.py b/smoke/prereq/test_cli_prereq_live.py
index 1f7415e3..3f6d0d4e 100644
--- a/smoke/prereq/test_cli_prereq_live.py
+++ b/smoke/prereq/test_cli_prereq_live.py
@@ -43,7 +43,7 @@ def test_claude_cli_prompt_when_available(
) as server:
env = build_claude_proxy_env(
proxy_root_url=server.base_url,
- auth_token=smoke_config.settings.anthropic_auth_token,
+ auth_token=smoke_config.settings.proxy_auth_token,
base_env=os.environ,
)
result = run_captured_text(
diff --git a/smoke/prereq/test_voice_prereq_live.py b/smoke/prereq/test_voice_prereq_live.py
index 78091eb1..b5055bfd 100644
--- a/smoke/prereq/test_voice_prereq_live.py
+++ b/smoke/prereq/test_voice_prereq_live.py
@@ -26,9 +26,12 @@ async def test_voice_transcription_backend_when_explicitly_enabled(
_write_tone_wav(wav_path)
transcriber: Transcriber
if smoke_config.settings.whisper_device == "nvidia_nim":
+ api_key = smoke_config.settings.nvidia_nim_api_key
+ if api_key is None:
+ pytest.skip("NVIDIA_NIM_API_KEY is required")
transcriber = NvidiaNimTranscriber(
model=smoke_config.settings.whisper_model,
- api_key=smoke_config.settings.nvidia_nim_api_key,
+ api_key=api_key,
)
else:
transcriber = TranscriptionService(
diff --git a/smoke/product/test_auth_product_live.py b/smoke/product/test_auth_product_live.py
index 623bd070..03c71ed2 100644
--- a/smoke/product/test_auth_product_live.py
+++ b/smoke/product/test_auth_product_live.py
@@ -9,16 +9,24 @@ pytestmark = [pytest.mark.live, pytest.mark.smoke_target("auth")]
def test_api_bearer_auth_contract_e2e(smoke_config: SmokeConfig, tmp_path) -> None:
token = "product-smoke-token"
- env_file = tmp_path / "auth-product.env"
- env_file.write_text(f'ANTHROPIC_AUTH_TOKEN="{token}"\n', encoding="utf-8")
+ home = tmp_path / "home"
+ env_file = home / ".fcc" / ".env"
+ env_file.parent.mkdir(parents=True)
+ env_file.write_text(
+ "FCC_CONFIG_SCHEMA=1\n"
+ "PROXY_AUTH_ENABLED=true\n"
+ f'ANTHROPIC_AUTH_TOKEN="{token}"\n',
+ encoding="utf-8",
+ )
with SmokeServerDriver(
smoke_config,
name="product-auth",
env_overrides={
- "ANTHROPIC_AUTH_TOKEN": token,
- "FCC_ENV_FILE": str(env_file),
+ "HOME": str(home),
+ "USERPROFILE": str(home),
"MESSAGING_PLATFORM": "none",
},
+ env_unset={"ANTHROPIC_AUTH_TOKEN", "PROXY_AUTH_ENABLED", "FCC_ENV_FILE"},
).run() as server:
unauth = httpx.get(
f"{server.base_url}/v1/models", timeout=smoke_config.timeout_s
diff --git a/smoke/product/test_cli_package_product_live.py b/smoke/product/test_cli_package_product_live.py
index 082217b6..37c1c86b 100644
--- a/smoke/product/test_cli_package_product_live.py
+++ b/smoke/product/test_cli_package_product_live.py
@@ -35,7 +35,9 @@ def test_entrypoint_version_e2e(smoke_config: SmokeConfig, tmp_path: Path) -> No
@pytest.mark.asyncio
async def test_cli_session_resume_fork_e2e(tmp_path: Path) -> None:
- session = ManagedClaudeSession(str(tmp_path), "http://127.0.0.1:8082")
+ session = ManagedClaudeSession(
+ str(tmp_path), "http://127.0.0.1:8082", auth_token="freecc"
+ )
process = AsyncMock()
process.stdout.read.side_effect = [b""]
process.stderr.read.return_value = b""
@@ -63,6 +65,7 @@ async def test_cli_process_cleanup_e2e(tmp_path: Path) -> None:
manager = ManagedClaudeSessionManager(
workspace_path=str(tmp_path),
proxy_root_url="http://127.0.0.1:8082",
+ auth_token="freecc",
)
session, pending_id, is_new = await manager.get_or_create_session()
assert is_new is True
@@ -82,7 +85,9 @@ async def test_cli_process_cleanup_e2e(tmp_path: Path) -> None:
@pytest.mark.asyncio
async def test_cli_session_stop_kills_child_e2e(tmp_path: Path) -> None:
- session = ManagedClaudeSession(str(tmp_path), "http://127.0.0.1:8082")
+ session = ManagedClaudeSession(
+ str(tmp_path), "http://127.0.0.1:8082", auth_token="freecc"
+ )
process = MagicMock()
process.pid = 123456
process.returncode = None
diff --git a/smoke/product/test_config_extensibility_product_live.py b/smoke/product/test_config_extensibility_product_live.py
index 4797243e..883f362c 100644
--- a/smoke/product/test_config_extensibility_product_live.py
+++ b/smoke/product/test_config_extensibility_product_live.py
@@ -1,4 +1,5 @@
import os
+from pathlib import Path
import pytest
@@ -17,21 +18,38 @@ from smoke.lib.e2e import SmokeServerDriver
pytestmark = [pytest.mark.live]
+def _isolated_config_env(home: Path) -> dict[str, str]:
+ env = os.environ.copy()
+ for field in Settings.model_fields.values():
+ alias = field.validation_alias
+ if isinstance(alias, str):
+ env.pop(alias, None)
+ env.pop("FCC_ENV_FILE", None)
+ env["HOME"] = str(home)
+ env["USERPROFILE"] = str(home)
+ return env
+
+
+def _write_managed_config(home: Path, text: str) -> None:
+ path = home / ".fcc" / ".env"
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(f"FCC_CONFIG_SCHEMA=1\n{text}", encoding="utf-8")
+
+
@pytest.mark.smoke_target("config")
def test_env_precedence_e2e(smoke_config: SmokeConfig, tmp_path) -> None:
- env_file = tmp_path / "product.env"
- env_file.write_text(
+ home = tmp_path / "home"
+ _write_managed_config(
+ home,
'MODEL="open_router/test/model"\nANTHROPIC_AUTH_TOKEN="dotenv-token"\n',
- encoding="utf-8",
)
- env = os.environ.copy()
- env["FCC_ENV_FILE"] = str(env_file)
+ env = _isolated_config_env(home)
env["MODEL"] = "nvidia_nim/process-model"
env["ANTHROPIC_AUTH_TOKEN"] = "process-token"
script = (
- "from free_claude_code.config.settings import get_settings; "
+ "from free_claude_code.config.loader import get_settings; "
"s=get_settings(); "
- "print(s.model); print(s.anthropic_auth_token)"
+ "print(s.model); print(s.proxy_auth_token)"
)
result = run_captured_text(
cmd_python_c(script),
@@ -47,39 +65,58 @@ def test_env_precedence_e2e(smoke_config: SmokeConfig, tmp_path) -> None:
@pytest.mark.smoke_target("config")
def test_removed_env_migration_e2e(smoke_config: SmokeConfig, tmp_path) -> None:
- env_file = tmp_path / "removed.env"
- env_file.write_text('NIM_ENABLE_THINKING="true"\n', encoding="utf-8")
- env = os.environ.copy()
+ home = tmp_path / "home"
+ env_file = tmp_path / "legacy-explicit.env"
+ original = 'MODEL="deepseek/imported-once"\n'
+ env_file.write_text(original, encoding="utf-8")
+ env = _isolated_config_env(home)
env["FCC_ENV_FILE"] = str(env_file)
+ script = (
+ "from free_claude_code.config.loader import get_settings; "
+ "print(get_settings().model)"
+ )
result = run_captured_text(
- cmd_python_c(
- "from free_claude_code.config.settings import Settings; Settings()"
- ),
+ cmd_python_c(script),
cwd=smoke_config.root,
env=env,
timeout=smoke_config.timeout_s,
check=False,
)
assert result.returncode == 0, result.stderr
+ assert result.stdout.strip() == "deepseek/imported-once"
+ assert env_file.read_text(encoding="utf-8") == original
+ managed = home / ".fcc" / ".env"
+ first = managed.read_bytes()
+
+ env_file.write_text('MODEL="groq/changed-later"\n', encoding="utf-8")
+ second = run_captured_text(
+ cmd_python_c(script),
+ cwd=smoke_config.root,
+ env=env,
+ timeout=smoke_config.timeout_s,
+ check=False,
+ )
+ assert second.returncode == 0, second.stderr
+ assert second.stdout.strip() == "deepseek/imported-once"
+ assert managed.read_bytes() == first
@pytest.mark.smoke_target("config")
def test_route_reasoning_config_e2e(smoke_config: SmokeConfig, tmp_path) -> None:
- env_file = tmp_path / "thinking.env"
- env_file.write_text(
+ home = tmp_path / "home"
+ _write_managed_config(
+ home,
'REASONING_POLICY="off"\n'
'REASONING_FABLE="high"\n'
'REASONING_OPUS="client"\n'
'REASONING_SONNET="inherit"\n'
'REASONING_HAIKU="off"\n',
- encoding="utf-8",
)
- env = os.environ.copy()
- env["FCC_ENV_FILE"] = str(env_file)
+ env = _isolated_config_env(home)
script = (
"from free_claude_code.application.routing import ModelRouter; "
- "from free_claude_code.config.settings import Settings; "
- "s=Settings(); "
+ "from free_claude_code.config.loader import get_settings; "
+ "s=get_settings(); "
"r=ModelRouter(s); "
"print(r.resolve('claude-fable-5').reasoning_preference.value); "
"print(r.resolve('claude-opus-4-20250514').reasoning_preference.value); "
@@ -106,23 +143,22 @@ def test_route_reasoning_config_e2e(smoke_config: SmokeConfig, tmp_path) -> None
@pytest.mark.smoke_target("config")
def test_proxy_timeout_config_e2e(smoke_config: SmokeConfig, tmp_path) -> None:
- env_file = tmp_path / "timeouts.env"
- env_file.write_text(
+ home = tmp_path / "home"
+ _write_managed_config(
+ home,
'MODEL="open_router/test/model"\n'
'OPENROUTER_API_KEY="key"\n'
'OPENROUTER_PROXY="socks5://127.0.0.1:9999"\n'
'HTTP_READ_TIMEOUT="321"\n'
'HTTP_CONNECT_TIMEOUT="7"\n'
'HTTP_WRITE_TIMEOUT="8"\n',
- encoding="utf-8",
)
- env = os.environ.copy()
- env["FCC_ENV_FILE"] = str(env_file)
+ env = _isolated_config_env(home)
script = (
- "from free_claude_code.config.settings import Settings; "
+ "from free_claude_code.config.loader import get_settings; "
"from free_claude_code.config.provider_catalog import PROVIDER_CATALOG; "
"from free_claude_code.providers.runtime import build_provider_config; "
- "s=Settings(); c=build_provider_config(PROVIDER_CATALOG['open_router'], s); "
+ "s=get_settings(); c=build_provider_config(PROVIDER_CATALOG['open_router'], s); "
"print(c.proxy); print(c.http_read_timeout); "
"print(c.http_connect_timeout); print(c.http_write_timeout)"
)
@@ -150,15 +186,24 @@ def test_provider_runtime_config_e2e() -> None:
settings_kwargs[_settings_init_key(descriptor.credential_attr)] = (
f"{descriptor.provider_id}-key"
)
- if descriptor.base_url_attr is not None and descriptor.default_base_url:
+ if descriptor.base_url_attr is not None:
settings_kwargs[_settings_init_key(descriptor.base_url_attr)] = (
descriptor.default_base_url
+ or f"https://{descriptor.provider_id}.example.invalid/v1"
+ )
+ for attr in descriptor.required_settings_attrs:
+ settings_kwargs.setdefault(
+ _settings_init_key(attr),
+ f"{descriptor.provider_id}-setting",
)
settings = Settings.model_validate(settings_kwargs)
for descriptor in PROVIDER_CATALOG.values():
config = build_provider_config(descriptor, settings)
assert config.base_url
- assert config.api_key
+ if descriptor.credential_attr is not None or descriptor.static_credential:
+ assert config.api_key
+ else:
+ assert config.api_key is None
def _settings_init_key(field_name: str) -> str:
diff --git a/smoke/product/test_provider_product_live.py b/smoke/product/test_provider_product_live.py
index f394c268..dec48c9c 100644
--- a/smoke/product/test_provider_product_live.py
+++ b/smoke/product/test_provider_product_live.py
@@ -639,7 +639,7 @@ def _server_for_provider(
def _openai_auth_headers(smoke_config: SmokeConfig) -> dict[str, str]:
headers = {"content-type": "application/json"}
- token = smoke_config.settings.anthropic_auth_token
+ token = smoke_config.settings.proxy_auth_token
if token:
headers["authorization"] = f"Bearer {token}"
return headers
diff --git a/smoke/product/test_runtime_ownership_product_live.py b/smoke/product/test_runtime_ownership_product_live.py
index e6ca2336..dd23c98a 100644
--- a/smoke/product/test_runtime_ownership_product_live.py
+++ b/smoke/product/test_runtime_ownership_product_live.py
@@ -11,7 +11,6 @@ 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
@@ -173,32 +172,13 @@ def _message_payload(*, stream: bool) -> dict[str, Any]:
def _write_initial_managed_config(home: Path, upstream: FakeOpenAIUpstream) -> None:
config_path = home / ".fcc" / ".env"
config_path.parent.mkdir(parents=True, exist_ok=True)
- template = "\n".join(
- line
- for line in load_env_template().splitlines()
- if not line.startswith(
- (
- "REASONING_POLICY=",
- "REASONING_FABLE=",
- "REASONING_OPUS=",
- "REASONING_SONNET=",
- "REASONING_HAIKU=",
- )
- )
- )
config_path.write_text(
- template
- + "\n"
- + "\n".join(
+ "\n".join(
[
"MODEL=lmstudio/model-a",
- "MODEL_FABLE=",
- "MODEL_OPUS=",
- "MODEL_SONNET=",
- "MODEL_HAIKU=",
f"LM_STUDIO_BASE_URL={upstream.base_url}",
- "ANTHROPIC_AUTH_TOKEN=",
"ENABLE_MODEL_THINKING=false",
+ "LOG_LEVEL=DEBUG",
"MESSAGING_PLATFORM=none",
"",
]
@@ -253,6 +233,7 @@ def test_provider_hot_swap_preserves_inflight_stream_e2e(
"ENABLE_MODEL_THINKING",
"FCC_ENV_FILE",
"LM_STUDIO_BASE_URL",
+ "LOG_LEVEL",
"MODEL",
"MODEL_FABLE",
"MODEL_HAIKU",
@@ -292,7 +273,7 @@ def test_provider_hot_swap_preserves_inflight_stream_e2e(
)
old_thread.start()
assert downstream_started.wait(timeout=10)
- assert upstream_a.chat_started.is_set()
+ assert upstream_a.chat_started.wait(timeout=10)
assert old_errors == []
apply_response = httpx.post(
diff --git a/smoke/product/test_voice_product_live.py b/smoke/product/test_voice_product_live.py
index 23947d27..e0feaf1c 100644
--- a/smoke/product/test_voice_product_live.py
+++ b/smoke/product/test_voice_product_live.py
@@ -50,14 +50,15 @@ async def test_voice_nim_backend_e2e(smoke_config: SmokeConfig, tmp_path: Path)
pytest.skip("missing_env: set FCC_SMOKE_RUN_VOICE=1 to run voice product smoke")
if smoke_config.settings.whisper_device != "nvidia_nim":
pytest.skip("missing_env: WHISPER_DEVICE must be nvidia_nim")
- if not smoke_config.settings.nvidia_nim_api_key.strip():
+ api_key = smoke_config.settings.nvidia_nim_api_key
+ if api_key is None:
pytest.skip("missing_env: NVIDIA_NIM_API_KEY is required")
wav_path = tmp_path / "voice-nim-product.wav"
VoiceFixtureDriver.write_tone_wav(wav_path)
transcriber = NvidiaNimTranscriber(
model=smoke_config.settings.whisper_model,
- api_key=smoke_config.settings.nvidia_nim_api_key,
+ api_key=api_key,
)
try:
text = await transcriber.transcribe(wav_path)
diff --git a/src/free_claude_code/api/admin_static/admin.js b/src/free_claude_code/api/admin_static/admin.js
index 841b878b..a222db54 100644
--- a/src/free_claude_code/api/admin_static/admin.js
+++ b/src/free_claude_code/api/admin_static/admin.js
@@ -9,6 +9,7 @@ const state = {
};
const MASKED_SECRET = "********";
+const NULL_VALUE = "__FCC_NULL__";
const VIEW_GROUPS = [
{
id: "providers",
@@ -38,10 +39,7 @@ const byId = (id) => document.getElementById(id);
function sourceLabel(source) {
const labels = {
default: "default",
- template: "template",
- repo_env: "repo .env",
managed_env: "",
- explicit_env_file: "FCC_ENV_FILE",
process: "process env",
};
return Object.prototype.hasOwnProperty.call(labels, source) ? labels[source] : source;
@@ -513,13 +511,18 @@ function renderField(field) {
const input = inputForField(field);
input.id = `field-${field.key}`;
input.dataset.key = field.key;
- input.dataset.original = field.value || "";
+ input.dataset.original = comparableValue(field.value);
input.dataset.secret = field.secret ? "true" : "false";
input.dataset.configured = field.configured ? "true" : "false";
+ input.dataset.nullable = field.nullable ? "true" : "false";
+ input.dataset.remove = "false";
input.dataset.fieldType = field.type;
input.disabled = field.locked;
input.addEventListener("input", updateDirtyState);
input.addEventListener("change", updateDirtyState);
+ input.addEventListener("input", () => {
+ input.dataset.remove = "false";
+ });
if (field.type === "optional_model") {
input.addEventListener("blur", () => {
if (!input.value.trim() || input.value.trim().toLowerCase() === "none") {
@@ -534,6 +537,20 @@ function renderField(field) {
? new ModelCombobox(input, field).element
: input;
wrapper.append(label, control);
+ if (field.secret && field.nullable && field.configured && !field.locked) {
+ const removeButton = document.createElement("button");
+ removeButton.type = "button";
+ removeButton.className = "ghost-button secret-remove";
+ removeButton.textContent = "Remove";
+ removeButton.addEventListener("click", () => {
+ const removing = input.dataset.remove !== "true";
+ input.dataset.remove = removing ? "true" : "false";
+ input.readOnly = removing;
+ removeButton.textContent = removing ? "Undo removal" : "Remove";
+ updateDirtyState();
+ });
+ wrapper.appendChild(removeButton);
+ }
if (field.description) {
const description = document.createElement("div");
description.className = "field-description";
@@ -779,24 +796,30 @@ function option(value, label) {
function readFieldValue(input) {
if (input.type === "checkbox") return input.checked ? "true" : "false";
+ if (input.dataset.remove === "true") return null;
if (
input.dataset.fieldType === "optional_model" &&
input.value.trim().toLowerCase() === "none"
) {
- return "";
+ return null;
}
if (input.dataset.secret === "true" && input.dataset.configured === "true") {
return input.value ? input.value : MASKED_SECRET;
}
+ if (input.dataset.nullable === "true" && !input.value.trim()) return null;
return input.value;
}
+function comparableValue(value) {
+ return value === null ? NULL_VALUE : String(value);
+}
+
function changedValues() {
const values = {};
document.querySelectorAll("[data-key]").forEach((input) => {
if (input.disabled || !input.matches("input, select, textarea")) return;
const value = readFieldValue(input);
- if (value !== input.dataset.original) {
+ if (comparableValue(value) !== input.dataset.original) {
values[input.dataset.key] = value;
}
});
diff --git a/src/free_claude_code/api/dependencies.py b/src/free_claude_code/api/dependencies.py
index ad45e188..a2a3b9b1 100644
--- a/src/free_claude_code/api/dependencies.py
+++ b/src/free_claude_code/api/dependencies.py
@@ -49,8 +49,7 @@ def require_proxy_auth(
settings: Settings = Depends(get_settings),
) -> None:
"""Require the configured proxy token as HTTP bearer authorization."""
- anthropic_auth_token = settings.anthropic_auth_token.strip()
- if not anthropic_auth_token:
+ if not settings.proxy_auth_enabled:
return
authorization = request.headers.get("authorization")
@@ -70,7 +69,7 @@ def require_proxy_auth(
if not token or not secrets.compare_digest(
token.encode("utf-8"),
- anthropic_auth_token.encode("utf-8"),
+ settings.proxy_auth_token.encode("utf-8"),
):
raise HTTPException(
status_code=401,
diff --git a/src/free_claude_code/cli/claude_env.py b/src/free_claude_code/cli/claude_env.py
index eff072f4..83b3a273 100644
--- a/src/free_claude_code/cli/claude_env.py
+++ b/src/free_claude_code/cli/claude_env.py
@@ -3,7 +3,6 @@
from collections.abc import Mapping
from free_claude_code.cli.local_http import with_local_proxy_bypass
-from free_claude_code.cli.proxy_auth import proxy_auth_token
CLAUDE_CODE_AUTO_COMPACT_WINDOW = "190000"
CLAUDE_BINARY_NAME = "claude"
@@ -28,7 +27,7 @@ def build_claude_proxy_env(
proxy_root_url=proxy_root_url,
)
env["ANTHROPIC_BASE_URL"] = proxy_root_url
- env["ANTHROPIC_AUTH_TOKEN"] = proxy_auth_token(auth_token)
+ env["ANTHROPIC_AUTH_TOKEN"] = auth_token
env["CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY"] = "1"
env["CLAUDE_CODE_AUTO_COMPACT_WINDOW"] = CLAUDE_CODE_AUTO_COMPACT_WINDOW
env["DISABLE_AUTOUPDATER"] = "1"
diff --git a/src/free_claude_code/cli/commands.py b/src/free_claude_code/cli/commands.py
index 8ec4d324..e5e45e94 100644
--- a/src/free_claude_code/cli/commands.py
+++ b/src/free_claude_code/cli/commands.py
@@ -1,28 +1,17 @@
"""Implementations for installed Free Claude Code commands."""
-import os
-import shutil
-import sys
import threading
import time
import webbrowser
from enum import StrEnum
-from pathlib import Path
import uvicorn
from free_claude_code.cli.launchers.common import preflight_proxy
from free_claude_code.cli.process_registry import kill_all_best_effort
-from free_claude_code.config.env_migrations import (
- explicit_env_file_migration_warning,
- migrate_owned_env_files,
-)
-from free_claude_code.config.paths import (
- legacy_env_paths,
- managed_env_path,
-)
+from free_claude_code.config.loader import clear_settings_cache, get_settings
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.config.settings import Settings
from free_claude_code.runtime.bootstrap import build_asgi_app
SERVER_GRACEFUL_SHUTDOWN_SECONDS = 5
@@ -108,7 +97,7 @@ class ServerSupervisor:
):
return
opened_admin_browser = opened_admin_browser or should_open_admin
- get_settings.cache_clear()
+ clear_settings_cache()
except KeyboardInterrupt:
return
finally:
@@ -189,10 +178,8 @@ class ServerSupervisor:
def load_server_settings() -> Settings:
- """Apply owned config migrations before returning the cached settings."""
+ """Return the canonical cached settings."""
- _migrate_legacy_env_if_missing()
- _migrate_config_env()
return get_settings()
@@ -218,30 +205,3 @@ def schedule_open_admin_browser(settings: Settings) -> None:
name="fcc-open-admin-browser",
daemon=True,
).start()
-
-
-def _migrate_legacy_env_if_missing() -> Path | None:
- """Copy a legacy user env into the managed config path when absent."""
-
- env_file = managed_env_path()
- if env_file.exists():
- return None
-
- # TODO: Remove after the ~/.fcc/.env migration has had a release cycle.
- for legacy_env in legacy_env_paths():
- if not legacy_env.is_file():
- continue
- env_file.parent.mkdir(parents=True, exist_ok=True)
- shutil.copyfile(legacy_env, env_file)
- return legacy_env
-
- return None
-
-
-def _migrate_config_env() -> tuple[Path, ...]:
- """Apply dotenv migrations before Settings loads config."""
-
- migrated = migrate_owned_env_files()
- if warning := explicit_env_file_migration_warning(os.environ):
- print(warning, file=sys.stderr)
- return migrated
diff --git a/src/free_claude_code/cli/desktop.py b/src/free_claude_code/cli/desktop.py
index bbe3dc3d..f5b9c1e1 100644
--- a/src/free_claude_code/cli/desktop.py
+++ b/src/free_claude_code/cli/desktop.py
@@ -12,9 +12,9 @@ from free_claude_code.cli.commands import (
schedule_open_admin_browser,
)
from free_claude_code.cli.launchers.common import preflight_proxy
+from free_claude_code.config.loader import get_settings
from free_claude_code.config.paths import config_dir_path
from free_claude_code.config.server_urls import local_proxy_root_url
-from free_claude_code.config.settings import get_settings
from free_claude_code.core.interprocess_lock import InterprocessFileLock
diff --git a/src/free_claude_code/cli/launchers/claude.py b/src/free_claude_code/cli/launchers/claude.py
index 8dbc988a..288a7fef 100644
--- a/src/free_claude_code/cli/launchers/claude.py
+++ b/src/free_claude_code/cli/launchers/claude.py
@@ -8,8 +8,8 @@ from free_claude_code.cli.claude_env import (
CLAUDE_BINARY_NAME,
build_claude_proxy_env,
)
+from free_claude_code.config.loader import get_settings
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
@@ -41,7 +41,7 @@ def launch(argv: Sequence[str] | None = None) -> None:
command=build_claude_launcher_command(binary_path=binary_path, argv=args),
env=build_claude_proxy_env(
proxy_root_url=proxy_root_url,
- auth_token=settings.anthropic_auth_token,
+ auth_token=settings.proxy_auth_token,
base_env=os.environ,
),
binary_name=binary_name,
diff --git a/src/free_claude_code/cli/launchers/codex.py b/src/free_claude_code/cli/launchers/codex.py
index 4bae582e..f075a4cb 100644
--- a/src/free_claude_code/cli/launchers/codex.py
+++ b/src/free_claude_code/cli/launchers/codex.py
@@ -10,10 +10,10 @@ from free_claude_code.cli.local_http import (
open_local_request,
with_local_proxy_bypass,
)
-from free_claude_code.cli.proxy_auth import proxy_auth_token
+from free_claude_code.config.loader import get_settings
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 free_claude_code.config.settings import Settings
from .codex_model_catalog import build_codex_model_catalog, write_codex_model_catalog
from .common import (
@@ -50,7 +50,7 @@ def launch(argv: Sequence[str] | None = None) -> None:
args = list(sys.argv[1:] if argv is None else argv)
settings = get_settings()
if args == [_PRINT_PROXY_AUTH_TOKEN_FLAG]:
- print(proxy_auth_token(settings.anthropic_auth_token))
+ print(settings.proxy_auth_token)
return
proxy_root_url = local_proxy_root_url(settings)
@@ -139,7 +139,7 @@ def codex_model_catalog_config_args(
try:
models_response = fetch_proxy_models_response(
- proxy_root_url, settings.anthropic_auth_token
+ proxy_root_url, settings.proxy_auth_token
)
catalog = build_codex_model_catalog(models_response)
models = catalog.get("models")
@@ -169,9 +169,7 @@ def fetch_proxy_models_response(
"""Fetch the local proxy `/v1/models` response for Codex catalog generation."""
url = f"{proxy_root_url.rstrip('/')}/v1/models"
- headers: dict[str, str] = {}
- if token := auth_token.strip():
- headers["Authorization"] = f"Bearer {token}"
+ headers = {"Authorization": f"Bearer {auth_token}"}
request = Request(url, headers=headers, method="GET")
with open_local_request(
diff --git a/src/free_claude_code/cli/launchers/pi.py b/src/free_claude_code/cli/launchers/pi.py
index a5998a33..3f390586 100644
--- a/src/free_claude_code/cli/launchers/pi.py
+++ b/src/free_claude_code/cli/launchers/pi.py
@@ -7,9 +7,8 @@ from collections.abc import Mapping, Sequence
from pathlib import Path
from free_claude_code.cli.local_http import with_local_proxy_bypass
-from free_claude_code.cli.proxy_auth import proxy_auth_token
+from free_claude_code.config.loader import get_settings
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
@@ -80,7 +79,7 @@ def launch(argv: Sequence[str] | None = None) -> None:
),
env=build_pi_launcher_env(
proxy_root_url=proxy_root_url,
- auth_token=settings.anthropic_auth_token,
+ auth_token=settings.proxy_auth_token,
base_env=os.environ,
),
binary_name=_BINARY_NAME,
@@ -124,7 +123,7 @@ def build_pi_launcher_env(
proxy_root_url=proxy_root_url,
)
env[_BASE_URL_ENV] = proxy_root_url.rstrip("/")
- env[_API_KEY_ENV] = proxy_auth_token(auth_token)
+ env[_API_KEY_ENV] = auth_token
return env
diff --git a/src/free_claude_code/cli/managed/claude.py b/src/free_claude_code/cli/managed/claude.py
index 52f706c3..9ba7d211 100644
--- a/src/free_claude_code/cli/managed/claude.py
+++ b/src/free_claude_code/cli/managed/claude.py
@@ -40,9 +40,9 @@ class ManagedClaudeConfig:
workspace_path: str
proxy_root_url: str
+ auth_token: str
allowed_dirs: list[str] = field(default_factory=list)
claude_bin: str = CLAUDE_BINARY_NAME
- auth_token: str = ""
@dataclass(slots=True)
diff --git a/src/free_claude_code/cli/managed/manager.py b/src/free_claude_code/cli/managed/manager.py
index 30bd603b..34cf9f46 100644
--- a/src/free_claude_code/cli/managed/manager.py
+++ b/src/free_claude_code/cli/managed/manager.py
@@ -24,8 +24,8 @@ class ManagedClaudeSessionManager:
proxy_root_url: str,
allowed_dirs: list[str] | None = None,
claude_bin: str = CLAUDE_BINARY_NAME,
- auth_token: str = "",
*,
+ auth_token: str,
log_raw_cli_diagnostics: bool = False,
log_messaging_error_details: bool = False,
):
diff --git a/src/free_claude_code/cli/managed/session.py b/src/free_claude_code/cli/managed/session.py
index af0016e5..e963bbcd 100644
--- a/src/free_claude_code/cli/managed/session.py
+++ b/src/free_claude_code/cli/managed/session.py
@@ -35,8 +35,8 @@ class ManagedClaudeSession:
proxy_root_url: str,
allowed_dirs: list[str] | None = None,
claude_bin: str = "claude",
- auth_token: str = "",
*,
+ auth_token: str,
log_raw_cli_diagnostics: bool = False,
):
self.config = ManagedClaudeConfig(
diff --git a/src/free_claude_code/cli/proxy_auth.py b/src/free_claude_code/cli/proxy_auth.py
deleted file mode 100644
index 7264ab7a..00000000
--- a/src/free_claude_code/cli/proxy_auth.py
+++ /dev/null
@@ -1,9 +0,0 @@
-"""Shared proxy-auth policy for FCC client launchers."""
-
-PROXY_NO_AUTH_SENTINEL = "fcc-no-auth"
-
-
-def proxy_auth_token(auth_token: str) -> str:
- """Return the configured proxy token or the no-auth client marker."""
-
- return auth_token.strip() or PROXY_NO_AUTH_SENTINEL
diff --git a/src/free_claude_code/config/__init__.py b/src/free_claude_code/config/__init__.py
index 87b0151f..b670d90c 100644
--- a/src/free_claude_code/config/__init__.py
+++ b/src/free_claude_code/config/__init__.py
@@ -1,5 +1,11 @@
"""Configuration management."""
-from .settings import Settings, get_settings
+from .loader import clear_settings_cache, get_settings, resolve_settings_snapshot
+from .settings import Settings
-__all__ = ["Settings", "get_settings"]
+__all__ = [
+ "Settings",
+ "clear_settings_cache",
+ "get_settings",
+ "resolve_settings_snapshot",
+]
diff --git a/src/free_claude_code/config/admin/manifest.py b/src/free_claude_code/config/admin/manifest.py
index ea22b4ac..6a682413 100644
--- a/src/free_claude_code/config/admin/manifest.py
+++ b/src/free_claude_code/config/admin/manifest.py
@@ -2,8 +2,10 @@
from collections.abc import Iterable
from dataclasses import dataclass
+from enum import Enum
from typing import Literal
+from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
from free_claude_code.config.reasoning import (
ROOT_REASONING_PREFERENCES,
ROUTE_REASONING_PREFERENCES,
@@ -44,7 +46,6 @@ class ConfigFieldSpec:
section_id: str
field_type: FieldType = "text"
settings_attr: str | None = None
- default: str = ""
options: tuple[str | ConfigOptionSpec, ...] = ()
secret: bool = False
advanced: bool = False
@@ -52,6 +53,28 @@ class ConfigFieldSpec:
session_sensitive: bool = False
description: str = ""
+ def resolved_default(self) -> str | None:
+ """Return the Settings-owned default or Admin-only fallback."""
+
+ if self.settings_attr is None:
+ return None
+ value = Settings.model_fields[self.settings_attr].get_default(
+ call_default_factory=True
+ )
+ if value is None:
+ return None
+ if isinstance(value, bool):
+ return "true" if value else "false"
+ if isinstance(value, Enum):
+ return str(value.value)
+ return str(value)
+
+ @property
+ def nullable(self) -> bool:
+ """Return whether Admin may explicitly remove this setting."""
+
+ return self.settings_attr is None or self.resolved_default() is None
+
@dataclass(frozen=True, slots=True)
class ConfigOptionSpec:
@@ -138,7 +161,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"models",
"model",
settings_attr="model",
- default="nvidia_nim/nvidia/nemotron-3-super-120b-a12b",
description="Fallback provider/model route for all Claude model names.",
),
ConfigFieldSpec(
@@ -179,7 +201,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"reasoning",
"select",
settings_attr="reasoning_policy",
- default="client",
options=_reasoning_options(ROOT_REASONING_PREFERENCES),
description=(
"From client preserves CLI effort. Providers translate only the controls "
@@ -192,7 +213,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"reasoning",
"select",
settings_attr="reasoning_fable",
- default="inherit",
options=_reasoning_options(ROUTE_REASONING_PREFERENCES),
),
ConfigFieldSpec(
@@ -201,7 +221,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"reasoning",
"select",
settings_attr="reasoning_opus",
- default="inherit",
options=_reasoning_options(ROUTE_REASONING_PREFERENCES),
),
ConfigFieldSpec(
@@ -210,7 +229,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"reasoning",
"select",
settings_attr="reasoning_sonnet",
- default="inherit",
options=_reasoning_options(ROUTE_REASONING_PREFERENCES),
),
ConfigFieldSpec(
@@ -219,19 +237,29 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"reasoning",
"select",
settings_attr="reasoning_haiku",
- default="inherit",
options=_reasoning_options(ROUTE_REASONING_PREFERENCES),
),
+ ConfigFieldSpec(
+ "PROXY_AUTH_ENABLED",
+ "Require API Authentication",
+ "runtime",
+ "boolean",
+ settings_attr="proxy_auth_enabled",
+ restart_required=True,
+ description="Require the retained API/CLI token on FCC API routes.",
+ ),
ConfigFieldSpec(
"ANTHROPIC_AUTH_TOKEN",
"API/CLI Auth Token",
"runtime",
"secret",
- settings_attr="anthropic_auth_token",
- default="freecc",
+ settings_attr="proxy_auth_token",
secret=True,
restart_required=True,
- description="Bearer token protecting Claude/API access. It is not admin-page login.",
+ description=(
+ "Retained non-empty token passed to every harness. Authentication can be "
+ "disabled without clearing it."
+ ),
),
ConfigFieldSpec(
"PROVIDER_RATE_LIMIT",
@@ -239,7 +267,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"runtime",
"number",
settings_attr="provider_rate_limit",
- default="1",
),
ConfigFieldSpec(
"PROVIDER_RATE_WINDOW",
@@ -247,7 +274,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"runtime",
"number",
settings_attr="provider_rate_window",
- default="3",
),
ConfigFieldSpec(
"PROVIDER_MAX_CONCURRENCY",
@@ -255,7 +281,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"runtime",
"number",
settings_attr="provider_max_concurrency",
- default="5",
),
ConfigFieldSpec(
"HTTP_READ_TIMEOUT",
@@ -263,7 +288,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"runtime",
"number",
settings_attr="http_read_timeout",
- default="300",
),
ConfigFieldSpec(
"HTTP_WRITE_TIMEOUT",
@@ -271,7 +295,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"runtime",
"number",
settings_attr="http_write_timeout",
- default="60",
),
ConfigFieldSpec(
"HTTP_CONNECT_TIMEOUT",
@@ -279,14 +302,12 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"runtime",
"number",
settings_attr="http_connect_timeout",
- default="60",
),
ConfigFieldSpec(
"HOST",
"Server Host",
"runtime",
settings_attr="host",
- default="0.0.0.0",
restart_required=True,
),
ConfigFieldSpec(
@@ -295,7 +316,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"runtime",
"number",
settings_attr="port",
- default="8082",
restart_required=True,
),
ConfigFieldSpec(
@@ -304,7 +324,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"runtime",
"boolean",
settings_attr="open_admin_browser",
- default="true",
description="Open the Admin UI after the next fcc-server launch becomes healthy.",
),
ConfigFieldSpec(
@@ -313,7 +332,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"messaging",
"select",
settings_attr="messaging_platform",
- default="discord",
options=("telegram", "discord", "none"),
session_sensitive=True,
),
@@ -323,7 +341,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"messaging",
"number",
settings_attr="messaging_rate_limit",
- default="1",
session_sensitive=True,
),
ConfigFieldSpec(
@@ -332,7 +349,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"messaging",
"number",
settings_attr="messaging_rate_window",
- default="1",
session_sensitive=True,
),
ConfigFieldSpec(
@@ -399,7 +415,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"voice",
"boolean",
settings_attr="voice_note_enabled",
- default="false",
session_sensitive=True,
),
ConfigFieldSpec(
@@ -408,7 +423,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"voice",
"select",
settings_attr="whisper_device",
- default="nvidia_nim",
options=("cpu", "cuda", "nvidia_nim"),
session_sensitive=True,
),
@@ -417,7 +431,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"Whisper Model",
"voice",
settings_attr="whisper_model",
- default="openai/whisper-large-v3",
session_sensitive=True,
),
ConfigFieldSpec(
@@ -426,7 +439,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"runtime",
"boolean",
settings_attr="fast_prefix_detection",
- default="true",
advanced=True,
),
ConfigFieldSpec(
@@ -435,7 +447,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"runtime",
"boolean",
settings_attr="enable_network_probe_mock",
- default="true",
advanced=True,
),
ConfigFieldSpec(
@@ -444,7 +455,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"runtime",
"boolean",
settings_attr="enable_title_generation_skip",
- default="true",
advanced=True,
),
ConfigFieldSpec(
@@ -453,7 +463,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"runtime",
"boolean",
settings_attr="enable_suggestion_mode_skip",
- default="true",
advanced=True,
),
ConfigFieldSpec(
@@ -462,7 +471,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"runtime",
"boolean",
settings_attr="enable_filepath_extraction_mock",
- default="true",
advanced=True,
),
ConfigFieldSpec(
@@ -471,14 +479,12 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"web_tools",
"boolean",
settings_attr="enable_web_server_tools",
- default="true",
),
ConfigFieldSpec(
"WEB_FETCH_ALLOWED_SCHEMES",
"Allowed Web Fetch Schemes",
"web_tools",
settings_attr="web_fetch_allowed_schemes",
- default="http,https",
),
ConfigFieldSpec(
"WEB_FETCH_ALLOW_PRIVATE_NETWORKS",
@@ -486,7 +492,16 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"web_tools",
"boolean",
settings_attr="web_fetch_allow_private_networks",
- default="false",
+ ),
+ ConfigFieldSpec(
+ "LOG_LEVEL",
+ "Log Level",
+ "diagnostics",
+ "select",
+ settings_attr="log_level",
+ options=("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"),
+ advanced=True,
+ restart_required=True,
),
ConfigFieldSpec(
"DEBUG_PLATFORM_EDITS",
@@ -494,7 +509,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"diagnostics",
"boolean",
settings_attr="debug_platform_edits",
- default="false",
advanced=True,
restart_required=True,
),
@@ -504,7 +518,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"diagnostics",
"boolean",
settings_attr="debug_subagent_stack",
- default="false",
advanced=True,
restart_required=True,
),
@@ -514,7 +527,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"diagnostics",
"boolean",
settings_attr="log_raw_api_payloads",
- default="false",
advanced=True,
restart_required=True,
),
@@ -524,7 +536,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"diagnostics",
"boolean",
settings_attr="log_raw_sse_events",
- default="false",
advanced=True,
),
ConfigFieldSpec(
@@ -533,7 +544,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"diagnostics",
"boolean",
settings_attr="log_api_error_tracebacks",
- default="false",
advanced=True,
restart_required=True,
),
@@ -543,7 +553,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"diagnostics",
"boolean",
settings_attr="log_raw_messaging_content",
- default="false",
advanced=True,
restart_required=True,
),
@@ -553,7 +562,6 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"diagnostics",
"boolean",
settings_attr="log_raw_cli_diagnostics",
- default="false",
advanced=True,
restart_required=True,
),
@@ -563,175 +571,12 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"diagnostics",
"boolean",
settings_attr="log_messaging_error_details",
- default="false",
advanced=True,
restart_required=True,
),
ConfigFieldSpec(
- "FCC_SMOKE_MODEL_NVIDIA_NIM",
- "Smoke NVIDIA NIM Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_OPEN_ROUTER",
- "Smoke OpenRouter Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_MISTRAL",
- "Smoke Mistral Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_MISTRAL_CODESTRAL",
- "Smoke Mistral Codestral Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_DEEPSEEK",
- "Smoke DeepSeek Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_LMSTUDIO",
- "Smoke LM Studio Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_LLAMACPP",
- "Smoke llama.cpp Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_OLLAMA",
- "Smoke Ollama Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_OLLAMA_CLOUD",
- "Smoke Ollama Cloud Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_KIMI",
- "Smoke Kimi Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_MINIMAX",
- "Smoke MiniMax Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_WAFER",
- "Smoke Wafer Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_OPENCODE_ZEN",
- "Smoke OpenCode Zen Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_OPENCODE_GO",
- "Smoke OpenCode Go Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_VERCEL",
- "Smoke Vercel AI Gateway Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_BEDROCK",
- "Smoke Amazon Bedrock Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_HUGGINGFACE",
- "Smoke Hugging Face Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_COHERE",
- "Smoke Cohere Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_GITHUB_MODELS",
- "Smoke GitHub Models Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_ZAI",
- "Smoke Z.ai Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_NARAROUTE",
- "Smoke NaraRoute Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_FIREWORKS",
- "Smoke Fireworks Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_CLOUDFLARE",
- "Smoke Cloudflare Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_GEMINI",
- "Smoke Gemini Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_GROQ",
- "Smoke Groq Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_SAMBANOVA",
- "Smoke SambaNova Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_CEREBRAS",
- "Smoke Cerebras Model",
- "smoke",
- advanced=True,
- ),
- ConfigFieldSpec(
- "FCC_SMOKE_MODEL_TOKENROUTER",
- "Smoke TokenRouter Model",
+ "FCC_SMOKE_MODEL_MISTRAL_REASONING",
+ "Smoke Mistral Reasoning Model",
"smoke",
advanced=True,
),
@@ -762,9 +607,22 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
)
+def _catalog_smoke_fields() -> tuple[ConfigFieldSpec, ...]:
+ return tuple(
+ ConfigFieldSpec(
+ key=f"FCC_SMOKE_MODEL_{provider_id.upper()}",
+ label=f"Smoke {descriptor.display_name} Model",
+ section_id="smoke",
+ advanced=True,
+ )
+ for provider_id, descriptor in PROVIDER_CATALOG.items()
+ )
+
+
FIELDS: tuple[ConfigFieldSpec, ...] = (
*(ConfigFieldSpec(**spec) for spec in provider_field_specs()),
*_NON_PROVIDER_FIELDS,
+ *_catalog_smoke_fields(),
)
FIELD_BY_KEY = {field.key: field for field in FIELDS}
diff --git a/src/free_claude_code/config/admin/persistence.py b/src/free_claude_code/config/admin/persistence.py
index 042f71b7..89444d56 100644
--- a/src/free_claude_code/config/admin/persistence.py
+++ b/src/free_claude_code/config/admin/persistence.py
@@ -1,18 +1,26 @@
-"""Managed env persistence, validation preview, and rendering."""
+"""Sparse managed-config validation, preview, and atomic persistence."""
-import os
from collections.abc import Mapping
from dataclasses import dataclass
from pathlib import Path
from typing import Any
+from free_claude_code.config.env_files import (
+ FCC_CONFIG_SCHEMA_ENV,
+ dotenv_values_from_file,
+)
+from free_claude_code.config.env_migrations import (
+ CONFIG_SCHEMA_VERSION,
+ atomic_write_managed_config,
+ recognized_env_keys,
+ render_managed_config,
+)
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 .manifest import FIELD_BY_KEY
from .validation import settings_from_values
-from .values import MASKED_SECRET, load_value_state, normalize_for_env
+from .values import MASKED_SECRET, is_locked_source, load_value_state, normalize_for_env
@dataclass(frozen=True, slots=True)
@@ -27,13 +35,16 @@ class PreparedAdminUpdate:
@property
def valid(self) -> bool:
- return self.settings is not None
+ return self.settings is not None and not self.errors
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),
+ "env_preview": render_managed_config(
+ self.target_values,
+ mask_secrets=True,
+ ),
}
def applied_response(self) -> dict[str, Any]:
@@ -46,7 +57,7 @@ class PreparedAdminUpdate:
"applied": True,
"valid": True,
"errors": [],
- "env_preview": render_env_file(
+ "env_preview": render_managed_config(
self.target_values,
mask_secrets=True,
),
@@ -56,57 +67,37 @@ class PreparedAdminUpdate:
def target_values_with_updates(updates: Mapping[str, Any]) -> dict[str, str]:
- """Return a managed target after repairing stored state and applying updates."""
+ """Return sparse managed state after applying valid partial-update semantics."""
state = load_value_state()
- values = template_values()
-
- # Preserve existing managed values when present. If no managed config exists,
- # seed the first write from effective repo values to migrate legacy setups.
- managed_values = dotenv_values_from_file(managed_env_path())
- if managed_values:
- values.update(
- {key: val for key, val in managed_values.items() if key in values}
- )
- else:
- for key, entry in state.items():
- if entry["source"] in {"repo_env", "template", "default"}:
- values[key] = str(entry["value"])
-
- # Repair stale editable state before applying the explicit request. Empty
- # select updates then remain intact for normal Settings validation to reject.
- for field in FIELDS:
- values.setdefault(field.key, field.default)
- if field.field_type == "select" and values[field.key] == "" and field.default:
- values[field.key] = field.default
-
- for key, value in updates.items():
+ path = managed_env_path()
+ values = dotenv_values_from_file(path) if path.is_file() else {}
+ known = recognized_env_keys()
+ for key in tuple(values):
+ if key in known and key != FCC_CONFIG_SCHEMA_ENV and not values[key].strip():
+ values.pop(key)
+
+ for key, submitted in updates.items():
field = FIELD_BY_KEY.get(key)
- if field is None:
- continue
- if is_locked_source(state[key]["source"]):
+ if field is None or is_locked_source(state[key]["source"]):
continue
- if field.secret and value == MASKED_SECRET:
+ if field.secret and (
+ submitted == MASKED_SECRET
+ or (isinstance(submitted, str) and not submitted.strip())
+ ):
continue
- values[key] = normalize_for_env(value)
+ value = normalize_for_env(submitted)
+ if value is None or (field.nullable and not value):
+ values.pop(key, None)
+ else:
+ values[key] = value
- return values
-
-
-def effective_values_for_validation(
- target_values: Mapping[str, str],
-) -> dict[str, str]:
- """Return values validated after preserving locked external sources."""
-
- values = dict(target_values)
- for key, entry in load_value_state().items():
- if is_locked_source(entry["source"]):
- values[key] = str(entry["value"])
+ values[FCC_CONFIG_SCHEMA_ENV] = CONFIG_SCHEMA_VERSION
return values
def validate_updates(updates: Mapping[str, Any]) -> dict[str, Any]:
- """Validate partial admin updates and return a masked generated env preview."""
+ """Validate partial Admin updates and return a masked sparse preview."""
return prepare_admin_update(updates).validation_response()
@@ -120,46 +111,42 @@ def changed_pending_fields(
state = load_value_state()
pending: list[str] = []
- for key, value in updates.items():
+ for key, submitted in updates.items():
field = FIELD_BY_KEY.get(key)
if field is None or is_locked_source(state[key]["source"]):
continue
- if field.secret and value == MASKED_SECRET:
+ if field.secret and (
+ submitted == MASKED_SECRET
+ or (isinstance(submitted, str) and not submitted.strip())
+ ):
continue
requires_restart = field.restart_required or field.session_sensitive
if not requires_restart:
requires_restart = _active_voice_credential(settings) == key
if not requires_restart:
continue
- if normalize_for_env(value) == str(state[key]["value"]):
+ if normalize_for_env(submitted) == state[key]["value"]:
continue
pending.append(key)
return pending
-def _active_voice_credential(settings: Settings) -> str | None:
- if not settings.voice_note_enabled:
- return None
- if settings.whisper_device == "nvidia_nim":
- return "NVIDIA_NIM_API_KEY"
- return "HUGGINGFACE_API_KEY"
-
-
def prepare_admin_update(updates: Mapping[str, Any]) -> PreparedAdminUpdate:
"""Validate an update and construct its prospective Settings snapshot."""
+ update_errors = _update_protocol_errors(updates)
target_values = target_values_with_updates(updates)
- effective_values = effective_values_for_validation(target_values)
- settings, errors = settings_from_values(effective_values)
+ settings, settings_errors = settings_from_values(target_values)
+ errors = (*update_errors, *settings_errors)
pending_fields = (
tuple(changed_pending_fields(updates, settings=settings))
- if settings is not None
+ if settings is not None and not errors
else ()
)
return PreparedAdminUpdate(
target_values=target_values,
settings=settings,
- errors=tuple(errors),
+ errors=errors,
pending_fields=pending_fields,
path=managed_env_path(),
)
@@ -170,54 +157,32 @@ def commit_prepared_admin_update(prepared: PreparedAdminUpdate) -> dict[str, Any
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")
- 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)
+ atomic_write_managed_config(prepared.target_values, path=prepared.path)
return prepared.applied_response()
-def quote_env_value(value: str) -> str:
- """Quote a value when dotenv syntax requires it."""
-
- if value == "":
- return ""
- escaped = value.replace("\\", "\\\\").replace('"', '\\"')
- if any(char.isspace() for char in value) or any(
- char in value for char in ('"', "#", "=", "$")
- ):
- return f'"{escaped}"'
- return value
-
-
-def render_env_file(values: Mapping[str, str], *, mask_secrets: bool = False) -> str:
- """Render a complete grouped env file."""
-
- lines: list[str] = [
- "# Managed by Free Claude Code /admin.",
- "# Edit in the server UI when possible.",
- "",
- ]
- fields_by_section: dict[str, list[ConfigFieldSpec]] = {
- section.section_id: [] for section in SECTIONS
- }
- for field in FIELDS:
- fields_by_section.setdefault(field.section_id, []).append(field)
-
- for section in SECTIONS:
- lines.append(f"# {section.label}")
- for field in fields_by_section.get(section.section_id, []):
- value = values.get(field.key, field.default)
- if mask_secrets and field.secret and value:
- value = MASKED_SECRET
- lines.append(f"{field.key}={quote_env_value(value)}")
- lines.append("")
- return "\n".join(lines).rstrip() + "\n"
+def _update_protocol_errors(updates: Mapping[str, Any]) -> tuple[str, ...]:
+ errors: list[str] = []
+ for key, submitted in updates.items():
+ field = FIELD_BY_KEY.get(key)
+ if field is None or (field.secret and submitted == MASKED_SECRET):
+ continue
+ if submitted is None and not field.nullable:
+ errors.append(f"{key}: this setting cannot be removed")
+ continue
+ if (
+ not field.secret
+ and isinstance(submitted, str)
+ and not submitted.strip()
+ and not field.nullable
+ ):
+ errors.append(f"{key}: this setting cannot be blank")
+ return tuple(errors)
+
+
+def _active_voice_credential(settings: Settings) -> str | None:
+ if not settings.voice_note_enabled:
+ return None
+ if settings.whisper_device == "nvidia_nim":
+ return "NVIDIA_NIM_API_KEY"
+ return "HUGGINGFACE_API_KEY"
diff --git a/src/free_claude_code/config/admin/provider_manifest.py b/src/free_claude_code/config/admin/provider_manifest.py
index 14ba4d96..67d09128 100644
--- a/src/free_claude_code/config/admin/provider_manifest.py
+++ b/src/free_claude_code/config/admin/provider_manifest.py
@@ -299,7 +299,6 @@ def _base_url_field_specs() -> tuple[dict[str, Any], ...]:
"label": f"{descriptor.display_name} Base URL",
"section_id": "providers",
"settings_attr": descriptor.base_url_attr,
- "default": descriptor.default_base_url or "",
}
spec.update(_PROVIDER_FIELD_OVERRIDES.get(key, {}))
specs.append(spec)
@@ -337,7 +336,6 @@ def _vertex_field_specs() -> tuple[dict[str, Any], ...]:
"label": "Vertex AI Location",
"section_id": "providers",
"settings_attr": "vertex_location",
- "default": "global",
"description": (
"Use global for the global Vertex AI endpoint or a region such as "
"us-central1."
diff --git a/src/free_claude_code/config/admin/sources.py b/src/free_claude_code/config/admin/sources.py
deleted file mode 100644
index 854538d7..00000000
--- a/src/free_claude_code/config/admin/sources.py
+++ /dev/null
@@ -1,84 +0,0 @@
-"""Admin config source loading and source precedence."""
-
-import os
-from io import StringIO
-from pathlib import Path
-from typing import Literal
-
-from dotenv import dotenv_values
-
-from free_claude_code.config.env_files import (
- explicit_env_path as configured_explicit_env_path,
-)
-from free_claude_code.config.env_files import (
- repo_env_path as configured_repo_env_path,
-)
-from free_claude_code.config.env_files import (
- settings_env_files,
-)
-from free_claude_code.config.env_template import load_env_template_or_empty
-
-from .manifest import FIELDS
-
-SourceType = Literal[
- "default",
- "template",
- "repo_env",
- "managed_env",
- "explicit_env_file",
- "process",
-]
-
-
-def repo_env_path() -> Path:
- """Return the repo-local env path."""
-
- return configured_repo_env_path()
-
-
-def explicit_env_path() -> Path | None:
- """Return the explicit FCC_ENV_FILE path, when configured."""
-
- return configured_explicit_env_path(os.environ)
-
-
-def configured_env_files() -> tuple[tuple[SourceType, Path], ...]:
- """Return dotenv files in low-to-high precedence order."""
-
- source_names: tuple[SourceType, ...] = (
- "repo_env",
- "managed_env",
- "explicit_env_file",
- )
- return tuple(zip(source_names, settings_env_files(), strict=False))
-
-
-def dotenv_values_from_text(text: str) -> dict[str, str]:
- """Parse dotenv text into string values."""
-
- values = dotenv_values(stream=StringIO(text))
- return {key: "" if value is None else value for key, value in values.items()}
-
-
-def template_values() -> dict[str, str]:
- """Return .env.example values plus manifest defaults for newer fields."""
-
- values = dotenv_values_from_text(load_env_template_or_empty())
- for field in FIELDS:
- values.setdefault(field.key, field.default)
- return values
-
-
-def dotenv_values_from_file(path: Path) -> dict[str, str]:
- """Return dotenv values from a file, or an empty mapping when absent."""
-
- if not path.is_file():
- return {}
- values = dotenv_values(path)
- return {key: "" if value is None else value for key, value in values.items()}
-
-
-def is_locked_source(source: SourceType) -> bool:
- """Return whether an admin value source must not be overwritten."""
-
- return source in {"process", "explicit_env_file"}
diff --git a/src/free_claude_code/config/admin/status.py b/src/free_claude_code/config/admin/status.py
index 5bc315e6..a28bca53 100644
--- a/src/free_claude_code/config/admin/status.py
+++ b/src/free_claude_code/config/admin/status.py
@@ -29,7 +29,7 @@ def provider_config_status(
)
continue
if descriptor.local:
- base_url = ""
+ base_url: str | None = None
if descriptor.base_url_attr is not None:
base_url = _value_for_settings_attr(state, descriptor.base_url_attr)
statuses.append(
@@ -37,8 +37,8 @@ def provider_config_status(
"provider_id": provider_id,
"display_name": descriptor.display_name,
"kind": "local",
- "status": "missing_url" if not base_url.strip() else "unknown",
- "label": "Missing URL" if not base_url.strip() else "Not checked",
+ "status": "missing_url" if not base_url else "unknown",
+ "label": "Missing URL" if not base_url else "Not checked",
"base_url": base_url or descriptor.default_base_url or "",
}
)
@@ -48,7 +48,7 @@ def provider_config_status(
missing_attrs = tuple(
attr
for attr in configuration_attrs
- if not _value_for_settings_attr(state, attr).strip()
+ if not _value_for_settings_attr(state, attr)
)
configured = not missing_attrs
configuration = " + ".join(
@@ -82,11 +82,12 @@ def provider_config_status(
def _value_for_settings_attr(
state: Mapping[str, Mapping[str, Any]], settings_attr: str
-) -> str:
+) -> str | None:
for field in FIELDS:
if field.settings_attr == settings_attr:
- return str(state.get(field.key, {}).get("value", field.default))
- return ""
+ value = state.get(field.key, {}).get("value", field.resolved_default())
+ return str(value) if value is not None else None
+ return None
def _field_key_for_settings_attr(settings_attr: str) -> str:
diff --git a/src/free_claude_code/config/admin/validation.py b/src/free_claude_code/config/admin/validation.py
index c37c5d59..45716d71 100644
--- a/src/free_claude_code/config/admin/validation.py
+++ b/src/free_claude_code/config/admin/validation.py
@@ -1,14 +1,12 @@
"""Settings-backed Admin config validation."""
from collections.abc import Mapping
-from typing import Any
from pydantic import ValidationError
+from free_claude_code.config.loader import compose_settings_snapshot
from free_claude_code.config.settings import Settings
-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."""
@@ -22,15 +20,8 @@ def settings_from_values(
) -> 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)
- if input_key is None:
- continue
- kwargs[input_key] = values.get(field.key, "")
-
try:
- return Settings(**kwargs), []
+ return compose_settings_snapshot(values).settings, []
except ValidationError as exc:
return None, format_validation_errors(exc)
diff --git a/src/free_claude_code/config/admin/values.py b/src/free_claude_code/config/admin/values.py
index 328bf701..db707e47 100644
--- a/src/free_claude_code/config/admin/values.py
+++ b/src/free_claude_code/config/admin/values.py
@@ -1,84 +1,78 @@
"""Admin config value state and API response assembly."""
import os
+from enum import Enum
from typing import Any
+from free_claude_code.config.env_files import dotenv_values_from_file
+from free_claude_code.config.loader import ConfigSource, resolve_settings_snapshot
from free_claude_code.config.paths import managed_env_path
-from .manifest import (
- FIELD_BY_KEY,
- FIELDS,
- SECTIONS,
- ConfigFieldSpec,
- ConfigOptionSpec,
-)
-from .sources import (
- configured_env_files,
- dotenv_values_from_file,
- explicit_env_path,
- is_locked_source,
- repo_env_path,
- template_values,
-)
+from .manifest import FIELDS, SECTIONS, ConfigFieldSpec, ConfigOptionSpec
from .status import provider_config_status
MASKED_SECRET = "********"
ValueState = dict[str, dict[str, Any]]
-def normalize_for_env(value: Any) -> str:
- """Normalize a submitted admin value for dotenv persistence."""
+def normalize_for_env(value: Any) -> str | None:
+ """Normalize a submitted Admin value for sparse dotenv persistence."""
if value is None:
- return ""
+ return None
if isinstance(value, bool):
return "true" if value else "false"
- return str(value)
+ if isinstance(value, Enum):
+ return str(value.value)
+ return str(value).strip()
-def display_value(field: ConfigFieldSpec, value: str) -> str:
- """Return the Admin UI display value for a raw config value."""
+def display_value(field: ConfigFieldSpec, value: str | None) -> str | None:
+ """Return the Admin UI display value for a canonical config value."""
- if field.secret and value:
+ if field.secret and value is not None:
return MASKED_SECRET
return value
-def load_value_state() -> ValueState:
- """Load effective admin field values and their sources."""
+def is_locked_source(source: str | ConfigSource) -> bool:
+ """Return whether process ownership makes an Admin field read-only."""
- values = template_values()
- sources = {key: "template" if key in values else "default" for key in FIELD_BY_KEY}
+ return str(source) == ConfigSource.PROCESS.value
- for source, path in configured_env_files():
- file_values = dotenv_values_from_file(path)
- for key, value in file_values.items():
- if key in FIELD_BY_KEY:
- values[key] = value
- sources[key] = source
- for key in FIELD_BY_KEY:
- if key in os.environ:
- values[key] = os.environ[key]
- sources[key] = "process"
+def load_value_state() -> ValueState:
+ """Load effective Admin values from the canonical Settings resolver."""
- return {
- key: {
- "value": values.get(key, ""),
- "source": sources.get(key, "default"),
- }
- for key in FIELD_BY_KEY
- }
+ snapshot = resolve_settings_snapshot()
+ managed_path = managed_env_path()
+ managed = dotenv_values_from_file(managed_path) if managed_path.is_file() else {}
+ state: ValueState = {}
+ for field in FIELDS:
+ if field.settings_attr is not None:
+ value = normalize_for_env(getattr(snapshot.settings, field.settings_attr))
+ source = snapshot.sources[field.settings_attr].value
+ elif field.key in os.environ:
+ value = os.environ[field.key].strip() or None
+ source = ConfigSource.PROCESS.value
+ elif field.key in managed:
+ value = managed[field.key].strip() or None
+ source = ConfigSource.MANAGED.value
+ else:
+ value = field.resolved_default()
+ source = ConfigSource.DEFAULT.value
+ state[field.key] = {"value": value, "source": source}
+ return state
def load_config_response() -> dict[str, Any]:
- """Return manifest and current config values for the admin UI."""
+ """Return manifest and current config values for the Admin UI."""
state = load_value_state()
fields: list[dict[str, Any]] = []
for field in FIELDS:
entry = state[field.key]
- source = entry["source"]
+ source = str(entry["source"])
raw_value = entry["value"]
fields.append(
{
@@ -87,9 +81,10 @@ def load_config_response() -> dict[str, Any]:
"section": field.section_id,
"type": field.field_type,
"value": display_value(field, raw_value),
- "configured": bool(str(raw_value).strip()),
+ "configured": raw_value is not None,
"source": source,
"locked": is_locked_source(source),
+ "nullable": field.nullable,
"secret": field.secret,
"advanced": field.advanced,
"restart_required": field.restart_required,
@@ -117,10 +112,6 @@ def load_config_response() -> dict[str, Any]:
for section in SECTIONS
],
"fields": fields,
- "paths": {
- "managed": str(managed_env_path()),
- "repo": str(repo_env_path()),
- "explicit": str(explicit_env_path()) if explicit_env_path() else None,
- },
+ "paths": {"managed": str(managed_env_path())},
"provider_status": provider_config_status(state),
}
diff --git a/src/free_claude_code/config/env_files.py b/src/free_claude_code/config/env_files.py
index c6830219..ccba0850 100644
--- a/src/free_claude_code/config/env_files.py
+++ b/src/free_claude_code/config/env_files.py
@@ -1,91 +1,74 @@
-"""Dotenv file discovery and explicit dotenv override helpers."""
+"""Managed and legacy dotenv discovery helpers."""
import os
from collections.abc import Mapping
+from io import StringIO
from pathlib import Path
-from typing import Any
from dotenv import dotenv_values
+from dotenv.parser import parse_stream
-from .paths import managed_env_path
-
+FCC_ENV_FILE_ENV = "FCC_ENV_FILE"
+FCC_CONFIG_SCHEMA_ENV = "FCC_CONFIG_SCHEMA"
ANTHROPIC_AUTH_TOKEN_ENV = "ANTHROPIC_AUTH_TOKEN"
+PROXY_AUTH_ENABLED_ENV = "PROXY_AUTH_ENABLED"
-def repo_env_path() -> Path:
- """Return the repo-local env path."""
-
- return Path(".env")
-
-
-def explicit_env_path(env: Mapping[str, str] | None = None) -> Path | None:
- """Return the explicit FCC_ENV_FILE path, when configured."""
+def legacy_explicit_env_path(
+ env: Mapping[str, str] | None = None,
+) -> Path | None:
+ """Return the pre-schema explicit dotenv import path, when configured."""
source = env if env is not None else os.environ
- if explicit := source.get("FCC_ENV_FILE"):
- return Path(explicit)
- return None
-
-
-def settings_env_files(env: Mapping[str, str] | None = None) -> tuple[Path, ...]:
- """Return Settings dotenv files in low-to-high precedence order."""
-
- files: list[Path] = [
- repo_env_path(),
- managed_env_path(),
- ]
- if explicit := explicit_env_path(env):
- files.append(explicit)
- return tuple(files)
-
-
-def configured_env_files(model_config: Mapping[str, Any]) -> tuple[Path, ...]:
- """Return the env files currently configured for a Settings model."""
+ value = source.get(FCC_ENV_FILE_ENV, "").strip()
+ return Path(value).expanduser() if value else None
- configured = model_config.get("env_file")
- if configured is None:
- return ()
- if isinstance(configured, (str, Path)):
- return (Path(configured),)
- return tuple(Path(item) for item in configured)
+def verified_checkout_env_path() -> Path | None:
+ """Return this package checkout's legacy dotenv, never the caller's CWD."""
-def env_file_value(path: Path, key: str) -> str | None:
- """Return a dotenv value when the file explicitly defines the key."""
-
- if not path.is_file():
+ checkout = Path(__file__).resolve().parents[3]
+ package = checkout / "src" / "free_claude_code"
+ pyproject = checkout / "pyproject.toml"
+ if package != Path(__file__).resolve().parents[1]:
+ return None
+ if not pyproject.is_file():
return None
-
try:
- values = dotenv_values(path)
+ project_text = pyproject.read_text(encoding="utf-8")
except OSError:
return None
-
- if key not in values:
+ if 'name = "free-claude-code"' not in project_text:
return None
- value = values[key]
- return "" if value is None else value
+ env_path = checkout / ".env"
+ return env_path if env_path.is_file() else None
-def env_file_override(model_config: Mapping[str, Any], key: str) -> str | None:
- """Return the last configured dotenv value that explicitly defines a key."""
+def dotenv_values_from_text(text: str) -> dict[str, str]:
+ """Parse dotenv text while preserving explicit blank assignments."""
- configured_value: str | None = None
- for env_file in configured_env_files(model_config):
- value = env_file_value(env_file, key)
- if value is not None:
- configured_value = value
- return configured_value
+ malformed = next(
+ (binding for binding in parse_stream(StringIO(text)) if binding.error),
+ None,
+ )
+ if malformed is not None:
+ raise ValueError(f"Invalid dotenv syntax on line {malformed.original.line}")
+ parsed = dotenv_values(stream=StringIO(text), interpolate=False)
+ return {key: "" if value is None else value for key, value in parsed.items()}
-def process_env_key_is_effective(
- model_config: Mapping[str, Any],
- key: str,
- env: Mapping[str, str] | None = None,
-) -> bool:
- """Return whether a key is coming from process env instead of configured dotenv."""
+def dotenv_values_from_file(path: Path) -> dict[str, str]:
+ """Parse a dotenv file, raising an actionable error when it cannot be read."""
- source = env if env is not None else os.environ
- if env_file_override(model_config, key) is not None:
- return False
- return key in source
+ if not path.exists():
+ raise FileNotFoundError(f"Configuration file does not exist: {path}")
+ if not path.is_file():
+ raise ValueError(f"Configuration path is not a file: {path}")
+ try:
+ text = path.read_text(encoding="utf-8")
+ except OSError as exc:
+ raise OSError(f"Could not read configuration file {path}: {exc}") from exc
+ try:
+ return dotenv_values_from_text(text)
+ except ValueError as exc:
+ raise ValueError(f"Could not parse configuration file {path}: {exc}") from exc
diff --git a/src/free_claude_code/config/env_migrations.py b/src/free_claude_code/config/env_migrations.py
index ae8c29d7..d9c84f63 100644
--- a/src/free_claude_code/config/env_migrations.py
+++ b/src/free_claude_code/config/env_migrations.py
@@ -1,13 +1,25 @@
-"""One-time dotenv migrations for FCC-owned config files."""
+"""One-time consolidation of legacy FCC dotenv state."""
+import os
import re
from collections.abc import Mapping
from dataclasses import dataclass
from pathlib import Path
-from .env_files import explicit_env_path, repo_env_path
-from .paths import managed_env_path
+from .env_files import (
+ ANTHROPIC_AUTH_TOKEN_ENV,
+ FCC_CONFIG_SCHEMA_ENV,
+ PROXY_AUTH_ENABLED_ENV,
+ dotenv_values_from_file,
+ dotenv_values_from_text,
+ legacy_explicit_env_path,
+ verified_checkout_env_path,
+)
+from .paths import legacy_env_paths, managed_env_path
+from .provider_catalog import PROVIDER_CATALOG
+from .settings import Settings
+CONFIG_SCHEMA_VERSION = "1"
LEGACY_HUGGINGFACE_TOKEN_ENV = "HF_TOKEN"
HUGGINGFACE_API_KEY_ENV = "HUGGINGFACE_API_KEY"
LEGACY_OPENCODE_PROXY_ENV = "OPENCODE_PROXY"
@@ -15,6 +27,15 @@ OPENCODE_ZEN_PROXY_ENV = "OPENCODE_ZEN_PROXY"
LEGACY_OPENCODE_SMOKE_MODEL_ENV = "FCC_SMOKE_MODEL_OPENCODE"
OPENCODE_ZEN_SMOKE_MODEL_ENV = "FCC_SMOKE_MODEL_OPENCODE_ZEN"
+_SPECIAL_SMOKE_KEYS = frozenset(
+ {
+ "FCC_SMOKE_MODEL_MISTRAL_REASONING",
+ "FCC_SMOKE_NIM_MODELS",
+ "FCC_SMOKE_NIM_EXTRA_MODELS",
+ "FCC_SMOKE_OPENROUTER_FREE_MODELS",
+ "FCC_SMOKE_OPENROUTER_FREE_EXTRA_MODELS",
+ }
+)
_DOTENV_ASSIGNMENT_RE = re.compile(
r"^(?P<prefix>\s*(?:export\s+)?)(?P<key>[A-Za-z_][A-Za-z0-9_]*)(?P<suffix>\s*(?:=|$))"
)
@@ -30,6 +51,14 @@ class EnvMigration:
value_prefix_map: tuple[tuple[str, str], ...] = ()
+@dataclass(frozen=True, slots=True)
+class ConfigMigrationResult:
+ """Outcome of one managed-config consolidation attempt."""
+
+ changed: bool
+ imported_from: tuple[Path, ...] = ()
+
+
HUGGINGFACE_TOKEN_MIGRATION = EnvMigration(
old_key=LEGACY_HUGGINGFACE_TOKEN_ENV,
new_key=HUGGINGFACE_API_KEY_ENV,
@@ -89,63 +118,196 @@ ENV_MIGRATIONS = (
*OPENCODE_ZEN_KEY_MIGRATIONS,
*OPENCODE_ZEN_MODEL_REF_MIGRATIONS,
)
+_RETIRED_ENV_KEYS = frozenset(
+ migration.old_key
+ for migration in ENV_MIGRATIONS
+ if migration.old_key != migration.new_key
+)
-def migrate_owned_env_files() -> tuple[Path, ...]:
- """Apply config migrations to repo and managed dotenv files."""
+def settings_env_keys() -> frozenset[str]:
+ """Return the explicit environment aliases owned by Settings."""
- changed_paths: list[Path] = []
- for path in _unique_paths((repo_env_path(), managed_env_path())):
- changed = False
- for migration in ENV_MIGRATIONS:
- changed = migrate_env_setting_in_file(path, migration) or changed
- if changed:
- changed_paths.append(path.resolve())
- return tuple(changed_paths)
+ keys: set[str] = set()
+ for name, field in Settings.model_fields.items():
+ if name == "nim":
+ continue
+ alias = field.validation_alias
+ if not isinstance(alias, str):
+ raise AssertionError(f"Settings field {name!r} needs one string alias")
+ keys.add(alias)
+ return frozenset(keys)
-def explicit_env_file_migration_warning(
- env: Mapping[str, str] | None = None,
-) -> str | None:
- """Return a warning when an explicit env file uses a retired setting."""
-
- path = explicit_env_path(env)
- if path is None or not path.is_file():
- return None
- text = path.read_text(encoding="utf-8")
- pending = tuple(
- migration
+def smoke_env_keys() -> frozenset[str]:
+ """Return catalog-derived and special live-smoke configuration keys."""
+
+ catalog_keys = {
+ f"FCC_SMOKE_MODEL_{provider_id.upper()}" for provider_id in PROVIDER_CATALOG
+ }
+ return frozenset(catalog_keys) | _SPECIAL_SMOKE_KEYS
+
+
+def recognized_env_keys() -> frozenset[str]:
+ """Return every dotenv key FCC may import into managed configuration."""
+
+ migrated_keys = {
+ key
for migration in ENV_MIGRATIONS
- if env_text_needs_migration(text, migration)
- )
- if not pending:
- return None
- actions: list[str] = []
- for migration in pending:
- if migration.old_key != migration.new_key:
- actions.append(f"rename {migration.old_key} to {migration.new_key}")
- actions.extend(
- f"replace {old_prefix} with {new_prefix} in {migration.new_key}"
- for old_prefix, new_prefix in migration.value_prefix_map
- )
+ for key in (migration.old_key, migration.new_key)
+ }
return (
- f"Explicit FCC_ENV_FILE {path} uses retired settings. "
- f"{'; '.join(actions)}; "
- "explicit env files are not rewritten automatically."
+ settings_env_keys() | smoke_env_keys() | migrated_keys | {FCC_CONFIG_SCHEMA_ENV}
)
-def migrate_env_setting_in_file(path: Path, migration: EnvMigration) -> bool:
- """Apply one setting migration to ``path``."""
+def secret_env_keys() -> frozenset[str]:
+ """Return settings aliases whose values must be masked in previews."""
- if not path.is_file():
- return False
- original = path.read_text(encoding="utf-8")
- migrated, changed = migrate_env_setting_in_text(original, migration)
- if not changed:
- return False
- path.write_text(migrated, encoding="utf-8")
- return True
+ secret_attrs = {
+ name
+ for name in Settings.model_fields
+ if name.endswith(("_api_key", "_proxy", "_token"))
+ }
+ secret_attrs.update({"telegram_proxy_url", "proxy_auth_token"})
+ return frozenset(
+ str(Settings.model_fields[name].validation_alias) for name in secret_attrs
+ )
+
+
+def consolidate_managed_config(
+ env: Mapping[str, str] | None = None,
+) -> ConfigMigrationResult:
+ """Consolidate pre-schema configuration into ``~/.fcc/.env`` once."""
+
+ process = env if env is not None else os.environ
+ managed = managed_env_path()
+ base_path: Path | None = managed if managed.exists() else _legacy_base_path()
+ base_is_managed = base_path == managed
+ base_text = _read_text(base_path) if base_path is not None else ""
+ base_values = dotenv_values_from_text(base_text)
+
+ if base_is_managed:
+ schema = base_values.get(FCC_CONFIG_SCHEMA_ENV)
+ if schema == CONFIG_SCHEMA_VERSION:
+ return ConfigMigrationResult(changed=False)
+ if schema not in {None, ""}:
+ raise ValueError(
+ f"Managed config {managed} uses unsupported schema {schema!r}; "
+ f"this FCC version supports {CONFIG_SCHEMA_VERSION}."
+ )
+
+ known = recognized_env_keys()
+ base_values = _migrated_values(base_text)
+ values = (
+ dict(base_values)
+ if base_is_managed
+ else {key: value for key, value in base_values.items() if key in known}
+ )
+ imported: list[Path] = []
+ if base_path is not None and not base_is_managed:
+ imported.append(base_path.resolve())
+
+ explicit_path = legacy_explicit_env_path(process)
+ if explicit_path is not None and not _same_path(explicit_path, managed):
+ explicit_values = _migrated_values(_read_required_text(explicit_path))
+ values.update(
+ {key: value for key, value in explicit_values.items() if key in known}
+ )
+ imported.append(explicit_path.resolve())
+
+ for key in _RETIRED_ENV_KEYS:
+ values.pop(key, None)
+ values.pop(FCC_CONFIG_SCHEMA_ENV, None)
+ _materialize_auth_state(values, process, had_legacy_state=base_path is not None)
+ for key in tuple(values):
+ if key in known and key != FCC_CONFIG_SCHEMA_ENV and not values[key].strip():
+ values.pop(key)
+ values[FCC_CONFIG_SCHEMA_ENV] = CONFIG_SCHEMA_VERSION
+
+ atomic_write_managed_config(values, path=managed)
+ return ConfigMigrationResult(changed=True, imported_from=tuple(imported))
+
+
+def atomic_write_managed_config(
+ values: Mapping[str, str],
+ *,
+ path: Path | None = None,
+ mask_secrets: bool = False,
+) -> str:
+ """Atomically write canonical managed config and return the rendered text."""
+
+ target = path or managed_env_path()
+ rendered = render_managed_config(values, mask_secrets=mask_secrets)
+ if mask_secrets:
+ return rendered
+
+ target.parent.mkdir(parents=True, exist_ok=True)
+ temp_path = target.with_name(f".{target.name}.{os.getpid()}.tmp")
+ try:
+ with temp_path.open("w", encoding="utf-8", newline="\n") as handle:
+ handle.write(rendered)
+ handle.flush()
+ os.fsync(handle.fileno())
+ if os.name != "nt":
+ temp_path.chmod(0o600)
+ os.replace(temp_path, target)
+ if os.name != "nt":
+ target.chmod(0o600)
+ finally:
+ temp_path.unlink(missing_ok=True)
+ return rendered
+
+
+def render_managed_config(
+ values: Mapping[str, str],
+ *,
+ mask_secrets: bool = False,
+) -> str:
+ """Render sparse canonical FCC configuration."""
+
+ known = recognized_env_keys()
+ secret_keys = secret_env_keys()
+ canonical = dict(values)
+ canonical[FCC_CONFIG_SCHEMA_ENV] = CONFIG_SCHEMA_VERSION
+ lines = [
+ "# Managed by Free Claude Code.",
+ "# Edit settings in /admin when possible.",
+ f"{FCC_CONFIG_SCHEMA_ENV}={CONFIG_SCHEMA_VERSION}",
+ ]
+ configured = [
+ key
+ for key in canonical
+ if key != FCC_CONFIG_SCHEMA_ENV and key in known and canonical[key].strip()
+ ]
+ if configured:
+ lines.extend(("", "# Configured settings"))
+ for key in sorted(configured):
+ value = (
+ "********" if mask_secrets and key in secret_keys else canonical[key]
+ )
+ lines.append(f"{key}={quote_env_value(value)}")
+
+ unknown = [key for key in canonical if key not in known]
+ if unknown:
+ lines.extend(("", "# Preserved unrecognized settings"))
+ lines.extend(
+ f"{key}={quote_env_value(canonical[key])}" for key in sorted(unknown)
+ )
+ return "\n".join(lines) + "\n"
+
+
+def quote_env_value(value: str) -> str:
+ """Quote a value when dotenv syntax requires it."""
+
+ escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+ if (
+ not value
+ or any(char.isspace() for char in value)
+ or any(char in value for char in ('"', "#", "=", "$"))
+ ):
+ return f'"{escaped}"'
+ return value
def migrate_env_setting_in_text(
@@ -187,6 +349,61 @@ def env_text_needs_migration(text: str, migration: EnvMigration) -> bool:
return migrate_env_setting_in_text(text, migration)[1]
+def _legacy_base_path() -> Path | None:
+ for path in legacy_env_paths():
+ if path.is_file():
+ return path
+ return verified_checkout_env_path()
+
+
+def _read_text(path: Path | None) -> str:
+ return "" if path is None else _read_required_text(path)
+
+
+def _read_required_text(path: Path) -> str:
+ dotenv_values_from_file(path)
+ try:
+ return path.read_text(encoding="utf-8")
+ except OSError as exc:
+ raise OSError(f"Could not read configuration file {path}: {exc}") from exc
+
+
+def _migrated_values(text: str) -> dict[str, str]:
+ migrated = text
+ for migration in ENV_MIGRATIONS:
+ migrated, _ = migrate_env_setting_in_text(migrated, migration)
+ return dotenv_values_from_text(migrated)
+
+
+def _materialize_auth_state(
+ values: dict[str, str],
+ process: Mapping[str, str],
+ *,
+ had_legacy_state: bool,
+) -> None:
+ if PROXY_AUTH_ENABLED_ENV in values:
+ return
+ if PROXY_AUTH_ENABLED_ENV in process:
+ return
+ if ANTHROPIC_AUTH_TOKEN_ENV in values:
+ values[PROXY_AUTH_ENABLED_ENV] = (
+ "true" if values[ANTHROPIC_AUTH_TOKEN_ENV].strip() else "false"
+ )
+ return
+ process_token = process.get(ANTHROPIC_AUTH_TOKEN_ENV, "").strip()
+ if process_token:
+ values[PROXY_AUTH_ENABLED_ENV] = "true"
+ elif had_legacy_state:
+ values[PROXY_AUTH_ENABLED_ENV] = "false"
+
+
+def _same_path(left: Path, right: Path) -> bool:
+ try:
+ return left.resolve() == right.resolve()
+ except OSError:
+ return left == right
+
+
def _defines_key(text: str, key: str) -> bool:
for line in text.splitlines():
if line.lstrip().startswith("#"):
@@ -198,8 +415,6 @@ def _defines_key(text: str, key: str) -> bool:
def _mapped_value(value: str, mapping: tuple[tuple[str, str], ...]) -> str:
- """Map a simple dotenv value while preserving comments and line endings."""
-
line = value.rstrip("\r\n")
newline = value[len(line) :]
raw_value, separator, comment = line.partition("#")
@@ -212,8 +427,6 @@ def _mapped_value(value: str, mapping: tuple[tuple[str, str], ...]) -> str:
def _mapped_prefix_value(value: str, old_prefix: str, new_prefix: str) -> str:
- """Rewrite one simple dotenv value while preserving its original syntax."""
-
pattern = rf"^(?P<leading>\s*['\"]?){re.escape(old_prefix)}"
return re.sub(
pattern,
@@ -221,18 +434,3 @@ def _mapped_prefix_value(value: str, old_prefix: str, new_prefix: str) -> str:
value,
count=1,
)
-
-
-def _unique_paths(paths: tuple[Path, ...]) -> tuple[Path, ...]:
- seen: set[Path] = set()
- unique: list[Path] = []
- for path in paths:
- try:
- resolved = path.resolve()
- except OSError:
- resolved = path
- if resolved in seen:
- continue
- seen.add(resolved)
- unique.append(path)
- return tuple(unique)
diff --git a/src/free_claude_code/config/env_template.py b/src/free_claude_code/config/env_template.py
deleted file mode 100644
index 77845e98..00000000
--- a/src/free_claude_code/config/env_template.py
+++ /dev/null
@@ -1,29 +0,0 @@
-"""Canonical env template loading for init and Admin UI defaults."""
-
-import importlib.resources
-from pathlib import Path
-
-
-def load_env_template() -> str:
- """Load the root ``.env.example`` template from wheel resources or checkout."""
-
- packaged = importlib.resources.files("free_claude_code.config").joinpath(
- "env.example"
- )
- if packaged.is_file():
- return packaged.read_text("utf-8")
-
- source_template = Path(__file__).resolve().parents[3] / ".env.example"
- if source_template.is_file():
- return source_template.read_text(encoding="utf-8")
-
- raise FileNotFoundError("Could not find bundled or source .env.example template.")
-
-
-def load_env_template_or_empty() -> str:
- """Return the env template, or an empty template when unavailable."""
-
- try:
- return load_env_template()
- except FileNotFoundError:
- return ""
diff --git a/src/free_claude_code/config/loader.py b/src/free_claude_code/config/loader.py
new file mode 100644
index 00000000..183d92fb
--- /dev/null
+++ b/src/free_claude_code/config/loader.py
@@ -0,0 +1,116 @@
+"""Canonical managed-config loading, precedence, provenance, and caching."""
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from functools import lru_cache
+from types import MappingProxyType
+
+from free_claude_code.core.interprocess_lock import InterprocessFileLock
+
+from .env_files import ANTHROPIC_AUTH_TOKEN_ENV, dotenv_values_from_file
+from .env_migrations import consolidate_managed_config, settings_env_keys
+from .paths import config_lock_path, managed_env_path
+from .settings import Settings
+
+
+class ConfigSource(StrEnum):
+ """Live owner of one effective setting value."""
+
+ DEFAULT = "default"
+ MANAGED = "managed_env"
+ PROCESS = "process"
+
+
+@dataclass(frozen=True, slots=True)
+class SettingsSnapshot:
+ """One validated settings model and its effective field provenance."""
+
+ settings: Settings
+ sources: Mapping[str, ConfigSource]
+
+
+def resolve_settings_snapshot(
+ env: Mapping[str, str] | None = None,
+) -> SettingsSnapshot:
+ """Resolve one uncached Settings snapshot from managed and process state."""
+
+ process = env if env is not None else os.environ
+ lock = InterprocessFileLock(config_lock_path())
+ if not lock.acquire(wait=True, timeout=10.0):
+ raise TimeoutError(
+ f"Could not acquire managed-config lock: {config_lock_path()}"
+ )
+ try:
+ consolidate_managed_config(process)
+ finally:
+ lock.release()
+
+ managed_path = managed_env_path()
+ managed = dotenv_values_from_file(managed_path) if managed_path.is_file() else {}
+ return compose_settings_snapshot(managed, process)
+
+
+def compose_settings_snapshot(
+ managed: Mapping[str, str],
+ env: Mapping[str, str] | None = None,
+) -> SettingsSnapshot:
+ """Validate prospective managed values with live process precedence."""
+
+ process = env if env is not None else os.environ
+ aliases = _settings_aliases()
+ recognized = settings_env_keys()
+ values: dict[str, str] = {
+ key: value for key, value in managed.items() if key in recognized
+ }
+ sources = dict.fromkeys(Settings.model_fields, ConfigSource.DEFAULT)
+ for key in values:
+ if name := aliases.get(key):
+ sources[name] = ConfigSource.MANAGED
+
+ managed_owns_token = bool(values.get(ANTHROPIC_AUTH_TOKEN_ENV, "").strip())
+ for key in recognized:
+ if key not in process:
+ continue
+ if key == ANTHROPIC_AUTH_TOKEN_ENV and managed_owns_token:
+ continue
+ value = process[key]
+ if key == ANTHROPIC_AUTH_TOKEN_ENV and not value.strip():
+ values.pop(key, None)
+ sources[aliases[key]] = ConfigSource.DEFAULT
+ continue
+ values[key] = value
+ if name := aliases.get(key):
+ sources[name] = ConfigSource.PROCESS
+
+ settings = Settings.model_validate(values)
+ return SettingsSnapshot(
+ settings=settings,
+ sources=MappingProxyType(sources),
+ )
+
+
+@lru_cache
+def get_settings() -> Settings:
+ """Return the process-wide cached settings model."""
+
+ return resolve_settings_snapshot().settings
+
+
+def clear_settings_cache() -> None:
+ """Discard the runtime Settings cache after a committed configuration change."""
+
+ get_settings.cache_clear()
+
+
+def _settings_aliases() -> dict[str, str]:
+ aliases: dict[str, str] = {}
+ for name, field in Settings.model_fields.items():
+ if name == "nim":
+ continue
+ alias = field.validation_alias
+ if not isinstance(alias, str):
+ raise AssertionError(f"Settings field {name!r} needs one string alias")
+ aliases[alias] = name
+ return aliases
diff --git a/src/free_claude_code/config/paths.py b/src/free_claude_code/config/paths.py
index 87202ea2..8e9d640e 100644
--- a/src/free_claude_code/config/paths.py
+++ b/src/free_claude_code/config/paths.py
@@ -13,6 +13,7 @@ CODEX_MODEL_CATALOG_FILENAME = "codex-model-catalog.json"
AUTH_DIRNAME = "auth"
OPENAI_AUTH_FILENAME = "openai.json"
OPENAI_AUTH_LOCK_FILENAME = "openai.lock"
+CONFIG_LOCK_FILENAME = "config.lock"
def config_dir_path() -> Path:
@@ -27,6 +28,12 @@ def managed_env_path() -> Path:
return config_dir_path() / FCC_ENV_FILENAME
+def config_lock_path() -> Path:
+ """Return the cross-process managed-config migration lock path."""
+
+ return config_dir_path() / CONFIG_LOCK_FILENAME
+
+
def legacy_env_paths() -> tuple[Path, ...]:
"""Return legacy user env paths that can be migrated to ~/.fcc/.env."""
diff --git a/src/free_claude_code/config/settings.py b/src/free_claude_code/config/settings.py
index b0dcc7b6..630c12fc 100644
--- a/src/free_claude_code/config/settings.py
+++ b/src/free_claude_code/config/settings.py
@@ -1,17 +1,18 @@
-"""Flat application settings schema loaded by Pydantic Settings."""
-
-from functools import lru_cache
-from typing import Any
-
-from pydantic import Field, field_validator, model_validator
-from pydantic_settings import BaseSettings, SettingsConfigDict
+"""Pure, validated application settings schema."""
+
+from typing import Annotated, Any
+
+from pydantic import (
+ BaseModel,
+ BeforeValidator,
+ ConfigDict,
+ Field,
+ StringConstraints,
+ field_validator,
+ model_validator,
+)
from .constants import HTTP_CONNECT_TIMEOUT_DEFAULT
-from .env_files import (
- ANTHROPIC_AUTH_TOKEN_ENV,
- env_file_override,
- settings_env_files,
-)
from .nim import NimSettings
from .provider_catalog import (
BEDROCK_DEFAULT_BASE,
@@ -22,154 +23,246 @@ from .provider_catalog import (
from .reasoning import ReasoningPreference
-class Settings(BaseSettings):
- """Application settings loaded from environment variables."""
+def _empty_to_none(value: Any) -> Any:
+ if isinstance(value, str) and not value.strip():
+ return None
+ return value
+
+
+NonEmptyString = Annotated[
+ str,
+ StringConstraints(strip_whitespace=True, min_length=1),
+]
+OptionalNonEmptyString = Annotated[
+ NonEmptyString | None,
+ BeforeValidator(_empty_to_none),
+]
+
+
+class Settings(BaseModel):
+ """Validated application settings with no file or process I/O."""
+
+ model_config = ConfigDict(
+ validate_default=True,
+ populate_by_name=True,
+ extra="ignore",
+ )
# ==================== Azure OpenAI ====================
- azure_openai_api_key: str = Field(
- default="", validation_alias="AZURE_OPENAI_API_KEY"
+ azure_openai_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="AZURE_OPENAI_API_KEY"
)
- azure_openai_base_url: str = Field(
- default="", validation_alias="AZURE_OPENAI_BASE_URL"
+ azure_openai_base_url: OptionalNonEmptyString = Field(
+ default=None, validation_alias="AZURE_OPENAI_BASE_URL"
)
# ==================== OpenRouter Config ====================
- open_router_api_key: str = Field(default="", validation_alias="OPENROUTER_API_KEY")
+ open_router_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="OPENROUTER_API_KEY"
+ )
# ==================== Mistral La Plateforme ====================
- mistral_api_key: str = Field(default="", validation_alias="MISTRAL_API_KEY")
+ mistral_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="MISTRAL_API_KEY"
+ )
# ==================== Mistral Codestral (codestral.mistral.ai) ====================
- codestral_api_key: str = Field(default="", validation_alias="CODESTRAL_API_KEY")
+ codestral_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="CODESTRAL_API_KEY"
+ )
# ==================== DeepSeek Config ====================
- deepseek_api_key: str = Field(default="", validation_alias="DEEPSEEK_API_KEY")
+ deepseek_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="DEEPSEEK_API_KEY"
+ )
# ==================== Kimi Config ====================
- kimi_api_key: str = Field(default="", validation_alias="KIMI_API_KEY")
+ kimi_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="KIMI_API_KEY"
+ )
# ==================== Kimi Code Subscription ====================
- kimi_code_api_key: str = Field(default="", validation_alias="KIMI_CODE_API_KEY")
+ kimi_code_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="KIMI_CODE_API_KEY"
+ )
# ==================== Wafer Config ====================
- wafer_api_key: str = Field(default="", validation_alias="WAFER_API_KEY")
+ wafer_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="WAFER_API_KEY"
+ )
# ==================== MiniMax Config ====================
- minimax_api_key: str = Field(default="", validation_alias="MINIMAX_API_KEY")
+ minimax_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="MINIMAX_API_KEY"
+ )
# ==================== OpenCode Zen / OpenCode Go ====================
# Same key from opencode.ai/auth; Zen uses ``opencode_zen/``, Go uses ``opencode_go/``.
- opencode_api_key: str = Field(default="", validation_alias="OPENCODE_API_KEY")
+ opencode_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="OPENCODE_API_KEY"
+ )
# ==================== Vercel AI Gateway ====================
- vercel_ai_gateway_api_key: str = Field(
- default="", validation_alias="AI_GATEWAY_API_KEY"
+ vercel_ai_gateway_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="AI_GATEWAY_API_KEY"
)
# ==================== Amazon Bedrock Mantle ====================
- bedrock_api_key: str = Field(
- default="", validation_alias="AWS_BEARER_TOKEN_BEDROCK"
+ bedrock_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="AWS_BEARER_TOKEN_BEDROCK"
)
- bedrock_base_url: str = Field(
+ bedrock_base_url: NonEmptyString = Field(
default=BEDROCK_DEFAULT_BASE,
validation_alias="BEDROCK_BASE_URL",
)
# ==================== Hugging Face Inference Providers ====================
- huggingface_api_key: str = Field(default="", validation_alias="HUGGINGFACE_API_KEY")
+ huggingface_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="HUGGINGFACE_API_KEY"
+ )
# ==================== Cohere Compatibility API ====================
- cohere_api_key: str = Field(default="", validation_alias="COHERE_API_KEY")
+ cohere_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="COHERE_API_KEY"
+ )
# ==================== GitHub Models ====================
- github_models_token: str = Field(default="", validation_alias="GITHUB_MODELS_TOKEN")
+ github_models_token: OptionalNonEmptyString = Field(
+ default=None, validation_alias="GITHUB_MODELS_TOKEN"
+ )
# ==================== SambaNova Cloud ====================
- sambanova_api_key: str = Field(default="", validation_alias="SAMBANOVA_API_KEY")
+ sambanova_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="SAMBANOVA_API_KEY"
+ )
# ==================== Kilo.ai Config ====================
- kilo_api_key: str = Field(default="", validation_alias="KILO_API_KEY")
+ kilo_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="KILO_API_KEY"
+ )
# ==================== Z.ai Config ====================
- zai_api_key: str = Field(default="", validation_alias="ZAI_API_KEY")
+ zai_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="ZAI_API_KEY"
+ )
# ==================== TokenRouter Config ====================
- tokenrouter_api_key: str = Field(default="", validation_alias="TOKENROUTER_API_KEY")
- tokenrouter_base_url: str = Field(
+ tokenrouter_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="TOKENROUTER_API_KEY"
+ )
+ tokenrouter_base_url: NonEmptyString = Field(
default=TOKENROUTER_DEFAULT_BASE,
validation_alias="TOKENROUTER_BASE_URL",
)
# ==================== NaraRoute Config ====================
- nararoute_api_key: str = Field(default="", validation_alias="NARAROUTE_API_KEY")
- nararoute_base_url: str = Field(
+ nararoute_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="NARAROUTE_API_KEY"
+ )
+ nararoute_base_url: NonEmptyString = Field(
default=NARAROUTE_DEFAULT_BASE,
validation_alias="NARAROUTE_BASE_URL",
)
# ==================== Fireworks AI Config ====================
- fireworks_api_key: str = Field(default="", validation_alias="FIREWORKS_API_KEY")
+ fireworks_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="FIREWORKS_API_KEY"
+ )
# ==================== Novita AI Config ====================
- novita_api_key: str = Field(default="", validation_alias="NOVITA_API_KEY")
+ novita_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="NOVITA_API_KEY"
+ )
# ==================== Cloudflare Workers AI Config ====================
- cloudflare_api_token: str = Field(
- default="", validation_alias="CLOUDFLARE_API_TOKEN"
+ cloudflare_api_token: OptionalNonEmptyString = Field(
+ default=None, validation_alias="CLOUDFLARE_API_TOKEN"
)
- cloudflare_account_id: str = Field(
- default="", validation_alias="CLOUDFLARE_ACCOUNT_ID"
+ cloudflare_account_id: OptionalNonEmptyString = Field(
+ default=None, validation_alias="CLOUDFLARE_ACCOUNT_ID"
)
# ==================== Google Gemini (Google AI Studio) ====================
- gemini_api_key: str = Field(default="", validation_alias="GEMINI_API_KEY")
+ gemini_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="GEMINI_API_KEY"
+ )
# ==================== Google Vertex AI ====================
- vertex_project_id: str = Field(default="", validation_alias="VERTEX_PROJECT_ID")
- vertex_location: str = Field(default="global", validation_alias="VERTEX_LOCATION")
+ vertex_project_id: OptionalNonEmptyString = Field(
+ default=None, validation_alias="VERTEX_PROJECT_ID"
+ )
+ vertex_location: NonEmptyString = Field(
+ default="global", validation_alias="VERTEX_LOCATION"
+ )
# ==================== Groq (OpenAI-compatible) ====================
- groq_api_key: str = Field(default="", validation_alias="GROQ_API_KEY")
+ groq_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="GROQ_API_KEY"
+ )
# ==================== xAI / Grok (OpenAI-compatible) ====================
- xai_api_key: str = Field(default="", validation_alias="XAI_API_KEY")
+ xai_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="XAI_API_KEY"
+ )
# ==================== QwenCloud Token Plan (OpenAI-compatible) ====================
- qwencloud_api_key: str = Field(default="", validation_alias="QWENCLOUD_API_KEY")
+ qwencloud_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="QWENCLOUD_API_KEY"
+ )
# ==================== Together AI (OpenAI-compatible) ====================
- together_api_key: str = Field(default="", validation_alias="TOGETHER_API_KEY")
+ together_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="TOGETHER_API_KEY"
+ )
# ==================== DeepInfra (OpenAI-compatible) ====================
- deepinfra_api_key: str = Field(default="", validation_alias="DEEPINFRA_API_KEY")
+ deepinfra_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="DEEPINFRA_API_KEY"
+ )
# ==================== SiliconFlow (OpenAI-compatible) ====================
- siliconflow_api_key: str = Field(default="", validation_alias="SILICONFLOW_API_KEY")
+ siliconflow_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="SILICONFLOW_API_KEY"
+ )
# ==================== Nebius Token Factory (OpenAI-compatible) ====================
- nebius_api_key: str = Field(default="", validation_alias="NEBIUS_API_KEY")
+ nebius_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="NEBIUS_API_KEY"
+ )
# ==================== Chutes (OpenAI-compatible) ====================
- chutes_api_key: str = Field(default="", validation_alias="CHUTES_API_KEY")
+ chutes_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="CHUTES_API_KEY"
+ )
# ==================== Featherless AI (OpenAI-compatible) ====================
- featherless_api_key: str = Field(default="", validation_alias="FEATHERLESS_API_KEY")
+ featherless_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="FEATHERLESS_API_KEY"
+ )
# ==================== Agnes AI (OpenAI-compatible) ====================
- agnes_api_key: str = Field(default="", validation_alias="AGNES_API_KEY")
+ agnes_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="AGNES_API_KEY"
+ )
# ==================== ZenMux (OpenAI-compatible) ====================
- zenmux_api_key: str = Field(default="", validation_alias="ZENMUX_API_KEY")
+ zenmux_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="ZENMUX_API_KEY"
+ )
# ==================== Cerebras Inference (OpenAI-compatible) ====================
- cerebras_api_key: str = Field(default="", validation_alias="CEREBRAS_API_KEY")
+ cerebras_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="CEREBRAS_API_KEY"
+ )
# ==================== Ollama Cloud ====================
- ollama_api_key: str = Field(default="", validation_alias="OLLAMA_API_KEY")
+ ollama_api_key: OptionalNonEmptyString = Field(
+ default=None, validation_alias="OLLAMA_API_KEY"
+ )
# ==================== Messaging Platform Selection ====================
# Valid: "telegram" | "discord" | "none"
- messaging_platform: str = Field(
+ messaging_platform: NonEmptyString = Field(
default="discord", validation_alias="MESSAGING_PLATFORM"
)
messaging_rate_limit: int = Field(
@@ -180,22 +273,25 @@ class Settings(BaseSettings):
)
# ==================== NVIDIA NIM Config ====================
- nvidia_nim_api_key: str = ""
+ nvidia_nim_api_key: OptionalNonEmptyString = Field(
+ default=None,
+ validation_alias="NVIDIA_NIM_API_KEY",
+ )
# ==================== LM Studio Config ====================
- lm_studio_base_url: str = Field(
+ lm_studio_base_url: NonEmptyString = Field(
default="http://localhost:1234/v1",
validation_alias="LM_STUDIO_BASE_URL",
)
# ==================== Llama.cpp Config ====================
- llamacpp_base_url: str = Field(
+ llamacpp_base_url: NonEmptyString = Field(
default="http://localhost:8080/v1",
validation_alias="LLAMACPP_BASE_URL",
)
# ==================== Ollama Config ====================
- ollama_base_url: str = Field(
+ ollama_base_url: NonEmptyString = Field(
default="http://localhost:11434",
validation_alias="OLLAMA_BASE_URL",
)
@@ -203,68 +299,161 @@ class Settings(BaseSettings):
# ==================== Model ====================
# All Claude model requests are mapped to this single model (fallback)
# Format: provider_type/model/name
- model: str = "nvidia_nim/nvidia/nemotron-3-super-120b-a12b"
+ model: NonEmptyString = Field(
+ default="nvidia_nim/nvidia/nemotron-3-super-120b-a12b",
+ validation_alias="MODEL",
+ )
# Per-model overrides (optional, falls back to MODEL)
# Each can use a different provider
- model_fable: str | None = Field(default=None, validation_alias="MODEL_FABLE")
- model_opus: str | None = Field(default=None, validation_alias="MODEL_OPUS")
- model_sonnet: str | None = Field(default=None, validation_alias="MODEL_SONNET")
- model_haiku: str | None = Field(default=None, validation_alias="MODEL_HAIKU")
+ model_fable: OptionalNonEmptyString = Field(
+ default=None, validation_alias="MODEL_FABLE"
+ )
+ model_opus: OptionalNonEmptyString = Field(
+ default=None, validation_alias="MODEL_OPUS"
+ )
+ model_sonnet: OptionalNonEmptyString = Field(
+ default=None, validation_alias="MODEL_SONNET"
+ )
+ model_haiku: OptionalNonEmptyString = Field(
+ default=None, validation_alias="MODEL_HAIKU"
+ )
# ==================== Per-Provider Proxy ====================
- openai_proxy: str = Field(default="", validation_alias="OPENAI_PROXY")
- xai_proxy: str = Field(default="", validation_alias="XAI_PROXY")
- qwencloud_proxy: str = Field(default="", validation_alias="QWENCLOUD_PROXY")
- together_proxy: str = Field(default="", validation_alias="TOGETHER_PROXY")
- deepinfra_proxy: str = Field(default="", validation_alias="DEEPINFRA_PROXY")
- siliconflow_proxy: str = Field(default="", validation_alias="SILICONFLOW_PROXY")
- nebius_proxy: str = Field(default="", validation_alias="NEBIUS_PROXY")
- chutes_proxy: str = Field(default="", validation_alias="CHUTES_PROXY")
- featherless_proxy: str = Field(default="", validation_alias="FEATHERLESS_PROXY")
- agnes_proxy: str = Field(default="", validation_alias="AGNES_PROXY")
- zenmux_proxy: str = Field(default="", validation_alias="ZENMUX_PROXY")
- azure_openai_proxy: str = Field(default="", validation_alias="AZURE_OPENAI_PROXY")
- nvidia_nim_proxy: str = Field(default="", validation_alias="NVIDIA_NIM_PROXY")
- open_router_proxy: str = Field(default="", validation_alias="OPENROUTER_PROXY")
- mistral_proxy: str = Field(default="", validation_alias="MISTRAL_PROXY")
- codestral_proxy: str = Field(default="", validation_alias="CODESTRAL_PROXY")
- lmstudio_proxy: str = Field(default="", validation_alias="LMSTUDIO_PROXY")
- llamacpp_proxy: str = Field(default="", validation_alias="LLAMACPP_PROXY")
- kimi_proxy: str = Field(default="", validation_alias="KIMI_PROXY")
- kimi_code_proxy: str = Field(default="", validation_alias="KIMI_CODE_PROXY")
- wafer_proxy: str = Field(default="", validation_alias="WAFER_PROXY")
- minimax_proxy: str = Field(default="", validation_alias="MINIMAX_PROXY")
- opencode_zen_proxy: str = Field(default="", validation_alias="OPENCODE_ZEN_PROXY")
- opencode_go_proxy: str = Field(default="", validation_alias="OPENCODE_GO_PROXY")
- vercel_ai_gateway_proxy: str = Field(
- default="", validation_alias="VERCEL_AI_GATEWAY_PROXY"
- )
- bedrock_proxy: str = Field(default="", validation_alias="BEDROCK_PROXY")
- huggingface_proxy: str = Field(default="", validation_alias="HUGGINGFACE_PROXY")
- cohere_proxy: str = Field(default="", validation_alias="COHERE_PROXY")
- github_models_proxy: str = Field(default="", validation_alias="GITHUB_MODELS_PROXY")
- sambanova_proxy: str = Field(default="", validation_alias="SAMBANOVA_PROXY")
- kilo_proxy: str = Field(default="", validation_alias="KILO_PROXY")
- zai_proxy: str = Field(default="", validation_alias="ZAI_PROXY")
- tokenrouter_proxy: str = Field(default="", validation_alias="TOKENROUTER_PROXY")
- nararoute_proxy: str = Field(default="", validation_alias="NARAROUTE_PROXY")
- fireworks_proxy: str = Field(default="", validation_alias="FIREWORKS_PROXY")
- novita_proxy: str = Field(default="", validation_alias="NOVITA_PROXY")
- cloudflare_proxy: str = Field(default="", validation_alias="CLOUDFLARE_PROXY")
- gemini_proxy: str = Field(default="", validation_alias="GEMINI_PROXY")
- vertex_proxy: str = Field(default="", validation_alias="VERTEX_PROXY")
- groq_proxy: str = Field(default="", validation_alias="GROQ_PROXY")
- cerebras_proxy: str = Field(default="", validation_alias="CEREBRAS_PROXY")
- ollama_cloud_proxy: str = Field(default="", validation_alias="OLLAMA_CLOUD_PROXY")
+ openai_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="OPENAI_PROXY"
+ )
+ xai_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="XAI_PROXY"
+ )
+ qwencloud_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="QWENCLOUD_PROXY"
+ )
+ together_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="TOGETHER_PROXY"
+ )
+ deepinfra_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="DEEPINFRA_PROXY"
+ )
+ siliconflow_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="SILICONFLOW_PROXY"
+ )
+ nebius_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="NEBIUS_PROXY"
+ )
+ chutes_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="CHUTES_PROXY"
+ )
+ featherless_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="FEATHERLESS_PROXY"
+ )
+ agnes_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="AGNES_PROXY"
+ )
+ zenmux_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="ZENMUX_PROXY"
+ )
+ azure_openai_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="AZURE_OPENAI_PROXY"
+ )
+ nvidia_nim_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="NVIDIA_NIM_PROXY"
+ )
+ open_router_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="OPENROUTER_PROXY"
+ )
+ mistral_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="MISTRAL_PROXY"
+ )
+ codestral_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="CODESTRAL_PROXY"
+ )
+ lmstudio_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="LMSTUDIO_PROXY"
+ )
+ llamacpp_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="LLAMACPP_PROXY"
+ )
+ kimi_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="KIMI_PROXY"
+ )
+ kimi_code_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="KIMI_CODE_PROXY"
+ )
+ wafer_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="WAFER_PROXY"
+ )
+ minimax_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="MINIMAX_PROXY"
+ )
+ opencode_zen_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="OPENCODE_ZEN_PROXY"
+ )
+ opencode_go_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="OPENCODE_GO_PROXY"
+ )
+ vercel_ai_gateway_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="VERCEL_AI_GATEWAY_PROXY"
+ )
+ bedrock_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="BEDROCK_PROXY"
+ )
+ huggingface_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="HUGGINGFACE_PROXY"
+ )
+ cohere_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="COHERE_PROXY"
+ )
+ github_models_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="GITHUB_MODELS_PROXY"
+ )
+ sambanova_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="SAMBANOVA_PROXY"
+ )
+ kilo_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="KILO_PROXY"
+ )
+ zai_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="ZAI_PROXY"
+ )
+ tokenrouter_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="TOKENROUTER_PROXY"
+ )
+ nararoute_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="NARAROUTE_PROXY"
+ )
+ fireworks_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="FIREWORKS_PROXY"
+ )
+ novita_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="NOVITA_PROXY"
+ )
+ cloudflare_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="CLOUDFLARE_PROXY"
+ )
+ gemini_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="GEMINI_PROXY"
+ )
+ vertex_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="VERTEX_PROXY"
+ )
+ groq_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="GROQ_PROXY"
+ )
+ cerebras_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="CEREBRAS_PROXY"
+ )
+ ollama_cloud_proxy: OptionalNonEmptyString = Field(
+ default=None, validation_alias="OLLAMA_CLOUD_PROXY"
+ )
# ==================== Provider Rate Limiting ====================
- provider_rate_limit: int = Field(default=40, validation_alias="PROVIDER_RATE_LIMIT")
+ provider_rate_limit: int = Field(default=1, validation_alias="PROVIDER_RATE_LIMIT")
provider_rate_window: int = Field(
- default=60, validation_alias="PROVIDER_RATE_WINDOW"
+ default=2, validation_alias="PROVIDER_RATE_WINDOW"
)
provider_max_concurrency: int = Field(
- default=5, validation_alias="PROVIDER_MAX_CONCURRENCY"
+ default=2, validation_alias="PROVIDER_MAX_CONCURRENCY"
)
reasoning_policy: ReasoningPreference = Field(
default=ReasoningPreference.CLIENT,
@@ -300,13 +489,28 @@ class Settings(BaseSettings):
)
# ==================== Fast Prefix Detection ====================
- fast_prefix_detection: bool = True
+ fast_prefix_detection: bool = Field(
+ default=True,
+ validation_alias="FAST_PREFIX_DETECTION",
+ )
# ==================== Optimizations ====================
- enable_network_probe_mock: bool = True
- enable_title_generation_skip: bool = True
- enable_suggestion_mode_skip: bool = True
- enable_filepath_extraction_mock: bool = True
+ enable_network_probe_mock: bool = Field(
+ default=True,
+ validation_alias="ENABLE_NETWORK_PROBE_MOCK",
+ )
+ enable_title_generation_skip: bool = Field(
+ default=True,
+ validation_alias="ENABLE_TITLE_GENERATION_SKIP",
+ )
+ enable_suggestion_mode_skip: bool = Field(
+ default=True,
+ validation_alias="ENABLE_SUGGESTION_MODE_SKIP",
+ )
+ enable_filepath_extraction_mock: bool = Field(
+ default=True,
+ validation_alias="ENABLE_FILEPATH_EXTRACTION_MOCK",
+ )
# ==================== Local web server tools (web_search / web_fetch) ====================
# Off by default: these tools perform outbound HTTP from the proxy (SSRF risk).
@@ -314,7 +518,7 @@ class Settings(BaseSettings):
default=False, validation_alias="ENABLE_WEB_SERVER_TOOLS"
)
# Comma-separated URL schemes allowed for web_fetch (default: http,https).
- web_fetch_allowed_schemes: str = Field(
+ web_fetch_allowed_schemes: NonEmptyString = Field(
default="http,https", validation_alias="WEB_FETCH_ALLOWED_SCHEMES"
)
# When true, skip private/loopback/link-local IP blocking for web_fetch (lab only).
@@ -324,7 +528,7 @@ class Settings(BaseSettings):
# ==================== Debug / diagnostic logging (avoid sensitive content) ====================
# Minimum log level for the JSON file sink (DEBUG, INFO, WARNING, ERROR, CRITICAL).
- log_level: str = Field(default="INFO", validation_alias="LOG_LEVEL")
+ log_level: NonEmptyString = Field(default="INFO", validation_alias="LOG_LEVEL")
# When false (default), API and SSE helpers log only metadata (counts, lengths, ids).
log_raw_api_payloads: bool = Field(
default=False, validation_alias="LOG_RAW_API_PAYLOADS"
@@ -365,53 +569,53 @@ class Settings(BaseSettings):
# Device: "cpu" | "cuda" | "nvidia_nim"
# - "cpu"/"cuda": local Whisper (requires voice_local extra: uv sync --extra voice_local)
# - "nvidia_nim": NVIDIA NIM Whisper API (requires voice extra: uv sync --extra voice)
- whisper_device: str = Field(default="cpu", validation_alias="WHISPER_DEVICE")
+ whisper_device: NonEmptyString = Field(
+ default="cpu", validation_alias="WHISPER_DEVICE"
+ )
# Whisper model ID or short name (for local Whisper) or NVIDIA NIM model (for nvidia_nim)
# Local Whisper: "tiny", "base", "small", "medium", "large-v2", "large-v3", "large-v3-turbo"
# NVIDIA NIM: "nvidia/parakeet-ctc-1.1b-asr", "openai/whisper-large-v3", etc.
- whisper_model: str = Field(default="base", validation_alias="WHISPER_MODEL")
+ whisper_model: NonEmptyString = Field(
+ default="base", validation_alias="WHISPER_MODEL"
+ )
# ==================== Bot Wrapper Config ====================
- telegram_bot_token: str | None = None
- allowed_telegram_user_id: str | None = None
- telegram_proxy_url: str = Field(default="", validation_alias="TELEGRAM_PROXY_URL")
- discord_bot_token: str | None = Field(
+ telegram_bot_token: OptionalNonEmptyString = Field(
+ default=None,
+ validation_alias="TELEGRAM_BOT_TOKEN",
+ )
+ allowed_telegram_user_id: OptionalNonEmptyString = Field(
+ default=None,
+ validation_alias="ALLOWED_TELEGRAM_USER_ID",
+ )
+ telegram_proxy_url: OptionalNonEmptyString = Field(
+ default=None, validation_alias="TELEGRAM_PROXY_URL"
+ )
+ discord_bot_token: OptionalNonEmptyString = Field(
default=None, validation_alias="DISCORD_BOT_TOKEN"
)
- allowed_discord_channels: str | None = Field(
+ allowed_discord_channels: OptionalNonEmptyString = Field(
default=None, validation_alias="ALLOWED_DISCORD_CHANNELS"
)
- allowed_dir: str = ""
+ allowed_dir: OptionalNonEmptyString = Field(
+ default=None,
+ validation_alias="ALLOWED_DIR",
+ )
max_message_log_entries_per_chat: int | None = Field(
default=None, validation_alias="MAX_MESSAGE_LOG_ENTRIES_PER_CHAT"
)
# ==================== Server ====================
- host: str = "0.0.0.0"
- port: int = 8082
+ host: NonEmptyString = Field(default="0.0.0.0", validation_alias="HOST")
+ port: int = Field(default=8082, validation_alias="PORT")
open_admin_browser: bool = Field(default=True, validation_alias="FCC_OPEN_BROWSER")
- # Optional proxy bearer token protecting public API endpoints.
- # Set via env `ANTHROPIC_AUTH_TOKEN`. When empty, no auth is required.
- anthropic_auth_token: str = Field(
- default="", validation_alias="ANTHROPIC_AUTH_TOKEN"
+ proxy_auth_enabled: bool = Field(
+ default=False,
+ validation_alias="PROXY_AUTH_ENABLED",
)
-
- # Handle empty strings for optional string fields
- @field_validator(
- "telegram_bot_token",
- "allowed_telegram_user_id",
- "discord_bot_token",
- "allowed_discord_channels",
- "model_fable",
- "model_opus",
- "model_sonnet",
- "model_haiku",
- mode="before",
+ proxy_auth_token: NonEmptyString = Field(
+ default="freecc",
+ validation_alias="ANTHROPIC_AUTH_TOKEN",
)
- @classmethod
- def parse_optional_str(cls, v: Any) -> Any:
- if v == "":
- return None
- return v
@field_validator("max_message_log_entries_per_chat", mode="before")
@classmethod
@@ -507,30 +711,10 @@ class Settings(BaseSettings):
if (
self.voice_note_enabled
and self.whisper_device == "nvidia_nim"
- and not self.nvidia_nim_api_key.strip()
+ and self.nvidia_nim_api_key is None
):
raise ValueError(
"NVIDIA_NIM_API_KEY is required when WHISPER_DEVICE is 'nvidia_nim'. "
- "Set it in your .env file."
+ "Set it in the Admin UI."
)
return self
-
- @model_validator(mode="after")
- def prefer_dotenv_anthropic_auth_token(self) -> Settings:
- """Let explicit .env auth config override stale shell/client tokens."""
- dotenv_value = env_file_override(self.model_config, ANTHROPIC_AUTH_TOKEN_ENV)
- if dotenv_value is not None:
- self.anthropic_auth_token = dotenv_value
- return self
-
- model_config = SettingsConfigDict(
- env_file=settings_env_files(),
- env_file_encoding="utf-8",
- extra="ignore",
- )
-
-
-@lru_cache
-def get_settings() -> Settings:
- """Get cached settings instance."""
- return Settings()
diff --git a/src/free_claude_code/messaging/platforms/factory.py b/src/free_claude_code/messaging/platforms/factory.py
index 0b678bb6..504fab0c 100644
--- a/src/free_claude_code/messaging/platforms/factory.py
+++ b/src/free_claude_code/messaging/platforms/factory.py
@@ -15,7 +15,7 @@ class MessagingPlatformOptions:
telegram_bot_token: str | None = None
allowed_telegram_user_id: str | None = None
- telegram_proxy_url: str = ""
+ telegram_proxy_url: str | None = None
discord_bot_token: str | None = None
allowed_discord_channels: str | None = None
transcriber: Transcriber | None = None
diff --git a/src/free_claude_code/messaging/platforms/telegram.py b/src/free_claude_code/messaging/platforms/telegram.py
index 4556b7c8..ef135c07 100644
--- a/src/free_claude_code/messaging/platforms/telegram.py
+++ b/src/free_claude_code/messaging/platforms/telegram.py
@@ -50,7 +50,7 @@ class TelegramRuntime:
bot_token: str | None = None,
allowed_user_id: str | None = None,
*,
- telegram_proxy_url: str = "",
+ telegram_proxy_url: str | None = None,
limiter: MessagingRateLimiter,
transcriber: Transcriber | None,
log_raw_messaging_content: bool = False,
@@ -63,7 +63,7 @@ class TelegramRuntime:
self.bot_token = bot_token
self.allowed_user_id = allowed_user_id
- self.telegram_proxy_url = telegram_proxy_url.strip()
+ self.telegram_proxy_url = telegram_proxy_url
if not self.bot_token:
logger.warning("TELEGRAM_BOT_TOKEN not set")
diff --git a/src/free_claude_code/messaging/transcription.py b/src/free_claude_code/messaging/transcription.py
index 82eb4261..0e6ff43e 100644
--- a/src/free_claude_code/messaging/transcription.py
+++ b/src/free_claude_code/messaging/transcription.py
@@ -26,7 +26,7 @@ class TranscriptionService:
*,
model: str,
device: str,
- huggingface_api_key: str = "",
+ huggingface_api_key: str | None = None,
) -> None:
if device not in {"cpu", "cuda"}:
raise ValueError(
@@ -58,7 +58,7 @@ class TranscriptionService:
self._closed = True
async with self._lock:
self._pipeline = None
- self._huggingface_api_key = ""
+ self._huggingface_api_key = None
def _transcribe_sync(self, file_path: Path) -> str:
pipe = self._get_pipeline()
@@ -83,7 +83,7 @@ class TranscriptionService:
"Install with: uv sync --extra voice_local"
) from exc
- token = self._huggingface_api_key or None
+ token = self._huggingface_api_key
use_cuda = self._device == "cuda" and torch.cuda.is_available()
pipeline_device = "cuda:0" if use_cuda else "cpu"
model_dtype = torch.float16 if use_cuda else torch.float32
diff --git a/src/free_claude_code/providers/base.py b/src/free_claude_code/providers/base.py
index 0abd9825..4fd73c38 100644
--- a/src/free_claude_code/providers/base.py
+++ b/src/free_claude_code/providers/base.py
@@ -7,7 +7,6 @@ from dataclasses import dataclass
from loguru import logger
from free_claude_code.application.model_metadata import ProviderModelInfo
-from free_claude_code.config.constants import HTTP_CONNECT_TIMEOUT_DEFAULT
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.diagnostics import (
exception_cause_types,
@@ -25,17 +24,17 @@ class ProviderConfig:
(e.g. NIM temperature, top_p) are passed by the provider constructor.
"""
- api_key: str
+ api_key: str | None
base_url: str
- rate_limit: int | None = None
- rate_window: int = 60
- max_concurrency: int = 5
- http_read_timeout: float = 300.0
- http_write_timeout: float = 10.0
- http_connect_timeout: float = HTTP_CONNECT_TIMEOUT_DEFAULT
- proxy: str = ""
- log_raw_sse_events: bool = False
- log_api_error_tracebacks: bool = False
+ rate_limit: int
+ rate_window: int
+ max_concurrency: int
+ http_read_timeout: float
+ http_write_timeout: float
+ http_connect_timeout: float
+ proxy: str | None
+ log_raw_sse_events: bool
+ log_api_error_tracebacks: bool
class BaseProvider(ABC):
diff --git a/src/free_claude_code/providers/cloudflare/client.py b/src/free_claude_code/providers/cloudflare/client.py
index e2ba36ab..a484d6f0 100644
--- a/src/free_claude_code/providers/cloudflare/client.py
+++ b/src/free_claude_code/providers/cloudflare/client.py
@@ -54,7 +54,7 @@ def _cloudflare_account_api_url(api_root: str | None, account_id: str) -> str:
stripped_account = account_id.strip()
if not stripped_account:
raise ApplicationUnavailableError(
- "CLOUDFLARE_ACCOUNT_ID is not set. Add it to your .env file."
+ "CLOUDFLARE_ACCOUNT_ID is not set. Add it in the Admin UI."
)
root = (api_root or CLOUDFLARE_AI_REST_ROOT).rstrip("/")
encoded_account = quote(stripped_account, safe="")
@@ -76,7 +76,7 @@ class CloudflareProvider(OpenAIChatProvider):
config.base_url, account_id
)
self._model_list_client = httpx.AsyncClient(
- proxy=config.proxy or None,
+ proxy=config.proxy,
timeout=httpx.Timeout(
config.http_read_timeout,
connect=config.http_connect_timeout,
@@ -134,6 +134,8 @@ class CloudflareProvider(OpenAIChatProvider):
yield ledger.emit_thinking_delta(reasoning)
def _model_list_headers(self) -> dict[str, str]:
+ if self._api_key is None:
+ raise AssertionError("Cloudflare requires a static API token")
return {"Authorization": f"Bearer {self._api_key}"}
diff --git a/src/free_claude_code/providers/github_models/client.py b/src/free_claude_code/providers/github_models/client.py
index 87c0ef28..b8c76c8f 100644
--- a/src/free_claude_code/providers/github_models/client.py
+++ b/src/free_claude_code/providers/github_models/client.py
@@ -40,7 +40,7 @@ class GitHubModelsProvider(OpenAIChatProvider):
):
self._catalog_url = GITHUB_MODELS_CATALOG_URL
self._model_list_client = httpx.AsyncClient(
- proxy=config.proxy or None,
+ proxy=config.proxy,
timeout=httpx.Timeout(
config.http_read_timeout,
connect=config.http_connect_timeout,
@@ -90,6 +90,8 @@ class GitHubModelsProvider(OpenAIChatProvider):
await maybe_await_aclose(response)
def _model_list_headers(self) -> dict[str, str]:
+ if self._api_key is None:
+ raise AssertionError("GitHub Models requires a static API key")
return _github_models_api_headers(self._api_key)
diff --git a/src/free_claude_code/providers/openai_chat/provider.py b/src/free_claude_code/providers/openai_chat/provider.py
index 6e7e811b..ecd386e2 100644
--- a/src/free_claude_code/providers/openai_chat/provider.py
+++ b/src/free_claude_code/providers/openai_chat/provider.py
@@ -147,6 +147,10 @@ class OpenAIChatProvider(BaseProvider):
super().__init__(config)
self._profile = profile
self._provider_name = profile.provider_name
+ if config.api_key is None and api_key_provider is None:
+ raise ValueError(
+ f"{profile.provider_name} requires an API key or credential provider"
+ )
self._api_key = config.api_key
self._base_url = profile.base_url(config.base_url).rstrip("/")
# Learned per-model output-token caps from upstream 400 rejections, so
diff --git a/src/free_claude_code/providers/openai_codex/auth.py b/src/free_claude_code/providers/openai_codex/auth.py
index 680b57e1..b8dad057 100644
--- a/src/free_claude_code/providers/openai_codex/auth.py
+++ b/src/free_claude_code/providers/openai_codex/auth.py
@@ -136,7 +136,7 @@ class OpenAIAuthManager:
def __init__(
self,
*,
- proxy: str = "",
+ proxy: str | None = None,
credential_path: Path | None = None,
lock_path: Path | None = None,
client: httpx.AsyncClient | None = None,
@@ -144,7 +144,7 @@ class OpenAIAuthManager:
self._credential_path = credential_path or openai_auth_path()
self._lock_path = lock_path or openai_auth_lock_path()
self._client = client or httpx.AsyncClient(
- proxy=proxy or None,
+ proxy=proxy,
timeout=httpx.Timeout(30.0),
headers={"originator": OPENAI_CODEX_ORIGINATOR},
)
diff --git a/src/free_claude_code/providers/openai_codex/provider.py b/src/free_claude_code/providers/openai_codex/provider.py
index 53623cdc..aecdae29 100644
--- a/src/free_claude_code/providers/openai_codex/provider.py
+++ b/src/free_claude_code/providers/openai_codex/provider.py
@@ -75,7 +75,7 @@ class OpenAICodexProvider(BaseProvider):
}
self._client = client or httpx.AsyncClient(
base_url=f"{config.base_url.rstrip('/')}/",
- proxy=config.proxy or None,
+ proxy=config.proxy,
timeout=httpx.Timeout(
config.http_read_timeout,
connect=config.http_connect_timeout,
diff --git a/src/free_claude_code/providers/runtime/config.py b/src/free_claude_code/providers/runtime/config.py
index 1f95972b..1e17cb5a 100644
--- a/src/free_claude_code/providers/runtime/config.py
+++ b/src/free_claude_code/providers/runtime/config.py
@@ -6,21 +6,23 @@ from free_claude_code.config.settings import Settings
from free_claude_code.providers.base import ProviderConfig
-def string_setting(settings: Settings, attr_name: str | None, default: str = "") -> str:
- """Return a string-valued settings attribute, ignoring non-string mocks."""
+def string_setting(settings: Settings, attr_name: str | None) -> str | None:
+ """Return an optional validated string setting."""
if attr_name is None:
- return default
- value = getattr(settings, attr_name, default)
- return value if isinstance(value, str) else default
+ return None
+ value = getattr(settings, attr_name, None)
+ return value if isinstance(value, str) else None
-def provider_credential(descriptor: ProviderDescriptor, settings: Settings) -> str:
+def provider_credential(
+ descriptor: ProviderDescriptor, settings: Settings
+) -> str | None:
"""Return the configured credential for a provider descriptor."""
if descriptor.static_credential is not None:
return descriptor.static_credential
if descriptor.credential_attr:
return string_setting(settings, descriptor.credential_attr)
- return ""
+ return None
def has_provider_configuration(
@@ -29,19 +31,19 @@ def has_provider_configuration(
"""Return whether all provider-defining settings are present."""
attrs = descriptor.configuration_attrs()
if attrs:
- return all(string_setting(settings, attr).strip() for attr in attrs)
+ return all(string_setting(settings, attr) for attr in attrs)
return descriptor.static_credential is not None
def require_provider_credential(
- descriptor: ProviderDescriptor, credential: str
+ descriptor: ProviderDescriptor, credential: str | None
) -> None:
"""Raise a user-facing configuration error when a required key is missing."""
if descriptor.credential_env is None:
return
- if credential and credential.strip():
+ if credential:
return
- message = f"{descriptor.credential_env} is not set. Add it to your .env file."
+ message = f"{descriptor.credential_env} is not set. Add it in the Admin UI."
if descriptor.credential_url:
message = f"{message} Get a key at {descriptor.credential_url}"
raise ApplicationUnavailableError(message)
@@ -53,9 +55,7 @@ def build_provider_config(
"""Build shared provider configuration for one provider descriptor."""
credential = provider_credential(descriptor, settings)
require_provider_credential(descriptor, credential)
- base_url = string_setting(
- settings, descriptor.base_url_attr, descriptor.default_base_url or ""
- )
+ base_url = string_setting(settings, descriptor.base_url_attr)
resolved_base_url = base_url or descriptor.default_base_url
if not resolved_base_url:
if descriptor.base_url_attr is None:
@@ -65,7 +65,15 @@ def build_provider_config(
field = Settings.model_fields[descriptor.base_url_attr]
env_name = field.validation_alias or descriptor.base_url_attr
raise ApplicationUnavailableError(
- f"{env_name} is not set. Add it to your .env file."
+ f"{env_name} is not set. Add it in the Admin UI."
+ )
+ for attr in descriptor.required_settings_attrs:
+ if string_setting(settings, attr) is not None:
+ continue
+ field = Settings.model_fields[attr]
+ env_name = field.validation_alias or attr
+ raise ApplicationUnavailableError(
+ f"{env_name} is not set. Add it in the Admin UI."
)
proxy = string_setting(settings, descriptor.proxy_attr)
return ProviderConfig(
diff --git a/src/free_claude_code/providers/runtime/factory.py b/src/free_claude_code/providers/runtime/factory.py
index a4044293..0d8ca145 100644
--- a/src/free_claude_code/providers/runtime/factory.py
+++ b/src/free_claude_code/providers/runtime/factory.py
@@ -95,7 +95,7 @@ def _create_cloudflare(
return CloudflareProvider(
config,
- account_id=settings.cloudflare_account_id,
+ account_id=_required_setting(settings, "cloudflare_account_id"),
admission=admission,
)
@@ -119,7 +119,7 @@ def _create_vertex(
return VertexProvider(
config,
- project_id=settings.vertex_project_id,
+ project_id=_required_setting(settings, "vertex_project_id"),
location=settings.vertex_location,
admission=admission,
)
@@ -160,6 +160,14 @@ _SPECIAL_PROVIDER_FACTORIES: dict[str, ProviderFactory] = {
}
_INJECTED_PROVIDER_IDS = {"openai"}
+
+def _required_setting(settings: Settings, attr_name: str) -> str:
+ value = getattr(settings, attr_name, None)
+ if not isinstance(value, str) or not value:
+ raise AssertionError(f"Provider config did not validate {attr_name!r}")
+ return value
+
+
_profiled_ids = set(OPENAI_CHAT_PROFILES)
_special_ids = set(_SPECIAL_PROVIDER_FACTORIES)
_construction_ids = _profiled_ids | _special_ids | _INJECTED_PROVIDER_IDS
@@ -190,8 +198,8 @@ def create_provider(
config = build_provider_config(descriptor, settings)
admission = ProviderAdmissionController(
provider_name=provider_id,
- rate_limit=config.rate_limit or 40,
- rate_window=config.rate_window or 60.0,
+ rate_limit=config.rate_limit,
+ rate_window=config.rate_window,
max_concurrency=config.max_concurrency,
)
factory = (injected_factories or {}).get(provider_id)
diff --git a/src/free_claude_code/providers/vertex/auth.py b/src/free_claude_code/providers/vertex/auth.py
index 68e81be8..0b3804db 100644
--- a/src/free_claude_code/providers/vertex/auth.py
+++ b/src/free_claude_code/providers/vertex/auth.py
@@ -34,7 +34,7 @@ class GoogleAccessTokenProvider:
self,
credentials_loader: CredentialsLoader = load_application_default_credentials,
*,
- proxy: str = "",
+ proxy: str | None = None,
) -> None:
self._credentials_loader = credentials_loader
self._proxy = proxy
diff --git a/src/free_claude_code/providers/vertex/client.py b/src/free_claude_code/providers/vertex/client.py
index 209a684b..5e0169b7 100644
--- a/src/free_claude_code/providers/vertex/client.py
+++ b/src/free_claude_code/providers/vertex/client.py
@@ -57,7 +57,7 @@ class VertexProvider(GoogleOpenAIProvider):
access_token_provider or GoogleAccessTokenProvider(proxy=config.proxy)
)
self._model_list_client = httpx.AsyncClient(
- proxy=config.proxy or None,
+ proxy=config.proxy,
timeout=httpx.Timeout(
config.http_read_timeout,
connect=config.http_connect_timeout,
diff --git a/src/free_claude_code/providers/vertex/endpoint.py b/src/free_claude_code/providers/vertex/endpoint.py
index df971d4b..43855b2f 100644
--- a/src/free_claude_code/providers/vertex/endpoint.py
+++ b/src/free_claude_code/providers/vertex/endpoint.py
@@ -22,7 +22,7 @@ def vertex_openai_base_url(project_id: str, location: str) -> str:
project = project_id.strip()
if not project:
raise ApplicationUnavailableError(
- "VERTEX_PROJECT_ID is not set. Add it to your .env file."
+ "VERTEX_PROJECT_ID is not set. Add it in the Admin UI."
)
normalized_location = _validated_location(location)
service_endpoint = vertex_service_endpoint(normalized_location)
diff --git a/src/free_claude_code/runtime/application.py b/src/free_claude_code/runtime/application.py
index 213344eb..a92f51d0 100644
--- a/src/free_claude_code/runtime/application.py
+++ b/src/free_claude_code/runtime/application.py
@@ -29,14 +29,11 @@ from free_claude_code.config.admin.persistence import (
)
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.loader import clear_settings_cache
from free_claude_code.config.model_refs import parse_provider_type
from free_claude_code.config.paths import messaging_state_dir_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.config.settings import 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 (
@@ -83,18 +80,6 @@ async def best_effort(
return True
-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, ApplicationUnavailableError):
@@ -150,7 +135,6 @@ class ApplicationRuntime:
return
logger.info("Starting Claude Code Proxy...")
try:
- warn_if_process_auth_token(self.settings)
await self.provider_manager.warm_referenced_model_cache()
self.provider_manager.start_model_list_refresh()
await self._start_messaging_if_configured()
@@ -327,7 +311,7 @@ class ApplicationRuntime:
prepared: PreparedAdminUpdate,
) -> dict[str, Any]:
result = commit_prepared_admin_update(prepared)
- get_settings.cache_clear()
+ clear_settings_cache()
return result
def _restart_metadata(
@@ -411,7 +395,7 @@ class ApplicationRuntime:
workspace_path=workspace,
proxy_root_url=local_proxy_root_url(settings),
allowed_dirs=allowed_dirs,
- auth_token=settings.anthropic_auth_token,
+ auth_token=settings.proxy_auth_token,
log_raw_cli_diagnostics=settings.log_raw_cli_diagnostics,
log_messaging_error_details=settings.log_messaging_error_details,
)
diff --git a/src/free_claude_code/runtime/bootstrap.py b/src/free_claude_code/runtime/bootstrap.py
index 7d86a260..2277f58f 100644
--- a/src/free_claude_code/runtime/bootstrap.py
+++ b/src/free_claude_code/runtime/bootstrap.py
@@ -84,10 +84,16 @@ def _create_transcriber(settings: Settings) -> Transcriber | None:
if settings.whisper_device == "nvidia_nim":
return NvidiaNimTranscriber(
model=settings.whisper_model,
- api_key=settings.nvidia_nim_api_key,
+ api_key=_required_voice_key(settings.nvidia_nim_api_key),
)
return TranscriptionService(
model=settings.whisper_model,
device=settings.whisper_device,
huggingface_api_key=settings.huggingface_api_key,
)
+
+
+def _required_voice_key(api_key: str | None) -> str:
+ if api_key is None:
+ raise AssertionError("NIM voice settings were not validated")
+ return api_key
diff --git a/tests/api/test_admin.py b/tests/api/test_admin.py
index 4d062043..5a800889 100644
--- a/tests/api/test_admin.py
+++ b/tests/api/test_admin.py
@@ -15,6 +15,7 @@ from free_claude_code.application.model_metadata import (
ProviderModelRefreshResult,
)
from free_claude_code.config.admin.values import MASKED_SECRET
+from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
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, provider_manager_for_app
@@ -41,6 +42,7 @@ def _clear_process_config(monkeypatch) -> None:
"BEDROCK_PROXY",
"OLLAMA_API_KEY",
"ANTHROPIC_AUTH_TOKEN",
+ "PROXY_AUTH_ENABLED",
"TELEGRAM_PROXY_URL",
"FCC_ENV_FILE",
"CLOUDFLARE_API_TOKEN",
@@ -362,7 +364,7 @@ def test_admin_static_model_combobox_preserves_custom_slugs_and_none_semantics()
assert '? ["None", ...state.modelOptions]' in script
assert "You can still enter a custom slug." in script
assert 'input.dataset.fieldType === "optional_model"' in script
- assert 'return "";' in script
+ assert "return null;" in script
assert "await hydrateModelOptions();" in script
assert "Model fields remain editable" in script
assert "result.failed_providers || []" in script
@@ -382,6 +384,8 @@ def test_admin_config_masks_secrets_and_exposes_manifest(monkeypatch, tmp_path):
assert "MODEL_FABLE" in keys
assert "REASONING_FABLE" in keys
assert "ANTHROPIC_AUTH_TOKEN" in keys
+ assert "PROXY_AUTH_ENABLED" in keys
+ assert "LOG_LEVEL" in keys
assert "OPENROUTER_API_KEY" in keys
assert "AWS_BEARER_TOKEN_BEDROCK" in keys
assert "BEDROCK_BASE_URL" in keys
@@ -405,11 +409,27 @@ def test_admin_config_masks_secrets_and_exposes_manifest(monkeypatch, tmp_path):
)
assert auth_field["secret"] is True
assert auth_field["value"] == MASKED_SECRET
- assert auth_field["source"] == "template"
+ assert auth_field["source"] == "default"
+ assert auth_field["nullable"] is False
telegram_proxy_field = next(
field for field in body["fields"] if field["key"] == "TELEGRAM_PROXY_URL"
)
assert telegram_proxy_field["secret"] is True
+ assert telegram_proxy_field["value"] is None
+ assert telegram_proxy_field["configured"] is False
+ assert telegram_proxy_field["nullable"] is True
+ assert body["paths"] == {"managed": str(tmp_path / ".fcc" / ".env")}
+ catalog_smoke_keys = {
+ f"FCC_SMOKE_MODEL_{provider_id.upper()}" for provider_id in PROVIDER_CATALOG
+ }
+ actual_smoke_keys = {
+ field["key"]
+ for field in body["fields"]
+ if field["key"].startswith("FCC_SMOKE_MODEL_")
+ }
+ assert actual_smoke_keys == catalog_smoke_keys | {
+ "FCC_SMOKE_MODEL_MISTRAL_REASONING"
+ }
open_browser_field = next(
field for field in body["fields"] if field["key"] == "FCC_OPEN_BROWSER"
)
@@ -602,6 +622,53 @@ def test_admin_apply_masks_telegram_proxy_credentials(monkeypatch, tmp_path):
assert f"TELEGRAM_PROXY_URL={proxy_url}" in text
+def test_admin_apply_null_removes_optional_secret(monkeypatch, tmp_path):
+ _set_home(monkeypatch, tmp_path)
+ _clear_process_config(monkeypatch)
+ env_file = tmp_path / ".fcc" / ".env"
+ env_file.parent.mkdir(parents=True)
+ env_file.write_text(
+ "FCC_CONFIG_SCHEMA=1\nTELEGRAM_PROXY_URL=https://secret.invalid\n",
+ encoding="utf-8",
+ )
+ app = create_test_app()
+
+ response = _local_client(app).post(
+ "/admin/api/config/apply",
+ json={"values": {"TELEGRAM_PROXY_URL": None}},
+ )
+
+ assert response.status_code == 200
+ assert response.json()["applied"] is True
+ assert "TELEGRAM_PROXY_URL=" not in env_file.read_text(encoding="utf-8")
+
+
[email protected]("submitted", [MASKED_SECRET, "", " "])
+def test_admin_apply_masked_or_blank_secret_is_unchanged(
+ monkeypatch,
+ tmp_path,
+ submitted,
+):
+ _set_home(monkeypatch, tmp_path)
+ _clear_process_config(monkeypatch)
+ env_file = tmp_path / ".fcc" / ".env"
+ env_file.parent.mkdir(parents=True)
+ env_file.write_text(
+ "FCC_CONFIG_SCHEMA=1\nOPENROUTER_API_KEY=original-secret\n",
+ encoding="utf-8",
+ )
+ app = create_test_app()
+
+ response = _local_client(app).post(
+ "/admin/api/config/apply",
+ json={"values": {"OPENROUTER_API_KEY": submitted}},
+ )
+
+ assert response.status_code == 200
+ assert response.json()["applied"] is True
+ assert "OPENROUTER_API_KEY=original-secret" in env_file.read_text(encoding="utf-8")
+
+
def test_admin_validate_rejects_bad_model_shape(monkeypatch, tmp_path):
_set_home(monkeypatch, tmp_path)
_clear_process_config(monkeypatch)
@@ -643,7 +710,10 @@ def test_admin_apply_writes_complete_managed_env_and_masks_preview(
text = env_file.read_text("utf-8")
assert "MODEL=open_router/test-model" in text
assert "OPENROUTER_API_KEY=router-secret" in text
- assert "ANTHROPIC_AUTH_TOKEN=" in text
+ assert "ANTHROPIC_AUTH_TOKEN=" not in text
+ assert "PROXY_AUTH_ENABLED=" not in text
+ assert "HOST=" not in text
+ assert "PORT=" not in text
assert body["restart"] == {
"required": False,
"automatic": False,
@@ -850,7 +920,7 @@ def test_admin_apply_writes_huggingface_key_and_masks_preview(monkeypatch, tmp_p
assert response.status_code == 200
body = response.json()
assert body["applied"] is True
- assert body["pending_fields"] == []
+ assert body["pending_fields"] == ["HUGGINGFACE_API_KEY"]
assert "HUGGINGFACE_API_KEY=********" in body["env_preview"]
env_file = tmp_path / ".fcc" / ".env"
text = env_file.read_text(encoding="utf-8")
@@ -1035,7 +1105,7 @@ def test_admin_apply_preserves_hidden_diagnostics_and_smoke_values(
assert "FCC_SMOKE_MODEL_ZAI=zai/smoke-model" in text
-def test_admin_apply_omits_stale_zai_base_url(monkeypatch, tmp_path):
+def test_admin_apply_preserves_unrecognized_managed_zai_base_url(monkeypatch, tmp_path):
_set_home(monkeypatch, tmp_path)
_clear_process_config(monkeypatch)
env_file = tmp_path / ".fcc" / ".env"
@@ -1063,10 +1133,10 @@ def test_admin_apply_omits_stale_zai_base_url(monkeypatch, tmp_path):
assert body["applied"] is True
text = env_file.read_text("utf-8")
assert "ZAI_API_KEY=zai-secret" in text
- assert "ZAI_BASE_URL" not in text
+ assert "ZAI_BASE_URL=https://custom.zai.invalid/v1" in text
-def test_admin_apply_omits_stale_fixed_claude_runtime_settings(monkeypatch, tmp_path):
+def test_admin_apply_preserves_unrecognized_managed_assignments(monkeypatch, tmp_path):
_set_home(monkeypatch, tmp_path)
_clear_process_config(monkeypatch)
env_file = tmp_path / ".fcc" / ".env"
@@ -1094,8 +1164,8 @@ def test_admin_apply_omits_stale_fixed_claude_runtime_settings(monkeypatch, tmp_
assert body["applied"] is True
text = env_file.read_text("utf-8")
assert "MODEL=open_router/test-model" in text
- assert "CLAUDE_WORKSPACE" not in text
- assert "CLAUDE_CLI_BIN" not in text
+ assert "CLAUDE_WORKSPACE=C:/custom/workspace" in text
+ assert "CLAUDE_CLI_BIN=claude-custom" in text
def test_admin_apply_restart_required_reports_automatic_restart(monkeypatch, tmp_path):
@@ -1169,7 +1239,7 @@ def test_admin_process_env_values_are_locked_and_not_written(monkeypatch, tmp_pa
assert "deepseek/managed-model" not in env_file.read_text("utf-8")
-def test_admin_first_apply_migrates_repo_env(monkeypatch, tmp_path):
+def test_admin_never_reads_arbitrary_current_directory_env(monkeypatch, tmp_path):
_set_home(monkeypatch, tmp_path)
_clear_process_config(monkeypatch)
monkeypatch.chdir(tmp_path)
@@ -1181,8 +1251,8 @@ def test_admin_first_apply_migrates_repo_env(monkeypatch, tmp_path):
config = _local_client(app).get("/admin/api/config").json()
model_field = next(field for field in config["fields"] if field["key"] == "MODEL")
- assert model_field["value"] == "deepseek/deepseek-chat"
- assert model_field["source"] == "repo_env"
+ assert model_field["value"] == "nvidia_nim/nvidia/nemotron-3-super-120b-a12b"
+ assert model_field["source"] == "default"
response = _local_client(app).post(
"/admin/api/config/apply",
@@ -1191,18 +1261,20 @@ def test_admin_first_apply_migrates_repo_env(monkeypatch, tmp_path):
assert response.status_code == 200
managed_text = (tmp_path / ".fcc" / ".env").read_text("utf-8")
- assert "MODEL=deepseek/deepseek-chat" in managed_text
- assert "DEEPSEEK_API_KEY=deepseek-secret" in managed_text
+ assert "MODEL=deepseek/deepseek-chat" not in managed_text
+ assert "DEEPSEEK_API_KEY=deepseek-secret" not in managed_text
-def test_admin_first_apply_repairs_empty_select_repo_values(monkeypatch, tmp_path):
+def test_admin_migration_removes_blank_required_managed_values(monkeypatch, tmp_path):
_set_home(monkeypatch, tmp_path)
_clear_process_config(monkeypatch)
- app = create_test_app()
- (tmp_path / ".env").write_text(
+ env_file = tmp_path / ".fcc" / ".env"
+ env_file.parent.mkdir(parents=True)
+ env_file.write_text(
"MESSAGING_PLATFORM=\nWHISPER_DEVICE=\n",
encoding="utf-8",
)
+ app = create_test_app()
response = _local_client(app).post(
"/admin/api/config/apply",
@@ -1213,11 +1285,13 @@ def test_admin_first_apply_repairs_empty_select_repo_values(monkeypatch, tmp_pat
assert response.json()["applied"] is True
managed_text = (tmp_path / ".fcc" / ".env").read_text("utf-8")
assert "NVIDIA_NIM_API_KEY=nim-secret" in managed_text
- assert "MESSAGING_PLATFORM=discord" in managed_text
- assert "WHISPER_DEVICE=nvidia_nim" in managed_text
+ assert "MESSAGING_PLATFORM=" not in managed_text
+ assert "WHISPER_DEVICE=" not in managed_text
-def test_admin_apply_preserves_empty_managed_auth_token(monkeypatch, tmp_path):
+def test_admin_migrates_empty_auth_token_to_explicit_disabled_state(
+ monkeypatch, tmp_path
+):
_set_home(monkeypatch, tmp_path)
_clear_process_config(monkeypatch)
env_file = tmp_path / ".fcc" / ".env"
@@ -1236,11 +1310,25 @@ def test_admin_apply_preserves_empty_managed_auth_token(monkeypatch, tmp_path):
assert response.status_code == 200
assert response.json()["applied"] is True
managed_lines = env_file.read_text("utf-8").splitlines()
- assert "ANTHROPIC_AUTH_TOKEN=" in managed_lines
+ assert not any(line.startswith("ANTHROPIC_AUTH_TOKEN=") for line in managed_lines)
+ assert "PROXY_AUTH_ENABLED=false" in managed_lines
assert "PROVIDER_RATE_LIMIT=2" in managed_lines
-def test_admin_apply_rejects_explicit_empty_select_update(monkeypatch, tmp_path):
+ ("submitted", "message"),
+ [
+ (None, "this setting cannot be removed"),
+ ("", "this setting cannot be blank"),
+ (" ", "this setting cannot be blank"),
+ ],
+)
+def test_admin_apply_rejects_missing_required_value_without_writing(
+ monkeypatch,
+ tmp_path,
+ submitted,
+ message,
+):
_set_home(monkeypatch, tmp_path)
_clear_process_config(monkeypatch)
env_file = tmp_path / ".fcc" / ".env"
@@ -1248,50 +1336,42 @@ def test_admin_apply_rejects_explicit_empty_select_update(monkeypatch, tmp_path)
original = "ANTHROPIC_AUTH_TOKEN=\nMESSAGING_PLATFORM=none\n"
env_file.write_text(original, encoding="utf-8")
app = create_test_app()
+ _local_client(app).get("/admin/api/config")
+ baseline = env_file.read_bytes()
response = _local_client(app).post(
"/admin/api/config/apply",
- json={"values": {"MESSAGING_PLATFORM": ""}},
+ json={"values": {"MESSAGING_PLATFORM": submitted}},
)
assert response.status_code == 200
body = response.json()
assert body["applied"] is False
assert body["valid"] is False
- assert any(
- "messaging_platform" in error and "got ''" in error for error in body["errors"]
- )
- assert env_file.read_text("utf-8") == original
+ assert f"MESSAGING_PLATFORM: {message}" in body["errors"]
+ assert env_file.read_bytes() == baseline
[email protected]("source", ("process", "explicit_env_file"))
-def test_admin_apply_rejects_empty_locked_select_value(
- monkeypatch,
- tmp_path,
- source,
-):
+def test_admin_apply_preserves_false_and_numeric_zero(monkeypatch, tmp_path):
_set_home(monkeypatch, tmp_path)
_clear_process_config(monkeypatch)
app = create_test_app()
- if source == "process":
- monkeypatch.setenv("MESSAGING_PLATFORM", "")
- else:
- env_file = tmp_path / "locked.env"
- env_file.write_text("MESSAGING_PLATFORM=\n", encoding="utf-8")
- monkeypatch.setenv("FCC_ENV_FILE", str(env_file))
response = _local_client(app).post(
"/admin/api/config/apply",
- json={"values": {"NVIDIA_NIM_API_KEY": "nim-secret"}},
+ json={
+ "values": {
+ "FCC_OPEN_BROWSER": False,
+ "HTTP_WRITE_TIMEOUT": 0,
+ }
+ },
)
assert response.status_code == 200
- body = response.json()
- assert body["applied"] is False
- assert any(
- "messaging_platform" in error and "got ''" in error for error in body["errors"]
- )
- assert not (tmp_path / ".fcc" / ".env").exists()
+ assert response.json()["applied"] is True
+ managed = (tmp_path / ".fcc" / ".env").read_text(encoding="utf-8")
+ assert "FCC_OPEN_BROWSER=false" in managed
+ assert "HTTP_WRITE_TIMEOUT=0" in managed
def test_admin_local_provider_status_reports_reachable(monkeypatch, tmp_path):
diff --git a/tests/api/test_app_lifespan_and_errors.py b/tests/api/test_app_lifespan_and_errors.py
index 3f65aff9..dca8b2a1 100644
--- a/tests/api/test_app_lifespan_and_errors.py
+++ b/tests/api/test_app_lifespan_and_errors.py
@@ -19,7 +19,6 @@ from free_claude_code.providers.nvidia_nim.voice import NvidiaNimTranscriber
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 _create_transcriber, build_asgi_app
@@ -38,29 +37,6 @@ def _redirect_fcc_home(monkeypatch, tmp_path):
monkeypatch.setenv("USERPROFILE", str(home))
-def test_warn_if_process_auth_token_logs_warning(monkeypatch):
- monkeypatch.setenv("ANTHROPIC_AUTH_TOKEN", "process-token")
- monkeypatch.setitem(Settings.model_config, "env_file", ())
-
- 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):
- 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,))
-
- 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():
settings = _settings(
@@ -383,6 +359,7 @@ def test_bootstrap_constructs_fresh_runtime_owned_transcribers() -> None:
async def test_bootstrap_constructs_isolated_runtime_resource_graphs() -> None:
settings = _settings(
model="nvidia_nim/test-model",
+ nvidia_nim_api_key="test-key",
voice_note_enabled=True,
whisper_device="cpu",
)
diff --git a/tests/api/test_auth.py b/tests/api/test_auth.py
index c26ce2bd..fd5f3ce5 100644
--- a/tests/api/test_auth.py
+++ b/tests/api/test_auth.py
@@ -11,8 +11,7 @@ app = create_test_app()
def test_proxy_auth_requires_canonical_bearer_header():
client = TestClient(app)
- settings = Settings()
- settings.anthropic_auth_token = "s3cr3t"
+ settings = Settings(proxy_auth_enabled=True, proxy_auth_token="s3cr3t")
app.dependency_overrides[get_settings] = lambda: settings
payload = {
@@ -52,8 +51,7 @@ def test_proxy_auth_requires_canonical_bearer_header():
def test_proxy_auth_ignores_conflicting_legacy_headers():
client = TestClient(app)
- settings = Settings()
- settings.anthropic_auth_token = "b3artoken"
+ settings = Settings(proxy_auth_enabled=True, proxy_auth_token="b3artoken")
app.dependency_overrides[get_settings] = lambda: settings
payload = {
@@ -88,10 +86,12 @@ def test_proxy_auth_ignores_conflicting_legacy_headers():
app.dependency_overrides.clear()
-def test_anthropic_auth_token_normalizes_configured_whitespace():
+def test_proxy_auth_token_normalizes_configured_whitespace():
client = TestClient(app)
- settings = Settings()
- settings.anthropic_auth_token = " spaced-token \n"
+ settings = Settings(
+ proxy_auth_enabled=True,
+ proxy_auth_token=" spaced-token \n",
+ )
app.dependency_overrides[get_settings] = lambda: settings
payload = {
@@ -111,10 +111,9 @@ def test_anthropic_auth_token_normalizes_configured_whitespace():
app.dependency_overrides.clear()
-def test_anthropic_auth_token_applies_to_models_endpoint():
+def test_proxy_auth_token_applies_to_models_endpoint():
client = TestClient(app)
- settings = Settings()
- settings.anthropic_auth_token = "models-token"
+ settings = Settings(proxy_auth_enabled=True, proxy_auth_token="models-token")
app.dependency_overrides[get_settings] = lambda: settings
r = client.get("/v1/models")
@@ -131,8 +130,7 @@ def test_anthropic_auth_token_applies_to_models_endpoint():
def test_root_get_requires_auth_but_root_probes_are_public():
client = TestClient(app)
- settings = Settings()
- settings.anthropic_auth_token = "root-token"
+ settings = Settings(proxy_auth_enabled=True, proxy_auth_token="root-token")
app.dependency_overrides[get_settings] = lambda: settings
response = client.get("/")
diff --git a/tests/api/test_dependencies.py b/tests/api/test_dependencies.py
index 0bffdeec..c3b1b2cc 100644
--- a/tests/api/test_dependencies.py
+++ b/tests/api/test_dependencies.py
@@ -16,7 +16,12 @@ from free_claude_code.config.settings import Settings
from tests.api.support import create_test_app
-def _request(*, headers: dict[str, str], token: str) -> tuple[Request, Settings]:
+def _request(
+ *,
+ headers: dict[str, str],
+ token: str = "freecc",
+ enabled: bool = True,
+) -> tuple[Request, Settings]:
request = Request(
{
"type": "http",
@@ -27,7 +32,10 @@ def _request(*, headers: dict[str, str], token: str) -> tuple[Request, Settings]
],
}
)
- settings = Settings.model_construct(anthropic_auth_token=token)
+ settings = Settings.model_construct(
+ proxy_auth_enabled=enabled,
+ proxy_auth_token=token,
+ )
return request, settings
@@ -55,7 +63,8 @@ def test_get_settings_reads_current_request_runtime_settings() -> None:
app = create_test_app(
Settings.model_construct(
model="deepseek/test-model",
- anthropic_auth_token="",
+ proxy_auth_enabled=False,
+ proxy_auth_token="freecc",
)
)
@@ -106,8 +115,8 @@ def test_resolve_provider_unrelated_error_is_not_reclassified() -> None:
resolve_provider("nvidia_nim", lease=lease)
-def test_require_proxy_auth_allows_when_no_token_configured():
- request, settings = _request(headers={}, token="")
+def test_require_proxy_auth_allows_when_disabled_with_retained_token():
+ request, settings = _request(headers={}, enabled=False)
require_proxy_auth(request, settings)
diff --git a/tests/api/test_model_listing.py b/tests/api/test_model_listing.py
index 528bb39c..f1073ffa 100644
--- a/tests/api/test_model_listing.py
+++ b/tests/api/test_model_listing.py
@@ -18,7 +18,8 @@ def _settings(
model_opus=model_opus,
model_sonnet=None,
model_haiku=model_haiku,
- anthropic_auth_token="",
+ proxy_auth_enabled=False,
+ proxy_auth_token="freecc",
deepseek_api_key="deepseek-key",
open_router_api_key="open-router-key",
wafer_api_key="wafer-key",
diff --git a/tests/api/test_openai_codex_compatibility.py b/tests/api/test_openai_codex_compatibility.py
index 30ed614b..758d4000 100644
--- a/tests/api/test_openai_codex_compatibility.py
+++ b/tests/api/test_openai_codex_compatibility.py
@@ -10,13 +10,13 @@ from free_claude_code.core.anthropic.stream_contracts import (
text_content,
)
from free_claude_code.providers.admission import ProviderAdmissionController
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_codex.auth import (
OpenAIAccess,
OpenAIAuthManager,
)
from free_claude_code.providers.openai_codex.provider import OpenAICodexProvider
from tests.api.support import create_test_app
+from tests.providers.support import make_provider_config
class _FakeOpenAIAuth(OpenAIAuthManager):
@@ -71,7 +71,7 @@ async def test_messages_accepts_current_claude_controls_for_openai_provider() ->
transport=httpx.MockTransport(handler),
)
provider = OpenAICodexProvider(
- ProviderConfig(
+ make_provider_config(
api_key="",
base_url="https://chatgpt.com/backend-api/codex",
rate_limit=100,
diff --git a/tests/api/test_ordinary_error_phases.py b/tests/api/test_ordinary_error_phases.py
index 16556ee8..00f5c452 100644
--- a/tests/api/test_ordinary_error_phases.py
+++ b/tests/api/test_ordinary_error_phases.py
@@ -39,7 +39,7 @@ _PRODUCT_REQUESTS = (
def _settings(**updates: object) -> Settings:
return Settings().model_copy(
update={
- "anthropic_auth_token": "",
+ "proxy_auth_enabled": False,
"log_api_error_tracebacks": False,
**updates,
}
@@ -101,7 +101,7 @@ def test_missing_provider_credential_is_protocol_specific_503_without_terminal_h
payload: dict[str, object],
) -> None:
message = (
- "OPENROUTER_API_KEY is not set. Add it to your .env file. "
+ "OPENROUTER_API_KEY is not set. Add it in the Admin UI. "
"Get a key at https://openrouter.ai/keys"
)
app = create_test_app(
@@ -241,7 +241,7 @@ def test_proxy_auth_preserves_ingress_detail_contract(
headers: dict[str, str],
detail: str,
) -> None:
- app = create_test_app(_settings(anthropic_auth_token="secret"))
+ app = create_test_app(_settings(proxy_auth_enabled=True, proxy_auth_token="secret"))
with TestClient(app) as client:
response = client.post(path, json=payload, headers=headers)
diff --git a/tests/cli/test_cli.py b/tests/cli/test_cli.py
index eda69150..70a2dada 100644
--- a/tests/cli/test_cli.py
+++ b/tests/cli/test_cli.py
@@ -158,6 +158,7 @@ class TestManagedClaudeSession:
workspace_path="/tmp/test",
proxy_root_url="http://localhost:8082",
allowed_dirs=["/home/user/projects"],
+ auth_token="freecc",
)
assert session.workspace == os.path.normpath(os.path.abspath("/tmp/test"))
assert session.proxy_root_url == "http://localhost:8082"
@@ -200,7 +201,9 @@ class TestManagedClaudeSession:
"""Test start_task running a basic command flow."""
from free_claude_code.cli.managed.session import ManagedClaudeSession
- session = ManagedClaudeSession("/tmp", "http://localhost:8082")
+ session = ManagedClaudeSession(
+ "/tmp", "http://localhost:8082", auth_token="freecc"
+ )
# Mock subprocess
mock_process = AsyncMock()
@@ -244,7 +247,9 @@ class TestManagedClaudeSession:
"""Test resuming an existing session."""
from free_claude_code.cli.managed.session import ManagedClaudeSession
- session = ManagedClaudeSession("/tmp", "http://localhost:8082")
+ session = ManagedClaudeSession(
+ "/tmp", "http://localhost:8082", auth_token="freecc"
+ )
mock_process = AsyncMock()
mock_process.stdout.read.side_effect = [
@@ -271,7 +276,9 @@ class TestManagedClaudeSession:
"""Test resuming an existing session and forking."""
from free_claude_code.cli.managed.session import ManagedClaudeSession
- session = ManagedClaudeSession("/tmp", "http://localhost:8082")
+ session = ManagedClaudeSession(
+ "/tmp", "http://localhost:8082", auth_token="freecc"
+ )
mock_process = AsyncMock()
mock_process.stdout.read.side_effect = [b""] # Immediate EOF
@@ -298,7 +305,9 @@ class TestManagedClaudeSession:
"""Test process exit with error code and stderr output."""
from free_claude_code.cli.managed.session import ManagedClaudeSession
- session = ManagedClaudeSession("/tmp", "http://localhost:8082")
+ session = ManagedClaudeSession(
+ "/tmp", "http://localhost:8082", auth_token="freecc"
+ )
mock_process = AsyncMock()
mock_process.stdout.read.side_effect = [b""] # No stdout
@@ -326,7 +335,9 @@ class TestManagedClaudeSession:
"""Stderr is drained concurrently so stdout streaming is not blocked."""
from free_claude_code.cli.managed.session import ManagedClaudeSession
- session = ManagedClaudeSession("/tmp", "http://localhost:8082")
+ session = ManagedClaudeSession(
+ "/tmp", "http://localhost:8082", auth_token="freecc"
+ )
mock_process = AsyncMock()
mock_process.stdout.read.side_effect = [
@@ -355,7 +366,9 @@ class TestManagedClaudeSession:
"""Known Claude diagnostics on stderr are not surfaced as task failures."""
from free_claude_code.cli.managed.session import ManagedClaudeSession
- session = ManagedClaudeSession("/tmp", "http://localhost:8082")
+ session = ManagedClaudeSession(
+ "/tmp", "http://localhost:8082", auth_token="freecc"
+ )
mock_process = AsyncMock()
mock_process.stdout.read.side_effect = [
@@ -383,7 +396,9 @@ class TestManagedClaudeSession:
"""Benign stderr diagnostics are filtered without hiding real failures."""
from free_claude_code.cli.managed.session import ManagedClaudeSession
- session = ManagedClaudeSession("/tmp", "http://localhost:8082")
+ session = ManagedClaudeSession(
+ "/tmp", "http://localhost:8082", auth_token="freecc"
+ )
mock_process = AsyncMock()
mock_process.stdout.read.side_effect = [b""]
@@ -411,7 +426,9 @@ class TestManagedClaudeSession:
"""A benign stderr line is not duplicated as the process failure reason."""
from free_claude_code.cli.managed.session import ManagedClaudeSession
- session = ManagedClaudeSession("/tmp", "http://localhost:8082")
+ session = ManagedClaudeSession(
+ "/tmp", "http://localhost:8082", auth_token="freecc"
+ )
mock_process = AsyncMock()
mock_process.stdout.read.side_effect = [b""]
@@ -465,7 +482,9 @@ class TestManagedClaudeSession:
"""Test stopping the session process."""
from free_claude_code.cli.managed.session import ManagedClaudeSession
- session = ManagedClaudeSession("/tmp", "http://localhost:8082")
+ session = ManagedClaudeSession(
+ "/tmp", "http://localhost:8082", auth_token="freecc"
+ )
mock_process = MagicMock()
mock_process.returncode = None # Running
@@ -488,7 +507,9 @@ class TestManagedClaudeSession:
"""Test force kill if terminate times out."""
from free_claude_code.cli.managed.session import ManagedClaudeSession
- session = ManagedClaudeSession("/tmp", "http://localhost:8082")
+ session = ManagedClaudeSession(
+ "/tmp", "http://localhost:8082", auth_token="freecc"
+ )
mock_process = MagicMock()
mock_process.returncode = None
@@ -518,7 +539,9 @@ class TestManagedClaudeSession:
"""Test handling of JSON split across chunks."""
from free_claude_code.cli.managed.session import ManagedClaudeSession
- session = ManagedClaudeSession("/tmp", "http://localhost:8082")
+ session = ManagedClaudeSession(
+ "/tmp", "http://localhost:8082", auth_token="freecc"
+ )
mock_process = AsyncMock()
# Split json: {"type": "mess... age"}
@@ -547,7 +570,9 @@ class TestManagedClaudeSession:
"""Test handling of buffer remnant at EOF (no newline at end)."""
from free_claude_code.cli.managed.session import ManagedClaudeSession
- session = ManagedClaudeSession("/tmp", "http://localhost:8082")
+ session = ManagedClaudeSession(
+ "/tmp", "http://localhost:8082", auth_token="freecc"
+ )
mock_process = AsyncMock()
mock_process.stdout.read.side_effect = [
@@ -574,7 +599,9 @@ class TestManagedClaudeSession:
"""Test start_task passes the configured proxy root to Claude Code."""
from free_claude_code.cli.managed.session import ManagedClaudeSession
- session = ManagedClaudeSession("/tmp", "http://localhost:8082")
+ session = ManagedClaudeSession(
+ "/tmp", "http://localhost:8082", auth_token="freecc"
+ )
mock_process = AsyncMock()
mock_process.stdout.read.side_effect = [b""]
@@ -630,7 +657,11 @@ class TestManagedClaudeSession:
"""Test start_task does not leak inherited Claude auth into proxy calls."""
from free_claude_code.cli.managed.session import ManagedClaudeSession
- session = ManagedClaudeSession("/tmp", "http://localhost:8082", auth_token="")
+ session = ManagedClaudeSession(
+ "/tmp",
+ "http://localhost:8082",
+ auth_token="freecc",
+ )
mock_process = AsyncMock()
mock_process.stdout.read.side_effect = [b""]
@@ -648,7 +679,7 @@ class TestManagedClaudeSession:
pass
env = mock_exec.call_args.kwargs["env"]
- assert env["ANTHROPIC_AUTH_TOKEN"] == "fcc-no-auth"
+ assert env["ANTHROPIC_AUTH_TOKEN"] == "freecc"
@pytest.mark.asyncio
async def test_start_task_allowed_dirs(self):
@@ -656,7 +687,10 @@ class TestManagedClaudeSession:
from free_claude_code.cli.managed.session import ManagedClaudeSession
session = ManagedClaudeSession(
- "/tmp", "http://localhost:8082", allowed_dirs=["/dir1", "/dir2"]
+ "/tmp",
+ "http://localhost:8082",
+ allowed_dirs=["/dir1", "/dir2"],
+ auth_token="freecc",
)
mock_process = AsyncMock()
@@ -681,7 +715,9 @@ class TestManagedClaudeSession:
"""Test handling of non-JSON output from free_claude_code.cli."""
from free_claude_code.cli.managed.session import ManagedClaudeSession
- session = ManagedClaudeSession("/tmp", "http://localhost:8082")
+ session = ManagedClaudeSession(
+ "/tmp", "http://localhost:8082", auth_token="freecc"
+ )
mock_process = AsyncMock()
mock_process.stdout.read.side_effect = [b"Not valid json\n", b""]
@@ -703,7 +739,9 @@ class TestManagedClaudeSession:
"""Test exception handling during stop."""
from free_claude_code.cli.managed.session import ManagedClaudeSession
- session = ManagedClaudeSession("/tmp", "http://localhost:8082")
+ session = ManagedClaudeSession(
+ "/tmp", "http://localhost:8082", auth_token="freecc"
+ )
mock_process = MagicMock()
mock_process.returncode = None
@@ -729,6 +767,7 @@ class TestManagedClaudeSessionManager:
manager = ManagedClaudeSessionManager(
workspace_path="/tmp/test",
proxy_root_url="http://localhost:8082",
+ auth_token="freecc",
)
session, sid, is_new = await manager.get_or_create_session()
@@ -744,6 +783,7 @@ class TestManagedClaudeSessionManager:
manager = ManagedClaudeSessionManager(
workspace_path="/tmp/test",
proxy_root_url="http://localhost:8082",
+ auth_token="freecc",
)
# Create first session
@@ -763,6 +803,7 @@ class TestManagedClaudeSessionManager:
manager = ManagedClaudeSessionManager(
workspace_path="/tmp/test",
proxy_root_url="http://localhost:8082",
+ auth_token="freecc",
)
stats = manager.get_stats()
diff --git a/tests/cli/test_cli_manager_edge_cases.py b/tests/cli/test_cli_manager_edge_cases.py
index a06762fa..e3bc7c73 100644
--- a/tests/cli/test_cli_manager_edge_cases.py
+++ b/tests/cli/test_cli_manager_edge_cases.py
@@ -41,7 +41,7 @@ async def test_register_real_session_id_missing_temp_id_returns_false():
from free_claude_code.cli.managed.manager import ManagedClaudeSessionManager
manager = ManagedClaudeSessionManager(
- workspace_path="/tmp", proxy_root_url="http://x"
+ workspace_path="/tmp", proxy_root_url="http://x", auth_token="freecc"
)
ok = await manager.register_real_session_id("missing", "real_1")
assert ok is False
@@ -60,7 +60,7 @@ async def test_remove_session_pending_stops_and_returns_true():
mock_session_cls.return_value = mock_session
manager = ManagedClaudeSessionManager(
- workspace_path="/tmp", proxy_root_url="http://x"
+ workspace_path="/tmp", proxy_root_url="http://x", auth_token="freecc"
)
_, temp_id, _ = await manager.get_or_create_session()
@@ -82,7 +82,7 @@ async def test_remove_session_active_removes_temp_mapping():
mock_session_cls.return_value = mock_session
manager = ManagedClaudeSessionManager(
- workspace_path="/tmp", proxy_root_url="http://x"
+ workspace_path="/tmp", proxy_root_url="http://x", auth_token="freecc"
)
_, temp_id, _ = await manager.get_or_create_session()
await manager.register_real_session_id(temp_id, "real_1")
@@ -101,7 +101,7 @@ async def test_stop_all_reports_and_retains_stop_exceptions():
from free_claude_code.cli.managed.manager import ManagedClaudeSessionManager
manager = ManagedClaudeSessionManager(
- workspace_path="/tmp", proxy_root_url="http://x"
+ workspace_path="/tmp", proxy_root_url="http://x", auth_token="freecc"
)
s1 = MagicMock()
diff --git a/tests/cli/test_cli_ownership.py b/tests/cli/test_cli_ownership.py
index 03a099f6..396490fc 100644
--- a/tests/cli/test_cli_ownership.py
+++ b/tests/cli/test_cli_ownership.py
@@ -9,9 +9,11 @@ def test_cli_session_owns_typed_runner_config(tmp_path: Path) -> None:
proxy_root_url="http://127.0.0.1:8082",
allowed_dirs=[str(tmp_path)],
claude_bin="claude-test",
+ auth_token="freecc",
)
assert session.config.workspace_path == str(tmp_path)
assert session.config.proxy_root_url == "http://127.0.0.1:8082"
assert session.config.allowed_dirs == [str(tmp_path)]
assert session.config.claude_bin == "claude-test"
+ assert session.config.auth_token == "freecc"
diff --git a/tests/cli/test_entrypoints.py b/tests/cli/test_entrypoints.py
index 5e08f3de..8fc7b95a 100644
--- a/tests/cli/test_entrypoints.py
+++ b/tests/cli/test_entrypoints.py
@@ -22,10 +22,11 @@ def _launcher_settings(
token: str = "freecc",
open_admin_browser: bool = True,
) -> Settings:
- return Settings.model_construct(
+ return Settings(
host="0.0.0.0",
port=port,
- anthropic_auth_token=token,
+ proxy_auth_enabled=False,
+ proxy_auth_token=token,
model="nvidia_nim/test-model",
open_admin_browser=open_admin_browser,
)
@@ -45,42 +46,6 @@ class _JsonResponse:
return json.dumps(self._payload).encode("utf-8")
-def test_legacy_env_migration_supports_xdg_path(tmp_path: Path) -> None:
- """Server startup preserves config from ~/.config/free-claude-code/.env."""
- from free_claude_code.cli.commands import _migrate_legacy_env_if_missing
-
- legacy_env = tmp_path / ".config" / "free-claude-code" / ".env"
- legacy_env.parent.mkdir(parents=True)
- legacy_env.write_text("MODEL=open_router/free-model\n", encoding="utf-8")
-
- with patch("pathlib.Path.home", return_value=tmp_path):
- migrated_from = _migrate_legacy_env_if_missing()
-
- env_file = tmp_path / ".fcc" / ".env"
- assert migrated_from == legacy_env
- assert env_file.read_text("utf-8") == "MODEL=open_router/free-model\n"
-
-
-def test_legacy_env_migration_does_not_overwrite_managed_env(
- tmp_path: Path,
-) -> None:
- """Legacy migration never overwrites an existing ~/.fcc/.env."""
- from free_claude_code.cli.commands import _migrate_legacy_env_if_missing
-
- managed_env = tmp_path / ".fcc" / ".env"
- managed_env.parent.mkdir(parents=True)
- managed_env.write_text("MODEL=nvidia_nim/current\n", encoding="utf-8")
- legacy_env = tmp_path / "free-claude-code" / ".env"
- legacy_env.parent.mkdir(parents=True)
- legacy_env.write_text("MODEL=deepseek/legacy\n", encoding="utf-8")
-
- with patch("pathlib.Path.home", return_value=tmp_path):
- migrated_from = _migrate_legacy_env_if_missing()
-
- assert migrated_from is None
- assert managed_env.read_text("utf-8") == "MODEL=nvidia_nim/current\n"
-
-
def test_cli_scripts_are_registered() -> None:
pyproject = tomllib.loads(
(Path(__file__).resolve().parents[2] / "pyproject.toml").read_text(
@@ -186,7 +151,6 @@ def test_serve_skips_admin_browser_when_setting_is_disabled() -> None:
settings = _launcher_settings(open_admin_browser=False)
get_settings = MagicMock(return_value=settings)
- get_settings.cache_clear = MagicMock()
with (
patch.object(commands, "get_settings", get_settings),
@@ -209,7 +173,6 @@ def test_serve_supervisor_restarts_when_app_requests_restart() -> None:
settings = _launcher_settings()
get_settings = MagicMock(side_effect=[settings, settings])
- get_settings.cache_clear = MagicMock()
servers: list[object] = []
restart_callbacks: list[Callable[[], None]] = []
@@ -242,13 +205,14 @@ def test_serve_supervisor_restarts_when_app_requests_restart() -> None:
patch.object(commands.uvicorn, "Server", side_effect=FakeServer),
patch.object(commands, "build_asgi_app", side_effect=build_asgi_app),
patch.object(commands, "schedule_open_admin_browser") as schedule_open_admin,
+ patch.object(commands, "clear_settings_cache") as clear_settings_cache,
patch.object(commands, "kill_all_best_effort") as kill_all,
):
commands.serve()
assert len(servers) == 2
schedule_open_admin.assert_called_once_with(settings)
- get_settings.cache_clear.assert_called_once()
+ clear_settings_cache.assert_called_once()
kill_all.assert_called_once()
@@ -257,7 +221,6 @@ def test_serve_supervisor_refuses_restart_after_incomplete_shutdown() -> None:
settings = _launcher_settings()
get_settings = MagicMock(return_value=settings)
- get_settings.cache_clear = MagicMock()
servers: list[object] = []
restart_callbacks: list[Callable[[], None]] = []
@@ -284,123 +247,21 @@ def test_serve_supervisor_refuses_restart_after_incomplete_shutdown() -> None:
patch.object(commands.uvicorn, "Server", side_effect=FakeServer),
patch.object(commands, "build_asgi_app", side_effect=build_asgi_app),
patch.object(commands, "schedule_open_admin_browser"),
+ patch.object(commands, "clear_settings_cache") as clear_settings_cache,
patch.object(commands, "kill_all_best_effort") as kill_all,
):
commands.serve()
assert len(servers) == 1
- get_settings.cache_clear.assert_not_called()
+ clear_settings_cache.assert_not_called()
kill_all.assert_called_once()
-def test_serve_migrates_legacy_env_before_loading_settings(tmp_path: Path) -> None:
- from free_claude_code.cli import commands
-
- legacy_env = tmp_path / "free-claude-code" / ".env"
- legacy_env.parent.mkdir(parents=True)
- legacy_env.write_text("MODEL=deepseek/deepseek-chat\n", encoding="utf-8")
- settings = _launcher_settings()
- get_settings = MagicMock(return_value=settings)
- get_settings.cache_clear = MagicMock()
-
- with (
- patch("pathlib.Path.home", return_value=tmp_path),
- patch.object(commands, "get_settings", get_settings),
- patch.object(commands.ServerSupervisor, "_run_once", return_value=False),
- patch.object(commands, "kill_all_best_effort"),
- ):
- commands.serve()
-
- assert (tmp_path / ".fcc" / ".env").read_text("utf-8") == (
- "MODEL=deepseek/deepseek-chat\n"
- )
- get_settings.assert_called_once_with()
-
-
-def test_serve_migrates_hf_token_before_loading_settings(
- monkeypatch: pytest.MonkeyPatch,
- tmp_path: Path,
-) -> None:
- from free_claude_code.cli import commands
-
- repo = tmp_path / "repo"
- repo.mkdir()
- (repo / ".env").write_text("HF_TOKEN=legacy-hf\n", encoding="utf-8")
- settings = _launcher_settings()
- get_settings = MagicMock(return_value=settings)
- get_settings.cache_clear = MagicMock()
- monkeypatch.chdir(repo)
-
- with (
- patch("pathlib.Path.home", return_value=tmp_path),
- patch.object(commands, "get_settings", get_settings),
- patch.object(commands.ServerSupervisor, "_run_once", return_value=False),
- patch.object(commands, "kill_all_best_effort"),
- patch.object(commands, "explicit_env_file_migration_warning"),
- ):
- commands.serve()
-
- assert (repo / ".env").read_text(encoding="utf-8") == (
- "HUGGINGFACE_API_KEY=legacy-hf\n"
- )
- get_settings.assert_called_once_with()
-
-
-def test_serve_migrates_opencode_zen_prefix_before_loading_settings(
- monkeypatch: pytest.MonkeyPatch,
- tmp_path: Path,
-) -> None:
- from free_claude_code.cli import commands
-
- repo = tmp_path / "repo"
- repo.mkdir()
- env_file = repo / ".env"
- env_file.write_text("MODEL=opencode/model\n", encoding="utf-8")
- settings = _launcher_settings()
-
- def load_settings() -> Settings:
- assert env_file.read_text(encoding="utf-8") == ("MODEL=opencode_zen/model\n")
- return settings
-
- get_settings = MagicMock(side_effect=load_settings)
- get_settings.cache_clear = MagicMock()
- monkeypatch.chdir(repo)
-
- with (
- patch("pathlib.Path.home", return_value=tmp_path),
- patch.object(commands, "get_settings", get_settings),
- patch.object(commands.ServerSupervisor, "_run_once", return_value=False),
- patch.object(commands, "kill_all_best_effort"),
- patch.object(commands, "explicit_env_file_migration_warning"),
- ):
- commands.serve()
-
- get_settings.assert_called_once_with()
-
-
-def test_config_env_migration_warns_for_explicit_env_file(
- tmp_path: Path,
- capsys: pytest.CaptureFixture[str],
-) -> None:
- from free_claude_code.cli import commands
-
- explicit = tmp_path / "custom.env"
- explicit.write_text("HF_TOKEN=legacy-hf\n", encoding="utf-8")
-
- with patch.dict(commands.os.environ, {"FCC_ENV_FILE": str(explicit)}):
- migrated = commands._migrate_config_env()
-
- assert migrated == ()
- assert "HF_TOKEN" in capsys.readouterr().err
- assert explicit.read_text(encoding="utf-8") == "HF_TOKEN=legacy-hf\n"
-
-
def test_serve_handles_keyboard_interrupt_without_traceback() -> None:
from free_claude_code.cli import commands
settings = _launcher_settings()
get_settings = MagicMock(return_value=settings)
- get_settings.cache_clear = MagicMock()
with (
patch.object(commands, "get_settings", get_settings),
@@ -409,11 +270,12 @@ def test_serve_handles_keyboard_interrupt_without_traceback() -> None:
"_run_once",
side_effect=KeyboardInterrupt,
),
+ patch.object(commands, "clear_settings_cache") as clear_settings_cache,
patch.object(commands, "kill_all_best_effort") as kill_all,
):
commands.serve()
- get_settings.cache_clear.assert_not_called()
+ clear_settings_cache.assert_not_called()
kill_all.assert_called_once()
@@ -422,7 +284,7 @@ def test_claude_child_env_targets_current_proxy_config() -> None:
env = build_claude_proxy_env(
proxy_root_url="http://127.0.0.1:9090",
- auth_token=" proxy-token ",
+ auth_token="proxy-token",
base_env={
"PATH": "keep",
"ANTHROPIC_API_URL": "https://api.anthropic.com/v1",
@@ -454,22 +316,6 @@ def test_claude_child_env_targets_current_proxy_config() -> None:
assert "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC" not in env
-def test_claude_child_env_uses_sentinel_for_blank_configured_auth_token() -> None:
- from free_claude_code.cli.claude_env import build_claude_proxy_env
-
- env = build_claude_proxy_env(
- proxy_root_url="http://127.0.0.1:8082",
- auth_token="",
- base_env={
- "ANTHROPIC_AUTH_TOKEN": "inherited-token",
- "ANTHROPIC_API_KEY": "official-key",
- },
- )
-
- assert env["ANTHROPIC_AUTH_TOKEN"] == "fcc-no-auth"
- assert "ANTHROPIC_API_KEY" not in env
-
-
def test_launch_claude_passes_args_and_child_env(
monkeypatch: pytest.MonkeyPatch,
) -> None:
@@ -626,21 +472,12 @@ def test_launch_codex_passes_responses_config_and_child_env(
unregister_pid.assert_called_once_with(12345)
- ("configured_token", "expected_token"),
- [
- (" proxy-token ", "proxy-token"),
- ("", "fcc-no-auth"),
- ],
-)
def test_codex_proxy_auth_command_prints_only_current_token(
- configured_token: str,
- expected_token: str,
capsys: pytest.CaptureFixture[str],
) -> None:
from free_claude_code.cli.launchers import codex
- settings = _launcher_settings(token=configured_token)
+ settings = _launcher_settings(token=" proxy-token ")
with (
patch.object(codex, "get_settings", return_value=settings) as get_settings,
patch.object(codex, "preflight_proxy") as preflight_proxy,
@@ -650,7 +487,7 @@ def test_codex_proxy_auth_command_prints_only_current_token(
):
codex.launch(["--print-proxy-auth-token"])
- assert capsys.readouterr() == (f"{expected_token}\n", "")
+ assert capsys.readouterr() == ("proxy-token\n", "")
get_settings.assert_called_once_with()
preflight_proxy.assert_not_called()
resolve_client_binary.assert_not_called()
@@ -714,7 +551,7 @@ def test_pi_launcher_builds_scoped_session_command_and_proxy_env(
extension = tmp_path / "pi_extension.ts"
env = build_pi_launcher_env(
proxy_root_url="http://127.0.0.1:9191/",
- auth_token=" proxy-token ",
+ auth_token="proxy-token",
base_env={
"PATH": "keep",
"ANTHROPIC_API_KEY": "native-pi-credential",
@@ -746,18 +583,6 @@ def test_pi_launcher_builds_scoped_session_command_and_proxy_env(
}
-def test_pi_launcher_uses_no_auth_sentinel_for_blank_token() -> None:
- from free_claude_code.cli.launchers.pi import build_pi_launcher_env
-
- env = build_pi_launcher_env(
- proxy_root_url="http://127.0.0.1:8082",
- auth_token="",
- base_env={},
- )
-
- assert env["FCC_PI_API_KEY"] == "fcc-no-auth"
-
-
def test_launch_pi_registers_bundled_extension_for_sessions(
monkeypatch: pytest.MonkeyPatch,
tmp_path: Path,
diff --git a/tests/cli/test_managed_claude.py b/tests/cli/test_managed_claude.py
index 8555e358..e5d48c84 100644
--- a/tests/cli/test_managed_claude.py
+++ b/tests/cli/test_managed_claude.py
@@ -127,14 +127,14 @@ def test_managed_claude_uses_native_plan_storage() -> None:
assert "--settings" not in invocation.argv
-def test_managed_claude_env_uses_sentinel_when_proxy_auth_blank() -> None:
+def test_managed_claude_env_forwards_retained_proxy_auth_token() -> None:
env = build_managed_claude_env(
proxy_root_url="http://localhost:8082",
- auth_token="",
+ auth_token="freecc",
base_env={"ANTHROPIC_AUTH_TOKEN": "stale"},
)
- assert env["ANTHROPIC_AUTH_TOKEN"] == "fcc-no-auth"
+ assert env["ANTHROPIC_AUTH_TOKEN"] == "freecc"
def test_managed_claude_env_adds_noninteractive_process_policy() -> None:
diff --git a/tests/cli/test_managed_session_shutdown.py b/tests/cli/test_managed_session_shutdown.py
index 465f4f7d..c02313da 100644
--- a/tests/cli/test_managed_session_shutdown.py
+++ b/tests/cli/test_managed_session_shutdown.py
@@ -11,6 +11,15 @@ def _manager() -> ManagedClaudeSessionManager:
return ManagedClaudeSessionManager(
workspace_path="/tmp",
proxy_root_url="http://127.0.0.1:8082",
+ auth_token="freecc",
+ )
+
+
+def _session() -> ManagedClaudeSession:
+ return ManagedClaudeSession(
+ "/tmp",
+ "http://127.0.0.1:8082",
+ auth_token="freecc",
)
@@ -33,7 +42,7 @@ def _completed_process(pid: int) -> MagicMock:
@pytest.mark.asyncio
async def test_stop_is_idempotent_without_a_live_process() -> None:
- session = ManagedClaudeSession("/tmp", "http://127.0.0.1:8082")
+ session = _session()
assert await session.stop() is True
@@ -58,7 +67,7 @@ async def test_stop_is_idempotent_without_a_live_process() -> None:
@pytest.mark.asyncio
async def test_stopped_session_reference_cannot_launch_a_new_process() -> None:
- session = ManagedClaudeSession("/tmp", "http://127.0.0.1:8082")
+ session = _session()
assert await session.stop() is True
@@ -80,7 +89,7 @@ async def test_stopped_session_reference_cannot_launch_a_new_process() -> None:
@pytest.mark.asyncio
async def test_launch_publication_wins_before_concurrent_stop() -> None:
- session = ManagedClaudeSession("/tmp", "http://127.0.0.1:8082")
+ session = _session()
launch_entered = asyncio.Event()
release_launch = asyncio.Event()
release_stream = asyncio.Event()
@@ -137,7 +146,7 @@ async def test_launch_publication_wins_before_concurrent_stop() -> None:
@pytest.mark.asyncio
async def test_concurrent_stop_wins_before_launch_publication() -> None:
- session = ManagedClaudeSession("/tmp", "http://127.0.0.1:8082")
+ session = _session()
stop_entered = asyncio.Event()
release_stop = asyncio.Event()
process = MagicMock()
@@ -179,7 +188,7 @@ async def test_concurrent_stop_wins_before_launch_publication() -> None:
@pytest.mark.asyncio
async def test_normal_sequential_starts_remain_allowed_before_stop() -> None:
- session = ManagedClaudeSession("/tmp", "http://127.0.0.1:8082")
+ session = _session()
processes = [_completed_process(104), _completed_process(105)]
with (
@@ -207,7 +216,7 @@ async def _collect_session_events(
@pytest.mark.asyncio
async def test_failed_stop_keeps_pid_registered_until_retry_confirms_exit() -> None:
- session = ManagedClaudeSession("/tmp", "http://127.0.0.1:8082")
+ session = _session()
process = MagicMock()
process.pid = 202
process.returncode = None
@@ -228,7 +237,7 @@ async def test_failed_stop_keeps_pid_registered_until_retry_confirms_exit() -> N
@pytest.mark.asyncio
async def test_cancelled_stop_keeps_pid_registered_and_can_be_retried() -> None:
- session = ManagedClaudeSession("/tmp", "http://127.0.0.1:8082")
+ session = _session()
process = MagicMock()
process.pid = 303
process.returncode = None
@@ -261,7 +270,7 @@ async def test_cancelled_stop_keeps_pid_registered_and_can_be_retried() -> None:
@pytest.mark.asyncio
async def test_task_failure_keeps_unconfirmed_process_pid_registered() -> None:
- session = ManagedClaudeSession("/tmp", "http://127.0.0.1:8082")
+ session = _session()
process = MagicMock()
process.pid = 404
process.returncode = None
@@ -286,7 +295,7 @@ async def test_task_failure_keeps_unconfirmed_process_pid_registered() -> None:
@pytest.mark.asyncio
async def test_completed_task_wait_unregisters_confirmed_process_pid() -> None:
- session = ManagedClaudeSession("/tmp", "http://127.0.0.1:8082")
+ session = _session()
process = MagicMock()
process.pid = 405
process.returncode = None
diff --git a/tests/config/test_config.py b/tests/config/test_config.py
index 98292092..2deec91f 100644
--- a/tests/config/test_config.py
+++ b/tests/config/test_config.py
@@ -1,17 +1,20 @@
-"""Tests for config/settings.py and config/nim.py"""
+"""Contracts for pure Settings and canonical source composition."""
-from typing import Any, cast
+from enum import Enum
import pytest
from pydantic import ValidationError
+from free_claude_code.application.routing import ModelRouter
from free_claude_code.config.constants import (
ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
HTTP_CONNECT_TIMEOUT_DEFAULT,
)
-from free_claude_code.config.env_files import (
- ANTHROPIC_AUTH_TOKEN_ENV,
- process_env_key_is_effective,
+from free_claude_code.config.loader import (
+ ConfigSource,
+ clear_settings_cache,
+ compose_settings_snapshot,
+ get_settings,
)
from free_claude_code.config.model_refs import (
configured_chat_model_refs,
@@ -19,1162 +22,239 @@ from free_claude_code.config.model_refs import (
parse_provider_type,
)
from free_claude_code.config.nim import NimSettings
-from free_claude_code.config.paths import messaging_state_dir_path
+from free_claude_code.config.paths import messaging_state_dir_path, server_log_path
from free_claude_code.config.reasoning import ReasoningPreference
-
-
-class TestSettings:
- """Test Settings configuration."""
-
- def test_settings_loads(self):
- """Ensure Settings can be instantiated."""
- from free_claude_code.config.settings import Settings
-
- settings = Settings()
- assert settings is not None
-
- def test_default_values(self, monkeypatch):
- """Test default values are set and have correct types."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.delenv("CLAUDE_WORKSPACE", raising=False)
- monkeypatch.delenv("MODEL", raising=False)
- monkeypatch.delenv("VERTEX_LOCATION", raising=False)
- monkeypatch.delenv("HTTP_READ_TIMEOUT", raising=False)
- monkeypatch.delenv("HTTP_CONNECT_TIMEOUT", raising=False)
- monkeypatch.setitem(Settings.model_config, "env_file", ())
- settings = Settings()
- assert settings.model == "nvidia_nim/nvidia/nemotron-3-super-120b-a12b"
- assert isinstance(settings.provider_rate_limit, int)
- assert isinstance(settings.provider_rate_window, int)
- assert isinstance(settings.nim.temperature, float)
- assert isinstance(settings.fast_prefix_detection, bool)
- assert settings.reasoning_policy is ReasoningPreference.CLIENT
- assert settings.http_read_timeout == 120.0
- assert settings.http_connect_timeout == HTTP_CONNECT_TIMEOUT_DEFAULT
- assert settings.enable_web_server_tools is False
- assert settings.log_raw_api_payloads is False
- assert settings.log_raw_sse_events is False
- assert settings.debug_platform_edits is False
- assert settings.debug_subagent_stack is False
- assert settings.log_level == "INFO"
- assert settings.open_admin_browser is True
- assert settings.vertex_location == "global"
-
- def test_open_admin_browser_loads_from_environment(self, monkeypatch):
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("FCC_OPEN_BROWSER", "false")
- monkeypatch.setitem(Settings.model_config, "env_file", ())
-
- assert Settings().open_admin_browser is False
-
- def test_default_claude_workspace_uses_fcc_home(self, monkeypatch, tmp_path):
- """Unset CLAUDE_WORKSPACE stores agent data under the fixed path helper."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("HOME", str(tmp_path))
- monkeypatch.setenv("USERPROFILE", str(tmp_path))
- monkeypatch.delenv("CLAUDE_WORKSPACE", raising=False)
- monkeypatch.setitem(Settings.model_config, "env_file", ())
-
- settings = Settings()
-
- assert messaging_state_dir_path() == tmp_path / ".fcc" / "agent_workspace"
- assert not hasattr(settings, "claude_workspace")
-
- def test_server_log_path_uses_fcc_home(self, monkeypatch, tmp_path):
- """The server log location is fixed under ~/.fcc."""
- from free_claude_code.config.paths import server_log_path
-
- monkeypatch.setenv("HOME", str(tmp_path))
- monkeypatch.setenv("USERPROFILE", str(tmp_path))
-
- assert server_log_path() == tmp_path / ".fcc" / "logs" / "server.log"
-
- def test_removed_log_file_env_is_ignored(self, monkeypatch):
- """Legacy LOG_FILE values do not affect Settings or block startup."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("LOG_FILE", "custom/server.log")
- monkeypatch.setitem(Settings.model_config, "env_file", ())
-
- settings = Settings()
-
- assert not hasattr(settings, "log_file")
-
- def test_stale_zai_base_url_env_is_ignored(self, monkeypatch):
- """Cloud Z.ai endpoint is fixed in provider metadata, not settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("ZAI_BASE_URL", "https://custom.zai.invalid/v1")
- monkeypatch.setitem(Settings.model_config, "env_file", ())
-
- settings = Settings()
-
- assert not hasattr(settings, "zai_base_url")
-
- def test_blank_claude_workspace_uses_fcc_home(self, monkeypatch, tmp_path):
- """An explicit blank env value does not affect the fixed workspace helper."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("HOME", str(tmp_path))
- monkeypatch.setenv("USERPROFILE", str(tmp_path))
- monkeypatch.setenv("CLAUDE_WORKSPACE", "")
- monkeypatch.setitem(Settings.model_config, "env_file", ())
-
- settings = Settings()
-
- assert messaging_state_dir_path() == tmp_path / ".fcc" / "agent_workspace"
- assert not hasattr(settings, "claude_workspace")
-
- def test_explicit_claude_workspace_is_ignored(self, monkeypatch, tmp_path):
- """Custom CLAUDE_WORKSPACE values do not override the fixed workspace helper."""
- from free_claude_code.config.settings import Settings
-
- workspace = tmp_path / "custom-workspace"
- monkeypatch.setenv("HOME", str(tmp_path))
- monkeypatch.setenv("USERPROFILE", str(tmp_path))
- monkeypatch.setenv("CLAUDE_WORKSPACE", str(workspace))
- monkeypatch.setitem(Settings.model_config, "env_file", ())
-
- settings = Settings()
-
- assert messaging_state_dir_path() == tmp_path / ".fcc" / "agent_workspace"
- assert not hasattr(settings, "claude_workspace")
-
- def test_explicit_claude_cli_bin_is_ignored(self, monkeypatch):
- """Custom CLAUDE_CLI_BIN values do not become Settings fields."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("CLAUDE_CLI_BIN", "claude-custom")
- monkeypatch.setitem(Settings.model_config, "env_file", ())
-
- settings = Settings()
-
- assert not hasattr(settings, "claude_cli_bin")
- assert not hasattr(settings, "codex_cli_bin")
-
- def test_direct_claude_runtime_overrides_are_ignored(self, monkeypatch, tmp_path):
- """Constructor extras cannot add fixed Claude runtime settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("HOME", str(tmp_path))
- monkeypatch.setenv("USERPROFILE", str(tmp_path))
- monkeypatch.setitem(Settings.model_config, "env_file", ())
-
- settings = Settings(
- **cast(
- Any,
- {
- "claude_workspace": str(tmp_path / "custom-workspace"),
- "claude_cli_bin": "claude-custom",
- },
- )
- )
-
- assert messaging_state_dir_path() == tmp_path / ".fcc" / "agent_workspace"
- assert not hasattr(settings, "claude_workspace")
- assert not hasattr(settings, "claude_cli_bin")
-
- def test_get_settings_cached(self):
- """Test get_settings returns cached instance."""
- from free_claude_code.config.settings import get_settings
-
- s1 = get_settings()
- s2 = get_settings()
- assert s1 is s2 # Same object (cached)
-
- def test_empty_string_to_none_for_optional_int(self):
- """Test that empty string converts to None for optional int fields."""
- from free_claude_code.config.settings import Settings
-
- # Settings should handle NVIDIA_NIM_SEED="" gracefully
- settings = Settings()
- assert settings.nim.seed is None or isinstance(settings.nim.seed, int)
-
- def test_model_setting(self):
- """Test model setting exists and is a string."""
- from free_claude_code.config.settings import Settings
-
- settings = Settings()
- assert isinstance(settings.model, str)
- assert len(settings.model) > 0
-
- def test_base_url_constant(self):
- """Test NVIDIA_NIM_DEFAULT_BASE is a constant."""
- from free_claude_code.config.provider_catalog import NVIDIA_NIM_DEFAULT_BASE
-
- assert NVIDIA_NIM_DEFAULT_BASE == "https://integrate.api.nvidia.com/v1"
-
- def test_lm_studio_base_url_from_env(self, monkeypatch):
- """LM_STUDIO_BASE_URL env var is loaded into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("LM_STUDIO_BASE_URL", "http://custom:5678/v1")
- settings = Settings()
- assert settings.lm_studio_base_url == "http://custom:5678/v1"
-
- def test_ollama_base_url_defaults_to_root(self, monkeypatch):
- """OLLAMA_BASE_URL keeps the customer-facing Ollama root default."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.delenv("OLLAMA_BASE_URL", raising=False)
- monkeypatch.setitem(Settings.model_config, "env_file", ())
- settings = Settings()
- assert settings.ollama_base_url == "http://localhost:11434"
-
- def test_ollama_base_url_accepts_v1_suffix(self, monkeypatch):
- """The adapter accepts either the root URL or the explicit OpenAI path."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("OLLAMA_BASE_URL", "http://localhost:11434/v1")
- assert Settings().ollama_base_url == "http://localhost:11434/v1"
-
- def test_ollama_cloud_api_key_from_env(self, monkeypatch):
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("OLLAMA_API_KEY", "ollama-cloud-key")
-
- assert Settings().ollama_api_key == "ollama-cloud-key"
-
- def test_provider_rate_limit_from_env(self, monkeypatch):
- """PROVIDER_RATE_LIMIT env var is loaded into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("PROVIDER_RATE_LIMIT", "20")
- settings = Settings()
- assert settings.provider_rate_limit == 20
-
- def test_provider_rate_window_from_env(self, monkeypatch):
- """PROVIDER_RATE_WINDOW env var is loaded into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("PROVIDER_RATE_WINDOW", "30")
- settings = Settings()
- assert settings.provider_rate_window == 30
-
- def test_http_read_timeout_from_env(self, monkeypatch):
- """HTTP_READ_TIMEOUT env var is loaded into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("HTTP_READ_TIMEOUT", "600")
- settings = Settings()
- assert settings.http_read_timeout == 600.0
-
- def test_http_write_timeout_from_env(self, monkeypatch):
- """HTTP_WRITE_TIMEOUT env var is loaded into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("HTTP_WRITE_TIMEOUT", "20")
- settings = Settings()
- assert settings.http_write_timeout == 20.0
-
- def test_http_connect_timeout_from_env(self, monkeypatch):
- """HTTP_CONNECT_TIMEOUT env var is loaded into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("HTTP_CONNECT_TIMEOUT", "5")
- settings = Settings()
- assert settings.http_connect_timeout == 5.0
-
- def test_http_connect_timeout_default_matches_shared_constant(
- self, monkeypatch
- ) -> None:
- """Default must match config.constants (and README / .env.example)."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.delenv("HTTP_CONNECT_TIMEOUT", raising=False)
- monkeypatch.setitem(Settings.model_config, "env_file", ())
- settings = Settings()
- assert settings.http_connect_timeout == HTTP_CONNECT_TIMEOUT_DEFAULT
- assert HTTP_CONNECT_TIMEOUT_DEFAULT == 10.0
-
- def test_reasoning_policy_from_env(self, monkeypatch):
- """REASONING_POLICY is loaded as a typed preference."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("REASONING_POLICY", "off")
- settings = Settings()
- assert settings.reasoning_policy is ReasoningPreference.OFF
-
- def test_root_reasoning_policy_cannot_inherit(self, monkeypatch):
- """Only route overrides may inherit."""
- from pydantic import ValidationError
-
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("REASONING_POLICY", "inherit")
-
- with pytest.raises(ValidationError, match="cannot inherit"):
- Settings()
-
- def test_wafer_api_key_from_env(self, monkeypatch):
- """WAFER_API_KEY env var is loaded into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("WAFER_API_KEY", "wafer-key")
- settings = Settings()
- assert settings.wafer_api_key == "wafer-key"
-
- def test_minimax_settings_from_env(self, monkeypatch):
- """MiniMax key and proxy env vars load into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("MINIMAX_API_KEY", "minimax-key")
- monkeypatch.setenv("MINIMAX_PROXY", "http://proxy.test:8080")
- settings = Settings()
- assert settings.minimax_api_key == "minimax-key"
- assert settings.minimax_proxy == "http://proxy.test:8080"
-
- def test_cloudflare_settings_from_env(self, monkeypatch):
- """Cloudflare token, account, and proxy env vars load into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("CLOUDFLARE_API_TOKEN", "cf-token")
- monkeypatch.setenv("CLOUDFLARE_ACCOUNT_ID", "cf-account")
- monkeypatch.setenv("CLOUDFLARE_PROXY", "http://proxy.test:8080")
- settings = Settings()
- assert settings.cloudflare_api_token == "cf-token"
- assert settings.cloudflare_account_id == "cf-account"
- assert settings.cloudflare_proxy == "http://proxy.test:8080"
-
- def test_azure_openai_settings_from_env(self, monkeypatch):
- """Azure OpenAI key, resource URL, and proxy load into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("AZURE_OPENAI_API_KEY", "azure-key")
- monkeypatch.setenv(
- "AZURE_OPENAI_BASE_URL",
- "https://resource.openai.azure.com/openai/v1/",
- )
- monkeypatch.setenv("AZURE_OPENAI_PROXY", "http://proxy.test:8080")
- settings = Settings()
-
- assert settings.azure_openai_api_key == "azure-key"
- assert settings.azure_openai_base_url == (
- "https://resource.openai.azure.com/openai/v1/"
- )
- assert settings.azure_openai_proxy == "http://proxy.test:8080"
-
- def test_vertex_settings_from_env(self, monkeypatch):
- """Vertex project, location, and proxy env vars load into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("VERTEX_PROJECT_ID", "vertex-project")
- monkeypatch.setenv("VERTEX_LOCATION", "us-central1")
- monkeypatch.setenv("VERTEX_PROXY", "http://proxy.test:8080")
- settings = Settings()
- assert settings.vertex_project_id == "vertex-project"
- assert settings.vertex_location == "us-central1"
- assert settings.vertex_proxy == "http://proxy.test:8080"
-
- def test_vercel_settings_from_env(self, monkeypatch):
- """Vercel AI Gateway key and proxy env vars load into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("AI_GATEWAY_API_KEY", "vercel-key")
- monkeypatch.setenv("VERCEL_AI_GATEWAY_PROXY", "http://proxy.test:8080")
- settings = Settings()
- assert settings.vercel_ai_gateway_api_key == "vercel-key"
- assert settings.vercel_ai_gateway_proxy == "http://proxy.test:8080"
-
- def test_bedrock_settings_from_official_environment(self, monkeypatch):
- """Bedrock key, regional base URL, and proxy load into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("AWS_BEARER_TOKEN_BEDROCK", "bedrock-key")
- monkeypatch.setenv(
- "BEDROCK_BASE_URL", "https://bedrock-mantle.us-west-2.api.aws/v1"
- )
- monkeypatch.setenv("BEDROCK_PROXY", "http://proxy.test:8080")
- settings = Settings()
-
- assert settings.bedrock_api_key == "bedrock-key"
- assert settings.bedrock_base_url == (
- "https://bedrock-mantle.us-west-2.api.aws/v1"
- )
- assert settings.bedrock_proxy == "http://proxy.test:8080"
-
- def test_huggingface_settings_from_env(self, monkeypatch):
- """Hugging Face key and proxy env vars load into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("HUGGINGFACE_API_KEY", "hf-key")
- monkeypatch.setenv("HUGGINGFACE_PROXY", "http://proxy.test:8080")
- settings = Settings()
- assert settings.huggingface_api_key == "hf-key"
- assert settings.huggingface_proxy == "http://proxy.test:8080"
- assert not hasattr(settings, "hf_token")
-
- def test_cohere_settings_from_env(self, monkeypatch):
- """Cohere key and proxy env vars load into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("COHERE_API_KEY", "cohere-key")
- monkeypatch.setenv("COHERE_PROXY", "http://proxy.test:8080")
- settings = Settings()
- assert settings.cohere_api_key == "cohere-key"
- assert settings.cohere_proxy == "http://proxy.test:8080"
-
- def test_github_models_settings_from_env(self, monkeypatch):
- """GitHub Models token and proxy env vars load into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("GITHUB_MODELS_TOKEN", "github-token")
- monkeypatch.setenv("GITHUB_MODELS_PROXY", "http://proxy.test:8080")
- settings = Settings()
- assert settings.github_models_token == "github-token"
- assert settings.github_models_proxy == "http://proxy.test:8080"
-
- def test_sambanova_settings_from_env(self, monkeypatch):
- """SambaNova key and proxy env vars load into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("SAMBANOVA_API_KEY", "sambanova-key")
- monkeypatch.setenv("SAMBANOVA_PROXY", "http://proxy.test:8080")
- settings = Settings()
- assert settings.sambanova_api_key == "sambanova-key"
- assert settings.sambanova_proxy == "http://proxy.test:8080"
-
- def test_legacy_hf_token_env_is_ignored(self, monkeypatch):
- """HF_TOKEN is migrated by startup config migration, not read by Settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("HF_TOKEN", "legacy-token")
- monkeypatch.delenv("HUGGINGFACE_API_KEY", raising=False)
- settings = Settings()
- assert settings.huggingface_api_key == ""
- assert not hasattr(settings, "hf_token")
-
- def test_route_reasoning_from_env(self, monkeypatch):
- """Route reasoning preferences are loaded into settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("REASONING_FABLE", "high")
- monkeypatch.setenv("REASONING_OPUS", "max")
- monkeypatch.setenv("REASONING_SONNET", "client")
- monkeypatch.setenv("REASONING_HAIKU", "off")
- settings = Settings()
- assert settings.reasoning_fable is ReasoningPreference.HIGH
- assert settings.reasoning_opus is ReasoningPreference.MAX
- assert settings.reasoning_sonnet is ReasoningPreference.CLIENT
- assert settings.reasoning_haiku is ReasoningPreference.OFF
-
- def test_route_reasoning_inherits_root_policy(self, monkeypatch):
- """Inherit defers route reasoning to the root preference."""
- from free_claude_code.application.routing import ModelRouter
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("REASONING_POLICY", "off")
- monkeypatch.setenv("REASONING_OPUS", "inherit")
- settings = Settings()
- assert settings.reasoning_opus is ReasoningPreference.INHERIT
- assert (
- ModelRouter(settings).resolve("claude-opus-4-20250514").reasoning_preference
- is ReasoningPreference.OFF
- )
-
- def test_resolve_reasoning_uses_routes(self, monkeypatch):
- """ModelRouter applies route preference then root fallback."""
- from free_claude_code.application.routing import ModelRouter
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("REASONING_POLICY", "off")
- monkeypatch.setenv("REASONING_FABLE", "high")
- monkeypatch.setenv("REASONING_OPUS", "max")
- monkeypatch.setenv("REASONING_HAIKU", "off")
- settings = Settings()
- router = ModelRouter(settings)
- assert (
- router.resolve("claude-fable-5").reasoning_preference
- is ReasoningPreference.HIGH
- )
- assert (
- router.resolve("claude-opus-4-20250514").reasoning_preference
- is ReasoningPreference.MAX
- )
- assert (
- router.resolve("claude-sonnet-4-20250514").reasoning_preference
- is ReasoningPreference.OFF
- )
- assert (
- router.resolve("claude-haiku-4-20250514").reasoning_preference
- is ReasoningPreference.OFF
- )
- assert (
- router.resolve("unknown-model").reasoning_preference
- is ReasoningPreference.OFF
- )
-
- def test_anthropic_auth_token_from_env_without_dotenv_key(self, monkeypatch):
- """ANTHROPIC_AUTH_TOKEN env var is loaded when dotenv does not define it."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("ANTHROPIC_AUTH_TOKEN", "process-token")
- monkeypatch.setitem(Settings.model_config, "env_file", ())
- settings = Settings()
- assert settings.anthropic_auth_token == "process-token"
- assert (
- process_env_key_is_effective(
- Settings.model_config, ANTHROPIC_AUTH_TOKEN_ENV
- )
- is True
- )
-
- def test_empty_dotenv_anthropic_auth_token_overrides_process_env(
- self, monkeypatch, tmp_path
- ):
- """An explicit empty .env token disables auth despite stale shell tokens."""
- from free_claude_code.config.settings import Settings
-
- env_file = tmp_path / ".env"
- env_file.write_text("ANTHROPIC_AUTH_TOKEN=\n", encoding="utf-8")
- monkeypatch.setenv("ANTHROPIC_AUTH_TOKEN", "stale-client-token")
- monkeypatch.setitem(Settings.model_config, "env_file", (env_file,))
-
- settings = Settings()
- assert settings.anthropic_auth_token == ""
- assert (
- process_env_key_is_effective(
- Settings.model_config, ANTHROPIC_AUTH_TOKEN_ENV
- )
- is False
- )
-
- def test_dotenv_anthropic_auth_token_overrides_process_env(
- self, monkeypatch, tmp_path
- ):
- """A configured .env token is the server token even with a stale shell token."""
- from free_claude_code.config.settings import Settings
-
- env_file = tmp_path / ".env"
- env_file.write_text(
- 'ANTHROPIC_AUTH_TOKEN="server-token"\n',
- encoding="utf-8",
- )
- monkeypatch.setenv("ANTHROPIC_AUTH_TOKEN", "stale-client-token")
- monkeypatch.setitem(Settings.model_config, "env_file", (env_file,))
-
- settings = Settings()
- assert settings.anthropic_auth_token == "server-token"
- assert (
- process_env_key_is_effective(
- Settings.model_config, ANTHROPIC_AUTH_TOKEN_ENV
- )
- is False
- )
-
- @pytest.mark.parametrize("removed_key", ["NIM_ENABLE_THINKING", "ENABLE_THINKING"])
- def test_removed_thinking_env_keys_are_ignored(self, monkeypatch, removed_key):
- """Stale thinking env keys do not block startup or affect settings."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv(removed_key, "false")
- monkeypatch.setitem(Settings.model_config, "env_file", ())
-
- settings = Settings()
-
- assert settings.reasoning_policy is ReasoningPreference.CLIENT
-
- @pytest.mark.parametrize("removed_key", ["NIM_ENABLE_THINKING", "ENABLE_THINKING"])
- @pytest.mark.parametrize("value", ["false", ""])
- def test_removed_thinking_dotenv_keys_are_ignored(
- self, monkeypatch, tmp_path, removed_key, value
- ):
- """Stale thinking dotenv keys do not block startup or affect settings."""
- from free_claude_code.config.settings import Settings
-
- env_file = tmp_path / ".env"
- env_file.write_text(f"{removed_key}={value}\n", encoding="utf-8")
- monkeypatch.delenv(removed_key, raising=False)
- monkeypatch.setitem(Settings.model_config, "env_file", (env_file,))
-
- settings = Settings()
-
- assert settings.reasoning_policy is ReasoningPreference.CLIENT
-
-
-# --- NimSettings Validation Tests ---
-class TestNimSettingsValidBounds:
- """Test that valid values within bounds are accepted."""
-
- @pytest.mark.parametrize("top_k", [-1, 0, 1, 100])
- def test_top_k_valid(self, top_k):
- """top_k >= -1 should be accepted."""
- s = NimSettings(top_k=top_k)
- assert s.top_k == top_k
-
- @pytest.mark.parametrize("temp", [0.0, 0.5, 1.0, 2.0])
- def test_temperature_valid(self, temp):
- s = NimSettings(temperature=temp)
- assert s.temperature == temp
-
- @pytest.mark.parametrize("top_p", [0.0, 0.5, 1.0])
- def test_top_p_valid(self, top_p):
- s = NimSettings(top_p=top_p)
- assert s.top_p == top_p
-
- def test_max_tokens_valid(self):
- s = NimSettings(max_tokens=1)
- assert s.max_tokens == 1
-
- def test_min_tokens_valid(self):
- s = NimSettings(min_tokens=0)
- assert s.min_tokens == 0
-
- @pytest.mark.parametrize("penalty", [-2.0, 0.0, 2.0])
- def test_presence_penalty_valid(self, penalty):
- s = NimSettings(presence_penalty=penalty)
- assert s.presence_penalty == penalty
-
- @pytest.mark.parametrize("penalty", [-2.0, 0.0, 2.0])
- def test_frequency_penalty_valid(self, penalty):
- s = NimSettings(frequency_penalty=penalty)
- assert s.frequency_penalty == penalty
-
- @pytest.mark.parametrize("min_p", [0.0, 0.5, 1.0])
- def test_min_p_valid(self, min_p):
- s = NimSettings(min_p=min_p)
- assert s.min_p == min_p
-
-
-class TestNimSettingsInvalidBounds:
- """Test that out-of-range values raise ValidationError."""
-
- @pytest.mark.parametrize("top_k", [-2, -100])
- def test_top_k_below_lower_bound(self, top_k):
- with pytest.raises((ValidationError, ValueError)):
- NimSettings(top_k=top_k)
-
- def test_temperature_negative(self):
- with pytest.raises(ValidationError):
- NimSettings(temperature=-0.1)
-
- @pytest.mark.parametrize("top_p", [-0.1, 1.1])
- def test_top_p_out_of_range(self, top_p):
- with pytest.raises(ValidationError):
- NimSettings(top_p=top_p)
-
- @pytest.mark.parametrize("penalty", [-2.1, 2.1])
- def test_presence_penalty_out_of_range(self, penalty):
- with pytest.raises(ValidationError):
- NimSettings(presence_penalty=penalty)
-
- @pytest.mark.parametrize("penalty", [-2.1, 2.1])
- def test_frequency_penalty_out_of_range(self, penalty):
- with pytest.raises(ValidationError):
- NimSettings(frequency_penalty=penalty)
-
- @pytest.mark.parametrize("min_p", [-0.1, 1.1])
- def test_min_p_out_of_range(self, min_p):
- with pytest.raises(ValidationError):
- NimSettings(min_p=min_p)
-
- @pytest.mark.parametrize("max_tokens", [0, -1])
- def test_max_tokens_too_low(self, max_tokens):
- with pytest.raises(ValidationError):
- NimSettings(max_tokens=max_tokens)
-
- def test_min_tokens_negative(self):
- with pytest.raises(ValidationError):
- NimSettings(min_tokens=-1)
-
-
-class TestNimSettingsValidators:
- """Test custom field validators in NimSettings."""
-
- def test_default_max_tokens_matches_shared_constant(self):
- assert NimSettings().max_tokens == ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
-
- @pytest.mark.parametrize(
- "seed_val,expected",
- [("", None), (None, None), ("42", 42), (42, 42)],
- ids=["empty_str", "none", "str_42", "int_42"],
- )
- def test_parse_optional_int(self, seed_val, expected):
- s = NimSettings(seed=seed_val)
- assert s.seed == expected
-
- @pytest.mark.parametrize(
- "stop_val,expected",
- [("", None), ("STOP", "STOP"), (None, None)],
- ids=["empty_str", "valid", "none"],
- )
- def test_parse_optional_str_stop(self, stop_val, expected):
- s = NimSettings(stop=stop_val)
- assert s.stop == expected
-
- @pytest.mark.parametrize(
- "chat_template_val,expected",
- [("", None), ("template", "template")],
- ids=["empty_str", "valid"],
+from free_claude_code.config.settings import Settings
+
+
+def test_settings_defaults_are_valid_and_nonempty() -> None:
+ settings = Settings()
+
+ assert settings.provider_rate_limit == 1
+ assert settings.provider_rate_window == 2
+ assert settings.provider_max_concurrency == 2
+ assert settings.http_read_timeout == 120.0
+ assert settings.http_write_timeout == 10.0
+ assert settings.http_connect_timeout == HTTP_CONNECT_TIMEOUT_DEFAULT
+ assert settings.voice_note_enabled is True
+ assert settings.whisper_device == "cpu"
+ assert settings.whisper_model == "base"
+ assert settings.enable_web_server_tools is False
+ assert settings.proxy_auth_enabled is False
+ assert settings.proxy_auth_token == "freecc"
+ assert [
+ name for name, value in settings if isinstance(value, str) and not value
+ ] == []
+ assert [
+ name
+ for name, field in Settings.model_fields.items()
+ if field.get_default(call_default_factory=True) == ""
+ ] == []
+
+
+def test_every_external_setting_has_one_explicit_alias() -> None:
+ aliases = [
+ field.validation_alias
+ for name, field in Settings.model_fields.items()
+ if name != "nim"
+ ]
+ assert all(isinstance(alias, str) for alias in aliases)
+ assert len(aliases) == len(set(aliases))
+ assert Settings.model_fields["nim"].validation_alias is None
+
+
+def test_direct_settings_construction_performs_no_environment_io(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setenv("MODEL", "deepseek/process-model")
+ monkeypatch.setenv("PROVIDER_RATE_LIMIT", "99")
+
+ settings = Settings()
+
+ assert settings.model.startswith("nvidia_nim/")
+ assert settings.provider_rate_limit == 1
+
+
+ ("key", "attribute", "value", "expected"),
+ [
+ ("MODEL", "model", "deepseek/deepseek-chat", "deepseek/deepseek-chat"),
+ ("PROVIDER_RATE_LIMIT", "provider_rate_limit", "20", 20),
+ ("HTTP_READ_TIMEOUT", "http_read_timeout", "600", 600.0),
+ ("FCC_OPEN_BROWSER", "open_admin_browser", "false", False),
+ ("REASONING_POLICY", "reasoning_policy", "off", ReasoningPreference.OFF),
+ ("GROQ_API_KEY", "groq_api_key", " secret ", "secret"),
+ ("OPENROUTER_PROXY", "open_router_proxy", " http://proxy ", "http://proxy"),
+ ],
+)
+def test_process_values_are_parsed_at_the_loader_boundary(
+ key: str,
+ attribute: str,
+ value: str,
+ expected: object,
+) -> None:
+ snapshot = compose_settings_snapshot({}, {key: value})
+
+ assert getattr(snapshot.settings, attribute) == expected
+ assert snapshot.sources[attribute] is ConfigSource.PROCESS
+
+
+ "key",
+ [
+ "GROQ_API_KEY",
+ "OPENROUTER_PROXY",
+ "MODEL_OPUS",
+ "TELEGRAM_BOT_TOKEN",
+ "ALLOWED_DIR",
+ ],
+)
+def test_optional_blank_process_values_normalize_to_none(key: str) -> None:
+ snapshot = compose_settings_snapshot({}, {key: " "})
+ attribute = next(
+ name
+ for name, field in Settings.model_fields.items()
+ if field.validation_alias == key
)
- def test_parse_optional_str_chat_template(self, chat_template_val, expected):
- s = NimSettings(chat_template=chat_template_val)
- assert s.chat_template == expected
-
- def test_extra_forbid_rejects_unknown_field(self):
- """NimSettings with extra='forbid' rejects unknown fields."""
- from typing import Any, cast
-
- with pytest.raises(ValidationError):
- NimSettings(**cast(Any, {"unknown_field": "value"}))
-
- def test_enable_thinking_field_removed(self):
- """NimSettings no longer accepts the removed thinking toggle."""
- from typing import Any, cast
-
- with pytest.raises(ValidationError):
- NimSettings(**cast(Any, {"enable_thinking": True}))
-
-
-class TestSettingsOptionalStr:
- """Test Settings parse_optional_str validator."""
- def test_empty_telegram_token_to_none(self, monkeypatch):
- from free_claude_code.config.settings import Settings
+ assert getattr(snapshot.settings, attribute) is None
- monkeypatch.setenv("TELEGRAM_BOT_TOKEN", "")
- s = Settings()
- assert s.telegram_bot_token is None
- def test_valid_telegram_token_preserved(self, monkeypatch):
- from free_claude_code.config.settings import Settings
+def test_blank_required_process_value_is_rejected() -> None:
+ with pytest.raises(ValidationError, match="MODEL"):
+ compose_settings_snapshot({}, {"MODEL": " "})
- monkeypatch.setenv("TELEGRAM_BOT_TOKEN", "abc123")
- s = Settings()
- assert s.telegram_bot_token == "abc123"
- def test_empty_allowed_user_id_to_none(self, monkeypatch):
- from free_claude_code.config.settings import Settings
+def test_blank_process_auth_token_uses_retained_default() -> None:
+ snapshot = compose_settings_snapshot({}, {"ANTHROPIC_AUTH_TOKEN": ""})
- monkeypatch.setenv("ALLOWED_TELEGRAM_USER_ID", "")
- s = Settings()
- assert s.allowed_telegram_user_id is None
+ assert snapshot.settings.proxy_auth_token == "freecc"
+ assert snapshot.sources["proxy_auth_token"] is ConfigSource.DEFAULT
- def test_discord_bot_token_from_env(self, monkeypatch):
- from free_claude_code.config.settings import Settings
- monkeypatch.setenv("DISCORD_BOT_TOKEN", "discord_token_123")
- s = Settings()
- assert s.discord_bot_token == "discord_token_123"
-
- def test_empty_discord_bot_token_to_none(self, monkeypatch):
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("DISCORD_BOT_TOKEN", "")
- s = Settings()
- assert s.discord_bot_token is None
-
- def test_allowed_discord_channels_from_env(self, monkeypatch):
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("ALLOWED_DISCORD_CHANNELS", "111,222,333")
- s = Settings()
- assert s.allowed_discord_channels == "111,222,333"
-
- def test_messaging_platform_from_env(self, monkeypatch):
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("MESSAGING_PLATFORM", "discord")
- s = Settings()
- assert s.messaging_platform == "discord"
-
- def test_whisper_device_auto_rejected(self, monkeypatch):
- """WHISPER_DEVICE=auto raises ValidationError (auto removed)."""
- from free_claude_code.config.settings import Settings
+def test_process_precedence_and_managed_token_exception() -> None:
+ snapshot = compose_settings_snapshot(
+ {
+ "MODEL": "deepseek/managed",
+ "ANTHROPIC_AUTH_TOKEN": "managed-token",
+ },
+ {
+ "MODEL": "groq/process",
+ "ANTHROPIC_AUTH_TOKEN": "stale-process-token",
+ },
+ )
- monkeypatch.setenv("WHISPER_DEVICE", "auto")
- with pytest.raises(ValidationError, match="whisper_device"):
- Settings()
+ assert snapshot.settings.model == "groq/process"
+ assert snapshot.sources["model"] is ConfigSource.PROCESS
+ assert snapshot.settings.proxy_auth_token == "managed-token"
+ assert snapshot.sources["proxy_auth_token"] is ConfigSource.MANAGED
- @pytest.mark.parametrize("device", ["cpu", "cuda"])
- def test_whisper_device_valid(self, monkeypatch, device):
- """Valid whisper_device values are accepted."""
- from free_claude_code.config.settings import Settings
- monkeypatch.setenv("WHISPER_DEVICE", device)
- s = Settings()
- assert s.whisper_device == device
+def test_get_settings_is_cached_and_creates_managed_schema() -> None:
+ clear_settings_cache()
+ first = get_settings()
+ second = get_settings()
-class TestPerModelMapping:
- """Test per-model settings and model-ref helpers."""
+ assert first is second
- def test_model_fields_default_none(self):
- """Per-model fields default to None."""
- from free_claude_code.config.settings import Settings
- s = Settings()
- assert s.model_fable is None
- assert s.model_opus is None
- assert s.model_sonnet is None
- assert s.model_haiku is None
+def test_optional_strings_share_one_normalization_rule() -> None:
+ settings = Settings.model_validate(
+ {
+ "GROQ_API_KEY": " key ",
+ "OPENROUTER_PROXY": " ",
+ "MODEL_OPUS": "",
+ "ALLOWED_DIR": None,
+ }
+ )
- def test_model_opus_from_env(self, monkeypatch):
- """MODEL_OPUS env var is loaded."""
- from free_claude_code.config.settings import Settings
+ assert settings.groq_api_key == "key"
+ assert settings.open_router_proxy is None
+ assert settings.model_opus is None
+ assert settings.allowed_dir is None
- monkeypatch.setenv("MODEL_OPUS", "open_router/deepseek/deepseek-r1")
- s = Settings()
- assert s.model_opus == "open_router/deepseek/deepseek-r1"
- def test_model_fable_from_env(self, monkeypatch):
- """MODEL_FABLE env var is loaded."""
- from free_claude_code.config.settings import Settings
+ "field",
+ ["MODEL", "HOST", "WHISPER_MODEL", "LOG_LEVEL", "ANTHROPIC_AUTH_TOKEN"],
+)
+def test_required_strings_reject_blank(field: str) -> None:
+ with pytest.raises(ValidationError):
+ Settings.model_validate({field: " "})
- monkeypatch.setenv("MODEL_FABLE", "open_router/anthropic/claude-fable-5")
- s = Settings()
- assert s.model_fable == "open_router/anthropic/claude-fable-5"
- @pytest.mark.parametrize(
- "env_var", ["MODEL_FABLE", "MODEL_OPUS", "MODEL_SONNET", "MODEL_HAIKU"]
+def test_model_validation_and_routing() -> None:
+ settings = Settings(
+ model="deepseek/fallback",
+ model_opus="open_router/anthropic/claude-opus",
)
- def test_empty_model_override_env_is_unset(self, monkeypatch, env_var):
- """Empty per-model override env vars are treated as unset."""
- from free_claude_code.application.routing import ModelRouter
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv(env_var, "")
- s = Settings()
- assert getattr(s, env_var.lower()) is None
- assert (
- ModelRouter(s)
- .resolve(f"claude-{env_var.removeprefix('MODEL_').lower()}-4")
- .provider_model_ref
- == s.model
- )
- @pytest.mark.parametrize(
- "env_vars,expected_model,expected_haiku",
- [
- (
- {"MODEL": "nvidia_nim/meta/llama3-70b-instruct"},
- "nvidia_nim/meta/llama3-70b-instruct",
- None,
- ),
- (
- {
- "MODEL": "open_router/anthropic/claude-3-opus",
- "MODEL_HAIKU": "open_router/anthropic/claude-3-haiku",
- },
- "open_router/anthropic/claude-3-opus",
- "open_router/anthropic/claude-3-haiku",
- ),
- ({"MODEL": "deepseek/deepseek-chat"}, "deepseek/deepseek-chat", None),
- ({"MODEL": "wafer/DeepSeek-V4-Pro"}, "wafer/DeepSeek-V4-Pro", None),
- (
- {"MODEL": "cloudflare/@cf/moonshotai/kimi-k2.6"},
- "cloudflare/@cf/moonshotai/kimi-k2.6",
- None,
- ),
- (
- {"MODEL": "github_models/openai/gpt-4.1"},
- "github_models/openai/gpt-4.1",
- None,
- ),
- (
- {"MODEL": "sambanova/Meta-Llama-3.3-70B-Instruct"},
- "sambanova/Meta-Llama-3.3-70B-Instruct",
- None,
- ),
- ({"MODEL": "lmstudio/qwen2.5-7b"}, "lmstudio/qwen2.5-7b", None),
- ({"MODEL": "llamacpp/local-model"}, "llamacpp/local-model", None),
- ({"MODEL": "ollama/llama3.1"}, "ollama/llama3.1", None),
- (
- {"MODEL": "ollama_cloud/qwen3-coder:480b"},
- "ollama_cloud/qwen3-coder:480b",
- None,
- ),
- ],
+ router = ModelRouter(settings)
+ assert router.resolve("claude-opus-4").provider_model_ref == (
+ "open_router/anthropic/claude-opus"
)
- def test_settings_models_from_env(
- self, env_vars, expected_model, expected_haiku, monkeypatch
- ):
- """Test environment variables override model defaults."""
- from free_claude_code.config.settings import Settings
-
- for k, v in env_vars.items():
- monkeypatch.setenv(k, v)
+ assert router.resolve("unknown").provider_model_ref == "deepseek/fallback"
+ with pytest.raises(ValidationError, match="Invalid provider"):
+ Settings(model="unknown/model")
- s = Settings()
- assert s.model == expected_model
- assert s.model_haiku == expected_haiku
- def test_model_sonnet_from_env(self, monkeypatch):
- """MODEL_SONNET env var is loaded."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("MODEL_SONNET", "nvidia_nim/meta/llama-3.3-70b-instruct")
- s = Settings()
- assert s.model_sonnet == "nvidia_nim/meta/llama-3.3-70b-instruct"
-
- def test_model_haiku_from_env(self, monkeypatch):
- """MODEL_HAIKU env var is loaded."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("MODEL_HAIKU", "lmstudio/qwen2.5-7b")
- s = Settings()
- assert s.model_haiku == "lmstudio/qwen2.5-7b"
-
- def test_model_opus_invalid_provider_raises(self, monkeypatch):
- """MODEL_OPUS with invalid provider prefix raises ValidationError."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("MODEL_OPUS", "bad_provider/some-model")
- with pytest.raises(ValidationError, match="Invalid provider"):
- Settings()
-
- def test_model_opus_no_slash_raises(self, monkeypatch):
- """MODEL_OPUS without provider prefix raises ValidationError."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("MODEL_OPUS", "noprefix")
- with pytest.raises(ValidationError, match="provider type"):
- Settings()
-
- def test_model_haiku_invalid_provider_raises(self, monkeypatch):
- """MODEL_HAIKU with invalid provider prefix raises ValidationError."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("MODEL_HAIKU", "invalid/model")
- with pytest.raises(ValidationError, match="Invalid provider"):
- Settings()
-
- def test_model_fable_invalid_provider_raises(self, monkeypatch):
- """MODEL_FABLE with invalid provider prefix raises ValidationError."""
- from free_claude_code.config.settings import Settings
-
- monkeypatch.setenv("MODEL_FABLE", "invalid/model")
- with pytest.raises(ValidationError, match="Invalid provider"):
- Settings()
-
- def test_resolve_model_fable_override(self):
- """ModelRouter returns model_fable for Fable model names."""
- from free_claude_code.application.routing import ModelRouter
- from free_claude_code.config.settings import Settings
-
- s = Settings()
- s.model_fable = "open_router/anthropic/claude-fable-5"
- assert (
- ModelRouter(s).resolve("claude-fable-5").provider_model_ref
- == "open_router/anthropic/claude-fable-5"
- )
-
- def test_resolve_model_opus_override(self):
- """ModelRouter returns model_opus for opus model names."""
- from free_claude_code.application.routing import ModelRouter
- from free_claude_code.config.settings import Settings
-
- s = Settings()
- s.model_opus = "open_router/deepseek/deepseek-r1"
- router = ModelRouter(s)
- assert (
- router.resolve("claude-opus-4-20250514").provider_model_ref
- == "open_router/deepseek/deepseek-r1"
- )
- assert (
- router.resolve("claude-3-opus").provider_model_ref
- == "open_router/deepseek/deepseek-r1"
- )
- assert (
- router.resolve("claude-3-opus-20240229").provider_model_ref
- == "open_router/deepseek/deepseek-r1"
- )
-
- def test_resolve_model_sonnet_override(self):
- """ModelRouter returns model_sonnet for sonnet model names."""
- from free_claude_code.application.routing import ModelRouter
- from free_claude_code.config.settings import Settings
-
- s = Settings()
- s.model_sonnet = "nvidia_nim/meta/llama-3.3-70b-instruct"
- router = ModelRouter(s)
- assert (
- router.resolve("claude-sonnet-4-20250514").provider_model_ref
- == "nvidia_nim/meta/llama-3.3-70b-instruct"
- )
- assert (
- router.resolve("claude-3-5-sonnet-20241022").provider_model_ref
- == "nvidia_nim/meta/llama-3.3-70b-instruct"
- )
-
- def test_resolve_model_haiku_override(self):
- """ModelRouter returns model_haiku for haiku model names."""
- from free_claude_code.application.routing import ModelRouter
- from free_claude_code.config.settings import Settings
-
- s = Settings()
- s.model_haiku = "lmstudio/qwen2.5-7b"
- router = ModelRouter(s)
- assert (
- router.resolve("claude-3-haiku-20240307").provider_model_ref
- == "lmstudio/qwen2.5-7b"
- )
- assert (
- router.resolve("claude-3-5-haiku-20241022").provider_model_ref
- == "lmstudio/qwen2.5-7b"
- )
- assert (
- router.resolve("claude-haiku-4-20250514").provider_model_ref
- == "lmstudio/qwen2.5-7b"
- )
-
- def test_resolve_model_fallback_when_override_not_set(self):
- """ModelRouter falls back to MODEL when model override is None."""
- from free_claude_code.application.routing import ModelRouter
- from free_claude_code.config.settings import Settings
-
- s = Settings()
- s.model = "nvidia_nim/fallback-model"
- router = ModelRouter(s)
- assert (
- router.resolve("claude-fable-5").provider_model_ref
- == "nvidia_nim/fallback-model"
- )
- assert (
- router.resolve("claude-opus-4-20250514").provider_model_ref
- == "nvidia_nim/fallback-model"
- )
- assert (
- router.resolve("claude-sonnet-4-20250514").provider_model_ref
- == "nvidia_nim/fallback-model"
- )
- assert (
- router.resolve("claude-3-haiku-20240307").provider_model_ref
- == "nvidia_nim/fallback-model"
- )
+def test_configured_chat_model_refs_are_unique() -> None:
+ settings = Settings(
+ model="deepseek/fallback",
+ model_fable="open_router/anthropic/claude-fable",
+ model_sonnet="deepseek/fallback",
+ )
- def test_resolve_model_unknown_model_falls_back(self):
- """ModelRouter falls back to MODEL for unrecognized model names."""
- from free_claude_code.application.routing import ModelRouter
- from free_claude_code.config.settings import Settings
+ refs = configured_chat_model_refs(settings)
- s = Settings()
- s.model = "nvidia_nim/fallback-model"
- s.model_opus = "open_router/opus-model"
- router = ModelRouter(s)
- assert router.resolve("claude-2.1").provider_model_ref == (
- "nvidia_nim/fallback-model"
- )
- assert router.resolve("some-unknown-model").provider_model_ref == (
- "nvidia_nim/fallback-model"
- )
+ assert [ref.model_ref for ref in refs] == [
+ "deepseek/fallback",
+ "open_router/anthropic/claude-fable",
+ ]
- def test_resolve_model_case_insensitive(self):
- """Model classification is case-insensitive."""
- from free_claude_code.application.routing import ModelRouter
- from free_claude_code.config.settings import Settings
- s = Settings()
- s.model_opus = "open_router/opus-model"
- assert (
- ModelRouter(s).resolve("Claude-OPUS-4").provider_model_ref
- == "open_router/opus-model"
- )
+ ("model_ref", "provider", "model"),
+ [
+ ("nvidia_nim/meta/llama", "nvidia_nim", "meta/llama"),
+ ("open_router/deepseek/r1", "open_router", "deepseek/r1"),
+ ("ollama_cloud/qwen3-coder:480b", "ollama_cloud", "qwen3-coder:480b"),
+ ],
+)
+def test_model_ref_parsing(model_ref: str, provider: str, model: str) -> None:
+ assert parse_provider_type(model_ref) == provider
+ assert parse_model_name(model_ref) == model
- def test_parse_provider_type(self):
- """parse_provider_type extracts provider from model string."""
- assert parse_provider_type("nvidia_nim/meta/llama") == "nvidia_nim"
- assert parse_provider_type("open_router/deepseek/r1") == "open_router"
- assert parse_provider_type("mistral/devstral-small-latest") == "mistral"
- assert (
- parse_provider_type("mistral_codestral/codestral-latest")
- == "mistral_codestral"
- )
- assert parse_provider_type("deepseek/deepseek-chat") == "deepseek"
- assert parse_provider_type("lmstudio/qwen") == "lmstudio"
- assert parse_provider_type("llamacpp/model") == "llamacpp"
- assert parse_provider_type("ollama/llama3.1") == "ollama"
- assert parse_provider_type("ollama_cloud/qwen3-coder:480b") == "ollama_cloud"
- assert parse_provider_type("wafer/DeepSeek-V4-Pro") == "wafer"
- assert parse_provider_type("minimax/MiniMax-M3") == "minimax"
- assert (
- parse_provider_type("cloudflare/@cf/moonshotai/kimi-k2.6") == "cloudflare"
- )
- assert parse_provider_type("vercel/openai/gpt-5.5") == "vercel"
- assert (
- parse_provider_type("huggingface/openai/gpt-oss-120b:fastest")
- == "huggingface"
- )
- assert parse_provider_type("cohere/command-a-plus-05-2026") == "cohere"
- assert parse_provider_type("github_models/openai/gpt-4.1") == ("github_models")
- assert parse_provider_type("gemini/models/gemini-3.1-flash-lite") == "gemini"
- assert parse_provider_type("groq/llama-3.3-70b-versatile") == "groq"
- assert (
- parse_provider_type("sambanova/Meta-Llama-3.3-70B-Instruct") == "sambanova"
- )
- assert parse_provider_type("cerebras/llama3.1-8b") == "cerebras"
+def test_paths_are_owned_by_fcc_home(monkeypatch: pytest.MonkeyPatch, tmp_path) -> None:
+ monkeypatch.setenv("HOME", str(tmp_path))
+ monkeypatch.setenv("USERPROFILE", str(tmp_path))
- def test_parse_model_name(self):
- """parse_model_name extracts model name from model string."""
+ assert messaging_state_dir_path() == tmp_path / ".fcc" / "agent_workspace"
+ assert server_log_path() == tmp_path / ".fcc" / "logs" / "server.log"
- assert parse_model_name("nvidia_nim/meta/llama") == "meta/llama"
- assert parse_model_name("mistral/devstral-small-latest") == (
- "devstral-small-latest"
- )
- assert (
- parse_model_name("mistral_codestral/codestral-latest") == "codestral-latest"
- )
- assert parse_model_name("deepseek/deepseek-chat") == "deepseek-chat"
- assert parse_model_name("lmstudio/qwen") == "qwen"
- assert parse_model_name("llamacpp/model") == "model"
- assert parse_model_name("ollama/llama3.1") == "llama3.1"
- assert parse_model_name("ollama_cloud/qwen3-coder:480b") == "qwen3-coder:480b"
- assert parse_model_name("wafer/DeepSeek-V4-Pro") == "DeepSeek-V4-Pro"
- assert parse_model_name("minimax/MiniMax-M3") == "MiniMax-M3"
- assert (
- parse_model_name("cloudflare/@cf/moonshotai/kimi-k2.6")
- == "@cf/moonshotai/kimi-k2.6"
- )
- assert parse_model_name("vercel/openai/gpt-5.5") == "openai/gpt-5.5"
- assert (
- parse_model_name("huggingface/openai/gpt-oss-120b:fastest")
- == "openai/gpt-oss-120b:fastest"
- )
- assert parse_model_name("cohere/command-a-plus-05-2026") == (
- "command-a-plus-05-2026"
- )
- assert parse_model_name("github_models/openai/gpt-4.1") == "openai/gpt-4.1"
- assert (
- parse_model_name("gemini/models/gemini-3.1-flash-lite")
- == "models/gemini-3.1-flash-lite"
- )
- assert (
- parse_model_name("groq/llama-3.3-70b-versatile")
- == "llama-3.3-70b-versatile"
- )
- assert (
- parse_model_name("sambanova/Meta-Llama-3.3-70B-Instruct")
- == "Meta-Llama-3.3-70B-Instruct"
- )
- assert parse_model_name("cerebras/llama3.1-8b") == "llama3.1-8b"
- def test_configured_chat_model_refs_collects_unique_models(self, monkeypatch):
- """Model discovery is limited to configured chat references."""
- from free_claude_code.config.settings import Settings
+def test_nim_settings_keep_request_local_validation() -> None:
+ settings = NimSettings.model_validate(
+ {
+ "max_tokens": "1024",
+ "temperature": "0.5",
+ "seed": "7",
+ "stop": "",
+ }
+ )
- monkeypatch.setenv("FCC_SMOKE_MODEL_NVIDIA_NIM", "nvidia_nim/smoke")
- monkeypatch.setenv("WHISPER_MODEL", "openai/whisper-large-v3")
- s = Settings()
- s.model = "nvidia_nim/fallback"
- s.model_fable = "open_router/anthropic/claude-fable-5"
- s.model_opus = "open_router/anthropic/claude-opus"
- s.model_sonnet = "nvidia_nim/fallback"
- s.model_haiku = None
+ assert settings.max_tokens == 1024
+ assert settings.temperature == 0.5
+ assert settings.seed == 7
+ assert settings.stop is None
+ assert NimSettings().max_tokens == ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
+ with pytest.raises(ValidationError):
+ NimSettings(top_p=1.1)
- refs = configured_chat_model_refs(s)
- assert [ref.model_ref for ref in refs] == [
- "nvidia_nim/fallback",
- "open_router/anthropic/claude-fable-5",
- "open_router/anthropic/claude-opus",
- ]
- assert refs[0].provider_id == "nvidia_nim"
- assert refs[0].model_id == "fallback"
- assert refs[1].provider_id == "open_router"
- assert refs[1].model_id == "anthropic/claude-fable-5"
- assert refs[2].provider_id == "open_router"
- assert refs[2].model_id == "anthropic/claude-opus"
+def test_settings_defaults_do_not_contain_empty_enum_strings() -> None:
+ for _name, value in Settings():
+ if isinstance(value, Enum):
+ assert value.value
diff --git a/tests/config/test_env_migrations.py b/tests/config/test_env_migrations.py
index f8042047..630f7863 100644
--- a/tests/config/test_env_migrations.py
+++ b/tests/config/test_env_migrations.py
@@ -1,221 +1,369 @@
+"""Contracts for one-time managed-config consolidation."""
+
+import os
+from concurrent.futures import ThreadPoolExecutor
from pathlib import Path
import pytest
+from free_claude_code.config import env_migrations
+from free_claude_code.config.env_files import dotenv_values_from_file
from free_claude_code.config.env_migrations import (
- HUGGINGFACE_API_KEY_ENV,
+ CONFIG_SCHEMA_VERSION,
HUGGINGFACE_TOKEN_MIGRATION,
- LEGACY_HUGGINGFACE_TOKEN_ENV,
- LEGACY_OPENCODE_PROXY_ENV,
OPENCODE_ZEN_MODEL_REF_MIGRATIONS,
- OPENCODE_ZEN_PROXY_ENV,
- REASONING_MIGRATIONS,
- env_text_needs_migration,
- explicit_env_file_migration_warning,
- migrate_env_setting_in_file,
+ consolidate_managed_config,
migrate_env_setting_in_text,
- migrate_owned_env_files,
)
+from free_claude_code.config.loader import resolve_settings_snapshot
-def test_migrate_env_key_in_text_renames_legacy_hf_token() -> None:
- text = "# comment\nHF_TOKEN=old-token\nMODEL=nvidia_nim/model\n"
+def _paths(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> tuple[Path, Path]:
+ managed = tmp_path / ".fcc" / ".env"
+ legacy = tmp_path / "legacy" / ".env"
+ monkeypatch.setattr(env_migrations, "managed_env_path", lambda: managed)
+ monkeypatch.setattr(env_migrations, "legacy_env_paths", lambda: (legacy,))
+ monkeypatch.setattr(env_migrations, "verified_checkout_env_path", lambda: None)
+ return managed, legacy
- migrated, changed = migrate_env_setting_in_text(text, HUGGINGFACE_TOKEN_MIGRATION)
+def test_pure_key_and_value_migrations_remain_available() -> None:
+ migrated, changed = migrate_env_setting_in_text(
+ "HF_TOKEN=legacy\n",
+ HUGGINGFACE_TOKEN_MIGRATION,
+ )
assert changed is True
- assert migrated == (
- "# comment\nHUGGINGFACE_API_KEY=old-token\nMODEL=nvidia_nim/model\n"
+ assert migrated == "HUGGINGFACE_API_KEY=legacy\n"
+
+ migration = next(
+ item for item in OPENCODE_ZEN_MODEL_REF_MIGRATIONS if item.old_key == "MODEL"
+ )
+ migrated, changed = migrate_env_setting_in_text(
+ "MODEL=opencode/model\n",
+ migration,
)
+ assert changed is True
+ assert migrated == "MODEL=opencode_zen/model\n"
-def test_migrate_env_key_in_text_preserves_existing_huggingface_api_key() -> None:
- text = "HF_TOKEN=old-token\nHUGGINGFACE_API_KEY=new-token\n"
+def test_fresh_install_writes_only_schema_metadata(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ managed, _legacy = _paths(monkeypatch, tmp_path)
- migrated, changed = migrate_env_setting_in_text(text, HUGGINGFACE_TOKEN_MIGRATION)
+ result = consolidate_managed_config({})
- assert changed is False
- assert migrated == text
+ assert result.changed is True
+ assert dotenv_values_from_file(managed) == {
+ "FCC_CONFIG_SCHEMA": CONFIG_SCHEMA_VERSION
+ }
-def test_migrate_env_key_in_text_ignores_comments() -> None:
- text = "# HF_TOKEN=old-token\n"
+def test_legacy_file_imports_only_recognized_values_and_is_untouched(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ managed, legacy = _paths(monkeypatch, tmp_path)
+ legacy.parent.mkdir(parents=True)
+ original = "MODEL=deepseek/legacy\nUNRELATED_SECRET=leave-me\nHF_TOKEN=hf\n"
+ legacy.write_text(original, encoding="utf-8")
- migrated, changed = migrate_env_setting_in_text(text, HUGGINGFACE_TOKEN_MIGRATION)
+ result = consolidate_managed_config({})
+ values = dotenv_values_from_file(managed)
- assert changed is False
- assert migrated == text
- assert not env_text_needs_migration(text, HUGGINGFACE_TOKEN_MIGRATION)
+ assert result.imported_from == (legacy.resolve(),)
+ assert values["MODEL"] == "deepseek/legacy"
+ assert values["HUGGINGFACE_API_KEY"] == "hf"
+ assert values["PROXY_AUTH_ENABLED"] == "false"
+ assert "UNRELATED_SECRET" not in values
+ assert legacy.read_text(encoding="utf-8") == original
-def test_migrate_env_key_in_file_rewrites_dotenv(tmp_path: Path) -> None:
- env_file = tmp_path / ".env"
- env_file.write_text("export HF_TOKEN = quoted-token\n", encoding="utf-8")
+def test_existing_managed_state_does_not_merge_legacy(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ managed, legacy = _paths(monkeypatch, tmp_path)
+ managed.parent.mkdir(parents=True)
+ managed.write_text("MODEL=groq/managed\n", encoding="utf-8")
+ legacy.parent.mkdir(parents=True)
+ legacy.write_text("MODEL=deepseek/legacy\nGROQ_API_KEY=legacy-key\n")
- assert migrate_env_setting_in_file(env_file, HUGGINGFACE_TOKEN_MIGRATION) is True
+ consolidate_managed_config({})
+ values = dotenv_values_from_file(managed)
- assert env_file.read_text(encoding="utf-8") == (
- "export HUGGINGFACE_API_KEY = quoted-token\n"
- )
+ assert values["MODEL"] == "groq/managed"
+ assert "GROQ_API_KEY" not in values
-def test_migrate_owned_env_files_rewrites_repo_and_managed_env(
- monkeypatch, tmp_path: Path
+def test_verified_checkout_imports_only_when_managed_and_legacy_are_absent(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
- repo = tmp_path / "repo"
- repo.mkdir()
- managed = tmp_path / ".fcc" / ".env"
- managed.parent.mkdir()
- (repo / ".env").write_text("HF_TOKEN=repo-token\n", encoding="utf-8")
- managed.write_text("HF_TOKEN=managed-token\n", encoding="utf-8")
- monkeypatch.chdir(repo)
- monkeypatch.setenv("HOME", str(tmp_path))
- monkeypatch.setenv("USERPROFILE", str(tmp_path))
-
- migrated = migrate_owned_env_files()
-
- assert migrated == (repo / ".env", managed)
- assert (repo / ".env").read_text(encoding="utf-8") == (
- "HUGGINGFACE_API_KEY=repo-token\n"
- )
- assert managed.read_text(encoding="utf-8") == (
- "HUGGINGFACE_API_KEY=managed-token\n"
+ managed, _legacy = _paths(monkeypatch, tmp_path)
+ checkout = tmp_path / "checkout.env"
+ original = "MODEL=deepseek/checkout\n"
+ checkout.write_text(original, encoding="utf-8")
+ monkeypatch.setattr(env_migrations, "legacy_env_paths", lambda: ())
+ monkeypatch.setattr(
+ env_migrations,
+ "verified_checkout_env_path",
+ lambda: checkout,
)
+ result = consolidate_managed_config({})
-def test_explicit_env_file_migration_warning_does_not_rewrite(
- tmp_path: Path,
+ assert result.imported_from == (checkout.resolve(),)
+ assert dotenv_values_from_file(managed)["MODEL"] == "deepseek/checkout"
+ assert checkout.read_text(encoding="utf-8") == original
+
+
+def test_canonical_setting_wins_and_retired_key_is_removed(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
- explicit = tmp_path / "custom.env"
- explicit.write_text("HF_TOKEN=explicit-token\n", encoding="utf-8")
+ managed, legacy = _paths(monkeypatch, tmp_path)
+ legacy.parent.mkdir(parents=True)
+ legacy.write_text(
+ "HF_TOKEN=old-token\nHUGGINGFACE_API_KEY=current-token\n",
+ encoding="utf-8",
+ )
- warning = explicit_env_file_migration_warning({"FCC_ENV_FILE": str(explicit)})
+ consolidate_managed_config({})
+ values = dotenv_values_from_file(managed)
- assert warning is not None
- assert str(explicit) in warning
- assert LEGACY_HUGGINGFACE_TOKEN_ENV in warning
- assert HUGGINGFACE_API_KEY_ENV in warning
- assert explicit.read_text(encoding="utf-8") == "HF_TOKEN=explicit-token\n"
+ assert values["HUGGINGFACE_API_KEY"] == "current-token"
+ assert "HF_TOKEN" not in values
-def test_opencode_zen_migration_rewrites_owned_model_refs_and_keys(
- monkeypatch,
- tmp_path: Path,
+def test_explicit_file_overlays_once_and_then_becomes_inert(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
- repo = tmp_path / "repo"
- repo.mkdir()
- env_file = repo / ".env"
- env_file.write_text(
- "MODEL=opencode/kimi-k2.6\n"
- 'MODEL_FABLE = "opencode/model-a" # keep\n'
- "MODEL_OPUS='opencode/model-b'\n"
- "MODEL_SONNET=opencode_go/model-c\n"
- "MODEL_HAIKU=open_router/opencode/model-d\n"
- "FCC_SMOKE_MODEL_OPENCODE=opencode/smoke\n"
- "OPENCODE_PROXY=http://proxy.example\n",
- encoding="utf-8",
- )
- monkeypatch.chdir(repo)
- monkeypatch.setenv("HOME", str(tmp_path))
- monkeypatch.setenv("USERPROFILE", str(tmp_path))
-
- assert migrate_owned_env_files() == (env_file,)
- assert env_file.read_text(encoding="utf-8") == (
- "MODEL=opencode_zen/kimi-k2.6\n"
- 'MODEL_FABLE = "opencode_zen/model-a" # keep\n'
- "MODEL_OPUS='opencode_zen/model-b'\n"
- "MODEL_SONNET=opencode_go/model-c\n"
- "MODEL_HAIKU=open_router/opencode/model-d\n"
- "FCC_SMOKE_MODEL_OPENCODE_ZEN=opencode_zen/smoke\n"
- "OPENCODE_ZEN_PROXY=http://proxy.example\n"
- )
- assert migrate_owned_env_files() == ()
+ managed, legacy = _paths(monkeypatch, tmp_path)
+ legacy.parent.mkdir(parents=True)
+ legacy.write_text("MODEL=deepseek/base\nGROQ_API_KEY=base-key\n")
+ explicit = tmp_path / "explicit.env"
+ original = "MODEL=open_router/override\nGROQ_API_KEY=\n"
+ explicit.write_text(original, encoding="utf-8")
+
+ consolidate_managed_config({"FCC_ENV_FILE": str(explicit)})
+ first = dotenv_values_from_file(managed)
+ assert explicit.read_text(encoding="utf-8") == original
+ explicit.write_text("MODEL=groq/later\n", encoding="utf-8")
+ result = consolidate_managed_config({"FCC_ENV_FILE": str(explicit)})
+
+ assert first["MODEL"] == "open_router/override"
+ assert "GROQ_API_KEY" not in first
+ assert result.changed is False
+ assert dotenv_values_from_file(managed)["MODEL"] == "open_router/override"
+ assert explicit.read_text(encoding="utf-8") == "MODEL=groq/later\n"
+
+
+def test_post_schema_invalid_explicit_path_is_never_dereferenced(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ managed, _legacy = _paths(monkeypatch, tmp_path)
+ managed.parent.mkdir(parents=True)
+ managed.write_text("FCC_CONFIG_SCHEMA=1\n", encoding="utf-8")
+ result = consolidate_managed_config({"FCC_ENV_FILE": str(tmp_path / "missing.env")})
-def test_opencode_zen_value_migration_ignores_comments_and_other_values() -> None:
- text = (
- "# MODEL=opencode/commented\n"
- "MODEL=opencode_go/model\n"
- "MODEL_OPUS=open_router/opencode/model\n"
- )
+ assert result.changed is False
- migrated = text
- changed = False
- for migration in OPENCODE_ZEN_MODEL_REF_MIGRATIONS:
- migrated, migration_changed = migrate_env_setting_in_text(
- migrated,
- migration,
- )
- changed = changed or migration_changed
- assert changed is False
- assert migrated == text
- assert not any(
- env_text_needs_migration(text, migration)
- for migration in OPENCODE_ZEN_MODEL_REF_MIGRATIONS
- )
+def test_pre_schema_invalid_explicit_path_fails_without_writing(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ managed, _legacy = _paths(monkeypatch, tmp_path)
+ with pytest.raises(FileNotFoundError, match=r"missing\.env"):
+ consolidate_managed_config({"FCC_ENV_FILE": str(tmp_path / "missing.env")})
-def test_explicit_env_file_warns_for_opencode_zen_migrations(
- tmp_path: Path,
+ assert not managed.exists()
+
+
+def test_pre_schema_malformed_explicit_file_fails_without_writing(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
- explicit = tmp_path / "custom.env"
- explicit.write_text(
- "MODEL=opencode/model\nOPENCODE_PROXY=http://proxy.example\n",
- encoding="utf-8",
- )
+ managed, _legacy = _paths(monkeypatch, tmp_path)
+ explicit = tmp_path / "malformed.env"
+ original = 'MODEL="unterminated\n'
+ explicit.write_text(original, encoding="utf-8")
- warning = explicit_env_file_migration_warning({"FCC_ENV_FILE": str(explicit)})
+ with pytest.raises(ValueError, match=r"malformed\.env.*line 1"):
+ consolidate_managed_config({"FCC_ENV_FILE": str(explicit)})
- assert warning is not None
- assert LEGACY_OPENCODE_PROXY_ENV in warning
- assert OPENCODE_ZEN_PROXY_ENV in warning
- assert "opencode/" in warning
- assert "opencode_zen/" in warning
- assert explicit.read_text(encoding="utf-8") == (
- "MODEL=opencode/model\nOPENCODE_PROXY=http://proxy.example\n"
- )
+ assert not managed.exists()
+ assert explicit.read_text(encoding="utf-8") == original
-def test_reasoning_migrations_rename_and_map_boolean_values() -> None:
- text = (
- "ENABLE_MODEL_THINKING=false\n"
- "ENABLE_FABLE_THINKING=true\n"
- "ENABLE_OPUS_THINKING=\n"
- )
+def test_explicit_managed_path_is_deduplicated(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ managed, _legacy = _paths(monkeypatch, tmp_path)
- for migration in REASONING_MIGRATIONS:
- text, _ = migrate_env_setting_in_text(text, migration)
+ result = consolidate_managed_config({"FCC_ENV_FILE": str(managed)})
- assert text == (
- "REASONING_POLICY=off\nREASONING_FABLE=client\nREASONING_OPUS=inherit\n"
- )
+ assert result.imported_from == ()
+ assert dotenv_values_from_file(managed) == {
+ "FCC_CONFIG_SCHEMA": CONFIG_SCHEMA_VERSION
+ }
@pytest.mark.parametrize(
- ("legacy_value", "expected"),
+ ("dotenv", "process", "enabled", "token"),
[
- ("1", "client"),
- ("TRUE", "client"),
- ("t", "client"),
- ("on", "client"),
- ("yes", "client"),
- ("y", "client"),
- ("0", "off"),
- ("FALSE", "off"),
- ("f", "off"),
- ("off", "off"),
- ("no", "off"),
- ("n", "off"),
+ ("ANTHROPIC_AUTH_TOKEN=secret\n", {}, "true", "secret"),
+ ("ANTHROPIC_AUTH_TOKEN=\n", {}, "false", None),
+ ("", {"ANTHROPIC_AUTH_TOKEN": "process-secret"}, "true", None),
+ ("", {}, "false", None),
+ (
+ "PROXY_AUTH_ENABLED=false\nANTHROPIC_AUTH_TOKEN=secret\n",
+ {},
+ "false",
+ "secret",
+ ),
],
)
-def test_reasoning_migration_accepts_every_legacy_boolean_spelling(
- legacy_value: str,
- expected: str,
+def test_auth_state_is_materialized_once(
+ monkeypatch: pytest.MonkeyPatch,
+ tmp_path: Path,
+ dotenv: str,
+ process: dict[str, str],
+ enabled: str,
+ token: str | None,
) -> None:
- text = f"ENABLE_MODEL_THINKING={legacy_value}\n"
+ managed, legacy = _paths(monkeypatch, tmp_path)
+ legacy.parent.mkdir(parents=True)
+ legacy.write_text(dotenv, encoding="utf-8")
- migrated, changed = migrate_env_setting_in_text(text, REASONING_MIGRATIONS[0])
+ consolidate_managed_config(process)
+ values = dotenv_values_from_file(managed)
- assert changed is True
- assert migrated == f"REASONING_POLICY={expected}\n"
+ assert values["PROXY_AUTH_ENABLED"] == enabled
+ assert values.get("ANTHROPIC_AUTH_TOKEN") == token
+
+
+def test_process_auth_flag_is_not_persisted(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ managed, _legacy = _paths(monkeypatch, tmp_path)
+
+ consolidate_managed_config({"PROXY_AUTH_ENABLED": "true"})
+
+ assert "PROXY_AUTH_ENABLED" not in dotenv_values_from_file(managed)
+
+
+def test_only_managed_schema_marker_is_trusted(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ managed, legacy = _paths(monkeypatch, tmp_path)
+ legacy.parent.mkdir(parents=True)
+ legacy.write_text("FCC_CONFIG_SCHEMA=99\nMODEL=deepseek/imported\n")
+
+ consolidate_managed_config({"FCC_CONFIG_SCHEMA": "99"})
+
+ values = dotenv_values_from_file(managed)
+ assert values["FCC_CONFIG_SCHEMA"] == "1"
+ assert values["MODEL"] == "deepseek/imported"
+
+
+def test_unknown_managed_assignments_survive_canonicalization(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ managed, _legacy = _paths(monkeypatch, tmp_path)
+ managed.parent.mkdir(parents=True)
+ managed.write_text("MODEL=deepseek/model\nCUSTOM=\n", encoding="utf-8")
+
+ consolidate_managed_config({})
+
+ values = dotenv_values_from_file(managed)
+ assert values["CUSTOM"] == ""
+ assert values["MODEL"] == "deepseek/model"
+
+
+def test_repeated_migration_is_byte_for_byte_idempotent(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ managed, legacy = _paths(monkeypatch, tmp_path)
+ legacy.parent.mkdir(parents=True)
+ legacy.write_text("MODEL=opencode/model\n", encoding="utf-8")
+
+ consolidate_managed_config({})
+ first = managed.read_bytes()
+ result = consolidate_managed_config({})
+
+ assert result.changed is False
+ assert managed.read_bytes() == first
+
+
+def test_duplicate_recognized_assignments_collapse_to_last_value(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ managed, _legacy = _paths(monkeypatch, tmp_path)
+ managed.parent.mkdir(parents=True)
+ managed.write_text(
+ "MODEL=deepseek/first\nMODEL=groq/last\n",
+ encoding="utf-8",
+ )
+
+ consolidate_managed_config({})
+
+ assert dotenv_values_from_file(managed)["MODEL"] == "groq/last"
+ assert managed.read_text(encoding="utf-8").count("MODEL=") == 1
+
+
+def test_concurrent_loaders_produce_one_valid_managed_file(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ managed, legacy = _paths(monkeypatch, tmp_path)
+ legacy.parent.mkdir(parents=True)
+ legacy.write_text("MODEL=deepseek/concurrent\n", encoding="utf-8")
+
+ with ThreadPoolExecutor(max_workers=8) as executor:
+ snapshots = list(
+ executor.map(lambda _index: resolve_settings_snapshot({}), range(8))
+ )
+
+ assert {snapshot.settings.model for snapshot in snapshots} == {
+ "deepseek/concurrent"
+ }
+ assert dotenv_values_from_file(managed)["FCC_CONFIG_SCHEMA"] == "1"
+ assert list(managed.parent.glob("*.tmp")) == []
+
+
[email protected](os.name == "nt", reason="POSIX permissions")
+def test_managed_config_is_owner_only_on_posix(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ managed, _legacy = _paths(monkeypatch, tmp_path)
+
+ consolidate_managed_config({})
+
+ assert managed.stat().st_mode & 0o777 == 0o600
+
+
+def test_atomic_replace_failure_preserves_original(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ managed, _legacy = _paths(monkeypatch, tmp_path)
+ managed.parent.mkdir(parents=True)
+ original = "MODEL=deepseek/original\n"
+ managed.write_text(original, encoding="utf-8")
+
+ def fail_replace(_source: Path, _target: Path) -> None:
+ raise OSError("replace failed")
+
+ monkeypatch.setattr(os, "replace", fail_replace)
+ with pytest.raises(OSError, match="replace failed"):
+ consolidate_managed_config({})
+
+ assert managed.read_text(encoding="utf-8") == original
+ assert list(managed.parent.glob("*.tmp")) == []
+
+
+def test_newer_managed_schema_fails_closed(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ managed, _legacy = _paths(monkeypatch, tmp_path)
+ managed.parent.mkdir(parents=True)
+ managed.write_text("FCC_CONFIG_SCHEMA=2\n", encoding="utf-8")
+
+ with pytest.raises(ValueError, match="unsupported schema"):
+ consolidate_managed_config({})
diff --git a/tests/config/test_env_template.py b/tests/config/test_env_template.py
deleted file mode 100644
index db8a3dd3..00000000
--- a/tests/config/test_env_template.py
+++ /dev/null
@@ -1,13 +0,0 @@
-from pathlib import Path
-
-from free_claude_code.config.env_template import load_env_template
-
-
-def test_env_template_loader_uses_root_template_in_source_checkout() -> None:
- """Source checkout fallback uses the root .env.example as the single source."""
-
- template = (Path(__file__).resolve().parents[2] / ".env.example").read_text(
- encoding="utf-8"
- )
-
- assert load_env_template() == template
diff --git a/tests/conftest.py b/tests/conftest.py
index bfb155d4..5f14b40b 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -7,37 +7,49 @@ from unittest.mock import AsyncMock, MagicMock
import pytest
-from free_claude_code.config.settings import Settings
-from tests.providers.support import immediate_admission
-
-# Set mock environment BEFORE any imports that use Settings
+from free_claude_code.config import env_migrations, paths
+from free_claude_code.config.loader import clear_settings_cache
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+)
+
+# Set deterministic process overrides before any test resolves Settings.
os.environ.setdefault("NVIDIA_NIM_API_KEY", "test_key")
os.environ.setdefault("MODEL", "nvidia_nim/test-model")
os.environ["PTB_TIMEDELTA"] = "1"
-# Ensure tests don't pick up a server API key from the repo .env
-# (tests expect endpoints to be unauthenticated by default)
+# Tests keep proxy authentication disabled unless a case enables it explicitly.
os.environ["ANTHROPIC_AUTH_TOKEN"] = ""
-Settings.model_config = {**Settings.model_config, "env_file": None}
-
@pytest.fixture(autouse=True)
-def _isolate_from_dotenv(monkeypatch):
- """Prevent Pydantic BaseSettings from reading the .env file during tests."""
- monkeypatch.setattr(
- Settings, "model_config", {**Settings.model_config, "env_file": None}
- )
+def _isolate_managed_config(monkeypatch, tmp_path):
+ """Keep every test away from real home, checkout, and running-server config."""
+
+ config_dir = tmp_path / ".fcc"
+ monkeypatch.setattr(paths, "config_dir_path", lambda: config_dir)
+ monkeypatch.setattr(env_migrations, "legacy_env_paths", lambda: ())
+ monkeypatch.setattr(env_migrations, "verified_checkout_env_path", lambda: None)
+ clear_settings_cache()
+ yield
+ clear_settings_cache()
@pytest.fixture
def provider_config():
- from free_claude_code.providers.base import ProviderConfig
- return ProviderConfig(
+ return make_provider_config(
api_key="test_key",
base_url="https://test.api.nvidia.com/v1",
rate_limit=10,
rate_window=60,
+ max_concurrency=5,
+ http_read_timeout=300.0,
+ http_write_timeout=10.0,
+ http_connect_timeout=10.0,
+ proxy=None,
+ log_raw_sse_events=False,
+ log_api_error_tracebacks=False,
)
@@ -62,28 +74,40 @@ def open_router_provider(provider_config):
@pytest.fixture
def lmstudio_provider(provider_config):
- from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.lmstudio import LMStudioProvider
- lmstudio_config = ProviderConfig(
+ lmstudio_config = make_provider_config(
api_key="lm-studio",
base_url="http://localhost:1234/v1",
rate_limit=provider_config.rate_limit,
rate_window=provider_config.rate_window,
+ max_concurrency=provider_config.max_concurrency,
+ http_read_timeout=provider_config.http_read_timeout,
+ http_write_timeout=provider_config.http_write_timeout,
+ http_connect_timeout=provider_config.http_connect_timeout,
+ proxy=None,
+ log_raw_sse_events=False,
+ log_api_error_tracebacks=False,
)
return LMStudioProvider(lmstudio_config, admission=immediate_admission())
@pytest.fixture
def llamacpp_provider(provider_config):
- from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_chat import create_openai_chat_provider
- llamacpp_config = ProviderConfig(
+ llamacpp_config = make_provider_config(
api_key="llamacpp",
base_url="http://localhost:8080/v1",
rate_limit=10,
rate_window=60,
+ max_concurrency=5,
+ http_read_timeout=300.0,
+ http_write_timeout=10.0,
+ http_connect_timeout=10.0,
+ proxy=None,
+ log_raw_sse_events=False,
+ log_api_error_tracebacks=False,
)
return create_openai_chat_provider(
"llamacpp",
diff --git a/tests/contracts/test_admin_provider_manifest.py b/tests/contracts/test_admin_provider_manifest.py
index 267e7d6c..0c28a24a 100644
--- a/tests/contracts/test_admin_provider_manifest.py
+++ b/tests/contracts/test_admin_provider_manifest.py
@@ -136,7 +136,7 @@ def test_vertex_project_and_location_are_admin_provider_fields() -> None:
assert project.section_id == "providers"
assert project.secret is False
assert location.settings_attr == "vertex_location"
- assert location.default == "global"
+ assert location.resolved_default() == "global"
def test_vertex_admin_status_uses_project_configuration_not_an_api_key() -> None:
diff --git a/tests/contracts/test_import_boundaries.py b/tests/contracts/test_import_boundaries.py
index dfaad318..9b4bf9ff 100644
--- a/tests/contracts/test_import_boundaries.py
+++ b/tests/contracts/test_import_boundaries.py
@@ -11,7 +11,7 @@ _PACKAGE_ROOT = _REPO_ROOT / "src" / "free_claude_code"
_PACKAGE_NAME = "free_claude_code"
ALLOWED_PACKAGE_DEPENDENCIES: dict[str, set[str]] = {
- "config": set(),
+ "config": {"core"},
"core": set(),
"application": {"config", "core"},
"messaging": {"core"},
diff --git a/tests/contracts/test_nvidia_nim_cli_matrix.py b/tests/contracts/test_nvidia_nim_cli_matrix.py
index d5d89a5b..3e93ea19 100644
--- a/tests/contracts/test_nvidia_nim_cli_matrix.py
+++ b/tests/contracts/test_nvidia_nim_cli_matrix.py
@@ -29,7 +29,10 @@ def _smoke_config(tmp_path: Path) -> SmokeConfig:
prompt="Reply with exactly: FCC_SMOKE_PONG",
claude_bin="claude",
worker_id="test-worker",
- settings=Settings.model_construct(anthropic_auth_token=""),
+ settings=Settings.model_construct(
+ proxy_auth_enabled=False,
+ proxy_auth_token="freecc",
+ ),
)
diff --git a/tests/contracts/test_packaging_contracts.py b/tests/contracts/test_packaging_contracts.py
index 910fc4d2..08526941 100644
--- a/tests/contracts/test_packaging_contracts.py
+++ b/tests/contracts/test_packaging_contracts.py
@@ -1,30 +1,7 @@
import re
-import tomllib
from pathlib import Path
-def test_root_env_example_is_the_single_template_source() -> None:
- repo_root = Path(__file__).resolve().parents[2]
- root_example = repo_root / ".env.example"
- duplicate_example = (
- repo_root / "src" / "free_claude_code" / "config" / "env.example"
- )
-
- assert root_example.is_file()
- assert not duplicate_example.exists()
-
-
-def test_root_env_example_is_packaged_for_config_template_loader() -> None:
- repo_root = Path(__file__).resolve().parents[2]
- pyproject = tomllib.loads((repo_root / "pyproject.toml").read_text("utf-8"))
-
- force_include = pyproject["tool"]["hatch"]["build"]["targets"]["wheel"][
- "force-include"
- ]
-
- assert force_include[".env.example"] == "free_claude_code/config/env.example"
-
-
def test_pyproject_first_party_packages_match_packaged_roots() -> None:
repo_root = Path(__file__).resolve().parents[2]
pyproject = (repo_root / "pyproject.toml").read_text(encoding="utf-8")
diff --git a/tests/messaging/test_transcription.py b/tests/messaging/test_transcription.py
index 2b8ebf32..b9649237 100644
--- a/tests/messaging/test_transcription.py
+++ b/tests/messaging/test_transcription.py
@@ -216,7 +216,7 @@ async def test_cancelled_transcription_keeps_ownership_until_thread_exits(
await close_task
assert service._pipeline is None
- assert service._huggingface_api_key == ""
+ assert service._huggingface_api_key is None
with pytest.raises(RuntimeError, match="closed"):
await service.transcribe(audio_path)
diff --git a/tests/providers/support.py b/tests/providers/support.py
index aa63ad6e..489c53d8 100644
--- a/tests/providers/support.py
+++ b/tests/providers/support.py
@@ -20,6 +20,36 @@ REASONING_ON = ReasoningPolicy.on()
REASONING_OFF = ReasoningPolicy.off()
+def make_provider_config(
+ api_key: str | None,
+ base_url: str,
+ rate_limit: int = 1_000_000,
+ rate_window: int = 1,
+ max_concurrency: int = 1_000,
+ http_read_timeout: float = 120.0,
+ http_write_timeout: float = 10.0,
+ http_connect_timeout: float = 10.0,
+ proxy: str | None = None,
+ log_raw_sse_events: bool = False,
+ log_api_error_tracebacks: bool = False,
+) -> ProviderConfig:
+ """Build a complete resolved config for isolated provider tests."""
+
+ return ProviderConfig(
+ api_key=api_key,
+ base_url=base_url,
+ rate_limit=rate_limit,
+ rate_window=rate_window,
+ max_concurrency=max_concurrency,
+ http_read_timeout=http_read_timeout,
+ http_write_timeout=http_write_timeout,
+ http_connect_timeout=http_connect_timeout,
+ proxy=proxy,
+ log_raw_sse_events=log_raw_sse_events,
+ log_api_error_tracebacks=log_api_error_tracebacks,
+ )
+
+
async def capture_openai_chat_wire_body(body: dict) -> dict:
"""Return the JSON body serialized by the OpenAI chat client."""
captured: list[dict] = []
diff --git a/tests/providers/test_agnes.py b/tests/providers/test_agnes.py
index 5c88648d..53e62e26 100644
--- a/tests/providers/test_agnes.py
+++ b/tests/providers/test_agnes.py
@@ -13,12 +13,12 @@ from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKEN
from free_claude_code.config.provider_catalog import AGNES_DEFAULT_BASE
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.reasoning import ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
REASONING_OFF,
REASONING_ON,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -28,7 +28,7 @@ from tests.providers.support import (
def agnes_provider() -> OpenAIChatProvider:
return profiled_provider(
"agnes",
- ProviderConfig(
+ make_provider_config(
api_key="test-agnes-key",
base_url=AGNES_DEFAULT_BASE,
rate_limit=10,
@@ -208,7 +208,7 @@ async def test_model_catalog_uses_documented_endpoint_and_auth() -> None:
):
provider = profiled_provider(
"agnes",
- ProviderConfig(
+ make_provider_config(
api_key="wire-agnes-key",
base_url=AGNES_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_azure_openai.py b/tests/providers/test_azure_openai.py
index 9fe1aa76..edbda2be 100644
--- a/tests/providers/test_azure_openai.py
+++ b/tests/providers/test_azure_openai.py
@@ -6,10 +6,13 @@ from unittest.mock import AsyncMock, patch
import pytest
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.request_factory import make_messages_request
-from tests.providers.support import immediate_admission, profiled_provider
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+ profiled_provider,
+)
AZURE_OPENAI_BASE_URL = "https://example-resource.openai.azure.com/openai/v1/"
AZURE_OPENAI_DEPLOYMENT = "gpt-5.1"
@@ -18,7 +21,7 @@ AZURE_OPENAI_DEPLOYMENT = "gpt-5.1"
def _provider() -> OpenAIChatProvider:
return profiled_provider(
"azure_openai",
- ProviderConfig(
+ make_provider_config(
api_key="azure-key",
base_url=AZURE_OPENAI_BASE_URL,
),
diff --git a/tests/providers/test_bedrock.py b/tests/providers/test_bedrock.py
index b2a5133c..d7562ce2 100644
--- a/tests/providers/test_bedrock.py
+++ b/tests/providers/test_bedrock.py
@@ -7,10 +7,13 @@ import pytest
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.provider_catalog import BEDROCK_DEFAULT_BASE
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.request_factory import make_messages_request
-from tests.providers.support import immediate_admission, profiled_provider
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+ profiled_provider,
+)
BEDROCK_MODEL = "openai.gpt-oss-120b"
@@ -18,7 +21,7 @@ BEDROCK_MODEL = "openai.gpt-oss-120b"
def _provider(base_url: str = BEDROCK_DEFAULT_BASE) -> OpenAIChatProvider:
return profiled_provider(
"bedrock",
- ProviderConfig(api_key="bedrock-key", base_url=base_url),
+ make_provider_config(api_key="bedrock-key", base_url=base_url),
admission=immediate_admission(),
)
diff --git a/tests/providers/test_cerebras.py b/tests/providers/test_cerebras.py
index c4eb9ccb..a1e61a71 100644
--- a/tests/providers/test_cerebras.py
+++ b/tests/providers/test_cerebras.py
@@ -5,11 +5,11 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from free_claude_code.config.provider_catalog import CEREBRAS_DEFAULT_BASE
-from free_claude_code.providers.base import ProviderConfig
from tests.providers.request_factory import make_messages_request
from tests.providers.support import (
REASONING_OFF,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -53,7 +53,7 @@ def make_reasoning_tool_history_request():
@pytest.fixture
def cerebras_config():
- return ProviderConfig(
+ return make_provider_config(
api_key="test_cerebras_key",
base_url=CEREBRAS_DEFAULT_BASE,
rate_limit=10,
@@ -119,7 +119,7 @@ def test_build_request_body_replays_reasoning_as_tagged_content(cerebras_provide
def test_replay_is_independent_of_current_turn_reasoning_control():
provider = profiled_provider(
"cerebras",
- ProviderConfig(
+ make_provider_config(
api_key="test_cerebras_key",
base_url=CEREBRAS_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_chutes.py b/tests/providers/test_chutes.py
index 68796f48..f14295de 100644
--- a/tests/providers/test_chutes.py
+++ b/tests/providers/test_chutes.py
@@ -10,13 +10,13 @@ from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.provider_catalog import CHUTES_DEFAULT_BASE
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.reasoning import ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.model_listing import ModelListResponseError
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
REASONING_OFF,
REASONING_ON,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -28,7 +28,7 @@ _MODEL = "Qwen/Qwen3-32B-TEE"
def chutes_provider() -> OpenAIChatProvider:
return profiled_provider(
"chutes",
- ProviderConfig(
+ make_provider_config(
api_key="test-chutes-key",
base_url=CHUTES_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_cloudflare.py b/tests/providers/test_cloudflare.py
index d97c18ec..b64c4bfe 100644
--- a/tests/providers/test_cloudflare.py
+++ b/tests/providers/test_cloudflare.py
@@ -17,7 +17,11 @@ from free_claude_code.providers.cloudflare import (
CloudflareProvider,
cloudflare_ai_base_url,
)
-from tests.providers.support import immediate_admission, reasoning_for
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+ reasoning_for,
+)
_ACCOUNT_ID = "account-123"
_BASE_URL = f"{CLOUDFLARE_AI_REST_ROOT}/accounts/{_ACCOUNT_ID}/ai/v1"
@@ -26,7 +30,7 @@ _MODEL_SEARCH_URL = f"{CLOUDFLARE_AI_REST_ROOT}/accounts/{_ACCOUNT_ID}/ai/models
@pytest.fixture
def cloudflare_config() -> ProviderConfig:
- return ProviderConfig(
+ return make_provider_config(
api_key="test-cloudflare-token",
base_url=CLOUDFLARE_AI_REST_ROOT,
rate_limit=10,
diff --git a/tests/providers/test_codestral.py b/tests/providers/test_codestral.py
index def47b56..f97b5793 100644
--- a/tests/providers/test_codestral.py
+++ b/tests/providers/test_codestral.py
@@ -5,9 +5,12 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from free_claude_code.config.provider_catalog import CODESTRAL_DEFAULT_BASE
-from free_claude_code.providers.base import ProviderConfig
from tests.providers.request_factory import make_messages_request
-from tests.providers.support import immediate_admission, profiled_provider
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+ profiled_provider,
+)
def make_request(**overrides):
@@ -16,7 +19,7 @@ def make_request(**overrides):
@pytest.fixture
def codestral_config():
- return ProviderConfig(
+ return make_provider_config(
api_key="test_codestral_key",
base_url=CODESTRAL_DEFAULT_BASE,
rate_limit=10,
@@ -63,7 +66,7 @@ def test_build_request_body_global_disable_blocks_reasoning_mapping():
"""Global disable disables reasoning replay in the converter."""
provider = profiled_provider(
"mistral_codestral",
- ProviderConfig(
+ make_provider_config(
api_key="test_codestral_key",
base_url=CODESTRAL_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_cohere.py b/tests/providers/test_cohere.py
index 1b15bed8..14dfc4e9 100644
--- a/tests/providers/test_cohere.py
+++ b/tests/providers/test_cohere.py
@@ -7,10 +7,10 @@ import pytest
from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.config.provider_catalog import COHERE_DEFAULT_BASE
-from free_claude_code.providers.base import ProviderConfig
from tests.providers.request_factory import make_messages_request
from tests.providers.support import (
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -22,7 +22,7 @@ def make_request(**overrides):
@pytest.fixture
def cohere_config():
- return ProviderConfig(
+ return make_provider_config(
api_key="test_cohere_key",
base_url=COHERE_DEFAULT_BASE,
rate_limit=10,
@@ -143,7 +143,7 @@ def test_build_request_body_preserves_replayed_reasoning_content(cohere_provider
def test_build_request_body_maps_reasoning_off_to_none():
provider = profiled_provider(
"cohere",
- ProviderConfig(
+ make_provider_config(
api_key="test_cohere_key",
base_url=COHERE_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_deepinfra.py b/tests/providers/test_deepinfra.py
index 3a61668c..b844e987 100644
--- a/tests/providers/test_deepinfra.py
+++ b/tests/providers/test_deepinfra.py
@@ -14,13 +14,13 @@ from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKEN
from free_claude_code.config.provider_catalog import DEEPINFRA_DEFAULT_BASE
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.model_listing import ModelListResponseError
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
REASONING_OFF,
REASONING_ON,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -64,7 +64,7 @@ def _catalog_model(
def deepinfra_provider() -> OpenAIChatProvider:
return profiled_provider(
"deepinfra",
- ProviderConfig(
+ make_provider_config(
api_key="test-deepinfra-key",
base_url=DEEPINFRA_DEFAULT_BASE,
rate_limit=10,
@@ -279,7 +279,7 @@ async def test_model_catalog_uses_absolute_public_url() -> None:
):
provider = profiled_provider(
"deepinfra",
- ProviderConfig(
+ make_provider_config(
api_key="wire-deepinfra-key",
base_url=DEEPINFRA_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_deepseek.py b/tests/providers/test_deepseek.py
index 68165a72..7748a926 100644
--- a/tests/providers/test_deepseek.py
+++ b/tests/providers/test_deepseek.py
@@ -16,20 +16,20 @@ from free_claude_code.core.anthropic.models import (
Tool,
)
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.deepseek import DeepSeekProvider
from tests.providers.support import (
REASONING_OFF,
REASONING_ON,
capture_openai_chat_wire_body,
immediate_admission,
+ make_provider_config,
reasoning_for,
)
@pytest.fixture
def deepseek_config():
- return ProviderConfig(
+ return make_provider_config(
api_key="test_deepseek_key",
base_url=DEEPSEEK_DEFAULT_BASE,
rate_limit=10,
@@ -258,7 +258,7 @@ def test_build_request_body_forced_tool_choice_downgrades_to_auto(
def test_build_request_body_encodes_reasoning_off():
provider = DeepSeekProvider(
- ProviderConfig(
+ make_provider_config(
api_key="k",
base_url=DEEPSEEK_DEFAULT_BASE,
rate_limit=1,
@@ -570,7 +570,7 @@ def test_tool_history_with_empty_top_level_reasoning_preserves_reasoning_state(
def test_thinking_off_strips_thinking_history():
provider = DeepSeekProvider(
- ProviderConfig(
+ make_provider_config(
api_key="k",
base_url=DEEPSEEK_DEFAULT_BASE,
rate_limit=1,
@@ -599,7 +599,7 @@ def test_thinking_off_strips_thinking_history():
def test_thinking_off_still_replays_required_tool_reasoning():
provider = DeepSeekProvider(
- ProviderConfig(
+ make_provider_config(
api_key="k",
base_url=DEEPSEEK_DEFAULT_BASE,
rate_limit=1,
@@ -700,7 +700,7 @@ def test_preflight_strips_user_image():
],
)
provider = DeepSeekProvider(
- ProviderConfig(
+ make_provider_config(
api_key="k",
base_url=DEEPSEEK_DEFAULT_BASE,
rate_limit=1,
@@ -723,7 +723,7 @@ def test_preflight_rejects_mcp_servers():
mcp_servers=[{"type": "url", "url": "https://x"}],
)
provider = DeepSeekProvider(
- ProviderConfig(
+ make_provider_config(
api_key="k",
base_url=DEEPSEEK_DEFAULT_BASE,
rate_limit=1,
@@ -742,7 +742,7 @@ def test_preflight_rejects_listed_server_tools_in_tools_list():
tools=[Tool(name="web_search", type="web_search_20250305", input_schema={})],
)
provider = DeepSeekProvider(
- ProviderConfig(
+ make_provider_config(
api_key="k",
base_url=DEEPSEEK_DEFAULT_BASE,
rate_limit=1,
@@ -779,7 +779,7 @@ def test_preflight_rejects_server_tool_result_blocks():
}
)
provider = DeepSeekProvider(
- ProviderConfig(
+ make_provider_config(
api_key="k",
base_url=DEEPSEEK_DEFAULT_BASE,
rate_limit=1,
diff --git a/tests/providers/test_execution_failure_boundary.py b/tests/providers/test_execution_failure_boundary.py
index 4746efa7..ccc4f9a9 100644
--- a/tests/providers/test_execution_failure_boundary.py
+++ b/tests/providers/test_execution_failure_boundary.py
@@ -10,11 +10,13 @@ from free_claude_code.config.nim import NimSettings
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
from free_claude_code.core.async_iterators import AsyncCloseable
from free_claude_code.core.failures import ExecutionFailure, FailureKind
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.http import close_provider_stream
from free_claude_code.providers.nvidia_nim import NvidiaNimProvider
from tests.providers.request_factory import make_messages_request
-from tests.providers.support import immediate_admission
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+)
class _FailingStream:
@@ -53,7 +55,7 @@ def _chunk(*, content: str | None = None, finish_reason: str | None = None) -> o
def _provider() -> NvidiaNimProvider:
return NvidiaNimProvider(
- ProviderConfig(
+ make_provider_config(
api_key="test_key",
base_url="https://test.api.nvidia.com/v1",
rate_limit=10,
diff --git a/tests/providers/test_featherless.py b/tests/providers/test_featherless.py
index dd6c8123..ce10a395 100644
--- a/tests/providers/test_featherless.py
+++ b/tests/providers/test_featherless.py
@@ -13,13 +13,13 @@ from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKEN
from free_claude_code.config.provider_catalog import FEATHERLESS_DEFAULT_BASE
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.reasoning import ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.model_listing import ModelListResponseError
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
REASONING_OFF,
REASONING_ON,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -31,7 +31,7 @@ _MODEL = "Qwen/Qwen3-32B"
def featherless_provider() -> OpenAIChatProvider:
return profiled_provider(
"featherless",
- ProviderConfig(
+ make_provider_config(
api_key="test-featherless-key",
base_url=FEATHERLESS_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_fireworks.py b/tests/providers/test_fireworks.py
index 71887fd0..1229e8db 100644
--- a/tests/providers/test_fireworks.py
+++ b/tests/providers/test_fireworks.py
@@ -8,11 +8,11 @@ from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.config.provider_catalog import FIREWORKS_DEFAULT_BASE
from free_claude_code.core.anthropic.models import Message, MessagesRequest
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
REASONING_OFF,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -22,7 +22,7 @@ from tests.providers.support import (
def fireworks_provider():
return profiled_provider(
"fireworks",
- ProviderConfig(
+ make_provider_config(
api_key="test_fireworks_key",
base_url=FIREWORKS_DEFAULT_BASE,
rate_limit=10,
@@ -78,7 +78,7 @@ def test_build_request_body_default_max_tokens(fireworks_provider):
def test_replay_is_independent_of_current_turn_reasoning_control():
provider = profiled_provider(
"fireworks",
- ProviderConfig(
+ make_provider_config(
api_key="k",
base_url=FIREWORKS_DEFAULT_BASE,
rate_limit=1,
diff --git a/tests/providers/test_gemini.py b/tests/providers/test_gemini.py
index 2cf64b90..2cc88ea5 100644
--- a/tests/providers/test_gemini.py
+++ b/tests/providers/test_gemini.py
@@ -7,13 +7,16 @@ import pytest
from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.config.provider_catalog import GEMINI_DEFAULT_BASE
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.gemini import GeminiProvider
from free_claude_code.providers.google_openai import (
GOOGLE_SKIP_THOUGHT_SIGNATURE_VALIDATOR,
)
from tests.providers.request_factory import make_messages_request
-from tests.providers.support import immediate_admission, reasoning_for
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+ reasoning_for,
+)
def make_request(**overrides):
@@ -41,7 +44,7 @@ def _google_thinking_config(wire: dict) -> dict | None:
@pytest.fixture
def gemini_config():
- return ProviderConfig(
+ return make_provider_config(
api_key="test_gemini_key",
base_url=GEMINI_DEFAULT_BASE,
rate_limit=10,
@@ -115,7 +118,7 @@ def test_build_request_body_sdk_wire_json_has_literal_extra_body(gemini_provider
def test_build_request_body_reasoning_off_sets_reasoning_none():
"""When thinking is off, Gemini uses reasoning_effort none (Gemini 2.5 convention)."""
provider = GeminiProvider(
- ProviderConfig(
+ make_provider_config(
api_key="test_gemini_key",
base_url=GEMINI_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_github_models.py b/tests/providers/test_github_models.py
index ea3e5ad6..3e22f76d 100644
--- a/tests/providers/test_github_models.py
+++ b/tests/providers/test_github_models.py
@@ -16,12 +16,16 @@ from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.github_models import GitHubModelsProvider
from free_claude_code.providers.github_models.client import GITHUB_MODELS_CATALOG_URL
from free_claude_code.providers.model_listing import ModelListResponseError
-from tests.providers.support import REASONING_ON, immediate_admission
+from tests.providers.support import (
+ REASONING_ON,
+ immediate_admission,
+ make_provider_config,
+)
@pytest.fixture
def github_models_config() -> ProviderConfig:
- return ProviderConfig(
+ return make_provider_config(
api_key="test-github-models-token",
base_url=GITHUB_MODELS_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_groq.py b/tests/providers/test_groq.py
index 7d7e9b99..e85ebe2a 100644
--- a/tests/providers/test_groq.py
+++ b/tests/providers/test_groq.py
@@ -5,10 +5,12 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from free_claude_code.config.provider_catalog import GROQ_DEFAULT_BASE
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.groq import GroqProvider
from tests.providers.request_factory import make_messages_request
-from tests.providers.support import immediate_admission
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+)
def make_request(**overrides):
@@ -17,7 +19,7 @@ def make_request(**overrides):
@pytest.fixture
def groq_config():
- return ProviderConfig(
+ return make_provider_config(
api_key="test_groq_key",
base_url=GROQ_DEFAULT_BASE,
rate_limit=10,
@@ -107,7 +109,7 @@ def test_build_request_body_replays_reasoning_as_tagged_content(groq_provider):
def test_build_request_body_global_disable_blocks_reasoning_mapping():
provider = GroqProvider(
- ProviderConfig(
+ make_provider_config(
api_key="test_groq_key",
base_url=GROQ_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_groq_reasoning.py b/tests/providers/test_groq_reasoning.py
index 6d0d6397..6e5173d4 100644
--- a/tests/providers/test_groq_reasoning.py
+++ b/tests/providers/test_groq_reasoning.py
@@ -11,14 +11,17 @@ import pytest
from free_claude_code.config.provider_catalog import GROQ_DEFAULT_BASE
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.groq import GroqProvider
from free_claude_code.providers.groq.client import (
_parse_reasoning_vocabulary,
_rewrite_reasoning_effort,
)
from tests.providers.request_factory import make_messages_request
-from tests.providers.support import capture_openai_chat_wire_body, immediate_admission
+from tests.providers.support import (
+ capture_openai_chat_wire_body,
+ immediate_admission,
+ make_provider_config,
+)
_MODEL = "opaque-model-a"
_ISSUE_MESSAGE = "`reasoning_effort` must be one of `none` or `default`"
@@ -41,7 +44,7 @@ class _BadRequest(Exception):
def _provider(*, max_attempts: int = 5) -> GroqProvider:
return GroqProvider(
- ProviderConfig(
+ make_provider_config(
api_key="test_groq_key",
base_url=GROQ_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_huggingface.py b/tests/providers/test_huggingface.py
index 8987d51c..e8724366 100644
--- a/tests/providers/test_huggingface.py
+++ b/tests/providers/test_huggingface.py
@@ -8,9 +8,12 @@ import pytest
from free_claude_code.config.provider_catalog import HUGGINGFACE_DEFAULT_BASE
from free_claude_code.core.anthropic import ReasoningReplayMode
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from tests.providers.request_factory import make_messages_request
-from tests.providers.support import immediate_admission, profiled_provider
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+ profiled_provider,
+)
def make_request(**overrides):
@@ -19,7 +22,7 @@ def make_request(**overrides):
@pytest.fixture
def huggingface_config():
- return ProviderConfig(
+ return make_provider_config(
api_key="test_hf_key",
base_url=HUGGINGFACE_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_kilo.py b/tests/providers/test_kilo.py
index fb6e9c58..f4ea054d 100644
--- a/tests/providers/test_kilo.py
+++ b/tests/providers/test_kilo.py
@@ -16,19 +16,19 @@ from free_claude_code.core.anthropic.stream_contracts import (
thinking_content,
)
from free_claude_code.core.reasoning import ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.kilo import KiloProvider
from free_claude_code.providers.model_listing import ModelListResponseError
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
immediate_admission,
+ make_provider_config,
reasoning_for,
)
@pytest.fixture
def kilo_config():
- return ProviderConfig(
+ return make_provider_config(
api_key="test_kilo_key",
base_url=KILO_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_kimi.py b/tests/providers/test_kimi.py
index 9e1b44d4..878c3443 100644
--- a/tests/providers/test_kimi.py
+++ b/tests/providers/test_kimi.py
@@ -10,10 +10,10 @@ from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.config.provider_catalog import KIMI_DEFAULT_BASE
from free_claude_code.core.anthropic.models import Message, MessagesRequest
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -23,7 +23,7 @@ from tests.providers.support import (
def kimi_provider():
return profiled_provider(
"kimi",
- ProviderConfig(
+ make_provider_config(
api_key="test_kimi_key",
base_url=KIMI_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_kimi_code.py b/tests/providers/test_kimi_code.py
index e84dda1b..fd881961 100644
--- a/tests/providers/test_kimi_code.py
+++ b/tests/providers/test_kimi_code.py
@@ -9,10 +9,10 @@ from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.provider_catalog import KIMI_CODE_DEFAULT_BASE
from free_claude_code.core.anthropic.models import MessagesRequest
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -31,7 +31,7 @@ def _request(**overrides) -> MessagesRequest:
def kimi_code_provider() -> OpenAIChatProvider:
return profiled_provider(
"kimi_code",
- ProviderConfig(
+ make_provider_config(
api_key="test-subscription-key",
base_url=KIMI_CODE_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_llamacpp.py b/tests/providers/test_llamacpp.py
index 977ce58c..c432d6b4 100644
--- a/tests/providers/test_llamacpp.py
+++ b/tests/providers/test_llamacpp.py
@@ -6,12 +6,12 @@ import pytest
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.request_factory import make_messages_request
from tests.providers.support import (
REASONING_OFF,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -23,7 +23,7 @@ LLAMACPP_MODEL = "llamacpp-community/qwen2.5-7b-instruct"
def provider() -> OpenAIChatProvider:
return profiled_provider(
"llamacpp",
- ProviderConfig(api_key="llamacpp", base_url="http://localhost:8080/v1"),
+ make_provider_config(api_key="llamacpp", base_url="http://localhost:8080/v1"),
admission=immediate_admission(),
)
@@ -43,7 +43,7 @@ def test_init_normalizes_openai_base_url(configured: str, expected: str) -> None
) as openai_client:
provider = profiled_provider(
"llamacpp",
- ProviderConfig(api_key="llamacpp", base_url=configured),
+ make_provider_config(api_key="llamacpp", base_url=configured),
admission=immediate_admission(),
)
@@ -52,7 +52,7 @@ def test_init_normalizes_openai_base_url(configured: str, expected: str) -> None
def test_init_uses_openai_chat_client() -> None:
- config = ProviderConfig(
+ config = make_provider_config(
api_key="llamacpp",
base_url="http://localhost:8080/v1/",
http_read_timeout=600.0,
diff --git a/tests/providers/test_lmstudio.py b/tests/providers/test_lmstudio.py
index f162c590..359e7844 100644
--- a/tests/providers/test_lmstudio.py
+++ b/tests/providers/test_lmstudio.py
@@ -9,13 +9,13 @@ from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.config.provider_catalog import LMSTUDIO_DEFAULT_BASE
from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.lmstudio import LMStudioProvider
from tests.providers.request_factory import make_messages_request
from tests.providers.support import (
REASONING_OFF,
REASONING_ON,
immediate_admission,
+ make_provider_config,
)
@@ -25,7 +25,7 @@ def make_request(**overrides):
@pytest.fixture
def lmstudio_config():
- return ProviderConfig(
+ return make_provider_config(
api_key="lm-studio",
base_url=LMSTUDIO_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_minimax.py b/tests/providers/test_minimax.py
index 9516f983..f2c1b03c 100644
--- a/tests/providers/test_minimax.py
+++ b/tests/providers/test_minimax.py
@@ -14,11 +14,11 @@ from free_claude_code.core.anthropic.stream_contracts import (
text_content,
thinking_content,
)
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
REASONING_OFF,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -44,7 +44,7 @@ class AsyncStream:
def minimax_provider():
return profiled_provider(
"minimax",
- ProviderConfig(
+ make_provider_config(
api_key="test-minimax-key",
base_url=MINIMAX_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_mistral.py b/tests/providers/test_mistral.py
index 65fe0947..430104b6 100644
--- a/tests/providers/test_mistral.py
+++ b/tests/providers/test_mistral.py
@@ -9,12 +9,12 @@ from httpx import Request, Response
from free_claude_code.config.provider_catalog import MISTRAL_DEFAULT_BASE
from free_claude_code.core.failures import ExecutionFailure
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.mistral import MistralProvider
from tests.providers.request_factory import make_messages_request
from tests.providers.support import (
REASONING_OFF,
immediate_admission,
+ make_provider_config,
reasoning_for,
)
@@ -25,7 +25,7 @@ def make_request(**overrides):
@pytest.fixture
def mistral_config():
- return ProviderConfig(
+ return make_provider_config(
api_key="test_mistral_key",
base_url=MISTRAL_DEFAULT_BASE,
rate_limit=10,
@@ -138,7 +138,7 @@ def test_build_request_body_preserves_tools_tool_choice_and_params(mistral_provi
def test_build_request_body_reasoning_off_uses_native_none():
provider = MistralProvider(
- ProviderConfig(
+ make_provider_config(
api_key="test_mistral_key",
base_url=MISTRAL_DEFAULT_BASE,
rate_limit=10,
@@ -155,7 +155,7 @@ def test_build_request_body_reasoning_off_uses_native_none():
def test_reasoning_off_keeps_replay_separate_from_new_turn_compute():
provider = MistralProvider(
- ProviderConfig(
+ make_provider_config(
api_key="test_mistral_key",
base_url=MISTRAL_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_model_discovery.py b/tests/providers/test_model_discovery.py
index 11a5fe63..7c87cb58 100644
--- a/tests/providers/test_model_discovery.py
+++ b/tests/providers/test_model_discovery.py
@@ -16,7 +16,7 @@ from free_claude_code.config.provider_catalog import (
)
from free_claude_code.config.settings import Settings
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
-from free_claude_code.providers.base import BaseProvider, ProviderConfig
+from free_claude_code.providers.base import BaseProvider
from free_claude_code.providers.deepseek import DeepSeekProvider
from free_claude_code.providers.model_listing import ModelListResponseError
from free_claude_code.providers.nvidia_nim import NvidiaNimProvider
@@ -25,7 +25,11 @@ from free_claude_code.providers.openai_chat import OpenAIChatProvider
from free_claude_code.providers.runtime import ProviderRuntime
from free_claude_code.providers.runtime.model_cache import ProviderModelCache
from free_claude_code.runtime.provider_manager import ProviderRuntimeManager
-from tests.providers.support import immediate_admission, profiled_provider
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+ profiled_provider,
+)
def _settings(
@@ -82,7 +86,7 @@ def test_provider_catalog_contract_is_metadata_only() -> None:
@pytest.mark.asyncio
async def test_nim_lists_openai_compatible_model_infos() -> None:
- config = ProviderConfig(api_key="test-key", base_url=NVIDIA_NIM_DEFAULT_BASE)
+ config = make_provider_config(api_key="test-key", base_url=NVIDIA_NIM_DEFAULT_BASE)
with patch("free_claude_code.providers.openai_chat.provider.AsyncOpenAI"):
provider = NvidiaNimProvider(
config, nim_settings=NimSettings(), admission=immediate_admission()
@@ -103,12 +107,14 @@ async def test_nim_lists_openai_compatible_model_infos() -> None:
[
profiled_provider(
"llamacpp",
- ProviderConfig(api_key="llamacpp", base_url="http://localhost:8080/v1"),
+ make_provider_config(
+ api_key="llamacpp", base_url="http://localhost:8080/v1"
+ ),
admission=immediate_admission(),
),
profiled_provider(
"ollama",
- ProviderConfig(api_key="ollama", base_url="http://localhost:11434"),
+ make_provider_config(api_key="ollama", base_url="http://localhost:11434"),
admission=immediate_admission(),
),
],
@@ -130,7 +136,7 @@ async def test_local_openai_chat_providers_list_model_infos(
@pytest.mark.asyncio
async def test_deepseek_lists_models_from_root_endpoint() -> None:
provider = DeepSeekProvider(
- ProviderConfig(api_key="deepseek-key", base_url=DEEPSEEK_DEFAULT_BASE),
+ make_provider_config(api_key="deepseek-key", base_url=DEEPSEEK_DEFAULT_BASE),
admission=immediate_admission(),
)
with patch.object(
@@ -148,7 +154,7 @@ async def test_deepseek_lists_models_from_root_endpoint() -> None:
async def test_wafer_lists_models_from_default_models_endpoint() -> None:
provider = profiled_provider(
"wafer",
- ProviderConfig(api_key="wafer-key", base_url=WAFER_DEFAULT_BASE),
+ make_provider_config(api_key="wafer-key", base_url=WAFER_DEFAULT_BASE),
admission=immediate_admission(),
)
with patch.object(
@@ -165,7 +171,9 @@ async def test_wafer_lists_models_from_default_models_endpoint() -> None:
@pytest.mark.asyncio
async def test_openrouter_lists_only_tool_capable_models() -> None:
provider = OpenRouterProvider(
- ProviderConfig(api_key="open-router-key", base_url=OPENROUTER_DEFAULT_BASE),
+ make_provider_config(
+ api_key="open-router-key", base_url=OPENROUTER_DEFAULT_BASE
+ ),
admission=immediate_admission(),
)
with patch.object(
@@ -203,7 +211,9 @@ async def test_openrouter_lists_only_tool_capable_models() -> None:
@pytest.mark.asyncio
async def test_openrouter_lists_tool_metadata_with_thinking_support() -> None:
provider = OpenRouterProvider(
- ProviderConfig(api_key="open-router-key", base_url=OPENROUTER_DEFAULT_BASE),
+ make_provider_config(
+ api_key="open-router-key", base_url=OPENROUTER_DEFAULT_BASE
+ ),
admission=immediate_admission(),
)
with patch.object(
@@ -244,7 +254,9 @@ async def test_openrouter_lists_tool_metadata_with_thinking_support() -> None:
@pytest.mark.asyncio
async def test_openrouter_lists_empty_set_when_no_tool_capable_models() -> None:
provider = OpenRouterProvider(
- ProviderConfig(api_key="open-router-key", base_url=OPENROUTER_DEFAULT_BASE),
+ make_provider_config(
+ api_key="open-router-key", base_url=OPENROUTER_DEFAULT_BASE
+ ),
admission=immediate_admission(),
)
with patch.object(
@@ -264,7 +276,9 @@ async def test_openrouter_lists_empty_set_when_no_tool_capable_models() -> None:
@pytest.mark.asyncio
async def test_openrouter_model_metadata_rejects_malformed_ids() -> None:
provider = OpenRouterProvider(
- ProviderConfig(api_key="open-router-key", base_url=OPENROUTER_DEFAULT_BASE),
+ make_provider_config(
+ api_key="open-router-key", base_url=OPENROUTER_DEFAULT_BASE
+ ),
admission=immediate_admission(),
)
with (
@@ -285,7 +299,7 @@ async def test_openrouter_model_metadata_rejects_malformed_ids() -> None:
async def test_model_listing_rejects_malformed_payload() -> None:
provider = profiled_provider(
"llamacpp",
- ProviderConfig(api_key="llamacpp", base_url="http://localhost:8080/v1"),
+ make_provider_config(api_key="llamacpp", base_url="http://localhost:8080/v1"),
admission=immediate_admission(),
)
with (
@@ -304,7 +318,7 @@ async def test_model_listing_rejects_malformed_payload() -> None:
async def test_model_listing_propagates_upstream_errors() -> None:
provider = profiled_provider(
"llamacpp",
- ProviderConfig(api_key="llamacpp", base_url="http://localhost:8080/v1"),
+ make_provider_config(api_key="llamacpp", base_url="http://localhost:8080/v1"),
admission=immediate_admission(),
)
with (
@@ -329,7 +343,7 @@ class FakeProvider(BaseProvider):
peer_started: asyncio.Event | None = None,
):
super().__init__(
- ProviderConfig(api_key="test", base_url="https://test.invalid")
+ make_provider_config(api_key="test", base_url="https://test.invalid")
)
self._model_infos = model_infos
self._error = error
diff --git a/tests/providers/test_nebius.py b/tests/providers/test_nebius.py
index c959bc03..447162d8 100644
--- a/tests/providers/test_nebius.py
+++ b/tests/providers/test_nebius.py
@@ -11,13 +11,13 @@ from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.provider_catalog import NEBIUS_DEFAULT_BASE
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.model_listing import ModelListResponseError
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
REASONING_OFF,
REASONING_ON,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -29,7 +29,7 @@ _MODEL = "Qwen/Qwen3-30B-A3B"
def nebius_provider() -> OpenAIChatProvider:
return profiled_provider(
"nebius",
- ProviderConfig(
+ make_provider_config(
api_key="test-nebius-key",
base_url=NEBIUS_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_novita.py b/tests/providers/test_novita.py
index 5de6fcbc..3909fc32 100644
--- a/tests/providers/test_novita.py
+++ b/tests/providers/test_novita.py
@@ -9,12 +9,12 @@ from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKEN
from free_claude_code.config.provider_catalog import NOVITA_DEFAULT_BASE
from free_claude_code.core.anthropic.models import Message, MessagesRequest
from free_claude_code.core.reasoning import ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
REASONING_OFF,
REASONING_ON,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -24,7 +24,7 @@ from tests.providers.support import (
def novita_provider():
return profiled_provider(
"novita",
- ProviderConfig(
+ make_provider_config(
api_key="test_novita_key",
base_url=NOVITA_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_nvidia_nim.py b/tests/providers/test_nvidia_nim.py
index b5e3fda2..6259505b 100644
--- a/tests/providers/test_nvidia_nim.py
+++ b/tests/providers/test_nvidia_nim.py
@@ -20,6 +20,7 @@ from tests.providers.support import (
REASONING_OFF,
REASONING_ON,
immediate_admission,
+ make_provider_config,
reasoning_for,
)
@@ -146,9 +147,8 @@ async def test_init(provider_config):
@pytest.mark.asyncio
async def test_init_uses_configurable_timeouts():
"""Test that provider passes configurable read/write/connect timeouts to client."""
- from free_claude_code.providers.base import ProviderConfig
- config = ProviderConfig(
+ config = make_provider_config(
api_key="test_key",
base_url="https://test.api.nvidia.com/v1",
http_read_timeout=600.0,
diff --git a/tests/providers/test_nvidia_nim_degraded_retry.py b/tests/providers/test_nvidia_nim_degraded_retry.py
index 1763608b..4655c432 100644
--- a/tests/providers/test_nvidia_nim_degraded_retry.py
+++ b/tests/providers/test_nvidia_nim_degraded_retry.py
@@ -20,13 +20,14 @@ from free_claude_code.providers.failure_policy import (
from free_claude_code.providers.nvidia_nim import NvidiaNimProvider
from free_claude_code.providers.open_router import OpenRouterProvider
from tests.providers.request_factory import make_messages_request
+from tests.providers.support import make_provider_config
_FUNCTION_ID = "87ea0ddc-cff1-4bca-bf8b-3bd98a35ddd0"
_DEGRADED_DETAIL = f"Function id '{_FUNCTION_ID}': DEGRADED function cannot be invoked"
def _config(base_url: str) -> ProviderConfig:
- return ProviderConfig(
+ return make_provider_config(
api_key="test_key",
base_url=base_url,
rate_limit=1_000_000,
diff --git a/tests/providers/test_ollama.py b/tests/providers/test_ollama.py
index 5268fe93..1fa5a0b2 100644
--- a/tests/providers/test_ollama.py
+++ b/tests/providers/test_ollama.py
@@ -12,12 +12,12 @@ from free_claude_code.core.anthropic.stream_contracts import (
parse_sse_text,
thinking_content,
)
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.request_factory import make_messages_request
from tests.providers.support import (
REASONING_OFF,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -29,7 +29,7 @@ OLLAMA_CLOUD_MODEL = "qwen3-coder:480b"
def _provider(base_url: str = OLLAMA_DEFAULT_BASE) -> OpenAIChatProvider:
return profiled_provider(
"ollama",
- ProviderConfig(api_key="ollama", base_url=base_url),
+ make_provider_config(api_key="ollama", base_url=base_url),
admission=immediate_admission(),
)
@@ -37,7 +37,7 @@ def _provider(base_url: str = OLLAMA_DEFAULT_BASE) -> OpenAIChatProvider:
def _cloud_provider() -> OpenAIChatProvider:
return profiled_provider(
"ollama_cloud",
- ProviderConfig(
+ make_provider_config(
api_key="ollama-cloud-key",
base_url=OLLAMA_CLOUD_DEFAULT_BASE,
),
diff --git a/tests/providers/test_open_router.py b/tests/providers/test_open_router.py
index dd612ac1..1c9c5338 100644
--- a/tests/providers/test_open_router.py
+++ b/tests/providers/test_open_router.py
@@ -14,13 +14,13 @@ from free_claude_code.core.anthropic.stream_contracts import (
text_content,
thinking_content,
)
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.open_router import OpenRouterProvider
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.request_factory import make_messages_request
from tests.providers.support import (
REASONING_OFF,
immediate_admission,
+ make_provider_config,
reasoning_for,
)
@@ -48,7 +48,7 @@ def make_request(**overrides):
@pytest.fixture
def open_router_provider():
return OpenRouterProvider(
- ProviderConfig(
+ make_provider_config(
api_key="test_openrouter_key",
base_url="https://openrouter.ai/api/v1",
rate_limit=10,
diff --git a/tests/providers/test_openai_chat_output_cap.py b/tests/providers/test_openai_chat_output_cap.py
index e03d8235..6127d966 100644
--- a/tests/providers/test_openai_chat_output_cap.py
+++ b/tests/providers/test_openai_chat_output_cap.py
@@ -10,14 +10,16 @@ from unittest.mock import AsyncMock, patch
import pytest
from free_claude_code.config.provider_catalog import GROQ_DEFAULT_BASE
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.groq import GroqProvider
from free_claude_code.providers.openai_chat.output_cap import (
clamp_output_tokens,
parse_output_token_cap,
)
from tests.providers.request_factory import make_messages_request
-from tests.providers.support import immediate_admission
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+)
class _BadRequest(Exception):
@@ -115,7 +117,7 @@ def test_clamp_ignores_bool_values():
@pytest.fixture
def groq_provider():
return GroqProvider(
- ProviderConfig(
+ make_provider_config(
api_key="test_groq_key",
base_url=GROQ_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_openai_chat_usage.py b/tests/providers/test_openai_chat_usage.py
index 1b5a9f14..98a29d78 100644
--- a/tests/providers/test_openai_chat_usage.py
+++ b/tests/providers/test_openai_chat_usage.py
@@ -12,7 +12,6 @@ from free_claude_code.core.anthropic import ReasoningReplayMode
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_chat import (
OpenAIChatProfile,
OpenAIChatProvider,
@@ -26,13 +25,16 @@ from free_claude_code.providers.openai_chat.usage import (
usage_int,
)
from tests.providers.request_factory import make_messages_request
-from tests.providers.support import immediate_admission
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+)
class _UsageTestProvider(OpenAIChatProvider):
def __init__(self):
super().__init__(
- ProviderConfig(
+ make_provider_config(
api_key="test_key",
base_url="https://provider.example/v1",
rate_limit=100,
diff --git a/tests/providers/test_openai_codex_provider.py b/tests/providers/test_openai_codex_provider.py
index 30731434..4e65b90c 100644
--- a/tests/providers/test_openai_codex_provider.py
+++ b/tests/providers/test_openai_codex_provider.py
@@ -22,6 +22,7 @@ from free_claude_code.providers.openai_codex.auth import (
OpenAIAuthManager,
)
from free_claude_code.providers.openai_codex.provider import OpenAICodexProvider
+from tests.providers.support import make_provider_config
class _FakeAuth(OpenAIAuthManager):
@@ -42,7 +43,7 @@ class _FakeAuth(OpenAIAuthManager):
def _config() -> ProviderConfig:
- return ProviderConfig(
+ return make_provider_config(
api_key="",
base_url="https://chatgpt.com/backend-api/codex",
rate_limit=100,
diff --git a/tests/providers/test_openai_compat_5xx_retry.py b/tests/providers/test_openai_compat_5xx_retry.py
index 0edb621e..0541ff54 100644
--- a/tests/providers/test_openai_compat_5xx_retry.py
+++ b/tests/providers/test_openai_compat_5xx_retry.py
@@ -9,10 +9,12 @@ from httpx import Request, Response
from free_claude_code.config.nim import NimSettings
from free_claude_code.core.failures import ExecutionFailure
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.nvidia_nim import NvidiaNimProvider
from tests.providers.request_factory import make_messages_request
-from tests.providers.support import immediate_admission
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+)
def _internal_5xx(code: int) -> openai.InternalServerError:
@@ -34,7 +36,7 @@ def _connection_error(message: str = "connect failed") -> openai.APIConnectionEr
@pytest.mark.parametrize("status_code", [500, 502, 503, 504])
@pytest.mark.asyncio
async def test_nim_stream_retries_on_openai_5xx_then_streams(status_code):
- config = ProviderConfig(
+ config = make_provider_config(
api_key="test_key",
base_url="https://test.api.nvidia.com/v1",
rate_limit=100,
@@ -78,7 +80,7 @@ async def test_nim_stream_retries_on_openai_5xx_then_streams(status_code):
@pytest.mark.asyncio
async def test_nim_stream_retries_on_pre_stream_connection_error_then_streams():
- config = ProviderConfig(
+ config = make_provider_config(
api_key="test_key",
base_url="https://test.api.nvidia.com/v1",
rate_limit=100,
@@ -122,7 +124,7 @@ async def test_nim_stream_retries_on_pre_stream_connection_error_then_streams():
@pytest.mark.asyncio
async def test_nim_stream_connection_error_exhausted_emits_cause_chain():
- config = ProviderConfig(
+ config = make_provider_config(
api_key="test_key",
base_url="https://test.api.nvidia.com/v1",
rate_limit=100,
@@ -177,7 +179,7 @@ async def test_nim_stream_openai_5xx_exhausted_emits_user_message(
status_code,
expect_substr,
):
- config = ProviderConfig(
+ config = make_provider_config(
api_key="test_key",
base_url="https://test.api.nvidia.com/v1",
rate_limit=100,
diff --git a/tests/providers/test_opencode.py b/tests/providers/test_opencode.py
index d6086cc8..dd4b4a9f 100644
--- a/tests/providers/test_opencode.py
+++ b/tests/providers/test_opencode.py
@@ -3,10 +3,10 @@
import pytest
from free_claude_code.core.anthropic.models import MessagesRequest
-from free_claude_code.providers.base import ProviderConfig
from tests.providers.support import (
capture_openai_chat_wire_body,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -18,7 +18,7 @@ def test_build_request_body_replays_tool_reasoning_natively(
) -> None:
provider = profiled_provider(
provider_id,
- ProviderConfig(
+ make_provider_config(
api_key="test_opencode_key",
base_url="https://example.invalid/v1",
rate_limit=1,
@@ -82,7 +82,7 @@ async def test_tool_only_history_sends_empty_reasoning_content_on_wire(
) -> None:
provider = profiled_provider(
provider_id,
- ProviderConfig(
+ make_provider_config(
api_key="test_opencode_key",
base_url="https://example.invalid/v1",
rate_limit=1,
diff --git a/tests/providers/test_preflight_contract.py b/tests/providers/test_preflight_contract.py
index dd1e2601..cfe4ae68 100644
--- a/tests/providers/test_preflight_contract.py
+++ b/tests/providers/test_preflight_contract.py
@@ -7,8 +7,9 @@ import pytest
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.core.anthropic.models import Message, MessagesRequest
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
-from free_claude_code.providers.base import BaseProvider, ProviderConfig
+from free_claude_code.providers.base import BaseProvider
from free_claude_code.providers.openai_chat import OpenAIChatProvider
+from tests.providers.support import make_provider_config
class RecordingOpenAIProvider(OpenAIChatProvider):
@@ -48,7 +49,7 @@ class ProviderWithoutPreflight(BaseProvider):
def test_provider_base_requires_an_explicit_preflight_implementation() -> None:
with pytest.raises(TypeError, match="preflight_stream"):
ProviderWithoutPreflight(
- ProviderConfig(api_key="test", base_url="https://test.invalid")
+ make_provider_config(api_key="test", base_url="https://test.invalid")
)
diff --git a/tests/providers/test_provider_runtime.py b/tests/providers/test_provider_runtime.py
index b3087af9..6c6b570f 100644
--- a/tests/providers/test_provider_runtime.py
+++ b/tests/providers/test_provider_runtime.py
@@ -101,59 +101,59 @@ def _make_settings(**overrides):
mock.llamacpp_base_url = "http://localhost:8080/v1"
mock.ollama_base_url = "http://localhost:11434"
mock.ollama_api_key = "test_ollama_cloud_key"
- mock.nvidia_nim_proxy = ""
- mock.open_router_proxy = ""
- mock.lmstudio_proxy = ""
- mock.llamacpp_proxy = ""
- mock.mistral_proxy = ""
- mock.codestral_proxy = ""
- mock.kimi_proxy = ""
+ mock.nvidia_nim_proxy = None
+ mock.open_router_proxy = None
+ mock.lmstudio_proxy = None
+ mock.llamacpp_proxy = None
+ mock.mistral_proxy = None
+ mock.codestral_proxy = None
+ mock.kimi_proxy = None
mock.kimi_api_key = "test_kimi_key"
- mock.kimi_code_proxy = ""
+ mock.kimi_code_proxy = None
mock.kimi_code_api_key = "test_kimi_code_key"
- mock.wafer_proxy = ""
- mock.minimax_proxy = ""
- mock.opencode_zen_proxy = ""
- mock.opencode_go_proxy = ""
- mock.vercel_ai_gateway_proxy = ""
- mock.bedrock_proxy = ""
- mock.huggingface_proxy = ""
- mock.cohere_proxy = ""
- mock.github_models_proxy = ""
- mock.zai_proxy = ""
- mock.tokenrouter_proxy = ""
- mock.nararoute_proxy = ""
- mock.agnes_proxy = ""
- mock.zenmux_proxy = ""
- mock.fireworks_proxy = ""
+ mock.wafer_proxy = None
+ mock.minimax_proxy = None
+ mock.opencode_zen_proxy = None
+ mock.opencode_go_proxy = None
+ mock.vercel_ai_gateway_proxy = None
+ mock.bedrock_proxy = None
+ mock.huggingface_proxy = None
+ mock.cohere_proxy = None
+ mock.github_models_proxy = None
+ mock.zai_proxy = None
+ mock.tokenrouter_proxy = None
+ mock.nararoute_proxy = None
+ mock.agnes_proxy = None
+ mock.zenmux_proxy = None
+ mock.fireworks_proxy = None
mock.fireworks_api_key = "test_fireworks_key"
- mock.novita_proxy = ""
+ mock.novita_proxy = None
mock.novita_api_key = "test_novita_key"
mock.cloudflare_api_token = "test_cloudflare_token"
mock.cloudflare_account_id = "test_cloudflare_account"
- mock.cloudflare_proxy = ""
+ mock.cloudflare_proxy = None
mock.gemini_api_key = ""
- mock.gemini_proxy = ""
+ mock.gemini_proxy = None
mock.vertex_project_id = "test-vertex-project"
mock.vertex_location = "global"
- mock.vertex_proxy = ""
+ mock.vertex_proxy = None
mock.groq_api_key = ""
- mock.groq_proxy = ""
+ mock.groq_proxy = None
mock.cerebras_api_key = ""
- mock.cerebras_proxy = ""
- mock.ollama_cloud_proxy = ""
+ mock.cerebras_proxy = None
+ mock.ollama_cloud_proxy = None
mock.kilo_api_key = "test_kilo_key"
- mock.kilo_proxy = ""
- mock.openai_proxy = ""
- mock.xai_proxy = ""
- mock.qwencloud_proxy = ""
- mock.together_proxy = ""
- mock.deepinfra_proxy = ""
- mock.siliconflow_proxy = ""
- mock.nebius_proxy = ""
- mock.chutes_proxy = ""
- mock.featherless_proxy = ""
- mock.azure_openai_proxy = ""
+ mock.kilo_proxy = None
+ mock.openai_proxy = None
+ mock.xai_proxy = None
+ mock.qwencloud_proxy = None
+ mock.together_proxy = None
+ mock.deepinfra_proxy = None
+ mock.siliconflow_proxy = None
+ mock.nebius_proxy = None
+ mock.chutes_proxy = None
+ mock.featherless_proxy = None
+ mock.azure_openai_proxy = None
mock.provider_rate_limit = 40
mock.provider_rate_window = 60
mock.provider_max_concurrency = 5
diff --git a/tests/providers/test_provider_transport_logging.py b/tests/providers/test_provider_transport_logging.py
index 3e2624f3..31c505c8 100644
--- a/tests/providers/test_provider_transport_logging.py
+++ b/tests/providers/test_provider_transport_logging.py
@@ -9,15 +9,17 @@ import pytest
from free_claude_code.config.nim import NimSettings
from free_claude_code.core.failures import ExecutionFailure
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.nvidia_nim import NvidiaNimProvider
from tests.providers.request_factory import make_messages_request
-from tests.providers.support import immediate_admission
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+)
def _provider(*, verbose: bool = False) -> NvidiaNimProvider:
return NvidiaNimProvider(
- ProviderConfig(
+ make_provider_config(
api_key="k",
base_url="http://localhost:1/v1",
log_api_error_tracebacks=verbose,
diff --git a/tests/providers/test_qwencloud.py b/tests/providers/test_qwencloud.py
index 16c16230..e7571641 100644
--- a/tests/providers/test_qwencloud.py
+++ b/tests/providers/test_qwencloud.py
@@ -11,13 +11,13 @@ from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.config.provider_catalog import QWENCLOUD_DEFAULT_BASE
from free_claude_code.core.anthropic.models import MessagesRequest
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.model_listing import ModelListResponseError
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
REASONING_OFF,
REASONING_ON,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -27,7 +27,7 @@ from tests.providers.support import (
def qwencloud_provider() -> OpenAIChatProvider:
return profiled_provider(
"qwencloud",
- ProviderConfig(
+ make_provider_config(
api_key="test-qwencloud-key",
base_url=QWENCLOUD_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_sambanova.py b/tests/providers/test_sambanova.py
index fbdb7c9b..9d9c5ada 100644
--- a/tests/providers/test_sambanova.py
+++ b/tests/providers/test_sambanova.py
@@ -7,9 +7,12 @@ import pytest
from free_claude_code.config.provider_catalog import SAMBANOVA_DEFAULT_BASE
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from tests.providers.request_factory import make_messages_request
-from tests.providers.support import immediate_admission, profiled_provider
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+ profiled_provider,
+)
def make_request(**overrides):
@@ -18,7 +21,7 @@ def make_request(**overrides):
@pytest.fixture
def sambanova_config():
- return ProviderConfig(
+ return make_provider_config(
api_key="test_sambanova_key",
base_url=SAMBANOVA_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_siliconflow.py b/tests/providers/test_siliconflow.py
index 24bd8ef0..7ae76f90 100644
--- a/tests/providers/test_siliconflow.py
+++ b/tests/providers/test_siliconflow.py
@@ -14,13 +14,13 @@ from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKEN
from free_claude_code.config.provider_catalog import SILICONFLOW_DEFAULT_BASE
from free_claude_code.core.anthropic.models import MessagesRequest
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.model_listing import ModelListResponseError
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
REASONING_OFF,
REASONING_ON,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -42,7 +42,7 @@ def _request(**overrides: Any) -> MessagesRequest:
def siliconflow_provider() -> OpenAIChatProvider:
return profiled_provider(
"siliconflow",
- ProviderConfig(
+ make_provider_config(
api_key="test-siliconflow-key",
base_url=SILICONFLOW_DEFAULT_BASE,
rate_limit=10,
@@ -230,7 +230,7 @@ async def test_model_catalog_uses_documented_endpoint_query_and_auth() -> None:
):
provider = profiled_provider(
"siliconflow",
- ProviderConfig(
+ make_provider_config(
api_key="wire-siliconflow-key",
base_url=SILICONFLOW_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_streaming_errors.py b/tests/providers/test_streaming_errors.py
index 05c48074..91c6d84d 100644
--- a/tests/providers/test_streaming_errors.py
+++ b/tests/providers/test_streaming_errors.py
@@ -21,7 +21,6 @@ from free_claude_code.core.anthropic.streaming import (
from free_claude_code.core.failures import ExecutionFailure
from free_claude_code.core.reasoning import DEFAULT_REASONING_POLICY, ReasoningPolicy
from free_claude_code.providers.admission import UPSTREAM_TRANSIENT_TOTAL_ATTEMPTS
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.nvidia_nim import NvidiaNimProvider
from free_claude_code.providers.openai_chat.provider import (
_OpenAIChatStreamRunner,
@@ -34,7 +33,11 @@ from free_claude_code.providers.openai_chat.tool_calls import (
)
from free_claude_code.providers.stream_recovery import TruncatedProviderStreamError
from tests.providers.request_factory import make_messages_request
-from tests.providers.support import REASONING_OFF, immediate_admission
+from tests.providers.support import (
+ REASONING_OFF,
+ immediate_admission,
+ make_provider_config,
+)
class AsyncStreamMock:
@@ -75,7 +78,7 @@ class ClosableAsyncStreamMock(AsyncStreamMock):
def _make_provider():
"""Create a provider instance for testing."""
- config = ProviderConfig(
+ config = make_provider_config(
api_key="test_key",
base_url="https://test.api.nvidia.com/v1",
rate_limit=10,
diff --git a/tests/providers/test_subagent_interception.py b/tests/providers/test_subagent_interception.py
index fc51c20a..ab1af632 100644
--- a/tests/providers/test_subagent_interception.py
+++ b/tests/providers/test_subagent_interception.py
@@ -6,18 +6,20 @@ import pytest
from free_claude_code.config.nim import NimSettings
from free_claude_code.config.provider_catalog import NVIDIA_NIM_DEFAULT_BASE
from free_claude_code.core.anthropic import StreamBlockLedger
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.nvidia_nim import NvidiaNimProvider
from free_claude_code.providers.openai_chat.tool_calls import (
OpenAIToolCallAssembler,
)
-from tests.providers.support import immediate_admission
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+)
@pytest.mark.asyncio
async def test_task_tool_interception():
# Setup provider
- config = ProviderConfig(api_key="test", base_url=NVIDIA_NIM_DEFAULT_BASE)
+ config = make_provider_config(api_key="test", base_url=NVIDIA_NIM_DEFAULT_BASE)
provider = NvidiaNimProvider(
config,
nim_settings=NimSettings(),
diff --git a/tests/providers/test_together.py b/tests/providers/test_together.py
index c91a30cd..50987a17 100644
--- a/tests/providers/test_together.py
+++ b/tests/providers/test_together.py
@@ -11,13 +11,13 @@ from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.config.provider_catalog import TOGETHER_DEFAULT_BASE
from free_claude_code.core.anthropic.models import MessagesRequest
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.model_listing import ModelListResponseError
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
REASONING_OFF,
REASONING_ON,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -27,7 +27,7 @@ from tests.providers.support import (
def together_provider() -> OpenAIChatProvider:
return profiled_provider(
"together",
- ProviderConfig(
+ make_provider_config(
api_key="test-together-key",
base_url=TOGETHER_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_vercel.py b/tests/providers/test_vercel.py
index 89f06c03..48b1370c 100644
--- a/tests/providers/test_vercel.py
+++ b/tests/providers/test_vercel.py
@@ -6,9 +6,12 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from free_claude_code.config.provider_catalog import VERCEL_AI_GATEWAY_DEFAULT_BASE
-from free_claude_code.providers.base import ProviderConfig
from tests.providers.request_factory import make_messages_request
-from tests.providers.support import immediate_admission, profiled_provider
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+ profiled_provider,
+)
def make_request(**overrides):
@@ -17,7 +20,7 @@ def make_request(**overrides):
@pytest.fixture
def vercel_config():
- return ProviderConfig(
+ return make_provider_config(
api_key="test_vercel_key",
base_url=VERCEL_AI_GATEWAY_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_vertex.py b/tests/providers/test_vertex.py
index 301233c6..60a30d07 100644
--- a/tests/providers/test_vertex.py
+++ b/tests/providers/test_vertex.py
@@ -17,7 +17,6 @@ from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.provider_catalog import VERTEX_AI_API_ROOT
from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.model_listing import ModelListResponseError
from free_claude_code.providers.vertex import VertexProvider
from free_claude_code.providers.vertex.auth import GoogleAccessTokenProvider
@@ -28,7 +27,11 @@ from free_claude_code.providers.vertex.endpoint import (
)
from free_claude_code.providers.vertex.models import extract_vertex_model_page
from tests.providers.request_factory import make_messages_request
-from tests.providers.support import immediate_admission, reasoning_for
+from tests.providers.support import (
+ immediate_admission,
+ make_provider_config,
+ reasoning_for,
+)
_PROJECT_ID = "my-project"
_GLOBAL_OPENAI_BASE = (
@@ -87,7 +90,7 @@ def _provider(
token_provider: GoogleAccessTokenProvider | None = None,
) -> VertexProvider:
return VertexProvider(
- ProviderConfig(api_key="", base_url=VERTEX_AI_API_ROOT),
+ make_provider_config(api_key="", base_url=VERTEX_AI_API_ROOT),
project_id=_PROJECT_ID,
location=location,
admission=immediate_admission(),
diff --git a/tests/providers/test_wafer.py b/tests/providers/test_wafer.py
index 616fd076..afe7fd98 100644
--- a/tests/providers/test_wafer.py
+++ b/tests/providers/test_wafer.py
@@ -8,13 +8,13 @@ from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.config.provider_catalog import WAFER_DEFAULT_BASE
from free_claude_code.core.anthropic.models import Message, MessagesRequest, Tool
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_chat import (
OpenAIChatProvider,
)
from tests.providers.support import (
REASONING_OFF,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -22,7 +22,7 @@ from tests.providers.support import (
@pytest.fixture
def wafer_config():
- return ProviderConfig(
+ return make_provider_config(
api_key="test-wafer-key",
base_url=WAFER_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_xai.py b/tests/providers/test_xai.py
index bfa6b438..fc691fb5 100644
--- a/tests/providers/test_xai.py
+++ b/tests/providers/test_xai.py
@@ -11,13 +11,13 @@ from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.config.provider_catalog import XAI_DEFAULT_BASE
from free_claude_code.core.anthropic.models import MessagesRequest
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.model_listing import ModelListResponseError
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
REASONING_OFF,
REASONING_ON,
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -27,7 +27,7 @@ from tests.providers.support import (
def xai_provider() -> OpenAIChatProvider:
return profiled_provider(
"xai",
- ProviderConfig(
+ make_provider_config(
api_key="test-xai-key",
base_url=XAI_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_zai.py b/tests/providers/test_zai.py
index 08c98d21..bd6fb172 100644
--- a/tests/providers/test_zai.py
+++ b/tests/providers/test_zai.py
@@ -8,10 +8,10 @@ from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
from free_claude_code.config.provider_catalog import ZAI_DEFAULT_BASE
from free_claude_code.core.anthropic.models import Message, MessagesRequest
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -21,7 +21,7 @@ from tests.providers.support import (
def zai_provider():
return profiled_provider(
"zai",
- ProviderConfig(
+ make_provider_config(
api_key="test_zai_key",
base_url=ZAI_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/providers/test_zenmux.py b/tests/providers/test_zenmux.py
index ef41489e..4db5abd3 100644
--- a/tests/providers/test_zenmux.py
+++ b/tests/providers/test_zenmux.py
@@ -19,11 +19,11 @@ from free_claude_code.core.anthropic.stream_contracts import (
thinking_content,
)
from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
-from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.model_listing import ModelListResponseError
from free_claude_code.providers.openai_chat import OpenAIChatProvider
from tests.providers.support import (
immediate_admission,
+ make_provider_config,
profiled_provider,
reasoning_for,
)
@@ -33,7 +33,7 @@ from tests.providers.support import (
def zenmux_provider() -> OpenAIChatProvider:
return profiled_provider(
"zenmux",
- ProviderConfig(
+ make_provider_config(
api_key="test-zenmux-key",
base_url=ZENMUX_DEFAULT_BASE,
rate_limit=10,
@@ -435,7 +435,7 @@ async def test_model_catalog_uses_documented_endpoint_and_auth() -> None:
):
provider = profiled_provider(
"zenmux",
- ProviderConfig(
+ make_provider_config(
api_key="wire-zenmux-key",
base_url=ZENMUX_DEFAULT_BASE,
rate_limit=10,
diff --git a/tests/runtime/test_provider_manager.py b/tests/runtime/test_provider_manager.py
index 13c0eb0e..5ad2c2b2 100644
--- a/tests/runtime/test_provider_manager.py
+++ b/tests/runtime/test_provider_manager.py
@@ -75,7 +75,9 @@ class RecordingModelCatalogPublisher:
def _settings(model: str) -> Settings:
- return Settings().model_copy(update={"model": model})
+ return Settings().model_copy(
+ update={"model": model, "nvidia_nim_api_key": "test-key"}
+ )
@pytest.mark.asyncio
diff --git a/uv.lock b/uv.lock
index d27b1f40..8dfca31b 100644
--- a/uv.lock
+++ b/uv.lock
@@ -620,7 +620,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "4.30.2"
+version = "5.0.0"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },
@@ -634,7 +634,6 @@ dependencies = [
{ name = "openai" },
{ name = "pillow", marker = "sys_platform == 'darwin' or sys_platform == 'win32'" },
{ name = "pydantic" },
- { name = "pydantic-settings" },
{ name = "pystray", marker = "sys_platform == 'darwin' or sys_platform == 'win32'" },
{ name = "python-dotenv" },
{ name = "python-telegram-bot" },
@@ -684,7 +683,6 @@ requires-dist = [
{ name = "openai", specifier = ">=2.53.0" },
{ name = "pillow", marker = "sys_platform == 'darwin' or sys_platform == 'win32'", specifier = ">=12.0.0" },
{ name = "pydantic", specifier = ">=2.13.4" },
- { name = "pydantic-settings", specifier = ">=2.14.2" },
{ name = "pystray", marker = "sys_platform == 'darwin' or sys_platform == 'win32'", specifier = ">=0.19.5" },
{ name = "python-dotenv", specifier = ">=1.2.2" },
{ name = "python-telegram-bot", specifier = ">=22.8" },