diff --git a/README.md b/README.md
index cceba05..da3bdd6 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,15 @@
- 
+
-Corbat-Coco
+🥥 Corbat-Coco
- Autonomous Coding Agent with Self-Review, Quality Convergence, and Production-Ready Output
+ The AI Coding Agent That Actually Ships Production-Ready Code
+
+
+
+ Self-reviewing • Quality-obsessed • Never ships crap
@@ -13,392 +17,547 @@
- 
- 
+
+
- Quick Start •
- Features •
- Methodology •
- Examples •
- Docs
+ 
---
-## What is Corbat-Coco?
+## 💡 The Problem
+
+AI coding assistants generate code that **looks good but breaks in production**. You end up:
+- 🔄 Going back and forth fixing bugs
+- 🧪 Writing tests after the fact (if at all)
+- 🤞 Hoping edge cases don't blow up
+- 📝 Explaining the same patterns over and over
-Corbat-Coco is an **autonomous coding agent** that transforms natural language requirements into production-ready code. Unlike other AI coding tools, it **iteratively improves code until it meets senior-level quality standards**.
+## ✨ The Solution
+
+**Corbat-Coco iterates on its own code until it's actually good.**
```
-"Every line of code must be worthy of a senior engineer's signature."
+Generate → Test → Review → Improve → Repeat until senior-level quality
```
-### Why Corbat-Coco?
-
-| Feature | Cursor/Copilot | Claude Code | **Corbat-Coco** |
-|---------|:--------------:|:-----------:|:---------------:|
-| Generate code | ✅ | ✅ | ✅ |
-| Self-review loops | ❌ | ❌ | ✅ |
-| Quality scoring | ❌ | ❌ | ✅ (11 dimensions) |
-| Architecture planning | Basic | Basic | ✅ Full ADR system |
-| Progress persistence | ❌ | Session | ✅ Checkpoints |
-| Production deployment | ❌ | ❌ | ✅ CI/CD generation |
+Every piece of code goes through **self-review loops** with **11-dimension quality scoring**. It doesn't stop until it reaches 85+ quality score.
---
-## Quick Start
-
-### Installation
+## 🚀 Quick Start
```bash
-# Using npm
+# Install globally
npm install -g corbat-coco
-# Using pnpm (recommended)
-pnpm add -g corbat-coco
+# Start the interactive REPL
+coco
-# Verify installation
-coco --version
+# That's it. Coco guides you through the rest.
```
-### TL;DR (3 commands)
+On first run, Coco will help you:
+1. **Choose a provider** (Anthropic, OpenAI, Google, Moonshot)
+2. **Set up your API key** (with secure storage options)
+3. **Configure your preferences**
-```bash
-coco init my-project # Initialize & describe what you want
-coco plan # Generate architecture & backlog
-coco build # Build with quality iteration
+---
+
+## 🎯 What Makes Coco Different
+
+
+
+|
+
+### Other AI Assistants
+```
+You: "Build a user auth system"
+AI: *generates code*
+You: "This doesn't handle edge cases"
+AI: *generates more code*
+You: "The tests are broken"
+AI: *generates even more code*
+...3 hours later...
```
-### Example Session
+ |
+
-```bash
-$ coco init my-api
+### Corbat-Coco
+```
+You: "Build a user auth system"
+Coco: *generates → tests → reviews*
+ "Score: 72/100 - Missing rate limiting"
+ *improves → tests → reviews*
+ "Score: 86/100 ✅ Ready"
-🚀 Welcome to Corbat-Coco!
+...15 minutes later, production-ready...
+```
-? What would you like to build?
-> A REST API for task management with user authentication
+ |
+
+
-? Tech stack preferences?
-> TypeScript, Express, PostgreSQL, JWT auth
+### Feature Comparison
-📋 Specification generated!
+| Feature | Cursor/Copilot | Claude Code | **Corbat-Coco** |
+|---------|:--------------:|:-----------:|:---------------:|
+| Generate code | ✅ | ✅ | ✅ |
+| **Self-review loops** | ❌ | ❌ | ✅ |
+| **Quality scoring** | ❌ | ❌ | ✅ (11 dimensions) |
+| **Auto-iteration until good** | ❌ | ❌ | ✅ |
+| Architecture planning | Basic | Basic | ✅ Full ADR system |
+| Progress persistence | ❌ | Session | ✅ Checkpoints |
+| Production CI/CD | ❌ | ❌ | ✅ Auto-generated |
-$ coco plan
+---
-📐 Designing architecture...
-✓ ADR-001: Express.js framework
-✓ ADR-002: JWT authentication
-✓ ADR-003: PostgreSQL with Prisma
+## 📊 The Quality Engine
-📝 Backlog: 2 epics, 8 stories, 24 tasks
+Every code iteration is scored across **11 dimensions**:
-$ coco build
+| Dimension | What It Measures |
+|-----------|------------------|
+| **Correctness** | Tests pass, logic is sound |
+| **Completeness** | All requirements implemented |
+| **Robustness** | Edge cases handled |
+| **Readability** | Clean, understandable code |
+| **Maintainability** | Easy to modify later |
+| **Complexity** | Cyclomatic complexity in check |
+| **Duplication** | DRY principles followed |
+| **Test Coverage** | Line and branch coverage |
+| **Test Quality** | Tests are meaningful |
+| **Security** | No vulnerabilities |
+| **Documentation** | Code is documented |
-🔨 Building Sprint 0...
+**Minimum threshold: 85/100** — Senior engineer level.
-Task 1/6: User entity ✓ (3 iterations, score: 92/100)
-Task 2/6: Auth service ✓ (4 iterations, score: 89/100)
-...
+---
-📊 Sprint Complete!
-├─ Average quality: 90/100
-├─ Test coverage: 87%
-└─ Security issues: 0
-```
+## 🛠️ Supported Providers
+
+Coco works with multiple AI providers. Choose what fits your needs:
+
+| Provider | Models | Best For | Auth Options |
+|----------|--------|----------|--------------|
+| 🟠 **Anthropic** | Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 | Best coding quality | API Key |
+| 🟢 **OpenAI** | GPT-5.2 Codex, GPT-5.2 Thinking/Pro | Fast iterations | API Key **or** OAuth |
+| 🔵 **Google** | Gemini 3 Flash/Pro, 2.5 | Large context (2M tokens) | API Key **or** OAuth **or** gcloud ADC |
+| 🌙 **Moonshot** | Kimi K2.5, K2 | Great value | API Key |
+| 💻 **LM Studio** | Local models (Qwen3-Coder, etc.) | Privacy, offline | None (local) |
+
+**Switch anytime** with `/provider` or `/model` commands.
-### Example Session: Working on Existing Projects
+> 💡 **OAuth Authentication**:
+> - **OpenAI**: Have a ChatGPT Plus/Pro subscription? Select OpenAI and choose "Sign in with ChatGPT account" - no separate API key needed!
+> - **Gemini**: Have a Google account? Select Gemini and choose "Sign in with Google account" - same as Gemini CLI!
-For day-to-day development work on existing projects, use `coco task` to execute specific tasks:
+---
+
+## 💻 Usage Examples
+
+### New Project: Build from Scratch
```bash
-$ cd my-existing-backend
-$ coco task
-
-? Describe your task (paste from Jira, GitHub issue, etc.):
-> ## JIRA-1234: Add GET endpoint for user orders
->
-> **Story Points:** 5
-> **Acceptance Criteria:**
-> - Create GET /api/v1/users/{userId}/orders endpoint
-> - Return paginated list of orders (default: 20 items)
-> - Support query params: status, fromDate, toDate, page, size
-> - Include order items in response
-> - Return 404 if user not found
-> - Add unit tests (>80% coverage)
-> - Update OpenAPI spec
+$ coco
-🔍 Analyzing codebase...
-✓ Detected: Java 17 + Spring Boot 3.2
-✓ Found: OrderRepository, UserRepository, existing /api/v1/* structure
-✓ Style: Following existing patterns in UserController.java
+🥥 Welcome to Corbat-Coco!
-📋 Task breakdown:
-1. Create OrderController with GET endpoint
-2. Create OrderService with business logic
-3. Create OrderDTO and OrderPageDTO
-4. Add validation and error handling
-5. Write unit tests for Service layer
-6. Write integration tests for Controller
-7. Update OpenAPI documentation
+> Build a REST API for task management with auth
-? Proceed with implementation? (Y/n) Y
+📋 Analyzing requirements...
+📐 Creating architecture (3 ADRs)...
+📝 Generated backlog: 2 epics, 8 stories
-🔨 Executing task...
+🔨 Building...
-Step 1/7: OrderController ✓ (2 iterations, score: 94/100)
- → Created: src/main/java/com/example/controller/OrderController.java
- → Follows existing controller patterns
+Task 1/8: User model ✓ (2 iterations, 91/100)
+Task 2/8: Auth service ✓ (3 iterations, 88/100)
+Task 3/8: JWT middleware ✓ (2 iterations, 94/100)
+...
-Step 2/7: OrderService ✓ (3 iterations, score: 91/100)
- → Created: src/main/java/com/example/service/OrderService.java
- → Using existing OrderRepository
+📊 Complete!
+├─ Quality: 90/100 average
+├─ Coverage: 87%
+└─ Security issues: 0
+```
-Step 3/7: DTOs ✓ (1 iteration, score: 96/100)
- → Created: OrderDTO.java, OrderPageDTO.java, OrderFilterDTO.java
+### Existing Project: Execute Tasks
-Step 4/7: Error handling ✓ (2 iterations, score: 93/100)
- → Added: UserNotFoundException handling
- → Updated: GlobalExceptionHandler.java
+```bash
+$ cd my-backend
+$ coco
-Step 5/7: Unit tests ✓ (2 iterations, score: 89/100)
- → Created: OrderServiceTest.java (12 tests)
- → Coverage: 94%
+> Add GET /users/:id/orders endpoint with pagination
-Step 6/7: Integration tests ✓ (3 iterations, score: 88/100)
- → Created: OrderControllerIntegrationTest.java (8 tests)
+🔍 Analyzing codebase...
+✓ Detected: TypeScript + Express
+✓ Found existing patterns in UserController
-Step 7/7: OpenAPI ✓ (1 iteration, score: 97/100)
- → Updated: openapi.yaml with new endpoint schema
+🔨 Implementing...
-📊 Task Complete!
-├─ Files created: 6
-├─ Files modified: 2
-├─ Tests added: 20 (all passing)
-├─ Coverage: 92%
-├─ Average quality: 92/100
-└─ Time: 12 minutes
+Step 1/4: OrderController ✓ (2 iterations, 93/100)
+Step 2/4: OrderService ✓ (1 iteration, 96/100)
+Step 3/4: Tests ✓ (2 iterations, 89/100)
+Step 4/4: OpenAPI docs ✓ (1 iteration, 97/100)
-? Create commit? (Y/n) Y
-✓ Committed: feat(orders): add GET endpoint for user orders [JIRA-1234]
+📊 Done in 8 minutes
+├─ Files: 4 created, 1 modified
+├─ Tests: 15 added (all passing)
+└─ Coverage: 94%
-? Push to remote? (Y/n) Y
-✓ Pushed to origin/feature/JIRA-1234-user-orders
+> /commit
+✓ feat(orders): add user orders endpoint with pagination
```
-**Pro tips for existing projects:**
-- Coco automatically detects your tech stack and coding patterns
-- Paste your Jira/GitHub issue directly - it parses acceptance criteria
-- Use `coco task --dry-run` to preview without changes
-- Use `coco task --no-commit` to skip auto-commit
+### Interactive REPL Commands
----
+```bash
+/help # Show all commands
+/status # Project & git status
+/model # Change AI model
+/provider # Switch provider
+/memory # View conversation context
+/compact # Compress context if running low
+/clear # Clear conversation
+/exit # Exit REPL
+```
-## Features
+---
-### 🔄 Iterative Quality Improvement
+## ⚙️ Configuration
-Code is automatically reviewed and improved until it meets quality standards:
+Coco uses a hierarchical configuration system with **global** and **project-level** settings:
```
-Generate → Test → Review → Improve → Repeat until excellent
+~/.coco/ # Global configuration (user home)
+├── .env # API keys (secure, gitignored)
+├── config.json # Provider/model preferences (persisted across sessions)
+├── projects.json # Project trust/permissions
+├── trusted-tools.json # Trusted tools (global + per-project)
+├── tokens/ # OAuth tokens (secure, 600 permissions)
+│ └── openai.json # e.g., OpenAI/Codex OAuth tokens
+├── sessions/ # Session history
+└── COCO.md # User-level memory/instructions
+
+/.coco/ # Project configuration (overrides global)
+├── config.json # Project-specific settings
+└── ...
```
-### 📊 Multi-Dimensional Quality Scoring
+### Configuration Priority
-11 dimensions measured on every iteration:
+Settings are loaded with this priority (highest first):
-| Dimension | Weight | Description |
-|-----------|:------:|-------------|
-| Correctness | 15% | Tests pass, logic correct |
-| Completeness | 10% | All requirements met |
-| Robustness | 10% | Edge cases handled |
-| Readability | 10% | Code clarity |
-| Maintainability | 10% | Easy to modify |
-| Complexity | 8% | Cyclomatic complexity |
-| Duplication | 7% | DRY score |
-| Test Coverage | 10% | Line/branch coverage |
-| Test Quality | 5% | Test meaningfulness |
-| Security | 8% | No vulnerabilities |
-| Documentation | 4% | Doc coverage |
-| Style | 3% | Linting compliance |
+1. **Command-line flags** — `--provider`, `--model`
+2. **User preferences** — `~/.coco/config.json` (last used provider/model)
+3. **Environment variables** — `COCO_PROVIDER`, `ANTHROPIC_API_KEY`, etc.
+4. **Defaults** — Built-in default values (Anthropic Claude Sonnet)
-### 💾 Checkpoint & Recovery
+### Environment Variables
-Never lose progress:
+Store your API keys in `~/.coco/.env` (created during onboarding):
-- Automatic checkpoints every 5 minutes
-- Resume from any interruption
-- Full version history per task
-- Rollback capability
+```bash
+# ~/.coco/.env
+ANTHROPIC_API_KEY="sk-ant-..." # Anthropic Claude
+OPENAI_API_KEY="sk-..." # OpenAI
+GEMINI_API_KEY="..." # Google Gemini
+KIMI_API_KEY="..." # Moonshot Kimi
+```
-### 🏗️ Architecture Documentation
+Or export them in your shell profile:
-Generated automatically:
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
-- Architecture Decision Records (ADRs)
-- System diagrams (C4 model)
-- Backlog with epics, stories, tasks
-- Sprint planning
+### Global Config (`~/.coco/config.json`)
-### 🚀 Production Ready
+Stores your last used provider, model preferences, and authentication methods:
-Outputs ready for deployment:
+```json
+{
+ "provider": "openai",
+ "models": {
+ "openai": "gpt-4o",
+ "anthropic": "claude-sonnet-4-20250514",
+ "kimi": "kimi-k2.5"
+ },
+ "authMethods": {
+ "openai": "oauth"
+ },
+ "updatedAt": "2026-02-05T16:03:13.193Z"
+}
+```
-- Dockerfile & docker-compose.yml
-- GitHub Actions workflows
-- README & API documentation
-- Deployment guides
+This file is **auto-managed** - when you use `/provider` or `/model` commands, your choice is saved here and restored on next launch.
----
+The `authMethods` field tracks how you authenticated with each provider:
+- `"apikey"` - Standard API key authentication
+- `"oauth"` - OAuth (e.g., ChatGPT subscription)
+- `"gcloud"` - Google Cloud ADC
-## The COCO Methodology
+### Project Config (`/.coco/config.json`)
-Four phases from idea to deployment:
+Override global settings for a specific project:
+```json
+{
+ "provider": {
+ "type": "openai",
+ "model": "gpt-4o"
+ },
+ "quality": {
+ "minScore": 90
+ }
+}
```
-┌──────────┐ ┌────────────┐ ┌──────────┐ ┌────────┐
-│ CONVERGE │ → │ ORCHESTRATE│ → │ COMPLETE │ → │ OUTPUT │
-└──────────┘ └────────────┘ └──────────┘ └────────┘
- │ │ │ │
- Understand Plan & Execute & Deploy &
- Requirements Design Iterate Document
+
+### Project Trust & Permissions (`~/.coco/projects.json`)
+
+Coco asks for permission the first time you access a directory. Your choices are saved:
+
+```json
+{
+ "version": 1,
+ "projects": {
+ "/path/to/project": {
+ "approvalLevel": "write",
+ "toolsTrusted": ["bash_exec", "write_file"]
+ }
+ }
+}
```
-| Phase | Purpose | Output |
-|-------|---------|--------|
-| **Converge** | Understand requirements through Q&A | Specification document |
-| **Orchestrate** | Design architecture, create plan | ADRs, Backlog, Standards |
-| **Complete** | Build with quality iteration | Quality code + tests |
-| **Output** | Prepare for production | CI/CD, Docs, Deployment |
+**Approval levels:**
+- `read` — Read-only access (no file modifications)
+- `write` — Read and write files
+- `full` — Full access including bash commands
----
+Manage permissions with `/trust` command in the REPL.
-## Commands
+### Trusted Tools (`~/.coco/trusted-tools.json`)
-```bash
-# New projects
-coco init [path] # Initialize new project
-coco plan # Run discovery and planning
-coco build # Execute tasks with quality iteration
-coco build --sprint=N # Build specific sprint
-
-# Existing projects (day-to-day workflow)
-coco task # Execute a single task (Jira, GitHub issue, etc.)
-coco task --dry-run # Preview changes without applying
-coco task --no-commit # Skip auto-commit after task
-
-# Utilities
-coco status # Show current progress
-coco status --verbose # Detailed status
-coco resume # Resume from checkpoint
-coco config set # Configure settings
-coco config get # Get configuration value
-```
+Tools that skip confirmation prompts. Once you've granted directory access, trusted tools run automatically without asking each time.
----
+When a tool requires confirmation, you can choose:
+- `[y]es` — Allow once
+- `[n]o` — Deny
+- `[e]dit` — Edit command before running (bash only)
+- `[a]ll` — Allow all this turn
+- `[t]rust` — Always allow for this project
-## Configuration
+#### Recommended Safe Configuration
-Configuration is stored in `.coco/config.json`:
+Here's a pre-configured `trusted-tools.json` with commonly-used **read-only** tools for developers:
```json
{
- "project": {
- "name": "my-project",
- "version": "0.1.0"
- },
- "provider": {
- "type": "anthropic",
- "model": "claude-sonnet-4-20250514"
- },
- "quality": {
- "minScore": 85,
- "minCoverage": 80,
- "maxIterations": 10,
- "convergenceThreshold": 2
- },
- "persistence": {
- "checkpointInterval": 300000,
- "maxCheckpoints": 50
+ "globalTrusted": [
+ "read_file",
+ "glob",
+ "list_dir",
+ "tree",
+ "file_exists",
+ "grep",
+ "find_in_file",
+ "git_status",
+ "git_diff",
+ "git_log",
+ "git_branch",
+ "command_exists",
+ "run_linter",
+ "analyze_complexity",
+ "calculate_quality",
+ "get_coverage"
+ ],
+ "projectTrusted": {}
+}
+```
+
+#### Tool Categories & Risk Levels
+
+| Category | Tools | Risk | Why |
+|----------|-------|------|-----|
+| **Read files** | `read_file`, `glob`, `list_dir`, `tree`, `file_exists` | 🟢 Safe | Only reads, never modifies |
+| **Search** | `grep`, `find_in_file` | 🟢 Safe | Search within project only |
+| **Git status** | `git_status`, `git_diff`, `git_log`, `git_branch` | 🟢 Safe | Read-only git info |
+| **Analysis** | `run_linter`, `analyze_complexity`, `calculate_quality` | 🟢 Safe | Static analysis, no changes |
+| **Coverage** | `get_coverage` | 🟢 Safe | Reads existing coverage data |
+| **System** | `command_exists` | 🟢 Safe | Only checks if command exists |
+| **Write files** | `write_file`, `edit_file` | 🟡 Caution | Modifies files - trust per project |
+| **Move/Copy** | `copy_file`, `move_file` | 🟡 Caution | Can overwrite files |
+| **Git stage** | `git_add`, `git_commit` | 🟡 Caution | Local changes only |
+| **Git branches** | `git_checkout`, `git_init` | 🟡 Caution | Can change branch state |
+| **Tests** | `run_tests`, `run_test_file` | 🟡 Caution | Runs code (could have side effects) |
+| **Build** | `run_script`, `tsc` | 🟡 Caution | Executes npm scripts/compiler |
+| **Delete** | `delete_file` | 🔴 Always ask | Permanently removes files |
+| **Git remote** | `git_push`, `git_pull` | 🔴 Always ask | Affects remote repository |
+| **Install** | `install_deps` | 🔴 Always ask | Runs npm/pnpm install (downloads code) |
+| **Make** | `make` | 🔴 Always ask | Can run arbitrary Makefile targets |
+| **Bash** | `bash_exec`, `bash_background` | 🔴 Always ask | Arbitrary shell commands |
+| **HTTP** | `http_fetch`, `http_json` | 🔴 Always ask | Network requests to external services |
+| **Env vars** | `get_env` | 🔴 Always ask | Could expose secrets if misused |
+
+#### Example: Productive Developer Setup
+
+For developers who want to speed up common workflows while keeping dangerous actions gated:
+
+```json
+{
+ "globalTrusted": [
+ "read_file", "glob", "list_dir", "tree", "file_exists",
+ "grep", "find_in_file",
+ "git_status", "git_diff", "git_log", "git_branch",
+ "run_linter", "analyze_complexity", "calculate_quality", "get_coverage",
+ "command_exists"
+ ],
+ "projectTrusted": {
+ "/path/to/my-trusted-project": [
+ "write_file", "edit_file", "copy_file", "move_file",
+ "git_add", "git_commit",
+ "run_tests", "run_test_file",
+ "run_script", "tsc"
+ ]
}
}
```
-### Quality Thresholds
+#### Built-in Safety Protections
-| Setting | Default | Description |
-|---------|:-------:|-------------|
-| `minScore` | 85 | Minimum quality score (0-100) |
-| `minCoverage` | 80 | Minimum test coverage (%) |
-| `maxIterations` | 10 | Max iterations per task |
-| `convergenceThreshold` | 2 | Score delta to consider converged |
+Even with trusted tools, Coco has **three layers of protection**:
----
+| Level | Behavior | Example |
+|-------|----------|---------|
+| 🟢 **Trusted** | Auto-executes without asking | `read_file`, `git_status` |
+| 🔴 **Always Ask** | Shows warning, user can approve | `bash_exec`, `git_push` |
+| ⛔ **Blocked** | Never executes, shows error | `rm -rf /`, `curl \| sh` |
-## Examples
+**Blocked commands** (cannot be executed even with approval):
+- `rm -rf /` — Delete root filesystem
+- `sudo rm -rf` — Privileged destructive commands
+- `curl | sh`, `wget | sh` — Remote code execution
+- `dd if=... of=/dev/` — Write to devices
+- `mkfs`, `format` — Format filesystems
+- `eval`, `source` — Arbitrary code execution
+- Fork bombs and other malicious patterns
-See the [examples/](examples/) directory for complete examples:
+**File access restrictions**:
+- System paths blocked: `/etc`, `/var`, `/root`, `/sys`, `/proc`
+- Sensitive files protected: `.env`, `*.pem`, `id_rsa`, `credentials.*`
+- Operations sandboxed to project directory
-| Example | Description | Time |
-|---------|-------------|:----:|
-| [REST API (TypeScript)](examples/01-rest-api-typescript/) | Task management API with auth | ~30 min |
-| [CLI Tool](examples/02-cli-tool/) | Image processing CLI | ~25 min |
-| [Spring Boot (Java)](examples/03-java-spring-boot/) | Order management microservice | ~40 min |
+> ⚠️ **Important**: Tools marked 🔴 **always ask for confirmation** regardless of trust settings. They show a warning prompt because they can have **irreversible effects** (data loss, remote changes, network access). You can still approve them - they just won't auto-execute.
---
-## Requirements
+## 🔌 MCP (Model Context Protocol)
-- **Node.js**: 22.0.0 or higher
-- **Anthropic API Key**: For Claude models
-- **Git**: For version control features
+Coco supports [MCP](https://modelcontextprotocol.io/), enabling integration with 100+ external tools and services.
-### Environment Variables
+### Quick Setup
```bash
-export ANTHROPIC_API_KEY="sk-ant-..." # Required
-export COCO_CONFIG_PATH="..." # Optional: custom config path
+# Add an MCP server (e.g., filesystem access)
+coco mcp add filesystem \
+ --command "npx" \
+ --args "-y,@modelcontextprotocol/server-filesystem,/home/user"
+
+# Add GitHub integration
+coco mcp add github \
+ --command "npx" \
+ --args "-y,@modelcontextprotocol/server-github" \
+ --env "GITHUB_TOKEN=$GITHUB_TOKEN"
+
+# List configured servers
+coco mcp list
+```
+
+### Configuration File
+
+Add MCP servers to `~/.coco/mcp.json` or your project's `coco.config.json`:
+
+```json
+{
+ "mcp": {
+ "enabled": true,
+ "servers": [
+ {
+ "name": "filesystem",
+ "transport": "stdio",
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
+ },
+ {
+ "name": "github",
+ "transport": "stdio",
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-github"],
+ "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
+ }
+ ]
+ }
+}
```
+### Popular MCP Servers
+
+| Server | Package | Description |
+|--------|---------|-------------|
+| **Filesystem** | `@modelcontextprotocol/server-filesystem` | Local file access |
+| **GitHub** | `@modelcontextprotocol/server-github` | GitHub API integration |
+| **PostgreSQL** | `@modelcontextprotocol/server-postgres` | Database queries |
+| **Slack** | `@modelcontextprotocol/server-slack` | Slack messaging |
+| **Google Drive** | `@modelcontextprotocol/server-gdrive` | Drive access |
+
+📖 See [MCP Documentation](docs/MCP.md) for full details and HTTP transport setup.
+
---
-## Documentation
+## 📚 The COCO Methodology
-### Guides
-- [Quick Start Guide](docs/guides/QUICK_START.md) - Get started in 5 minutes
-- [Configuration Guide](docs/guides/CONFIGURATION.md) - Complete configuration reference
-- [Tutorial](docs/guides/AGENT_EVALUATION_AND_TUTORIAL.md) - Detailed tutorial with examples
-- [Troubleshooting](docs/guides/TROUBLESHOOTING.md) - Common issues and solutions
+Four phases from idea to deployment:
+
+```
+┌──────────┐ ┌────────────┐ ┌──────────┐ ┌────────┐
+│ CONVERGE │ → │ ORCHESTRATE│ → │ COMPLETE │ → │ OUTPUT │
+└──────────┘ └────────────┘ └──────────┘ └────────┘
+ │ │ │ │
+ Understand Plan & Execute & Deploy &
+ Requirements Design Iterate Document
+```
-### Technical
-- [API Reference](docs/API.md) - Use Corbat-Coco as a library
-- [Architecture](docs/architecture/ARCHITECTURE.md) - System design & C4 diagrams
-- [ADRs](docs/architecture/adrs/) - Architecture Decision Records
-- [Production Readiness](docs/PRODUCTION_READINESS_ASSESSMENT.md) - Assessment & roadmap
+| Phase | What Happens | Output |
+|-------|--------------|--------|
+| **Converge** | Q&A to understand requirements | Specification |
+| **Orchestrate** | Architecture design, create backlog | ADRs, Stories, Tasks |
+| **Complete** | Build with quality iteration loops | Production code + tests |
+| **Output** | Generate deployment artifacts | CI/CD, Dockerfile, Docs |
---
-## Development
+## 🔧 Development
```bash
-# Clone the repository
+# Clone
git clone https://github.com/corbat/corbat-coco.git
cd corbat-coco
-# Install dependencies
+# Install
pnpm install
-# Run in development
-pnpm dev --help
+# Development mode
+pnpm dev
# Run tests
pnpm test
-# Run all checks
-pnpm check # typecheck + lint + test
+# Full check (typecheck + lint + test)
+pnpm check
# Build
pnpm build
@@ -406,69 +565,43 @@ pnpm build
---
-## Contributing
-
-Contributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md) first.
+## 🗺️ Roadmap
-### Quick Contribution Steps
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feat/amazing-feature`)
-3. Write tests (80% coverage minimum)
-4. Run checks (`pnpm check`)
-5. Commit with conventional commits
-6. Open a Pull Request
+- [x] Multi-provider support (Anthropic, OpenAI, Gemini, Kimi)
+- [x] Interactive REPL with autocomplete
+- [x] Checkpoint & recovery system
+- [ ] VS Code extension
+- [ ] Web dashboard
+- [ ] Team collaboration
+- [ ] Local model support (Ollama)
---
-## Troubleshooting
-
-### "API key not found"
-
-```bash
-export ANTHROPIC_API_KEY="sk-ant-..."
-```
-
-### "Quality score not improving"
-
-- Check the quality report for specific issues
-- Review suggestions in `.coco/versions/task-XXX/`
-- Consider adjusting `maxIterations`
+## 🤝 Contributing
-### "Checkpoint recovery failed"
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
```bash
-coco resume --from-checkpoint=
-# Or start fresh:
-coco build --restart
+# Quick contribution flow
+git checkout -b feat/amazing-feature
+pnpm check # Must pass
+git commit -m "feat: add amazing feature"
```
-For more help, see [Issues](https://github.com/corbat/corbat-coco/issues).
-
----
-
-## Roadmap
-
-- [ ] OpenAI provider support
-- [ ] Local model support (Ollama)
-- [ ] VS Code extension
-- [ ] Web dashboard
-- [ ] Team collaboration features
-
---
-## License
+## 📄 License
-MIT License - see [LICENSE](LICENSE) for details.
+MIT — See [LICENSE](LICENSE).
---
- Built with ❤️ by Corbat
+ Stop babysitting your AI. Let Coco iterate until it's right.
- GitHub •
- Issues •
- Changelog
+ ⭐ Star on GitHub •
+ Report Bug •
+ Discussions
diff --git a/examples/trusted-tools.json b/examples/trusted-tools.json
new file mode 100644
index 0000000..03b2d82
--- /dev/null
+++ b/examples/trusted-tools.json
@@ -0,0 +1,97 @@
+{
+ "$schema": "https://corbat.tech/schemas/trusted-tools.json",
+ "_comment": "Recommended trusted tools config. Copy to ~/.coco/trusted-tools.json",
+
+ "globalTrusted": [
+ "read_file",
+ "glob",
+ "list_dir",
+ "tree",
+ "file_exists",
+ "grep",
+ "find_in_file",
+ "git_status",
+ "git_diff",
+ "git_log",
+ "git_branch",
+ "run_linter",
+ "analyze_complexity",
+ "calculate_quality",
+ "get_coverage",
+ "command_exists"
+ ],
+
+ "projectTrusted": {
+ "_example_/path/to/your/project": [
+ "write_file",
+ "edit_file",
+ "copy_file",
+ "move_file",
+ "git_add",
+ "git_commit",
+ "run_tests",
+ "run_test_file",
+ "run_script",
+ "tsc"
+ ]
+ },
+
+ "_reference": {
+ "safe_to_trust_globally": {
+ "_description": "Read-only tools that never modify anything",
+ "tools": [
+ "read_file - Read file contents",
+ "glob - Find files by pattern",
+ "list_dir - List directory contents",
+ "tree - Directory tree view",
+ "file_exists - Check if file exists",
+ "grep - Search text in files",
+ "find_in_file - Find text in a file",
+ "git_status - Show git status",
+ "git_diff - Show git diff",
+ "git_log - Show git history",
+ "git_branch - List branches",
+ "command_exists - Check if command exists",
+ "run_linter - Run code linter (read-only)",
+ "analyze_complexity - Code complexity (read-only)",
+ "calculate_quality - Quality score (read-only)",
+ "get_coverage - Test coverage (read-only)"
+ ]
+ },
+
+ "trust_per_project": {
+ "_description": "Tools that modify files - trust only in specific projects",
+ "tools": [
+ "write_file - Create/overwrite file",
+ "edit_file - Edit file contents",
+ "copy_file - Copy file",
+ "move_file - Move/rename file",
+ "git_add - Stage changes",
+ "git_commit - Create commit (local only)",
+ "git_checkout - Switch branch",
+ "git_init - Initialize repo",
+ "run_tests - Run test suite",
+ "run_test_file - Run specific test",
+ "run_script - Run npm/pnpm script",
+ "tsc - Run TypeScript compiler"
+ ]
+ },
+
+ "always_ask": {
+ "_description": "High-risk tools that always show a confirmation prompt with warning",
+ "_note": "These tools work normally but cannot be auto-trusted - user must approve each time",
+ "tools": [
+ "delete_file - Permanently removes files",
+ "git_push - Pushes to remote (affects others)",
+ "git_pull - Pulls from remote (can overwrite local)",
+ "install_deps - Downloads and runs npm packages",
+ "make - Runs arbitrary Makefile targets",
+ "bash_exec - Executes arbitrary shell commands",
+ "bash_background - Runs background processes",
+ "http_fetch - Makes HTTP requests",
+ "http_json - Makes JSON API requests",
+ "get_env - Could expose sensitive env vars"
+ ]
+ }
+ }
+}
diff --git a/package.json b/package.json
index d6818ee..ac9306d 100644
--- a/package.json
+++ b/package.json
@@ -58,10 +58,11 @@
"ansi-escapes": "^7.3.0",
"chalk": "^5.4.0",
"commander": "^13.0.0",
- "dotenv": "^17.2.3",
- "execa": "^9.5.0",
+"execa": "^9.5.0",
"glob": "^11.0.0",
"json5": "^2.2.3",
+ "marked": "^15.0.0",
+ "marked-terminal": "^7.0.0",
"openai": "^6.17.0",
"ora": "^9.2.0",
"simple-git": "^3.27.0",
@@ -69,6 +70,7 @@
"zod": "^3.24.0"
},
"devDependencies": {
+ "@types/marked-terminal": "^6.1.1",
"@types/node": "^22.10.0",
"@vitest/coverage-v8": "^3.0.0",
"oxfmt": "^0.26.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ca9c8c3..065793f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -26,9 +26,6 @@ importers:
commander:
specifier: ^13.0.0
version: 13.1.0
- dotenv:
- specifier: ^17.2.3
- version: 17.2.3
execa:
specifier: ^9.5.0
version: 9.6.1
@@ -38,6 +35,12 @@ importers:
json5:
specifier: ^2.2.3
version: 2.2.3
+ marked:
+ specifier: ^15.0.0
+ version: 15.0.12
+ marked-terminal:
+ specifier: ^7.0.0
+ version: 7.3.0(marked@15.0.12)
openai:
specifier: ^6.17.0
version: 6.17.0(zod@3.25.76)
@@ -54,6 +57,9 @@ importers:
specifier: ^3.24.0
version: 3.25.76
devDependencies:
+ '@types/marked-terminal':
+ specifier: ^6.1.1
+ version: 6.1.1
'@types/node':
specifier: ^22.10.0
version: 22.19.7
@@ -118,6 +124,10 @@ packages:
'@clack/prompts@0.11.0':
resolution: {integrity: sha512-pMN5FcrEw9hUkZA4f+zLlzivQSeQf5dRGJjSUbvVYDLvpKCdQx5OaknvKzgbtXOizhP+SJJJjqEbOe55uKKfAw==}
+ '@colors/colors@1.5.0':
+ resolution: {integrity: sha512-ooWCrlZP11i8GImSjTHYHLkvFDP48nS4+204nGb1RiX/WXYHmJA2III9/e2DWVabCESdW7hBAEzHRqUn9OUVvQ==}
+ engines: {node: '>=0.1.90'}
+
'@esbuild/aix-ppc64@0.27.2':
resolution: {integrity: sha512-GZMB+a0mOMZs4MpDbj8RJp4cw+w1WV5NYD6xzgvzUJ5Ek2jerwfO2eADyI6ExDSUED+1X8aMbegahsJi+8mgpw==}
engines: {node: '>=18'}
@@ -543,10 +553,17 @@ packages:
'@shikijs/vscode-textmate@10.0.2':
resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==}
+ '@sindresorhus/is@4.6.0':
+ resolution: {integrity: sha512-t09vSN3MdfsyCHoFcTRCH/iUtG7OJ0CsjzB8cjAmKc/va/kIgeDI/TxsigdncE/4be734m0cvIYwNaV4i2XqAw==}
+ engines: {node: '>=10'}
+
'@sindresorhus/merge-streams@4.0.0':
resolution: {integrity: sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==}
engines: {node: '>=18'}
+ '@types/cardinal@2.1.1':
+ resolution: {integrity: sha512-/xCVwg8lWvahHsV2wXZt4i64H1sdL+sN1Uoq7fAc8/FA6uYHjuIveDwPwvGUYp4VZiv85dVl6J/Bum3NDAOm8g==}
+
'@types/chai@5.2.3':
resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==}
@@ -559,6 +576,9 @@ packages:
'@types/hast@3.0.4':
resolution: {integrity: sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==}
+ '@types/marked-terminal@6.1.1':
+ resolution: {integrity: sha512-DfoUqkmFDCED7eBY9vFUhJ9fW8oZcMAK5EwRDQ9drjTbpQa+DnBTQQCwWhTFVf4WsZ6yYcJTI8D91wxTWXRZZQ==}
+
'@types/node-fetch@2.6.13':
resolution: {integrity: sha512-QGpRVpzSaUs30JBSGPjOg4Uveu384erbHBoT1zeONvyCfwQxIkUshLAOqN/k9EjGviPRmWTTe6aH2qySWKTVSw==}
@@ -682,10 +702,18 @@ packages:
resolution: {integrity: sha512-4zNhdJD/iOjSH0A05ea+Ke6MU5mmpQcbQsSOkgdaUMJ9zTlDTD/GYlwohmIE2u0gaxHYiVHEn1Fw9mZ/ktJWgw==}
engines: {node: '>=18'}
+ chalk@4.1.2:
+ resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
+ engines: {node: '>=10'}
+
chalk@5.6.2:
resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
+ char-regex@1.0.2:
+ resolution: {integrity: sha512-kWWXztvZ5SBQV+eRgKFeh8q5sLuZY2+8WUIzlxWVTg+oGwY14qylx1KbKzHd8P6ZYkAg0xyIDU9JMHhyJMZ1jw==}
+ engines: {node: '>=10'}
+
check-error@2.1.3:
resolution: {integrity: sha512-PAJdDJusoxnwm1VwW07VWwUN1sl7smmC3OKggvndJFadxxDRyFJBX/ggnu/KE4kQAB7a3Dp8f/YXC1FlUprWmA==}
engines: {node: '>= 16'}
@@ -698,10 +726,22 @@ packages:
resolution: {integrity: sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==}
engines: {node: '>=18'}
+ cli-highlight@2.1.11:
+ resolution: {integrity: sha512-9KDcoEVwyUXrjcJNvHD0NFc/hiwe/WPVYIleQh2O1N2Zro5gWJZ/K+3DGn8w8P/F6FxOgzyC5bxDyHIgCSPhGg==}
+ engines: {node: '>=8.0.0', npm: '>=5.0.0'}
+ hasBin: true
+
cli-spinners@3.4.0:
resolution: {integrity: sha512-bXfOC4QcT1tKXGorxL3wbJm6XJPDqEnij2gQ2m7ESQuE+/z9YFIWnl/5RpTiKWbMq3EVKR4fRLJGn6DVfu0mpw==}
engines: {node: '>=18.20'}
+ cli-table3@0.6.5:
+ resolution: {integrity: sha512-+W/5efTR7y5HRD7gACw9yQjqMVvEMLBHmboM/kPWam+H+Hmyrgjh6YncVKK122YZkXrLudzTuAukUw9FnMf7IQ==}
+ engines: {node: 10.* || >= 12.*}
+
+ cliui@7.0.4:
+ resolution: {integrity: sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ==}
+
color-convert@2.0.1:
resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
engines: {node: '>=7.0.0'}
@@ -749,10 +789,6 @@ packages:
resolution: {integrity: sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==}
engines: {node: '>=0.4.0'}
- dotenv@17.2.3:
- resolution: {integrity: sha512-JVUnt+DUIzu87TABbhPmNfVdBDt18BLOWjMUFJMSi/Qqg7NTYtabbvSNJGOJ7afbRuv9D/lngizHtP7QyLQ+9w==}
- engines: {node: '>=12'}
-
dunder-proto@1.0.1:
resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
engines: {node: '>= 0.4'}
@@ -766,6 +802,9 @@ packages:
emoji-regex@9.2.2:
resolution: {integrity: sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==}
+ emojilib@2.4.0:
+ resolution: {integrity: sha512-5U0rVMU5Y2n2+ykNLQqMoqklN9ICBT/KsvC1Gz6vqHbz2AXXGkG+Pm5rMWk/8Vjrr/mY9985Hi8DYzn1F09Nyw==}
+
entities@4.5.0:
resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==}
engines: {node: '>=0.12'}
@@ -798,6 +837,10 @@ packages:
engines: {node: '>=18'}
hasBin: true
+ escalade@3.2.0:
+ resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==}
+ engines: {node: '>=6'}
+
estree-walker@3.0.3:
resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}
@@ -852,6 +895,10 @@ packages:
function-bind@1.1.2:
resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==}
+ get-caller-file@2.0.5:
+ resolution: {integrity: sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==}
+ engines: {node: 6.* || 8.* || >= 10.*}
+
get-east-asian-width@1.4.0:
resolution: {integrity: sha512-QZjmEOC+IT1uk6Rx0sX22V6uHWVwbdbxf1faPqJ1QhLdGgsRGCZoyaQBm/piRdJy/D2um6hM1UP7ZEeQ4EkP+Q==}
engines: {node: '>=18'}
@@ -900,6 +947,9 @@ packages:
resolution: {integrity: sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==}
engines: {node: '>= 0.4'}
+ highlight.js@10.7.3:
+ resolution: {integrity: sha512-tzcUFauisWKNHaRkN4Wjl/ZA07gENAjFl3J/c480dprkGTg5EQstgaNFqBfUqCq54kZRIEcreTsAgF/m2quD7A==}
+
html-escaper@2.0.2:
resolution: {integrity: sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==}
@@ -1013,6 +1063,22 @@ packages:
resolution: {integrity: sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==}
hasBin: true
+ marked-terminal@7.3.0:
+ resolution: {integrity: sha512-t4rBvPsHc57uE/2nJOLmMbZCQ4tgAccAED3ngXQqW6g+TxA488JzJ+FK3lQkzBQOI1mRV/r/Kq+1ZlJ4D0owQw==}
+ engines: {node: '>=16.0.0'}
+ peerDependencies:
+ marked: '>=1 <16'
+
+ marked@11.2.0:
+ resolution: {integrity: sha512-HR0m3bvu0jAPYiIvLUUQtdg1g6D247//lvcekpHO1WMvbwDlwSkZAX9Lw4F4YHE1T0HaaNve0tuAWuV1UJ6vtw==}
+ engines: {node: '>= 18'}
+ hasBin: true
+
+ marked@15.0.12:
+ resolution: {integrity: sha512-8dD6FusOQSrpv9Z1rdNMdlSgQOIP880DHqnohobOmYLElGEqAL/JvxvuxZO16r4HtjTlfPRDC1hbvxC9dPN2nA==}
+ engines: {node: '>= 18'}
+ hasBin: true
+
math-intrinsics@1.1.0:
resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
engines: {node: '>= 0.4'}
@@ -1063,6 +1129,10 @@ packages:
engines: {node: '>=10.5.0'}
deprecated: Use your platform's native DOMException instead
+ node-emoji@2.2.0:
+ resolution: {integrity: sha512-Z3lTE9pLaJF47NyMhd4ww1yFTAP8YhYI8SleJiHzM46Fgpm5cnNzSl9XfzFNqbaz+VlJrIj3fXQ4DeN1Rjm6cw==}
+ engines: {node: '>=18'}
+
node-fetch@2.7.0:
resolution: {integrity: sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==}
engines: {node: 4.x || >=6.0.0}
@@ -1117,6 +1187,15 @@ packages:
resolution: {integrity: sha512-TXfryirbmq34y8QBwgqCVLi+8oA3oWx2eAnSn62ITyEhEYaWRlVZ2DvMM9eZbMs/RfxPu/PK/aBLyGj4IrqMHw==}
engines: {node: '>=18'}
+ parse5-htmlparser2-tree-adapter@6.0.1:
+ resolution: {integrity: sha512-qPuWvbLgvDGilKc5BoicRovlT4MtYT6JfJyBOMDsKoiT+GiuP5qyrPCnR9HcPECIJJmZh5jRndyNThnhhb/vlA==}
+
+ parse5@5.1.1:
+ resolution: {integrity: sha512-ugq4DFI0Ptb+WWjAdOK16+u/nHfiIrcE+sh8kZMaM0WllQKLI9rOUq6c2b7cwPkXdzfQESqvoqK6ug7U/Yyzug==}
+
+ parse5@6.0.1:
+ resolution: {integrity: sha512-Ofn/CTFzRGTTxwpNEs9PP93gXShHcTq255nzRYSKe8AkVpZY7e1fpmTfOyoIvjP5HG7Z2ZM7VS9PPhQGW2pOpw==}
+
path-key@3.1.1:
resolution: {integrity: sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==}
engines: {node: '>=8'}
@@ -1188,6 +1267,10 @@ packages:
resolution: {integrity: sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==}
engines: {node: '>= 14.18.0'}
+ require-directory@2.1.1:
+ resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
+ engines: {node: '>=0.10.0'}
+
resolve-from@5.0.0:
resolution: {integrity: sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==}
engines: {node: '>=8'}
@@ -1230,6 +1313,10 @@ packages:
sisteransi@1.0.5:
resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
+ skin-tone@2.0.0:
+ resolution: {integrity: sha512-kUMbT1oBJCpgrnKoSr0o6wPtvRWT9W9UKvGLwfJYO2WuahZRHOpEyL1ckyMGgMWh0UdpmaoFqKKD29WTomNEGA==}
+ engines: {node: '>=8'}
+
source-map-js@1.2.1:
resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
engines: {node: '>=0.10.0'}
@@ -1284,6 +1371,10 @@ packages:
resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==}
engines: {node: '>=8'}
+ supports-hyperlinks@3.2.0:
+ resolution: {integrity: sha512-zFObLMyZeEwzAoKCyu1B91U79K2t7ApXuQfo8OuxwXLDgcKxuwM+YvcbIhm6QWqz7mHUH1TVytR1PwVVjEuMig==}
+ engines: {node: '>=14.18'}
+
test-exclude@7.0.1:
resolution: {integrity: sha512-pFYqmTw68LXVjeWJMST4+borgQP2AyMNbg1BpZh9LbyhUeNkeaPF9gzfPGUAnSMV3qPYdWUwDIjjCLiSDOl7vg==}
engines: {node: '>=18'}
@@ -1383,6 +1474,10 @@ packages:
undici-types@6.21.0:
resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
+ unicode-emoji-modifier-base@1.0.0:
+ resolution: {integrity: sha512-yLSH4py7oFH3oG/9K+XWrz1pSi3dfUrWEnInbxMfArOfc1+33BlGPQtLsOYwvdMy11AwUBetYuaRxSPqgkq+8g==}
+ engines: {node: '>=4'}
+
unicorn-magic@0.3.0:
resolution: {integrity: sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==}
engines: {node: '>=18'}
@@ -1488,11 +1583,23 @@ packages:
resolution: {integrity: sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ==}
engines: {node: '>=12'}
+ y18n@5.0.8:
+ resolution: {integrity: sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==}
+ engines: {node: '>=10'}
+
yaml@2.8.2:
resolution: {integrity: sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==}
engines: {node: '>= 14.6'}
hasBin: true
+ yargs-parser@20.2.9:
+ resolution: {integrity: sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w==}
+ engines: {node: '>=10'}
+
+ yargs@16.2.0:
+ resolution: {integrity: sha512-D1mvvtDG0L5ft/jGWkLpG1+m0eQxOfaBvTNELraWj22wSVUMWxZUvYgJYcKh6jGGIkJFhH4IZPQhR4TKpc8mBw==}
+ engines: {node: '>=10'}
+
yoctocolors@2.1.2:
resolution: {integrity: sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug==}
engines: {node: '>=18'}
@@ -1545,6 +1652,9 @@ snapshots:
picocolors: 1.1.1
sisteransi: 1.0.5
+ '@colors/colors@1.5.0':
+ optional: true
+
'@esbuild/aix-ppc64@0.27.2':
optional: true
@@ -1820,8 +1930,12 @@ snapshots:
'@shikijs/vscode-textmate@10.0.2': {}
+ '@sindresorhus/is@4.6.0': {}
+
'@sindresorhus/merge-streams@4.0.0': {}
+ '@types/cardinal@2.1.1': {}
+
'@types/chai@5.2.3':
dependencies:
'@types/deep-eql': 4.0.2
@@ -1835,6 +1949,13 @@ snapshots:
dependencies:
'@types/unist': 3.0.3
+ '@types/marked-terminal@6.1.1':
+ dependencies:
+ '@types/cardinal': 2.1.1
+ '@types/node': 22.19.7
+ chalk: 5.6.2
+ marked: 11.2.0
+
'@types/node-fetch@2.6.13':
dependencies:
'@types/node': 22.19.7
@@ -1975,8 +2096,15 @@ snapshots:
loupe: 3.2.1
pathval: 2.0.1
+ chalk@4.1.2:
+ dependencies:
+ ansi-styles: 4.3.0
+ supports-color: 7.2.0
+
chalk@5.6.2: {}
+ char-regex@1.0.2: {}
+
check-error@2.1.3: {}
chokidar@4.0.3:
@@ -1987,8 +2115,29 @@ snapshots:
dependencies:
restore-cursor: 5.1.0
+ cli-highlight@2.1.11:
+ dependencies:
+ chalk: 4.1.2
+ highlight.js: 10.7.3
+ mz: 2.7.0
+ parse5: 5.1.1
+ parse5-htmlparser2-tree-adapter: 6.0.1
+ yargs: 16.2.0
+
cli-spinners@3.4.0: {}
+ cli-table3@0.6.5:
+ dependencies:
+ string-width: 4.2.3
+ optionalDependencies:
+ '@colors/colors': 1.5.0
+
+ cliui@7.0.4:
+ dependencies:
+ string-width: 4.2.3
+ strip-ansi: 6.0.1
+ wrap-ansi: 7.0.0
+
color-convert@2.0.1:
dependencies:
color-name: 1.1.4
@@ -2021,8 +2170,6 @@ snapshots:
delayed-stream@1.0.0: {}
- dotenv@17.2.3: {}
-
dunder-proto@1.0.1:
dependencies:
call-bind-apply-helpers: 1.0.2
@@ -2035,6 +2182,8 @@ snapshots:
emoji-regex@9.2.2: {}
+ emojilib@2.4.0: {}
+
entities@4.5.0: {}
environment@1.1.0: {}
@@ -2085,6 +2234,8 @@ snapshots:
'@esbuild/win32-ia32': 0.27.2
'@esbuild/win32-x64': 0.27.2
+ escalade@3.2.0: {}
+
estree-walker@3.0.3:
dependencies:
'@types/estree': 1.0.8
@@ -2147,6 +2298,8 @@ snapshots:
function-bind@1.1.2: {}
+ get-caller-file@2.0.5: {}
+
get-east-asian-width@1.4.0: {}
get-intrinsic@1.3.0:
@@ -2208,6 +2361,8 @@ snapshots:
dependencies:
function-bind: 1.1.2
+ highlight.js@10.7.3: {}
+
html-escaper@2.0.2: {}
human-signals@8.0.1: {}
@@ -2311,6 +2466,21 @@ snapshots:
punycode.js: 2.3.1
uc.micro: 2.1.0
+ marked-terminal@7.3.0(marked@15.0.12):
+ dependencies:
+ ansi-escapes: 7.3.0
+ ansi-regex: 6.2.2
+ chalk: 5.6.2
+ cli-highlight: 2.1.11
+ cli-table3: 0.6.5
+ marked: 15.0.12
+ node-emoji: 2.2.0
+ supports-hyperlinks: 3.2.0
+
+ marked@11.2.0: {}
+
+ marked@15.0.12: {}
+
math-intrinsics@1.1.0: {}
mdurl@2.0.0: {}
@@ -2352,6 +2522,13 @@ snapshots:
node-domexception@1.0.0: {}
+ node-emoji@2.2.0:
+ dependencies:
+ '@sindresorhus/is': 4.6.0
+ char-regex: 1.0.2
+ emojilib: 2.4.0
+ skin-tone: 2.0.0
+
node-fetch@2.7.0:
dependencies:
whatwg-url: 5.0.0
@@ -2410,6 +2587,14 @@ snapshots:
parse-ms@4.0.0: {}
+ parse5-htmlparser2-tree-adapter@6.0.1:
+ dependencies:
+ parse5: 6.0.1
+
+ parse5@5.1.1: {}
+
+ parse5@6.0.1: {}
+
path-key@3.1.1: {}
path-key@4.0.0: {}
@@ -2462,6 +2647,8 @@ snapshots:
readdirp@4.1.2: {}
+ require-directory@2.1.1: {}
+
resolve-from@5.0.0: {}
resolve-pkg-maps@1.0.0: {}
@@ -2524,6 +2711,10 @@ snapshots:
sisteransi@1.0.5: {}
+ skin-tone@2.0.0:
+ dependencies:
+ unicode-emoji-modifier-base: 1.0.0
+
source-map-js@1.2.1: {}
source-map@0.7.6: {}
@@ -2579,6 +2770,11 @@ snapshots:
dependencies:
has-flag: 4.0.0
+ supports-hyperlinks@3.2.0:
+ dependencies:
+ has-flag: 4.0.0
+ supports-color: 7.2.0
+
test-exclude@7.0.1:
dependencies:
'@istanbuljs/schema': 0.1.3
@@ -2672,6 +2868,8 @@ snapshots:
undici-types@6.21.0: {}
+ unicode-emoji-modifier-base@1.0.0: {}
+
unicorn-magic@0.3.0: {}
vite-node@3.2.4(@types/node@22.19.7)(tsx@4.21.0)(yaml@2.8.2):
@@ -2780,8 +2978,22 @@ snapshots:
string-width: 5.1.2
strip-ansi: 7.1.2
+ y18n@5.0.8: {}
+
yaml@2.8.2: {}
+ yargs-parser@20.2.9: {}
+
+ yargs@16.2.0:
+ dependencies:
+ cliui: 7.0.4
+ escalade: 3.2.0
+ get-caller-file: 2.0.5
+ require-directory: 2.1.1
+ string-width: 4.2.3
+ y18n: 5.0.8
+ yargs-parser: 20.2.9
+
yoctocolors@2.1.2: {}
zod@3.25.76: {}
diff --git a/src/auth/callback-server.ts b/src/auth/callback-server.ts
new file mode 100644
index 0000000..4d5ecd3
--- /dev/null
+++ b/src/auth/callback-server.ts
@@ -0,0 +1,464 @@
+/**
+ * Local HTTP server for OAuth callback
+ *
+ * Starts a temporary server on localhost to receive the authorization code
+ * after the user completes authentication in the browser.
+ *
+ * The server:
+ * 1. Listens on port 1455 (same as OpenCode/Codex CLI for compatibility)
+ * 2. Waits for the OAuth provider to redirect with the auth code
+ * 3. Extracts the code and state from the callback URL
+ * 4. Shows a success page and shuts down
+ */
+
+/**
+ * Default OAuth callback port (same as OpenCode and Codex CLI)
+ * Using a fixed port ensures consistency with OpenAI's OAuth flow
+ */
+export const OAUTH_CALLBACK_PORT = 1455;
+
+import * as http from "node:http";
+
+/**
+ * Escape a string for safe HTML insertion to prevent XSS
+ */
+function escapeHtml(unsafe: string): string {
+ return unsafe
+ .replace(/&/g, "&")
+ .replace(//g, ">")
+ .replace(/"/g, """)
+ .replace(/'/g, "'");
+}
+import { URL } from "node:url";
+
+/**
+ * Result from the callback server
+ */
+export interface CallbackResult {
+ code: string;
+ state: string;
+}
+
+/**
+ * Success HTML page shown to user after authentication
+ */
+const SUCCESS_HTML = `
+
+
+
+
+
+ Authentication Successful
+
+
+
+
+
+
Authentication Successful!
+
You can close this window and return to your terminal.
+
+ Powered by Corbat-Coco
+
+
+
+
Authentication Failed
+
Something went wrong. Please try again.
+
${safeError}
+
Authentication Failed
+ Error: ${safeError}
+ You can close this window.
+
+
+ `);
+ server.close();
+ reject(new Error(`OAuth error: ${error}`));
+ return;
+ }
+
+ if (state !== expectedState) {
+ res.writeHead(400, { "Content-Type": "text/html" });
+ res.end(`
+
+
+ Authentication Failed
+ Invalid state parameter (possible CSRF attack).
+ You can close this window.
+
+
+ `);
+ server.close();
+ reject(new Error("Invalid state parameter"));
+ return;
+ }
+
+ if (!code) {
+ res.writeHead(400, { "Content-Type": "text/html" });
+ res.end(`
+
+
+ Authentication Failed
+ No authorization code received.
+ You can close this window.
+
+
+ `);
+ server.close();
+ reject(new Error("No authorization code"));
+ return;
+ }
+
+ res.writeHead(200, { "Content-Type": "text/html" });
+ res.end(`
+
+
+ Authentication Successful!
+ You can close this window and return to the terminal.
+
+
+
+ `);
+ server.close();
+ resolve(code);
+ } else {
+ res.writeHead(404);
+ res.end();
+ }
+ });
+
+ server.listen(port, "localhost", () => {
+ // Server started
+ });
+
+ // Timeout after 5 minutes
+ setTimeout(
+ () => {
+ server.close();
+ reject(new Error("Authentication timeout"));
+ },
+ 5 * 60 * 1000,
+ );
+ });
+}
+
+/**
+ * Perform browser-based OAuth flow with PKCE
+ */
+export async function browserOAuthFlow(
+ config: OAuthConfig,
+ onUrlReady?: (url: string) => void,
+): Promise {
+ const pkce = generatePKCE();
+ const state = generateState();
+
+ // Parse port from redirect URI
+ const redirectUrl = new URL(config.redirectUri);
+ const port = parseInt(redirectUrl.port, 10) || 8090;
+
+ // Start callback server
+ const codePromise = startCallbackServer(port, state);
+
+ // Build authorization URL
+ const authUrl = buildAuthorizationUrl(config, pkce, state);
+
+ // Notify caller about URL (for display)
+ onUrlReady?.(authUrl);
+
+ // Open browser
+ await openBrowser(authUrl);
+
+ // Wait for callback
+ const code = await codePromise;
+
+ // Exchange code for tokens
+ return exchangeCodeForTokens(config, code, pkce);
+}
+
+/**
+ * Request device code for device code flow
+ */
+export async function requestDeviceCode(config: OAuthConfig): Promise {
+ if (!config.deviceAuthorizationUrl) {
+ throw new Error("Device authorization URL not configured");
+ }
+
+ const body = new URLSearchParams({
+ client_id: config.clientId,
+ scope: config.scopes.join(" "),
+ });
+
+ const response = await fetch(config.deviceAuthorizationUrl, {
+ method: "POST",
+ headers: {
+ "Content-Type": "application/x-www-form-urlencoded",
+ },
+ body: body.toString(),
+ });
+
+ if (!response.ok) {
+ const errorText = await response.text();
+ throw new Error(`Device code request failed: ${response.status} ${errorText}`);
+ }
+
+ const data = (await response.json()) as Record;
+
+ return {
+ deviceCode: data.device_code as string,
+ userCode: data.user_code as string,
+ verificationUri: data.verification_uri as string,
+ verificationUriComplete: data.verification_uri_complete as string | undefined,
+ expiresIn: data.expires_in as number,
+ interval: (data.interval as number) ?? 5,
+ };
+}
+
+/**
+ * Poll for tokens in device code flow
+ */
+export async function pollForDeviceTokens(
+ config: OAuthConfig,
+ deviceCode: string,
+ interval: number,
+ expiresIn: number,
+): Promise {
+ const startTime = Date.now();
+ const expiresAt = startTime + expiresIn * 1000;
+
+ while (Date.now() < expiresAt) {
+ await new Promise((resolve) => setTimeout(resolve, interval * 1000));
+
+ const body = new URLSearchParams({
+ client_id: config.clientId,
+ grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+ device_code: deviceCode,
+ });
+
+ const response = await fetch(config.tokenUrl, {
+ method: "POST",
+ headers: {
+ "Content-Type": "application/x-www-form-urlencoded",
+ },
+ body: body.toString(),
+ });
+
+ const data = (await response.json()) as Record;
+
+ if (response.ok) {
+ return {
+ accessToken: data.access_token as string,
+ refreshToken: data.refresh_token as string,
+ expiresIn: data.expires_in as number,
+ tokenType: data.token_type as string,
+ scope: data.scope as string | undefined,
+ };
+ }
+
+ // Check for pending authorization
+ if (data.error === "authorization_pending") {
+ continue;
+ }
+
+ // Check for slow down request
+ if (data.error === "slow_down") {
+ interval = Math.min(interval + 5, 30);
+ continue;
+ }
+
+ // Other errors are fatal
+ throw new Error(`Device token polling failed: ${data.error} - ${data.error_description}`);
+ }
+
+ throw new Error("Device code expired");
+}
+
+/**
+ * Perform device code OAuth flow
+ */
+export async function deviceCodeOAuthFlow(
+ config: OAuthConfig,
+ onCodeReady?: (code: DeviceCodeResponse) => void,
+): Promise {
+ const deviceCode = await requestDeviceCode(config);
+
+ // Notify caller about the code
+ onCodeReady?.(deviceCode);
+
+ // Poll for tokens
+ return pollForDeviceTokens(
+ config,
+ deviceCode.deviceCode,
+ deviceCode.interval,
+ deviceCode.expiresIn,
+ );
+}
diff --git a/src/providers/auth/token-store.ts b/src/providers/auth/token-store.ts
new file mode 100644
index 0000000..be6c517
--- /dev/null
+++ b/src/providers/auth/token-store.ts
@@ -0,0 +1,193 @@
+/**
+ * Secure token storage for OAuth tokens
+ * Stores tokens in ~/.config/coco/auth.json with restricted permissions
+ */
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { OAuthTokens } from "./oauth.js";
+
+/**
+ * Stored token data with metadata
+ */
+export interface StoredToken extends OAuthTokens {
+ provider: string;
+ createdAt: number;
+ expiresAt?: number;
+}
+
+/**
+ * Token store structure
+ */
+interface TokenStoreData {
+ version: number;
+ tokens: Record;
+}
+
+/**
+ * Get the config directory path
+ */
+function getConfigDir(): string {
+ const xdgConfig = process.env.XDG_CONFIG_HOME;
+ if (xdgConfig) {
+ return join(xdgConfig, "coco");
+ }
+ return join(homedir(), ".config", "coco");
+}
+
+/**
+ * Get the token store file path
+ */
+function getTokenStorePath(): string {
+ return join(getConfigDir(), "auth.json");
+}
+
+/**
+ * Ensure config directory exists with secure permissions
+ */
+async function ensureConfigDir(): Promise {
+ const dir = getConfigDir();
+ try {
+ await mkdir(dir, { recursive: true, mode: 0o700 });
+ } catch (error) {
+ // Directory might already exist
+ if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+ throw error;
+ }
+ }
+}
+
+/**
+ * Load token store from disk
+ */
+async function loadTokenStore(): Promise {
+ const path = getTokenStorePath();
+
+ try {
+ const content = await readFile(path, "utf-8");
+ const data = JSON.parse(content) as TokenStoreData;
+
+ // Validate version
+ if (data.version !== 1) {
+ // Future: handle migration
+ return { version: 1, tokens: {} };
+ }
+
+ return data;
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+ return { version: 1, tokens: {} };
+ }
+ throw error;
+ }
+}
+
+/**
+ * Save token store to disk with secure permissions
+ */
+async function saveTokenStore(data: TokenStoreData): Promise {
+ await ensureConfigDir();
+
+ const path = getTokenStorePath();
+ const content = JSON.stringify(data, null, 2);
+
+ await writeFile(path, content, { mode: 0o600 });
+}
+
+/**
+ * Save a token for a provider
+ */
+export async function saveToken(provider: string, tokens: OAuthTokens): Promise {
+ const store = await loadTokenStore();
+
+ const createdAt = Date.now();
+ const expiresAt = tokens.expiresIn ? createdAt + tokens.expiresIn * 1000 : undefined;
+
+ store.tokens[provider] = {
+ ...tokens,
+ provider,
+ createdAt,
+ expiresAt,
+ };
+
+ await saveTokenStore(store);
+}
+
+/**
+ * Get a token for a provider
+ */
+export async function getToken(provider: string): Promise {
+ const store = await loadTokenStore();
+ return store.tokens[provider] ?? null;
+}
+
+/**
+ * Get a valid access token, refreshing if needed
+ */
+export async function getValidToken(
+ provider: string,
+ refreshFn?: (refreshToken: string) => Promise,
+): Promise {
+ const token = await getToken(provider);
+
+ if (!token) {
+ return null;
+ }
+
+ // Check if token is expired or will expire soon (5 minute buffer)
+ const now = Date.now();
+ const expirationBuffer = 5 * 60 * 1000; // 5 minutes
+
+ if (token.expiresAt && token.expiresAt - expirationBuffer < now) {
+ // Token is expired or will expire soon
+ if (token.refreshToken && refreshFn) {
+ try {
+ const newTokens = await refreshFn(token.refreshToken);
+ await saveToken(provider, newTokens);
+ return newTokens.accessToken;
+ } catch {
+ // Refresh failed, token is invalid
+ await deleteToken(provider);
+ return null;
+ }
+ }
+ // No refresh token, token is invalid
+ await deleteToken(provider);
+ return null;
+ }
+
+ return token.accessToken;
+}
+
+/**
+ * Delete a token for a provider
+ */
+export async function deleteToken(provider: string): Promise {
+ const store = await loadTokenStore();
+ delete store.tokens[provider];
+ await saveTokenStore(store);
+}
+
+/**
+ * List all stored tokens
+ */
+export async function listTokens(): Promise {
+ const store = await loadTokenStore();
+ return Object.values(store.tokens);
+}
+
+/**
+ * Check if a token exists for a provider
+ */
+export async function hasToken(provider: string): Promise {
+ const token = await getToken(provider);
+ return token !== null;
+}
+
+/**
+ * Clear all stored tokens
+ */
+export async function clearAllTokens(): Promise {
+ await saveTokenStore({ version: 1, tokens: {} });
+}
diff --git a/src/providers/codex.test.ts b/src/providers/codex.test.ts
new file mode 100644
index 0000000..26b18e7
--- /dev/null
+++ b/src/providers/codex.test.ts
@@ -0,0 +1,743 @@
+/**
+ * Tests for OpenAI Codex provider
+ */
+
+import { describe, it, expect, vi, beforeEach, type Mock } from "vitest";
+
+// Mock the auth module
+const mockGetValidAccessToken = vi.fn();
+vi.mock("../auth/index.js", () => ({
+ getValidAccessToken: (...args: unknown[]) => mockGetValidAccessToken(...args),
+}));
+
+// Mock global fetch
+const mockFetch = vi.fn() as Mock;
+vi.stubGlobal("fetch", mockFetch);
+
+/**
+ * Helper: create a JWT token with custom claims payload.
+ * Format: header.payload.signature (base64url encoded)
+ */
+function createFakeJwt(claims: Record): string {
+ const header = Buffer.from(JSON.stringify({ alg: "RS256" })).toString("base64url");
+ const payload = Buffer.from(JSON.stringify(claims)).toString("base64url");
+ return `${header}.${payload}.fake-signature`;
+}
+
+/**
+ * Helper: build a ReadableStream that yields SSE lines from an array of event objects
+ */
+function buildSSEStream(events: Array>): ReadableStream {
+ const encoder = new TextEncoder();
+ const lines = events.map((e) => `data: ${JSON.stringify(e)}\n\n`);
+ lines.push("data: [DONE]\n\n");
+
+ let index = 0;
+ return new ReadableStream({
+ pull(controller) {
+ if (index < lines.length) {
+ controller.enqueue(encoder.encode(lines[index]));
+ index++;
+ } else {
+ controller.close();
+ }
+ },
+ });
+}
+
+/**
+ * Helper: mock a successful Codex API response with the given content
+ */
+function mockSuccessfulChatResponse(
+ content: string,
+ opts?: { id?: string; inputTokens?: number; outputTokens?: number; status?: string },
+) {
+ const id = opts?.id ?? "resp-test-123";
+ const inputTokens = opts?.inputTokens ?? 100;
+ const outputTokens = opts?.outputTokens ?? 50;
+ const status = opts?.status ?? "completed";
+
+ const events = [
+ { id, type: "response.created" },
+ { type: "response.output_text.delta", delta: content },
+ {
+ type: "response.completed",
+ response: {
+ id,
+ status,
+ usage: { input_tokens: inputTokens, output_tokens: outputTokens },
+ },
+ },
+ ];
+
+ mockFetch.mockResolvedValue({
+ ok: true,
+ body: buildSSEStream(events),
+ });
+}
+
+describe("CodexProvider", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ });
+
+ describe("initialize", () => {
+ it("should initialize with OAuth token from token store", async () => {
+ const token = createFakeJwt({ chatgpt_account_id: "acct-123" });
+ mockGetValidAccessToken.mockResolvedValue({ accessToken: token });
+
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+ await provider.initialize({});
+
+ expect(mockGetValidAccessToken).toHaveBeenCalledWith("openai");
+ });
+
+ it("should initialize with apiKey fallback when no OAuth token", async () => {
+ const token = createFakeJwt({ chatgpt_account_id: "acct-456" });
+ mockGetValidAccessToken.mockResolvedValue(null);
+
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+ await provider.initialize({ apiKey: token });
+
+ // Should not throw
+ });
+
+ it("should throw when no OAuth token and no API key", async () => {
+ mockGetValidAccessToken.mockResolvedValue(null);
+
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+
+ await expect(provider.initialize({})).rejects.toThrow(/No OAuth token found/);
+ });
+
+ it("should extract account ID from chatgpt_account_id claim", async () => {
+ const token = createFakeJwt({ chatgpt_account_id: "acct-direct" });
+ mockGetValidAccessToken.mockResolvedValue({ accessToken: token });
+
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+ await provider.initialize({});
+
+ // Verify account ID is used in requests
+ mockSuccessfulChatResponse("Hello");
+ await provider.chat([{ role: "user", content: "Hi" }]);
+
+ const fetchCall = mockFetch.mock.calls[0] as [string, RequestInit];
+ const headers = fetchCall[1].headers as Record;
+ expect(headers["ChatGPT-Account-Id"]).toBe("acct-direct");
+ });
+
+ it("should extract account ID from auth sub-claim", async () => {
+ const token = createFakeJwt({
+ "https://api.openai.com/auth": { chatgpt_account_id: "acct-auth" },
+ });
+ mockGetValidAccessToken.mockResolvedValue({ accessToken: token });
+
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+ await provider.initialize({});
+
+ mockSuccessfulChatResponse("Hi");
+ await provider.chat([{ role: "user", content: "test" }]);
+
+ const fetchCall = mockFetch.mock.calls[0] as [string, RequestInit];
+ const headers = fetchCall[1].headers as Record;
+ expect(headers["ChatGPT-Account-Id"]).toBe("acct-auth");
+ });
+
+ it("should extract account ID from organizations claim", async () => {
+ const token = createFakeJwt({
+ organizations: [{ id: "org-123" }],
+ });
+ mockGetValidAccessToken.mockResolvedValue({ accessToken: token });
+
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+ await provider.initialize({});
+
+ mockSuccessfulChatResponse("Hi");
+ await provider.chat([{ role: "user", content: "test" }]);
+
+ const fetchCall = mockFetch.mock.calls[0] as [string, RequestInit];
+ const headers = fetchCall[1].headers as Record;
+ expect(headers["ChatGPT-Account-Id"]).toBe("org-123");
+ });
+
+ it("should handle invalid JWT gracefully (no account ID)", async () => {
+ mockGetValidAccessToken.mockResolvedValue({ accessToken: "not-a-jwt" });
+
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+ await provider.initialize({});
+
+ // Should not throw; account ID is simply undefined
+ mockSuccessfulChatResponse("Hi");
+ await provider.chat([{ role: "user", content: "test" }]);
+
+ const fetchCall = mockFetch.mock.calls[0] as [string, RequestInit];
+ const headers = fetchCall[1].headers as Record;
+ expect(headers["ChatGPT-Account-Id"]).toBeUndefined();
+ });
+ });
+
+ describe("id and name", () => {
+ it("should have correct id and name", async () => {
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+
+ expect(provider.id).toBe("codex");
+ expect(provider.name).toBe("OpenAI Codex (ChatGPT Plus/Pro)");
+ });
+ });
+
+ describe("getContextWindow", () => {
+ it("should return 200000 for gpt-5.2-codex (default)", async () => {
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+
+ expect(provider.getContextWindow()).toBe(200000);
+ });
+
+ it("should return 200000 for gpt-5-codex", async () => {
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+
+ expect(provider.getContextWindow("gpt-5-codex")).toBe(200000);
+ });
+
+ it("should return 200000 for configured model", async () => {
+ const token = createFakeJwt({});
+ mockGetValidAccessToken.mockResolvedValue({ accessToken: token });
+
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+ await provider.initialize({ model: "gpt-5" });
+
+ expect(provider.getContextWindow()).toBe(200000);
+ });
+
+ it("should return 128000 for unknown model", async () => {
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+
+ expect(provider.getContextWindow("unknown-model")).toBe(128000);
+ });
+ });
+
+ describe("countTokens", () => {
+ it("should estimate tokens as ceil(length/4)", async () => {
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+
+ // "Hello" = 5 chars => ceil(5/4) = 2
+ expect(provider.countTokens("Hello")).toBe(2);
+ });
+
+ it("should return 0 for empty string", async () => {
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+
+ expect(provider.countTokens("")).toBe(0);
+ });
+
+ it("should handle longer text", async () => {
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+
+ // 100 chars => ceil(100/4) = 25
+ const text = "a".repeat(100);
+ expect(provider.countTokens(text)).toBe(25);
+ });
+ });
+
+ describe("isAvailable", () => {
+ it("should return true when OAuth token is available", async () => {
+ const token = createFakeJwt({});
+ mockGetValidAccessToken.mockResolvedValue({ accessToken: token });
+
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+
+ expect(await provider.isAvailable()).toBe(true);
+ });
+
+ it("should return false when no OAuth token", async () => {
+ mockGetValidAccessToken.mockResolvedValue(null);
+
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+
+ expect(await provider.isAvailable()).toBe(false);
+ });
+
+ it("should return false when token retrieval throws", async () => {
+ mockGetValidAccessToken.mockRejectedValue(new Error("Token error"));
+
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+
+ expect(await provider.isAvailable()).toBe(false);
+ });
+ });
+
+ describe("chat", () => {
+ async function initProvider() {
+ const token = createFakeJwt({ chatgpt_account_id: "acct-test" });
+ mockGetValidAccessToken.mockResolvedValue({ accessToken: token });
+
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+ await provider.initialize({});
+ return provider;
+ }
+
+ it("should throw ProviderError if not initialized", async () => {
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+
+ await expect(provider.chat([{ role: "user", content: "Hello" }])).rejects.toThrow(
+ /not initialized/i,
+ );
+ });
+
+ it("should send chat message and return response", async () => {
+ const provider = await initProvider();
+ mockSuccessfulChatResponse("Hello! How can I help?", {
+ id: "resp-abc",
+ inputTokens: 10,
+ outputTokens: 8,
+ });
+
+ const response = await provider.chat([{ role: "user", content: "Hi" }]);
+
+ expect(response.content).toBe("Hello! How can I help?");
+ expect(response.usage.inputTokens).toBe(10);
+ expect(response.usage.outputTokens).toBe(8);
+ expect(response.id).toBe("resp-abc");
+ expect(response.stopReason).toBe("end_turn");
+ });
+
+ it("should use default model gpt-5.2-codex", async () => {
+ const provider = await initProvider();
+ mockSuccessfulChatResponse("Hi");
+
+ const response = await provider.chat([{ role: "user", content: "Hello" }]);
+
+ expect(response.model).toBe("gpt-5.2-codex");
+ });
+
+ it("should use model from options", async () => {
+ const provider = await initProvider();
+ mockSuccessfulChatResponse("Hi");
+
+ const response = await provider.chat([{ role: "user", content: "Hello" }], {
+ model: "gpt-5-codex",
+ });
+
+ expect(response.model).toBe("gpt-5-codex");
+
+ const fetchCall = mockFetch.mock.calls[0] as [string, RequestInit];
+ const body = JSON.parse(fetchCall[1].body as string);
+ expect(body.model).toBe("gpt-5-codex");
+ });
+
+ it("should extract system message as instructions", async () => {
+ const provider = await initProvider();
+ mockSuccessfulChatResponse("Hi");
+
+ await provider.chat([
+ { role: "system", content: "You are a coding assistant" },
+ { role: "user", content: "Hello" },
+ ]);
+
+ const fetchCall = mockFetch.mock.calls[0] as [string, RequestInit];
+ const body = JSON.parse(fetchCall[1].body as string);
+ expect(body.instructions).toBe("You are a coding assistant");
+ // System message should be filtered from input
+ expect(body.input).toHaveLength(1);
+ expect(body.input[0].role).toBe("user");
+ });
+
+ it("should use default instructions when no system message", async () => {
+ const provider = await initProvider();
+ mockSuccessfulChatResponse("Hi");
+
+ await provider.chat([{ role: "user", content: "Hello" }]);
+
+ const fetchCall = mockFetch.mock.calls[0] as [string, RequestInit];
+ const body = JSON.parse(fetchCall[1].body as string);
+ expect(body.instructions).toBe("You are a helpful coding assistant.");
+ });
+
+ it("should map system role to developer in input messages", async () => {
+ const provider = await initProvider();
+ mockSuccessfulChatResponse("Hi");
+
+ // Even though system is extracted as instructions, test the role mapping
+ // by checking remaining non-system messages
+ await provider.chat([
+ { role: "user", content: "Hello" },
+ { role: "assistant", content: "Hi there" },
+ ]);
+
+ const fetchCall = mockFetch.mock.calls[0] as [string, RequestInit];
+ const body = JSON.parse(fetchCall[1].body as string);
+ expect(body.input[0].role).toBe("user");
+ expect(body.input[0].content[0].type).toBe("input_text");
+ expect(body.input[1].role).toBe("assistant");
+ expect(body.input[1].content[0].type).toBe("output_text");
+ });
+
+ it("should handle array content in messages", async () => {
+ const provider = await initProvider();
+ mockSuccessfulChatResponse("Done");
+
+ await provider.chat([
+ {
+ role: "user",
+ content: [
+ { type: "text", text: "Hello" },
+ { type: "tool_result", tool_use_id: "call_1", content: "result data" },
+ ],
+ },
+ ]);
+
+ const fetchCall = mockFetch.mock.calls[0] as [string, RequestInit];
+ const body = JSON.parse(fetchCall[1].body as string);
+ // extractTextContent joins text parts
+ expect(body.input[0].content[0].text).toContain("Hello");
+ expect(body.input[0].content[0].text).toContain("Tool result:");
+ });
+
+ it("should handle response.output_text.done event (full text)", async () => {
+ const provider = await initProvider();
+
+ const events = [
+ { id: "resp-1", type: "response.created" },
+ { type: "response.output_text.delta", delta: "partial " },
+ { type: "response.output_text.done", text: "Complete response text" },
+ {
+ type: "response.completed",
+ response: {
+ id: "resp-1",
+ status: "completed",
+ usage: { input_tokens: 5, output_tokens: 10 },
+ },
+ },
+ ];
+
+ mockFetch.mockResolvedValue({
+ ok: true,
+ body: buildSSEStream(events),
+ });
+
+ const response = await provider.chat([{ role: "user", content: "Hello" }]);
+
+ // output_text.done replaces the accumulated delta content
+ expect(response.content).toBe("Complete response text");
+ });
+
+ it("should throw ProviderError on API error response", async () => {
+ const provider = await initProvider();
+
+ mockFetch.mockResolvedValue({
+ ok: false,
+ status: 429,
+ text: async () => "Rate limit exceeded",
+ });
+
+ await expect(provider.chat([{ role: "user", content: "Hello" }])).rejects.toThrow(
+ /Codex API error: 429/,
+ );
+ });
+
+ it("should throw ProviderError when response body is null", async () => {
+ const provider = await initProvider();
+
+ mockFetch.mockResolvedValue({
+ ok: true,
+ body: null,
+ });
+
+ await expect(provider.chat([{ role: "user", content: "Hello" }])).rejects.toThrow(
+ /No response body/,
+ );
+ });
+
+ it("should throw when no content is returned", async () => {
+ const provider = await initProvider();
+
+ // Stream with no text events
+ const events = [
+ { id: "resp-1", type: "response.created" },
+ {
+ type: "response.completed",
+ response: {
+ id: "resp-1",
+ status: "completed",
+ usage: { input_tokens: 5, output_tokens: 0 },
+ },
+ },
+ ];
+
+ mockFetch.mockResolvedValue({
+ ok: true,
+ body: buildSSEStream(events),
+ });
+
+ await expect(provider.chat([{ role: "user", content: "Hello" }])).rejects.toThrow(
+ /No response content/,
+ );
+ });
+
+ it("should map incomplete status to max_tokens stop reason", async () => {
+ const provider = await initProvider();
+
+ const events = [
+ { type: "response.output_text.delta", delta: "Truncated..." },
+ {
+ type: "response.completed",
+ response: {
+ status: "incomplete",
+ usage: { input_tokens: 100, output_tokens: 4096 },
+ },
+ },
+ ];
+
+ mockFetch.mockResolvedValue({
+ ok: true,
+ body: buildSSEStream(events),
+ });
+
+ const response = await provider.chat([{ role: "user", content: "Hello" }]);
+
+ expect(response.stopReason).toBe("max_tokens");
+ });
+
+ it("should handle invalid JSON in SSE lines gracefully", async () => {
+ const provider = await initProvider();
+
+ // Build a custom stream with some invalid JSON
+ const encoder = new TextEncoder();
+ const lines = [
+ "data: {invalid json}\n\n",
+ `data: ${JSON.stringify({ type: "response.output_text.delta", delta: "Hello" })}\n\n`,
+ `data: ${JSON.stringify({ type: "response.completed", response: { status: "completed", usage: { input_tokens: 1, output_tokens: 1 } } })}\n\n`,
+ "data: [DONE]\n\n",
+ ];
+
+ let index = 0;
+ const stream = new ReadableStream({
+ pull(controller) {
+ if (index < lines.length) {
+ controller.enqueue(encoder.encode(lines[index]));
+ index++;
+ } else {
+ controller.close();
+ }
+ },
+ });
+
+ mockFetch.mockResolvedValue({ ok: true, body: stream });
+
+ const response = await provider.chat([{ role: "user", content: "Hello" }]);
+ expect(response.content).toBe("Hello");
+ });
+
+ it("should send request to the correct Codex API endpoint", async () => {
+ const provider = await initProvider();
+ mockSuccessfulChatResponse("Hi");
+
+ await provider.chat([{ role: "user", content: "Hello" }]);
+
+ expect(mockFetch).toHaveBeenCalledWith(
+ "https://chatgpt.com/backend-api/codex/responses",
+ expect.any(Object),
+ );
+ });
+
+ it("should set stream: true and store: false in the request body", async () => {
+ const provider = await initProvider();
+ mockSuccessfulChatResponse("Hi");
+
+ await provider.chat([{ role: "user", content: "Hello" }]);
+
+ const fetchCall = mockFetch.mock.calls[0] as [string, RequestInit];
+ const body = JSON.parse(fetchCall[1].body as string);
+ expect(body.stream).toBe(true);
+ expect(body.store).toBe(false);
+ });
+ });
+
+ describe("chatWithTools", () => {
+ async function initProvider() {
+ const token = createFakeJwt({ chatgpt_account_id: "acct-test" });
+ mockGetValidAccessToken.mockResolvedValue({ accessToken: token });
+
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+ await provider.initialize({});
+ return provider;
+ }
+
+ it("should delegate to chat() and return empty toolCalls", async () => {
+ const provider = await initProvider();
+ mockSuccessfulChatResponse("I'll help with that", { inputTokens: 20, outputTokens: 15 });
+
+ const response = await provider.chatWithTools([{ role: "user", content: "Read test.txt" }], {
+ tools: [
+ {
+ name: "read_file",
+ description: "Read a file",
+ input_schema: { type: "object", properties: { path: { type: "string" } } },
+ },
+ ],
+ });
+
+ expect(response.content).toBe("I'll help with that");
+ expect(response.toolCalls).toEqual([]);
+ expect(response.usage.inputTokens).toBe(20);
+ expect(response.usage.outputTokens).toBe(15);
+ });
+ });
+
+ describe("stream", () => {
+ async function initProvider() {
+ const token = createFakeJwt({ chatgpt_account_id: "acct-test" });
+ mockGetValidAccessToken.mockResolvedValue({ accessToken: token });
+
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+ await provider.initialize({});
+ return provider;
+ }
+
+ it("should throw if not initialized", async () => {
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+
+ const iterator = provider.stream([{ role: "user", content: "Hello" }]);
+ // Calling next() triggers the generator which calls chat() which checks initialization
+ await expect(
+ (async () => {
+ for await (const _chunk of iterator) {
+ // consume
+ }
+ })(),
+ ).rejects.toThrow(/not initialized/i);
+ });
+
+ it("should yield text chunks and a done chunk", async () => {
+ const provider = await initProvider();
+ mockSuccessfulChatResponse("Hello World!");
+
+ const chunks: Array<{ type: string; text?: string }> = [];
+ for await (const chunk of provider.stream([{ role: "user", content: "Hi" }])) {
+ chunks.push(chunk);
+ }
+
+ // Should have text chunks plus a "done" chunk at the end
+ expect(chunks.length).toBeGreaterThan(1);
+ const textChunks = chunks.filter((c) => c.type === "text");
+ expect(textChunks.length).toBeGreaterThan(0);
+
+ // Last chunk should be "done"
+ expect(chunks[chunks.length - 1]?.type).toBe("done");
+
+ // All text combined should equal the original content
+ const combinedText = textChunks.map((c) => c.text).join("");
+ expect(combinedText).toBe("Hello World!");
+ });
+
+ it("should handle empty content response", async () => {
+ const provider = await initProvider();
+
+ // A response that results in an empty content will throw in chat()
+ const events = [
+ {
+ type: "response.completed",
+ response: { status: "completed", usage: { input_tokens: 1, output_tokens: 0 } },
+ },
+ ];
+
+ mockFetch.mockResolvedValue({
+ ok: true,
+ body: buildSSEStream(events),
+ });
+
+ await expect(
+ (async () => {
+ for await (const _chunk of provider.stream([{ role: "user", content: "Hi" }])) {
+ // consume
+ }
+ })(),
+ ).rejects.toThrow(/No response content/);
+ });
+ });
+
+ describe("streamWithTools", () => {
+ it("should delegate to stream()", async () => {
+ const token = createFakeJwt({ chatgpt_account_id: "acct-test" });
+ mockGetValidAccessToken.mockResolvedValue({ accessToken: token });
+
+ const { CodexProvider } = await import("./codex.js");
+ const provider = new CodexProvider();
+ await provider.initialize({});
+
+ mockSuccessfulChatResponse("Streaming with tools");
+
+ const chunks: Array<{ type: string; text?: string }> = [];
+ for await (const chunk of provider.streamWithTools([{ role: "user", content: "Hi" }], {
+ tools: [
+ { name: "test", description: "test", input_schema: { type: "object", properties: {} } },
+ ],
+ })) {
+ chunks.push(chunk);
+ }
+
+ expect(chunks.length).toBeGreaterThan(1);
+ expect(chunks[chunks.length - 1]?.type).toBe("done");
+ });
+ });
+});
+
+describe("createCodexProvider", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it("should create a provider instance", async () => {
+ const { createCodexProvider } = await import("./codex.js");
+
+ const provider = createCodexProvider();
+
+ expect(provider.id).toBe("codex");
+ expect(provider.name).toBe("OpenAI Codex (ChatGPT Plus/Pro)");
+ });
+
+ it("should call initialize when config is provided", async () => {
+ const token = createFakeJwt({});
+ mockGetValidAccessToken.mockResolvedValue({ accessToken: token });
+
+ const { createCodexProvider } = await import("./codex.js");
+
+ // Config triggers async init (fire-and-forget)
+ const provider = createCodexProvider({ apiKey: "test" });
+
+ expect(provider.id).toBe("codex");
+ });
+
+ it("should not throw when config init fails silently", async () => {
+ mockGetValidAccessToken.mockRejectedValue(new Error("Auth failed"));
+
+ const { createCodexProvider } = await import("./codex.js");
+
+ // Should not throw (error is caught internally)
+ const provider = createCodexProvider({ apiKey: "bad-key" });
+
+ expect(provider.id).toBe("codex");
+ });
+});
diff --git a/src/providers/codex.ts b/src/providers/codex.ts
new file mode 100644
index 0000000..f5ec145
--- /dev/null
+++ b/src/providers/codex.ts
@@ -0,0 +1,425 @@
+/**
+ * OpenAI Codex Provider for Corbat-Coco
+ *
+ * Uses ChatGPT Plus/Pro subscription via OAuth authentication.
+ * This provider connects to the Codex API endpoint (chatgpt.com/backend-api/codex)
+ * which is different from the standard OpenAI API (api.openai.com).
+ *
+ * Authentication:
+ * - Uses OAuth tokens obtained via browser-based PKCE flow
+ * - Tokens are stored in ~/.coco/tokens/openai.json
+ * - Supports automatic token refresh
+ */
+
+import type {
+ LLMProvider,
+ ProviderConfig,
+ Message,
+ ChatOptions,
+ ChatResponse,
+ ChatWithToolsOptions,
+ ChatWithToolsResponse,
+ StreamChunk,
+} from "./types.js";
+import { ProviderError } from "../utils/errors.js";
+import { getValidAccessToken } from "../auth/index.js";
+
+/**
+ * Codex API endpoint (ChatGPT backend)
+ */
+const CODEX_API_ENDPOINT = "https://chatgpt.com/backend-api/codex/responses";
+
+/**
+ * Default model for Codex (via ChatGPT Plus/Pro subscription)
+ * Note: ChatGPT subscription uses different models than the API
+ * Updated January 2026
+ */
+const DEFAULT_MODEL = "gpt-5.2-codex";
+
+/**
+ * Context windows for Codex models (ChatGPT Plus/Pro)
+ * These are the models available via the chatgpt.com/backend-api/codex endpoint
+ */
+const CONTEXT_WINDOWS: Record = {
+ "gpt-5-codex": 200000,
+ "gpt-5.2-codex": 200000,
+ "gpt-5.1-codex": 200000,
+ "gpt-5": 200000,
+ "gpt-5.2": 200000,
+ "gpt-5.1": 200000,
+};
+
+/**
+ * Parse JWT token to extract claims
+ */
+function parseJwtClaims(token: string): Record | undefined {
+ const parts = token.split(".");
+ if (parts.length !== 3 || !parts[1]) return undefined;
+ try {
+ return JSON.parse(Buffer.from(parts[1], "base64url").toString());
+ } catch {
+ return undefined;
+ }
+}
+
+/**
+ * Extract ChatGPT account ID from token claims
+ */
+function extractAccountId(accessToken: string): string | undefined {
+ const claims = parseJwtClaims(accessToken);
+ if (!claims) return undefined;
+
+ // Try different claim locations
+ const auth = claims["https://api.openai.com/auth"] as Record | undefined;
+ return (
+ (claims["chatgpt_account_id"] as string) ||
+ (auth?.["chatgpt_account_id"] as string) ||
+ (claims["organizations"] as Array<{ id: string }> | undefined)?.[0]?.id
+ );
+}
+
+/**
+ * Codex provider implementation
+ * Uses ChatGPT Plus/Pro subscription via OAuth
+ */
+export class CodexProvider implements LLMProvider {
+ readonly id = "codex";
+ readonly name = "OpenAI Codex (ChatGPT Plus/Pro)";
+
+ private config: ProviderConfig = {};
+ private accessToken: string | null = null;
+ private accountId: string | undefined;
+
+ /**
+ * Initialize the provider with OAuth tokens
+ */
+ async initialize(config: ProviderConfig): Promise {
+ this.config = config;
+
+ // Try to load OAuth tokens
+ const tokenResult = await getValidAccessToken("openai");
+ if (tokenResult) {
+ this.accessToken = tokenResult.accessToken;
+ this.accountId = extractAccountId(tokenResult.accessToken);
+ } else if (config.apiKey) {
+ // Fallback to provided API key (might be an OAuth token)
+ this.accessToken = config.apiKey;
+ this.accountId = extractAccountId(config.apiKey);
+ }
+
+ if (!this.accessToken) {
+ throw new ProviderError(
+ "No OAuth token found. Please run authentication first with: coco --provider openai",
+ { provider: this.id },
+ );
+ }
+ }
+
+ /**
+ * Ensure provider is initialized
+ */
+ private ensureInitialized(): void {
+ if (!this.accessToken) {
+ throw new ProviderError("Provider not initialized", {
+ provider: this.id,
+ });
+ }
+ }
+
+ /**
+ * Get context window size for a model
+ */
+ getContextWindow(model?: string): number {
+ const m = model ?? this.config.model ?? DEFAULT_MODEL;
+ return CONTEXT_WINDOWS[m] ?? 128000;
+ }
+
+ /**
+ * Count tokens in text (approximate)
+ * Uses GPT-4 approximation: ~4 chars per token
+ */
+ countTokens(text: string): number {
+ return Math.ceil(text.length / 4);
+ }
+
+ /**
+ * Check if provider is available (has valid OAuth tokens)
+ */
+ async isAvailable(): Promise {
+ try {
+ const tokenResult = await getValidAccessToken("openai");
+ return tokenResult !== null;
+ } catch {
+ return false;
+ }
+ }
+
+ /**
+ * Make a request to the Codex API
+ */
+ private async makeRequest(body: Record): Promise {
+ this.ensureInitialized();
+
+ const headers: Record = {
+ "Content-Type": "application/json",
+ Authorization: `Bearer ${this.accessToken}`,
+ };
+
+ // Add account ID if available (required for organization subscriptions)
+ if (this.accountId) {
+ headers["ChatGPT-Account-Id"] = this.accountId;
+ }
+
+ const response = await fetch(CODEX_API_ENDPOINT, {
+ method: "POST",
+ headers,
+ body: JSON.stringify(body),
+ });
+
+ if (!response.ok) {
+ const errorText = await response.text();
+ throw new ProviderError(`Codex API error: ${response.status} - ${errorText}`, {
+ provider: this.id,
+ statusCode: response.status,
+ });
+ }
+
+ return response;
+ }
+
+ /**
+ * Extract text content from a message
+ */
+ private extractTextContent(msg: Message): string {
+ if (typeof msg.content === "string") {
+ return msg.content;
+ }
+ if (Array.isArray(msg.content)) {
+ return msg.content
+ .map((part) => {
+ if (part.type === "text") return part.text;
+ if (part.type === "tool_result") return `Tool result: ${JSON.stringify(part.content)}`;
+ return "";
+ })
+ .join("\n");
+ }
+ return "";
+ }
+
+ /**
+ * Convert messages to Codex Responses API format
+ * Codex uses a different format than Chat Completions:
+ * {
+ * "input": [
+ * { "type": "message", "role": "developer|user", "content": [{ "type": "input_text", "text": "..." }] },
+ * { "type": "message", "role": "assistant", "content": [{ "type": "output_text", "text": "..." }] }
+ * ]
+ * }
+ *
+ * IMPORTANT: User/developer messages use "input_text", assistant messages use "output_text"
+ */
+ private convertMessagesToResponsesFormat(messages: Message[]): Array<{
+ type: string;
+ role: string;
+ content: Array<{ type: string; text: string }>;
+ }> {
+ return messages.map((msg) => {
+ const text = this.extractTextContent(msg);
+ // Map roles: system -> developer, assistant -> assistant, user -> user
+ const role = msg.role === "system" ? "developer" : msg.role;
+ // Assistant messages use "output_text", all others use "input_text"
+ const contentType = msg.role === "assistant" ? "output_text" : "input_text";
+ return {
+ type: "message",
+ role,
+ content: [{ type: contentType, text }],
+ };
+ });
+ }
+
+ /**
+ * Send a chat message using Codex Responses API format
+ */
+ async chat(messages: Message[], options?: ChatOptions): Promise {
+ const model = options?.model ?? this.config.model ?? DEFAULT_MODEL;
+
+ // Extract system message for instructions (if any)
+ const systemMsg = messages.find((m) => m.role === "system");
+ const instructions = systemMsg
+ ? this.extractTextContent(systemMsg)
+ : "You are a helpful coding assistant.";
+
+ // Convert remaining messages to Responses API format
+ const inputMessages = messages
+ .filter((m) => m.role !== "system")
+ .map((msg) => this.convertMessagesToResponsesFormat([msg])[0]);
+
+ const body = {
+ model,
+ instructions,
+ input: inputMessages,
+ tools: [],
+ store: false,
+ stream: true, // Codex API requires streaming
+ };
+
+ const response = await this.makeRequest(body);
+
+ if (!response.body) {
+ throw new ProviderError("No response body from Codex API", {
+ provider: this.id,
+ });
+ }
+
+ // Read streaming response (SSE format)
+ const reader = response.body.getReader();
+ const decoder = new TextDecoder();
+ let buffer = "";
+ let content = "";
+ let responseId = `codex-${Date.now()}`;
+ let inputTokens = 0;
+ let outputTokens = 0;
+ let status = "completed";
+
+ try {
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done) break;
+
+ buffer += decoder.decode(value, { stream: true });
+ const lines = buffer.split("\n");
+ buffer = lines.pop() ?? "";
+
+ for (const line of lines) {
+ if (line.startsWith("data: ")) {
+ const data = line.slice(6).trim();
+ if (!data || data === "[DONE]") continue;
+
+ try {
+ const parsed = JSON.parse(data);
+
+ // Extract response ID
+ if (parsed.id) {
+ responseId = parsed.id;
+ }
+
+ // Handle different event types
+ if (parsed.type === "response.output_text.delta" && parsed.delta) {
+ content += parsed.delta;
+ } else if (parsed.type === "response.completed" && parsed.response) {
+ // Final response with usage info
+ if (parsed.response.usage) {
+ inputTokens = parsed.response.usage.input_tokens ?? 0;
+ outputTokens = parsed.response.usage.output_tokens ?? 0;
+ }
+ status = parsed.response.status ?? "completed";
+ } else if (parsed.type === "response.output_text.done" && parsed.text) {
+ // Full text output
+ content = parsed.text;
+ }
+ } catch {
+ // Invalid JSON, skip
+ }
+ }
+ }
+ }
+ } finally {
+ reader.releaseLock();
+ }
+
+ if (!content) {
+ throw new ProviderError("No response content from Codex API", {
+ provider: this.id,
+ });
+ }
+
+ const stopReason =
+ status === "completed"
+ ? ("end_turn" as const)
+ : status === "incomplete"
+ ? ("max_tokens" as const)
+ : ("end_turn" as const);
+
+ return {
+ id: responseId,
+ content,
+ stopReason,
+ model,
+ usage: {
+ inputTokens,
+ outputTokens,
+ },
+ };
+ }
+
+ /**
+ * Send a chat message with tool use
+ * Note: Codex Responses API tool support is complex; for now we delegate to chat()
+ * and return empty toolCalls. Full tool support can be added later.
+ */
+ async chatWithTools(
+ messages: Message[],
+ options: ChatWithToolsOptions,
+ ): Promise {
+ // For now, use basic chat without tools
+ const response = await this.chat(messages, options);
+
+ return {
+ ...response,
+ toolCalls: [], // Tools not yet supported in Codex provider
+ };
+ }
+
+ /**
+ * Stream a chat response
+ * Note: True streaming with Codex Responses API is complex.
+ * For now, we make a non-streaming call and simulate streaming by emitting chunks.
+ */
+ async *stream(messages: Message[], options?: ChatOptions): AsyncIterable {
+ // Make a regular chat call and emit the result
+ const response = await this.chat(messages, options);
+
+ // Simulate streaming by emitting content in small chunks
+ // This provides better visual feedback than emitting all at once
+ if (response.content) {
+ const content = response.content;
+ const chunkSize = 20; // Characters per chunk for smooth display
+
+ for (let i = 0; i < content.length; i += chunkSize) {
+ const chunk = content.slice(i, i + chunkSize);
+ yield { type: "text" as const, text: chunk };
+
+ // Small delay to simulate streaming (only if there's more content)
+ if (i + chunkSize < content.length) {
+ await new Promise((resolve) => setTimeout(resolve, 5));
+ }
+ }
+ }
+
+ yield { type: "done" as const };
+ }
+
+ /**
+ * Stream a chat response with tool use
+ * Note: Tools and true streaming with Codex Responses API are not yet implemented.
+ * For now, we delegate to stream() which uses non-streaming under the hood.
+ */
+ async *streamWithTools(
+ messages: Message[],
+ options: ChatWithToolsOptions,
+ ): AsyncIterable {
+ // Use the basic stream method (tools not supported yet)
+ yield* this.stream(messages, options);
+ }
+}
+
+/**
+ * Create a Codex provider
+ */
+export function createCodexProvider(config?: ProviderConfig): CodexProvider {
+ const provider = new CodexProvider();
+ if (config) {
+ provider.initialize(config).catch(() => {});
+ }
+ return provider;
+}
diff --git a/src/providers/fallback.test.ts b/src/providers/fallback.test.ts
new file mode 100644
index 0000000..9d744cc
--- /dev/null
+++ b/src/providers/fallback.test.ts
@@ -0,0 +1,642 @@
+/**
+ * Tests for Provider Fallback with circuit breaker protection
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type {
+ LLMProvider,
+ Message,
+ ChatOptions,
+ ChatResponse,
+ ChatWithToolsOptions,
+ ChatWithToolsResponse,
+ StreamChunk,
+} from "./types.js";
+import { ProviderFallback, createProviderFallback } from "./fallback.js";
+import { ProviderError } from "../utils/errors.js";
+
+/**
+ * Helper: create a mock LLM provider with configurable behavior
+ */
+function createMockProvider(id: string, overrides?: Partial): LLMProvider {
+ return {
+ id,
+ name: `Mock ${id}`,
+ initialize: vi.fn().mockResolvedValue(undefined),
+ chat: vi.fn().mockResolvedValue({
+ id: `resp-${id}`,
+ content: `Response from ${id}`,
+ stopReason: "end_turn",
+ model: "test-model",
+ usage: { inputTokens: 10, outputTokens: 5 },
+ } satisfies ChatResponse),
+ chatWithTools: vi.fn().mockResolvedValue({
+ id: `resp-${id}`,
+ content: `Response from ${id}`,
+ stopReason: "end_turn",
+ model: "test-model",
+ usage: { inputTokens: 10, outputTokens: 5 },
+ toolCalls: [],
+ } satisfies ChatWithToolsResponse),
+ stream: vi.fn().mockImplementation(async function* () {
+ yield { type: "text" as const, text: `Stream from ${id}` };
+ yield { type: "done" as const };
+ }),
+ streamWithTools: vi.fn().mockImplementation(async function* () {
+ yield { type: "text" as const, text: `Stream with tools from ${id}` };
+ yield { type: "done" as const };
+ }),
+ countTokens: vi.fn().mockReturnValue(10),
+ getContextWindow: vi.fn().mockReturnValue(128000),
+ isAvailable: vi.fn().mockResolvedValue(true),
+ ...overrides,
+ };
+}
+
+const sampleMessages: Message[] = [{ role: "user", content: "Hello" }];
+
+const sampleToolOptions: ChatWithToolsOptions = {
+ tools: [
+ {
+ name: "read_file",
+ description: "Read a file",
+ input_schema: { type: "object", properties: { path: { type: "string" } } },
+ },
+ ],
+};
+
+describe("ProviderFallback", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ });
+
+ describe("constructor", () => {
+ it("should create with a single provider", () => {
+ const provider = createMockProvider("primary");
+ const fallback = new ProviderFallback([provider]);
+
+ expect(fallback.id).toBe("fallback");
+ expect(fallback.name).toBe("Provider Fallback");
+ });
+
+ it("should create with multiple providers", () => {
+ const primary = createMockProvider("primary");
+ const secondary = createMockProvider("secondary");
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ expect(fallback.id).toBe("fallback");
+ });
+
+ it("should throw if no providers given", () => {
+ expect(() => new ProviderFallback([])).toThrow(/At least one provider/);
+ });
+
+ it("should accept optional circuit breaker config", () => {
+ const provider = createMockProvider("primary");
+ const fallback = new ProviderFallback([provider], {
+ circuitBreaker: { failureThreshold: 3, resetTimeout: 10000 },
+ });
+
+ expect(fallback.id).toBe("fallback");
+ });
+ });
+
+ describe("initialize", () => {
+ it("should initialize all providers", async () => {
+ const primary = createMockProvider("primary");
+ const secondary = createMockProvider("secondary");
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ await fallback.initialize({ apiKey: "test" });
+
+ expect(primary.initialize).toHaveBeenCalledWith({ apiKey: "test" });
+ expect(secondary.initialize).toHaveBeenCalledWith({ apiKey: "test" });
+ });
+
+ it("should succeed if at least one provider initializes", async () => {
+ const primary = createMockProvider("primary", {
+ initialize: vi.fn().mockRejectedValue(new Error("Primary init failed")),
+ });
+ const secondary = createMockProvider("secondary");
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ // Should not throw
+ await fallback.initialize({ apiKey: "test" });
+ });
+
+ it("should throw if all providers fail to initialize", async () => {
+ const primary = createMockProvider("primary", {
+ initialize: vi.fn().mockRejectedValue(new Error("Primary failed")),
+ });
+ const secondary = createMockProvider("secondary", {
+ initialize: vi.fn().mockRejectedValue(new Error("Secondary failed")),
+ });
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ await expect(fallback.initialize({ apiKey: "test" })).rejects.toThrow(
+ /All providers failed to initialize/,
+ );
+ });
+ });
+
+ describe("chat", () => {
+ it("should use the primary provider when available", async () => {
+ const primary = createMockProvider("primary");
+ const secondary = createMockProvider("secondary");
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ const response = await fallback.chat(sampleMessages);
+
+ expect(response.content).toBe("Response from primary");
+ expect(primary.chat).toHaveBeenCalledWith(sampleMessages, undefined);
+ expect(secondary.chat).not.toHaveBeenCalled();
+ });
+
+ it("should fallback to secondary when primary fails", async () => {
+ const primary = createMockProvider("primary", {
+ chat: vi.fn().mockRejectedValue(new Error("Primary down")),
+ });
+ const secondary = createMockProvider("secondary");
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ const response = await fallback.chat(sampleMessages);
+
+ expect(response.content).toBe("Response from secondary");
+ });
+
+ it("should pass options through to provider", async () => {
+ const primary = createMockProvider("primary");
+ const fallback = new ProviderFallback([primary]);
+
+ const options: ChatOptions = { model: "gpt-5", temperature: 0.5 };
+ await fallback.chat(sampleMessages, options);
+
+ expect(primary.chat).toHaveBeenCalledWith(sampleMessages, options);
+ });
+
+ it("should throw when all providers fail", async () => {
+ const primary = createMockProvider("primary", {
+ chat: vi.fn().mockRejectedValue(new Error("Primary down")),
+ });
+ const secondary = createMockProvider("secondary", {
+ chat: vi.fn().mockRejectedValue(new Error("Secondary down")),
+ });
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ await expect(fallback.chat(sampleMessages)).rejects.toThrow(/All providers failed/);
+ });
+
+ it("should include provider names in the all-failed error message", async () => {
+ const primary = createMockProvider("primary", {
+ chat: vi.fn().mockRejectedValue(new Error("Primary timeout")),
+ });
+ const secondary = createMockProvider("secondary", {
+ chat: vi.fn().mockRejectedValue(new Error("Secondary rate limited")),
+ });
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ await expect(fallback.chat(sampleMessages)).rejects.toThrow(/primary.*Primary timeout/);
+ });
+
+ it("should handle three providers in chain", async () => {
+ const first = createMockProvider("first", {
+ chat: vi.fn().mockRejectedValue(new Error("First down")),
+ });
+ const second = createMockProvider("second", {
+ chat: vi.fn().mockRejectedValue(new Error("Second down")),
+ });
+ const third = createMockProvider("third");
+ const fallback = new ProviderFallback([first, second, third]);
+
+ const response = await fallback.chat(sampleMessages);
+
+ expect(response.content).toBe("Response from third");
+ });
+ });
+
+ describe("chatWithTools", () => {
+ it("should use the primary provider for tool calls", async () => {
+ const toolResponse: ChatWithToolsResponse = {
+ id: "resp-tool",
+ content: "",
+ stopReason: "tool_use",
+ model: "test",
+ usage: { inputTokens: 20, outputTokens: 10 },
+ toolCalls: [{ id: "call_1", name: "read_file", input: { path: "/test.txt" } }],
+ };
+ const primary = createMockProvider("primary", {
+ chatWithTools: vi.fn().mockResolvedValue(toolResponse),
+ });
+ const fallback = new ProviderFallback([primary]);
+
+ const response = await fallback.chatWithTools(sampleMessages, sampleToolOptions);
+
+ expect(response.toolCalls).toHaveLength(1);
+ expect(response.toolCalls[0]?.name).toBe("read_file");
+ });
+
+ it("should fallback when primary fails with tools", async () => {
+ const primary = createMockProvider("primary", {
+ chatWithTools: vi.fn().mockRejectedValue(new Error("Tool failure")),
+ });
+ const secondary = createMockProvider("secondary");
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ const response = await fallback.chatWithTools(sampleMessages, sampleToolOptions);
+
+ expect(response.content).toBe("Response from secondary");
+ });
+
+ it("should throw when all providers fail with tools", async () => {
+ const primary = createMockProvider("primary", {
+ chatWithTools: vi.fn().mockRejectedValue(new Error("fail")),
+ });
+ const secondary = createMockProvider("secondary", {
+ chatWithTools: vi.fn().mockRejectedValue(new Error("fail")),
+ });
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ await expect(fallback.chatWithTools(sampleMessages, sampleToolOptions)).rejects.toThrow(
+ /All providers failed/,
+ );
+ });
+ });
+
+ describe("stream", () => {
+ it("should stream from primary provider", async () => {
+ const primary = createMockProvider("primary");
+ const fallback = new ProviderFallback([primary]);
+
+ const chunks: StreamChunk[] = [];
+ for await (const chunk of fallback.stream(sampleMessages)) {
+ chunks.push(chunk);
+ }
+
+ expect(chunks).toHaveLength(2);
+ expect(chunks[0]?.type).toBe("text");
+ expect(chunks[0]?.text).toBe("Stream from primary");
+ expect(chunks[1]?.type).toBe("done");
+ });
+
+ it("should fallback to secondary when primary stream fails", async () => {
+ const primary = createMockProvider("primary", {
+ stream: // eslint-disable-next-line require-yield
+ vi.fn().mockImplementation(async function* () {
+ throw new Error("Stream failure");
+ }),
+ });
+ const secondary = createMockProvider("secondary");
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ const chunks: StreamChunk[] = [];
+ for await (const chunk of fallback.stream(sampleMessages)) {
+ chunks.push(chunk);
+ }
+
+ expect(chunks).toHaveLength(2);
+ expect(chunks[0]?.text).toBe("Stream from secondary");
+ });
+
+ it("should throw when all providers fail streaming", async () => {
+ const primary = createMockProvider("primary", {
+ stream: // eslint-disable-next-line require-yield
+ vi.fn().mockImplementation(async function* () {
+ throw new Error("fail");
+ }),
+ });
+ const secondary = createMockProvider("secondary", {
+ stream: // eslint-disable-next-line require-yield
+ vi.fn().mockImplementation(async function* () {
+ throw new Error("fail");
+ }),
+ });
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ await expect(
+ (async () => {
+ for await (const _chunk of fallback.stream(sampleMessages)) {
+ // consume
+ }
+ })(),
+ ).rejects.toThrow(/All providers failed for streaming/);
+ });
+
+ it("should pass options to stream", async () => {
+ const primary = createMockProvider("primary");
+ const fallback = new ProviderFallback([primary]);
+
+ const options: ChatOptions = { temperature: 0.7 };
+ for await (const _chunk of fallback.stream(sampleMessages, options)) {
+ // consume
+ }
+
+ expect(primary.stream).toHaveBeenCalledWith(sampleMessages, options);
+ });
+ });
+
+ describe("streamWithTools", () => {
+ it("should stream with tools from primary provider", async () => {
+ const primary = createMockProvider("primary");
+ const fallback = new ProviderFallback([primary]);
+
+ const chunks: StreamChunk[] = [];
+ for await (const chunk of fallback.streamWithTools(sampleMessages, sampleToolOptions)) {
+ chunks.push(chunk);
+ }
+
+ expect(chunks).toHaveLength(2);
+ expect(chunks[0]?.text).toBe("Stream with tools from primary");
+ });
+
+ it("should fallback when primary streamWithTools fails", async () => {
+ const primary = createMockProvider("primary", {
+ streamWithTools: // eslint-disable-next-line require-yield
+ vi.fn().mockImplementation(async function* () {
+ throw new Error("fail");
+ }),
+ });
+ const secondary = createMockProvider("secondary");
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ const chunks: StreamChunk[] = [];
+ for await (const chunk of fallback.streamWithTools(sampleMessages, sampleToolOptions)) {
+ chunks.push(chunk);
+ }
+
+ expect(chunks[0]?.text).toBe("Stream with tools from secondary");
+ });
+
+ it("should throw when all providers fail streamWithTools", async () => {
+ const primary = createMockProvider("primary", {
+ streamWithTools: // eslint-disable-next-line require-yield
+ vi.fn().mockImplementation(async function* () {
+ throw new Error("fail");
+ }),
+ });
+ const secondary = createMockProvider("secondary", {
+ streamWithTools: // eslint-disable-next-line require-yield
+ vi.fn().mockImplementation(async function* () {
+ throw new Error("fail");
+ }),
+ });
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ await expect(
+ (async () => {
+ for await (const _chunk of fallback.streamWithTools(sampleMessages, sampleToolOptions)) {
+ // consume
+ }
+ })(),
+ ).rejects.toThrow(/All providers failed for streaming with tools/);
+ });
+ });
+
+ describe("countTokens", () => {
+ it("should delegate to current provider", () => {
+ const primary = createMockProvider("primary", {
+ countTokens: vi.fn().mockReturnValue(42),
+ });
+ const fallback = new ProviderFallback([primary]);
+
+ expect(fallback.countTokens("test text")).toBe(42);
+ expect(primary.countTokens).toHaveBeenCalledWith("test text");
+ });
+ });
+
+ describe("getContextWindow", () => {
+ it("should delegate to current provider", () => {
+ const primary = createMockProvider("primary", {
+ getContextWindow: vi.fn().mockReturnValue(200000),
+ });
+ const fallback = new ProviderFallback([primary]);
+
+ expect(fallback.getContextWindow()).toBe(200000);
+ });
+ });
+
+ describe("isAvailable", () => {
+ it("should return true if any provider is available", async () => {
+ const primary = createMockProvider("primary", {
+ isAvailable: vi.fn().mockResolvedValue(false),
+ });
+ const secondary = createMockProvider("secondary", {
+ isAvailable: vi.fn().mockResolvedValue(true),
+ });
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ expect(await fallback.isAvailable()).toBe(true);
+ });
+
+ it("should return false if all providers are unavailable", async () => {
+ const primary = createMockProvider("primary", {
+ isAvailable: vi.fn().mockResolvedValue(false),
+ });
+ const secondary = createMockProvider("secondary", {
+ isAvailable: vi.fn().mockResolvedValue(false),
+ });
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ expect(await fallback.isAvailable()).toBe(false);
+ });
+
+ it("should return false for provider with open circuit breaker", async () => {
+ // Need to trip the circuit breaker by causing enough failures
+ const primary = createMockProvider("primary", {
+ chat: vi.fn().mockRejectedValue(new Error("fail")),
+ isAvailable: vi.fn().mockResolvedValue(true),
+ });
+ const fallback = new ProviderFallback([primary], {
+ circuitBreaker: { failureThreshold: 2, resetTimeout: 60000, halfOpenRequests: 1 },
+ });
+
+ // Cause failures to open the circuit breaker
+ try {
+ await fallback.chat(sampleMessages);
+ } catch {
+ /* expected */
+ }
+ try {
+ await fallback.chat(sampleMessages);
+ } catch {
+ /* expected */
+ }
+
+ // Circuit should now be open (2 failures >= threshold 2)
+ // isAvailable should return false because circuit is open
+ expect(await fallback.isAvailable()).toBe(false);
+ });
+ });
+
+ describe("circuit breaker integration", () => {
+ it("should open circuit after threshold failures", async () => {
+ const primary = createMockProvider("primary", {
+ chat: vi.fn().mockRejectedValue(new Error("Server error")),
+ });
+ const secondary = createMockProvider("secondary");
+ const fallback = new ProviderFallback([primary, secondary], {
+ circuitBreaker: { failureThreshold: 2, resetTimeout: 60000, halfOpenRequests: 1 },
+ });
+
+ // First two calls fail on primary, fall back to secondary
+ await fallback.chat(sampleMessages);
+ await fallback.chat(sampleMessages);
+
+ // After threshold, primary circuit is open
+ const status = fallback.getCircuitStatus();
+ const primaryStatus = status.find((s) => s.providerId === "primary");
+ expect(primaryStatus?.failureCount).toBeGreaterThanOrEqual(2);
+ });
+
+ it("should skip provider with open circuit", async () => {
+ const primary = createMockProvider("primary", {
+ chat: vi.fn().mockRejectedValue(new Error("fail")),
+ });
+ const secondary = createMockProvider("secondary");
+ const fallback = new ProviderFallback([primary, secondary], {
+ circuitBreaker: { failureThreshold: 2, resetTimeout: 60000, halfOpenRequests: 1 },
+ });
+
+ // Trip the breaker on primary
+ await fallback.chat(sampleMessages); // fails primary, succeeds secondary
+ await fallback.chat(sampleMessages); // fails primary, succeeds secondary
+
+ // Now the circuit is open for primary
+ // Third call should go directly to secondary (primary circuit open)
+ vi.mocked(secondary.chat).mockClear();
+ await fallback.chat(sampleMessages);
+
+ // Secondary was called
+ expect(secondary.chat).toHaveBeenCalled();
+ });
+
+ it("should report circuit status for all providers", () => {
+ const primary = createMockProvider("primary");
+ const secondary = createMockProvider("secondary");
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ const status = fallback.getCircuitStatus();
+
+ expect(status).toHaveLength(2);
+ expect(status[0]?.providerId).toBe("primary");
+ expect(status[0]?.state).toBe("closed");
+ expect(status[0]?.failureCount).toBe(0);
+ expect(status[1]?.providerId).toBe("secondary");
+ });
+
+ it("should reset all circuit breakers", async () => {
+ const primary = createMockProvider("primary", {
+ chat: vi.fn().mockRejectedValue(new Error("fail")),
+ });
+ const secondary = createMockProvider("secondary");
+ const fallback = new ProviderFallback([primary, secondary], {
+ circuitBreaker: { failureThreshold: 2, resetTimeout: 60000, halfOpenRequests: 1 },
+ });
+
+ // Trip the primary circuit
+ await fallback.chat(sampleMessages);
+ await fallback.chat(sampleMessages);
+
+ // Reset circuits
+ fallback.resetCircuits();
+
+ const status = fallback.getCircuitStatus();
+ const primaryStatus = status.find((s) => s.providerId === "primary");
+ expect(primaryStatus?.state).toBe("closed");
+ expect(primaryStatus?.failureCount).toBe(0);
+ });
+ });
+
+ describe("getCurrentProvider", () => {
+ it("should return the first provider", () => {
+ const primary = createMockProvider("primary");
+ const secondary = createMockProvider("secondary");
+ const fallback = new ProviderFallback([primary, secondary]);
+
+ const current = fallback.getCurrentProvider();
+
+ expect(current.provider.id).toBe("primary");
+ });
+ });
+
+ describe("error propagation", () => {
+ it("should throw ProviderError with retryable=false when all fail", async () => {
+ const primary = createMockProvider("primary", {
+ chat: vi.fn().mockRejectedValue(new Error("fail")),
+ });
+ const fallback = new ProviderFallback([primary], {
+ circuitBreaker: { failureThreshold: 100, resetTimeout: 60000, halfOpenRequests: 1 },
+ });
+
+ try {
+ await fallback.chat(sampleMessages);
+ expect.fail("Should have thrown");
+ } catch (error) {
+ expect(error).toBeInstanceOf(ProviderError);
+ expect((error as ProviderError).provider).toBe("fallback");
+ }
+ });
+
+ it("should include all provider errors in the message", async () => {
+ const primary = createMockProvider("primary", {
+ chat: vi.fn().mockRejectedValue(new Error("Auth failed")),
+ });
+ const secondary = createMockProvider("secondary", {
+ chat: vi.fn().mockRejectedValue(new Error("Rate limited")),
+ });
+ const fallback = new ProviderFallback([primary, secondary], {
+ circuitBreaker: { failureThreshold: 100, resetTimeout: 60000, halfOpenRequests: 1 },
+ });
+
+ try {
+ await fallback.chat(sampleMessages);
+ expect.fail("Should have thrown");
+ } catch (error) {
+ const msg = (error as Error).message;
+ expect(msg).toContain("primary");
+ expect(msg).toContain("Auth failed");
+ expect(msg).toContain("secondary");
+ expect(msg).toContain("Rate limited");
+ }
+ });
+
+ it("should handle non-Error thrown values in error messages", async () => {
+ const primary = createMockProvider("primary", {
+ chat: vi.fn().mockRejectedValue("string error"),
+ });
+ const fallback = new ProviderFallback([primary], {
+ circuitBreaker: { failureThreshold: 100, resetTimeout: 60000, halfOpenRequests: 1 },
+ });
+
+ try {
+ await fallback.chat(sampleMessages);
+ expect.fail("Should have thrown");
+ } catch (error) {
+ const msg = (error as Error).message;
+ expect(msg).toContain("string error");
+ }
+ });
+ });
+});
+
+describe("createProviderFallback", () => {
+ it("should create a ProviderFallback instance", () => {
+ const primary = createMockProvider("primary");
+ const fallback = createProviderFallback([primary]);
+
+ expect(fallback).toBeInstanceOf(ProviderFallback);
+ expect(fallback.id).toBe("fallback");
+ });
+
+ it("should pass config to the ProviderFallback", () => {
+ const primary = createMockProvider("primary");
+ const fallback = createProviderFallback([primary], {
+ circuitBreaker: { failureThreshold: 10 },
+ });
+
+ expect(fallback).toBeInstanceOf(ProviderFallback);
+ });
+
+ it("should throw for empty provider array", () => {
+ expect(() => createProviderFallback([])).toThrow(/At least one provider/);
+ });
+});
diff --git a/src/providers/fallback.ts b/src/providers/fallback.ts
index 5b5ac97..0c74395 100644
--- a/src/providers/fallback.ts
+++ b/src/providers/fallback.ts
@@ -167,7 +167,7 @@ export class ProviderFallback implements LLMProvider {
}
breaker.recordSuccess();
return;
- } catch (error) {
+ } catch {
breaker.recordFailure();
// Continue to next provider
}
@@ -199,7 +199,7 @@ export class ProviderFallback implements LLMProvider {
}
breaker.recordSuccess();
return;
- } catch (error) {
+ } catch {
breaker.recordFailure();
// Continue to next provider
}
diff --git a/src/providers/gemini.test.ts b/src/providers/gemini.test.ts
index e38bb45..d6b34e2 100644
--- a/src/providers/gemini.test.ts
+++ b/src/providers/gemini.test.ts
@@ -113,7 +113,7 @@ describe("GeminiProvider", () => {
const provider = new GeminiProvider();
await provider.initialize({ apiKey: "test", model: "gemini-2.0-flash" });
- expect(provider.getContextWindow()).toBe(1000000);
+ expect(provider.getContextWindow()).toBe(1048576);
});
it("should return context window for gemini-1.5-pro", async () => {
diff --git a/src/providers/gemini.ts b/src/providers/gemini.ts
index ad489d1..f7299fc 100644
--- a/src/providers/gemini.ts
+++ b/src/providers/gemini.ts
@@ -1,5 +1,10 @@
/**
* Google Gemini provider for Corbat-Coco
+ *
+ * Supports multiple authentication methods:
+ * 1. GEMINI_API_KEY environment variable (recommended)
+ * 2. GOOGLE_API_KEY environment variable
+ * 3. Google Cloud ADC (gcloud auth application-default login)
*/
import {
@@ -26,17 +31,29 @@ import type {
ToolResultContent,
} from "./types.js";
import { ProviderError } from "../utils/errors.js";
+import { getCachedADCToken } from "../auth/gcloud.js";
/**
- * Default model
+ * Default model - Updated February 2026
*/
-const DEFAULT_MODEL = "gemini-2.0-flash";
+const DEFAULT_MODEL = "gemini-3-flash-preview";
/**
* Context windows for models
+ * Updated February 2026 - Gemini 3 uses -preview suffix
*/
const CONTEXT_WINDOWS: Record = {
- "gemini-2.0-flash": 1000000,
+ // Gemini 3 series (latest, Jan 2026 - use -preview suffix)
+ "gemini-3-flash-preview": 1000000,
+ "gemini-3-pro-preview": 1000000,
+ // Gemini 2.5 series (production stable)
+ "gemini-2.5-pro-preview-05-06": 1048576,
+ "gemini-2.5-flash-preview-05-20": 1048576,
+ "gemini-2.5-pro": 1048576,
+ "gemini-2.5-flash": 1048576,
+ // Gemini 2.0 series (GA stable)
+ "gemini-2.0-flash": 1048576,
+ // Legacy
"gemini-1.5-flash": 1000000,
"gemini-1.5-pro": 2000000,
"gemini-1.0-pro": 32000,
@@ -54,25 +71,71 @@ export class GeminiProvider implements LLMProvider {
/**
* Initialize the provider
+ *
+ * Authentication priority:
+ * 1. API key passed in config (unless it's the ADC marker)
+ * 2. GEMINI_API_KEY environment variable
+ * 3. GOOGLE_API_KEY environment variable
+ * 4. Google Cloud ADC (gcloud auth application-default login)
*/
async initialize(config: ProviderConfig): Promise {
this.config = config;
- const apiKey = config.apiKey ?? process.env["GEMINI_API_KEY"] ?? process.env["GOOGLE_API_KEY"];
+ // Check for ADC marker (set by onboarding when user chooses gcloud ADC)
+ const isADCMarker = config.apiKey === "__gcloud_adc__";
+
+ // Try explicit API keys first (unless it's the ADC marker)
+ let apiKey =
+ !isADCMarker && config.apiKey
+ ? config.apiKey
+ : (process.env["GEMINI_API_KEY"] ?? process.env["GOOGLE_API_KEY"]);
+
+ // If no API key or ADC marker is set, try gcloud ADC
+ if (!apiKey || isADCMarker) {
+ try {
+ const adcToken = await getCachedADCToken();
+ if (adcToken) {
+ apiKey = adcToken.accessToken;
+ // Store that we're using ADC for refresh later
+ this.config.useADC = true;
+ }
+ } catch {
+ // ADC not available, continue without it
+ }
+ }
+
if (!apiKey) {
- throw new ProviderError("Gemini API key not provided", {
- provider: this.id,
- });
+ throw new ProviderError(
+ "Gemini API key not provided. Set GEMINI_API_KEY or run: gcloud auth application-default login",
+ { provider: this.id },
+ );
}
this.client = new GoogleGenerativeAI(apiKey);
}
+ /**
+ * Refresh ADC token if needed and reinitialize client
+ */
+ private async refreshADCIfNeeded(): Promise {
+ if (!this.config.useADC) return;
+
+ try {
+ const adcToken = await getCachedADCToken();
+ if (adcToken) {
+ this.client = new GoogleGenerativeAI(adcToken.accessToken);
+ }
+ } catch {
+ // Token refresh failed, continue with existing client
+ }
+ }
+
/**
* Send a chat message
*/
async chat(messages: Message[], options?: ChatOptions): Promise {
this.ensureInitialized();
+ await this.refreshADCIfNeeded();
try {
const model = this.client!.getGenerativeModel({
@@ -104,6 +167,7 @@ export class GeminiProvider implements LLMProvider {
options: ChatWithToolsOptions,
): Promise {
this.ensureInitialized();
+ await this.refreshADCIfNeeded();
try {
const tools: Tool[] = [
@@ -143,6 +207,7 @@ export class GeminiProvider implements LLMProvider {
*/
async *stream(messages: Message[], options?: ChatOptions): AsyncIterable {
this.ensureInitialized();
+ await this.refreshADCIfNeeded();
try {
const model = this.client!.getGenerativeModel({
@@ -180,6 +245,7 @@ export class GeminiProvider implements LLMProvider {
options: ChatWithToolsOptions,
): AsyncIterable {
this.ensureInitialized();
+ await this.refreshADCIfNeeded();
try {
const tools: Tool[] = [
diff --git a/src/providers/index.test.ts b/src/providers/index.test.ts
index 730c89a..2041df4 100644
--- a/src/providers/index.test.ts
+++ b/src/providers/index.test.ts
@@ -201,16 +201,29 @@ describe("Providers module exports", () => {
it("should return list of providers", () => {
const providers = ProviderExports.listProviders();
- expect(providers).toHaveLength(4);
- expect(providers.map((p) => p.id)).toEqual(["anthropic", "openai", "gemini", "kimi"]);
+ expect(providers).toHaveLength(5);
+ expect(providers.map((p) => p.id)).toEqual([
+ "anthropic",
+ "openai",
+ "codex",
+ "gemini",
+ "kimi",
+ ]);
});
});
describe("ProviderType", () => {
it("should define valid provider types", () => {
// Test that the type constraints work by using valid values
- const validTypes: ProviderExports.ProviderType[] = ["anthropic", "openai", "gemini", "kimi"];
- expect(validTypes).toHaveLength(4);
+ const validTypes: ProviderExports.ProviderType[] = [
+ "anthropic",
+ "openai",
+ "codex",
+ "gemini",
+ "kimi",
+ "lmstudio",
+ ];
+ expect(validTypes).toHaveLength(6);
});
});
});
diff --git a/src/providers/index.ts b/src/providers/index.ts
index 40eb1ea..f23b3dc 100644
--- a/src/providers/index.ts
+++ b/src/providers/index.ts
@@ -29,6 +29,9 @@ export { AnthropicProvider, createAnthropicProvider } from "./anthropic.js";
// OpenAI provider
export { OpenAIProvider, createOpenAIProvider, createKimiProvider } from "./openai.js";
+// Codex provider (ChatGPT Plus/Pro via OAuth)
+export { CodexProvider, createCodexProvider } from "./codex.js";
+
// Gemini provider
export { GeminiProvider, createGeminiProvider } from "./gemini.js";
@@ -76,13 +79,14 @@ import type { LLMProvider, ProviderConfig } from "./types.js";
import { AnthropicProvider } from "./anthropic.js";
import { OpenAIProvider, createKimiProvider } from "./openai.js";
import { GeminiProvider } from "./gemini.js";
+import { CodexProvider } from "./codex.js";
import { ProviderError } from "../utils/errors.js";
import { getApiKey, getBaseUrl, getDefaultModel } from "../config/env.js";
/**
* Supported provider types
*/
-export type ProviderType = "anthropic" | "openai" | "gemini" | "kimi";
+export type ProviderType = "anthropic" | "openai" | "codex" | "gemini" | "kimi" | "lmstudio";
/**
* Create a provider by type
@@ -112,6 +116,11 @@ export async function createProvider(
provider = new OpenAIProvider();
break;
+ case "codex":
+ // Codex uses OAuth tokens from ChatGPT Plus/Pro
+ provider = new CodexProvider();
+ break;
+
case "gemini":
provider = new GeminiProvider();
break;
@@ -121,6 +130,14 @@ export async function createProvider(
await provider.initialize(mergedConfig);
return provider;
+ case "lmstudio":
+ // LM Studio uses OpenAI-compatible API
+ provider = new OpenAIProvider();
+ // Override base URL for LM Studio
+ mergedConfig.baseUrl = mergedConfig.baseUrl ?? "http://localhost:1234/v1";
+ mergedConfig.apiKey = mergedConfig.apiKey ?? "lm-studio"; // LM Studio doesn't need real key
+ break;
+
default:
throw new ProviderError(`Unknown provider type: ${type}`, {
provider: type,
@@ -156,9 +173,14 @@ export function listProviders(): Array<{
},
{
id: "openai",
- name: "OpenAI",
+ name: "OpenAI (API Key)",
configured: !!getApiKey("openai"),
},
+ {
+ id: "codex",
+ name: "OpenAI Codex (ChatGPT Plus/Pro)",
+ configured: false, // Will check OAuth tokens separately
+ },
{
id: "gemini",
name: "Google Gemini",
diff --git a/src/providers/integration.test.ts b/src/providers/integration.test.ts
index edfd286..8a9bed2 100644
--- a/src/providers/integration.test.ts
+++ b/src/providers/integration.test.ts
@@ -9,20 +9,9 @@
* - Error handling and retry
*/
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach } from "vitest";
import type { Mock } from "vitest";
-import type {
- LLMProvider,
- ProviderConfig,
- Message,
- ChatOptions,
- ChatResponse,
- ChatWithToolsOptions,
- ChatWithToolsResponse,
- ToolDefinition,
- ToolCall,
- StreamChunk,
-} from "./types.js";
+import type { LLMProvider, Message, ToolDefinition } from "./types.js";
// Mock the Anthropic SDK
vi.mock("@anthropic-ai/sdk", () => {
diff --git a/src/providers/openai.ts b/src/providers/openai.ts
index a65f823..b4be13a 100644
--- a/src/providers/openai.ts
+++ b/src/providers/openai.ts
@@ -22,9 +22,9 @@ import { ProviderError } from "../utils/errors.js";
import { withRetry, type RetryConfig, DEFAULT_RETRY_CONFIG } from "./retry.js";
/**
- * Default models
+ * Default model - Updated January 2026
*/
-const DEFAULT_MODEL = "gpt-4o";
+const DEFAULT_MODEL = "gpt-5.2-codex";
/**
* Context windows for models
@@ -39,6 +39,13 @@ const CONTEXT_WINDOWS: Record = {
o1: 200000,
"o1-mini": 128000,
"o3-mini": 200000,
+ // GPT-5 series (2025-2026)
+ "gpt-5": 400000,
+ "gpt-5.2": 400000,
+ "gpt-5.2-codex": 400000,
+ "gpt-5.2-thinking": 400000,
+ "gpt-5.2-instant": 400000,
+ "gpt-5.2-pro": 400000,
// Kimi/Moonshot models
"kimi-k2.5": 262144,
"kimi-k2-0324": 131072,
@@ -46,6 +53,33 @@ const CONTEXT_WINDOWS: Record = {
"moonshot-v1-8k": 8000,
"moonshot-v1-32k": 32000,
"moonshot-v1-128k": 128000,
+ // LM Studio / Local models (Qwen3-Coder series)
+ "qwen3-coder-3b-instruct": 256000,
+ "qwen3-coder-8b-instruct": 256000,
+ "qwen3-coder-14b-instruct": 256000,
+ "qwen3-coder-32b-instruct": 256000,
+ // DeepSeek Coder models
+ "deepseek-coder-v3": 128000,
+ "deepseek-coder-v3-lite": 128000,
+ "deepseek-coder-v2": 128000,
+ "deepseek-coder": 128000,
+ // Codestral (Mistral)
+ "codestral-22b": 32768,
+ codestral: 32768,
+ // Qwen 2.5 Coder (legacy but still popular)
+ "qwen2.5-coder-7b-instruct": 32768,
+ "qwen2.5-coder-14b-instruct": 32768,
+ "qwen2.5-coder-32b-instruct": 32768,
+ // Llama 3 Code models
+ "llama-3-8b": 8192,
+ "llama-3-70b": 8192,
+ "llama-3.1-8b": 128000,
+ "llama-3.1-70b": 128000,
+ "llama-3.2-3b": 128000,
+ // Mistral models
+ "mistral-7b": 32768,
+ "mistral-nemo": 128000,
+ "mixtral-8x7b": 32768,
};
/**
@@ -61,6 +95,22 @@ const MODELS_WITHOUT_TEMPERATURE: string[] = [
"kimi-latest",
];
+/**
+ * Local model patterns - these use different tokenizers
+ * Used for more accurate token counting
+ */
+const LOCAL_MODEL_PATTERNS: string[] = [
+ "qwen",
+ "deepseek",
+ "codestral",
+ "llama",
+ "mistral",
+ "mixtral",
+ "phi",
+ "gemma",
+ "starcoder",
+];
+
/**
* Models that have "thinking" mode enabled by default and need it disabled for tool use
* Kimi K2.5 has interleaved reasoning that requires reasoning_content to be passed back
@@ -316,98 +366,144 @@ export class OpenAIProvider implements LLMProvider {
const toolCallBuilders: Map =
new Map();
- for await (const chunk of stream) {
- const delta = chunk.choices[0]?.delta;
+ // Add timeout protection for local LLMs that may hang
+ const streamTimeout = this.config.timeout ?? 120000;
+ let lastActivityTime = Date.now();
- // Handle text content
- if (delta?.content) {
- yield { type: "text", text: delta.content };
+ const checkTimeout = () => {
+ if (Date.now() - lastActivityTime > streamTimeout) {
+ throw new Error(`Stream timeout: No response from LLM for ${streamTimeout / 1000}s`);
}
+ };
- // Handle tool calls
- if (delta?.tool_calls) {
- for (const toolCallDelta of delta.tool_calls) {
- const index = toolCallDelta.index;
-
- if (!toolCallBuilders.has(index)) {
- // New tool call starting
- toolCallBuilders.set(index, {
- id: toolCallDelta.id ?? "",
- name: toolCallDelta.function?.name ?? "",
- arguments: "",
- });
- yield {
- type: "tool_use_start",
- toolCall: {
- id: toolCallDelta.id,
- name: toolCallDelta.function?.name,
- },
- };
- }
-
- const builder = toolCallBuilders.get(index)!;
+ // Set up periodic timeout check
+ const timeoutInterval = setInterval(checkTimeout, 5000);
- // Update id if provided
- if (toolCallDelta.id) {
- builder.id = toolCallDelta.id;
- }
+ try {
+ for await (const chunk of stream) {
+ lastActivityTime = Date.now(); // Reset timeout on activity
+ const delta = chunk.choices[0]?.delta;
- // Update name if provided
- if (toolCallDelta.function?.name) {
- builder.name = toolCallDelta.function.name;
- }
+ // Handle text content
+ if (delta?.content) {
+ yield { type: "text", text: delta.content };
+ }
- // Accumulate arguments
- if (toolCallDelta.function?.arguments) {
- builder.arguments += toolCallDelta.function.arguments;
- yield {
- type: "tool_use_delta",
- toolCall: {
- id: builder.id,
- name: builder.name,
- },
- text: toolCallDelta.function.arguments,
- };
+ // Handle tool calls
+ if (delta?.tool_calls) {
+ for (const toolCallDelta of delta.tool_calls) {
+ const index = toolCallDelta.index;
+
+ if (!toolCallBuilders.has(index)) {
+ // New tool call starting
+ toolCallBuilders.set(index, {
+ id: toolCallDelta.id ?? "",
+ name: toolCallDelta.function?.name ?? "",
+ arguments: "",
+ });
+ yield {
+ type: "tool_use_start",
+ toolCall: {
+ id: toolCallDelta.id,
+ name: toolCallDelta.function?.name,
+ },
+ };
+ }
+
+ const builder = toolCallBuilders.get(index)!;
+
+ // Update id if provided
+ if (toolCallDelta.id) {
+ builder.id = toolCallDelta.id;
+ }
+
+ // Update name if provided
+ if (toolCallDelta.function?.name) {
+ builder.name = toolCallDelta.function.name;
+ }
+
+ // Accumulate arguments
+ if (toolCallDelta.function?.arguments) {
+ builder.arguments += toolCallDelta.function.arguments;
+ yield {
+ type: "tool_use_delta",
+ toolCall: {
+ id: builder.id,
+ name: builder.name,
+ },
+ text: toolCallDelta.function.arguments,
+ };
+ }
}
}
}
- }
- // Finalize all tool calls
- for (const [, builder] of toolCallBuilders) {
- let input: Record = {};
- try {
- input = builder.arguments ? JSON.parse(builder.arguments) : {};
- } catch {
- // Invalid JSON, use empty object
+ // Finalize all tool calls
+ for (const [, builder] of toolCallBuilders) {
+ let input: Record = {};
+ try {
+ input = builder.arguments ? JSON.parse(builder.arguments) : {};
+ } catch {
+ // Invalid JSON, use empty object
+ }
+
+ yield {
+ type: "tool_use_end",
+ toolCall: {
+ id: builder.id,
+ name: builder.name,
+ input,
+ },
+ };
}
- yield {
- type: "tool_use_end",
- toolCall: {
- id: builder.id,
- name: builder.name,
- input,
- },
- };
+ yield { type: "done" };
+ } finally {
+ clearInterval(timeoutInterval);
}
-
- yield { type: "done" };
} catch (error) {
throw this.handleError(error);
}
}
/**
- * Count tokens (improved heuristic for OpenAI models)
+ * Check if current model is a local model (LM Studio, Ollama, etc.)
+ */
+ private isLocalModel(): boolean {
+ const model = (this.config.model ?? "").toLowerCase();
+ const baseUrl = (this.config.baseUrl ?? "").toLowerCase();
+
+ // Check by URL patterns (localhost, common local ports)
+ if (
+ baseUrl.includes("localhost") ||
+ baseUrl.includes("127.0.0.1") ||
+ baseUrl.includes(":1234") || // LM Studio default
+ baseUrl.includes(":11434") // Ollama default
+ ) {
+ return true;
+ }
+
+ // Check by model name patterns
+ return LOCAL_MODEL_PATTERNS.some((pattern) => model.includes(pattern));
+ }
+
+ /**
+ * Count tokens (improved heuristic for OpenAI and local models)
+ *
+ * Different tokenizers have different characteristics:
*
- * GPT models use a BPE tokenizer. The average ratio varies:
+ * GPT models (BPE tokenizer - tiktoken):
* - English text: ~4 characters per token
- * - Code: ~3.3 characters per token (more syntax chars)
- * - Common words: Often 1 token per word
+ * - Code: ~3.3 characters per token
*
- * For accurate counting, use tiktoken library.
- * This heuristic provides a reasonable estimate without the dependency.
+ * Local models (SentencePiece/HuggingFace tokenizers):
+ * - Qwen models: ~3.5 chars/token for code, uses tiktoken-compatible
+ * - Llama models: ~3.8 chars/token, SentencePiece-based
+ * - DeepSeek: ~3.2 chars/token for code, BPE-based
+ * - Mistral: ~3.5 chars/token, SentencePiece-based
+ *
+ * For accurate counting, use the model's native tokenizer.
+ * This heuristic provides a reasonable estimate without dependencies.
*/
countTokens(text: string): number {
if (!text) return 0;
@@ -416,40 +512,110 @@ export class OpenAIProvider implements LLMProvider {
const codePatterns = /[{}[\]();=<>!&|+\-*/]/g;
const whitespacePattern = /\s/g;
const wordPattern = /\b\w+\b/g;
+ // oxlint-disable-next-line no-control-regex -- Intentional: detecting non-ASCII characters
+ const nonAsciiPattern = /[^\x00-\x7F]/g;
const codeChars = (text.match(codePatterns) || []).length;
const whitespace = (text.match(whitespacePattern) || []).length;
const words = (text.match(wordPattern) || []).length;
+ const nonAscii = (text.match(nonAsciiPattern) || []).length;
// Estimate if text is code-like
const isCodeLike = codeChars > text.length * 0.05;
- // Calculate base ratio
+ // Check if we're using a local model (different tokenizer characteristics)
+ const isLocal = this.isLocalModel();
+
+ // Calculate base ratio based on model type and content
let charsPerToken: number;
- if (isCodeLike) {
- charsPerToken = 3.3;
- } else if (whitespace > text.length * 0.3) {
- charsPerToken = 4.5;
+ if (isLocal) {
+ // Local models tend to have slightly more efficient tokenization for code
+ if (isCodeLike) {
+ charsPerToken = 3.2; // Code is more efficiently tokenized
+ } else if (nonAscii > text.length * 0.1) {
+ charsPerToken = 2.0; // Non-ASCII (CJK, emoji) uses more tokens
+ } else {
+ charsPerToken = 3.5;
+ }
} else {
- charsPerToken = 4.0;
+ // OpenAI GPT models
+ if (isCodeLike) {
+ charsPerToken = 3.3;
+ } else if (whitespace > text.length * 0.3) {
+ charsPerToken = 4.5;
+ } else {
+ charsPerToken = 4.0;
+ }
}
- // Word-based estimate (GPT tends to have ~1.3 tokens per word)
- const wordBasedEstimate = words * 1.3;
+ // Word-based estimate
+ const tokensPerWord = isLocal ? 1.4 : 1.3;
+ const wordBasedEstimate = words * tokensPerWord;
// Char-based estimate
const charBasedEstimate = text.length / charsPerToken;
- // Use average of both methods
- return Math.ceil((wordBasedEstimate + charBasedEstimate) / 2);
+ // Use weighted average (char-based is usually more reliable for code)
+ const weight = isCodeLike ? 0.7 : 0.5;
+ return Math.ceil(charBasedEstimate * weight + wordBasedEstimate * (1 - weight));
}
/**
* Get context window size
+ *
+ * For local models, tries to match by model family if exact match not found.
+ * This handles cases where LM Studio reports models with different naming
+ * conventions (e.g., "qwen3-coder-8b" vs "qwen3-coder-8b-instruct").
*/
getContextWindow(): number {
const model = this.config.model ?? DEFAULT_MODEL;
- return CONTEXT_WINDOWS[model] ?? 128000;
+
+ // Try exact match first
+ if (CONTEXT_WINDOWS[model]) {
+ return CONTEXT_WINDOWS[model];
+ }
+
+ // Try partial match for local models
+ const modelLower = model.toLowerCase();
+ for (const [key, value] of Object.entries(CONTEXT_WINDOWS)) {
+ // Check if model name contains the key or vice versa
+ if (modelLower.includes(key.toLowerCase()) || key.toLowerCase().includes(modelLower)) {
+ return value;
+ }
+ }
+
+ // Infer context window by model family for local models
+ if (modelLower.includes("qwen3-coder")) {
+ return 256000; // Qwen3-Coder has 256k context
+ }
+ if (modelLower.includes("qwen2.5-coder")) {
+ return 32768;
+ }
+ if (modelLower.includes("deepseek-coder")) {
+ return 128000;
+ }
+ if (modelLower.includes("codestral")) {
+ return 32768;
+ }
+ if (modelLower.includes("llama-3.1") || modelLower.includes("llama-3.2")) {
+ return 128000;
+ }
+ if (modelLower.includes("llama")) {
+ return 8192;
+ }
+ if (modelLower.includes("mistral-nemo")) {
+ return 128000;
+ }
+ if (modelLower.includes("mistral") || modelLower.includes("mixtral")) {
+ return 32768;
+ }
+
+ // Default for unknown models (conservative estimate for local models)
+ if (this.isLocalModel()) {
+ return 32768; // Safe default for local models
+ }
+
+ return 128000; // Default for cloud APIs
}
/**
@@ -473,7 +639,7 @@ export class OpenAIProvider implements LLMProvider {
max_tokens: 1,
});
return true;
- } catch (chatError) {
+ } catch {
// If we get a 401/403, the key is invalid
// If we get a 404, the model might not exist
// If we get other errors, provider might be down
diff --git a/src/providers/pricing.test.ts b/src/providers/pricing.test.ts
index 839a2ba..aa06aa5 100644
--- a/src/providers/pricing.test.ts
+++ b/src/providers/pricing.test.ts
@@ -37,7 +37,7 @@ describe("MODEL_PRICING", () => {
});
it("should have valid pricing structure", () => {
- for (const [model, pricing] of Object.entries(MODEL_PRICING)) {
+ for (const [_model, pricing] of Object.entries(MODEL_PRICING)) {
expect(pricing.inputPerMillion).toBeGreaterThan(0);
expect(pricing.outputPerMillion).toBeGreaterThan(0);
expect(pricing.contextWindow).toBeGreaterThan(0);
diff --git a/src/providers/pricing.ts b/src/providers/pricing.ts
index a5d55aa..7268c06 100644
--- a/src/providers/pricing.ts
+++ b/src/providers/pricing.ts
@@ -58,8 +58,10 @@ export const MODEL_PRICING: Record = {
export const DEFAULT_PRICING: Record = {
anthropic: { inputPerMillion: 3, outputPerMillion: 15, contextWindow: 200000 },
openai: { inputPerMillion: 2.5, outputPerMillion: 10, contextWindow: 128000 },
+ codex: { inputPerMillion: 0, outputPerMillion: 0, contextWindow: 128000 }, // ChatGPT Plus/Pro subscription
gemini: { inputPerMillion: 0.1, outputPerMillion: 0.4, contextWindow: 1000000 },
kimi: { inputPerMillion: 1.2, outputPerMillion: 1.2, contextWindow: 8192 },
+ lmstudio: { inputPerMillion: 0, outputPerMillion: 0, contextWindow: 32768 }, // Free - local models
};
/**
diff --git a/src/providers/types.ts b/src/providers/types.ts
index d2fbc03..1445882 100644
--- a/src/providers/types.ts
+++ b/src/providers/types.ts
@@ -199,6 +199,8 @@ export interface ProviderConfig {
maxTokens?: number;
temperature?: number;
timeout?: number;
+ /** Internal: flag to indicate using Google Cloud ADC */
+ useADC?: boolean;
}
/**
diff --git a/src/tools/allowed-paths.test.ts b/src/tools/allowed-paths.test.ts
new file mode 100644
index 0000000..c8308ec
--- /dev/null
+++ b/src/tools/allowed-paths.test.ts
@@ -0,0 +1,323 @@
+/**
+ * Tests for Allowed Paths Store
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import path from "node:path";
+
+// Mock fs before importing the module
+vi.mock("node:fs/promises", () => ({
+ default: {
+ readFile: vi.fn(),
+ writeFile: vi.fn(),
+ mkdir: vi.fn(),
+ },
+}));
+
+// Mock config paths
+vi.mock("../config/paths.js", () => ({
+ CONFIG_PATHS: {
+ home: "/mock/.coco",
+ config: "/mock/.coco/config.json",
+ env: "/mock/.coco/.env",
+ projects: "/mock/.coco/projects.json",
+ trustedTools: "/mock/.coco/trusted-tools.json",
+ },
+}));
+
+import {
+ getAllowedPaths,
+ isWithinAllowedPath,
+ addAllowedPathToSession,
+ removeAllowedPathFromSession,
+ clearSessionAllowedPaths,
+ loadAllowedPaths,
+ persistAllowedPath,
+ removePersistedAllowedPath,
+} from "./allowed-paths.js";
+
+describe("Allowed Paths Store", () => {
+ beforeEach(() => {
+ clearSessionAllowedPaths();
+ vi.clearAllMocks();
+ });
+
+ describe("getAllowedPaths", () => {
+ it("should return empty array initially", () => {
+ expect(getAllowedPaths()).toEqual([]);
+ });
+
+ it("should return a copy of allowed paths", () => {
+ addAllowedPathToSession("/test/dir", "read");
+ const paths = getAllowedPaths();
+ expect(paths).toHaveLength(1);
+ expect(paths[0]!.path).toBe("/test/dir");
+ // Should be a copy
+ paths.push({ path: "/extra", authorizedAt: "", level: "read" });
+ expect(getAllowedPaths()).toHaveLength(1);
+ });
+ });
+
+ describe("isWithinAllowedPath", () => {
+ it("should return false when no paths are allowed", () => {
+ expect(isWithinAllowedPath("/some/path", "read")).toBe(false);
+ });
+
+ it("should return true for exact match with read", () => {
+ addAllowedPathToSession("/allowed/dir", "read");
+ expect(isWithinAllowedPath("/allowed/dir", "read")).toBe(true);
+ });
+
+ it("should return true for subdirectory with read", () => {
+ addAllowedPathToSession("/allowed/dir", "read");
+ expect(isWithinAllowedPath("/allowed/dir/sub/file.txt", "read")).toBe(true);
+ });
+
+ it("should return false for partial path match", () => {
+ addAllowedPathToSession("/allowed/dir", "read");
+ expect(isWithinAllowedPath("/allowed/directory", "read")).toBe(false);
+ });
+
+ it("should allow read on write-level entries", () => {
+ addAllowedPathToSession("/allowed/dir", "write");
+ expect(isWithinAllowedPath("/allowed/dir/file.txt", "read")).toBe(true);
+ });
+
+ it("should allow write on write-level entries", () => {
+ addAllowedPathToSession("/allowed/dir", "write");
+ expect(isWithinAllowedPath("/allowed/dir/file.txt", "write")).toBe(true);
+ });
+
+ it("should deny write on read-level entries", () => {
+ addAllowedPathToSession("/allowed/dir", "read");
+ expect(isWithinAllowedPath("/allowed/dir/file.txt", "write")).toBe(false);
+ });
+
+ it("should deny delete on read-level entries", () => {
+ addAllowedPathToSession("/allowed/dir", "read");
+ expect(isWithinAllowedPath("/allowed/dir/file.txt", "delete")).toBe(false);
+ });
+
+ it("should allow delete on write-level entries", () => {
+ addAllowedPathToSession("/allowed/dir", "write");
+ expect(isWithinAllowedPath("/allowed/dir/file.txt", "delete")).toBe(true);
+ });
+ });
+
+ describe("addAllowedPathToSession", () => {
+ it("should add a path to the session", () => {
+ addAllowedPathToSession("/test/path", "read");
+ const paths = getAllowedPaths();
+ expect(paths).toHaveLength(1);
+ expect(paths[0]!.level).toBe("read");
+ });
+
+ it("should not add duplicate paths", () => {
+ addAllowedPathToSession("/test/path", "read");
+ addAllowedPathToSession("/test/path", "read");
+ expect(getAllowedPaths()).toHaveLength(1);
+ });
+
+ it("should resolve relative paths to absolute", () => {
+ addAllowedPathToSession("relative/path", "write");
+ const paths = getAllowedPaths();
+ expect(paths).toHaveLength(1);
+ expect(path.isAbsolute(paths[0]!.path)).toBe(true);
+ });
+
+ it("should include authorizedAt timestamp", () => {
+ addAllowedPathToSession("/test/path", "read");
+ const paths = getAllowedPaths();
+ expect(paths[0]!.authorizedAt).toBeTruthy();
+ // Should be ISO string
+ expect(new Date(paths[0]!.authorizedAt).toISOString()).toBe(paths[0]!.authorizedAt);
+ });
+ });
+
+ describe("removeAllowedPathFromSession", () => {
+ it("should remove an existing path", () => {
+ addAllowedPathToSession("/test/path", "read");
+ const removed = removeAllowedPathFromSession("/test/path");
+ expect(removed).toBe(true);
+ expect(getAllowedPaths()).toHaveLength(0);
+ });
+
+ it("should return false when path not found", () => {
+ const removed = removeAllowedPathFromSession("/nonexistent");
+ expect(removed).toBe(false);
+ });
+ });
+
+ describe("clearSessionAllowedPaths", () => {
+ it("should clear all paths", () => {
+ addAllowedPathToSession("/path1", "read");
+ addAllowedPathToSession("/path2", "write");
+ clearSessionAllowedPaths();
+ expect(getAllowedPaths()).toHaveLength(0);
+ });
+ });
+
+ describe("loadAllowedPaths", () => {
+ it("should load persisted paths into session", async () => {
+ const fs = await import("node:fs/promises");
+ const store = {
+ version: 1,
+ projects: {
+ [path.resolve("/my/project")]: [
+ {
+ path: "/extra/dir",
+ authorizedAt: "2026-01-01T00:00:00.000Z",
+ level: "read" as const,
+ },
+ ],
+ },
+ };
+ vi.mocked(fs.default.readFile).mockResolvedValue(JSON.stringify(store));
+
+ await loadAllowedPaths("/my/project");
+
+ const paths = getAllowedPaths();
+ expect(paths).toHaveLength(1);
+ expect(paths[0]!.path).toBe("/extra/dir");
+ });
+
+ it("should handle missing store file", async () => {
+ const fs = await import("node:fs/promises");
+ vi.mocked(fs.default.readFile).mockRejectedValue(new Error("ENOENT"));
+
+ await loadAllowedPaths("/my/project");
+ expect(getAllowedPaths()).toHaveLength(0);
+ });
+
+ it("should not add duplicates when loading", async () => {
+ const fs = await import("node:fs/promises");
+ addAllowedPathToSession("/extra/dir", "read");
+
+ const store = {
+ version: 1,
+ projects: {
+ [path.resolve("/my/project")]: [
+ {
+ path: "/extra/dir",
+ authorizedAt: "2026-01-01T00:00:00.000Z",
+ level: "read" as const,
+ },
+ ],
+ },
+ };
+ vi.mocked(fs.default.readFile).mockResolvedValue(JSON.stringify(store));
+
+ await loadAllowedPaths("/my/project");
+ expect(getAllowedPaths()).toHaveLength(1);
+ });
+ });
+
+ describe("persistAllowedPath", () => {
+ it("should persist a path to the store file", async () => {
+ const fs = await import("node:fs/promises");
+ // First load to set currentProjectPath
+ vi.mocked(fs.default.readFile).mockResolvedValue(
+ JSON.stringify({ version: 1, projects: {} }),
+ );
+ await loadAllowedPaths("/my/project");
+
+ vi.mocked(fs.default.mkdir).mockResolvedValue(undefined);
+ vi.mocked(fs.default.writeFile).mockResolvedValue(undefined);
+
+ await persistAllowedPath("/new/dir", "write");
+
+ expect(vi.mocked(fs.default.writeFile)).toHaveBeenCalled();
+ const written = JSON.parse(vi.mocked(fs.default.writeFile).mock.calls[0]![1] as string);
+ const entries = written.projects[path.resolve("/my/project")];
+ expect(entries).toHaveLength(1);
+ expect(entries[0].path).toBe(path.resolve("/new/dir"));
+ expect(entries[0].level).toBe("write");
+ });
+
+ it("should not persist duplicates", async () => {
+ const fs = await import("node:fs/promises");
+ const projectPath = path.resolve("/my/project");
+ const existing = {
+ version: 1,
+ projects: {
+ [projectPath]: [
+ {
+ path: path.resolve("/new/dir"),
+ authorizedAt: "2026-01-01T00:00:00.000Z",
+ level: "write",
+ },
+ ],
+ },
+ };
+ vi.mocked(fs.default.readFile).mockResolvedValue(JSON.stringify(existing));
+ await loadAllowedPaths("/my/project");
+
+ await persistAllowedPath("/new/dir", "write");
+ // writeFile should not have been called (no change)
+ expect(vi.mocked(fs.default.writeFile)).not.toHaveBeenCalled();
+ });
+
+ it("should do nothing if no project loaded", async () => {
+ clearSessionAllowedPaths();
+ // Reset currentProjectPath by not calling loadAllowedPaths
+ // We can't directly reset it, but persistAllowedPath guards against empty project
+ const fs = await import("node:fs/promises");
+ vi.mocked(fs.default.readFile).mockResolvedValue(
+ JSON.stringify({ version: 1, projects: {} }),
+ );
+ // Don't call loadAllowedPaths so currentProjectPath might still be set from previous test
+ // Just verify it doesn't throw
+ await persistAllowedPath("/some/dir", "read");
+ });
+ });
+
+ describe("removePersistedAllowedPath", () => {
+ it("should remove a persisted path", async () => {
+ const fs = await import("node:fs/promises");
+ const projectPath = path.resolve("/my/project");
+ const existing = {
+ version: 1,
+ projects: {
+ [projectPath]: [
+ {
+ path: path.resolve("/old/dir"),
+ authorizedAt: "2026-01-01T00:00:00.000Z",
+ level: "read",
+ },
+ ],
+ },
+ };
+ vi.mocked(fs.default.readFile).mockResolvedValue(JSON.stringify(existing));
+ vi.mocked(fs.default.mkdir).mockResolvedValue(undefined);
+ vi.mocked(fs.default.writeFile).mockResolvedValue(undefined);
+ await loadAllowedPaths("/my/project");
+
+ const removed = await removePersistedAllowedPath("/old/dir");
+ expect(removed).toBe(true);
+ expect(vi.mocked(fs.default.writeFile)).toHaveBeenCalled();
+ });
+
+ it("should return false when path not found in store", async () => {
+ const fs = await import("node:fs/promises");
+ const projectPath = path.resolve("/my/project");
+ vi.mocked(fs.default.readFile).mockResolvedValue(
+ JSON.stringify({ version: 1, projects: { [projectPath]: [] } }),
+ );
+ await loadAllowedPaths("/my/project");
+
+ const removed = await removePersistedAllowedPath("/nonexistent");
+ expect(removed).toBe(false);
+ });
+
+ it("should return false when project has no entries", async () => {
+ const fs = await import("node:fs/promises");
+ vi.mocked(fs.default.readFile).mockResolvedValue(
+ JSON.stringify({ version: 1, projects: {} }),
+ );
+ await loadAllowedPaths("/my/project");
+
+ const removed = await removePersistedAllowedPath("/some/dir");
+ expect(removed).toBe(false);
+ });
+ });
+});
diff --git a/src/tools/allowed-paths.ts b/src/tools/allowed-paths.ts
new file mode 100644
index 0000000..928c06e
--- /dev/null
+++ b/src/tools/allowed-paths.ts
@@ -0,0 +1,212 @@
+/**
+ * Allowed Paths Store
+ *
+ * Manages additional directories that the user has explicitly authorized
+ * for file operations beyond the project root (process.cwd()).
+ *
+ * Security invariants preserved:
+ * - System paths (/etc, /var, etc.) are NEVER allowed
+ * - Sensitive file patterns (.env, .pem, etc.) still require confirmation
+ * - Null byte injection is still blocked
+ * - Symlink validation is still active
+ * - Each path must be explicitly authorized by the user
+ */
+
+import path from "node:path";
+import fs from "node:fs/promises";
+import { CONFIG_PATHS } from "../config/paths.js";
+
+/**
+ * Persisted allowed paths per project
+ */
+interface AllowedPathsStore {
+ version: number;
+ /** Map of project path -> array of allowed extra paths */
+ projects: Record;
+}
+
+export interface AllowedPathEntry {
+ /** Absolute path to the allowed directory */
+ path: string;
+ /** When it was authorized */
+ authorizedAt: string;
+ /** Permission level */
+ level: "read" | "write";
+}
+
+const STORE_FILE = path.join(CONFIG_PATHS.home, "allowed-paths.json");
+
+const DEFAULT_STORE: AllowedPathsStore = {
+ version: 1,
+ projects: {},
+};
+
+/**
+ * Runtime allowed paths for the current session.
+ * This is the source of truth checked by isPathAllowed().
+ */
+let sessionAllowedPaths: AllowedPathEntry[] = [];
+
+/**
+ * Current project path (set during initialization)
+ */
+let currentProjectPath: string = "";
+
+/**
+ * Get current session allowed paths (for display/commands)
+ */
+export function getAllowedPaths(): AllowedPathEntry[] {
+ return [...sessionAllowedPaths];
+}
+
+/**
+ * Check if a given absolute path falls within any allowed path
+ */
+export function isWithinAllowedPath(
+ absolutePath: string,
+ operation: "read" | "write" | "delete",
+): boolean {
+ const normalizedTarget = path.normalize(absolutePath);
+
+ for (const entry of sessionAllowedPaths) {
+ const normalizedAllowed = path.normalize(entry.path);
+
+ // Check if target is within the allowed directory
+ if (
+ normalizedTarget === normalizedAllowed ||
+ normalizedTarget.startsWith(normalizedAllowed + path.sep)
+ ) {
+ // For write/delete operations, check that the entry allows writes
+ if (operation === "read") return true;
+ if (entry.level === "write") return true;
+ }
+ }
+
+ return false;
+}
+
+/**
+ * Add an allowed path to the current session
+ */
+export function addAllowedPathToSession(dirPath: string, level: "read" | "write"): void {
+ const absolute = path.resolve(dirPath);
+
+ // Don't add duplicates
+ if (sessionAllowedPaths.some((e) => path.normalize(e.path) === path.normalize(absolute))) {
+ return;
+ }
+
+ sessionAllowedPaths.push({
+ path: absolute,
+ authorizedAt: new Date().toISOString(),
+ level,
+ });
+}
+
+/**
+ * Remove an allowed path from the current session
+ */
+export function removeAllowedPathFromSession(dirPath: string): boolean {
+ const absolute = path.resolve(dirPath);
+ const normalized = path.normalize(absolute);
+ const before = sessionAllowedPaths.length;
+ sessionAllowedPaths = sessionAllowedPaths.filter((e) => path.normalize(e.path) !== normalized);
+ return sessionAllowedPaths.length < before;
+}
+
+/**
+ * Clear all session allowed paths
+ */
+export function clearSessionAllowedPaths(): void {
+ sessionAllowedPaths = [];
+}
+
+// --- Persistence ---
+
+/**
+ * Load persisted allowed paths for a project into the session
+ */
+export async function loadAllowedPaths(projectPath: string): Promise {
+ currentProjectPath = path.resolve(projectPath);
+ const store = await loadStore();
+ const entries = store.projects[currentProjectPath] ?? [];
+
+ // Merge persisted paths into session (avoid duplicates)
+ for (const entry of entries) {
+ addAllowedPathToSession(entry.path, entry.level);
+ }
+}
+
+/**
+ * Persist an allowed path for the current project
+ */
+export async function persistAllowedPath(dirPath: string, level: "read" | "write"): Promise {
+ if (!currentProjectPath) return;
+
+ const absolute = path.resolve(dirPath);
+ const store = await loadStore();
+
+ if (!store.projects[currentProjectPath]) {
+ store.projects[currentProjectPath] = [];
+ }
+
+ const entries = store.projects[currentProjectPath]!;
+ const normalized = path.normalize(absolute);
+
+ // Don't add duplicates
+ if (entries.some((e) => path.normalize(e.path) === normalized)) {
+ return;
+ }
+
+ entries.push({
+ path: absolute,
+ authorizedAt: new Date().toISOString(),
+ level,
+ });
+
+ await saveStore(store);
+}
+
+/**
+ * Remove a persisted allowed path
+ */
+export async function removePersistedAllowedPath(dirPath: string): Promise {
+ if (!currentProjectPath) return false;
+
+ const absolute = path.resolve(dirPath);
+ const normalized = path.normalize(absolute);
+ const store = await loadStore();
+ const entries = store.projects[currentProjectPath];
+
+ if (!entries) return false;
+
+ const before = entries.length;
+ store.projects[currentProjectPath] = entries.filter((e) => path.normalize(e.path) !== normalized);
+
+ if (store.projects[currentProjectPath]!.length < before) {
+ await saveStore(store);
+ return true;
+ }
+
+ return false;
+}
+
+// --- Internal ---
+
+async function loadStore(): Promise {
+ try {
+ const content = await fs.readFile(STORE_FILE, "utf-8");
+ return { ...DEFAULT_STORE, ...JSON.parse(content) };
+ } catch {
+ return { ...DEFAULT_STORE };
+ }
+}
+
+async function saveStore(store: AllowedPathsStore): Promise {
+ try {
+ await fs.mkdir(path.dirname(STORE_FILE), { recursive: true });
+ await fs.writeFile(STORE_FILE, JSON.stringify(store, null, 2), "utf-8");
+ } catch {
+ // Silently fail
+ }
+}
diff --git a/src/tools/build.test.ts b/src/tools/build.test.ts
new file mode 100644
index 0000000..5864ce2
--- /dev/null
+++ b/src/tools/build.test.ts
@@ -0,0 +1,452 @@
+/**
+ * Tests for build tools
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { BuildResult } from "./build.js";
+
+// Mock execa
+vi.mock("execa", () => ({
+ execa: vi.fn(),
+}));
+
+// Mock fs
+vi.mock("node:fs/promises", () => ({
+ default: {
+ access: vi.fn(),
+ },
+}));
+
+import { runScriptTool, installDepsTool, makeTool, tscTool, buildTools } from "./build.js";
+import { execa } from "execa";
+import fs from "node:fs/promises";
+
+function mockExecaResult(
+ overrides: Partial<{ stdout: string; stderr: string; exitCode: number }> = {},
+) {
+ return {
+ stdout: overrides.stdout ?? "",
+ stderr: overrides.stderr ?? "",
+ exitCode: overrides.exitCode ?? 0,
+ ...overrides,
+ };
+}
+
+describe("Build Tools", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ // Default: pnpm-lock.yaml exists (detect pnpm)
+ vi.mocked(fs.access).mockRejectedValue(new Error("ENOENT"));
+ });
+
+ describe("buildTools export", () => {
+ it("should export all 4 build tools", () => {
+ expect(buildTools).toHaveLength(4);
+ });
+ });
+
+ describe("runScriptTool", () => {
+ it("should have correct metadata", () => {
+ expect(runScriptTool.name).toBe("run_script");
+ expect(runScriptTool.category).toBe("build");
+ });
+
+ it("should run a script successfully", async () => {
+ vi.mocked(execa).mockResolvedValue(
+ mockExecaResult({ stdout: "Build complete", exitCode: 0 }) as any,
+ );
+
+ const result = (await runScriptTool.execute({ script: "build" })) as BuildResult;
+
+ expect(result.success).toBe(true);
+ expect(result.stdout).toBe("Build complete");
+ expect(result.exitCode).toBe(0);
+ expect(result.duration).toBeGreaterThanOrEqual(0);
+ });
+
+ it("should detect package manager from lockfile", async () => {
+ // Make pnpm-lock.yaml accessible
+ vi.mocked(fs.access).mockImplementation(async (p) => {
+ if (String(p).includes("pnpm-lock.yaml")) return;
+ throw new Error("ENOENT");
+ });
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await runScriptTool.execute({ script: "build" });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith("pnpm", ["run", "build"], expect.any(Object));
+ });
+
+ it("should use provided package manager", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await runScriptTool.execute({ script: "test", packageManager: "yarn" });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith("yarn", ["run", "test"], expect.any(Object));
+ });
+
+ it("should pass additional args", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await runScriptTool.execute({ script: "test", packageManager: "npm", args: ["--coverage"] });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith(
+ "npm",
+ ["run", "test", "--", "--coverage"],
+ expect.any(Object),
+ );
+ });
+
+ it("should handle failed scripts", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult({ exitCode: 1, stderr: "Error" }) as any);
+
+ const result = (await runScriptTool.execute({
+ script: "build",
+ packageManager: "npm",
+ })) as BuildResult;
+
+ expect(result.success).toBe(false);
+ expect(result.exitCode).toBe(1);
+ });
+
+ it("should handle timeout", async () => {
+ vi.mocked(execa).mockRejectedValue(Object.assign(new Error("timeout"), { timedOut: true }));
+
+ await expect(
+ runScriptTool.execute({ script: "build", packageManager: "npm" }),
+ ).rejects.toThrow("timed out");
+ });
+
+ it("should handle execution errors", async () => {
+ vi.mocked(execa).mockRejectedValue(new Error("Command not found"));
+
+ await expect(
+ runScriptTool.execute({ script: "build", packageManager: "npm" }),
+ ).rejects.toThrow("Failed to run script");
+ });
+
+ it("should handle non-Error thrown values", async () => {
+ vi.mocked(execa).mockRejectedValue("string error");
+
+ await expect(
+ runScriptTool.execute({ script: "build", packageManager: "npm" }),
+ ).rejects.toThrow("Failed to run script");
+ });
+
+ it("should default to npm when no lockfile found", async () => {
+ vi.mocked(fs.access).mockRejectedValue(new Error("ENOENT"));
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await runScriptTool.execute({ script: "build" });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith("npm", expect.any(Array), expect.any(Object));
+ });
+
+ it("should detect yarn from lockfile", async () => {
+ vi.mocked(fs.access).mockImplementation(async (p) => {
+ if (String(p).includes("yarn.lock")) return;
+ throw new Error("ENOENT");
+ });
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await runScriptTool.execute({ script: "build" });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith("yarn", expect.any(Array), expect.any(Object));
+ });
+
+ it("should detect bun from lockfile", async () => {
+ vi.mocked(fs.access).mockImplementation(async (p) => {
+ if (String(p).includes("bun.lockb")) return;
+ throw new Error("ENOENT");
+ });
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await runScriptTool.execute({ script: "build" });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith("bun", expect.any(Array), expect.any(Object));
+ });
+
+ it("should truncate long output", async () => {
+ const longOutput = "x".repeat(100000);
+ vi.mocked(execa).mockResolvedValue(mockExecaResult({ stdout: longOutput }) as any);
+
+ const result = (await runScriptTool.execute({
+ script: "build",
+ packageManager: "npm",
+ })) as BuildResult;
+
+ expect(result.stdout.length).toBeLessThan(longOutput.length);
+ expect(result.stdout).toContain("[Output truncated");
+ });
+ });
+
+ describe("installDepsTool", () => {
+ it("should have correct metadata", () => {
+ expect(installDepsTool.name).toBe("install_deps");
+ expect(installDepsTool.category).toBe("build");
+ });
+
+ it("should install all dependencies", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult({ stdout: "Installed" }) as any);
+
+ const result = (await installDepsTool.execute({ packageManager: "npm" })) as BuildResult;
+
+ expect(result.success).toBe(true);
+ expect(vi.mocked(execa)).toHaveBeenCalledWith("npm", ["install"], expect.any(Object));
+ });
+
+ it("should install specific packages with pnpm", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await installDepsTool.execute({ packageManager: "pnpm", packages: ["lodash", "zod"] });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith(
+ "pnpm",
+ ["add", "lodash", "zod"],
+ expect.any(Object),
+ );
+ });
+
+ it("should install dev dependencies with pnpm", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await installDepsTool.execute({ packageManager: "pnpm", packages: ["vitest"], dev: true });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith(
+ "pnpm",
+ ["add", "vitest", "-D"],
+ expect.any(Object),
+ );
+ });
+
+ it("should install with yarn", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await installDepsTool.execute({ packageManager: "yarn", packages: ["lodash"], dev: true });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith(
+ "yarn",
+ ["add", "lodash", "--dev"],
+ expect.any(Object),
+ );
+ });
+
+ it("should install with bun", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await installDepsTool.execute({ packageManager: "bun", packages: ["lodash"], dev: true });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith(
+ "bun",
+ ["add", "lodash", "--dev"],
+ expect.any(Object),
+ );
+ });
+
+ it("should install with npm and --save-dev", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await installDepsTool.execute({ packageManager: "npm", packages: ["vitest"], dev: true });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith(
+ "npm",
+ ["install", "vitest", "--save-dev"],
+ expect.any(Object),
+ );
+ });
+
+ it("should use frozen lockfile with pnpm", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await installDepsTool.execute({ packageManager: "pnpm", frozen: true });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith(
+ "pnpm",
+ ["install", "--frozen-lockfile"],
+ expect.any(Object),
+ );
+ });
+
+ it("should use frozen lockfile with yarn", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await installDepsTool.execute({ packageManager: "yarn", frozen: true });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith(
+ "yarn",
+ ["install", "--frozen-lockfile"],
+ expect.any(Object),
+ );
+ });
+
+ it("should use frozen lockfile with bun", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await installDepsTool.execute({ packageManager: "bun", frozen: true });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith(
+ "bun",
+ ["install", "--frozen-lockfile"],
+ expect.any(Object),
+ );
+ });
+
+ it("should use ci for npm frozen", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await installDepsTool.execute({ packageManager: "npm", frozen: true });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith("npm", ["ci"], expect.any(Object));
+ });
+
+ it("should handle timeout", async () => {
+ vi.mocked(execa).mockRejectedValue(Object.assign(new Error("timeout"), { timedOut: true }));
+
+ await expect(installDepsTool.execute({ packageManager: "npm" })).rejects.toThrow("timed out");
+ });
+
+ it("should handle errors", async () => {
+ vi.mocked(execa).mockRejectedValue(new Error("Network error"));
+
+ await expect(installDepsTool.execute({ packageManager: "npm" })).rejects.toThrow(
+ "Failed to install",
+ );
+ });
+ });
+
+ describe("makeTool", () => {
+ it("should have correct metadata", () => {
+ expect(makeTool.name).toBe("make");
+ expect(makeTool.category).toBe("build");
+ });
+
+ it("should run default target", async () => {
+ vi.mocked(fs.access).mockResolvedValue(undefined);
+ vi.mocked(execa).mockResolvedValue(mockExecaResult({ stdout: "Built" }) as any);
+
+ const result = (await makeTool.execute({})) as BuildResult;
+
+ expect(result.success).toBe(true);
+ expect(vi.mocked(execa)).toHaveBeenCalledWith("make", [], expect.any(Object));
+ });
+
+ it("should run specific target", async () => {
+ vi.mocked(fs.access).mockResolvedValue(undefined);
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await makeTool.execute({ target: "build" });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith("make", ["build"], expect.any(Object));
+ });
+
+ it("should split multiple targets", async () => {
+ vi.mocked(fs.access).mockResolvedValue(undefined);
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await makeTool.execute({ target: "clean build" });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith("make", ["clean", "build"], expect.any(Object));
+ });
+
+ it("should pass additional args", async () => {
+ vi.mocked(fs.access).mockResolvedValue(undefined);
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await makeTool.execute({ target: "test", args: ["VERBOSE=1"] });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith(
+ "make",
+ ["test", "VERBOSE=1"],
+ expect.any(Object),
+ );
+ });
+
+ it("should throw when no Makefile found", async () => {
+ vi.mocked(fs.access).mockRejectedValue(new Error("ENOENT"));
+
+ await expect(makeTool.execute({})).rejects.toThrow("No Makefile found");
+ });
+
+ it("should handle timeout", async () => {
+ vi.mocked(fs.access).mockResolvedValue(undefined);
+ vi.mocked(execa).mockRejectedValue(Object.assign(new Error("timeout"), { timedOut: true }));
+
+ await expect(makeTool.execute({})).rejects.toThrow("timed out");
+ });
+
+ it("should handle execution errors", async () => {
+ vi.mocked(fs.access).mockResolvedValue(undefined);
+ vi.mocked(execa).mockRejectedValue(new Error("make failed"));
+
+ await expect(makeTool.execute({})).rejects.toThrow("Make failed");
+ });
+ });
+
+ describe("tscTool", () => {
+ it("should have correct metadata", () => {
+ expect(tscTool.name).toBe("tsc");
+ expect(tscTool.category).toBe("build");
+ });
+
+ it("should run tsc with no options", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult({ stdout: "No errors" }) as any);
+
+ const result = (await tscTool.execute({})) as BuildResult;
+
+ expect(result.success).toBe(true);
+ expect(vi.mocked(execa)).toHaveBeenCalledWith("npx", ["tsc"], expect.any(Object));
+ });
+
+ it("should run with --noEmit", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await tscTool.execute({ noEmit: true });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith("npx", ["tsc", "--noEmit"], expect.any(Object));
+ });
+
+ it("should run with custom project", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await tscTool.execute({ project: "tsconfig.build.json" });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith(
+ "npx",
+ ["tsc", "--project", "tsconfig.build.json"],
+ expect.any(Object),
+ );
+ });
+
+ it("should run in watch mode", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await tscTool.execute({ watch: true });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith("npx", ["tsc", "--watch"], expect.any(Object));
+ });
+
+ it("should pass additional args", async () => {
+ vi.mocked(execa).mockResolvedValue(mockExecaResult() as any);
+
+ await tscTool.execute({ args: ["--declaration", "--emitDeclarationOnly"] });
+
+ expect(vi.mocked(execa)).toHaveBeenCalledWith(
+ "npx",
+ ["tsc", "--declaration", "--emitDeclarationOnly"],
+ expect.any(Object),
+ );
+ });
+
+ it("should handle timeout", async () => {
+ vi.mocked(execa).mockRejectedValue(Object.assign(new Error("timeout"), { timedOut: true }));
+
+ await expect(tscTool.execute({})).rejects.toThrow("timed out");
+ });
+
+ it("should handle errors", async () => {
+ vi.mocked(execa).mockRejectedValue(new Error("tsc not found"));
+
+ await expect(tscTool.execute({})).rejects.toThrow("TypeScript compile failed");
+ });
+ });
+});
diff --git a/src/tools/file.ts b/src/tools/file.ts
index 9cf82bc..cc94455 100644
--- a/src/tools/file.ts
+++ b/src/tools/file.ts
@@ -9,6 +9,7 @@ import path from "node:path";
import { glob } from "glob";
import { defineTool, type ToolDefinition } from "./registry.js";
import { FileSystemError, ToolError } from "../utils/errors.js";
+import { isWithinAllowedPath } from "./allowed-paths.js";
/**
* Sensitive file patterns that should be protected
@@ -50,6 +51,7 @@ function hasNullByte(str: string): boolean {
*/
function normalizePath(filePath: string): string {
// Remove null bytes
+ // oxlint-disable-next-line no-control-regex -- Intentional: sanitizing null bytes from file paths
let normalized = filePath.replace(/\0/g, "");
// Normalize path separators and resolve .. and .
normalized = path.normalize(normalized);
@@ -81,27 +83,32 @@ function isPathAllowed(
}
}
- // Check home directory access (only allow within project)
+ // Check home directory access (only allow within project or explicitly allowed paths)
const home = process.env.HOME;
if (home) {
const normalizedHome = path.normalize(home);
const normalizedCwd = path.normalize(cwd);
if (absolute.startsWith(normalizedHome) && !absolute.startsWith(normalizedCwd)) {
- // Allow reading common config files in home (but NOT sensitive ones)
- if (operation === "read") {
+ // Check if path is within user-authorized allowed paths
+ if (isWithinAllowedPath(absolute, operation)) {
+ // Path is explicitly authorized — continue to sensitive file checks below
+ } else if (operation === "read") {
+ // Allow reading common config files in home (but NOT sensitive ones)
const allowedHomeReads = [".gitconfig", ".zshrc", ".bashrc"];
const basename = path.basename(absolute);
// Block .npmrc, .pypirc as they may contain auth tokens
if (!allowedHomeReads.includes(basename)) {
+ const targetDir = path.dirname(absolute);
return {
allowed: false,
- reason: "Reading files outside project directory is not allowed",
+ reason: `Reading files outside project directory is not allowed. Use /allow-path ${targetDir} to grant access.`,
};
}
} else {
+ const targetDir = path.dirname(absolute);
return {
allowed: false,
- reason: `${operation} operations outside project directory are not allowed`,
+ reason: `${operation} operations outside project directory are not allowed. Use /allow-path ${targetDir} to grant access.`,
};
}
}
diff --git a/src/tools/http.ts b/src/tools/http.ts
index dcaf05a..7e39953 100644
--- a/src/tools/http.ts
+++ b/src/tools/http.ts
@@ -81,6 +81,7 @@ Examples:
"User-Agent": "Corbat-Coco/0.1.0",
...headers,
},
+ // oxlint-disable-next-line unicorn/no-invalid-fetch-options -- Body is conditionally set only for non-GET methods
body: method && ["POST", "PUT", "PATCH"].includes(method) ? body : undefined,
signal: controller.signal,
});
diff --git a/src/tools/search.ts b/src/tools/search.ts
index 35e11f8..6fd46a2 100644
--- a/src/tools/search.ts
+++ b/src/tools/search.ts
@@ -213,7 +213,7 @@ export const findInFileTool: ToolDefinition<
Examples:
- Find text: { "file": "src/app.ts", "pattern": "export" }
- Case insensitive: { "file": "README.md", "pattern": "install", "caseSensitive": false }
-- Regex: { "file": "package.json", "pattern": "\"version\":\\s*\"[^\"]+\"" }`,
+- Regex: { "file": "package.json", "pattern": '"version":\\s*"[^"]+"' }`,
category: "file",
parameters: z.object({
file: z.string().describe("File path to search"),
diff --git a/src/utils/async.ts b/src/utils/async.ts
index 6afa143..3842655 100644
--- a/src/utils/async.ts
+++ b/src/utils/async.ts
@@ -139,7 +139,7 @@ export async function parallel(
fn: (item: T, index: number) => Promise,
concurrency: number = 5,
): Promise {
- const results: R[] = new Array(items.length);
+ const results: R[] = Array.from({ length: items.length });
const executing = new Map>();
let nextId = 0;
diff --git a/vitest.config.ts b/vitest.config.ts
index 7befd42..1e90303 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -10,7 +10,12 @@ export default defineConfig({
provider: "v8",
reporter: ["text", "lcov", "html"],
include: ["src/**/*.ts"],
- exclude: ["src/**/*.test.ts", "src/**/*.d.ts"],
+ exclude: [
+ "src/**/*.test.ts",
+ "src/**/*.d.ts",
+ "src/types/**", // Pure type definitions, no runtime code
+ "src/cli/repl/onboarding-v2.ts", // Interactive UI, requires manual testing
+ ],
thresholds: {
// Phase 2 audit: stepping toward 80%+ target
lines: 72,