Skip to content
Merged
7 changes: 7 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,10 @@ dsh.bundle.patch.yml text eol=lf

# #2489: same failure class for the multi-line trajectory SVG golden.
tests/golden/web-trajectory/*.svg text eol=lf

# #1305 class again, new path: the Vertex fixture's manifest pins each artifact's
# byte size and sha256, and turn-streaming.meta.json is 42 lines — Git-for-Windows'
# autocrlf=true checked it out at 1941 bytes against the recorded 1899, so
# "every fixture artifact matches its recorded digest and size" failed every
# windows-latest leg (run 38982246862).
tests/fixtures/vertex-anthropic/* text eol=lf
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,12 @@ All notable changes to **billion-context** are documented here.
Versions follow the merge of a `*_release-v*` branch; CI publishes to npm on tag.

## [Unreleased]
- **Fix: the Vertex managed block no longer wraps its own value.** `bili install claude` pins `ANTHROPIC_VERTEX_BASE_URL`, and the next derivation read that value back — the settings `env` block reaches the client process, which `readClaudeSettings` falls back to — wrapped it again, and added a `/bili/anthropic/` layer per launch. The extra hop targets the proxy's own port, which the tunnel guard denies (`403 detail:"self"`), so the lane died on the second start. Both derivations (`claudeNativeVertexBaseUrl` in `src/plugin-install.ts`, `claudeVertexUpstream` in `src/launcher.ts`) now collapse any nesting of bili's own wrapper first (`stripBiliWrappers`, `src/vertex.ts`) and are idempotent on their own output; a user's own endpoint behind a wrapper is preserved intact. The same pass closes an install/remove asymmetry: `bili plugin remove claude` now takes `ANTHROPIC_VERTEX_BASE_URL` back when it is ours (a foreign endpoint is left alone, as at install).
- **Claude Code on Vertex AI (`CLAUDE_CODE_USE_VERTEX=1`) is routed through bili.** Under Vertex the plain `ANTHROPIC_BASE_URL` is inert — the client dials `<ANTHROPIC_VERTEX_BASE_URL>/projects/…:rawPredict|streamRawPredict` instead — so the launcher, the managed native install, the upstream-discovery pass and the client config all gained that key: `bili claude` now sets `ANTHROPIC_VERTEX_BASE_URL` to `<proxy>/bili/anthropic/<vertex origin>/v1`, where the protocol marker is required (`:rawPredict` matches no path suffix, so the suffix ladder cannot classify it) and the `/v1` is required because the client appends its own path starting at `/projects/…`; the endpoint host is derived from `ANTHROPIC_VERTEX_BASE_URL`/`CLOUD_ML_REGION` with the region validated against a strict pattern, host and `locations/<loc>` moving together; a dated model id (`claude-opus-5-5@…`) is normalized before the window lookup. The plain key stays set and untouched (inert under Vertex); with Vertex off nothing changes and nothing is emitted. Grounded in a captured Claude Code 2.1.300 wire (`tests/fixtures/vertex-anthropic/`, `tests/vertex-wire-fixture.test.ts`) plus a lane-scoped upstream fake (`tests/wire-contract-fakes.ts` rules `WC-019`/`WC-020`/`WC-021`, `tests/vertex-fake-upstream.test.ts`).
- **Anthropic Threads lane: mirror + reforge (#2926, #2884).** `thread` bodies (`create`/`continue`) hold conversation state server-side: a continue wire body is delta-only no matter how big the thread grew, so bili's history-rewrite lever does not exist on this wire and the compress machinery now stands down for these turns entirely (byte-faithful passthrough, no preflight — the wire body says nothing about the real thread size). Instead every turn is mirrored into the unified store (`session_ext` keys `threads:mirror:*`: create replaces the mirror — it is the client's authoritative snapshot — continue appends its delta; oversized entries are elided, not stored as media). When the mirror estimate crosses the window on a continue and the rollout feature `anthropicThreadsReforge` is on (default 0%; force with `rollout.features.anthropicThreadsReforge: true` or `BILI_ROLLOUT_ANTHROPIC_THREADS_REFORGE=1`), bili swaps that continue for a fresh `create` carrying [summary of the folded prefix, verbatim tail ring (last 3 user turns), this turn's delta] — the only channel that can deliver a fold to a server-side thread. The client's system/tools are copied byte-faithfully from the captured create shape (host instructions never enter the summary); one summarizer side-call rides the client's auth and the same upstream; because the message-id chain IS the thread identity, the client's next continue lands in the new thread with zero redirection. Fail-open everywhere: legacy-only storage (no unified sidecar) captures nothing and never reforges; a failed summary side-call forwards the continue untouched. The lane also claims turns before the #2648 global-scope stand-down — the stand-down used to swallow whole Claude Code threads sessions and silently disable folding (#2884).
- **Stale-guard ownership fast path (#3049):** in shadow/full modes the per-save rollback guard no longer re-reads and re-parses the entire session envelope (the ~320 ms/turn, full-file read on >40 MiB sessions — a large slice of #3049's read amplification). The builder now carries an ownership token (the two monotonic counters it just ingested, plus its build time); when the unified row still matches those counters and the envelope file's mtime sits inside the build window, no other writer can have committed and the guard skips the read. Cross-instance commits are still caught through the shared `index.db` row, foreign file writes (legacy sibling, manual edit) through the mtime check, and legacy-only installs keep the exact per-save full read. Deliberate residual (documented on `ownershipFastPath`): a sibling whose sidecar is disabled writing within the ~1.5 s grace window is missed for one cycle — strictly narrower than an unconditional size/mtime skip.
- **Image pre-compression (`compress.imageCompression`) and the `image_full` tool removed (#3266).** The opt-in downscale pass and its restore channel are gone from host and kernel: no more arrival-time shrinking, no `image_full` injection, no `[Downscaled screenshots]` notes, no image stats — `sharp` is no longer an optional dependency. Rationale: the restore loop was structurally unreachable on hosts that reject bili-injected tools (codex), and where reachable the model had no reliable way to learn the right ref, producing the 38-round guess-reject-resend loop in #3266 (cache hit 75%→28%). Every image now passes through byte-identical at original resolution. Sessions persisted by older versions load unchanged; their legacy `imageShrinks`/`imageFullRestored` state keys and `imageShrunk*` stats are ignored on load (never materialize). A future redesign is tracked on the issue.
- **The proxy now carries Claude Code on Vertex: the wire is classified and the model comes off the publisher path.** A Vertex turn arrives at `/bili/anthropic/https://aiplatform.googleapis.com/v1/projects/…/publishers/anthropic/models/<model>:rawPredict`, whose body carries `anthropic_version` and no `model` field at all — so the model is read from the path (`vertexAnthropicModelFromPath`, a sibling of the Gemini parser so its `:countTokens` arm cannot start matching Anthropic paths), normalised once (`claude-…@YYYYMMDD` → bare publisher id, logged per id), and handed to every model-keyed decision — window resolution, compress thresholds, price profile, fallback logging — through one resolution point (`bodyModel ?? googleModel ?? vertexPathModel ?? v1Model`, body first, so the non-Vertex anthropic lane is byte-identical) that also rides on the prepared request into the relay's compress-loop rebuild. `aiplatform.googleapis.com` and both location-shaped host families now map to the `anthropic` provider; the incremental-lane parameter allowlist keeps `anthropic_version` (`src/incremental-lane.ts` and its mirror `src/agent/incremental-client.ts`) for native-extension hosts; and `bili doctor` reports `bypassed` on a Vertex session instead of under-reporting one. No GCP access was needed — acceptance is the captured fixture replayed at the emitted path against a mock upstream (`tests/e2e-vertex-anthropic.test.ts`), and the same request without the protocol marker is still forwarded verbatim.
- **Incremental marker divert + native client helpers (#3248 phase 2).** A native extension can now send incremental turns on its ORDINARY model requests: stamp `x-bili-plugin-turn: 1` (requires the usual `x-bili-plugin`) and post the incremental payload — the body shape (top-level `conversationId`/`sinceSeq`/`messages`, no top-level `model`) is the final word, so a marker on a non-incremental body rides the normal pipeline unchanged and no provider URL changes. The lane forwards to the ORIGINAL request path; `GET /__bili/plugin/turn` probes capability (`{ok, protocol: 1, feature, enabled, storage}`). Gated by the rollout feature `pluginIncrementalTurns` — default 0% keeps every install byte-identical; force with `rollout.features.pluginIncrementalTurns: true` or `BILI_ROLLOUT_PLUGIN_INCREMENTAL_TURNS=1` (still requires a live unified sidecar). Seeds imply `resync: true` (a first incremental turn never 409s, and interop full-resend traffic is replaced client-authoritatively); a system-only change rides an empty delta. Reference wirings: pi (`before_provider_headers`/`before_provider_request`/`after_provider_response`) and dsh-native (fetch patch `beforeSend`/`headersFor`/`onResponse`), both on the shared state machine in `src/agent/incremental-client.ts` (probe TTL cache, prefix-hash diffing, sticky system, per-conversation dead flag) — new hosts should reuse it. Follow-up wiring ships the remaining native hosts: pi-native inherits the pi wiring unchanged (same extension factory), opencode rides its `http.request` hook (adapter callback swaps the request body after routing/stamping, acks on the fetch intercept), and omp — which has no header events — reads the extension-stamped `prompt_cache_key` body field as the conversation id inside `beforeSend` and stamps the plugin headers directly on the request init (identity upgrade, not a fork). Non-Anthropic wire shapes (OpenAI `tool_calls`) are detected and left on full resend; planned turns are single-in-flight per URL and age out after 30s.
- **Incremental turns (#3248): `POST /__bili/plugin/turn`.** Native hosts that keep their own full local history can stop resending it: the first turn seeds the canonical (server-side, unified messages table), later turns send only the delta (client-added messages including the previous assistant reply), and the lane assembles the full body and re-enters the proxy pipeline in-process — same session (the client's own conversation id), same fold ledger, same nudges/tools, freely interleaving with full-resend traffic. Strict ack contract (`x-bili-applied-seq`; 409 seq-mismatch/turn-in-flight forces resync), sticky system prompt, anthropic request params via allowlist, loopback-gated like every `/__bili/` surface. Requires `storage.unified` (503 otherwise); v1 keeps the O(full) pipeline walk (zero-hit, cheap) — the server-authored prefix fast path is tracked on the issue. A divergent `resync: true` records a base-seq epoch (`session_ext` `inc:base-seq`), so cold rebuilds slice past the rejected branch's append-only rows — one resync heals, restarts included; legacy-only storage degrades to the previous full-union read.
- **Resident metadata folds after save (#3050 R3 ②c):** an idle session's metadata record (fold anchors, cache ledger, lineage — the reconciliation bookkeeping that dominates long sessions) swaps to a transparent lazy proxy after the save captures it; any access re-materializes the persisted shape (exactly what a restart restores) with one disk read, and \`/__bili/memory\` gains a \`metadata\` column. Measured ~19.6 MB off the fattest dogfood session; an unrecoverable drop throws instead of persisting a thinned record.
Expand Down
23 changes: 20 additions & 3 deletions CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -1937,6 +1937,23 @@ Run `codex login` as usual; the OAuth token travels in the `Authorization` heade
export ANTHROPIC_BASE_URL="http://localhost:8787/bili/https://api.anthropic.com"
```

**Claude Code on Vertex AI** (`CLAUDE_CODE_USE_VERTEX=1`) — under Vertex the plain key is inert: Claude Code ignores `ANTHROPIC_BASE_URL` and dials `<ANTHROPIC_VERTEX_BASE_URL>/projects/<p>/locations/<loc>/publishers/anthropic/models/<id>:rawPredict|streamRawPredict`, appending that path to the base URL **verbatim** — trailing path and all. Route `ANTHROPIC_VERTEX_BASE_URL` instead:

```bash
export CLAUDE_CODE_USE_VERTEX=1
export ANTHROPIC_VERTEX_PROJECT_ID=<gcp-project>
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_BASE_URL="http://localhost:8787/bili/anthropic/https://aiplatform.googleapis.com/v1"
```

Three things that URL must get right (each one silently 404s if missed):

- **The `/v1` lives in the base URL.** The client's own path starts at `/projects/…`; Vertex serves `/v1/projects/…:rawPredict` and 404s the version-less form.
- **The `anthropic` segment is required.** With `/bili/<url>` alone the proxy classifies by path suffix, and `:rawPredict` matches no known suffix — the explicit-protocol marker is what selects the anthropic lane.
- **Host and `locations/<loc>` must agree**, and the host follows the region: `global` → `https://aiplatform.googleapis.com`, `us`/`eu` → `https://aiplatform.<loc>.rep.googleapis.com`, any other region → `https://<loc>-aiplatform.googleapis.com`.

Auth is untouched on this lane: Claude Code mints its own ADC access token and bili never mints auth for it. `bili claude` does all of the above automatically — it sets `ANTHROPIC_VERTEX_BASE_URL` to the same routed form and leaves the plain key in place (inert under Vertex, so one launch still works when the provider is flipped off).

> **Auto-compact alignment (manual mode only).** The `bili claude` launcher automatically sets `CLAUDE_CODE_AUTO_COMPACT_WINDOW` to bili's effective window for your model, so claude's own auto-compact threshold lines up with bili's compression budget. In manual `/bili/` mode you must do this yourself — otherwise claude may run its own local auto-compact (a "summarize the conversation" turn) on a threshold that doesn't match bili's window. That is usually harmless (same session-id, so bili re-derives state from the truncation) but noisier than needed. Set it to bili's effective window for your model:
>
> ```bash
Expand Down Expand Up @@ -2012,14 +2029,14 @@ How each client is pointed at the proxy (set automatically in the child env):
| pi | `HTTPS_PROXY` + `BILI_PROVIDER_REWRITES` env manifest (extension `registerProvider`) | `NODE_EXTRA_CA_CERTS` |
| omp | `HTTPS_PROXY` + `BILI_PROVIDER_REWRITES` env manifest (extension `registerProvider`) | `NODE_EXTRA_CA_CERTS` |
| codex | `HTTPS_PROXY` + `-c key=value` overrides | `SSL_CERT_FILE` → `combined-ca.pem` |
| claude | `ANTHROPIC_BASE_URL` = `/bili/` URL | none needed |
| claude | `ANTHROPIC_BASE_URL` = `/bili/` URL (Vertex: `ANTHROPIC_VERTEX_BASE_URL`, when `CLAUDE_CODE_USE_VERTEX=1`) | none needed |
| opencode | `HTTPS_PROXY` + isolated `OPENCODE_CONFIG` | `NODE_EXTRA_CA_CERTS` |
| hermes | `HTTPS_PROXY` (plain-http rides absolute-form forward-proxy requests) | `SSL_CERT_FILE` → `combined-ca.pem` (+ legacy `HERMES_CA_BUNDLE` → `root-ca.pem`) |
| dsh | `HTTPS_PROXY` (+ `HTTP_PROXY` for plain-http) + `DEEPSEEK_BASE_URL`; **loopback-only** isolated `DSH_HOME` | `SSL_CERT_FILE` → `combined-ca.pem` |

`NODE_EXTRA_CA_CERTS` *appends* to the built-in trust store, so it points at the MITM root alone (`root-ca.pem`). `SSL_CERT_FILE` *replaces* the default CA bundle, so for codex/dsh/hermes it points at `combined-ca.pem` — a bundle containing the MITM root **plus** the OS trust store and the Node public roots. The OS-store merge matters because some launched clients treat this file as their *entire* trust pool (codex's rustls HTTP stack replaces rather than appends, #1807): any direct, non-proxied connection of theirs must validate against this file alone, so the file must be a superset of what the OS itself trusts (Windows cert stores via PowerShell, macOS keychains via `security(1)`; Linux already reads the filesystem bundle; rebuilt at most once per 24 h). Keeping pip/git/curl style TLS (blind-tunnelled, real certificates) working inside the child env is the original reason for the bundle (#152; hermes since #1375, because current hermes resolves ambient trust only through `SSL_CERT_FILE`; OS-store merge since #1807).

Claude Code's undici fetch ignores `HTTPS_PROXY`, so cert MITM cannot intercept it. Every claude upstream — including a pre-configured `ANTHROPIC_BASE_URL` relay — is routed through the `/bili/` URL form via `ANTHROPIC_BASE_URL` instead; no CA trust is required.
Claude Code's undici fetch ignores `HTTPS_PROXY`, so cert MITM cannot intercept it. Every claude upstream — including a pre-configured `ANTHROPIC_BASE_URL` relay, and the Vertex endpoint under `CLAUDE_CODE_USE_VERTEX=1` — is routed through the `/bili/` URL form via the client's own base-URL variable instead; no CA trust is required.

Where upstreams are discovered from (read-only):

Expand All @@ -2028,7 +2045,7 @@ Where upstreams are discovered from (read-only):
| Pi | `~/.pi/agent/models.json` — each provider's `baseUrl` |
| omp | `~/.omp/agent/models.yml` — each provider's `baseUrl` |
| Codex | `~/.codex/config.toml` — each `[model_providers.<name>]` `base_url` (+ top-level `openai_base_url`) |
| Claude Code | `ANTHROPIC_BASE_URL` env var, else hardcoded `api.anthropic.com` |
| Claude Code | `ANTHROPIC_BASE_URL` env var; under `CLAUDE_CODE_USE_VERTEX=1` the Vertex host derived from `ANTHROPIC_VERTEX_BASE_URL` / `CLOUD_ML_REGION`, else hardcoded `api.anthropic.com` |
| OpenCode | `~/.config/opencode/opencode.json` — each provider's `baseURL` |
| hermes | `~/.hermes/config.yaml` — each provider's endpoint lines |
| dsh | `~/.dsh/settings.yaml` — every `baseURL`/`baseUrl`/`base_url` value, split by destination (loopback → `/bili/` rewrite; non-loopback https → MITM whitelist; non-loopback http → `HTTP_PROXY`); plus the built-in `deepseek-official` route via `$DEEPSEEK_BASE_URL` |
Expand Down
Loading
Loading