billion-context 0.1.23 → 0.1.25

package/README.md

@@ -42,179 +42,160 @@ This installs the `bili` command (`bili-proxy` is kept as an alias).
 
 ## Quickstart
 
-Three steps: **start the proxy → edit the config file → point your client at it**.
+Two ways to use it — pick one:
+
+- **Zero-config (simplest):** prefix your client's baseURL with the proxy
+  origin + `/bili/`. No config file needed — context windows are auto-detected
+  from the [models.dev](https://models.dev) registry. The `/bili/` prefix also
+  doubles as a self-detection signal: billion-context client extensions
+  (billion-context-pi / opencode-acp) can recognize it in their own baseUrl
+  and self-disable, so you never get double compression.
+- **Explicit context-window overrides:** declare per-URL context windows in a
+  config file (or the web UI) for endpoints the registry doesn't know about,
+  or when you want to pin an exact value. Routing is the same `/bili/` prefix
+  either way — the config only changes which context window the proxy uses.
+
 Compression is injected automatically — you only configure routing, never
 compression itself.
 
-### Step 1 — Start the proxy
+### Option A — Zero-config (`/bili/` prefix)
+
+Start the proxy:
 
 ```bash
 bili
 ```
 
-It listens on `http://127.0.0.1:8787`. Keep this terminal open (or run in the
-background; see [Running the proxy](#running-the-proxy)).
-
-Click [http://localhost:8787/__acp/](http://localhost:8787/__acp/) to add your models:
-<img width="2908" height="1787" alt="image" src="https://github.com/user-attachments/assets/cacf4b64-e5c6-41f2-b270-fd2be02eab0c" />
-
-On first run `bili` **auto-creates an empty config file** and tells you where,
-so you don't have to invent the schema from scratch. The startup banner prints
-the web UI URL too:
-
-```
-acp-proxy listening on http://localhost:8787 — web UI: http://localhost:8787/__acp/
-```
-
-### How routing works
-
-The proxy routes by a **provider name in the URL path** — the first path
-segment after the host. It strips the name and forwards the rest to that
-provider. Everything after the name is passed through untouched:
-
-```
-client baseURL:  http://localhost:8787/zhipu/api/coding/paas/v4
-                  └──────────┬──────────┘└────────┬────────┘
-                      proxy host           remaining path
-                      + provider name      (forwarded as-is)
-```
-
-This is why Step 2 has you declare named providers, and Step 3 has you put that
-same name at the start of the client's base URL — it's how the proxy knows where
-to send each request. In the config below, `zhipu` corresponds to:
-```json
-    "zhipu": {
-      "url": "https://open.bigmodel.cn",
-      "models": {
-        "glm-5.2": { "context": 1000000, "output": 131072 }
-      }
-```
-
-### Step 2 — Configure your providers
-
-Copy the content below:
-<img width="2931" height="1519" alt="image" src="https://github.com/user-attachments/assets/c02278be-bc7a-4f14-8f58-0f2d83784d54" />
-
-> Prefer not to use the web UI? You can also edit the JSON file directly — see
-> [Manual config file](#manual-config-file) below.
-
-Then **restart `bili`** — the startup banner lists your routes:
+Then just prefix your client's existing baseURL with `http://localhost:8787/bili/`.
+The full upstream URL is embedded in the path, so the proxy knows where to
+forward without any config:
 
 ```
-acp-proxy listening on http://localhost:8787 — routes: anthropic=https://api.anthropic.com, zhipu=https://open.bigmodel.cn
+client baseURL before:  https://api.openai.com/v1
+client baseURL after:   http://localhost:8787/bili/https://api.openai.com/v1
 ```
 
-That confirms the proxy picked up your config. (Prefer editing the JSON file by
-hand? See [Manual config file](#manual-config-file). Full schema — per-model
-context windows, optional fields — is in [Configuration](#configuration).)
-
-### Step 3 — Point your client at the proxy
-
-Edit the client's own config file so it sends requests to
-`http://localhost:8787/<provider>/...` (the provider name from Step 2 as the
-first path segment). Put your **real** API key in the client's config too —
-the proxy passes it through untouched.
+That's it — put your real API key in the client config as usual (the proxy
+passes it through untouched). Context windows (gpt-5.1-codex=400K,
+glm-5.2=1M, claude-opus-4=200K, …) are looked up from models.dev
+automatically.
 
-#### Pi (billion-context-pi)
+#### A. API-key clients (`/bili/` prefix)
 
-Open `~/.pi/agent/models.json` and change your existing provider's **`baseUrl` line** to point at the proxy — leave every other field alone:
-
-```jsonc
-// before:
-"baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4",
-// after (swap the host for the proxy + the provider name you picked):
-"baseUrl": "http://localhost:8787/zhipu/api/coding/paas/v4",
-```
-
-`http://localhost:8787` is the proxy, `zhipu` is the name from Step 2, and the remaining path `/api/coding/paas/v4` is forwarded as-is to Zhipu. `apiKey`, `api`, and `models` stay unchanged.
-
-| `api` value | `baseUrl` should point at |
-|---|---|
-| `openai-completions` | an OpenAI-compatible endpoint (GLM/DeepSeek/OpenAI) → `…/zhipu/...` |
-| `anthropic-messages` | an Anthropic-compatible endpoint → `…/anthropic` |
-
-> If you use the `billion-context-pi` extension, run Pi in an isolated agent
-dir (`PI_CODING_AGENT_DIR=…`) so the client-side extension doesn't double-
-compress alongside the proxy. The `bili-test-pi` helper does this for you.
-
-#### OpenCode
-
-Open `~/.config/opencode/opencode.json` and change your existing provider's **`baseURL` line** to point at the proxy:
+Clients you configure with an **API key** (not a login) let you change the
+upstream URL. Just prepend `http://localhost:8787/bili/` to it — that's the
+only change.
 
+**OpenCode** — edit `~/.config/opencode/opencode.json`, change the provider's `baseURL`:
 ```jsonc
 // before:
 "baseURL": "https://open.bigmodel.cn/api/coding/paas/v4"
-// after:
-"baseURL": "http://localhost:8787/zhipu/api/coding/paas/v4"
+// after (just prepend the proxy origin + /bili/):
+"baseURL": "http://localhost:8787/bili/https://open.bigmodel.cn/api/coding/paas/v4"
 ```
 
-Everything else (`apiKey`, `models`) stays unchanged. For an Anthropic provider, change `baseURL` to `http://localhost:8787/anthropic`.
-
-#### Codex
-
-Open `~/.codex/config.toml` and change your existing provider's **`base_url` line** to point at the proxy:
-
+**Codex (API key)** — edit `~/.codex/config.toml`, change the provider's `base_url`:
 ```toml
 # before:
-base_url = "https://open.bigmodel.cn/api/coding/paas/v4"
+base_url = "https://api.openai.com/v1"
 # after:
-base_url = "http://localhost:8787/zhipu/api/coding/paas/v4"
+base_url = "http://localhost:8787/bili/https://api.openai.com/v1"
 ```
 
-Everything else (`name`, `wire_api`, `env_key`) stays unchanged.
-
-> Codex's Responses API needs an upstream that speaks the Responses protocol.
-> Most regional OpenAI-compatible endpoints only speak `/chat/completions`; if
-> yours 404s on `/responses`, use a relay that speaks Responses, or the
-> official OpenAI API.
-
-#### Other clients (Cursor / Aider / Continue …)
-
-Not yet supported. The proxy currently speaks the Anthropic, OpenAI
-chat-completions, and OpenAI Responses protocols — if your client uses a
-different protocol or a non-standard auth header, it won't work yet.
-
-### Web UI
+**Pi** — edit `~/.pi/agent/models.json`, change the provider's `baseUrl`:
+```jsonc
+// before:
+"baseUrl": "https://api.anthropic.com"
+// after:
+"baseUrl": "http://localhost:8787/bili/https://api.anthropic.com"
+```
 
-Open `http://localhost:8787/__acp/` in a browser while the proxy is running. You can:
+**Other API-key clients (Cursor / Aider / Continue …)** — wherever the
+upstream URL is configured, prepend `http://localhost:8787/bili/` to it.
+Nothing else changes.
 
-- **Edit providers** in a form (add/remove providers and per-model context windows) and save — this writes to `billion-context.json` directly.
-- **Generate client URLs** — pick a provider, get ready-to-copy config snippets for Pi / OpenCode / Codex (the `baseUrl`/`baseURL`/`base_url` line with the proxy origin + provider name filled in).
-- **View sessions** — live table of active sessions (requests, tokens saved, last seen), auto-refreshing.
+#### B. Login/subscription clients (MITM transparent proxy)
 
-Changes to providers require a **restart** to take effect (the UI tells you this).
+Clients you sign **into an account** (ChatGPT Plus/Pro, Claude, ZCode coding
+plan, …) authenticate via **OAuth and hardcode the endpoint** — you can't
+change the baseURL, so the `/bili/` prefix trick doesn't work. These need
+**MITM transparent-proxy mode** instead.
 
-### Manual config file
+Supported login clients:
 
-Prefer editing JSON by hand — for git-managed configs, scripted deployments, or
-if you just don't want to use the browser? The web UI writes to the same file,
-so you can edit it directly with identical results.
+| Client | Login | Endpoint hardcoded | Status |
+|---|---|---|---|
+| **ZCode** | bigmodel coding plan (OAuth) | `open.bigmodel.cn` (builtin provider) | ✅ tested |
+| **Codex** | ChatGPT account (OAuth) | `chatgpt.com/backend-api` | ❓ untested (may not work — needs verification) |
+| **Claude Code** | Claude subscription (OAuth) | `api.anthropic.com` | ❓ untested (may not work — needs verification) |
+
+How MITM mode works: the client only offers an **HTTP proxy** setting, so it
+sends `CONNECT <host>:443`; billion-context terminates the TLS locally (with a
+locally-generated root CA), injects compression into the cleartext, then
+re-encrypts and forwards. The OAuth token travels in the client's
+`Authorization` header, which is forwarded untouched — so the subscription
+discount is preserved.
+
+MITM is on by default and is scoped to a **whitelist** of model hosts
+(`open.bigmodel.cn`, `api.anthropic.com`, `api.openai.com`, `chatgpt.com`).
+All other HTTPS hosts are blind-tunnelled — billion-context never decrypts
+non-model traffic.
+
+**One-time setup (trust the root CA in the client):**
+
+1. Start the proxy once to generate the root CA:
+   ```bash
+   bili start
+   ls ~/.local/share/billion-context/ca/root-ca.pem   # exists now
+   ```
+
+2. In the client's **Settings → Network / Proxy** set:
+   - **HTTP Proxy**: `http://127.0.0.1:8787`
+   - **Proxy CA certificate path**: `~/.local/share/billion-context/ca/root-ca.pem`
+   - (optional) **No-proxy list**: `localhost,127.0.0.1`
+   - (For ZCode specifically: **Settings → Network**. For Codex/Claude Code:
+     set the `HTTPS_PROXY` env var and `NODE_EXTRA_CA_CERTS` to the CA path.)
+
+3. Restart the client. Its model traffic now flows through billion-context
+   with compression injected. Send a message and check the proxy log
+   (`~/.local/state/billion-context/bili.log`) for
+   `mitm <host>:443 tunnel established`.
+
+> The root CA is generated locally and lives only on this machine; it is
+> **not** a system-wide install. Only the client you configure (via the
+> CA-path setting, which it feeds to Node as `NODE_EXTRA_CA_CERTS`) trusts it,
+> so no other app is affected. Deleting the CA files and restarting the proxy
+> regenerates them.
+
+### Option B — Manual config file & context windows
 
 Open `~/.config/billion-context/billion-context.json` and edit the `providers`
-block. Each entry is a **name → URL** mapping; the name is what you put in the
-client's base URL in Step 3.
+block. **The key is the upstream URL** — the string the client puts after
+`/bili/`. The value declares per-model context windows for that URL:
 
 ```json
 {
   "providers": {
-    "zhipu": {
-      "url": "https://open.bigmodel.cn",
-      "models": {
-        "glm-5.2": { "context": 1000000, "output": 131072 }
-      }
+    "https://open.bigmodel.cn/api/coding/paas/v4": {
+      "models": { "glm-5.2": { "context": 1000000 } }
     },
-    "anthropic": "https://api.anthropic.com"
+    "https://api.anthropic.com": {}
   }
 }
 ```
 
-- Delete providers you don't use.
-- Add others (e.g. `"deepseek": "https://api.deepseek.com"`).
+- A key matches when the client's embedded URL equals it or starts with it
+  (longest key wins). A bare host key covers every path on that host.
+- An empty value `{}` means "this URL exists, no overrides" (context windows
+  come from models.dev / the prefix table).
+- Delete entries you don't use; add others as needed.
 - The API key is **not** here — it lives in the client; the proxy passes it
   through untouched.
 
-After saving, **restart `bili`**. (Full schema — per-model context windows,
-optional fields — is in [Configuration](#configuration).)
+### Option C — Web UI & context windows
+
+Open [http://localhost:8787/__bili/](http://localhost:8787/__bili/) to
+configure.
 
 ### Verify
 
@@ -223,11 +204,11 @@ first real request shows compression activity in the log:
 
 ```bash
 # Health check (proxy up + where it forwards)
-curl -s http://localhost:8787/__acp/health
+curl -s http://localhost:8787/__bili/health
 # → {"ok":true,"upstream":"https://api.anthropic.com"}
 
 # Live session stats (after a real request)
-curl -s http://localhost:8787/__acp/stats
+curl -s http://localhost:8787/__bili/stats
 ```
 
 Then send one message from your client and watch the log
@@ -340,15 +321,13 @@ The config file is a single JSON object. Example:
   "port": 8787,
   "host": "127.0.0.1",
   "providers": {
-    "zhipu": {
-      "url": "https://open.bigmodel.cn",
+    "https://open.bigmodel.cn/api/coding/paas/v4": {
       "models": {
-        "glm-5.2": { "context": 1000000, "output": 131072 },
-        "glm-5.1": { "context": 200000, "output": 131072 }
+        "glm-5.2": { "context": 1000000 },
+        "glm-5.1": { "context": 200000 }
       }
     },
-    "anthropic": "https://api.anthropic.com",
-    "deepseek": "https://api.deepseek.com"
+    "https://api.deepseek.com": {}
   }
 }
 ```
@@ -359,12 +338,11 @@ The config file is a single JSON object. Example:
 |------|---------|-------------|
 | `port` | `8787` | Proxy listen port |
 | `host` | `127.0.0.1` | Proxy listen host |
-| `upstream` | `https://api.anthropic.com` | Default upstream when no route matches |
 | `sessionHeader` | `x-acp-session` | Header name clients may send to identify a conversation |
 | `log` | `true` | Enable request logging |
 | `debug` | `false` | Verbose logging (same as `ACP_DEBUG=1`) |
 | `passthrough` | `false` | Forward without compression (same as `ACP_PASSTHROUGH=1`) |
-| `providers` | *(none)* | Provider routes — see below |
+| `providers` | *(none)* | Per-URL context overrides — see below |
 | `compress` | *(see defaults)* | `{ injectTool, injectNudge }` |
 
 > **Choosing a `host`** (IPv6 / containers): the default `127.0.0.1` is
@@ -376,53 +354,52 @@ The config file is a single JSON object. Example:
 > `--host 0.0.0.0` there. ⚠️ `0.0.0.0` / `::` expose the proxy on **all**
 > interfaces; ensure you're on a trusted network or behind a firewall.
 
-### Providers (URL routing + per-model context)
+### Providers (per-URL context overrides)
 
-`providers` maps a route name to either a bare URL string (simple) or an
-object with `url` + optional per-model context window (recommended).
+Routing is always the `/bili/` prefix (see [Option A](#option-a--zero-config-bili-prefix)).
+The `providers` block only declares **context-window overrides** keyed by
+upstream URL. The key is the same string the client puts after `/bili/`:
 
-**Simple form** — provider name → URL:
-```json
-{ "deepseek": "https://api.deepseek.com" }
-```
-
-**Full form** — provider name → `{ url, models }`:
 ```json
 {
-  "zhipu": {
-    "url": "https://open.bigmodel.cn",
-    "models": {
-      "glm-5.2": { "context": 1000000, "output": 131072 },
-      "glm-5.1": { "context": 200000 }
-    }
+  "providers": {
+    "https://open.bigmodel.cn/api/coding/paas/v4": {
+      "models": {
+        "glm-5.2": { "context": 1000000 },
+        "glm-5.1": { "context": 200000 }
+      }
+    },
+    "https://api.deepseek.com": {}
   }
 }
 ```
 
-The same model can have a different context window behind different providers
-(e.g. relay wraps a model with a larger window). `context` is the **input
-context limit** (used by the compressor to decide when to nudge); `output` is
-the max output tokens. Both are optional; missing values fall back to the
-built-in model table, then to `modelContextLimit`.
+The same model can have a different context window behind different upstreams
+(e.g. a relay wraps a model with a larger window). `context` is the **input
+context limit** (used by the compressor to decide when to nudge). It is
+optional; missing values fall back to the [models.dev](https://models.dev)
+registry, then the built-in prefix table.
 
 > **Why declare context at all?** The LLM `/models` API does **not** return
 > context windows (verified across OpenAI, Anthropic, 智谱, comfly). They are
 > document-level information. A wrong value (e.g. GLM-5.2 guessed as 128K
 > instead of 1M) causes spurious frequent compression. Declaring it per
-> provider + model makes the proxy match the registry the client itself uses.
+> URL + model makes the proxy match the registry the client itself uses.
 
-**API keys are never stored in the proxy** — whatever key the agent sends is
-passed through untouched to the upstream.
+### URL key matching rules
 
-### Provider name rules
+- A request matches a key when the client's embedded URL **equals the key or
+  starts with it** (longest key wins).
+- A shallow key like `https://open.bigmodel.cn` overrides every path on that
+  host; a deep key like `https://open.bigmodel.cn/api/anthropic` overrides
+  only that endpoint.
+- Keys never cross hosts (the boundary check requires a `/` or end-of-string
+  after the key), so `https://x.com` does not match `https://x.com.evil`.
+- Models not covered by any matching key fall back to models.dev, then the
+  prefix table, then `modelContextLimit`.
 
-- Must start with a letter, contain only letters/digits/`-`/`_`.
-- Reserved words (`v1`, `chat`, `completions`, `messages`, `models`, `api`)
-  are rejected to avoid colliding with real API path segments.
-- The provider name can appear anywhere in the path; the longest match wins.
-- With **no providers** declared (e.g. you emptied the `providers` block),
-  every request is forwarded to the default `upstream` with its full path —
-  an edge case, not the normal flow.
+**API keys are never stored in the proxy** — whatever key the agent sends is
+passed through untouched to the upstream.
 
 ## How sessions work
 
@@ -460,7 +437,7 @@ pass an explicit `x-acp-session` header per conversation to avoid collisions.
 
 ## Status
 
-Early. Protocol handling and compression work against mock tests (141 passing). Real-model integration testing is the next milestone. Expect rough edges.
+Early. Protocol handling and compression work against mock tests (146 passing). Real-model integration testing is the next milestone. Expect rough edges.
 
 See [billion-context-pi](https://github.com/ranxianglei/billion-context-pi) for the pi-extension mode (in-process, tighter integration, the reference implementation).