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

Type application edge and control-plane boundaries (#1432)

Ali Khokharaa5064d8b7c3
diff --git a/pyproject.toml b/pyproject.toml
index e4c0b882..289b3d19 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "5.3.2"
+version = "5.3.3"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/api/admin_routes.py b/src/free_claude_code/api/admin_routes.py
index 3f1755e9..da8c0168 100644
--- a/src/free_claude_code/api/admin_routes.py
+++ b/src/free_claude_code/api/admin_routes.py
@@ -1,8 +1,8 @@
"""Local admin UI routes and APIs."""
import ipaddress
+from collections.abc import Mapping
from pathlib import Path
-from typing import Any
from urllib.parse import urlsplit
import httpx
@@ -16,12 +16,13 @@ from free_claude_code.application.connected_accounts import (
from free_claude_code.application.model_metadata import ProviderModelRefreshResult
from free_claude_code.config.admin.manifest import FIELD_BY_KEY
from free_claude_code.config.admin.persistence import validate_updates
-from free_claude_code.config.admin.values import load_config_response
+from free_claude_code.config.admin.values import load_config_response, load_value_state
from free_claude_code.config.model_refs import configured_chat_model_refs
from free_claude_code.config.provider_catalog import (
PROVIDER_CATALOG,
ProviderAuthKind,
)
+from free_claude_code.core.json_types import JsonObject, JsonValue
from .dependencies import get_services
from .ports import ApiServices
@@ -39,7 +40,7 @@ LOCAL_PROVIDER_PATHS = {
class AdminConfigPayload(BaseModel):
"""Partial config update submitted by the admin UI."""
- values: dict[str, Any] = Field(default_factory=dict)
+ values: JsonObject = Field(default_factory=dict)
class ConnectedAccountLoginPayload(BaseModel):
@@ -139,8 +140,7 @@ async def admin_status(
@router.get("/admin/api/providers/local-status")
async def local_provider_status(request: Request):
require_loopback_admin(request)
- config = load_config_response()
- values = {field["key"]: field["value"] for field in config["fields"]}
+ values = {key: entry.value or "" for key, entry in load_value_state().items()}
checks = []
for provider_id, path in LOCAL_PROVIDER_PATHS.items():
base_url = _local_provider_url(provider_id, values)
@@ -255,7 +255,7 @@ def _model_options(
}
-def _filtered_values(values: dict[str, Any]) -> dict[str, Any]:
+def _filtered_values(values: Mapping[str, JsonValue]) -> JsonObject:
return {key: value for key, value in values.items() if key in FIELD_BY_KEY}
@@ -271,7 +271,7 @@ def _local_provider_url(provider_id: str, values: dict[str, str]) -> str:
async def _check_local_provider(
provider_id: str, base_url: str, path: str
-) -> dict[str, Any]:
+) -> JsonObject:
clean_url = base_url.strip().rstrip("/")
if not clean_url:
return {
@@ -315,5 +315,5 @@ def _require_connected_account_provider(provider_id: str) -> None:
)
-def _no_store(payload: Any) -> JSONResponse:
+def _no_store(payload: JsonValue) -> JSONResponse:
return JSONResponse(payload, headers={"Cache-Control": "no-store"})
diff --git a/src/free_claude_code/api/app.py b/src/free_claude_code/api/app.py
index 193ab89d..ec47614e 100644
--- a/src/free_claude_code/api/app.py
+++ b/src/free_claude_code/api/app.py
@@ -1,7 +1,5 @@
"""Pure FastAPI application factory."""
-from typing import Any
-
from fastapi import FastAPI, Request
from fastapi.exception_handlers import request_validation_exception_handler
from fastapi.exceptions import RequestValidationError
@@ -47,7 +45,7 @@ def create_app(services: ApiServices) -> FastAPI:
@app.exception_handler(RequestValidationError)
async def validation_error_handler(request: Request, exc: RequestValidationError):
"""Log request shape for 422 debugging without content values."""
- body: Any
+ body: object
try:
body = await request.json()
except Exception as error:
diff --git a/src/free_claude_code/api/ports.py b/src/free_claude_code/api/ports.py
index 27c4900a..197a5b60 100644
--- a/src/free_claude_code/api/ports.py
+++ b/src/free_claude_code/api/ports.py
@@ -2,7 +2,7 @@
from collections.abc import Mapping
from dataclasses import dataclass
-from typing import Any, Protocol
+from typing import Protocol
from free_claude_code.application.connected_accounts import (
ConnectedAccountLoginMode,
@@ -10,18 +10,20 @@ from free_claude_code.application.connected_accounts import (
)
from free_claude_code.application.model_metadata import ProviderModelRefreshResult
from free_claude_code.application.ports import RequestRuntimePort, TaskController
+from free_claude_code.config.admin.state import ConfigInputValue
+from free_claude_code.core.json_types import JsonObject
class AdminRuntimePort(Protocol):
"""Runtime operations exposed by the local Admin API."""
async def apply_admin_config(
- self, updates: Mapping[str, Any]
- ) -> dict[str, Any]: ...
+ self, updates: Mapping[str, ConfigInputValue]
+ ) -> JsonObject: ...
- def admin_status(self) -> dict[str, Any]: ...
+ def admin_status(self) -> JsonObject: ...
- async def test_provider(self, provider_id: str) -> dict[str, Any]: ...
+ async def test_provider(self, provider_id: str) -> JsonObject: ...
async def refresh_models(self) -> ProviderModelRefreshResult: ...
diff --git a/src/free_claude_code/api/request_errors.py b/src/free_claude_code/api/request_errors.py
index 4e67fa58..4607250e 100644
--- a/src/free_claude_code/api/request_errors.py
+++ b/src/free_claude_code/api/request_errors.py
@@ -1,6 +1,7 @@
"""Shared API request validation and safe error logging."""
-from typing import Any, Literal
+from collections.abc import Sequence
+from typing import Literal
from fastapi import HTTPException
from fastapi.responses import JSONResponse
@@ -24,7 +25,7 @@ from free_claude_code.core.openai_responses import (
WireApi = Literal["messages", "responses"]
-def require_non_empty_messages(messages: list[Any]) -> None:
+def require_non_empty_messages(messages: Sequence[object]) -> None:
if not messages:
raise InvalidRequestError("messages cannot be empty")
diff --git a/src/free_claude_code/api/response_streams.py b/src/free_claude_code/api/response_streams.py
index a66833e5..0f4afa1d 100644
--- a/src/free_claude_code/api/response_streams.py
+++ b/src/free_claude_code/api/response_streams.py
@@ -7,7 +7,7 @@ from collections.abc import (
Callable,
Mapping,
)
-from typing import Any, Literal
+from typing import Literal
from fastapi.responses import JSONResponse, Response, StreamingResponse
from starlette.background import BackgroundTask
@@ -23,6 +23,7 @@ from free_claude_code.core.anthropic.streaming import (
from free_claude_code.core.async_iterators import try_close_async_iterator
from free_claude_code.core.diagnostics import safe_exception_message
from free_claude_code.core.failures import find_execution_failure
+from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.trace import close_stream_input, trace_event
TERMINAL_EXECUTION_ERROR_HEADERS = {"x-should-retry": "false"}
@@ -174,7 +175,7 @@ async def bind_response_lifetime(
def terminal_execution_error_response(
- *, status_code: int, content: dict[str, Any]
+ *, status_code: int, content: JsonObject
) -> JSONResponse:
"""Return a final provider-execution error without enabling client retries."""
return JSONResponse(
diff --git a/src/free_claude_code/api/validation_log.py b/src/free_claude_code/api/validation_log.py
index 87d812d9..644b0a34 100644
--- a/src/free_claude_code/api/validation_log.py
+++ b/src/free_claude_code/api/validation_log.py
@@ -1,21 +1,21 @@
"""Safe metadata summaries for HTTP 422 validation logging (no raw text content)."""
-from typing import Any
+from free_claude_code.core.json_types import JsonObject
def summarize_request_validation_body(
- body: Any,
-) -> tuple[list[dict[str, Any]], list[str]]:
+ body: object,
+) -> tuple[list[JsonObject], list[str]]:
"""Return message shape summary and tool name list for debug logs."""
messages = body.get("messages") if isinstance(body, dict) else None
- message_summary: list[dict[str, Any]] = []
+ message_summary: list[JsonObject] = []
if isinstance(messages, list):
for msg in messages:
if not isinstance(msg, dict):
message_summary.append({"message_kind": type(msg).__name__})
continue
content = msg.get("content")
- item: dict[str, Any] = {
+ item: JsonObject = {
"role": msg.get("role"),
"content_kind": type(content).__name__,
}
diff --git a/src/free_claude_code/api/web_tools/parsers.py b/src/free_claude_code/api/web_tools/parsers.py
index 797af7c2..929538ac 100644
--- a/src/free_claude_code/api/web_tools/parsers.py
+++ b/src/free_claude_code/api/web_tools/parsers.py
@@ -3,7 +3,6 @@
import html
import re
from html.parser import HTMLParser
-from typing import Any
from urllib.parse import parse_qs, unquote, urlparse
@@ -76,7 +75,7 @@ class HTMLTextParser(HTMLParser):
self.text_parts.append(text)
-def content_text(content: Any) -> str:
+def content_text(content: object) -> str:
if isinstance(content, str):
return content
if isinstance(content, list):
diff --git a/src/free_claude_code/api/web_tools/streaming.py b/src/free_claude_code/api/web_tools/streaming.py
index ddd3392b..fb065ea4 100644
--- a/src/free_claude_code/api/web_tools/streaming.py
+++ b/src/free_claude_code/api/web_tools/streaming.py
@@ -3,7 +3,6 @@
import uuid
from collections.abc import AsyncIterator
from datetime import UTC, datetime
-from typing import Any
from free_claude_code.core.anthropic import MessagesRequest
from free_claude_code.core.anthropic.server_tool_sse import (
@@ -14,6 +13,7 @@ from free_claude_code.core.anthropic.server_tool_sse import (
WEB_SEARCH_TOOL_RESULT_ERROR,
)
from free_claude_code.core.anthropic.streaming import format_sse_event
+from free_claude_code.core.json_types import JsonValue
from . import outbound
from .constants import _MAX_FETCH_CHARS
@@ -110,7 +110,7 @@ async def stream_web_server_tool_response(
if tool_name == "web_search":
query = str(tool_input["query"])
results = await outbound._run_web_search(query)
- result_content: Any = [
+ result_content: JsonValue = [
{
"type": "web_search_result",
"title": result["title"],
diff --git a/src/free_claude_code/application/connected_accounts.py b/src/free_claude_code/application/connected_accounts.py
index 6c544bc6..32a7c4e2 100644
--- a/src/free_claude_code/application/connected_accounts.py
+++ b/src/free_claude_code/application/connected_accounts.py
@@ -1,8 +1,10 @@
"""Safe application boundary for provider connected accounts."""
-from dataclasses import asdict, dataclass
+from dataclasses import dataclass
from enum import StrEnum
-from typing import Any, Protocol
+from typing import Protocol
+
+from free_claude_code.core.json_types import JsonObject, JsonValue
class ConnectedAccountLoginMode(StrEnum):
@@ -39,10 +41,30 @@ class ConnectedAccountStatus:
model_count: int | None = None
message: str | None = None
- def as_dict(self) -> dict[str, Any]:
+ def as_dict(self) -> JsonObject:
"""Serialize only the explicitly safe status contract."""
- return {key: value for key, value in asdict(self).items() if value is not None}
+ payload: JsonObject = {
+ "provider_id": self.provider_id,
+ "state": self.state,
+ "connected": self.connected,
+ "revision": self.revision,
+ }
+ optional_fields: tuple[tuple[str, JsonValue], ...] = (
+ ("attempt_id", self.attempt_id),
+ ("email", self.email),
+ ("mode", self.mode),
+ ("authorization_url", self.authorization_url),
+ ("verification_url", self.verification_url),
+ ("user_code", self.user_code),
+ ("expires_at", self.expires_at),
+ ("model_count", self.model_count),
+ ("message", self.message),
+ )
+ for key, value in optional_fields:
+ if value is not None:
+ payload[key] = value
+ return payload
class ConnectedAccountPort(Protocol):
diff --git a/src/free_claude_code/application/reasoning.py b/src/free_claude_code/application/reasoning.py
index 7cd495a4..14a5411b 100644
--- a/src/free_claude_code/application/reasoning.py
+++ b/src/free_claude_code/application/reasoning.py
@@ -1,7 +1,6 @@
"""Resolve client reasoning input and FCC configuration exactly once."""
from collections.abc import Mapping
-from typing import Any
from free_claude_code.config.reasoning import ReasoningPreference
from free_claude_code.core.anthropic.models import MessagesRequest, ThinkingConfig
@@ -75,7 +74,7 @@ def _thinking_control(
return ReasoningControl.DEFAULT
-def _output_effort(value: Any) -> tuple[ReasoningEffort | None, bool]:
+def _output_effort(value: object) -> tuple[ReasoningEffort | None, bool]:
if not isinstance(value, Mapping):
return None, False
raw = value.get("effort")
diff --git a/src/free_claude_code/cli/launchers/codex.py b/src/free_claude_code/cli/launchers/codex.py
index f075a4cb..8bb12789 100644
--- a/src/free_claude_code/cli/launchers/codex.py
+++ b/src/free_claude_code/cli/launchers/codex.py
@@ -14,6 +14,7 @@ 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
+from free_claude_code.core.json_types import JsonObject, JsonValue
from .codex_model_catalog import build_codex_model_catalog, write_codex_model_catalog
from .common import (
@@ -163,9 +164,7 @@ def codex_model_catalog_config_args(
return build_model_catalog_config_args(str(catalog_path))
-def fetch_proxy_models_response(
- proxy_root_url: str, auth_token: str
-) -> dict[str, object]:
+def fetch_proxy_models_response(proxy_root_url: str, auth_token: str) -> JsonObject:
"""Fetch the local proxy `/v1/models` response for Codex catalog generation."""
url = f"{proxy_root_url.rstrip('/')}/v1/models"
@@ -175,7 +174,7 @@ def fetch_proxy_models_response(
with open_local_request(
request, timeout=PROXY_PREFLIGHT_TIMEOUT_SECONDS
) as response:
- payload = json.loads(response.read().decode("utf-8"))
+ payload: JsonValue = json.loads(response.read().decode("utf-8"))
if not isinstance(payload, dict):
raise ValueError("model list response was not a JSON object")
diff --git a/src/free_claude_code/cli/launchers/codex_model_catalog.py b/src/free_claude_code/cli/launchers/codex_model_catalog.py
index 129b025a..9252663a 100644
--- a/src/free_claude_code/cli/launchers/codex_model_catalog.py
+++ b/src/free_claude_code/cli/launchers/codex_model_catalog.py
@@ -5,15 +5,15 @@ import uuid
from collections.abc import Mapping
from dataclasses import dataclass
from pathlib import Path
-from typing import Any
from free_claude_code.config.provider_catalog import SUPPORTED_PROVIDER_IDS
from free_claude_code.core.gateway_model_ids import (
GATEWAY_MODEL_ID_PREFIX,
NO_THINKING_GATEWAY_MODEL_ID_PREFIX,
)
+from free_claude_code.core.json_types import JsonObject, JsonValue
-SUPPORTED_REASONING_LEVELS = [
+SUPPORTED_REASONING_LEVELS: list[JsonObject] = [
{"effort": "low", "description": "Fast responses with lighter reasoning"},
{
"effort": "medium",
@@ -41,7 +41,7 @@ class _CatalogCandidate:
force_no_thinking: bool
-def build_codex_model_catalog(models_response: Mapping[str, Any]) -> dict[str, Any]:
+def build_codex_model_catalog(models_response: Mapping[str, JsonValue]) -> JsonObject:
"""Convert FCC `/v1/models` data into Codex `model_catalog_json` payload."""
candidates = list(_catalog_candidates(models_response))
@@ -50,7 +50,7 @@ def build_codex_model_catalog(models_response: Mapping[str, Any]) -> dict[str, A
for candidate in candidates
if not candidate.force_no_thinking
}
- models: list[dict[str, Any]] = []
+ models: list[JsonObject] = []
seen_slugs: set[str] = set()
for candidate in candidates:
@@ -67,7 +67,9 @@ def build_codex_model_catalog(models_response: Mapping[str, Any]) -> dict[str, A
return {"models": models}
-def write_codex_model_catalog(catalog_path: Path, catalog: Mapping[str, Any]) -> bool:
+def write_codex_model_catalog(
+ catalog_path: Path, catalog: Mapping[str, JsonValue]
+) -> bool:
"""Atomically write changed Codex model catalog JSON."""
content = (json.dumps(catalog, ensure_ascii=True, indent=2) + "\n").encode()
@@ -88,7 +90,7 @@ def write_codex_model_catalog(catalog_path: Path, catalog: Mapping[str, Any]) ->
def _catalog_candidates(
- models_response: Mapping[str, Any],
+ models_response: Mapping[str, JsonValue],
) -> list[_CatalogCandidate]:
data = models_response.get("data")
if not isinstance(data, list):
@@ -148,9 +150,7 @@ def _candidate_from_model_id(
return None
-def _codex_catalog_entry(
- candidate: _CatalogCandidate, *, priority: int
-) -> dict[str, Any]:
+def _codex_catalog_entry(candidate: _CatalogCandidate, *, priority: int) -> JsonObject:
return {
"slug": candidate.slug,
"display_name": candidate.display_name,
@@ -188,5 +188,5 @@ def _is_provider_model_ref(value: str) -> bool:
return bool(separator and provider_model and provider_id in SUPPORTED_PROVIDER_IDS)
-def _string_value(value: Any) -> str | None:
+def _string_value(value: object) -> str | None:
return value if isinstance(value, str) else None
diff --git a/src/free_claude_code/cli/launchers/common.py b/src/free_claude_code/cli/launchers/common.py
index 1bea5b17..6ff8e9a7 100644
--- a/src/free_claude_code/cli/launchers/common.py
+++ b/src/free_claude_code/cli/launchers/common.py
@@ -27,7 +27,7 @@ def preflight_proxy(proxy_root_url: str) -> str | None:
with open_local_request(
request, timeout=PROXY_PREFLIGHT_TIMEOUT_SECONDS
) as response:
- status_code = response.getcode()
+ status_code = response.status
except HTTPError as exc:
return f"returned HTTP {exc.code}"
except URLError as exc:
diff --git a/src/free_claude_code/cli/local_http.py b/src/free_claude_code/cli/local_http.py
index 01811a88..ed8eb0ac 100644
--- a/src/free_claude_code/cli/local_http.py
+++ b/src/free_claude_code/cli/local_http.py
@@ -1,7 +1,7 @@
"""Direct HTTP and child-environment policy for FCC-local traffic."""
from collections.abc import Mapping
-from typing import Any
+from http.client import HTTPResponse
from urllib.parse import urlsplit
from urllib.request import ProxyHandler, Request, build_opener
@@ -10,7 +10,7 @@ _LOOPBACK_BYPASS_HOSTS = ("127.0.0.1", "localhost", "::1")
_NO_PROXY_KEYS = ("NO_PROXY", "no_proxy")
-def open_local_request(request: Request, *, timeout: float) -> Any:
+def open_local_request(request: Request, *, timeout: float) -> HTTPResponse:
"""Open an FCC-local request without consulting machine proxy settings."""
return _DIRECT_OPENER.open(request, timeout=timeout)
diff --git a/src/free_claude_code/cli/managed/claude.py b/src/free_claude_code/cli/managed/claude.py
index 9ba7d211..749fe92c 100644
--- a/src/free_claude_code/cli/managed/claude.py
+++ b/src/free_claude_code/cli/managed/claude.py
@@ -3,7 +3,6 @@
import json
from collections.abc import Iterable, Mapping
from dataclasses import dataclass, field
-from typing import Any
from loguru import logger
@@ -11,6 +10,7 @@ from free_claude_code.cli.claude_env import (
CLAUDE_BINARY_NAME,
build_claude_proxy_env,
)
+from free_claude_code.core.json_types import JsonObject, JsonValue
MANAGED_CLAUDE_MODEL_TIER = "fable"
@@ -31,7 +31,7 @@ class ManagedClaudeInvocation:
argv: tuple[str, ...]
env: dict[str, str]
cwd: str
- trace_metadata: dict[str, Any] = field(default_factory=dict)
+ trace_metadata: JsonObject = field(default_factory=dict)
@dataclass(frozen=True, slots=True)
@@ -162,11 +162,11 @@ def build_managed_claude_command(
def parse_managed_claude_stdout_line(
line: str, state: ManagedClaudeParseState
-) -> Iterable[Any]:
+) -> Iterable[JsonObject]:
"""Parse one Claude Code stream-json stdout line."""
try:
- event = json.loads(line)
+ parsed: JsonValue = json.loads(line)
except json.JSONDecodeError:
if state.log_raw_cli_diagnostics:
logger.debug("Non-JSON output: {}", line)
@@ -175,6 +175,15 @@ def parse_managed_claude_stdout_line(
yield {"type": "raw", "content": line}
return
+ if not isinstance(parsed, dict):
+ if state.log_raw_cli_diagnostics:
+ logger.debug("Non-object JSON output: {}", line)
+ else:
+ logger.debug("Non-object JSON CLI line: char_len={}", len(line))
+ yield {"type": "raw", "content": line}
+ return
+ event = parsed
+
if not state.session_id_extracted:
extracted_id = extract_managed_claude_session_id(event)
if extracted_id:
@@ -185,7 +194,7 @@ def parse_managed_claude_stdout_line(
yield event
-def extract_managed_claude_session_id(event: Any) -> str | None:
+def extract_managed_claude_session_id(event: object) -> str | None:
"""Extract a Claude Code session ID from supported stream-json event shapes."""
if not isinstance(event, dict):
@@ -212,5 +221,5 @@ def extract_managed_claude_session_id(event: Any) -> str | None:
return None
-def _string_value(value: Any) -> str | None:
+def _string_value(value: object) -> str | None:
return value if isinstance(value, str) else None
diff --git a/src/free_claude_code/config/admin/manifest.py b/src/free_claude_code/config/admin/manifest.py
index 6a682413..db230508 100644
--- a/src/free_claude_code/config/admin/manifest.py
+++ b/src/free_claude_code/config/admin/manifest.py
@@ -1,9 +1,6 @@
"""Admin configuration manifest."""
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 (
@@ -14,74 +11,7 @@ from free_claude_code.config.reasoning import (
from free_claude_code.config.settings import Settings
from .provider_manifest import provider_field_specs
-
-FieldType = Literal[
- "text",
- "secret",
- "number",
- "boolean",
- "model",
- "optional_model",
- "select",
- "textarea",
-]
-
-
-@dataclass(frozen=True, slots=True)
-class ConfigSectionSpec:
- """A group of config fields rendered together in the admin UI."""
-
- section_id: str
- label: str
- description: str
- advanced: bool = False
-
-
-@dataclass(frozen=True, slots=True)
-class ConfigFieldSpec:
- """Typed metadata for one env-backed admin setting."""
-
- key: str
- label: str
- section_id: str
- field_type: FieldType = "text"
- settings_attr: str | None = None
- options: tuple[str | ConfigOptionSpec, ...] = ()
- secret: bool = False
- advanced: bool = False
- restart_required: bool = False
- 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:
- """A persisted option value and its user-facing label."""
-
- value: str
- label: str
+from .specs import ConfigFieldSpec, ConfigOptionSpec, ConfigSectionSpec
def _reasoning_options(
@@ -620,7 +550,7 @@ def _catalog_smoke_fields() -> tuple[ConfigFieldSpec, ...]:
FIELDS: tuple[ConfigFieldSpec, ...] = (
- *(ConfigFieldSpec(**spec) for spec in provider_field_specs()),
+ *provider_field_specs(),
*_NON_PROVIDER_FIELDS,
*_catalog_smoke_fields(),
)
diff --git a/src/free_claude_code/config/admin/persistence.py b/src/free_claude_code/config/admin/persistence.py
index 89444d56..fbeedca6 100644
--- a/src/free_claude_code/config/admin/persistence.py
+++ b/src/free_claude_code/config/admin/persistence.py
@@ -3,7 +3,6 @@
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,
@@ -17,8 +16,10 @@ from free_claude_code.config.env_migrations import (
)
from free_claude_code.config.paths import managed_env_path
from free_claude_code.config.settings import Settings
+from free_claude_code.core.json_types import JsonObject
from .manifest import FIELD_BY_KEY
+from .state import ConfigInputValue
from .validation import settings_from_values
from .values import MASKED_SECRET, is_locked_source, load_value_state, normalize_for_env
@@ -37,7 +38,7 @@ class PreparedAdminUpdate:
def valid(self) -> bool:
return self.settings is not None and not self.errors
- def validation_response(self) -> dict[str, Any]:
+ def validation_response(self) -> JsonObject:
return {
"valid": self.valid,
"errors": list(self.errors),
@@ -47,7 +48,7 @@ class PreparedAdminUpdate:
),
}
- def applied_response(self) -> dict[str, Any]:
+ def applied_response(self) -> JsonObject:
if not self.valid:
return self.validation_response() | {
"applied": False,
@@ -66,7 +67,9 @@ class PreparedAdminUpdate:
}
-def target_values_with_updates(updates: Mapping[str, Any]) -> dict[str, str]:
+def target_values_with_updates(
+ updates: Mapping[str, ConfigInputValue],
+) -> dict[str, str]:
"""Return sparse managed state after applying valid partial-update semantics."""
state = load_value_state()
@@ -79,7 +82,7 @@ def target_values_with_updates(updates: Mapping[str, Any]) -> dict[str, str]:
for key, submitted in updates.items():
field = FIELD_BY_KEY.get(key)
- if field is None or is_locked_source(state[key]["source"]):
+ if field is None or is_locked_source(state[key].source):
continue
if field.secret and (
submitted == MASKED_SECRET
@@ -96,14 +99,14 @@ def target_values_with_updates(updates: Mapping[str, Any]) -> dict[str, str]:
return values
-def validate_updates(updates: Mapping[str, Any]) -> dict[str, Any]:
+def validate_updates(updates: Mapping[str, ConfigInputValue]) -> JsonObject:
"""Validate partial Admin updates and return a masked sparse preview."""
return prepare_admin_update(updates).validation_response()
def changed_pending_fields(
- updates: Mapping[str, Any],
+ updates: Mapping[str, ConfigInputValue],
*,
settings: Settings,
) -> list[str]:
@@ -113,7 +116,7 @@ def changed_pending_fields(
pending: list[str] = []
for key, submitted in updates.items():
field = FIELD_BY_KEY.get(key)
- if field is None or is_locked_source(state[key]["source"]):
+ if field is None or is_locked_source(state[key].source):
continue
if field.secret and (
submitted == MASKED_SECRET
@@ -125,13 +128,15 @@ def changed_pending_fields(
requires_restart = _active_voice_credential(settings) == key
if not requires_restart:
continue
- if normalize_for_env(submitted) == state[key]["value"]:
+ if normalize_for_env(submitted) == state[key].value:
continue
pending.append(key)
return pending
-def prepare_admin_update(updates: Mapping[str, Any]) -> PreparedAdminUpdate:
+def prepare_admin_update(
+ updates: Mapping[str, ConfigInputValue],
+) -> PreparedAdminUpdate:
"""Validate an update and construct its prospective Settings snapshot."""
update_errors = _update_protocol_errors(updates)
@@ -152,7 +157,7 @@ def prepare_admin_update(updates: Mapping[str, Any]) -> PreparedAdminUpdate:
)
-def commit_prepared_admin_update(prepared: PreparedAdminUpdate) -> dict[str, Any]:
+def commit_prepared_admin_update(prepared: PreparedAdminUpdate) -> JsonObject:
"""Atomically persist a previously validated Admin update."""
if not prepared.valid:
@@ -161,7 +166,9 @@ def commit_prepared_admin_update(prepared: PreparedAdminUpdate) -> dict[str, Any
return prepared.applied_response()
-def _update_protocol_errors(updates: Mapping[str, Any]) -> tuple[str, ...]:
+def _update_protocol_errors(
+ updates: Mapping[str, ConfigInputValue],
+) -> tuple[str, ...]:
errors: list[str] = []
for key, submitted in updates.items():
field = FIELD_BY_KEY.get(key)
diff --git a/src/free_claude_code/config/admin/provider_manifest.py b/src/free_claude_code/config/admin/provider_manifest.py
index 1f377cc3..ae2d1333 100644
--- a/src/free_claude_code/config/admin/provider_manifest.py
+++ b/src/free_claude_code/config/admin/provider_manifest.py
@@ -1,11 +1,23 @@
"""Catalog-derived Admin provider fields."""
-from typing import Any
+from dataclasses import replace
+from typing import TypedDict
from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
from free_claude_code.config.settings import Settings
-_PROVIDER_FIELD_OVERRIDES: dict[str, dict[str, Any]] = {
+from .specs import ConfigFieldSpec
+
+
+class ProviderFieldOverride(TypedDict, total=False):
+ """Optional catalog-field presentation overrides."""
+
+ label: str
+ description: str
+ restart_required: bool
+
+
+_PROVIDER_FIELD_OVERRIDES: dict[str, ProviderFieldOverride] = {
"OPENAI_PROXY": {
"description": (
"Optional proxy used for OpenAI sign-in and ChatGPT Codex requests. "
@@ -273,7 +285,7 @@ _PROVIDER_FIELD_OVERRIDES: dict[str, dict[str, Any]] = {
}
-def provider_field_specs() -> tuple[dict[str, Any], ...]:
+def provider_field_specs() -> tuple[ConfigFieldSpec, ...]:
"""Return provider fields generated from the provider catalog."""
return (
@@ -285,8 +297,8 @@ def provider_field_specs() -> tuple[dict[str, Any], ...]:
)
-def _credential_field_specs() -> tuple[dict[str, Any], ...]:
- specs: list[dict[str, Any]] = []
+def _credential_field_specs() -> tuple[ConfigFieldSpec, ...]:
+ specs: list[ConfigFieldSpec] = []
seen_env_keys: set[str] = set()
for descriptor in PROVIDER_CATALOG.values():
if descriptor.credential_env is None:
@@ -294,94 +306,112 @@ def _credential_field_specs() -> tuple[dict[str, Any], ...]:
if descriptor.credential_env in seen_env_keys:
continue
seen_env_keys.add(descriptor.credential_env)
- spec = {
- "key": descriptor.credential_env,
- "label": f"{descriptor.display_name} API Key",
- "section_id": "providers",
- "field_type": "secret",
- "settings_attr": descriptor.credential_attr,
- "secret": True,
- }
- spec.update(_PROVIDER_FIELD_OVERRIDES.get(descriptor.credential_env, {}))
- specs.append(spec)
+ specs.append(
+ _with_override(
+ ConfigFieldSpec(
+ key=descriptor.credential_env,
+ label=f"{descriptor.display_name} API Key",
+ section_id="providers",
+ field_type="secret",
+ settings_attr=descriptor.credential_attr,
+ secret=True,
+ )
+ )
+ )
return tuple(specs)
-def _base_url_field_specs() -> tuple[dict[str, Any], ...]:
- specs: list[dict[str, Any]] = []
+def _base_url_field_specs() -> tuple[ConfigFieldSpec, ...]:
+ specs: list[ConfigFieldSpec] = []
for descriptor in PROVIDER_CATALOG.values():
if descriptor.base_url_attr is None:
continue
key = _settings_env_key(descriptor.base_url_attr)
- spec = {
- "key": key,
- "label": f"{descriptor.display_name} Base URL",
- "section_id": "providers",
- "settings_attr": descriptor.base_url_attr,
- }
- spec.update(_PROVIDER_FIELD_OVERRIDES.get(key, {}))
- specs.append(spec)
+ specs.append(
+ _with_override(
+ ConfigFieldSpec(
+ key=key,
+ label=f"{descriptor.display_name} Base URL",
+ section_id="providers",
+ settings_attr=descriptor.base_url_attr,
+ )
+ )
+ )
return tuple(specs)
-def _cloudflare_account_field_specs() -> tuple[dict[str, Any], ...]:
+def _cloudflare_account_field_specs() -> tuple[ConfigFieldSpec, ...]:
return (
- {
- "key": "CLOUDFLARE_ACCOUNT_ID",
- "label": "Cloudflare Account ID",
- "section_id": "providers",
- "settings_attr": "cloudflare_account_id",
- "description": (
+ ConfigFieldSpec(
+ key="CLOUDFLARE_ACCOUNT_ID",
+ label="Cloudflare Account ID",
+ section_id="providers",
+ settings_attr="cloudflare_account_id",
+ description=(
"Cloudflare account ID used to build the /accounts/{id}/ai/v1 endpoint."
),
- },
+ ),
)
-def _vertex_field_specs() -> tuple[dict[str, Any], ...]:
+def _vertex_field_specs() -> tuple[ConfigFieldSpec, ...]:
return (
- {
- "key": "VERTEX_PROJECT_ID",
- "label": "Google Cloud Project ID",
- "section_id": "providers",
- "settings_attr": "vertex_project_id",
- "description": (
+ ConfigFieldSpec(
+ key="VERTEX_PROJECT_ID",
+ label="Google Cloud Project ID",
+ section_id="providers",
+ settings_attr="vertex_project_id",
+ description=(
"Google Cloud project used for Vertex AI. Authentication uses "
"Application Default Credentials (ADC)."
),
- },
- {
- "key": "VERTEX_LOCATION",
- "label": "Vertex AI Location",
- "section_id": "providers",
- "settings_attr": "vertex_location",
- "description": (
+ ),
+ ConfigFieldSpec(
+ key="VERTEX_LOCATION",
+ label="Vertex AI Location",
+ section_id="providers",
+ settings_attr="vertex_location",
+ description=(
"Use global for the global Vertex AI endpoint or a region such as "
"us-central1."
),
- },
+ ),
)
-def _proxy_field_specs() -> tuple[dict[str, Any], ...]:
- specs: list[dict[str, Any]] = []
+def _proxy_field_specs() -> tuple[ConfigFieldSpec, ...]:
+ specs: list[ConfigFieldSpec] = []
for descriptor in PROVIDER_CATALOG.values():
if descriptor.proxy_attr is None:
continue
specs.append(
- {
- "key": _settings_env_key(descriptor.proxy_attr),
- "label": f"{descriptor.display_name} Proxy",
- "section_id": "providers",
- "field_type": "secret",
- "settings_attr": descriptor.proxy_attr,
- "secret": True,
- "advanced": True,
- }
+ _with_override(
+ ConfigFieldSpec(
+ key=_settings_env_key(descriptor.proxy_attr),
+ label=f"{descriptor.display_name} Proxy",
+ section_id="providers",
+ field_type="secret",
+ settings_attr=descriptor.proxy_attr,
+ secret=True,
+ advanced=True,
+ )
+ )
)
return tuple(specs)
+def _with_override(spec: ConfigFieldSpec) -> ConfigFieldSpec:
+ override = _PROVIDER_FIELD_OVERRIDES.get(spec.key)
+ if override is None:
+ return spec
+ return replace(
+ spec,
+ label=override.get("label", spec.label),
+ description=override.get("description", spec.description),
+ restart_required=override.get("restart_required", spec.restart_required),
+ )
+
+
def _settings_env_key(settings_attr: str) -> str:
model_field = Settings.model_fields[settings_attr]
alias = model_field.validation_alias
diff --git a/src/free_claude_code/config/admin/specs.py b/src/free_claude_code/config/admin/specs.py
new file mode 100644
index 00000000..48b30340
--- /dev/null
+++ b/src/free_claude_code/config/admin/specs.py
@@ -0,0 +1,75 @@
+"""Typed metadata owned by the Admin configuration boundary."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Literal
+
+from free_claude_code.config.settings import Settings
+
+type FieldType = Literal[
+ "text",
+ "secret",
+ "number",
+ "boolean",
+ "model",
+ "optional_model",
+ "select",
+ "textarea",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigOptionSpec:
+ """A persisted option value and its user-facing label."""
+
+ value: str
+ label: str
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigSectionSpec:
+ """A group of config fields rendered together in the Admin UI."""
+
+ section_id: str
+ label: str
+ description: str
+ advanced: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigFieldSpec:
+ """Typed metadata for one env-backed Admin setting."""
+
+ key: str
+ label: str
+ section_id: str
+ field_type: FieldType = "text"
+ settings_attr: str | None = None
+ options: tuple[str | ConfigOptionSpec, ...] = ()
+ secret: bool = False
+ advanced: bool = False
+ restart_required: bool = False
+ 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
diff --git a/src/free_claude_code/config/admin/state.py b/src/free_claude_code/config/admin/state.py
new file mode 100644
index 00000000..54c412ba
--- /dev/null
+++ b/src/free_claude_code/config/admin/state.py
@@ -0,0 +1,18 @@
+"""Typed effective-value state shared by Admin configuration services."""
+
+from dataclasses import dataclass
+
+from free_claude_code.core.json_types import JsonValue
+
+type ConfigInputValue = JsonValue
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigValueState:
+ """One resolved Admin value and the configuration source that owns it."""
+
+ value: str | None
+ source: str
+
+
+type ValueState = dict[str, ConfigValueState]
diff --git a/src/free_claude_code/config/admin/status.py b/src/free_claude_code/config/admin/status.py
index a28bca53..e3504908 100644
--- a/src/free_claude_code/config/admin/status.py
+++ b/src/free_claude_code/config/admin/status.py
@@ -1,21 +1,22 @@
"""Provider configuration status for the Admin UI."""
from collections.abc import Mapping
-from typing import Any
from free_claude_code.config.provider_catalog import (
PROVIDER_CATALOG,
ProviderAuthKind,
)
+from free_claude_code.core.json_types import JsonObject
from .manifest import FIELDS
+from .state import ConfigValueState
def provider_config_status(
- state: Mapping[str, Mapping[str, Any]],
-) -> list[dict[str, Any]]:
+ state: Mapping[str, ConfigValueState],
+) -> list[JsonObject]:
"""Return provider configuration status without making network calls."""
- statuses: list[dict[str, Any]] = []
+ statuses: list[JsonObject] = []
for provider_id, descriptor in PROVIDER_CATALOG.items():
if descriptor.auth_kind is ProviderAuthKind.CONNECTED_ACCOUNT:
statuses.append(
@@ -81,11 +82,12 @@ def provider_config_status(
def _value_for_settings_attr(
- state: Mapping[str, Mapping[str, Any]], settings_attr: str
+ state: Mapping[str, ConfigValueState], settings_attr: str
) -> str | None:
for field in FIELDS:
if field.settings_attr == settings_attr:
- value = state.get(field.key, {}).get("value", field.resolved_default())
+ entry = state.get(field.key)
+ value = entry.value if entry is not None else field.resolved_default()
return str(value) if value is not None else None
return None
diff --git a/src/free_claude_code/config/admin/values.py b/src/free_claude_code/config/admin/values.py
index db707e47..365dd962 100644
--- a/src/free_claude_code/config/admin/values.py
+++ b/src/free_claude_code/config/admin/values.py
@@ -2,20 +2,21 @@
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 free_claude_code.core.json_types import JsonObject
-from .manifest import FIELDS, SECTIONS, ConfigFieldSpec, ConfigOptionSpec
+from .manifest import FIELDS, SECTIONS
+from .specs import ConfigFieldSpec, ConfigOptionSpec
+from .state import ConfigValueState, ValueState
from .status import provider_config_status
MASKED_SECRET = "********"
-ValueState = dict[str, dict[str, Any]]
-def normalize_for_env(value: Any) -> str | None:
+def normalize_for_env(value: object) -> str | None:
"""Normalize a submitted Admin value for sparse dotenv persistence."""
if value is None:
@@ -61,19 +62,19 @@ def load_value_state() -> ValueState:
else:
value = field.resolved_default()
source = ConfigSource.DEFAULT.value
- state[field.key] = {"value": value, "source": source}
+ state[field.key] = ConfigValueState(value=value, source=source)
return state
-def load_config_response() -> dict[str, Any]:
+def load_config_response() -> JsonObject:
"""Return manifest and current config values for the Admin UI."""
state = load_value_state()
- fields: list[dict[str, Any]] = []
+ fields: list[JsonObject] = []
for field in FIELDS:
entry = state[field.key]
- source = str(entry["source"])
- raw_value = entry["value"]
+ source = entry.source
+ raw_value = entry.value
fields.append(
{
"key": field.key,
diff --git a/src/free_claude_code/config/settings.py b/src/free_claude_code/config/settings.py
index e24596e7..5ff24144 100644
--- a/src/free_claude_code/config/settings.py
+++ b/src/free_claude_code/config/settings.py
@@ -1,6 +1,6 @@
"""Pure, validated application settings schema."""
-from typing import Annotated, Any
+from typing import Annotated
from pydantic import (
BaseModel,
@@ -23,7 +23,7 @@ from .provider_catalog import (
from .reasoning import ReasoningPreference
-def _empty_to_none(value: Any) -> Any:
+def _empty_to_none(value: object) -> object:
if isinstance(value, str) and not value.strip():
return None
return value
@@ -638,7 +638,7 @@ class Settings(BaseModel):
@field_validator("max_message_log_entries_per_chat", mode="before")
@classmethod
- def parse_optional_log_cap(cls, v: Any) -> Any:
+ def parse_optional_log_cap(cls, v: object) -> object:
if v == "" or v is None:
return None
return v
diff --git a/src/free_claude_code/core/json_types.py b/src/free_claude_code/core/json_types.py
new file mode 100644
index 00000000..1025bf4c
--- /dev/null
+++ b/src/free_claude_code/core/json_types.py
@@ -0,0 +1,7 @@
+"""Shared JSON value vocabulary for wire and persistence boundaries."""
+
+from collections.abc import Mapping, Sequence
+
+type JsonScalar = bool | int | float | str | None
+type JsonValue = JsonScalar | Sequence[JsonValue] | Mapping[str, JsonValue]
+type JsonObject = dict[str, JsonValue]
diff --git a/src/free_claude_code/runtime/application.py b/src/free_claude_code/runtime/application.py
index a92f51d0..49f29f0e 100644
--- a/src/free_claude_code/runtime/application.py
+++ b/src/free_claude_code/runtime/application.py
@@ -7,7 +7,6 @@ import os
import traceback
from collections.abc import Awaitable, Callable, Mapping
from dataclasses import replace
-from typing import Any
from loguru import logger
@@ -27,6 +26,7 @@ from free_claude_code.config.admin.persistence import (
commit_prepared_admin_update,
prepare_admin_update,
)
+from free_claude_code.config.admin.state import ConfigInputValue
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.loader import clear_settings_cache
@@ -34,6 +34,7 @@ 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
+from free_claude_code.core.json_types import JsonObject
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 (
@@ -49,7 +50,7 @@ RestartCallback = Callable[[], Awaitable[None] | None]
async def best_effort(
name: str,
- awaitable: Awaitable[Any],
+ awaitable: Awaitable[object],
*,
log_verbose_errors: bool = False,
) -> bool:
@@ -171,8 +172,8 @@ class ApplicationRuntime:
async def apply_admin_config(
self,
- updates: Mapping[str, Any],
- ) -> dict[str, Any]:
+ updates: Mapping[str, ConfigInputValue],
+ ) -> JsonObject:
"""Apply one validated config update without splitting runtime ownership."""
async with self._config_lock:
prepared = prepare_admin_update(updates)
@@ -192,7 +193,7 @@ class ApplicationRuntime:
)
return result
- result: dict[str, Any] = {}
+ result: JsonObject = {}
def commit() -> None:
result.update(self._commit_admin_update(prepared))
@@ -206,7 +207,7 @@ class ApplicationRuntime:
result["restart"] = self._restart_metadata((), prepared.settings)
return result
- def admin_status(self) -> dict[str, Any]:
+ def admin_status(self) -> JsonObject:
settings = self.settings
return {
"status": "running",
@@ -222,7 +223,7 @@ class ApplicationRuntime:
},
}
- async def test_provider(self, provider_id: str) -> dict[str, Any]:
+ async def test_provider(self, provider_id: str) -> JsonObject:
lease = await self.provider_manager.acquire()
try:
provider = lease.resolve_provider(provider_id)
@@ -309,7 +310,7 @@ class ApplicationRuntime:
def _commit_admin_update(
self,
prepared: PreparedAdminUpdate,
- ) -> dict[str, Any]:
+ ) -> JsonObject:
result = commit_prepared_admin_update(prepared)
clear_settings_cache()
return result
@@ -318,7 +319,7 @@ class ApplicationRuntime:
self,
fields: tuple[str, ...],
settings: Settings,
- ) -> dict[str, Any]:
+ ) -> JsonObject:
automatic = bool(fields and self._restart_callback is not None)
return {
"required": bool(fields),
diff --git a/src/free_claude_code/runtime/asgi.py b/src/free_claude_code/runtime/asgi.py
index 654d53b5..f6f41318 100644
--- a/src/free_claude_code/runtime/asgi.py
+++ b/src/free_claude_code/runtime/asgi.py
@@ -1,7 +1,5 @@
"""ASGI lifespan adapter for the application runtime owner."""
-from typing import Any
-
from loguru import logger
from starlette.types import ASGIApp, Receive, Scope, Send
@@ -15,9 +13,6 @@ class RuntimeASGIApp:
self.app = app
self.runtime = runtime
- def __getattr__(self, name: str) -> Any:
- return getattr(self.app, name)
-
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
if scope["type"] != "lifespan":
await self.app(scope, receive, send)
diff --git a/tests/cli/test_managed_claude.py b/tests/cli/test_managed_claude.py
index e5d48c84..059e587c 100644
--- a/tests/cli/test_managed_claude.py
+++ b/tests/cli/test_managed_claude.py
@@ -223,3 +223,13 @@ def test_managed_claude_parser_returns_raw_for_non_json() -> None:
)
assert events == [{"type": "raw", "content": "not json"}]
+
+
+def test_managed_claude_parser_returns_raw_for_non_object_json() -> None:
+ events = list(
+ parse_managed_claude_stdout_line(
+ '"not an event"', ManagedClaudeParseState(log_raw_cli_diagnostics=False)
+ )
+ )
+
+ assert events == [{"type": "raw", "content": '"not an event"'}]
diff --git a/tests/contracts/test_admin_provider_manifest.py b/tests/contracts/test_admin_provider_manifest.py
index 34585c9b..26c1cabd 100644
--- a/tests/contracts/test_admin_provider_manifest.py
+++ b/tests/contracts/test_admin_provider_manifest.py
@@ -1,11 +1,17 @@
"""Ensure admin UI manifest exposes every catalog credential/proxy binding."""
from free_claude_code.config.admin.manifest import FIELD_BY_KEY, FIELDS
+from free_claude_code.config.admin.state import ConfigValueState
from free_claude_code.config.provider_catalog import (
PROVIDER_CATALOG,
ProviderAuthKind,
)
from free_claude_code.config.settings import Settings
+from free_claude_code.core.json_types import JsonObject
+
+
+def _test_value(value: str) -> ConfigValueState:
+ return ConfigValueState(value=value, source="test")
def test_provider_catalog_remote_credentials_in_admin_manifest() -> None:
@@ -98,6 +104,14 @@ def test_provider_catalog_proxy_attrs_in_admin_manifest() -> None:
assert not missing_key and not wrong_attr, "\n".join(missing_key + wrong_attr)
+def test_openai_proxy_override_applies_to_catalog_proxy_field() -> None:
+ entry = FIELD_BY_KEY["OPENAI_PROXY"]
+
+ assert entry.settings_attr == "openai_proxy"
+ assert entry.restart_required is True
+ assert "restarts FCC" in entry.description
+
+
def test_provider_catalog_display_names_are_admin_status_source() -> None:
from free_claude_code.config.admin.status import provider_config_status
from free_claude_code.config.admin.values import load_value_state
@@ -156,7 +170,7 @@ def test_zai_shared_key_configures_both_distinct_provider_surfaces() -> None:
statuses = {
status["provider_id"]: status
for status in provider_config_status(
- {"ZAI_API_KEY": {"value": "shared-zai-key"}}
+ {"ZAI_API_KEY": _test_value("shared-zai-key")}
)
}
@@ -174,11 +188,11 @@ def test_zai_shared_key_configures_both_distinct_provider_surfaces() -> None:
def test_vertex_admin_status_uses_project_configuration_not_an_api_key() -> None:
from free_claude_code.config.admin.status import provider_config_status
- def vertex_status(project_id: str) -> dict[str, object]:
+ def vertex_status(project_id: str) -> JsonObject:
statuses = provider_config_status(
{
- "VERTEX_PROJECT_ID": {"value": project_id},
- "VERTEX_LOCATION": {"value": "global"},
+ "VERTEX_PROJECT_ID": _test_value(project_id),
+ "VERTEX_LOCATION": _test_value("global"),
}
)
return next(status for status in statuses if status["provider_id"] == "vertex")
@@ -192,11 +206,11 @@ def test_vertex_admin_status_uses_project_configuration_not_an_api_key() -> None
def test_azure_openai_admin_status_distinguishes_key_and_url() -> None:
from free_claude_code.config.admin.status import provider_config_status
- def azure_status(api_key: str, base_url: str) -> dict[str, object]:
+ def azure_status(api_key: str, base_url: str) -> JsonObject:
statuses = provider_config_status(
{
- "AZURE_OPENAI_API_KEY": {"value": api_key},
- "AZURE_OPENAI_BASE_URL": {"value": base_url},
+ "AZURE_OPENAI_API_KEY": _test_value(api_key),
+ "AZURE_OPENAI_BASE_URL": _test_value(base_url),
}
)
return next(
diff --git a/uv.lock b/uv.lock
index ce7dc8db..7cbc55cb 100644
--- a/uv.lock
+++ b/uv.lock
@@ -607,7 +607,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "5.3.2"
+version = "5.3.3"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },