@hsupu/copilot-api 0.8.0 → 0.8.1-beta.1

package/README.md

@@ -4,111 +4,180 @@
 > This is a fork of [ericc-ch/copilot-api](https://github.com/ericc-ch/copilot-api) with additional improvements and bug fixes.
 
 > [!WARNING]
-> This is a reverse-engineered proxy of GitHub Copilot API. It is not supported by GitHub, and may break unexpectedly. Use at your own risk.
+> This is a reverse proxy for the GitHub Copilot API. It is not officially supported by GitHub and may break at any time. Use at your own risk.
 
-## Fork Improvements
+A reverse proxy that exposes GitHub Copilot's API as standard OpenAI and Anthropic compatible endpoints. Works with Claude Code, Cursor, and other tools that speak these protocols.
 
-This fork includes the following enhancements over the upstream project:
-
-### New Features
-
-- **`--host` option**: Bind the server to a specific network interface (e.g., `--host 0.0.0.0` for all interfaces, `--host 127.0.0.1` for localhost only)
-- **Queue-based rate limiting**: Requests are queued and processed sequentially with configurable delays, instead of being rejected when rate limited
-- **`/v1/event_logging/batch` endpoint**: Compatibility endpoint for Anthropic SDK's event logging (returns OK without processing)
-- **`logout` command**: Remove stored GitHub token with `copilot-api logout`
-- **Tool name length handling**: Automatically truncates long tool names (>64 chars) to comply with OpenAI's limit, with hash-based suffix to avoid collisions. Original names are restored in responses.
-- **Request History UI**: Optional built-in Web UI (`--history`) to view, search, filter, and export all API requests/responses. Access at `/history` when enabled.
+## Quick Start
 
-### Bug Fixes
+### Install from npm (Recommended)
 
-- **Fixed missing `model` field in streaming**: The first streaming chunk from Copilot API sometimes has an empty `choices` array but contains the model name. We now store this for use in subsequent events.
-- **Auto-fix message sequence errors**: When tool calls are interrupted (e.g., by user cancel), the API now automatically adds placeholder `tool_result` blocks to maintain valid message sequences
-- **Fixed `bunx` symlink issue**: Changed pre-commit hook to use `bun x` instead of `bunx` for better compatibility
+```sh
+npx -y @hsupu/copilot-api start
+```
 
-### Documentation
+### Run from Source
 
-- Added [CLAUDE.md](./CLAUDE.md) with project architecture documentation
+```sh
+git clone https://github.com/puxu-msft/copilot-api-js.git
+cd copilot-api-js
+bun install
+bun run dev      # Development mode with hot reload
+bun run start    # Production mode
+bun run build    # Build for distribution
+
+# Testing
+bun test                   # Backend unit tests
+bun run test:all           # All backend tests
+bun run test:ui            # Frontend (History UI) tests
+bun run typecheck          # TypeScript type checking
+```
 
-## Quick Start
+## Using with Claude Code
 
-### Install from npm (Recommended)
+Run the interactive setup command:
 
 ```sh
-# Run directly with npx
-npx @hsupu/copilot-api start
+copilot-api setup-claude-code
+```
 
-# Or install globally
-npm install -g @hsupu/copilot-api
-copilot-api start
+Or manually create `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://localhost:4141",
+    "ANTHROPIC_AUTH_TOKEN": "dummy",
+    "ANTHROPIC_MODEL": "opus",
+    "ANTHROPIC_SMALL_FAST_MODEL": "haiku",
+    "DISABLE_NON_ESSENTIAL_MODEL_CALLS": "1",
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
+  }
+}
 ```
 
-### Install from GitHub
+## Features
 
-You can also install directly from GitHub (requires build step):
+### Dual API Compatibility
 
-```sh
-npm install -g github:puxu-msft/copilot-api-js
-copilot-api start
-```
+Exposes both OpenAI and Anthropic compatible endpoints through a single proxy:
 
-### Running from Source
+- **Direct Anthropic path** — Uses Copilot API's native Anthropic endpoint for Claude models
+- **OpenAI-compatible path** — Forwards OpenAI Chat Completions, Responses, Embeddings, and Models requests to Copilot's OpenAI endpoints
 
-```sh
-# Clone the repository
-git clone https://github.com/puxu-msft/copilot-api-js.git
-cd copilot-api-js
+### Auto-Truncate
 
-# Install dependencies
-bun install
+Automatically handles context length limits (enabled by default):
 
-# Development mode (with hot reload)
-bun run dev
+- **Reactive** — Retries failed requests with a truncated payload when hitting token or byte limits
+- **Proactive** — Pre-checks requests against known model limits before sending
+- **Dynamic limit learning** — Adjusts limits based on actual API error responses
+- **Tool result compression** — Compresses old `tool_result` content before truncating messages
 
-# Production mode
-bun run start
+### Message Sanitization
 
-# Build for distribution
-bun run build
-```
+Cleans up messages before forwarding to the API:
 
-### After Building
+- Filters orphaned `tool_use` / `tool_result` blocks (unpaired due to interrupted tool calls or truncation)
+- Fixes tool name casing mismatches
+- Removes empty text content blocks
+- Strips `<system-reminder>` tags from message content
+- **[Optional]** Deduplicates repeated tool calls (`config.yaml: anthropic.dedup_tool_calls`)
+- **[Optional]** Strips system-reminder tags from Read tool results (`config.yaml: anthropic.truncate_read_tool_result`)
 
-```sh
-# Run the built version locally
-npx .
+### Model Name Translation
 
-# Or link globally
-bun link
-copilot-api start
-```
+Translates client-sent model names to matching Copilot models:
+
+| Input | Resolved To |
+|-------|-------------|
+| `opus`, `sonnet`, `haiku` | Best available model in that family |
+| `claude-opus-4-6` | `claude-opus-4.6` |
+| `claude-sonnet-4-6-20250514` | `claude-sonnet-4.6` |
+| `claude-opus-4-6-fast`, `opus[1m]` | `claude-opus-4.6-fast`, `claude-opus-4.6-1m` |
+| `claude-sonnet-4`, `gpt-4` | Passed through directly |
+
+User-configured `model_overrides` (via config.yaml) can redirect any model name to another, with chained resolution and family-level overrides.
+
+### Server-Side Tools
+
+Supports Anthropic server-side tools (`web_search`, `tool_search`). These tools are executed by the API backend, with both `server_tool_use` and result blocks appearing inline in assistant messages. Tool definitions can optionally be rewritten to a custom format (`--no-rewrite-anthropic-tools`).
+
+### Request History UI
+
+Built-in web interface for inspecting API requests and responses. Access at `http://localhost:4141/history/v3/`.
 
-## Command Reference
+- Real-time updates via WebSocket
+- Filter by model, endpoint, status, and time range
+- Session tracking and statistics
+
+### Additional Features
+
+- **Model overrides** — Configure arbitrary model name redirections via config.yaml
+- **Adaptive rate limiting** — Intelligent rate limiting with exponential backoff (3 modes: Normal, Rate-limited, Recovering)
+- **Tool name truncation** — Truncates tool names exceeding 64 characters (OpenAI limit) with hash suffixes
+- **Health checks** — Container-ready endpoint at `/health`
+- **Graceful shutdown** — Connection draining on shutdown signals
+- **Proxy support** — HTTP/HTTPS proxy via environment variables
+
+## Commands
 
 | Command | Description |
 |---------|-------------|
-| `start` | Start the API server (handles auth if needed) |
+| `start` | Start the API server (authenticates automatically if needed) |
 | `auth` | Run GitHub authentication flow only |
 | `logout` | Remove stored GitHub token |
-| `check-usage` | Show Copilot usage and quota |
-| `debug` | Display diagnostic information |
-
-### Start Command Options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `--port`, `-p` | Port to listen on | 4141 |
-| `--host` | Host/interface to bind to | (all interfaces) |
-| `--verbose`, `-v` | Enable verbose logging | false |
-| `--account-type`, `-a` | Account type (individual, business, enterprise) | individual |
-| `--rate-limit`, `-r` | Seconds between requests (uses queue) | none |
-| `--wait`, `-w` | Wait in queue instead of rejecting | false |
-| `--github-token`, `-g` | Provide GitHub token directly | none |
-| `--claude-code`, `-c` | Generate Claude Code launch command | false |
-| `--show-token` | Show tokens on fetch/refresh | false |
-| `--manual` | Manual request approval mode | false |
-| `--proxy-env` | Use proxy from environment | false |
-| `--history` | Enable request history UI at `/history` | false |
-| `--history-limit` | Max history entries in memory | 1000 |
+| `check-usage` | Show Copilot usage and quota information |
+| `debug info` | Display diagnostic information |
+| `debug models` | Fetch and display raw model data from Copilot API |
+| `list-claude-code` | List all locally installed Claude Code versions |
+| `setup-claude-code` | Interactively configure Claude Code to use this proxy |
+
+### `start` Options
+
+**General:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--port`, `-p` | 4141 | Port to listen on |
+| `--host`, `-H` | (all interfaces) | Host/interface to bind to |
+| `--verbose`, `-v` | false | Enable verbose logging |
+| `--account-type`, `-a` | individual | Account type: `individual`, `business`, or `enterprise` |
+| `--github-token`, `-g` | | Provide GitHub token directly |
+| `--no-http-proxy-from-env` | enabled | Disable HTTP proxy from environment variables |
+
+**Auto-Truncate:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--no-auto-truncate` | enabled | Disable auto-truncation on context limit errors |
+
+**Anthropic-Specific (via config.yaml):**
+
+These options are configured in `config.yaml` under the `anthropic:` section. See [`config.example.yaml`](config.example.yaml).
+
+| Config Key | Default | Description |
+|------------|---------|-------------|
+| `anthropic.rewrite_tools` | true | Rewrite server-side tools to custom format |
+| `stream_idle_timeout` | 300 | Max seconds between SSE events (0 = no timeout) |
+
+**Sanitization:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--collect-system-prompts` | false | Collect system prompts to file |
+
+**Rate Limiting:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--no-rate-limit` | enabled | Disable adaptive rate limiting |
+
+Rate limiter sub-parameters are configured in `config.yaml` under `rate_limiter:`. See [`config.example.yaml`](config.example.yaml).
+
+## Configuration
+
+Create a `config.yaml` in the working directory. See [`config.example.yaml`](config.example.yaml) for all available options.
 
 ## API Endpoints
 
@@ -117,52 +186,45 @@ copilot-api start
 | Endpoint | Method | Description |
 |----------|--------|-------------|
 | `/v1/chat/completions` | POST | Chat completions |
+| `/v1/responses` | POST | Responses API |
 | `/v1/models` | GET | List available models |
+| `/v1/models/:model` | GET | Get specific model details |
 | `/v1/embeddings` | POST | Text embeddings |
 
+All endpoints also work without the `/v1` prefix.
+
 ### Anthropic Compatible
 
 | Endpoint | Method | Description |
 |----------|--------|-------------|
 | `/v1/messages` | POST | Messages API |
 | `/v1/messages/count_tokens` | POST | Token counting |
-| `/v1/event_logging/batch` | POST | Event logging (no-op) |
 
 ### Utility
 
 | Endpoint | Method | Description |
 |----------|--------|-------------|
-| `/usage` | GET | Copilot usage stats |
-| `/token` | GET | Current Copilot token |
-| `/history` | GET | Request history Web UI (requires `--history`) |
-| `/history/api/*` | GET/DELETE | History API endpoints |
-
-## Using with Claude Code
-
-Create `.claude/settings.json` in your project:
-
-```json
-{
-  "env": {
-    "ANTHROPIC_BASE_URL": "http://localhost:4141",
-    "ANTHROPIC_AUTH_TOKEN": "dummy",
-    "ANTHROPIC_MODEL": "gpt-4.1",
-    "ANTHROPIC_SMALL_FAST_MODEL": "gpt-4.1",
-    "DISABLE_NON_ESSENTIAL_MODEL_CALLS": "1",
-    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
-  },
-  "permissions": {
-    "deny": ["WebSearch"]
-  }
-}
-```
-
-Or use the interactive setup:
-
-```sh
-bun run start --claude-code
-```
-
-## Upstream Project
-
-For the original project documentation, features, and updates, see: [ericc-ch/copilot-api](https://github.com/ericc-ch/copilot-api)
+| `/health` | GET | Health check (200 healthy, 503 unhealthy) |
+| `/usage` | GET | Copilot usage and quota statistics |
+| `/token` | GET | Current Copilot token information |
+| `/history/v3/` | GET | History web UI |
+| `/history/ws` | WebSocket | Real-time history updates |
+| `/history/api/entries` | GET | Query history entries |
+| `/history/api/entries/:id` | GET | Get single entry |
+| `/history/api/summaries` | GET | Entry summaries |
+| `/history/api/stats` | GET | Usage statistics |
+| `/history/api/sessions` | GET | List sessions |
+
+## Account Types
+
+The account type determines the Copilot API base URL:
+
+| Type | API Base URL |
+|------|-------------|
+| `individual` | `api.githubcopilot.com` |
+| `business` | `api.business.githubcopilot.com` |
+| `enterprise` | `api.enterprise.githubcopilot.com` |
+
+## License
+
+[MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,39 @@
+
+## 项目概述
+
+GitHub Copilot API 的逆向代理，将其暴露为 OpenAI 和 Anthropic 兼容端点。使得 Claude Code 等工具可以使用 GitHub Copilot 作为后端。
+
+## 常用命令
+
+```sh
+bun install              # 安装依赖
+bun run dev              # 开发模式（热重载）
+bun run start            # 生产模式
+bun run build            # 构建发布版（tsdown）
+bun run typecheck        # 类型检查
+bun run lint             # Lint 暂存文件
+bun run lint:all         # Lint 所有文件
+bun run knip             # 查找未使用的导出/依赖
+bun test                 # 运行所有测试
+bun test tests/foo.test.ts  # 运行单个测试文件
+```
+
+## API 端点
+
+| 端点 | 用途 |
+|------|------|
+| `/v1/chat/completions` | OpenAI 兼容 chat |
+| `/v1/messages` | Anthropic 兼容 messages |
+| `/v1/messages/count_tokens` | Anthropic 兼容 token 计数 |
+| `/v1/models` | 列出可用模型 |
+| `/v1/embeddings` | 文本嵌入 |
+| `/api/event_logging/batch` | Event logging（空操作） |
+| `/usage` | Copilot 配额/用量统计 |
+| `/health` | 健康检查 |
+| `/token` | 当前 Copilot token 信息 |
+| `/history` | 请求历史 Web UI（v1 和 v2） |
+| `/history/ws` | WebSocket 实时历史更新 |
+| `/history/api/entries` | 历史查询 API |
+| `/history/api/sessions` | 会话列表 API |
+| `/history/api/stats` | 统计 API |
+| `/history/api/export` | 导出历史（JSON/CSV） |