billion-context 0.1.42 → 0.1.44

package/README.md

@@ -61,6 +61,24 @@ Three ways to use it — pick one:
   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.
 
+### Agent plugin mode (内外呼应)
+
+For a native-plugin experience, an agent can run a small cooperative plugin
+alongside the proxy: the plugin registers the four ACP tools
+(`compress` / `decompress` / `search_context` / `acp_status`) natively with
+the agent and drives the agent's own tool loop, while the proxy stays the
+compression authority (state, history folding, philosophy prompt, nudges).
+Tool schemas are served by the proxy itself (`GET /__bili/plugin/manifest`),
+so plugin and proxy can never drift. See [PLUGIN.md](PLUGIN.md) for the
+protocol spec. Plugin-equipped sessions are detected automatically via
+request headers — wire-level tool injection is then suppressed for them
+(no double compression, native tool UX). Works in both proxy modes: the
+`/bili/` prefix baseURL **and MITM transparent mode** — the launcher
+(`bili pi` / `bili codex` / `bili claude`) exports `BILLION_CONTEXT_PROXY`
+for plugins to detect; the plugin can also report the agent's own model
+context window (`x-bili-plugin-context-window`) and read live context
+usage via `GET /__bili/plugin/status`.
+
 Compression is injected automatically — you only configure routing, never
 compression itself.
 
