feat: default to CommandCode Provider API with dynamic model catalog

- Chat now calls the official POST /provider/v1/chat/completions with
  native OpenAI bodies (COMMANDCODE_UPSTREAM_MODE=provider default);
  Claude models and legacy mode keep the /alpha/generate tunnel
- Dynamic model catalog refreshed from public /provider/v1/models at
  startup, filling the five unpublished context windows with live values
- Credential env name compatibility (COMMAND_CODE_API_KEY, CMD_API_KEY)
  and COMMANDCODE_ZDR -> x-cmd-zdr: 1 zero-data-retention header
- Billing, routing, and balance alerts stay on /alpha with no CLI
- Dashboard shows the summed current balance next to credentials
- Version scheme now tracks the CommandCode CLI version with a letter
  suffix (1.14.0.a)

Author: yelixir-dev

.env.example

@@ -1,8 +1,13 @@
 # CommandCode upstream
+# Default COMMANDCODE_UPSTREAM_MODE=provider calls the official Provider API
+# (POST /provider/v1/chat/completions) for non-Claude models. Claude models and
+# COMMANDCODE_UPSTREAM_MODE=alpha use the legacy /alpha/generate tunnel.
+COMMANDCODE_UPSTREAM_MODE=provider
 # Single-key mode: set this explicitly in production.
-# If omitted, the bridge reads ~/.commandcode/auth.json.
+# Recognized names in order: COMMAND_CODE_API_KEY, COMMANDCODE_API_KEY, CMD_API_KEY.
+# If omitted, the bridge also reads ~/.commandcode/auth.json.
 COMMANDCODE_API_KEY=
-# Multi-key mode (optional): id=key pairs. Takes precedence over COMMANDCODE_API_KEY.
+# Multi-key mode (optional): id=key pairs. Takes precedence over the single key.
 # COMMANDCODE_API_KEYS=primary=cmd_key_one,secondary=cmd_key_two
 # Or point to a JSON file: {"credentials":[{"id":"primary","apiKey":"...","weight":1}]}
 COMMANDCODE_CREDENTIALS_FILE=
@@ -18,6 +23,8 @@ COMMANDCODE_ALLOW_UNKNOWN_MODELS=false
 COMMANDCODE_CLI_VERSION=1.14.0
 COMMANDCODE_TIMEOUT_MS=300000
 COMMANDCODE_EMPTY_VISIBLE_RESPONSE_POLICY=error_on_length
+# Send x-cmd-zdr: 1 (zero data retention) on Provider API requests.
+COMMANDCODE_ZDR=false
 
 # Balance alerts are opt-in and disabled by default. When enabled, alerts are logged
 # and optionally POSTed to COMMANDCODE_BALANCE_ALERT_WEBHOOK_URL.

.gitignore

@@ -12,3 +12,7 @@ release/env.production
 *.tgz
 .DS_Store
 npm-debug.log*
+.commandcode/
+.omo/
+.senpi/
+.tmp/

README.ko.md

@@ -17,17 +17,20 @@ CommandCode Bridge
   ├─ model alias/allowlist resolver
   ├─ CommandCode credential router
   ├─ CommandCode billing/usage snapshot cache
-  ├─ OpenAI → CommandCode converter
+  ├─ Provider API client (native OpenAI, default)
+  ├─ CommandCode /alpha client (Claude + legacy mode)
+  ├─ OpenAI → CommandCode converter (alpha path only)
   ├─ CommandCode upstream HTTP client
-  ├─ CommandCode stream parser
-  └─ CommandCode → OpenAI response converter
+  ├─ CommandCode stream parser (alpha path only)
+  └─ CommandCode → OpenAI response converter (alpha path only)
         │
         ▼
 CommandCode API
-  └─ POST /alpha/generate
+  ├─ POST /provider/v1/chat/completions  (Provider API, non-Claude)
+  └─ POST /alpha/generate                (Claude + alpha mode)
         │
         ▼
