Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ Versions follow the merge of a `*_release-v*` branch; CI publishes to npm on tag

## [Unreleased]

- **Session-file zstd compression, opt-in; decoupled from encryption (#1080)**: set `BILI_PERSIST_ZSTD=1` to compress session files — each file that actually shrinks is written as `BILIZSTD1`, a magic + format-version + mode-byte header over a JSON body that is zstd-compressed on Node ≥ 22.15 and stored raw on older runtimes; readers accept both bodies (native zstd, else the bundled fzstd WASM fallback), so files stay readable across versions and runtimes. **The default stays plain JSON** (owner decision: recoverability — jq/grep-debuggable, no downgrade tail risk — beats silent disk savings; the format change then only ever happens for deployments that opted in). `BILI_ENCRYPTION_KEY` (#708) is now an orthogonal knob: `BILIENC1` bytes are unchanged, its mode byte records whether the body is compressed (the opt-in applies inside it too), existing plain-JSON files are never rewritten at boot (downgrade safety) and convert organically on their next save. `createSessionCodec(key)` is replaced by `createStorageCodec({ key?, compress? })` (no codec when neither is active; both default off). Tests cover round-trip, mixed trees, opt-in/opt-out, raw fallback, cross-runtime decode, never-rewrite-at-boot, and organic conversion on next save.

- **Marker-integrity silence clause now follows `visibilityMarkers` (#913)**: `MARKER_INTEGRITY_NOTE` was one unconditional constant carrying two rules — the #717 anti-forgery segment (never write a marker-style line as your own text) and the #862 silence clause (execute compress-class calls silently, no preamble before / no summary after). With `compress.visibilityMarkers: false` the proxy stops emitting markers entirely, yet the silence clause kept riding every nudge and the injected compress prompt — an instruction about artifacts that deployment never shows. The constant is split (`MARKER_INTEGRITY_NOTE` base + `MARKER_SILENCE_CLAUSE`), and `withMarkerIntegrityNote(text, visibilityMarkers = true)` appends the clause only while markers are visible. The flag is resolved once per request at the prepare dispatch (`resolveCompress(...).visibilityMarkers ?? true`) and threaded through `prepareAnthropic` / `prepareOpenai` / `prepareGoogle` / `prepareResponses` / `injectSystem` plus the compress-loop systemPrompt build, so first request and loop re-requests agree (per-config byte-stable anchor preserved; default output byte-identical to before). The #717 anti-forgery segment stays unconditional in every configuration. Tests pin: clause dropped at `false`, base intact, pure-suffix byte-stability, default-arg legacy equality.

- **Failed-compress receipts now name the live compressible span (#1026, slimmed port of PR #1008 by asuan-dev)**: a model whose compress call fails kept anchoring on refs an earlier fold already consumed — it re-issued the same dead range, burned retries, and eventually gave up and let the nudge re-fire every turn (observed live 2026-09-18: three consecutive failed compresses, two full T1 checkpoints wasted). Both failure receipts (`no valid ranges parsed` and `blocksCreated === 0`) now append `compressibleSpanHint(state)` — the raw-ref span NOT covered by an ACTIVE block right now (`mXXXXX–mYYYYY`, computed as highest mapped ref minus the newest active-block boundary) — so one retry lands on a valid range without another acp_status round-trip. Boundary counts ACTIVE blocks only: after a decompress, the restored span shows as compressible again, which is exactly the recoverable truth. When no raw refs are compressible (everything folded), the receipt names the active blocks' real ids (`startId b7, endId b11`) and suggests folding them into a higher-tier block — a kernel-first-class operation (b-ranges expand to their `effectiveMessageIds` and merge tiers). Coordinates with the #849 repeat-failure guard: the guard forbids repeating the same dead ranges, the hint hands over the live ones. Port keeps only PR #1008's head commit (e4a4700); its bundled #1003/#1004/#1006 content stays out (superseded by #740 / closed in the PR-queue triage). Tests pin: span past the highest ACTIVE block, inactive blocks not holding the boundary (decompress releases it), exhausted fallback naming real active block ids, and both receipt paths carrying the span.
Expand Down
3 changes: 2 additions & 1 deletion CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -516,12 +516,13 @@ Environment variables take precedence over the config file. They are useful for
| `BILI_PERSIST` | Set `0` to disable session persistence (in-memory only, lost on restart). |
| `BILI_PERSIST_DEBOUNCE_MS` | Debounce window for persistence writes to disk, in ms (default `500`). |
| `BILI_PERSIST_TAIL_TOKENS` | Token budget for the persisted conversation snapshot (#401). The disk record stores the **folded view** (block summaries in place of compressed ranges) truncated to the newest messages within this budget — never the raw full history. Default `16384`; `0` disables message persistence entirely (block summaries and compressed originals still persist; `bili export` falls back to block-only rendering). Live in-memory sessions are unaffected — `bili export` of a live session is always complete. |
| `BILI_PERSIST_ZSTD` | Set `1`/`true` to enable zstd compression of session files (#1080, owner decision: **default off** — plain JSON maximizes recoverability: jq/grep-debuggable, and immune to the downgrade tail risk). When enabled, every session file that actually shrinks is written as `BILIZSTD1` — a small header (magic + format version + mode byte) over the JSON body, zstd-compressed on Node ≥ 22.15 and stored raw on older runtimes; readers accept both bodies (native zstd, else the bundled WASM fallback), so files stay readable across runtimes and versions. Payloads the framing cannot shrink (tiny sessions) and key-less raw bodies stay bare JSON on disk. Independent of `BILI_ENCRYPTION_KEY` — with both active, the compression choice is recorded in the mode byte inside `BILIENC1`. Existing plain-JSON files are NEVER rewritten at boot (downgrade safety — a mass re-encode would make rolling back to an older bili read its own writes as "corrupt"); they convert organically on their next save. Note: once a session has been saved as `BILIZSTD1`, an OLDER bili (< 0.1.135) cannot read it — this caveat applies only to deployments that opted in; unset or any other value keeps plain JSON. |
| `BILI_PERSIST_EPERM_ALERT_THRESHOLD` | N consecutive persist write failures (`EPERM`/`EBUSY`/`EACCES`) on one session before the one-time "add this dir to antivirus exclusions" alert fires (default `5`). Windows only. See [Windows: exclude the sessions dir](#windows-exclude-the-sessions-dir-from-antivirus-362). |
| `BILI_PERSIST_EPERM_ALERT_REPEAT_MS` | Re-alert window for the persist EPERM alert, in ms. `0` (default) = alert once then stay silent; `>0` = re-alert at most every that many ms while the failures continue. |
| `BILI_TUNNEL_ALLOWED_HOSTS` | `/bili/<absolute-url>` tunnel admission for **remote clients** (#409): comma-separated `host` or `host:port` entries that unlock loopback/private destinations (e.g. a LAN relay or the machine's own sglang) for non-loopback clients. The proxy itself and link-local/metadata addresses are always denied; local (loopback) clients always pass. |
| `BILI_MAX_SESSIONS` | Max sessions held in memory (default `256`; LRU eviction — disk is the source of truth). |
| `BILI_SESSIONS_DIR` | Directory for persisted session state (default XDG data dir). |
| `BILI_ENCRYPTION_KEY` | Encrypt session files at rest (#708) for deployments on untrusted nodes. Exactly 32 bytes, hex (64 chars) or base64; unset = plain JSON files (default behavior, unchanged). When set: every session file is written as `BILIENC1` AES-256-GCM over zstd-compressed JSON (zstd on Node ≥ 22.15, raw body on older runtimes) — compression also shrinks the file ~5–10×. Existing unencoded files are taken over once at boot: each is re-encoded and atomically replaced in place (the rename IS the old-file deletion; a crash mid-migration self-heals on next boot). The key comes ONLY from this environment variable — never written to disk or logs — so keep it out of the same filesystem's reach. Invalid values abort startup (fail fast, never silently unencrypted). Booting with the wrong key skips the affected sessions as corrupt (logged, no crash). Losing the key makes encrypted sessions permanently unreadable. Symmetric by design (the same process encrypts and decrypts). Threat model (#708, owner-confirmed): it defends against **offline/mechanical** file acquisition — provider disk swaps, offline disk snapshots after node-image drift, stolen volumes, leaked backups, cloud-synced state dirs — where an offline third party cannot read the content without the key. It does NOT defend against targeted adversaries with live access to the node; for that tier move the trust root out of the proxy (KMS / TEE / confidential VMs, hardened permissions) instead of solving it inside the proxy — at that level far more than the key is exposed, so proxy-level key handling is not the boundary to hold (`BILI_PERSIST=0` disables persistence entirely). Double-encrypting the key with a second key from the same process/environment adds nothing: in every offline-theft scenario the attacker lacks exactly one artifact — your off-disk secret — whether it is called the data key or the wrapping key; only a wrapping key in a different trust domain (KMS/TPM/TEE) raises the bar, and that is scenario 2 above. |
| `BILI_ENCRYPTION_KEY` | Encrypt session files at rest (#708) for deployments on untrusted nodes. Exactly 32 bytes, hex (64 chars) or base64; unset = unencrypted plain-JSON files (or `BILIZSTD1` when `BILI_PERSIST_ZSTD=1` — see `BILI_PERSIST_ZSTD`). When set: every session file is written as `BILIENC1` AES-256-GCM over JSON that is zstd-compressed only when `BILI_PERSIST_ZSTD=1` (zstd on Node ≥ 22.15, raw body otherwise) — enabling compression also shrinks the file ~5–10×. Encryption and compression are now independent knobs (#1080). The key comes ONLY from this environment variable — never written to disk or logs — so keep it out of the same filesystem's reach. Invalid values abort startup (fail fast, never silently unencrypted). Booting with the wrong key skips the affected sessions as corrupt (logged, no crash). Losing the key makes encrypted sessions permanently unreadable. Symmetric by design (the same process encrypts and decrypts). Existing unencoded files are never rewritten at boot — they encrypt organically on their next save (downgrade safety; see `BILI_PERSIST_ZSTD`). Threat model (#708, owner-confirmed): it defends against **offline/mechanical** file acquisition — provider disk swaps, offline disk snapshots after node-image drift, stolen volumes, leaked backups, cloud-synced state dirs — where an offline third party cannot read the content without the key. It does NOT defend against targeted adversaries with live access to the node; for that tier move the trust root out of the proxy (KMS / TEE / confidential VMs, hardened permissions) instead of solving it inside the proxy — at that level far more than the key is exposed, so proxy-level key handling is not the boundary to hold (`BILI_PERSIST=0` disables persistence entirely). Double-encrypting the key with a second key from the same process/environment adds nothing: in every offline-theft scenario the attacker lacks exactly one artifact — your off-disk secret — whether it is called the data key or the wrapping key; only a wrapping key in a different trust domain (KMS/TPM/TEE) raises the bar, and that is scenario 2 above. |
| `BILLION_CONTEXT_PROXY` | Exported by the launcher; client-side bili plugins/extensions detect it and self-disable their own compression (no double compression). |
| `BILLION_CONTEXT_PLUGIN` | Set `0` to disable plugin mode entirely (wire-level tool injection resumes). |
| `BILI_LAUNCHER_MODEL_WINDOWS` | Internal: the launcher hands the client's own per-model context windows (pi `models.json`, omp `models.yml`, opencode `models.<id>.limit`, codex `model_context_window`) to the spawned proxy as JSON, so the nudge denominator matches the real window for self-hosted models. Only the launcher sets it — no user configuration. |
Expand Down
3 changes: 2 additions & 1 deletion CONFIGURATION.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -515,11 +515,12 @@
| `BILI_PERSIST` | 设 `0` 关闭会话持久化(仅内存,重启即丢)。 |
| `BILI_PERSIST_DEBOUNCE_MS` | 持久化写盘的防抖窗口(毫秒,默认 `500`)。 |
| `BILI_PERSIST_TAIL_TOKENS` | 持久化会话快照的 token 预算(#401)。盘上记录的是**折叠视图**(压缩范围以块摘要替代)并截断到该预算内的最新消息 —— 不再存全量原始历史。默认 `16384`;设 `0` 彻底不持久化消息(块摘要与压缩原件仍会持久化,`bili export` 退回块级渲染)。活会话内存不受影响 —— 活会话的 `bili export` 始终完整。 |
| `BILI_PERSIST_ZSTD` | 设为 `1`/`true` 启用会话文件的 zstd 压缩(#1080,owner 决定:**默认关闭**——纯 JSON 可恢复性最强:可用 jq/grep 调试,且无降级尾部风险)。启用后,每个确实能压缩变小的会话文件均以 `BILIZSTD1` 格式写入——即在 JSON 主体之上附加一个小头部(魔数 + 格式版本 + 模式字节),在 Node ≥ 22.15 上以 zstd 压缩存储,在旧版运行时上则原样存储;读取端兼容两种主体格式(优先使用原生 zstd,否则回退至内置的 WASM 实现),因此文件在不同运行时和版本间均可正常读取。压不小的小会话与无密钥的原始主体以裸 JSON 落盘。与 `BILI_ENCRYPTION_KEY` 相互独立——两者同时生效时,压缩方式会记录在 `BILIENC1` 内部的模式字节中。已有的纯 JSON 文件**永不在启动时改写**(降级安全——批量重编码会让回退到旧版 bili 时把自己的写入当成“损坏文件”);它们在其下一次保存时自然转换。注意:一旦会话已保存为 `BILIZSTD1`,旧版 bili(< 0.1.135)无法读取——该限制仅对显式启用的部署生效;未设置或其他值均保持纯 JSON。 |
| `BILI_PERSIST_EPERM_ALERT_THRESHOLD` | 同一会话连续 N 次持久化写失败(`EPERM`/`EBUSY`/`EACCES`)后触发一次性「把该目录加入杀软排除项」告警的阈值(默认 `5`)。仅 Windows。见下文「Windows:把会话目录加入杀软排除项」章节。 |
| `BILI_PERSIST_EPERM_ALERT_REPEAT_MS` | persist EPERM 告警的重复窗口(毫秒)。`0`(默认)= 只告警一次后静默;`>0` = 失败持续期间最多每这么久重复告警一次。 |
| `BILI_MAX_SESSIONS` | 内存中最多保留的会话数(默认 `256`;LRU 淘汰 —— 磁盘是事实源)。 |
| `BILI_SESSIONS_DIR` | 会话持久化目录(默认 XDG data 目录)。 |
| `BILI_ENCRYPTION_KEY` | 会话文件静态加密(#708),适用于部署在不可信节点的场景。密钥必须恰好 32 字节,hex(64 字符)或 base64;不设置 = 明文 JSON 文件(默认,行为不变)。设置后:每个会话文件以 `BILIENC1` AES-256-GCM 加密 zstd 压缩后的 JSON 写入(Node ≥ 22.15 启用 zstd,旧版本写原始数据)——压缩同时可使文件缩小约 5–10 倍。已有的未编码文件在启动时一次性接管:逐个重新编码并原子替换到原路径(rename 即旧文件的删除;迁移中途崩溃会在下次启动自愈)。密钥只从该环境变量读取——永不落盘、永不进日志——请确保它不受同一文件系统上的其他进程触及。非法值会导致启动中止(快速失败,绝不静默明文运行)。用错误的密钥启动时,受影响的会话按损坏文件跳过(有日志,不崩溃)。丢失密钥将使已加密的会话永久不可读。对称加密为刻意设计(同一进程既加密又解密)。威胁模型(#708,owner 确认):防的是**离线/机械性**的文件获取——云厂商换盘、节点镜像漂移后的离线磁盘快照、磁盘镜像失窃、备份泄露、被云同步的状态目录——离线第三方拿不到密钥即无法读取内容。不防御对活节点有访问权的定向攻击者;那一档应把信任根移出 proxy(KMS / TEE / 机密虚拟机 + 强化权限体系),而不是在 proxy 本身想办法——到了那个程度暴露的远不止密钥,proxy 层不是该守的边界(`BILI_PERSIST=0` 可彻底关闭持久化)。用同一进程/环境中的第二把密钥对密钥做二次加密不增加任何安全性:所有离线失窃场景里攻击者缺的始终只有一个工件——你的非落盘秘密——无论它叫数据密钥还是包裹密钥;只有把包裹密钥放进不同信任域(KMS/TPM/TEE)才能提高门槛,而那属于上面的场景 2。 |
| `BILI_ENCRYPTION_KEY` | 会话文件静态加密(#708),适用于部署在不可信节点的场景。密钥必须恰好 32 字节,hex(64 字符)或 base64;未设置 = 不加密的纯 JSON 文件(设 `BILI_PERSIST_ZSTD=1` 时为 `BILIZSTD1`——参见 `BILI_PERSIST_ZSTD`)。设置后:每个会话文件均以 `BILIENC1` 格式写入,即对 JSON 施加 AES-256-GCM 加密,JSON 仅在 `BILI_PERSIST_ZSTD=1` 时以 zstd 压缩(Node ≥ 22.15 使用 zstd,其余情况写入原始数据)——启用压缩还可将文件体积缩小约 5–10 倍。加密与压缩现为独立的配置项(#1080)。密钥只从该环境变量读取——永不落盘、永不进日志——请确保它不受同一文件系统上的其他进程触及。非法值会导致启动中止(快速失败,绝不静默明文运行)。用错误的密钥启动时,受影响的会话按损坏文件跳过(有日志,不崩溃)。丢失密钥将使已加密的会话永久不可读。对称加密为刻意设计(同一进程既加密又解密)。已有的未编码文件从不在启动时改写——在其下一次保存时自然加密(降级安全;参见 `BILI_PERSIST_ZSTD`)。威胁模型(#708,owner 确认):防的是**离线/机械性**的文件获取——云厂商换盘、节点镜像漂移后的离线磁盘快照、磁盘镜像失窃、备份泄露、被云同步的状态目录——离线第三方拿不到密钥即无法读取内容。不防御对活节点有访问权的定向攻击者;那一档应把信任根移出 proxy(KMS / TEE / 机密虚拟机 + 强化权限体系),而不是在 proxy 本身想办法——到了那个程度暴露的远不止密钥,proxy 层不是该守的边界(`BILI_PERSIST=0` 可彻底关闭持久化)。用同一进程/环境中的第二把密钥对密钥做二次加密不增加任何安全性:所有离线失窃场景里攻击者缺的始终只有一个工件——你的非落盘秘密——无论它叫数据密钥还是包裹密钥;只有把包裹密钥放进不同信任域(KMS/TPM/TEE)才能提高门槛,而那属于上面的场景 2。 |
| `BILLION_CONTEXT_PROXY` | launcher 会导出它;客户端侧 bili 插件/扩展检测到后自禁用自身压缩(避免双重压缩)。 |
| `BILLION_CONTEXT_PLUGIN` | 设 `0` 彻底关闭插件模式(恢复 wire 层工具注入)。 |
| `BILI_LAUNCHER_MODEL_WINDOWS` | 内部使用:launcher 把客户端自身配置里的逐模型上下文窗口(pi `models.json`、omp `models.yml`、opencode `models.<id>.limit`、codex `model_context_window`)以 JSON 传给自己拉起的代理,让 nudge 分母对自托管模型也用真实窗口。只有 launcher 会设置,无需用户配置。 |
Expand Down
Loading
Loading