Free Claude Code (FCC)

Smoke test results are stored in .smoke-results/. Failures and skips are categorized into the following classes:

• product_failure: The application accepted the scenario but returned the wrong shape, crashed, leaked state, or violated the product contract. (Failure)
• harness_bug: The smoke test or driver made an invalid assumption. (Failure)
• missing_env: Required credentials, binary, provider config, or opt-in flag is absent. (Skip, unless the provider was explicitly selected in FCC_SMOKE_PROVIDER_MATRIX)
• upstream_unavailable: A real provider or bot API is not reachable. (Skip, unless the provider was explicitly selected in FCC_SMOKE_PROVIDER_MATRIX)
• probe_timeout: The smoke driver reached the target, but the CLI/probe did not complete within the timeout. (Skip, unless the provider was explicitly selected in FCC_SMOKE_PROVIDER_MATRIX)
• target_disabled: Skipped because FCC_SMOKE_TARGETS intentionally selected a different target. (Skip)

The system uses a layered architecture to convert between Anthropic-style protocols and OpenAI-compatible upstreams.

• Anthropic Protocol Ownership: src/free_claude_code/core/anthropic/ manages Anthropic-side behavior, including models.py (Messages and token-count wire requests), tool schema/result handling, and thinking block handling.
• Streaming Lifecycle: Managed via src/free_claude_code/core/anthropic/streaming, which handles the neutral stream ledger, SSE emission, and tool repair.
• Role Mapping: When converting to OpenAI-compatible upstreams, the system maps top-level system content to leading system messages and converts inline system content into ordered user turns. It ensures strict chat templates by coalescing adjacent user content and using whitespace-only assistant boundaries to close tool rounds.
• Image Conversion: Anthropic base64 and URL image sources are converted to OpenAI image_url content parts. This is a pure protocol operation and does not fetch remote content.

Reasoning is managed via a provider-neutral ReasoningPolicy defined in core/reasoning.py. This policy consists of three components:

1. control: The state of reasoning (provider default, explicitly off, or explicitly on).
2. effort: The client's requested effort level.
3. budget_tokens: An exact positive integer budget if supplied.

The FCC Numeric Scale: When a provider requires a named effort but the client provides a numeric budget, FCC maps the budget to its internal scale:

• minimal / low: 512 tokens
• medium: 1024 tokens
• high: 2048 tokens
• xhigh: 4096 tokens
• max: 8192 tokens

Rules for Implementation:

• No Model-Name Inspection: Never inspect upstream model names to decide reasoning behavior; use the policy.
• Single Encoder: Each provider profile must have exactly one reasoning encoder responsible for writing the provider's specific computation and reasoning-output fields.
• Precedence: Exact client budgets take precedence over named effort scales.
• Reasoning Replay: Replaying reasoning history is a separate decision from the computation control. Profiles must explicitly choose how to handle prior state (e.g., <think> tags, native reasoning_content, or no replay).

The provider system is split into three distinct layers to separate metadata, runtime lifecycle, and transport implementation:

1. Metadata Layer (config/provider_catalog.py): A centralized, neutral catalog of ProviderDescriptor objects. It defines provider IDs, display names, authentication types, locality, and configuration requirements (like environment variables or base URLs). It does not select the actual adapter.
2. Runtime Layer (providers/runtime/): Manages the lifecycle of a provider generation. It handles construction policies, lazy instantiation, admission controllers (rate limiting/concurrency), and cleanup. The ProviderRuntimeManager manages process-lifetime state, while ProviderRuntime manages single-generation resources.
3. Implementation Layer (providers/): Contains the actual adapters. Most providers use the OpenAIChatProvider (an OpenAI-compatible implementation), while specialized providers are created only for upstreams with unique behaviors (e.g., Groq's reasoning vocabulary or Google's extra_body construction).

Key Abstractions:

• ProviderConfig: A frozen internal value containing shared settings like API keys, base URLs, and timeouts.
• BaseProvider: The abstract base defining the contract for list_model_infos(), preflight_stream(), and stream_response().
• ProviderModelInfo: An immutable value representing model capabilities, owned by the application layer but populated by provider-specific modules.

The codebase is organized into specific functional boundaries to maintain a least-privilege dependency policy:

Stream recovery is managed by src/free_claude_code/providers/stream_recovery.py using a ProviderRetrySession.

• Retry Budget: A single five-attempt budget is shared across the entire logical execution (initial opening, request-shape corrections, replay, continuation, and tool repair). There are no nested retry counters.
• Backoff Strategy: Deterministic corrections retry immediately. Transient failures use exponential backoff with jitter and respect the Retry-After header.
• Partial Output: If partial output exists, the final attempt is reserved for continuation or tool repair rather than a full replay. Completed tool calls can be salvaged without an upstream attempt.
• Failure Scopes:
  • Pre-acceptance: Failures before the first chunk are received participate in provider-wide coordinated recovery.
  • Post-acceptance: Failures after the first chunk are request-local to prevent one interrupted connection from affecting parallel streams.

The ModelRouter resolves incoming client model names into concrete provider models. It supports two primary formats:

1. Direct Provider Model Refs: e.g., nvidia_nim/nvidia/model-name. These use the root policy.
2. Gateway Model IDs: Decoded via core/gateway_model_ids.py. These are mapped by Claude tier (e.g., names containing fable, opus, sonnet, or haiku).

Key Routing Behaviors:

• Tier Overrides: If a gateway model name contains a Claude tier keyword, it uses the matching tier override if configured; otherwise, it falls back to the default MODEL.
• Reasoning Preference: The router selects the applicable reasoning preference (e.g., 'no-thinking' variants force off).
• Identity Separation: The system maintains a split between the original_model (the stable gateway model exposed in responses/traces) and the provider model sent upstream. Providers and local tools must never publish the private upstream model as the response model.

Voice-note processing is managed by a shared orchestration layer (voice_flow.py) that handles the transition from audio input to transcription and eventually to an IncomingMessage.

The Lifecycle:

1. Validation & Setup: Performs file-size validation and manages temporary file cleanup.
2. Reservation: Reserves an opaque claim in the PendingVoiceRegistry (owned by messaging/voice.py) before status delivery.
3. Transcription: Uses a Transcriber protocol. The system supports either a local Whisper TranscriptionService or a provider-owned NvidiaNimTranscriber.
4. Handoff: Once transcribed, the process hands off to the IncomingMessage flow.
5. Cancellation: An explicit /stop or /clear atomically removes the claim from the registry and cancels the associated child task. A cancellation that 'wins' turns late status, transcription, or callback completion into cleanup-only work.

Important: Changing credentials for an active voice backend (via Admin) requires a restart, as the local service retains immutable runtime settings for its pipeline.