feat(anthropic): Track A core protocol parity for /claude messages

.env.example

@@ -9,6 +9,39 @@ CODEX_LB_DATABASE_SQLITE_PRE_MIGRATE_BACKUP_MAX_FILES=5
 # Upstream ChatGPT base URL (no /codex suffix)
 CODEX_LB_UPSTREAM_BASE_URL=https://chatgpt.com/backend-api
 
+# Anthropic SDK runtime
+# Optional explicit Claude CLI path when auto-discovery via PATH is not enough
+# CODEX_LB_ANTHROPIC_SDK_CLI_PATH=/usr/local/bin/claude
+# Optional default session ID for SDK conversation continuity
+# CODEX_LB_ANTHROPIC_SDK_DEFAULT_SESSION_ID=codex-lb-default
+
+# Anthropic direct API runtime (/claude/v1/messages)
+CODEX_LB_ANTHROPIC_API_BASE_URL=https://api.anthropic.com
+CODEX_LB_ANTHROPIC_API_VERSION=2023-06-01
+# CODEX_LB_ANTHROPIC_API_BETA=
+CODEX_LB_ANTHROPIC_API_TIMEOUT_SECONDS=300
+CODEX_LB_ANTHROPIC_API_DETECT_CLI_HEADERS=true
+CODEX_LB_ANTHROPIC_API_SYSTEM_PROMPT_INJECTION_MODE=minimal
+CODEX_LB_ANTHROPIC_OAUTH_TOKEN_URL=https://console.anthropic.com/v1/oauth/token
+CODEX_LB_ANTHROPIC_OAUTH_CLIENT_ID=9d1c250a-e61b-44d9-88ed-5944d1962f5e
+
+# Anthropic usage (5h/7d)
+CODEX_LB_ANTHROPIC_USAGE_BASE_URL=https://api.anthropic.com
+CODEX_LB_ANTHROPIC_USAGE_BETA=oauth-2025-04-20
+CODEX_LB_ANTHROPIC_USAGE_REFRESH_ENABLED=true
+
+# Anthropic auth discovery (Linux-only POC)
+CODEX_LB_ANTHROPIC_CREDENTIALS_DISCOVERY_ENABLED=true
+# CODEX_LB_ANTHROPIC_CREDENTIALS_FILE=~/.claude/.credentials.json
+# CODEX_LB_ANTHROPIC_CREDENTIALS_HELPER_COMMAND=
+# Explicit override (if set, used before discovery)
+# CODEX_LB_ANTHROPIC_USAGE_BEARER_TOKEN=sk-ant-oat01-...
+CODEX_LB_ANTHROPIC_AUTO_DISCOVER_ORG=false
+CODEX_LB_ANTHROPIC_CREDENTIALS_CACHE_SECONDS=60
+CODEX_LB_ANTHROPIC_DEFAULT_ACCOUNT_ID=anthropic_default
+CODEX_LB_ANTHROPIC_DEFAULT_ACCOUNT_EMAIL=anthropic@local
+CODEX_LB_ANTHROPIC_DEFAULT_PLAN_TYPE=pro
+
 # Timeouts (seconds)
 CODEX_LB_UPSTREAM_CONNECT_TIMEOUT_SECONDS=30
 CODEX_LB_STREAM_IDLE_TIMEOUT_SECONDS=300

README.md

@@ -222,6 +222,71 @@ print(response.choices[0].message.content)
 
 </details>
 
+## Anthropic Messages Mode (POC)
+
+`codex-lb` serves two Anthropic-compatible routes:
+
+- `POST /claude/v1/messages` (direct OAuth-backed API proxy to `api.anthropic.com/v1/messages`)
+- `POST /claude-sdk/v1/messages` (local Claude SDK runtime via `claude-agent-sdk`)
+
+Start the server (OpenAI routes and both Anthropic routes are enabled):
+
+```bash
+uv run fastapi run app/main.py --host 0.0.0.0 --port 2455
+```
+
+Prerequisites:
+
+```bash
+claude /login
+uv sync
+```
+
+Usage windows source (Linux-only auto-discovery + optional overrides):
+
+- Set `CODEX_LB_ANTHROPIC_USAGE_REFRESH_ENABLED=true` to enable 5h/7d usage ingestion.
+- Auto-discovery from local Claude credentials (`claude login`) is enabled by default for 5h/7d usage ingestion.
+- Usage polling calls Anthropic OAuth usage API (`/api/oauth/usage`) with the configured OAuth beta header.
+- You can override usage auth explicitly with:
+
+```bash
+export CODEX_LB_ANTHROPIC_USAGE_BEARER_TOKEN="sk-ant-oat01-..."
+```
+
+Example request (API route):
+
+```bash
+curl -sS http://127.0.0.1:2455/claude/v1/messages \
+  -H 'content-type: application/json' \
+  -H 'anthropic-version: 2023-06-01' \
+  -d '{
+    "model": "claude-sonnet-4-20250514",
+    "max_tokens": 1024,
+    "messages": [{"role":"user","content":"Hello"}]
+  }'
+```
+
+Notes:
+
+- `/claude/v1/messages` sends requests directly to `api.anthropic.com/v1/messages` using discovered or configured OAuth credentials.
+- `/claude-sdk/v1/messages` runs generation through the local Claude SDK runtime.
+- API compatibility for `/claude/v1/messages` includes request normalization and optional CLI header/system-prompt parity helpers.
+- OpenAI compatibility routes (`/v1/responses`, `/v1/chat/completions`) stay available in the same server instance.
+
+### Claude Desktop custom deployment note
+
+Claude Desktop custom deployment can point at `codex-lb` for API/bootstrap compatibility routes, but this project does not implement a full `claude.ai` web application clone.
+
+- In custom deployment mode, Desktop loads the configured root page (`/`).
+- `codex-lb` intentionally serves a minimal root page and keeps dashboard UI on `/dashboard`.
+- If you need normal Claude Desktop UI, disable custom deployment and use the default Claude backend.
+
+If you want Desktop traffic to run through `codex-lb` while keeping the stock app UX, use a local shim/proxy that:
+
+- accepts Desktop-specific endpoints/stream shape,
+- translates requests to `codex-lb` API routes (`/claude/v1/messages` or `/v1/responses`),
+- returns Desktop-expected payload/event formats.
+
 ## API Key Authentication
 
 API key auth is **disabled by default** — the proxy is open to any client. Enable it in **Settings → API Key Auth** on the dashboard.