Numman Ali and Hanzo Dev
fe29b2110d
feat: Add comprehensive compliance documentation and fix critical bugs (v2.1.2)
...
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]
2025-10-12 21:25:43 +01:00
Numman Ali and Hanzo Dev
b32f67ba81
feat: Add Task tool & MCP awareness with ETag-based prompt verification
...
This release enhances the bridge prompt system with awareness of OpenCode's
advanced capabilities and implements cache-based verification for more robust
prompt filtering.
**New Features:**
- Task tool awareness: Bridge prompt now documents sub-agent system
- MCP tool awareness: Documents Model Context Protocol tool conventions
- OpenCode prompt verification: ETag-based caching of codex.txt for 100% accurate filtering
- AGENTS.md: Renamed from CLAUDE.md for broader AI agent applicability
**Technical Changes:**
- Created lib/prompts/opencode-codex.ts for prompt verification caching
- Made request transformation pipeline async to support cache fetching
- Enhanced isOpenCodeSystemPrompt() with dual verification (cached + fallback)
- Updated bridge prompt with "Advanced Tools" section (~550 tokens, was ~450)
- Added 6 new tests verifying AGENTS.md content safety (129 total tests)
**Verification System:**
Primary: Compare against cached OpenCode prompt from GitHub
Fallback: Text signature matching ("You are a coding agent running in")
This ensures 100% confidence when filtering OpenCode system prompts
**Breaking Changes:** None - all changes are additive
Co-authored-by: Hanzo Dev <[email protected]
2025-10-04 11:22:17 +01:00
Numman Ali and Hanzo Dev
3890872781
feat: Add CODEX_MODE with bridge prompt and reorganize lib/ structure
...
## CODEX_MODE Implementation
Added configurable CODEX_MODE that replaces OpenCode system prompts with
a Codex-OpenCode bridge prompt for better Codex CLI parity.
**Key Features:**
- Enabled by default for optimal Codex CLI compatibility
- Configurable via ~/.opencode/openai-codex-auth-config.json
- Environment variable override support (CODEX_MODE=0 or CODEX_MODE=1)
- Priority: env var > config file > default (true)
**Bridge Prompt:**
- ~450 tokens (~90% reduction vs full OpenCode prompt)
- Critical tool replacements (apply_patch โ edit, update_plan โ todowrite)
- Available tools list and verification checklist
- OpenCode working style guidelines
**Configuration:**
```json
{
"codexMode": true // default
}
```
## Library Reorganization
Restructured lib/ into semantic subfolders:
```
lib/
โโโ auth/ # OAuth authentication
โ โโโ auth.ts
โ โโโ browser.ts
โ โโโ server.ts
โโโ prompts/ # System prompts
โ โโโ codex.ts
โ โโโ codex-opencode-bridge.ts
โโโ request/ # Request handling
โ โโโ fetch-helpers.ts
โ โโโ request-transformer.ts
โ โโโ response-handler.ts
โโโ config.ts # Plugin configuration
โโโ constants.ts
โโโ logger.ts
โโโ types.ts
โโโ oauth-success.html
```
## Files Changed
**New Files:**
- lib/config.ts - Plugin configuration loading
- lib/prompts/codex-opencode-bridge.ts - Bridge prompt
- test/plugin-config.test.ts - 12 new tests
**Modified:**
- lib/request/request-transformer.ts - CODEX_MODE parameter
- lib/request/fetch-helpers.ts - Pass codexMode through pipeline
- index.ts - Load config and determine codexMode
- lib/types.ts - Add PluginConfig type
- README.md - Document CODEX_MODE configuration
**Reorganized:**
- lib/*.ts โ lib/{auth,prompts,request}/*.ts
- Updated all imports across codebase and tests
## Testing
- 123 total tests (added 12 new tests for config loading)
- All tests passing
- Comprehensive CODEX_MODE coverage:
- Config file loading (exists, missing, invalid)
- Priority order testing
- Environment variable override
- Bridge prompt vs tool remap behavior
## Documentation
Updated README.md:
- Added "Plugin Configuration" section
- Documented CODEX_MODE setting and priority
- Updated features list (123 tests, CODEX_MODE)
- Updated "How It Works" section
Co-authored-by: Hanzo Dev <[email protected]
2025-10-03 22:31:34 +01:00
