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

Add architecture map and provider guardrails

Alishahryar144fcc09c02fd
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 00000000..1f20d22c
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,538 @@
+# Architecture
+
+This document is a maintainer-oriented map of Free Claude Code. It explains the
+runtime boundaries, request flows, provider abstraction, configuration model,
+optional messaging bridge, and verification strategy.
+
+For installation, provider setup, and user-facing usage, see
+[README.md](README.md). This file focuses on where behavior lives in the codebase
+and how contributors should extend it.
+
+## System Overview
+
+Free Claude Code is a local proxy for agent clients. It accepts Anthropic
+Messages traffic from Claude Code clients and OpenAI Responses traffic from Codex
+clients, routes the request to a configured upstream provider, and preserves the
+wire protocol expected by the caller.
+
+There are three runtime surfaces:
+
+- HTTP proxy: FastAPI routes expose Anthropic-compatible, Responses-compatible,
+ health, model-listing, stop, and admin endpoints.
+- CLI launchers: wrapper entrypoints prepare Claude Code and Codex environments
+ so they target the local proxy.
+- Messaging bridge: optional Discord or Telegram adapters turn chat messages
+ into managed client CLI sessions.
+
+```mermaid
+flowchart LR
+ ClaudeCode[Claude Code CLI and Extensions] --> ProxyAPI[FastAPI Proxy]
+ Codex[Codex CLI and Extensions] --> ProxyAPI
+ AdminUI[Local Admin UI] --> ProxyAPI
+ Bots[Discord or Telegram Bots] --> Messaging[Messaging Bridge]
+ Messaging --> ClientCLI[Managed Client CLI Sessions]
+ ClientCLI --> ProxyAPI
+ ProxyAPI --> Service[ClaudeProxyService]
+ Service --> Router[ModelRouter]
+ Service --> Providers[ProviderRegistry]
+ Providers --> OpenAIChat[OpenAI Chat Providers]
+ Providers --> NativeAnthropic[Anthropic Messages Providers]
+```
+
+## Package Boundaries
+
+The installable wheel packages are declared in [pyproject.toml](pyproject.toml):
+
+- [api/](api/) owns the FastAPI app, route handlers, request orchestration,
+ admin APIs, local optimizations, and server-tool handling.
+- [cli/](cli/) owns console entrypoints, client CLI launchers, process/session
+ management, and client adapter contracts.
+- [config/](config/) owns settings, provider metadata, filesystem paths,
+ logging setup, constants, and provider ID catalogs.
+- [core/](core/) owns provider-neutral protocol logic: Anthropic conversion,
+ SSE construction, OpenAI Responses conversion, stream recovery, token counting,
+ and structured trace helpers.
+- [messaging/](messaging/) owns optional platform adapters, incoming message
+ handling, tree queues, transcript rendering, persistence, commands, and voice
+ support.
+- [providers/](providers/) owns provider construction, shared provider base
+ classes, upstream transports, rate limiting, model listing, and concrete
+ provider adapters.
+
+[tests/](tests/) contains deterministic unit and contract coverage.
+[smoke/](smoke/) contains local and live product smoke tests that can launch
+subprocesses or touch real services.
+
+The main ownership rule is that shared Anthropic and Responses protocol behavior
+belongs in [core/](core/). Provider modules should use neutral helpers rather
+than importing behavior from another provider-specific module.
+
+## Design Pressure And Refactor Targets
+
+The current package boundaries are intentional, but several modules still carry
+large orchestration responsibilities. Treat these as refactor targets, not as
+new places to add unrelated behavior:
+
+- [api/services.py](api/services.py) coordinates routing, optimizations, local
+ server tools, provider execution, and Responses adaptation. Future changes
+ should keep route handlers thin and move separable use-case logic behind small
+ helpers.
+- [providers/openai_compat.py](providers/openai_compat.py) and
+ [providers/anthropic_messages.py](providers/anthropic_messages.py) own shared
+ transport behavior plus retry, recovery, stream translation, and error
+ handling. Shared protocol rules should continue moving toward [core/](core/)
+ when they are not provider-specific.
+- [messaging/handler.py](messaging/handler.py) owns command dispatch, tree
+ queueing, CLI session execution, transcript updates, and persistence
+ coordination. New platform-specific behavior should stay in platform or
+ rendering modules.
+- [api/admin_config.py](api/admin_config.py) owns the admin config manifest,
+ validation, env rendering, and status metadata. Keep it data-driven, and split
+ only around cohesive admin responsibilities.
+
+## Runtime Startup And Lifecycle
+
+Console scripts are registered in [pyproject.toml](pyproject.toml):
+
+- `fcc-server` and `free-claude-code` call `cli.entrypoints:serve`.
+- `fcc-init` calls `cli.entrypoints:init`.
+- `fcc-claude` calls `cli.entrypoints:launch_claude`.
+- `fcc-codex` calls `cli.entrypoints:launch_codex`.
+
+[cli/entrypoints.py](cli/entrypoints.py) starts the FastAPI server with Uvicorn.
+`serve()` migrates legacy env files when needed, loads cached settings, runs a
+supervised server instance, and can restart the server after admin config changes.
+On final shutdown it best-effort kills registered child processes.
+
+[api/app.py](api/app.py) builds the FastAPI application. `create_app()` configures
+logging, registers admin and API routers, attaches HTTP correlation metadata, and
+installs exception handlers for validation failures, provider errors, and
+unexpected errors. `GracefulLifespanApp` wraps the app so startup failures are
+reported without noisy Starlette tracebacks.
+
+[api/runtime.py](api/runtime.py) owns process-lifetime resources through
+`AppRuntime`:
+
+- creates and publishes an app-scoped `ProviderRegistry`;
+- validates configured models best-effort without blocking first-run admin access;
+- starts provider model-list refresh;
+- starts optional Discord or Telegram messaging when configured;
+- publishes messaging, CLI, and provider state onto `app.state`;
+- shuts down messaging platforms, CLI sessions, provider transports, and rate
+ limiters with bounded best-effort cleanup.
+
+## Configuration Model
+
+[config/settings.py](config/settings.py) centralizes configuration with Pydantic
+Settings. Dotenv files are configured in 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.
+
+[config/paths.py](config/paths.py) defines managed paths:
+
+- config directory: `~/.fcc`;
+- managed env file: `~/.fcc/.env`;
+- agent workspace: `~/.fcc/agent_workspace`;
+- server log: `~/.fcc/logs/server.log`.
+
+Model routing configuration is tiered:
+
+- `MODEL` is the fallback provider-prefixed model ref.
+- `MODEL_OPUS`, `MODEL_SONNET`, and `MODEL_HAIKU` override Claude model tiers.
+- `ENABLE_MODEL_THINKING` is the global thinking switch.
+- `ENABLE_OPUS_THINKING`, `ENABLE_SONNET_THINKING`, and
+ `ENABLE_HAIKU_THINKING` optionally override thinking by tier.
+
+[api/admin_config.py](api/admin_config.py) defines the Admin UI config manifest
+and writes managed env updates. [api/admin_routes.py](api/admin_routes.py)
+exposes local-only admin endpoints that load, validate, apply, and test config.
+After an apply, settings are cache-cleared. Depending on the changed fields, the
+server either replaces the app provider registry or asks the supervised server to
+restart.
+
+Admin routes call `require_loopback_admin()`, which rejects non-loopback clients
+and non-local origins.
+
+## HTTP Request Flow
+
+[api/routes.py](api/routes.py) exposes the public proxy routes:
+
+- `POST /v1/messages`: Anthropic Messages-compatible streaming requests.
+- `POST /v1/responses`: OpenAI Responses-compatible requests.
+- `POST /v1/messages/count_tokens`: Anthropic token counting.
+- `GET /v1/models`: gateway and Claude-compatible model listing.
+- `GET /health`: health check.
+- `POST /stop`: stop CLI sessions and pending tasks.
+- `HEAD` and `OPTIONS` probes for compatibility on supported endpoints.
+
+Admin routes live beside these in [api/admin_routes.py](api/admin_routes.py).
+
+Authentication is handled by `require_api_key()` in
+[api/dependencies.py](api/dependencies.py). If `ANTHROPIC_AUTH_TOKEN` is blank,
+proxy auth is disabled. Otherwise the token may be supplied through `x-api-key`,
+`Authorization: Bearer ...`, or `anthropic-auth-token`. Comparisons use
+constant-time matching.
+
+`ClaudeProxyService` in [api/services.py](api/services.py) coordinates request
+handling. It validates non-empty messages, resolves models, handles local server
+tools and optimizations, resolves a provider, preflights the upstream request,
+then streams Anthropic SSE back to the caller.
+
+```mermaid
+sequenceDiagram
+ participant Client
+ participant Route as FastAPIRoute
+ participant Service as ClaudeProxyService
+ participant Router as ModelRouter
+ participant Registry as ProviderRegistry
+ participant Provider
+
+ Client->>Route: POST /v1/messages
+ Route->>Route: require_api_key
+ Route->>Service: create_message
+ Service->>Router: resolve model and thinking
+ Service->>Service: server tools or optimizations
+ Service->>Registry: resolve provider
+ Registry->>Provider: cached or new provider
+ Service->>Provider: preflight_stream
+ Service->>Provider: stream_response
+ Provider-->>Client: Anthropic SSE events
+```
+
+OpenAI Responses uses the same core route. `create_response()` converts the
+Responses payload into an Anthropic Messages payload with
+[core/openai_responses/conversion.py](core/openai_responses/conversion.py),
+reuses `create_message()`, then converts the final response or SSE stream back to
+Responses format.
+
+## Model Routing
+
+[api/model_router.py](api/model_router.py) resolves incoming client model names.
+It supports two forms:
+
+- Direct provider model refs such as `nvidia_nim/nvidia/model-name`.
+- Gateway model IDs decoded by [api/gateway_model_ids.py](api/gateway_model_ids.py).
+
+If the incoming model is not direct, `Settings.resolve_model()` maps it by Claude
+tier. Names containing `opus`, `sonnet`, or `haiku` use the matching tier override
+when set, otherwise they fall back to `MODEL`.
+
+The router also resolves thinking. Gateway model IDs can force thinking on or
+off; otherwise `Settings.resolve_thinking()` applies tier-specific thinking
+overrides or the global setting.
+
+`GET /v1/models` advertises:
+
+- configured provider model refs;
+- cached provider-discovered models;
+- no-thinking variants when appropriate;
+- built-in Claude model IDs for compatibility with Claude clients.
+
+Provider model discovery is app-scoped through `ProviderRegistry`, which caches
+model IDs and optional thinking capability metadata for the model-list route and
+admin status.
+
+## Provider Architecture
+
+Provider metadata is neutral and centralized in
+[config/provider_catalog.py](config/provider_catalog.py). Each
+`ProviderDescriptor` declares provider ID, transport type, capabilities,
+credential env var, default base URL, settings attribute names, and proxy support.
+
+[providers/registry.py](providers/registry.py) owns provider factories and the
+runtime registry. It validates that descriptors, factories, and supported IDs are
+in sync, builds shared `ProviderConfig`, checks required credentials, creates
+providers lazily, caches them, refreshes model lists, and cleans up transports.
+
+[providers/base.py](providers/base.py) defines:
+
+- `ProviderConfig`: shared provider settings such as API key, base URL, rate
+ limits, timeouts, proxy, thinking, and logging flags.
+- `BaseProvider`: the provider interface for cleanup, model listing, preflight,
+ and `stream_response()`.
+
+There are two transport families:
+
+- [providers/openai_compat.py](providers/openai_compat.py) implements
+ `OpenAIChatTransport` for providers with OpenAI-compatible
+ `/chat/completions` APIs. These providers convert Anthropic messages and tools
+ into OpenAI chat payloads, then rebuild Anthropic SSE events.
+- [providers/anthropic_messages.py](providers/anthropic_messages.py) implements
+ `AnthropicMessagesTransport` for providers with Anthropic-compatible
+ `/messages` APIs. These providers can send more of the Anthropic request shape
+ natively while still enforcing local stream and error contracts.
+
+Shared provider responsibilities include upstream rate limiting, model listing,
+safe error mapping, transport cleanup, thinking/tool handling, retry or recovery
+where supported, and returning Anthropic SSE strings to the service layer.
+
+### Adding A Provider
+
+1. Add provider metadata to [config/provider_catalog.py](config/provider_catalog.py).
+2. Add credentials and related settings to [config/settings.py](config/settings.py)
+ and [.env.example](.env.example) when user configurable.
+3. Add admin manifest fields in [api/admin_config.py](api/admin_config.py) when
+ the setting should be editable in the Admin UI.
+4. Implement the provider under [providers/](providers/) using the appropriate
+ shared transport family.
+5. Add a factory in [providers/registry.py](providers/registry.py).
+6. Add deterministic tests under [tests/providers/](tests/providers/) and any
+ relevant contract tests.
+7. Add smoke coverage or smoke config in [smoke/](smoke/) when the provider can
+ be exercised live.
+8. Update user-facing provider docs in [README.md](README.md) when users need new
+ setup instructions.
+
+## Protocol Conversion And Streaming Contracts
+
+[core/anthropic/](core/anthropic/) owns Anthropic-side protocol behavior:
+
+- content and message conversion for OpenAI-compatible upstreams;
+- tool schema and tool-result handling;
+- thinking block handling;
+- SSE event formatting through `SSEBuilder`;
+- native Anthropic stream policy;
+- stream recovery and repair helpers;
+- token counting and user-facing error formatting.
+
+[core/openai_responses/](core/openai_responses/) owns OpenAI Responses support:
+
+- Responses request conversion into Anthropic Messages payloads;
+- Anthropic message response conversion into Responses objects;
+- Anthropic SSE conversion into Responses SSE;
+- OpenAI-compatible error envelopes.
+
+Provider code should delegate protocol details to these modules. Avoid copying
+conversion code into individual providers, and avoid provider-to-provider imports
+for shared Anthropic behavior.
+
+## Local Optimizations And Server Tools
+
+[api/optimization_handlers.py](api/optimization_handlers.py) short-circuits
+common low-value client requests before they reach a provider:
+
+- quota probes;
+- command prefix detection;
+- title generation;
+- suggestion mode;
+- filepath extraction.
+
+The service runs these only after model routing and after local server-tool
+handling. Each optimization is controlled by settings flags.
+
+Local `web_search` and `web_fetch` handling lives under
+[api/web_tools/](api/web_tools/). When `ENABLE_WEB_SERVER_TOOLS` is true, the
+service can stream local Anthropic server-tool responses without sending the
+request upstream. [api/web_tools/egress.py](api/web_tools/egress.py) enforces URL
+scheme and private-network restrictions for `web_fetch`.
+
+OpenAI-chat upstream providers are identified by
+`ProviderDescriptor.transport_type == "openai_chat"` in
+[config/provider_catalog.py](config/provider_catalog.py). They cannot safely
+represent Anthropic server-tool blocks, so the service rejects unsupported
+server-tool requests before provider execution instead of performing a lossy
+conversion. Forced `web_search` or `web_fetch` requests are handled locally when
+`ENABLE_WEB_SERVER_TOOLS` is true; otherwise OpenAI-chat upstreams reject them
+and native Anthropic Messages transports may receive them.
+
+## CLI Launchers And Client Adapter Boundary
+
+[cli/adapters/base.py](cli/adapters/base.py) defines `ClientCliAdapter`, the
+boundary for building subprocess commands, building launcher environments,
+parsing stdout lines, and extracting persistent session IDs.
+
+[cli/adapters/claude.py](cli/adapters/claude.py) implements the Claude Code
+adapter:
+
+- `fcc-claude` strips inherited `ANTHROPIC_*` variables, sets
+ `ANTHROPIC_BASE_URL`, enables gateway model discovery, configures the
+ auto-compact window, and forwards `ANTHROPIC_AUTH_TOKEN` when configured.
+- Managed task invocations set `ANTHROPIC_API_URL`, `ANTHROPIC_BASE_URL`,
+ gateway model discovery, non-interactive terminal settings, optional
+ `--resume`, optional `--fork-session`, and `--output-format stream-json`.
+
+[cli/adapters/codex.py](cli/adapters/codex.py) implements the Codex adapter:
+
+- `fcc-codex` strips official OpenAI and Codex credential variables.
+- It creates an ephemeral `fcc` model provider with `wire_api = "responses"` and
+ a base URL pointing at the local proxy `/v1` path.
+- It stores the proxy auth token in `FCC_CODEX_API_KEY` for Codex to read.
+- Managed task invocations use Codex JSON output and map Responses events into
+ the messaging parser event shape.
+
+[cli/manager.py](cli/manager.py) coordinates multiple `CLISession` instances so
+separate conversations can run in separate client CLI processes while replies
+reuse or fork existing sessions.
+
+## Messaging Architecture
+
+Messaging is optional. [api/runtime.py](api/runtime.py) calls
+`create_messaging_platform()` from
+[messaging/platforms/factory.py](messaging/platforms/factory.py) during startup.
+If `MESSAGING_PLATFORM` is `none`, or if the selected platform token is missing,
+the messaging bridge is skipped.
+
+[messaging/handler.py](messaging/handler.py) contains `ClaudeMessageHandler`, the
+platform-agnostic orchestration layer. It receives `IncomingMessage` objects,
+dispatches commands, filters its own status messages, creates or extends a
+message tree, queues work, runs a managed client CLI session, parses CLI events,
+updates transcripts, and persists conversation state.
+
+[messaging/trees/queue_manager.py](messaging/trees/queue_manager.py) preserves
+per-conversation ordering with tree-aware queues. Replies become child nodes, and
+each tree processes one node at a time while separate trees can progress
+independently.
+
+[messaging/session.py](messaging/session.py) persists trees, node-to-tree
+mappings, and message IDs to a JSON file under the managed agent workspace. It
+uses debounced atomic writes and flushes pending saves on shutdown.
+
+```mermaid
+sequenceDiagram
+ participant Platform as DiscordOrTelegram
+ participant Handler as ClaudeMessageHandler
+ participant Queue as TreeQueueManager
+ participant Manager as CLISessionManager
+ participant CLI as ClientCLI
+ participant Proxy as LocalProxy
+
+ Platform->>Handler: IncomingMessage
+ Handler->>Queue: create or extend message tree
+ Queue->>Handler: process node in order
+ Handler->>Manager: get_or_create_session
+ Manager->>CLI: launch JSON stream task
+ CLI->>Proxy: provider-backed API calls
+ CLI-->>Handler: parsed stdout events
+ Handler-->>Platform: status and transcript updates
+```
+
+## Observability, Diagnostics, And Safety
+
+[core/trace.py](core/trace.py) emits structured trace events across stages such
+as ingress, routing, provider, egress, messaging, and client CLI execution. Trace
+payloads are intended to connect API, provider, CLI, and messaging activity
+without requiring raw transport logs by default.
+
+Logging defaults are conservative:
+
+- API payloads and SSE events are not logged raw unless explicitly enabled.
+- Provider and application errors log metadata by default; verbose traceback and
+ message logging are opt-in.
+- Messaging text, transcription previews, CLI diagnostics, and detailed
+ messaging exception strings are controlled by separate diagnostic flags.
+- Values under keys that look like API keys, authorization, tokens, or secrets
+ are redacted by trace helpers where structured traces are emitted.
+
+Important safety boundaries:
+
+- Admin UI and admin APIs are loopback-only.
+- Proxy API auth is controlled by `ANTHROPIC_AUTH_TOKEN`.
+- `web_fetch` egress defaults to configured URL schemes and blocks private
+ network targets unless explicitly allowed.
+- Local provider URLs are user-configurable, but local-provider status checks are
+ exposed only through the local admin API.
+
+## Testing And CI Strategy
+
+Deterministic tests live under [tests/](tests/). They cover API routes, config,
+provider conversion, provider transports, streaming contracts, messaging, CLI
+adapters, import boundaries, provider catalog contracts, and other invariants.
+
+Live and local product tests live under [smoke/](smoke/). See
+[smoke/README.md](smoke/README.md) for target taxonomy, environment variables,
+failure classes, and examples. Smoke tests can launch subprocesses, call real
+providers, touch local model servers, and optionally send bot messages.
+
+CI is defined in [.github/workflows/tests.yml](.github/workflows/tests.yml). It
+enforces:
+
+- `Ban type ignore suppressions`;
+- `ruff-format`;
+- `ruff-check`;
+- `ty`;
+- `pytest`.
+
+Contributor verification commands:
+
+```powershell
+uv run ruff format
+uv run ruff check
+uv run ty check
+uv run pytest
+```
+
+For docs-only architecture changes, a source-link and accuracy review is usually
+sufficient. Full CI can still be run when the doc accompanies runtime changes or
+when maintainers want branch-level assurance.
+
+## Extension Checklists
+
+### Add An Admin Setting
+
+1. Add or expose the setting in [config/settings.py](config/settings.py).
+2. Add the template key to [.env.example](.env.example) if users configure it.
+3. Add a `ConfigFieldSpec` in [api/admin_config.py](api/admin_config.py).
+4. Mark `restart_required` or `session_sensitive` when runtime state cannot be
+ updated in place.
+5. Add tests under [tests/api/](tests/api/) or [tests/config/](tests/config/).
+
+### Add A Client Adapter
+
+1. Implement the `ClientCliAdapter` protocol from
+ [cli/adapters/base.py](cli/adapters/base.py).
+2. Register selection behavior in [cli/adapters/registry.py](cli/adapters/registry.py).
+3. Ensure launcher env construction strips conflicting upstream credentials.
+4. Ensure managed task parsing emits the event shapes expected by
+ [messaging/event_parser.py](messaging/event_parser.py) and
+ [messaging/node_event_pipeline.py](messaging/node_event_pipeline.py).
+5. Add CLI adapter and session-manager tests under [tests/cli/](tests/cli/).
+
+### Add A Messaging Platform
+
+1. Implement `MessagingPlatform` from
+ [messaging/platforms/base.py](messaging/platforms/base.py).
+2. Add construction logic to
+ [messaging/platforms/factory.py](messaging/platforms/factory.py).
+3. Add settings and admin fields for tokens, allowlists, and platform-specific
+ runtime options.
+4. Add rendering profile support in
+ [messaging/rendering/profiles.py](messaging/rendering/profiles.py) if needed.
+5. Add fake-platform deterministic tests and optional live smoke targets.
+
+### Add Protocol Behavior
+
+1. Put shared Anthropic behavior under [core/anthropic/](core/anthropic/).
+2. Put OpenAI Responses behavior under
+ [core/openai_responses/](core/openai_responses/).
+3. Keep provider-specific request quirks inside the provider module or transport
+ subclass.
+4. Add stream contract tests under [tests/contracts/](tests/contracts/) or
+ [tests/core/](tests/core/) when event shape or ordering changes.
+5. Add provider tests when the behavior changes upstream request or response
+ handling.
+
+## Maintenance Rules For This Document
+
+Update this file when a change adds or meaningfully changes:
+
+- a top-level package or installable runtime boundary;
+- a public route or wire protocol;
+- startup, shutdown, or resource ownership;
+- configuration precedence or managed config behavior;
+- provider registry, catalog, or transport architecture;
+- model routing or thinking behavior;
+- CLI adapter behavior;
+- messaging platform behavior;
+- protocol conversion or streaming contracts;
+- CI, smoke, or verification strategy.
+
+Docs-only changes to this file do not require a semver bump. Production code
+changes still follow the versioning rules in [AGENTS.md](AGENTS.md) and
+[CLAUDE.md](CLAUDE.md).
diff --git a/api/services.py b/api/services.py
index cfc34f69..df1985c4 100644
--- a/api/services.py
+++ b/api/services.py
@@ -12,6 +12,7 @@ from fastapi.responses import JSONResponse, StreamingResponse
from loguru import logger
from pydantic import BaseModel
+from config.provider_catalog import PROVIDER_CATALOG
from config.settings import Settings
from core.anthropic import get_token_count, get_user_facing_error_message
from core.anthropic.sse import ANTHROPIC_SSE_RESPONSE_HEADERS
@@ -46,7 +47,11 @@ TokenCounter = Callable[[list[Any], str | list[Any] | None, list[Any] | None], i
ProviderGetter = Callable[[str], BaseProvider]
# Providers that use ``/chat/completions`` + Anthropic-to-OpenAI conversion (not native Messages).
-_OPENAI_CHAT_UPSTREAM_IDS = frozenset({"nvidia_nim", "opencode", "opencode_go"})
+_OPENAI_CHAT_UPSTREAM_IDS = frozenset(
+ provider_id
+ for provider_id, descriptor in PROVIDER_CATALOG.items()
+ if descriptor.transport_type == "openai_chat"
+)
def anthropic_sse_streaming_response(
diff --git a/pyproject.toml b/pyproject.toml
index 9296d8f2..44036f5a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "2.1.2"
+version = "2.1.3"
description = "Middleware between Claude Code CLI (Anthropic API) and NVIDIA NIM"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/tests/api/test_web_server_tools.py b/tests/api/test_web_server_tools.py
index f53e32a9..6d6df63a 100644
--- a/tests/api/test_web_server_tools.py
+++ b/tests/api/test_web_server_tools.py
@@ -21,6 +21,7 @@ from api.web_tools.outbound import (
)
from api.web_tools.request import is_web_server_tool_request
from api.web_tools.streaming import stream_web_server_tool_response
+from config.provider_catalog import PROVIDER_CATALOG
from config.settings import Settings
from core.anthropic.stream_contracts import (
assert_anthropic_stream_contract,
@@ -34,6 +35,16 @@ _STRICT_EGRESS = WebFetchEgressPolicy(
allow_private_network_targets=False,
allowed_schemes=frozenset({"http", "https"}),
)
+_OPENAI_CHAT_PROVIDER_IDS = tuple(
+ provider_id
+ for provider_id, descriptor in PROVIDER_CATALOG.items()
+ if descriptor.transport_type == "openai_chat"
+)
+_ANTHROPIC_MESSAGES_PROVIDER_IDS = tuple(
+ provider_id
+ for provider_id, descriptor in PROVIDER_CATALOG.items()
+ if descriptor.transport_type == "anthropic_messages"
+)
class FixedProviderModelRouter(ModelRouter):
@@ -94,14 +105,17 @@ def test_web_server_tool_not_detected_when_forced_name_missing_from_tools():
assert not is_web_server_tool_request(request)
-def test_service_rejects_forced_server_tool_on_openai_when_disabled():
[email protected]("provider_id", _OPENAI_CHAT_PROVIDER_IDS)
+def test_service_rejects_forced_server_tool_on_openai_when_disabled(
+ provider_id: str,
+):
"""OpenAI Chat upstreams cannot run forced server tools without the local handler."""
settings = Settings()
assert settings.enable_web_server_tools is False
service = ClaudeProxyService(
settings,
provider_getter=lambda _: MagicMock(),
- model_router=FixedProviderModelRouter(settings, "nvidia_nim"),
+ model_router=FixedProviderModelRouter(settings, provider_id),
)
request = MessagesRequest(
model="claude-haiku-4-5-20251001",
@@ -579,12 +593,15 @@ async def test_drain_response_body_capped_stops_after_first_chunk_when_oversized
assert chunk_calls["n"] == 1
-def test_service_rejects_listed_server_tools_on_openai_chat() -> None:
[email protected]("provider_id", _OPENAI_CHAT_PROVIDER_IDS)
+def test_service_rejects_listed_server_tools_on_openai_chat(
+ provider_id: str,
+) -> None:
settings = Settings()
service = ClaudeProxyService(
settings,
provider_getter=lambda _: MagicMock(),
- model_router=FixedProviderModelRouter(settings, "nvidia_nim"),
+ model_router=FixedProviderModelRouter(settings, provider_id),
)
request = MessagesRequest(
model="m",
@@ -596,8 +613,11 @@ def test_service_rejects_listed_server_tools_on_openai_chat() -> None:
service.create_message(request)
-def test_listed_server_tools_routed_on_open_router() -> None:
- """Native Anthropic transport may receive listed server tool definitions."""
[email protected]("provider_id", _ANTHROPIC_MESSAGES_PROVIDER_IDS)
+def test_listed_server_tools_routed_on_anthropic_messages_providers(
+ provider_id: str,
+) -> None:
+ """Native Anthropic transports may receive listed server tool definitions."""
settings = Settings()
async def fake_stream(*_a, **_k):
@@ -609,7 +629,7 @@ def test_listed_server_tools_routed_on_open_router() -> None:
service = ClaudeProxyService(
settings,
provider_getter=lambda _: mock_provider,
- model_router=FixedProviderModelRouter(settings, "open_router"),
+ model_router=FixedProviderModelRouter(settings, provider_id),
)
request = MessagesRequest(
model="m",
@@ -621,8 +641,11 @@ def test_listed_server_tools_routed_on_open_router() -> None:
mock_provider.preflight_stream.assert_called()
-def test_listed_server_tools_routed_on_zai() -> None:
- """Z.ai uses native Anthropic Messages; listed server tools are not OpenAI-chat blocked."""
[email protected]("provider_id", _ANTHROPIC_MESSAGES_PROVIDER_IDS)
+def test_forced_server_tools_routed_on_anthropic_messages_providers_when_local_disabled(
+ provider_id: str,
+) -> None:
+ """Native Anthropic transports may receive forced server tools when local tools are off."""
settings = Settings()
async def fake_stream(*_a, **_k):
@@ -634,13 +657,14 @@ def test_listed_server_tools_routed_on_zai() -> None:
service = ClaudeProxyService(
settings,
provider_getter=lambda _: mock_provider,
- model_router=FixedProviderModelRouter(settings, "zai"),
+ model_router=FixedProviderModelRouter(settings, provider_id),
)
request = MessagesRequest(
model="m",
max_tokens=20,
messages=[Message(role="user", content="q")],
tools=[Tool(name="web_search", type="web_search_20250305")],
+ tool_choice={"type": "tool", "name": "web_search"},
)
service.create_message(request)
mock_provider.preflight_stream.assert_called()
diff --git a/tests/contracts/test_architecture_contracts.py b/tests/contracts/test_architecture_contracts.py
index 10091213..fb2c1bdb 100644
--- a/tests/contracts/test_architecture_contracts.py
+++ b/tests/contracts/test_architecture_contracts.py
@@ -3,6 +3,30 @@ from __future__ import annotations
import re
import tomllib
from pathlib import Path
+from urllib.parse import unquote, urlsplit
+
+
+def test_architecture_document_exists() -> None:
+ repo_root = Path(__file__).resolve().parents[2]
+
+ assert (repo_root / "ARCHITECTURE.md").is_file()
+
+
+def test_architecture_document_relative_links_resolve() -> None:
+ repo_root = Path(__file__).resolve().parents[2]
+ architecture = repo_root / "ARCHITECTURE.md"
+ text = architecture.read_text(encoding="utf-8")
+
+ missing: list[str] = []
+ for match in re.finditer(r"(?<!!)\[[^\]]+\]\(([^)]+)\)", text):
+ raw_target = match.group(1).strip()
+ target = raw_target.split("#", 1)[0]
+ if not target or urlsplit(target).scheme:
+ continue
+ if not (repo_root / unquote(target)).exists():
+ missing.append(raw_target)
+
+ assert missing == []
def test_smoke_lib_has_no_sse_shim_module() -> None:
diff --git a/uv.lock b/uv.lock
index aa2106a8..6fabc258 100644
--- a/uv.lock
+++ b/uv.lock
@@ -561,7 +561,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "2.1.2"
+version = "2.1.3"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },