agent-cli-proxy 0.1.0 → 0.2.6

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.1](https://github.com/INONONO66/agent-cli-proxy/compare/v0.2.0...v0.2.1) (2026-05-29)
+
+### Bug Fixes
+
+- keep GitHub Release creation independent from npm publish failures
+- package GitHub runtime assets after npm publish
+
+## [0.2.0](https://github.com/INONONO66/agent-cli-proxy/compare/v0.1.0...v0.2.0) (2026-05-29)
+
+### Features
+
+- add separate local dashboard runtime and build output
+- require managed proxy API keys through Authorization Bearer tokens
+- attach release runtime tarballs to GitHub Releases
+
+### Bug Fixes
+
+- disable CLIProxyAPI usage correlation after unsupported 404 responses
+- keep admin APIs local-only by socket address
+
+### Documentation
+
+- document GitHub Release based server installation

package/README.md

@@ -4,11 +4,11 @@
 [![npm version](https://img.shields.io/npm/v/agent-cli-proxy.svg)](https://www.npmjs.com/package/agent-cli-proxy)
 [![Bun](https://img.shields.io/badge/runtime-Bun-black)](https://bun.sh)
 
-AI API proxy with per-tool usage monitoring. Sits between AI coding tools (OpenCode, OpenClaw, Hermes) and upstream API providers, tracking usage per tool and per instance, computing token costs from live pricing data, and mapping CLIProxyAPI accounts to subscription plans for cost monitoring. Runs as a native Bun process. Self-hosted, no containers needed.
+AI API proxy with per-tool usage monitoring. Sits between AI coding tools (OpenCode, OpenClaw, Hermes) and upstream API providers, tracking usage per tool and per instance, computing token costs from live pricing data, and correlating CLIProxyAPI accounts for cost attribution. Runs as a native Bun process. Self-hosted, no containers needed.
 
 ## Why this exists
 
-Most AI coding tools share a single upstream API key, making it impossible to know which tool or session is responsible for a given cost spike. agent-cli-proxy intercepts every request, identifies the originating tool from request headers, and records per-tool usage with accurate cost attribution from models.dev pricing data. It also maps CLIProxyAPI accounts to subscription plans so you can monitor spend against plan limits without any enforcement overhead.
+Most AI coding tools share a single upstream API key, making it impossible to know which tool or session is responsible for a given cost spike. agent-cli-proxy forwards API requests, identifies the originating tool from request headers, and records LLM generation usage with accurate cost attribution from live pricing data. It also correlates CLIProxyAPI accounts to request rows so usage can be audited by upstream account.
 
 ## Install
 
@@ -27,14 +27,42 @@ agent-cli-proxy init
 
 ### From source
 
+Requires Bun 1.3.0 or newer.
+
 ```bash
-git clone https://github.com/<owner>/agent-cli-proxy.git
+git clone https://github.com/INONONO66/agent-cli-proxy.git
 cd agent-cli-proxy
 bun install
 bun run build
 bun run src/cli.ts init
 ```
 
+### Server install from GitHub Release
+
+Install or update a server directly from the latest GitHub Release asset:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/INONONO66/agent-cli-proxy/main/scripts/install-release.sh | bash
+```
+
+Install a specific version and register the user service in one command:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/INONONO66/agent-cli-proxy/main/scripts/install-release.sh | \
+  AGENT_CLI_PROXY_VERSION=v0.2.1 \
+  AGENT_CLI_PROXY_SERVICE=1 \
+  AGENT_CLI_PROXY_INIT=1 \
+  AGENT_CLI_PROXY_ENV=$HOME/.config/agent-cli-proxy/.env \
+  CLI_PROXY_API_URL=http://localhost:8317 \
+  bash
+```
+
+The script requires Bun, downloads `agent-cli-proxy.tar.gz` from GitHub Releases,
+installs the runtime under `~/.local/share/agent-cli-proxy/runtime`, and writes a
+`~/.local/bin/agent-cli-proxy` wrapper. Set `AGENT_CLI_PROXY_INIT=1` to run
+non-interactive initialization during install. Release tarball installs require
+`v0.2.1` or newer because earlier tags do not include runtime assets.
+
 ## Quickstart
 
 1. **Initialize** — creates config, database, and prompts for optional features:
@@ -78,8 +106,8 @@ The installer creates OS-appropriate local paths by default:
 
 Optional features prompted during init:
 
-- Dashboard login (`DASHBOARD_PASSWORD_HASH`)
-- Admin API token (`ADMIN_API_KEY`) when exposing beyond loopback
+- Local admin session login (`DASHBOARD_PASSWORD_HASH`)
+- Admin API token (`ADMIN_API_KEY`) for local admin endpoints
 - CLIProxyAPI account correlation (`CLIPROXY_MGMT_KEY`)
 - SQLite/pricing cache paths
 
@@ -91,28 +119,77 @@ Provider API keys are intentionally **not** stored by this proxy. The proxy rout
 |----------|---------|-------------|
 | `PROXY_PORT` | `3100` | Proxy server port |
 | `PROXY_HOST` | `127.0.0.1` | Bind host. Keep loopback unless you add auth/network controls. |
-| `ADMIN_API_KEY` | | Required when `PROXY_HOST` is not loopback. Token for `/admin/*` endpoints. |
+| `TRUST_PROXY_HEADERS` | `false` | Trust reverse-proxy headers such as `X-Forwarded-Proto`/Cloudflare visitor scheme for HTTPS-only decisions. Enable only behind a trusted proxy. |
+| `ADMIN_API_KEY` | | Optional token for local-only `/admin/*` and `/metrics` endpoints. |
+| `PROXY_REQUIRE_API_KEY` | `false` on loopback, `true` off loopback | Require a valid managed proxy key on `/v1/*` and `/api/*` requests, sent as either `Authorization: Bearer <proxy-key>` or `x-api-key: <proxy-key>`. Keep enabled for any externally reachable deployment. |
 | `CLI_PROXY_API_URL` | `http://localhost:8317` | Upstream CLIProxyAPI URL (required unless `PROXY_LOCAL_OK=1`) |
 | `CLI_PROXY_API_KEY` | `proxy` | Proxy auth key sent to CLIProxyAPI |
 | `CLAUDE_CODE_VERSION` | `2.1.87` | Claude Code version for bypass headers |
-| `DB_PATH` | `data/proxy.db` | SQLite database path |
-| `PRICING_CACHE_PATH` | `data/pricing-cache.json` | Runtime models.dev pricing cache |
+| `DB_PATH` | `$XDG_DATA_HOME/agent-cli-proxy/proxy.db` or `~/.local/share/agent-cli-proxy/proxy.db` | SQLite database path. Use an absolute path outside repo/dist/runtime replacement directories. |
+| `PRICING_CACHE_PATH` | `$XDG_DATA_HOME/agent-cli-proxy/pricing-cache.json` or `~/.local/share/agent-cli-proxy/pricing-cache.json` | Runtime models.dev pricing cache. Use an absolute path outside repo/dist/runtime replacement directories. |
 | `READY_PRICING_MAX_AGE_MS` | `86400000` | Maximum pricing cache age accepted by `/ready` (24h) |
 | `PRICING_REFRESH_INTERVAL_MS` | `21600000` | How often to refresh pricing from models.dev (6h) |
+| `PRICING_OVERRIDES_JSON` | built-in overrides | Optional JSON object of model pricing overrides, keyed by model name. Values use models.dev-style `input`, `output`, `cache_read`, `cache_write`, and `reasoning` per-million-token prices. |
+| `PRICING_ALIASES_JSON` | built-in aliases | Optional JSON object mapping model prefixes to pricing model names for local alias resolution. |
 | `COST_BACKFILL_INTERVAL_MS` | `1800000` | How often to backfill zero-cost request logs (30m) |
 | `COST_BACKFILL_LOOKBACK_MS` | `604800000` | How far back cost backfill looks (7d) |
-| `UPSTREAM_TIMEOUT_MS` | `300000` | Total upstream request timeout (5m) |
-| `UPSTREAM_CONNECT_TIMEOUT_MS` | `10000` | Upstream connection timeout (10s) |
-| `STALE_PENDING_MAX_AGE_MS` | `300000` | Age at which pending request rows are recovered on boot (5m) |
+| `UPSTREAM_TIMEOUT_MS` | `0` | Total upstream request timeout. `0` disables the proxy-side timeout so CLIProxyAPI owns upstream timing. |
+| `UPSTREAM_STREAM_FIRST_BYTE_TIMEOUT_MS` | `0` | First SSE chunk timeout for Claude `/v1/messages` streaming requests. `0` disables the proxy-side timeout. |
+| `UPSTREAM_CONNECT_TIMEOUT_MS` | `0` | Upstream response-header timeout. `0` disables the proxy-side timeout so CLIProxyAPI can return its own result. |
+| `UPSTREAM_MAX_RETRIES` | `2` | Retry attempts for retryable idempotent upstream failures |
+| `UPSTREAM_CIRCUIT_BREAKER_OPEN_AFTER_FAILURES` | `5` | Consecutive upstream failures before a provider circuit opens |
+| `UPSTREAM_CIRCUIT_BREAKER_HALF_OPEN_AFTER_MS` | `30000` | Recovery window before one half-open probe is allowed |
+| `UPSTREAM_CIRCUIT_BREAKER_EVICT_AFTER_MS` | `300000` | Inactive closed provider breaker retention window |
+| `MAX_REQUEST_BODY_BYTES` | `25000000` | Maximum request body size accepted for proxied POST requests (25MB) |
+| `RATE_LIMIT_PER_CLIENT_PER_MIN` | `0` | Optional per `(tool, client_id)` proxy request limit per minute. `0` disables rate limiting. |
+| `STALE_PENDING_MAX_AGE_MS` | `600000` | Age at which pending request rows are recovered on boot (10m) |
 | `QUOTA_REFRESH_INTERVAL_MS` | `300000` | How often to refresh CLIProxyAPI quota snapshots (5m) |
 | `QUOTA_REFRESH_TIMEOUT_MS` | `15000` | Timeout for provider quota refresh calls (15s) |
+| `QUOTA_SNAPSHOT_RETENTION_DAYS` | `7` | Days of quota snapshots to retain |
 | `CLIENT_NAME_MAPPING` | | API key to display name mapping (e.g. `key1=alice,key2=bob`) |
 | `PROVIDERS_CONFIG_PATH` | | Optional JSON file for custom providers |
 | `PROVIDERS_JSON` | | Inline custom provider JSON; takes precedence over `PROVIDERS_CONFIG_PATH` |
-| `PLANS_JSON` | | Inline plans JSON; takes precedence over `PLANS_PATH` |
-| `PLANS_PATH` | | Path to a custom plans.json file |
-| `CLIPROXY_MGMT_KEY` | | Optional CLIProxyAPI management key for account correlation |
-| `CLIPROXY_AUTH_DIR` | | Optional CLIProxyAPI auth directory for subscription quota checks |
+| `CLIPROXY_MGMT_KEY` | | Optional CLIProxyAPI management key for account correlation. Uses `/v0/management/usage-queue` on CLIProxyAPI v6.10+ and falls back to legacy `/v0/management/usage` for older servers. |
+| `CLIPROXY_CORRELATION_LOOKBACK_MS` | `300000` | How far back the correlator fetches local request rows and upstream usage details (5m) |
+| `CLIPROXY_CORRELATION_WINDOW_MS` | `30000` | Maximum timestamp difference allowed when matching a local row to upstream usage (30s) |
+| `CLIPROXY_AUTH_DIR` | | Optional CLIProxyAPI auth directory for quota probes |
+| `UPSTREAM_CIRCUIT_BREAKER_OPEN_AFTER_FAILURES` | `5` | Consecutive upstream failures before the circuit breaker opens |
+| `UPSTREAM_CIRCUIT_BREAKER_HALF_OPEN_AFTER_MS` | `30000` | Delay before a half-open probe is allowed (30s) |
+| `UPSTREAM_CIRCUIT_BREAKER_EVICT_AFTER_MS` | `300000` | Idle time before a healthy breaker is evicted (5m) |
+
+### Persistent config and data paths
+
+Keep mutable files outside the deploy directory so `git pull`, rsync, package
+replacement, or runtime bundle refreshes do not erase state:
+
+- config/env: `~/.config/agent-cli-proxy/.env` for user installs, or
+  `/etc/agent-cli-proxy/agent-cli-proxy.env` for system installs
+- SQLite DB and WAL/SHM: `~/.local/share/agent-cli-proxy/proxy.db` or
+  `/var/lib/agent-cli-proxy/proxy.db`
+- pricing cache: `~/.local/share/agent-cli-proxy/pricing-cache.json` or
+  `/var/cache/agent-cli-proxy/pricing-cache.json`
+
+`agent-cli-proxy init` writes absolute `DB_PATH` and `PRICING_CACHE_PATH`
+values. Runtime defaults also use XDG data paths when those variables are
+unset. Explicit relative paths still work for local development, but startup
+emits configuration warnings because they are deploy-directory dependent.
+
+
+
+### Public proxy API keys
+
+When the proxy binds to a non-loopback host, `PROXY_REQUIRE_API_KEY` defaults to
+`true`. In that mode, every LLM proxy request under `/v1/*` and `/api/*` must
+include a valid managed proxy key as either `Authorization: Bearer <proxy-key>`
+or `x-api-key: <proxy-key>` (Anthropic-SDK style). `Authorization` takes
+precedence when both are present. The legacy `x-proxy-key` header still does
+not satisfy this application-level check. Non-loopback binds cannot disable
+this requirement; keep `PROXY_HOST` on loopback for local development without
+proxy client keys.
+
+Create and manage client proxy keys from the local-only `/admin/api-keys` API.
+These keys remain separate from `ADMIN_API_KEY` and from the upstream
+`CLI_PROXY_API_KEY`.
 
 ## Custom Providers
 
@@ -142,43 +219,10 @@ Add OpenAI-compatible local or custom providers with JSON config. Select them pe
 }
 ```
 
-Provider fields: `id`, `type` (`openai-compatible` or `anthropic`), `paths`, `upstreamBaseUrl`, optional `upstreamPath`, `models`, `headers`, `auth` (`none`, `preserve`, `bearer`, `x-api-key`, or object with `env`/`value`/`header`), and `stripProviderField`.
+Provider fields: `id`, `type` (`openai-compatible` or `anthropic`), `paths`, `upstreamBaseUrl`, optional `upstreamPath`, `models`, `headers`, `auth` (`none`, `preserve`, `bearer`, `x-api-key`, or object with `env`/`value`/`header`), and `stripProviderField`. Requests selected with `x-provider` or a JSON `provider` field are routed to the configured `upstreamBaseUrl` and `upstreamPath`; `stripProviderField: true` removes the selector before forwarding. Anthropic providers default `anthropic-version` to `2023-06-01` when the client omits it.
 
 Save this as a file and set `PROVIDERS_CONFIG_PATH`, or set `PROVIDERS_JSON` to the inline JSON string. Use `agent-cli-proxy providers init` to create a starter file at the default config path.
 
-## Subscription Plans
-
-Plans map CLIProxyAPI accounts to subscription tiers for cost monitoring. This is **monitoring-only** — no request enforcement or quota blocking happens.
-
-### plans.json format
-
-```json
-{
-  "plans": [
-    {
-      "code": "claude_pro",
-      "display_name": "Anthropic Claude Pro",
-      "monthly_price_usd": 20,
-      "notes": "Conservative estimate — verify with vendor — last updated 2026-05"
-    }
-  ]
-}
-```
-
-The proxy ships with a default `plans.json` covering common plans (Claude Pro/Max, ChatGPT Plus/Pro/Business, Kimi Pro, GLM Pro, local BYOK). Override with `PLANS_JSON` or `PLANS_PATH`.
-
-### Plans CLI commands
-
-| Command | Description |
-|---------|-------------|
-| `agent-cli-proxy plans show` | Show loaded plans (human-readable) |
-| `agent-cli-proxy plans show --json` | Show loaded plans as JSON |
-| `agent-cli-proxy plans list` | List all plan codes and prices |
-| `agent-cli-proxy plans init` | Create a starter plans.json at the default config path |
-| `agent-cli-proxy plans path` | Print the active plans.json path |
-| `agent-cli-proxy plans bind <account> <code>` | Bind a CLIProxyAPI account to a plan code |
-| `agent-cli-proxy plans unbind <account>` | Remove a plan binding for an account |
-
 ## CLI Reference
 
 | Command | Description |
@@ -186,8 +230,9 @@ The proxy ships with a default `plans.json` covering common plans (Claude Pro/Ma
 | `agent-cli-proxy init` | Interactive config + DB setup |
 | `agent-cli-proxy init --non-interactive ...` | Non-interactive install (CI-friendly) |
 | `agent-cli-proxy db init` | Initialize or migrate the SQLite database |
+| `agent-cli-proxy db backup --output PATH` | Create a consistent SQLite backup snapshot |
 | `agent-cli-proxy paths` | Print default install paths |
-| `agent-cli-proxy doctor` | Validate config, DB, plans, providers, pricing, upstream |
+| `agent-cli-proxy doctor` | Validate config, DB, providers, pricing, upstream |
 | `agent-cli-proxy doctor --json` | Doctor output as JSON (for issue reports) |
 | `agent-cli-proxy service install` | Install user daemon (systemd/launchd) |
 | `agent-cli-proxy service start` | Start the daemon |
@@ -196,12 +241,6 @@ The proxy ships with a default `plans.json` covering common plans (Claude Pro/Ma
 | `agent-cli-proxy service status` | Show daemon status |
 | `agent-cli-proxy service logs` | Show daemon logs |
 | `agent-cli-proxy service logs --follow` | Stream daemon logs |
-| `agent-cli-proxy plans show` | Show loaded plans |
-| `agent-cli-proxy plans list` | List plan codes |
-| `agent-cli-proxy plans init` | Create starter plans.json |
-| `agent-cli-proxy plans path` | Print active plans.json path |
-| `agent-cli-proxy plans bind <account> <code>` | Bind account to plan |
-| `agent-cli-proxy plans unbind <account>` | Remove account binding |
 | `agent-cli-proxy providers show` | Show loaded provider config |
 | `agent-cli-proxy providers path` | Print active providers config path |
 | `agent-cli-proxy providers init` | Create starter providers.json |
@@ -211,39 +250,70 @@ The proxy ships with a default `plans.json` covering common plans (Claude Pro/Ma
 
 Prefer `--admin-token-env` and `--cliproxy-mgmt-key-env` for non-interactive installs so secrets do not appear in shell history or process arguments.
 
+## Operations
+
+### Database Backups
+
+Use the CLI backup command to create a consistent SQLite snapshot while the daemon is running:
+
+```bash
+agent-cli-proxy db backup --output /var/backups/agent-cli-proxy/proxy-$(date -u +%Y%m%dT%H%M%SZ).db
+```
+
+The command reads `DB_PATH` from the default `.env`; pass `--env PATH` when using a non-default config file. It creates the output parent directory when needed and refuses to overwrite an existing backup. Run it from cron or a systemd timer and apply retention outside the command, for example by deleting backups older than your recovery window.
+
+To restore, stop the daemon, copy the selected backup over `DB_PATH`, run `agent-cli-proxy db init` to apply any pending migrations for the installed version, then restart the daemon. To migrate to a new host, install the same or newer `agent-cli-proxy` version, copy the `.env` and backup file, set `DB_PATH` to the restored location, run `agent-cli-proxy db init`, and start the service.
+
 ## Admin Endpoints
 
-All `/admin/*` endpoints require `ADMIN_API_KEY` when the proxy is not bound to loopback.
+`/admin/*` and `/metrics` are only available to loopback clients
+(`127.0.0.1`, `::1`). When `ADMIN_API_KEY` is set, local callers must send
+`x-admin-token: $ADMIN_API_KEY` or `Authorization: Bearer $ADMIN_API_KEY`.
+The proxy no longer serves a bundled dashboard; build a dashboard as a separate
+client that talks to these local admin APIs.
+
+Usage day parameters and defaults are UTC dates.
 
 | Method | Path | Description |
 |--------|------|-------------|
 | `GET` | `/health` | Liveness probe (always 200 if process alive) |
 | `GET` | `/ready` | Readiness probe (DB, pricing, upstream); 503 when failing |
-| `GET` | `/metrics` | Prometheus-format metrics |
-| `GET` | `/admin/usage/today` | Today's usage summary |
+| `GET` | `/metrics` | Prometheus-format metrics, including usage counters and low-cardinality latency histograms |
+| `GET` | `/admin/usage/today` | Current UTC day usage summary |
 | `GET` | `/admin/usage/range?from=&to=` | Usage by date range |
 | `GET` | `/admin/usage/models?day=` | Model breakdown for a day |
 | `GET` | `/admin/usage/providers?day=` | Provider breakdown for a day |
 | `GET` | `/admin/usage/accounts?day=` | Per-account usage for a day |
 | `GET` | `/admin/usage/accounts/range?from=&to=` | Per-account usage over a range |
 | `GET` | `/admin/usage/accounts/summary?from=&to=` | Account summary (7-day default) |
+| `GET` | `/admin/usage/trend?hours=` | Time-bucketed usage trend |
 | `GET` | `/admin/stats` | Total statistics |
 | `GET` | `/admin/logs` | Request logs (paginated) |
 | `GET` | `/admin/logs?tool=openclaw` | Filter logs by tool |
 | `GET` | `/admin/logs?client_id=openclaw-jongi` | Filter logs by instance |
 | `GET` | `/admin/logs/:id` | Single request log by ID |
+| `GET` | `/admin/logs/:id/cost-audit` | Cost audit records for a request log |
 | `GET` | `/admin/quotas` | Latest stored quota snapshots |
 | `GET` | `/admin/quotas?refresh=true` | Refresh and return quota snapshots |
 | `GET` | `/admin/quotas/refresh` | Force refresh quota snapshots |
-| `GET` | `/admin/plans` | List all plans |
-| `GET` | `/admin/plans/cost-summary?month=YYYY-MM` | Monthly cost summary by account |
-| `GET` | `/admin/plans/account/:account` | Plan binding and recent usage for an account |
+| `GET` | `/admin/quotas/probes` | Available quota probe definitions |
+| `GET` | `/admin/quotas/history?hours=` | Time-bucketed quota snapshots |
+| `GET` | `/admin/providers` | Loaded provider definitions and source info |
+| `GET` | `/admin/pricing?model=&provider=` | Pricing match and cache freshness for a model |
+| `GET` | `/admin/config` | Redacted runtime configuration summary |
+| `GET` | `/admin/api-keys` | List managed proxy API keys |
+| `POST` | `/admin/api-keys` | Create a managed proxy API key |
+| `GET` | `/admin/breakers` | List all circuit breaker states |
+| `GET` | `/admin/breakers/:providerId` | Single breaker state by provider |
+| `POST` | `/admin/breakers/:providerId/reset` | Reset a breaker to closed state |
+
+`/admin/logs` accepts `limit` from 1 to 200 and `offset` from 0 to 100000.
 
 ## Health and Readiness
 
 `/health` is a cheap liveness probe. It returns `200 {"status":"ok"}` as long as the process is alive, with no dependency checks.
 
-`/ready` is a readiness probe that checks the database, pricing cache freshness, upstream CLIProxyAPI, and supervisor loop state. It returns `200` when all checks pass and `503` when any critical dependency is failing.
+`/ready` is a readiness probe that checks the database, pricing cache freshness, upstream CLIProxyAPI, and supervisor loop state. It returns `200` when all checks pass or only transient supervisor retries are in progress, and `503` when any critical dependency is failing.
 
 Sample `/ready` response:
 
@@ -254,7 +324,24 @@ Sample `/ready` response:
     "database": { "status": "pass", "responseTime": 3 },
     "pricing": { "status": "pass", "ageMs": 14400000 },
     "upstream": { "status": "pass", "responseTime": 42 },
-    "supervisor": { "status": "pass", "loops": ["pricing-refresh", "cost-backfill"] }
+    "supervisor": {
+      "status": "warn",
+      "loops": ["pricing-refresh", "cost-backfill"],
+      "loopHealth": [
+        {
+          "name": "pricing-refresh",
+          "consecutiveFailures": 1,
+          "status": "warn",
+          "lastErrorAgeMs": 2500
+        },
+        {
+          "name": "cost-backfill",
+          "consecutiveFailures": 0,
+          "status": "pass",
+          "lastSuccessAgeMs": 60000
+        }
+      ]
+    }
   }
 }
 ```
@@ -272,9 +359,12 @@ Key event names:
 | `lifecycle.pre_logged` | Request row inserted before upstream call |
 | `lifecycle.finalized` | Request row updated after upstream response |
 | `lifecycle.aborted` | Request aborted before upstream response |
-| `upstream.error` | Upstream call failed (with error details) |
+| `passthrough.upstream_headers` | Upstream response headers arrived; includes latency and status for pre-body diagnosis |
+| `passthrough.stream_first_chunk` | First upstream SSE chunk arrived; includes latency for diagnosing Claude queueing |
+| `upstream.error` | Upstream call failed (timeout, 5xx, network) |
+| `upstream.breaker_reject` | Request rejected by open circuit breaker (not an upstream failure) |
+| `upstream.breaker_reset` | Circuit breaker manually reset via admin endpoint |
 | `cost.guard` | Cost computation skipped or guarded |
-| `plans.unmapped` | CLIProxyAPI account has no plan binding |
 | `shutdown.drain` | Graceful shutdown draining in-flight requests |
 | `shutdown.complete` | Shutdown finalized cleanly |
 
@@ -288,7 +378,9 @@ Hermes    ─┘
 
 Each tool is automatically identified by request headers and tracked separately. Multiple instances of the same tool are distinguished by `X-Agent-Name` header or session IDs.
 
-The request lifecycle: a `pending` row is inserted before the upstream call (pre-log), the upstream response streams to the client, and the row is finalized with tokens and cost after the stream completes. An optional correlator loop maps CLIProxyAPI accounts to request rows for subscription attribution. A cost backfill loop recomputes zero-cost rows when pricing data becomes available.
+The request lifecycle for LLM generation calls: a `pending` row is inserted before the upstream call (pre-log), the upstream response streams to the client, and the row is finalized with tokens and cost after the stream completes. Non-LLM proxy calls are forwarded without request-log rows. ProviderTransform modules apply provider-specific header, body, response, and stream-line rewrites, while the provider registry selects built-in or custom providers. An optional correlator loop maps CLIProxyAPI accounts to request rows for account attribution. A cost backfill loop recomputes zero-cost rows when pricing data becomes available.
+
+The correlator matches local rows to CLIProxyAPI usage by timestamp, model, and token totals. Keep the proxy host clock synchronized with CLIProxyAPI; sustained low match rates emit `correlator.low_match_rate`. If clocks can differ beyond the default 30 seconds, increase `CLIPROXY_CORRELATION_WINDOW_MS`.
 
 ### Tool Identification
 
@@ -303,10 +395,10 @@ The request lifecycle: a `pending` row is inserted before the upstream call (pre
 ```
 src/
 ├── config/           # Environment configuration and validation
-├── identification/   # Plugin-based tool identification
 ├── provider/
-│   ├── anthropic/    # Claude bypass + request transform
-│   └── openai/       # OpenAI pass-through
+│   ├── anthropic/    # Anthropic request/response helpers
+│   ├── transforms/   # ProviderTransform registrations
+│   └── registry.ts   # Built-in and custom provider routing
 ├── server/           # HTTP handler, stream relay, usage logging
 ├── storage/          # SQLite repos, pricing, usage service
 ├── usage/            # Usage type definitions
@@ -315,7 +407,7 @@ src/
 
 ## Troubleshooting
 
-Run `agent-cli-proxy doctor` first. It validates configuration, opens the SQLite database, reports applied migrations, checks plans/providers configuration, inspects the pricing cache, probes `CLI_PROXY_API_URL/health`, and lists supervised loops. Use `--json` when attaching output to issues.
+Run `agent-cli-proxy doctor` first. It validates configuration, opens the SQLite database, reports applied migrations, checks provider configuration, inspects the pricing cache, probes `CLI_PROXY_API_URL/health`, and lists supervised loops. Use `--json` when attaching output to issues.
 
 For daemon logs:
 
@@ -328,12 +420,11 @@ On Linux this proxies to `journalctl --user -u agent-cli-proxy.service -f`; on m
 **Common errors:**
 
 - `CLI_PROXY_API_URL is required` — set `CLI_PROXY_API_URL` in your `.env` or pass `PROXY_LOCAL_OK=1` to allow the local default.
-- `ADMIN_API_KEY is required when PROXY_HOST is not loopback` — set `ADMIN_API_KEY` before exposing the proxy beyond `127.0.0.1`.
-- Plans fallback warning in logs — `plans.json` failed to parse; the proxy fell back to bundled defaults. Run `agent-cli-proxy plans show` to inspect the active config.
+- `PROXY_REQUIRE_API_KEY must be true when PROXY_HOST is not loopback` — public proxy binds require a managed proxy key (`Authorization: Bearer <proxy-key>` or `x-api-key: <proxy-key>`) for `/v1/*` and `/api/*` requests.
 
 ## Releasing
 
-For maintainers: run `bun run release-check` to verify the build and package contents before tagging. Push a `v*` tag and the `.github/workflows/release.yml` GitHub Actions workflow runs `bun publish --access public --tolerate-republish` against the npm registry using the `NPM_TOKEN` repository secret.
+For maintainers: run `bun run release-check` to verify the build and package contents before tagging. Push a `v*` tag and the `.github/workflows/release.yml` GitHub Actions workflow runs `bun publish --access public --tolerate-republish` against the npm registry using the `NPM_TOKEN` repository secret, then creates a GitHub Release with `agent-cli-proxy.tar.gz` runtime assets for server installs.
 
 ## Contributing