feat: OpenAI compatibility improvements, build fixes, and documentation

[appletechie]

Summary

This PR includes a collection of improvements focused on:

1. OpenAI API Compatibility - Better support for tools like Kilo Code, Cursor, and other OpenAI-compatible clients
2. Build & Hydration Fixes - Resolves production build warnings and React hydration mismatches
3. Codex Provider Improvements - Full Responses API support with proper streaming translation
4. Documentation - Comprehensive deployment guide with environment variables

Changes

🚀 New Features

/v1/models Endpoint (dd0272d)

Adds an OpenAI-compatible models endpoint that returns available models based on active provider connections.

Why: Tools like Kilo Code, Cursor, and other OpenAI-compatible clients expect a /v1/models endpoint to discover available models. Without this, users had to manually configure model names.

GET /v1/models

Returns:

{
  "object": "list",
  "data": [
    { "id": "combo/my-combo", "object": "model", "owned_by": "combo" },
    { "id": "cc/claude-sonnet-4", "object": "model", "owned_by": "cc" },
    ...
  ]
}

Combos in Models List (ef45a31)

Combos now appear at the top of the /v1/models response.

Why: Users create combos for failover between providers. Having them prominently listed makes them easily selectable in client tools.

Codex Response Translator (c745a74)

Adds bidirectional translation between OpenAI Responses API and Chat Completions format.

Why: Codex uses the OpenAI Responses API format (events like response.output_text.delta), but most clients expect standard Chat Completions format (choices[0].delta.content). This translator enables Codex to work with any OpenAI-compatible client.

Handles:

• response.output_text.delta → choices[0].delta.content
• response.output_item.added (function_call) → tool_calls
• response.function_call_arguments.delta → tool call arguments
• response.completed → finish_reason: stop

🐛 Bug Fixes

Codex Parameter Filtering (f48c254)

Removes unsupported parameters before sending to Codex API.

Why: Codex API rejects requests with parameters like temperature, top_p, frequency_penalty, presence_penalty, logprobs, n, and seed. These are now filtered out in the executor.

Codex Streaming Status (3a088f0)

• Extends extractUsage() to recognize Responses API format
• Adds fallback to mark requests as "200 OK" even without usage data

Why: Codex streaming requests were stuck with PENDING status in the logs because the Responses API format wasn't recognized by the usage extractor. This caused confusion about whether requests succeeded.

React Hydration Mismatches (ac53cf0, ca93c63, e50169f)

Multiple fixes for React hydration issues:

• Fix useCallback ordering to prevent "Cannot access before initialization" errors
• Fix useTheme.js hydration mismatch using useSyncExternalStore
• Move isLocalhost detection to useEffect in OAuthModal
• Fix isLoading prop warnings in Button components
• Resolve circular dependency in AuthLayout

Why: Hydration mismatches cause the React app to re-render entirely on the client, degrading performance and causing UI flicker. These also produced console warnings in production builds.

Material Symbols Font (ef1b35f)

Adds missing Material Symbols Outlined font-family to globals.css.

Why: Icons were not rendering correctly because the font wasn't properly declared.

PropTypes Import (d9c2434)

Corrects PropTypes import in EndpointPageClient.

Why: Build was failing with incorrect import path.

🔧 Build & Configuration

Build Warnings Cleanup (7afc73d)

• Fix React Hook dependency warnings
• Fix Next.js Image optimization warnings
• Fix Tailwind v4 legacy syntax
• Add PropTypes and remove unused variables
• Add DATA_DIR and INITIAL_PASSWORD environment variable support

Why: Production builds were generating numerous warnings that cluttered CI/CD logs and made it harder to spot real issues.

📚 Documentation (1fd1ac7)

Comprehensive README update including:

• Environment Variables Table - All configurable options with descriptions
• Deployment Guides - Dokploy, VPS, Docker, and Nginx reverse proxy
• API Endpoints - Documentation for /v1/chat/completions, /v1/models, /v1/responses
• CLI Integration Examples - Claude Code, Codex CLI, Cursor IDE
• Troubleshooting Section - Common issues and solutions
• Provider Support Table - All providers with aliases and auth types

🔍 Debug Logging (79033f6)

Adds debug logging for Antigravity/Gemini empty response issues:

• Logs when stream translation starts
• Logs when translation returns empty for non-done chunks
• Logs actual response content when candidates are missing

Why: Users were seeing "The language model did not provide any assistant messages" errors with no visibility into what Antigravity was actually returning.

Testing

• Tested with Kilo Code using /v1/models endpoint
• Verified Codex streaming works with standard OpenAI clients
• Confirmed no hydration mismatches in production build
• Build completes with no warnings

Breaking Changes

None. All changes are backwards compatible.

---

🤖 Co-authored with Claude Opus 4.5