[ranxianglei]

Summary

Adds an env-only, three-state operator override for the inbound x-bili-plugin-bypass passthrough decision. The decision currently lives at a single point (src/server/handle.ts): if the inbound header x-bili-plugin-bypass: 1 is present, the request is forwarded verbatim (no tool injection, no nudge, no session binding) — a legacy contract stamped by the opencode host for in-process compression sessions (#920). Operators had no way to force or forbid that bypass; this adds the knob.

Behavior (three-state, read per-request, no restart)

BILI_PLUGIN_BYPASS	Effect
unset / auto (default)	Current behavior — the inbound header decides per request. Byte-identical to before when unset.
1 / on / true	Force bypass — every inbound request is forwarded verbatim (no tool injection, no nudge, no session binding).
0 / off / false	Never bypass — any inbound x-bili-plugin-bypass header is ignored, so even legacy opencode-acp sessions get the full pipeline.

The single decision point becomes: bypass = override=="on" || (override=="auto" && header=="1"). The log line reports which path fired (forced vs legacy header).

Config surface

• Added: BILI_PLUGIN_BYPASS — env-only, no config-file twin, no CLI flag.
• Why the existing surface cannot express it: the x-bili-plugin-bypass header is a per-request, host-stamped wire signal (binary, host-controlled). There is no operator-side knob to override it; the three-state (force-on / force-off / auto) cannot be expressed by the header alone.
• Mechanisms considered: the providers table (not applicable — this is a per-request routing decision, not provider selection); the compress hierarchy (not applicable — bypass skips the whole pipeline, not compression tuning); the rollout/feature-flag system (considered — a plain env var was chosen per owner sign-off in [Bug][storage] Verification digests ignore own __proto__ fields in retained JSON content #6222 because this is a stable per-process operator posture, not a gradual rollout).
• Compat / migration: unset = byte-identical to current behavior; nothing to migrate. Env-only per owner sign-off in [Bug][storage] Verification digests ignore own __proto__ fields in retained JSON content #6222 (the header is a wire contract stamped by hosts; the override is a per-process operator posture, not a per-route config field).
• Documented in docs/configuration.md + .zh-CN.md (generated env-only table + narrative table) and the website/config-reference/env-only.yaml seed.

Verification

• npm run typecheck — clean
• npm run build — success
• node --import tsx --test tests/plugin-bypass.test.ts — 6/6 pass (2 existing opencode v1: keep opencode-acp legacy sessions working after switching to bili #920 header tests + 4 new override tests, incl. the key force-off-overrides-header case)
• node scripts/config-surface-guard.mjs — coverage OK
• node tools/gen-config-docs.mjs check-coverage — 204 env names + 63 keys documented

Both compression modes

The change is in the inbound routing decision, before mode binding: bypass (either path) forwards verbatim, so neither plugin nor proxy mode is entered. When not bypassed, the existing per-request mode decision is untouched. No wire/message-shape change; no kernel change.

Fixes #6220

[github-actions]

📦 Built Package Artifact

Branch: 2026-11-12_bili-plugin-bypass-override (bab01fd)

Latest build — install this exact version

npm install -g billion-context@0.0.9297-pr.6360.82c4899

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit	version	build
bab01fd	billion-context@0.0.9297-pr.6360.82c4899	build
108530e	billion-context@0.0.9293-pr.6360.3495166	build
df8d22f	billion-context@0.0.9290-pr.6360.be9b332	build

Download artifact

1. Download the artifact from the Actions run
2. Extract the tarball and install:

tar xzf billion-context-pr6360.tgz
npm install -g package

---

Install instructions are refreshed on each push.