Add codex oauth support

.env.example

@@ -85,6 +85,32 @@
 # Path to your iFlow credential file (e.g., ~/.iflow/oauth_creds.json).
 #IFLOW_OAUTH_1=""
 
+# --- OpenAI Codex (ChatGPT OAuth) ---
+# One-time import from Codex CLI auth files (copied into oauth_creds/openai_codex_oauth_*.json)
+#OPENAI_CODEX_OAUTH_1="~/.codex/auth.json"
+
+# Stateless env credentials (legacy single account)
+#OPENAI_CODEX_ACCESS_TOKEN=""
+#OPENAI_CODEX_REFRESH_TOKEN=""
+#OPENAI_CODEX_EXPIRY_DATE="0"
+#OPENAI_CODEX_ID_TOKEN=""
+#OPENAI_CODEX_ACCOUNT_ID=""
+#OPENAI_CODEX_EMAIL=""
+
+# Stateless env credentials (numbered multi-account)
+#OPENAI_CODEX_1_ACCESS_TOKEN=""
+#OPENAI_CODEX_1_REFRESH_TOKEN=""
+#OPENAI_CODEX_1_EXPIRY_DATE="0"
+#OPENAI_CODEX_1_ID_TOKEN=""
+#OPENAI_CODEX_1_ACCOUNT_ID=""
+#OPENAI_CODEX_1_EMAIL=""
+
+# OpenAI Codex routing/config
+#OPENAI_CODEX_API_BASE="https://chatgpt.com/backend-api"
+#OPENAI_CODEX_OAUTH_PORT=1455
+#OPENAI_CODEX_MODELS='["gpt-5.1-codex","gpt-5-codex"]'
+#ROTATION_MODE_OPENAI_CODEX=sequential
+
 
 # ------------------------------------------------------------------------------
 # | [ADVANCED] Provider-Specific Settings                                      |
@@ -162,6 +188,7 @@
 #
 # Provider Defaults:
 #   - antigravity: sequential (free tier accounts with daily quotas)
+#   - openai_codex: sequential (account-level quota behavior)
 #   - All others: balanced
 #
 # Example:
@@ -401,8 +428,24 @@
 # ------------------------------------------------------------------------------
 #
 # OAuth callback port for Antigravity interactive re-authentication.
-# Default: 8085 (same as Gemini CLI, shared)
-# ANTIGRAVITY_OAUTH_PORT=8085
+# Default: 51121
+# ANTIGRAVITY_OAUTH_PORT=51121
+
+# ------------------------------------------------------------------------------
+# | [ADVANCED] iFlow OAuth Configuration                                        |
+# ------------------------------------------------------------------------------
+#
+# OAuth callback port for iFlow interactive re-authentication.
+# Default: 11451
+# IFLOW_OAUTH_PORT=11451
+
+# ------------------------------------------------------------------------------
+# | [ADVANCED] OpenAI Codex OAuth Configuration                                 |
+# ------------------------------------------------------------------------------
+#
+# OAuth callback port for OpenAI Codex interactive authentication.
+# Default: 1455
+# OPENAI_CODEX_OAUTH_PORT=1455
 
 # ------------------------------------------------------------------------------
 # | [ADVANCED] Debugging / Logging                                              |

.gitignore

@@ -126,9 +126,10 @@ staged_changes.txt
 launcher_config.json
 quota_viewer_config.json
 cache/antigravity/thought_signatures.json
-logs/
-cache/
+/logs/
+/cache/
 *.env
 
-oauth_creds/
+/oauth_creds/
 
+/usage/

DOCUMENTATION.md

@@ -22,9 +22,9 @@ This architecture cleanly separates the API interface from the resilience logic,
 
 This library is the heart of the project, containing all the logic for managing a pool of API keys, tracking their usage, and handling provider interactions to ensure application resilience.
 
-### 2.1. `client.py` - The `RotatingClient`
+### 2.1. `client/rotating_client.py` - The `RotatingClient`
 
-The `RotatingClient` is the central class that orchestrates all operations. It is designed as a long-lived, async-native object.
+The `RotatingClient` is the central class that orchestrates all operations. It is now a slim facade that delegates to modular components (executor, filters, transforms) while remaining a long-lived, async-native object.
 
 #### Initialization
 