-DeepSeek V4 Pro
+DeepSeek V4 Pro / Flash etc.
 ```
 
 ## Request Flow
@@ -65,15 +68,18 @@ DeepSeek V4 Pro
 
 ## Upstream Compatibility
 
-CommandCode's `/alpha/generate` requires `params.stream: true`. The bridge therefore always calls upstream streaming, even for OpenAI non-streaming clients.
+Provider mode (default) calls the official `POST /provider/v1/chat/completions` with a native OpenAI body and streams the provider's OpenAI SSE through with the public model id; `stream: false` requests are answered with a single JSON completion. Claude model ids are served through `POST /alpha/generate` because the Provider API exposes Claude only via the Anthropic `/messages` format. Legacy `alpha` mode keeps the old tunnel: `/alpha/generate` requires `params.stream: true`, so the bridge always calls upstream streaming there, even for OpenAI non-streaming clients.
+
+The Provider API emits token usage in the final chunk with no opt-in required; `x-cmd-zdr: 1` is sent when `COMMANDCODE_ZDR` is enabled. Billing and usage snapshots (`/alpha/whoami`, `/alpha/billing/*`, `/alpha/usage/summary`) are shared by both modes and remain the routing and balance-alert data source.
 
 ## Error Strategy
 
 - Invalid OpenAI request → HTTP 400 OpenAI-style error.
 - Disallowed model → HTTP 400 OpenAI-style error.
 - Missing upstream API key → HTTP 500 configuration error.
-- CommandCode HTTP failure → HTTP 502 with upstream status and sanitized body; selected credential cooldown/disable rules are applied.
-- CommandCode stream `error` event → fail over first if no visible output has been emitted and another credential is available; otherwise map to HTTP 502 or SSE error frame plus `[DONE]`.
+- Provider API HTTP failure → upstream status and OpenAI-style error body forwarded (for example `403 upgrade_required` or `429 rate_limit_error`); credential cooldown/disable rules are applied.
+- `/alpha` HTTP failure → HTTP 502 with upstream status and sanitized body.
+- `/alpha` stream `error` event → fail over first if no visible output has been emitted and another credential is available; otherwise map to HTTP 502 or SSE error frame plus `[DONE]`.
 - No available upstream credential → HTTP 503 OpenAI-style upstream error.
 - Unknown server failure → HTTP 500 generic error.
 

README.md

@@ -388,18 +388,20 @@ npm run smoke
 
 ### CommandCode upstream 옵션
 
-| 변수                               | 기본값                       | 설명                                                                                                                     |
-| ---------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `COMMANDCODE_API_KEY`              | 미설정                       | single upstream CommandCode API key입니다. 비워두면 일반 CommandCode auth file을 읽을 수 있습니다.                       |
-| `COMMANDCODE_API_KEYS`             | 미설정                       | multi-key용 comma-separated `id=key` 목록입니다. 예: `primary=...,secondary=...`. single-key보다 우선합니다.             |
-| `COMMANDCODE_CREDENTIALS`          | 미설정                       | JSON credential 배열/객체 또는 comma-separated multi-key 목록입니다. 구조화된 배포 시스템에서 유용합니다.                |
-| `COMMANDCODE_CREDENTIALS_FILE`     | 미설정                       | JSON credentials 파일 경로입니다. upstream credential source 중 최우선입니다. 복잡한 multi-key에는 이 방식을 권장합니다. |
-| `COMMANDCODE_API_BASE`             | `https://api.commandcode.ai` | upstream CommandCode API base URL입니다. 테스트나 upstream 변경 대응 외에는 바꾸지 마십시오.                             |
-| `COMMANDCODE_DEFAULT_MODEL`        | `deepseek/deepseek-v4-pro`   | `model: "default"` 요청이 실제로 사용할 upstream model입니다.                                                            |
-| `COMMANDCODE_ALLOWED_MODELS`       | Pro + Flash                  | 허용할 model ID 목록입니다. 이 목록 밖 요청은 unknown model 허용 옵션을 켜지 않는 한 거부됩니다.                         |
-| `COMMANDCODE_ALLOW_UNKNOWN_MODELS` | `false`                      | 임의 model ID를 upstream으로 통과시킵니다. 운영에서는 권장하지 않습니다.                                                 |
-| `COMMANDCODE_CLI_VERSION`          | `1.14.0`                     | 테스트된 CommandCode CLI 동작과 맞추기 위해 upstream에 보내는 version header입니다.                                      |
-| `COMMANDCODE_TIMEOUT_MS`           | `300000`                     | upstream generation timeout입니다.                                                                                       |
+| 변수                               | 기본값                       | 설명                                                                                                                                                             |
+| ---------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `COMMANDCODE_API_KEY`              | 미설정                       | single upstream CommandCode API key입니다. `COMMAND_CODE_API_KEY`, `CMD_API_KEY`도 인식합니다. 비워두면 일반 CommandCode auth file을 읽을 수 있습니다.           |
+| `COMMANDCODE_API_KEYS`             | 미설정                       | multi-key용 comma-separated `id=key` 목록입니다. 예: `primary=...,secondary=...`. single-key보다 우선합니다.                                                     |
+| `COMMANDCODE_CREDENTIALS`          | 미설정                       | JSON credential 배열/객체 또는 comma-separated multi-key 목록입니다. 구조화된 배포 시스템에서 유용합니다.                                                        |
+| `COMMANDCODE_CREDENTIALS_FILE`     | 미설정                       | JSON credentials 파일 경로입니다. upstream credential source 중 최우선입니다. 복잡한 multi-key에는 이 방식을 권장합니다.                                         |
+| `COMMANDCODE_UPSTREAM_MODE`        | `provider`                   | `provider`는 비-Claude 모델을 공식 Provider API(`/provider/v1/chat/completions`)로 호출합니다. `alpha`는 모든 모델을 legacy `/alpha/generate` 터널로 강제합니다. |
+| `COMMANDCODE_ZDR`                  | `false`                      | Provider API 요청에 `x-cmd-zdr: 1`(zero data retention)을 보냅니다.                                                                                              |
+| `COMMANDCODE_API_BASE`             | `https://api.commandcode.ai` | upstream CommandCode API base URL입니다. 테스트나 upstream 변경 대응 외에는 바꾸지 마십시오.                                                                     |
+| `COMMANDCODE_DEFAULT_MODEL`        | `deepseek/deepseek-v4-pro`   | `model: "default"` 요청이 실제로 사용할 upstream model입니다.                                                                                                    |
+| `COMMANDCODE_ALLOWED_MODELS`       | Pro + Flash                  | 허용할 model ID 목록입니다. 이 목록 밖 요청은 unknown model 허용 옵션을 켜지 않는 한 거부됩니다.                                                                 |
+| `COMMANDCODE_ALLOW_UNKNOWN_MODELS` | `false`                      | 임의 model ID를 upstream으로 통과시킵니다. 운영에서는 권장하지 않습니다.                                                                                         |
+| `COMMANDCODE_CLI_VERSION`          | `1.14.0`                     | 테스트된 CommandCode CLI 동작과 맞추기 위해 upstream에 보내는 version header입니다.                                                                              |
+| `COMMANDCODE_TIMEOUT_MS`           | `300000`                     | upstream generation timeout입니다.                                                                                                                               |
 
 Credential JSON 파일 예시:
 

README.zh.md

@@ -389,18 +389,20 @@ npm run smoke
 
 ### CommandCode upstream options
 
-| Variable                           | Default                      | Description                                                                                                              |
-| ---------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `COMMANDCODE_API_KEY`              | unset                        | Single upstream CommandCode API key. If unset, the bridge can read the normal CommandCode auth file.                     |
-| `COMMANDCODE_API_KEYS`             | unset                        | Comma-separated multi-key `id=key` list, for example `primary=...,secondary=...`. Takes precedence over single-key mode. |
-| `COMMANDCODE_CREDENTIALS`          | unset                        | JSON credential array/object or comma-separated multi-key list. Useful for structured deployment systems.                |
-| `COMMANDCODE_CREDENTIALS_FILE`     | unset                        | Path to a JSON credentials file. Highest upstream credential precedence. Recommended for complex multi-key setups.       |
-| `COMMANDCODE_API_BASE`             | `https://api.commandcode.ai` | Upstream CommandCode API base URL. Change only for testing or if CommandCode changes endpoint base.                      |
-| `COMMANDCODE_DEFAULT_MODEL`        | `deepseek/deepseek-v4-pro`   | Upstream model used by `model: "default"`.                                                                               |
-| `COMMANDCODE_ALLOWED_MODELS`       | Pro + Flash                  | Comma-separated allowlist. Requests outside this list are rejected unless unknown models are allowed.                    |
-| `COMMANDCODE_ALLOW_UNKNOWN_MODELS` | `false`                      | Allows arbitrary model IDs to pass through. Not recommended for production.                                              |
-| `COMMANDCODE_CLI_VERSION`          | `1.14.0`                     | Version header sent upstream to match the tested CommandCode CLI behavior.                                               |
-| `COMMANDCODE_TIMEOUT_MS`           | `300000`                     | Upstream generation timeout.                                                                                             |
+| Variable                           | Default                      | Description                                                                                                                                                  |
+| ---------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `COMMANDCODE_API_KEY`              | unset                        | Single upstream CommandCode API key. Also recognized: `COMMAND_CODE_API_KEY`, `CMD_API_KEY`. If unset, the bridge can read the normal CommandCode auth file. |
+| `COMMANDCODE_API_KEYS`             | unset                        | Comma-separated multi-key `id=key` list, for example `primary=...,secondary=...`. Takes precedence over single-key mode.                                     |
+| `COMMANDCODE_CREDENTIALS`          | unset                        | JSON credential array/object or comma-separated multi-key list. Useful for structured deployment systems.                                                    |
+| `COMMANDCODE_CREDENTIALS_FILE`     | unset                        | Path to a JSON credentials file. Highest upstream credential precedence. Recommended for complex multi-key setups.                                           |
+| `COMMANDCODE_UPSTREAM_MODE`        | `provider`                   | `provider` calls the official Provider API for non-Claude models; `alpha` forces the legacy `/alpha/generate` tunnel for every model.                        |
+| `COMMANDCODE_ZDR`                  | `false`                      | Sends `x-cmd-zdr: 1` (zero data retention) on Provider API requests.                                                                                         |
+| `COMMANDCODE_API_BASE`             | `https://api.commandcode.ai` | Upstream CommandCode API base URL. Change only for testing or if CommandCode changes endpoint base.                                                          |
+| `COMMANDCODE_DEFAULT_MODEL`        | `deepseek/deepseek-v4-pro`   | Upstream model used by `model: "default"`.                                                                                                                   |
+| `COMMANDCODE_ALLOWED_MODELS`       | Pro + Flash                  | Comma-separated allowlist. Requests outside this list are rejected unless unknown models are allowed.                                                        |
+| `COMMANDCODE_ALLOW_UNKNOWN_MODELS` | `false`                      | Allows arbitrary model IDs to pass through. Not recommended for production.                                                                                  |
+| `COMMANDCODE_CLI_VERSION`          | `1.14.0`                     | Version header sent upstream to match the tested CommandCode CLI behavior.                                                                                   |
+| `COMMANDCODE_TIMEOUT_MS`           | `300000`                     | Upstream generation timeout.                                                                                                                                 |
 
 Credential file shape:
 

docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # CommandCode Bridge PRD
 
-> Product Requirement Document for an OpenAI-compatible HTTP proxy over CommandCode's `/alpha/generate` endpoint.
+> Product Requirement Document for an OpenAI-compatible HTTP proxy over CommandCode's official Provider API (`/provider/v1`), with the legacy `/alpha/generate` tunnel retained for Claude models and billing.
 
 ## Mission
 

docs/DEPLOYMENT.ko.md

@@ -1,6 +1,6 @@
 {
   "name": "commandcode-bridge",
-  "version": "1.14.0",
+  "version": "1.14.0.a",
   "description": "OpenAI-compatible HTTP bridge for CommandCode's DeepSeek V4 Pro API path.",
   "type": "module",
   "license": "MIT",