mirror of
https://github.com/hanzoai/opencode-openai-codex-auth.git
synced 2026-09-24 17:01:02 +00:00
Numman AliandHanzo Dev
fe29b2110d
This release includes comprehensive OpenAI ToS compliance updates and fixes 4 critical bugs that prevented per-model options and multi-turn conversations from working correctly. ## ๐ Compliance & Legal Updates ### Terms of Service & Usage Guidelines - Added comprehensive ToS & Usage Notice to README emphasizing personal use only - Added Rate Limits & Responsible Use section with best practices - Added extensive FAQ section addressing TOS compliance questions - Updated LICENSE with MIT + Usage Disclaimer for personal development use - Added compliance header to index.ts documenting intended use cases ### New Documentation - **CONTRIBUTING.md**: Complete contribution guidelines with compliance requirements - **SECURITY.md**: Security policy, vulnerability reporting, best practices - **docs/privacy.md**: Comprehensive privacy & data handling documentation - **Issue Templates**: Bug reports & feature requests with compliance checklists ### Documentation Updates - Updated docs/index.md with usage notice and trademark disclaimers - Updated docs/getting-started.md with "Before You Begin" compliance notice - Updated docs/troubleshooting.md with subscription & compliance sections - All references updated to "Plus/Pro" (removed Team/Enterprise mentions) ### Key Compliance Principles - โ Emphasizes personal development use with own ChatGPT Plus/Pro subscription - โ Uses OpenAI's official OAuth authentication (same as Codex CLI) - โ Clear prohibition of commercial resale, multi-user services - โ Not a "free API alternative" - uses existing ChatGPT subscription - โ Proper trademark notices and attribution to OpenAI - โ Transparent about data handling and privacy ## ๐ Critical Bug Fixes ### Bug #1: Per-Model Options Ignored (Config Lookup Mismatch) **Severity:** ๐ด HIGH Users configured different reasoning levels for each model variant, but all variants behaved identically because the plugin was looking up normalized model names instead of the original config keys. **Fix:** lib/request/request-transformer.ts:277 - Use original model name for config lookup before normalization - Allows per-model options to work correctly - Impact: Different reasoning levels now properly applied per variant ### Bug #2: Multi-Turn Conversations Fail (AI SDK Compatibility) **Severity:** ๐ด CRITICAL Multi-turn conversations failed with "Item not found" errors because: 1. AI SDK sends `item_reference` (not in Codex API spec) 2. IDs weren't completely stripped for stateless mode (store: false) **Fix:** lib/request/request-transformer.ts:114-135 - Filter out AI SDK `item_reference` items - Strip ALL IDs from remaining items (not just rs_* prefix) - Confirmed ChatGPT backend requires store: false via testing - Full message history preserved for LLM context ### Bug #3: Case-Sensitive Normalization **Severity:** ๐ก MEDIUM **Fix:** lib/request/request-transformer.ts:22-27 - Added toLowerCase() for case-insensitive matching - Backwards compatible with old verbose config names - Handles uppercase/mixed case user input ### Bug #4: GitHub API Rate Limiting **Severity:** ๐ก MEDIUM Plugin checked GitHub on every request, exhausting 60 req/hour limit. 15-minute cache timestamp was stored but never checked. **Fix:** lib/prompts/codex.ts:50-53, lib/prompts/opencode-codex.ts:47-50 - Check cache TTL before GitHub API call - Only fetch if cache >15min old - Prevents rate limit exhaustion during testing ## โจ Enhancements ### Debug Logging System - New environment variable: `DEBUG_CODEX_PLUGIN=1` - Added logDebug() and logWarn() functions - Shows config lookups, ID filtering, options resolution - File: lib/logger.ts ### Optimized Config Structure - Changed to Codex CLI preset names (gpt-5-codex-low, etc.) - Removed redundant `id` field (not used by OpenAI provider) - Added `name` field for friendly TUI display - File: config/full-opencode.json ### GitHub Pages Documentation - Complete documentation restructure for GitHub Pages - User guides: getting-started.md, configuration.md, troubleshooting.md - Developer guides: ARCHITECTURE.md, CONFIG_FLOW.md, CONFIG_FIELDS.md, TESTING.md - Privacy policy, security policy, contribution guidelines ## ๐งช Testing ### Test Coverage - โ 159 unit tests passing (30+ new tests) - โ 14 integration tests passing (actual API verification) - โ All documented scenarios have test coverage ### Integration Tests (scripts/test-all-models.sh) - Tests all 9 custom model configurations - Tests all 4 default OpenCode models - Verifies backwards compatibility with old config format - Uses ENABLE_PLUGIN_REQUEST_LOGGING to verify actual API requests ### Test Results - 14/14 model configuration tests passing - All per-model options verified correct - Multi-turn conversations work without errors - Backwards compatibility confirmed ## ๐ Files Changed ### Modified (7 files) - lib/request/request-transformer.ts: Config lookup & ID filtering fixes - lib/prompts/codex.ts: 15-minute cache TTL - lib/prompts/opencode-codex.ts: 15-minute cache TTL - lib/logger.ts: Debug logging system - config/full-opencode.json: Optimized structure - test/request-transformer.test.ts: 30+ new tests - LICENSE: Added usage disclaimer - index.ts: Added compliance header - README.md: Added ToS, Rate Limits, FAQ sections ### Created (20+ files) - CONTRIBUTING.md: Contribution guidelines - SECURITY.md: Security policy - docs/index.md: GitHub Pages landing - docs/getting-started.md: Installation guide - docs/configuration.md: Advanced config - docs/troubleshooting.md: Debug guide - docs/privacy.md: Privacy policy - docs/development/ARCHITECTURE.md: Technical architecture - docs/development/CONFIG_FLOW.md: Config system internals - docs/development/CONFIG_FIELDS.md: Field usage guide - docs/development/TESTING.md: Testing guide - .github/ISSUE_TEMPLATE/bug_report.md - .github/ISSUE_TEMPLATE/feature_request.md - .github/ISSUE_TEMPLATE/config.yml - scripts/test-all-models.sh: Automated testing ## ๐ฏ Verification All scenarios tested and verified: - โ Default models work without config - โ Custom models with per-variant options - โ Old config format (backwards compatible) - โ Mixed default + custom models - โ Multi-turn conversations (no "item not found" errors) - โ Model switching with different options - โ All normalization patterns - โ Complete ID filtering ## ๐ Documentation Complete documentation suite (100+ KB): - User guides for installation, configuration, troubleshooting - Developer guides for architecture, config system, testing - Privacy policy and security policy - Compliance guidelines and contribution requirements - Release notes in tmp/release-notes/ ## ๐ References - OpenAI Terms of Use: https://openai.com/policies/terms-of-use/ - OpenAI Usage Policies: https://openai.com/policies/usage-policies/ - OpenAI Platform API: https://platform.openai.com/ - OpenAI Codex CLI: https://github.com/openai/codex Co-authored-by: Hanzo Dev <[email protected]>
Documentation
Welcome to the OpenCode OpenAI Codex Auth Plugin documentation!
For Users
- Getting Started - Installation, configuration, and quick start
- Configuration Guide - Complete config reference
- Troubleshooting - Common issues and debugging
- Changelog - Version history and release notes
For Developers
Explore the engineering depth behind this plugin:
- Architecture - Technical design, request pipeline, AI SDK compatibility
- Configuration System - How config loading and merging works
- Config Fields Guide - Understanding config keys,
id, andname - Testing Guide - Test scenarios, verification procedures, integration testing
Key Architectural Decisions
This plugin bridges two different systems with careful engineering:
- AI SDK Compatibility - Filters
item_reference(AI SDK construct) for Codex API compatibility - Stateless Operation - ChatGPT backend requires
store: false, verified via testing - Full Context Preservation - Sends complete message history (IDs stripped) for LLM context
- 15-Minute Caching - Prevents GitHub API rate limit exhaustion
- Per-Model Configuration - Enables quality presets with quick switching
Testing: 159 unit tests + 14 integration tests with actual API verification