feat(rotator_library): ✨ add OpenAI Codex provider with Responses API support (#33)

* feat(rotator_library): ✨ add OpenAI Codex provider with Responses API support

Adds a new provider for OpenAI Codex models (GPT-5, GPT-5.1, GPT-5.2, Codex, Codex Mini)
via the ChatGPT Responses API with OAuth PKCE authentication.

Key features:
- OAuth base class for OpenAI authentication with PKCE flow and token refresh
- Responses API streaming with SSE event handling
- Reasoning/thinking output with configurable effort levels (minimal to xhigh)
- Tool calling support translated from OpenAI format
- System prompt validation using official opencode prompt
- Usage tracking with proper litellm.Usage objects

Files added:
- codex_provider.py: Main provider implementation
- openai_oauth_base.py: OAuth base class with PKCE support
- codex_prompt.txt: Required system prompt for API validation

* fix(codex): 🐛 prefix model names with provider identifier

Models must be returned with the 'codex/' prefix (e.g., 'codex/gpt-5.2')
to match the convention used by other providers like antigravity.
This ensures proper provider routing in the RotatingClient.

* feat(codex): ✨ add reasoning effort model variants

Exposes reasoning effort levels as model variants:
- codex/gpt-5.2:low, :medium, :high, :xhigh
- codex/gpt-5.1:low, :medium, :high
- And similar for all codex models

This allows clients to control reasoning effort by model name,
similar to how gemini models use :thinking suffix.

Total models: 9 base + 30 reasoning variants = 39 models

* feat(codex): ✨ add identity override for user system prompt precedence

Injects an identity override as the first user message that tells the model
to prioritize user-provided system prompts over the required opencode
instructions. This mirrors the pattern used by Antigravity provider.

Message order:
1. Identity override (<system_override> tag)
2. User's system message (converted to user message)
3. Rest of conversation

Controlled by CODEX_INJECT_IDENTITY_OVERRIDE env var (default: true)

* docs: 📝 add Codex provider configuration to .env.example

Documents all Codex environment variables:
- CODEX_REASONING_EFFORT: low/medium/high/xhigh
- CODEX_REASONING_SUMMARY: auto/concise/detailed/none
- CODEX_REASONING_COMPAT: think-tags/raw/none
- CODEX_INJECT_IDENTITY_OVERRIDE: true/false
- CODEX_INJECT_INSTRUCTION: true/false
- CODEX_EMPTY_RESPONSE_ATTEMPTS: retry count
- CODEX_EMPTY_RESPONSE_RETRY_DELAY: seconds
- CODEX_OAUTH_PORT: callback port

* fix(codex): 🐛 register Codex in provider factory for OAuth TUI

Adds Codex to PROVIDER_MAP so it appears in the credential tool's
"Add OAuth Credential" menu alongside other OAuth providers.

* feat(codex): ✨ add quota tracking with rate limit header parsing

Integrate CodexQuotaTracker mixin into CodexProvider to track API usage
via response headers and periodic quota API calls. Enables smart
credential selection based on remaining quota and automatic cooldowns
when limits are approached.

Signed-off-by: Moeeze Hassan <fammas.maz@gmail.com>

* feat(codex): add gpt-5.3-codex to model list and reasoning config

* feat(codex): wire quota header updates to UsageManager for TUI display

- Add set_usage_manager() to CodexQuotaTracker mixin
- Push parsed rate limit headers to UsageManager via update_quota_baseline
- Inject UsageManager reference during RotatingClient initialization
- Enables quota status display in TUI after each Codex API response

* feat(codex): default to sequential credential selection for token caching

Sequential mode reuses the same credential across requests, enabling
upstream token caching on the Codex API.

* fix(codex): standardize ChatGPT-Account-Id header casing

Match the exact capitalization used by the Codex CLI, consistent with
codex_quota_tracker.py. Addresses PR review feedback.

Author: b3nw

.env.example

@@ -404,6 +404,65 @@
 # Default: 8085 (same as Gemini CLI, shared)
 # ANTIGRAVITY_OAUTH_PORT=8085
 
+# ------------------------------------------------------------------------------
+# | [CODEX] OpenAI Codex Provider Configuration                                |
+# ------------------------------------------------------------------------------
+#
+# Codex provider uses OAuth authentication with OpenAI's ChatGPT backend API.
+# Credentials are stored in oauth_creds/ directory as codex_oauth_*.json files.
+#
+
+# --- Reasoning Effort ---
+# Controls how much "thinking" the model does before responding.
+# Higher effort = more thorough reasoning but slower responses.
+#
+# Available levels (model-dependent):
+#   - low: Minimal reasoning, fastest responses
+#   - medium: Balanced (default)
+#   - high: More thorough reasoning
+#   - xhigh: Maximum reasoning (gpt-5.2, gpt-5.2-codex, gpt-5.1-codex-max only)
+#
+# Can also be controlled per-request via:
+#   1. Model suffix: codex/gpt-5.2:high
+#   2. Request param: "reasoning_effort": "high"
+#
+# CODEX_REASONING_EFFORT=medium
+
+# --- Reasoning Summary ---
+# Controls how reasoning is summarized in responses.
+# Options: auto, concise, detailed, none
+# CODEX_REASONING_SUMMARY=auto
+
+# --- Reasoning Output Format ---
+# How reasoning/thinking is presented in responses.
+# Options:
+#   - think-tags: Wrap in <think>...</think> tags (default, matches other providers)
+#   - raw: Include reasoning as-is
+#   - none: Don't include reasoning in output
+# CODEX_REASONING_COMPAT=think-tags
+
+# --- Identity Override ---
+# When true, injects an override that tells the model to prioritize
+# user-provided system prompts over the required opencode instructions.
+# CODEX_INJECT_IDENTITY_OVERRIDE=true
+
+# --- Instruction Injection ---
+# When true, injects the required opencode system instruction.
+# Only disable if you know what you're doing (API may reject requests).
+# CODEX_INJECT_INSTRUCTION=true
+
+# --- Empty Response Handling ---
+# Number of retry attempts when receiving empty responses.
+# CODEX_EMPTY_RESPONSE_ATTEMPTS=3
+
+# Delay (seconds) between empty response retries.
+# CODEX_EMPTY_RESPONSE_RETRY_DELAY=2
+
+# --- OAuth Configuration ---
+# OAuth callback port for Codex interactive authentication.
+# Default: 8086
+# CODEX_OAUTH_PORT=8086
+
 # ------------------------------------------------------------------------------
 # | [ADVANCED] Debugging / Logging                                              |
 # ------------------------------------------------------------------------------

src/rotator_library/client/rotating_client.py

@@ -294,6 +294,14 @@ async def initialize_usage_managers(self) -> None:
                 lib_logger.info(
                     f"Usage managers initialized: {', '.join(sorted(summaries))}"
                 )
+
+            # Inject usage manager references into providers that support it
+            # (e.g., CodexProvider via CodexQuotaTracker for header-based quota updates)
+            for provider, manager in self._usage_managers.items():
+                instance = self._get_provider_instance(provider)
+                if instance and hasattr(instance, "set_usage_manager"):
+                    instance.set_usage_manager(manager)
+
             self._usage_initialized = True
 
     async def close(self):

src/rotator_library/credential_manager.py

@@ -18,6 +18,7 @@
     "qwen_code": Path.home() / ".qwen",
     "iflow": Path.home() / ".iflow",
     "antigravity": Path.home() / ".antigravity",
+    "codex": Path.home() / ".codex",
     # Add other providers like 'claude' here if they have a standard CLI path
 }
 
@@ -28,6 +29,7 @@
     "antigravity": "ANTIGRAVITY",
     "qwen_code": "QWEN_CODE",
     "iflow": "IFLOW",
+    "codex": "CODEX",
 }
 
 

src/rotator_library/credential_tool.py

@@ -66,6 +66,7 @@ def _ensure_providers_loaded():
     "qwen_code": "Qwen Code",
     "iflow": "iFlow",
     "antigravity": "Antigravity",
+    "codex": "OpenAI Codex",
 }
 
 

src/rotator_library/provider_factory.py

@@ -7,12 +7,14 @@
 from .providers.qwen_auth_base import QwenAuthBase
 from .providers.iflow_auth_base import IFlowAuthBase
 from .providers.antigravity_auth_base import AntigravityAuthBase
+from .providers.openai_oauth_base import OpenAIOAuthBase
 
 PROVIDER_MAP = {
     "gemini_cli": GeminiAuthBase,
     "qwen_code": QwenAuthBase,
     "iflow": IFlowAuthBase,
     "antigravity": AntigravityAuthBase,
+    "codex": OpenAIOAuthBase,
 }
 
 def get_provider_auth_class(provider_name: str):