@@ -83,6 +101,35 @@ bili test pi                          # quick end-to-end smoke test of the pi pa
 bili pi --mitm-domain api.foo.com     # add a domain to the MITM whitelist
 ```
 
+**Plugin-in-launcher mode (#162)** — for `claude` and `codex` the launcher
+additionally injects a single `bili` MCP server (`--mcp-config` for claude,
+`-c mcp_servers.bili.*` for codex — both ephemeral, nothing written to host
+config). The traffic route is **unchanged by default** — the transparent-
+MITM proxy as before — so existing setups keep working exactly as they did
+(OAuth-subscription traffic, custom relay endpoints). Opt in to **direct URL
+routing** (`BILI_LAUNCHER_DIRECT=1`) to drop MITM/CA trust entirely (claude's
+`ANTHROPIC_BASE_URL` / codex's provider `base_url` pointing at the `/bili/`
+prefix); the launcher prints a warning when direct mode changes your traffic
+route. The result is the native-plugin experience of [PLUGIN.md](PLUGIN.md)
+with zero setup: the four ACP tools appear as native MCP tools, executed on
+the proxy under the session lock, while the proxy keeps state, folding,
+philosophy prompt and nudges. Session binding is automatic — claude passes
+its session id to MCP children and on every request; codex spawns bind on
+first sight. Plugin mode is opt-in while host-flag compatibility soaks: set
+`BILI_LAUNCHER_PLUGIN=1` to enable the native MCP tools (verified with
+claude 2.1.227 / codex 0.147.0; `BILI_LAUNCHER_PLUGIN=0` forces the plain
+wire-injected launcher once the default flips on).
+`BILI_LAUNCHER_DIRECT=1` is an opt-in, not an opt-out.
+
+Mode matrix:
+
+| Mode | Tools surface | Setup | When |
+|------|--------------|-------|------|
+| Launcher + MCP (`BILI_LAUNCHER_PLUGIN=1`) | native MCP tools | one env var | best UX; opt-in while soaking |
+| Launcher wire mode (default for claude/codex) | proxy-injected wire tools | none — just `bili claude` / `bili codex` | default until plugin mode soaks |
+| Manual plugin (pi etc.) | agent-side plugin | install plugin | hosts with plugin APIs |
+| Manual baseURL | proxy-injected wire tools | edit client config | exotic hosts |
+
 How the client is pointed at the proxy (set automatically in the child env):
 
 | Client      | Proxy redirect      | CA trust env var        |
@@ -91,6 +138,13 @@ How the client is pointed at the proxy (set automatically in the child env):
 | claude      | `HTTPS_PROXY`       | `NODE_EXTRA_CA_CERTS`   |
 | codex       | `HTTPS_PROXY`       | `SSL_CERT_FILE`         |
 
+`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 it points at `combined-ca.pem` — a bundle containing
+the MITM root **plus** the system/Node public roots — keeping pip/git/curl
+style TLS (blind-tunnelled, real certificates) working inside the child env
+(#152).
+
 The real upstream HTTPS hosts are **discovered by reading** (never editing)
 the client's own config, so whatever you already have set up keeps working:
 
@@ -107,7 +161,8 @@ now auto-proxied too. Both schemes are covered with no config edits:
 - **HTTPS upstreams → cert MITM.** The MITM CA cert is the proxy's own root
   (`~/.local/share/billion-context/ca/root-ca.pem`, generated lazily); the
   client must trust it — pi/claude honor `NODE_EXTRA_CA_CERTS`, codex honors
-  `SSL_CERT_FILE`. Compression is injected on the intercepted TLS stream.
+  `SSL_CERT_FILE` (which points at `combined-ca.pem`, see above). Compression
+  is injected on the intercepted TLS stream.
 - **HTTP upstreams → `/bili/` baseURL rewrite** (since plaintext can't be
   MITM'd). The launcher rewrites the client's base URL through the client's own
   mechanism, leaving its config files untouched: codex via `-c key=value` flags,
@@ -644,6 +699,49 @@ recommended** for many concurrent conversations because of the collision
 risk — until pi grows its own session-id signal. For pi multi-agent use,
 pass an explicit `x-acp-session` header per conversation to avoid collisions.
 
+### Codex subagents get their own compression namespace (#150)
+
+Codex subagents (e.g. the `guardian_subagent` approval reviewer) reuse the
+main conversation's `session_id`, so on the wire they look like the same
+session. Without care their requests inherit the main conversation's
+compression state — a subagent turn can get its context folded (losing the
+verbatim user authorization it must read back) and the two roles' usage
+estimates pollute each other.
+
+billion-context detects this via the `instructions` field: subagent requests
+carry their own role prompt. The **first** instructions seen for a
+conversation anchor the main namespace (stable even if the main prompt
+drifts); any other instructions value maps to a separate `|sub:` namespace
+with its own empty compression state. Subagent requests are self-contained
+replays, so the fresh namespace is lossless — and the web UI's session list
+shows the two namespaces as separate sessions sharing the same client label.
+
+### Sessions depend on the proxy (#151)
+
+Compression state (blocks, summaries, original message cache) lives **in the
+proxy**, not in the client. The client's own local history is the full
+uncompressed view. Two consequences:
+
+- If you point the client back at the real upstream (or stop the proxy), the
+  client replays its **full local history** every turn. After a long
+  compressed session this can exceed the model's context window
+  (`context_window_exceeded`).
+- There is no way to "unpack" a compression block into the client's local
+  history — the client never saw the compressed form.
+
+**Migrating off the proxy:** export the session and paste it into a fresh
+conversation as a handoff:
+
+```bash
+bili export                      # list persisted sessions (id, label, blocks)
+bili export <id|label>           # print a Markdown handoff (block summaries)
+bili export <id> --full          # include the original messages per block
+bili export <id> --full --output handoff.md
+```
+
+Then start a new conversation in the client (direct to upstream) and paste
+the handoff doc as the opening context.
+
 ## Status
 
 Early. Protocol handling and compression work against mock tests (146 passing). Real-model integration testing is the next milestone. Expect rough edges.

package/README.zh-CN.md

@@ -47,6 +47,21 @@ npm install -g billion-context
 - **零配置(最简单):** 在客户端 baseURL 前面加上代理地址 + `/bili/`。无需配置文件 —— context 窗口自动从 [models.dev](https://models.dev) registry 查询。`/bili/` 前缀还是个自检测信号:billion-context 的客户端扩展(billion-context-pi / opencode-acp)能在自己的 baseUrl 里认出它并自禁用,避免双层压缩。
 - **显式 context 窗口覆盖:** 在配置文件(或网页)里按 URL 声明 context 窗口,用于 registry 不认识的端点,或想钉死一个精确值的场景。两种方式路由都是同一个 `/bili/` 前缀 —— 配置只改变代理用哪个 context 窗口。
 
+### Agent 插件模式(内外呼应)
+
+想要原生插件体验,可以在 agent 内部装一个配合代理的插件:插件把四个
+ACP 工具(`compress` / `decompress` / `search_context` / `acp_status`)
+原生注册进 agent、由 agent 自己的工具循环驱动,而代理仍然是压缩引擎
+(状态、历史折叠、压缩哲学 prompt、nudge 全归代理)。工具 schema 由
+代理统一下发(`GET /__bili/plugin/manifest`),插件与代理永远不会版本
+漂移。协议规范见 [PLUGIN.md](PLUGIN.md)。带插件的会话通过请求头自动
+识别 —— 该会话的 wire 层工具注入自动关闭(不会双重压缩,工具体验原生)。
+两种代理模式都支持:`/bili/` 前缀 baseURL **和 MITM 透明模式** ——
+launcher(`bili pi` / `bili codex` / `bili claude`)会导出
+`BILLION_CONTEXT_PROXY` 供插件检测;插件还可以上报 agent 自己的模型
+上下文窗口(`x-bili-plugin-context-window`),并通过
+`GET /__bili/plugin/status` 读取实时上下文水位。
+
 压缩是自动注入的 —— 你只需配置路由,无需配置压缩本身。
 
 ### 方式 A —— 零配置(`/bili/` 前缀)