## Problem
Admin config was a single responsibility hub with manually duplicated
provider metadata. Provider labels, fields, template loading,
validation, persistence, and status lived in one place.
## Changes
| Before | After |
| --- | --- |
| Admin config lived in one large `api/admin_config.py` module. | Admin
config lives in package modules for manifest, sources, values,
validation, persistence, and status. |
| Provider admin fields and UI labels were manually duplicated. |
Provider admin fields and display names derive from `PROVIDER_CATALOG`
with admin-only help overrides. |
| `fcc-init` and Admin UI loaded `.env.example` separately. | `fcc-init`
and Admin UI use shared `config.env_template` loading. |
| Architecture docs pointed to the old admin config module. |
Architecture docs describe the package owners and catalog-driven
provider manifest. |
<!-- greptile_comment -->
<details open><summary><h3>Greptile Summary</h3></summary>
This PR refactors admin configuration into a catalog-driven package. The
main changes are:
- Split the former monolithic `api/admin_config.py` into manifest,
source loading, value presentation, validation, persistence, and
provider status modules.
- Generate provider admin fields and display names from
`PROVIDER_CATALOG` with admin-specific help overrides.
- Share `.env.example` loading between `fcc-init` and Admin UI defaults
through `config.env_template`.
- Update admin routes, Admin UI provider labels, architecture docs,
version metadata, and contract/API tests for the new module layout.
</details>
<h3>Confidence Score: 5/5</h3>
The refactor appears merge-safe with no code issues identified in the
reviewed changes.
The package split, catalog-driven provider metadata, shared environment
template loading, route updates, and tests/docs changes are cohesive and
covered by corresponding contract/API/CLI test updates.
<details><summary><h3><a href="https://www.greptile.com/trex"><img
alt="T-Rex"
src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg"
height="20" align="absmiddle"></a> T-Rex Logs</h3></summary>
**What T-Rex did**
- T-Rex ran manifest validation for catalog provider before and after
routes, capturing base and head responses and catalog-alignment checks,
and confirmed the validation completed successfully.
- T-Rex evaluated the shared-env-template scenarios, observing the
before run with no config.env\_template module and the after run with
the module present, with patched loader values and all consistency
checks passing, and the run exited with code 0.
- T-Rex executed the package-admin-workflow validation, verifying the
base and after import paths, the load/validate/write workflow produced
matching outputs, and the run completed with exit code 0.
<a
href="https://app.greptile.com/trex/runs/12529845/artifacts"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifactsDark.svg?v=1"><source
media="(prefers-color-scheme: light)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=1"><img
alt="View all artifacts"
src="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=1"
height="32"></picture></a>
<sub><a href="https://www.greptile.com/trex"><img alt="T-Rex"
src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg"
height="14" align="absmiddle"></a> Ran code and verified through
T-Rex</sub>
</details>
<sub>Reviews (1): Last reviewed commit: ["Refactor admin config into
catalog-drive..."](https://github.com/alishahryar1/free-claude-code/commit/d6239d7953fce75d435b8d6a20536c1aff53aa88)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=40315222)</sub>
<!-- /greptile_comment -->
## Problem
Provider construction, model discovery, validation, and cleanup lived in
one registry module. API and admin routes depended on registry-shaped
app state and legacy process-level provider helpers.
## Changes
| Before | After |
| --- | --- |
| `providers.registry` mixed provider factories, config, cache,
discovery, validation, and cleanup. | `providers.runtime` splits
factories, config, cache, model cache, discovery, validation, and
runtime orchestration. |
| API and admin routes read `app.state.provider_registry` and sometimes
created registries ad hoc. | API and admin routes use app-scoped
`ProviderRuntime` through `app.state.provider_runtime`. |
| `api.dependencies` kept process-global provider cache helpers. |
`api.dependencies` resolves providers only through the app-scoped
runtime. |
| Registry-shaped tests preserved old internal boundaries. |
Runtime-shaped tests assert provider config, construction, cache,
discovery, validation, and import boundaries. |
<!-- greptile_comment -->
<details open><summary><h3>Greptile Summary</h3></summary>
This PR moves provider lifecycle ownership from the old registry module
into an app-scoped runtime package. The main changes are:
- Split provider config, factory wiring, instance cache, model cache,
discovery, validation, and cleanup into `providers.runtime` modules.
- Updated API and admin routes to resolve providers and model metadata
through `app.state.provider_runtime`.
- Removed legacy process-global provider helpers and the deleted
`providers.registry` module.
- Updated docs, smoke metadata, import-boundary checks, and tests for
the new runtime ownership model.
- Bumped the package version and lockfile metadata for the production
refactor.
</details>
<h3>Confidence Score: 5/5</h3>
The provider runtime refactor appears merge-safe with no identified
blocking issues.
The changes consistently move provider ownership to app-scoped runtime
modules and update API, admin, docs, smoke metadata, import-boundary
checks, and tests around that architecture.
<details><summary><h3><a href="https://www.greptile.com/trex"><img
alt="T-Rex"
src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg"
height="20" align="absmiddle"></a> T-Rex Logs</h3></summary>
**What T-Rex did**
- Ran a baseline and head comparison of provider registry and runtime
states, verifying the after-state shows head
state\_has\_provider\_registry=False and
state\_has\_provider\_runtime=True, that GET /v1/models and admin
endpoints respond with 200, and that provider\_resolver\_called via
runtime, with assertions passing.
- Verified that the four focused provider-runtime contract tests passed
in both the before and after refactor runs, including runtime split
checks, with exit code 0.
- Identified environmental blockers that prevented the smoke-runtime
workflow from running, including uv unavailability, missing pytest for
/usr/local/bin/python, and Python 3.11 being used despite pyproject.toml
requiring \>=3.14.
<a
href="https://app.greptile.com/trex/runs/12528505/artifacts"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifactsDark.svg?v=1"><source
media="(prefers-color-scheme: light)"
srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=1"><img
alt="View all artifacts"
src="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=1"
height="32"></picture></a>
<sub><a href="https://www.greptile.com/trex"><img alt="T-Rex"
src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg"
height="14" align="absmiddle"></a> Ran code and verified through
T-Rex</sub>
</details>
<sub>Reviews (1): Last reviewed commit: ["Refactor provider runtime
ownership"](https://github.com/alishahryar1/free-claude-code/commit/01d589488185c1f85112f1a49c47f04512846161)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=40312173)</sub>
<!-- /greptile_comment -->
## Problem
The CLI package preserved a generic adapter layer and managed Codex
parser path that did not match the supported customer workflows.
Messaging runs Claude Code sessions, while Codex is supported through
`fcc-codex` and extensions.
## Changes
| Before | After |
| --- | --- |
| `fcc-claude` and `fcc-codex` shared generic adapter plumbing. |
`fcc-claude` and `fcc-codex` use explicit launcher modules. |
| Messaging depended on a generic CLI session abstraction. | Messaging
depends on managed Claude Code sessions. |
| Codex catalog generation lived as a top-level CLI helper. | Codex
catalog generation lives under the Codex launcher owner. |
| Tests asserted deleted internal adapter shapes. | Tests assert
launcher, managed-Claude, and customer-surface behavior. |
## Summary
- Split monolithic `core/openai_responses/conversion.py` and `sse.py`
into focused protocol modules (input, output, stream, tools, reasoning,
events, etc.) behind an `OpenAIResponsesAdapter` facade.
- Wire `ClaudeProxyService.create_response()` through the adapter
instead of importing conversion helpers directly, tightening the
API/import boundary.
- Add Codex bridging for Responses `custom_tool_call` items and document
the adapter architecture in `ARCHITECTURE.md`.
## Test plan
- [x] `uv run pytest tests/core/openai_responses/
tests/api/test_openai_responses.py tests/cli/test_adapters.py
tests/contracts/test_import_boundaries.py`
- [x] Full CI via `.\scripts\ci.ps1`
Update live smoke model defaults for NIM, OpenRouter, and Gemini; normalize tool-call indexes; downgrade DeepSeek forced tool_choice; and add coverage for the provider smoke fixes.
Route these providers through POST /messages with vendor headers and bases (including Kimi model list on OpenAI /v1/models). Remove Z.ai from OpenAI-chat server-tool rejection; extend tests and README.
## Summary
Adds support for the **OpenCode Go** subscription gateway at
`opencode.ai/zen/go/v1`, as requested in #504.
OpenCode Go exposes the same OpenAI-compatible Chat Completions API as
OpenCode Zen, so the implementation reuses `OpenCodeProvider` with a
configurable `provider_name` parameter — avoiding code duplication.
### Changes
- **Provider**: `OpenCodeProvider` now accepts `provider_name` (defaults
to `"OPENCODE"` for backward compatibility)
- **Catalog**: New `opencode_go` descriptor with correct base URL,
credential, and capabilities
- **Registry**: `_create_opencode_go` factory that passes
`provider_name="OPENCODE_GO"`
- **Settings**: `opencode_go_api_key` and `opencode_go_proxy` fields
- **Admin UI**: OpenCode Go API key, proxy, and smoke model config
fields
- **API services**: `opencode_go` added to OpenAI Chat Completions
upstream IDs
- **Smoke config**: Default smoke model `opencode_go/gpt-5.3-codex`
- **Tests**: New test for base URL, provider name, and API key; existing
tests updated
## Test plan
- [x] `test_opencode_go_provider_config_uses_correct_base_url_and_name`
— passes
- [x] `test_create_provider_instantiates_each_builtin` — covers
opencode_go
- [x]
`test_provider_and_platform_registries_include_advertised_builtins` —
covers opencode_go
- [x] `uv run ruff format`, `ruff check`, `ty check`, `pytest` — pass
locally on Python 3.14
Closes#504.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: Alishahryar1 <alishahryar2@gmail.com>
Registers FIREWORKS_API_KEY / FIREWORKS_PROXY in api/admin_config FIELDS so the UI can set credentials and provider status stays accurate.
Adds admin apply test and contract guards linking PROVIDER_CATALOG to FIELD_BY_KEY; updates .env.example.
## Summary
- Refactors the admin interface into focused views and simplifies the
header (removes noisy status labels; hides managed-source labels where
appropriate).
- Fixes Claude runtime settings handling, reduces Z.ai base URL leakage
in the admin UI, and streamlines API startup logging.
- Updates configuration and catalog behavior (including `.env.example` /
README), and expands automated tests around admin, app lifespan, and
config/registry behavior.
## Test plan
- [ ] `uv run ruff format`, `uv run ruff check`, `uv run ty check`, `uv
run pytest`
- [ ] Smoke the admin UI: navigation between views, settings save/load,
no sensitive URL leakage in the UI
- [ ] Confirm API startup logs are readable and not overly verbose in
normal operation
## Summary
- split the admin UI into Providers, Model Config, and Messaging views
- remove generated env, diagnostics, smoke, managed-label, and fixed
cloud/runtime settings from the visible admin UX
- make Z.ai base URL, Claude workspace, and Claude CLI binary fixed
app-level behavior instead of managed env fields
## Verification
- uv run ruff format
- uv run ruff check
- uv run ty check
- uv run pytest
- Default LOG_FILE to logs/server.log in settings and admin config
- Create log parent directories in configure_logging
- Gitignore /logs/, /server.*.log; keep server.log for root override
- Add test for nested log path mkdir
Claude Code newer versions send a `betas` list in the request body (e.g.
"interleaved-thinking-2025-05-14"). This landed in `__pydantic_extra__`
and triggered `_openai_reject_native_only_top_level_fields`, surfacing
as "Invalid request sent to provider." for all OpenAI Chat upstreams
(kimi, nvidia_nim).
Declare `betas` on both `MessagesRequest` and `TokenCountRequest` with
`exclude=True` so it is accepted from clients but never forwarded to any
provider body.
## What
Fixes the 422 error returned by the proxy when Claude Code v2.1.128+
sends PDF context as Anthropic `document` blocks, plus two related
DeepSeek-only issues uncovered while debugging.
Closes#357.
## Why
Claude Code now attaches PDFs/files as `document` content blocks. The
`Message.content` union didn't include that variant, so every follow-up
turn after a PDF read returned `422 Unprocessable Content` from the
proxy itself (before the request ever reached DeepSeek).
## Changes
- `api/models/anthropic.py`: new `ContentBlockDocument`, added to
`Message.content` union.
- `providers/deepseek/request.py`:
- `_strip_unsupported_attachment_blocks` — silently drops
`image`/`document` blocks for DeepSeek.
- `_serialize_tool_result_content` + `_normalize_tool_result_content` —
coerces `tool_result.content` to a string per DeepSeek's API contract.
- Hooked into `build_request_body` (strip before validation, normalize
before send).
- `tests/providers/test_deepseek.py`: +4 tests, 1 legacy test updated.
## Verification
- `uv run ruff format` ✅
- `uv run ruff check` ✅
- `uv run ty check` ✅
- `uv run pytest` ✅ (1194 passed)
- Manual: `claude-deepseek` against a PDF no longer 422s.
## Scope / non-goals
- No README change (per CONTRIBUTING).
- Image/document blocks for DeepSeek are stripped, not converted to text
— Claude Code already ships the extracted text in the paired
tool_result.
- No changes to other providers.
---------
Co-authored-by: Alishahryar1 <alishahryar2@gmail.com>
Ali Khokhar