@@ -35,7 +35,7 @@ client = RotatingClient(
     api_keys=api_keys,
     oauth_credentials=oauth_credentials,
     max_retries=2,
-    usage_file_path="key_usage.json",
+    usage_file_path="usage.json",
     configure_logging=True,
     global_timeout=30,
     abort_on_callback_error=True,
@@ -50,7 +50,7 @@ client = RotatingClient(
 -   `api_keys` (`Optional[Dict[str, List[str]]]`, default: `None`): A dictionary mapping provider names to a list of API keys.
 -   `oauth_credentials` (`Optional[Dict[str, List[str]]]`, default: `None`): A dictionary mapping provider names to a list of file paths to OAuth credential JSON files.
 -   `max_retries` (`int`, default: `2`): The number of times to retry a request with the *same key* if a transient server error occurs.
--   `usage_file_path` (`str`, default: `"key_usage.json"`): The path to the JSON file where usage statistics are persisted.
+-   `usage_file_path` (`str`, optional): Base path for usage persistence (defaults to `usage/` in the data directory). The client stores per-provider files under `usage/usage_<provider>.json`.
 -   `configure_logging` (`bool`, default: `True`): If `True`, configures the library's logger to propagate logs to the root logger.
 -   `global_timeout` (`int`, default: `30`): A hard time limit (in seconds) for the entire request lifecycle.
 -   `abort_on_callback_error` (`bool`, default: `True`): If `True`, any exception raised by `pre_request_callback` will abort the request.
@@ -96,9 +96,9 @@ The `_safe_streaming_wrapper` is a critical component for stability. It:
 *   **Error Interception**: Detects if a chunk contains an API error (like a quota limit) instead of content, and raises a specific `StreamedAPIError`.
 *   **Quota Handling**: If a specific "quota exceeded" error is detected mid-stream multiple times, it can terminate the stream gracefully to prevent infinite retry loops on oversized inputs.
 
-### 2.2. `usage_manager.py` - Stateful Concurrency & Usage Management
+### 2.2. `usage/manager.py` - Stateful Concurrency & Usage Management
 
-This class is the stateful core of the library, managing concurrency, usage tracking, cooldowns, and quota resets.
+This class is the stateful core of the library, managing concurrency, usage tracking, cooldowns, and quota resets. Usage tracking now lives in the `rotator_library/usage/` package with per-provider managers and `usage/usage_<provider>.json` storage.
 
 #### Key Concepts
 
@@ -205,15 +205,17 @@ The `CredentialManager` class (`credential_manager.py`) centralizes the lifecycl
 
 On startup (unless `SKIP_OAUTH_INIT_CHECK=true`), the manager performs a comprehensive sweep:
 
-1. **System-Wide Scan**: Searches for OAuth credential files in standard locations:
+1. **System-Wide Scan / Import Sources**:
    - `~/.gemini/` → All `*.json` files (typically `credentials.json`)
    - `~/.qwen/` → All `*.json` files (typically `oauth_creds.json`)
-   - `~/.iflow/` → All `*. json` files
+   - `~/.iflow/` → All `*.json` files
+   - `~/.codex/auth.json` + `~/.codex-accounts.json` → OpenAI Codex first-run import sources
 
 2. **Local Import**: Valid credentials are **copied** (not moved) to the project's `oauth_creds/` directory with standardized names:
-   -  `gemini_cli_oauth_1.json`, `gemini_cli_oauth_2.json`, etc.
+   - `gemini_cli_oauth_1.json`, `gemini_cli_oauth_2.json`, etc.
    - `qwen_code_oauth_1.json`, `qwen_code_oauth_2.json`, etc.
    - `iflow_oauth_1.json`, `iflow_oauth_2.json`, etc.
+   - `openai_codex_oauth_1.json`, `openai_codex_oauth_2.json`, etc.
 
 3. **Intelligent Deduplication**: 
    - The manager inspects each credential file for a `_proxy_metadata` field containing the user's email or ID
@@ -292,6 +294,24 @@ IFLOW_EMAIL
 IFLOW_API_KEY
 ```
 
+**OpenAI Codex Environment Variables:**
+```
+OPENAI_CODEX_ACCESS_TOKEN
+OPENAI_CODEX_REFRESH_TOKEN
+OPENAI_CODEX_EXPIRY_DATE
+OPENAI_CODEX_ID_TOKEN
+OPENAI_CODEX_ACCOUNT_ID
+OPENAI_CODEX_EMAIL
+
+# Numbered multi-account format
+OPENAI_CODEX_1_ACCESS_TOKEN
+OPENAI_CODEX_1_REFRESH_TOKEN
+OPENAI_CODEX_1_EXPIRY_DATE
+OPENAI_CODEX_1_ID_TOKEN
+OPENAI_CODEX_1_ACCOUNT_ID
+OPENAI_CODEX_1_EMAIL
+```
+
 **How it works:**
 - If the manager finds (e.g.) `GEMINI_CLI_ACCESS_TOKEN` or `GEMINI_CLI_1_ACCESS_TOKEN`, it constructs an in-memory credential object that mimics the file structure
 - The credential is referenced internally as `env://gemini_cli/0` (legacy) or `env://gemini_cli/1` (numbered)
@@ -304,17 +324,19 @@ IFLOW_API_KEY
 env://{provider}/{index}
 
 Examples:
-- env://gemini_cli/1  → GEMINI_CLI_1_ACCESS_TOKEN, etc.
-- env://gemini_cli/0  → GEMINI_CLI_ACCESS_TOKEN (legacy single credential)
-- env://antigravity/1 → ANTIGRAVITY_1_ACCESS_TOKEN, etc.
+- env://gemini_cli/1    → GEMINI_CLI_1_ACCESS_TOKEN, etc.
+- env://gemini_cli/0    → GEMINI_CLI_ACCESS_TOKEN (legacy single credential)
+- env://antigravity/1   → ANTIGRAVITY_1_ACCESS_TOKEN, etc.
+- env://openai_codex/1  → OPENAI_CODEX_1_ACCESS_TOKEN, etc.
+- env://openai_codex/0  → OPENAI_CODEX_ACCESS_TOKEN (legacy single credential)
 ```
 
 #### 2.6.3. Credential Tool Integration
 
 The `credential_tool.py` provides a user-friendly CLI interface to the `CredentialManager`:
 
 **Key Functions:**
-1. **OAuth Setup**: Wraps provider-specific `AuthBase` classes (`GeminiAuthBase`, `QwenAuthBase`, `IFlowAuthBase`) to handle interactive login flows
+1. **OAuth Setup**: Wraps provider-specific `AuthBase` classes (`GeminiAuthBase`, `QwenAuthBase`, `IFlowAuthBase`, `OpenAICodexAuthBase`) to handle interactive login flows
 2. **Credential Export**: Reads local `.json` files and generates `.env` format output for stateless deployment
 3. **API Key Management**: Adds or updates `PROVIDER_API_KEY_N` entries in the `.env` file
 
@@ -419,7 +441,7 @@ The `CooldownManager` handles IP or account-level rate limiting that affects all
 - All subsequent `acquire_key()` calls for that provider will wait until the cooldown expires
 
 
-### 2.10. Credential Prioritization System (`client.py` & `usage_manager.py`)
+### 2.10. Credential Prioritization System (`client/rotating_client.py` & `usage/manager.py`)
 
 The library now includes an intelligent credential prioritization system that automatically detects credential tiers and ensures optimal credential selection for each request.
 
@@ -762,7 +784,7 @@ Acquiring key for model antigravity/claude-opus-4.5. Tried keys: 0/12(17,cd:3,fc
 ```
 
 **Persistence:**
-Cycle state is persisted in `key_usage.json` under the `__fair_cycle__` key.
+Cycle state is persisted alongside usage data in `usage/usage_<provider>.json`.
 
 ### 2.20. Custom Caps
 
@@ -1426,12 +1448,13 @@ Each OAuth provider uses a local callback server during authentication. The call
 | Gemini CLI | 8085 | `GEMINI_CLI_OAUTH_PORT` |
 | Antigravity | 51121 | `ANTIGRAVITY_OAUTH_PORT` |
 | iFlow | 11451 | `IFLOW_OAUTH_PORT` |
+| OpenAI Codex | 1455 | `OPENAI_CODEX_OAUTH_PORT` |
 
 **Configuration Methods:**
 
 1. **Via TUI Settings Menu:**
    - Main Menu → `4. View Provider & Advanced Settings` → `1. Launch Settings Tool`
-   - Select the provider (Gemini CLI, Antigravity, or iFlow)
+   - Select the provider (Gemini CLI, Antigravity, iFlow, or OpenAI Codex)
    - Modify the `*_OAUTH_PORT` setting
    - Use "Reset to Default" to restore the original port
 
@@ -1441,6 +1464,7 @@ Each OAuth provider uses a local callback server during authentication. The call
    GEMINI_CLI_OAUTH_PORT=8085
    ANTIGRAVITY_OAUTH_PORT=51121
    IFLOW_OAUTH_PORT=11451
+   OPENAI_CODEX_OAUTH_PORT=1455
    ```
 
 **When to Change Ports:**
@@ -1528,7 +1552,7 @@ The following providers use `TimeoutConfig`:
 | `iflow_provider.py` | `acompletion()` | `streaming()` |
 | `qwen_code_provider.py` | `acompletion()` | `streaming()` |
 
-**Note:** iFlow, Qwen Code, and Gemini CLI providers always use streaming internally (even for non-streaming requests), aggregating chunks into a complete response. Only Antigravity has a true non-streaming path.
+**Note:** iFlow, Qwen Code, Gemini CLI, and OpenAI Codex providers always use streaming internally (even for non-streaming requests), aggregating chunks into a complete response. Only Antigravity has a true non-streaming path.
 
 #### Tuning Recommendations
 
@@ -1649,7 +1673,23 @@ QUOTA_GROUPS_GEMINI_CLI_3_FLASH="gemini-3-flash-preview"
 *   **Schema Cleaning**: Similar to Qwen, it aggressively sanitizes tool schemas to prevent 400 errors.
 *   **Dedicated Logging**: Implements `_IFlowFileLogger` to capture raw chunks for debugging proprietary API behaviors.
 
-### 3.4. Google Gemini (`gemini_provider.py`)
+### 3.4. OpenAI Codex (`openai_codex_provider.py`)
+
+*   **Auth Base**: Uses `OpenAICodexAuthBase` with Authorization Code + PKCE, queue-based refresh/re-auth, and local-first credential persistence (`oauth_creds/openai_codex_oauth_*.json`).
+*   **First-Run Import**: `CredentialManager` imports from `~/.codex/auth.json` and `~/.codex-accounts.json` when no local/OpenAI Codex env creds exist.
+*   **Endpoint Translation**: Implements OpenAI-compatible `/v1/chat/completions` by transforming chat payloads into Codex Responses payloads and calling `POST /codex/responses`.
+*   **SSE Translation**: Maps Codex SSE event families (e.g. `response.output_item.*`, `response.output_text.delta`, `response.function_call_arguments.*`, `response.completed`) into LiteLLM/OpenAI chunk objects.
+*   **Rotation Compatibility**: Emits typed `httpx.HTTPStatusError` for transport/status failures and includes provider-specific `parse_quota_error()` for retry/cooldown extraction (`Retry-After`, `error.resets_at`).
+*   **Default Rotation**: `sequential` (account-level quota behavior).
+
+**OpenAI Codex Troubleshooting Notes:**
+
+- **Malformed JWT payload**: If access/id tokens cannot be decoded, account/email metadata can be missing; re-authenticate to rebuild token metadata.
+- **Missing account-id claim**: Requests require `chatgpt-account-id`; if absent, refresh/re-auth to repopulate `_proxy_metadata.account_id`.
+- **Callback port conflicts**: Change `OPENAI_CODEX_OAUTH_PORT` when port `1455` is already in use.
+- **Header mismatch / 403**: Ensure provider sends `Authorization`, `chatgpt-account-id`, and expected Codex headers (`OpenAI-Beta`, `originator`) when routing to `/codex/responses`.
+
+### 3.5. Google Gemini (`gemini_provider.py`)
 
 *   **Thinking Parameter**: Automatically handles the `thinking` parameter transformation required for Gemini 2.5 models (`thinking` -> `gemini-2.5-pro` reasoning parameter).
 *   **Safety Settings**: Ensures default safety settings (blocking nothing) are applied if not provided, preventing over-sensitive refusals.
@@ -1773,7 +1813,7 @@ The system follows a strict hierarchy of survival:
 
 2. **Credential Management (Level 2)**: OAuth tokens are cached in memory first. If credential files are deleted, the proxy continues using cached tokens. If a token refresh succeeds but the file cannot be written, the new token is buffered for retry and saved on shutdown.
 
-3. **Usage Tracking (Level 3)**: Usage statistics (`key_usage.json`) are maintained in memory via `ResilientStateWriter`. If the file is deleted, the system tracks usage internally and attempts to recreate the file on the next save interval. Pending writes are flushed on shutdown.
+3. **Usage Tracking (Level 3)**: Usage statistics (`usage/usage_<provider>.json`) are maintained in memory via `ResilientStateWriter`. If the file is deleted, the system tracks usage internally and attempts to recreate the file on the next save interval. Pending writes are flushed on shutdown.
 
 4. **Provider Cache (Level 4)**: The provider cache tracks disk health and continues operating in memory-only mode if disk writes fail. Has its own shutdown mechanism.
 
@@ -1813,7 +1853,7 @@ INFO:rotator_library.resilient_io:Shutdown flush: all 2 write(s) succeeded
 This architecture supports a robust development workflow:
 
 - **Log Cleanup**: You can safely run `rm -rf logs/` while the proxy is serving traffic. The system will recreate the directory structure on the next request.
-- **Config Reset**: Deleting `key_usage.json` resets the persistence layer, but the running instance preserves its current in-memory counts for load balancing consistency.
+- **Config Reset**: Deleting `usage/usage_<provider>.json` resets the persistence layer, but the running instance preserves its current in-memory counts for load balancing consistency.
 - **File Recovery**: If you delete a critical file, the system attempts directory auto-recreation before every write operation.
 - **Safe Exit**: Ctrl+C triggers graceful shutdown with final data flush attempt.
 

Dockerfile

@@ -1,5 +1,5 @@
 # Build stage
-FROM python:3.11-slim AS builder
+FROM python:3.12-slim AS builder
 
 WORKDIR /app
 
@@ -21,7 +21,7 @@ COPY src/rotator_library ./src/rotator_library
 RUN pip install --no-cache-dir --user -r requirements.txt
 
 # Production stage
-FROM python:3.11-slim
+FROM python:3.12-slim
 
 WORKDIR /app