Skip to content

feat: image recovery channel for stripImages (#1995) - #2022

Merged
ranxianglei merged 11 commits into
masterfrom
2026-10-03_stripimage-recovery-channel
Oct 7, 2026
Merged

ranxianglei merged 11 commits into
masterfrom
2026-10-03_stripimage-recovery-channel

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Oct 4, 2026 •

Copy link
Copy Markdown
Owner

What & why

compress.stripImages (opt-in, src/config.ts, default stripImagesKeepRecent=5) drops historical image parts from every forwarded request so image-dense sessions stay lean. Today that drop has no way back: decompress is text-only and image_full (#1095) only restores downsampled originals — a strip-removed pixel is gone from the model's view forever. Meanwhile the sliding keep-recent window rewrites one message each turn, busting the prompt cache on the most expensive bytes (the billion-context-pi#593 cost source). The user is forced to pick between burning context or burning cache and going permanently blind to old images.

This adds the recovery channel so stripping becomes reversible: pick lean context, recover any old image on demand.

What this PR does

  • Index by ref. Each request indexes the images still present in the client's resent raw history by their stable mNNNNN ref (buildIncomingImageIndex, new src/image-restore.ts). Built from the unstripped body before stripHistoricalImages drops the parts. Gated on stripImages and cleared when it's off, so non-strip sessions pay nothing. Each indexed image is spilled to disk immediately (skip-if-exists) and only its metadata + path is retained, so session memory stays proportional to the number of images, not their byte size.
  • Restore by ref. decompress gains an optional imageRef: "list" enumerates what is restorable; an mNNNNN ref writes the original bytes to a host-readable file under <stateDir>/retrieve/img/ and returns the path for the model's read tool.
  • File-first delivery, uniform across all four wires — no per-protocol inline-image rendering.

The proxy never mutates client state, so every inbound request carries full raw history and stripped pixels are always recoverable. Native agents own their own decompress (their self-folded images are theirs, cf pi#594); this recovers what the proxy strips.

Config surface

No new config keys. v1 deliberately adds none: the restore location is fixed under the existing <stateDir>/retrieve/ tree (same home as acp_retrieve's spill), and the inline-vs-file split is not exposed as a knob yet — file-first is the safe default and a budget knob can be added later once the shape is proven. stripImages / stripImagesKeepRecent semantics are unchanged.

Behavior changes

  • Additive only. New optional decompress.imageRef; omitting it preserves today's behavior exactly.
  • Memory bounding (from the stripImages 滑窗剥离的图片无恢复通道,且滑窗每轮击穿 prompt cache(billion-context-pi#593 同族缺口) #1995 review): the image index previously retained every resent image's base64 in session memory — unbounded for long image-heavy sessions. It now spills each image to <stateDir>/retrieve/img/ at index-time and keeps only metadata + path, capping residency at O(#images). Restore-by-ref is now a pure path lookup (no re-write); an externally-evicted file reports "re-spilled on next request" instead of returning a dangling path. Non-strip sessions are unaffected (index build gated off).
  • decompress tool description changed (doc-only): one sentence appended advertising imageRef. Byte-visible in the served schema, no semantic change.
  • stripImages behavior DID change in gap2 (correcting an earlier draft that said otherwise): with an active fold on the anthropic wire, the strip boundary is now fold-anchored instead of purely count-driven (see "Gap2" below) and summary image notes carry refs — output format changed for fold-anchored anthropic sessions. No-active-fold and non-anthropic sessions keep the sliding window with byte-identical behavior.

Both compression modes

  • Proxy mode: full coverage — the client resends full raw history every turn, so stripped pixels are always recoverable.
  • Plugin mode: the ACP-native agent owns compression and sends its projected view; non-folded historical images are still present in its request and therefore indexable/recoverable. Images the agent folded itself live in its own store and are handled by the agent's own in-process recovery (pi#594 pattern) — outside the proxy's reach.

Wire-contract goldens (#1304)

Regenerated bili.json + both manifests via scripts/update-wire-contract-goldens.ts. Verified the diff is exactly the decompress description note plus the new imageRef property (and its closing brace) — no other field moved. kernel.json is unchanged (no kernel tools touched).

Gap2 — fold-anchored strip boundary (implemented, anthropic)

The sliding window moved the strip boundary every turn, re-billing the window's image bytes as cache writes forever (billion-context-pi#593). With an active compression fold the cutoff now anchors to fold coverage (foldAnchoredCutoff, src/image-restore.ts): strip exactly the wire messages the fold covers, keep everything after it verbatim — the stripped prefix is byte-stable between compression events, so the cache break stays put. A partially-covered boundary wire message (a live image in the same message the fold stopped before) is never stripped. No active fold → sliding-window fallback; count_tokens uses the same cutoff (token parity) but skips the index rebuild.

This is anthropic-only on purpose: the other three wires flip kernel message ids when stripping (openai/google collapse to "" vs "[image]", responses concatenates text+"[image]"), so anchoring there would orphan fold coverage at T+1. They keep the sliding window until their strip placeholders are made id-neutral — the kernel side needed for anthropic is in this PR:

  • stripHistoricalImages opts.cutoffIndex (protocol-neutral explicit boundary)
  • anthropicToCore tags each flattened core message with its source wire ordinal (BiliMessage.wireIndex)
  • image-only anthropic tool_results collapse to the empty string (not a "[image]" part) so the derived id stays byte-identical across the strip

Plus the two remaining review asks: summary image notes now carry the ref ([image: png 1024x768 · m00042]) so the fold's own text points at decompress({ imageRef }) after the wire drops the pixels, and spilled restore files get best-effort 7-day TTL eviction (pruneRetrieveImgExports, throttled to 1/min; emptied dirs removed).

kernel-change: wire strip-images cutoff option + anthropic wireIndex tagging + empty-string tool_result collapse; kernel 0.0.104 → 0.0.105.

Review round 4 follow-ups (all five open items addressed)

  1. Sanitizer-collision residue — restoreExportDir salted: any session id the sanitizer changes (or truncates at 100 chars) gets -<8 hex of sha256(raw id)> appended, so a/b and a-b no longer share a spill dir. Deterministic → restart-stable; already-pure ids keep their historical path (test: restoreExportDirName).
  2. Image-spill tree joins the session GC (session-gc.ts): deleting a session file co-deletes its retrieve/img/<sessionId>/ dir (same lifecycle as the [Bug] Session-file GC (#1082) never removes #1097 .content-store.json companions — orphaned ref files accumulate #1180 content-store companions), and a stale-mtime pass sweeps orphaned dirs past the same age gate. Spills are a pure cache — a live session that loses its dir self-heals by re-spilling on the next request (item 3's mechanism, now explicit). Opt-in BILI_SESSION_GC as always; session-gc.test.ts now isolates XDG_STATE_HOME for the whole file so sweeps under test never touch a real spill tree.
  3. TTL is mtime-based by design — expiry counts from the last spill write, and an expired-but-still-wanted file is re-spilled by the next request's index build (skip-if-exists). Documented here rather than changed.
  4. Ref footers on model-driven folds (stream.ts applyRanges): preflight summaries already render ref-carrying image notes; a MODEL-written fold covering sidecar images (e.g. responses tool-output screenshots — foldable by design) now gets a compact host-appended footer — [folded images: [image: png 1x1 · m00002] — decompress({ imageRef }) restores pixels] — so the restore channel stays discoverable in that path too. Appended after the kernel's length validation; no footer when the fold covers no images.
  5. Gemini $ref guard mirrored (messageImageBytes): functionResponse parts whose response uses {"$ref": displayName} are skipped at index time, matching the strip side's guard (wasted indexing, never corruption).

Also from the review: rebased onto current master (was 15 behind, src/server.ts/src/session.ts overlap) — clean, no conflicts.

Closes #1995

@github-actions

github-actions Bot commented Oct 4, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-03_stripimage-recovery-channel (59c49cf)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2428-pr.2022.bfa4ade

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

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr2022.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到,正在对 PR #2022(image recovery channel for stripImages)做完整审查:原 issue 方向核对 → 回归清点 → 代码/测试/diff 审查。结论稍后按结构化七问给出。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR #2022 审查完成。审查中发现两处首轮遗漏(均已按「小问题直接修」以追加 commit 修到 PR 分支),CI 现已全绿。判定:可合并(人工合并)。

结构化七问

  1. 是什么问题:stripImages 丢弃历史图片后模型永久失明(decompress 只还文本,image_full 只覆盖降采样原件),且滑动 keep-recent 窗口每轮改写一条消息、击穿 prompt cache。本 PR 补上「恢复通道」。
  2. 什么原因导致的:bili 会话存储只有文本,可恢复像素只存在于客户端每轮重发的完整原始历史里;此前没有任何机制从这些重发字节中留一份索引,strip 之后像素即不可达。
  3. 怎么修复的:请求解析后、strip 之前,把入站未剥离 body 里携带的 base64 图片按稳定 ref(state.messageRefs.byRaw → mNNNNN)索引进 session.incomingImageIndex(仅内存、latest-wins、仅 stripImages 会话);decompress 新增可选 imageRef 参数(mNNNNN 或 "list"),命中时把解码后的字节写到 <stateDir>/retrieve/img/<ref>.<ext>(0600)并返回路径,模型用 read 工具打开——file-first,四种 wire 统一,不内联渲染。
  4. 是否有回归问题:改动纯增量——非 stripImages 会话零行为变化(索引构建被 gate 掉);wire 可见差异只有 decompress schema(description 追加一句 + imageRef 可选属性),PR 已披露且 golden 已按规范重新生成。两种压缩模式都核过(proxy 模式全覆盖;plugin 模式 agent 自折叠的图片不在本通道范围,模块头已注明)。acp-kernel pin 未动。但首轮有两处测试缺口导致 CI 红,已修:① tests/search-context-cross-session.test.ts 的 [Feature] CCR v2: message-ID coverage in block summaries, range-level decompress, ID-returning search_context #1179 schema 漂移守卫仍钉死「kernel + startId/endId only」,新参数+description 使其在全部 4 个 test-matrix job 失败 → commit 78a8a6bc:守卫扩展为承认 imageRef 为第三个 bili-only 可选参数,description 用精确后缀匹配归一(措辞漂移仍会挂,守卫不失牙);② 新测试 writeRestoredImage 断言 0600,NTFS 忽略 POSIX mode 位(438 !== 384)→ 两个 Windows job 失败 → commit b27feee3:mode 断言 gate 到 POSIX,字节回环/幂等断言保持全平台。两处均为 test-only,无 src 语义变更。
  5. 是否破坏缓存:不破坏既有缓存策略;非 strip 会话逐字节不变。strip 会话新增的索引来自本就要转发/重发的请求体,不产生额外上游流量;恢复文件落在本地 retrieve/img/(新增目录,属可观测产物,非配置项)。注意 gap2(缓存稳定的 strip 边界)仍未做,见下。
  6. 是否改了设计方向:无架构转向——host-side only,kernel 不动,恢复走文件而非内联像素,与既有 decompress/search_context 的 file-first 纪律一致。
  7. 是否引入了新的配置:无新 env/config/默认值。imageRef 是工具参数(schema 面,已随 golden 披露),不是配置面。

需要 owner 拍板的三件事

  • 内存驻留(主要发现):incomingImageIndex 会钉住每轮重发历史里所有图片的 base64,直到会话逐出——截图密集型会话的代理常驻内存 ≈ 累计图片字节,无上界。PR 未披露这一点。建议加字节上限或索引时即落盘(不再持有 b64);是否要求合入前解决由你定。
  • 范围缺口:floor 7 计划第 2 项(image-note 占位符带 mNNNNN ref,如 [image: png 1024x768 @ m00042])既不在 PR 里,floor 8 交付报告也没提。请定:并入本 PR(host-side 小改)还是有意放弃(list 功能已让图片可发现)。
  • gap2(cache-stable strip boundary)维持 floor 8 状态:待你批准后另做。

验证证据:本地 typecheck 干净 + 定向套件(image-restore 7/7、wire-contract、strip-images×2、decompress-empty-range、proxy-decompress-cache、wire-schema-portable、fix-decompress-reaper/tofile)全绿;b27feee3 上 CI 九个 workflow 全 success(CI 四系统 test matrix、ci-image、e2e-fake-codex、real codex E2E、e2e-local-registry 双 OS、native opencode/pi/dsh、Windows codex overlay、Build Artifact)。自动合并门禁不适用(feat + wire/message-shape),按 §7.4 需人工合并。

@ranxianglei
ranxianglei force-pushed the 2026-10-03_stripimage-recovery-channel branch 2 times, most recently from 64172c5 to 75259ca Compare October 6, 2026 15:10
@ranxianglei

Copy link
Copy Markdown
Owner Author

Follow-up from review — cross-session collision fix (blocker):

mNNNNN refs are per-session sequence numbers, so the flat <stateDir>/retrieve/img/<ref>.png layout let two sessions' same-numbered refs collide. With skip-if-exists, whichever session spilled first owned the file forever: every other session's decompress({imageRef}) for that number returned the first session's pixels, while the listing metadata (dims/bytes) described the caller's own image — an invisible wrong-content restore. (Adjacent CCR exports avoid the class by rewriting on every retrieve; this keeps skip-if-exists and adds the session id to the path instead.)

  • restoreExportDir(sessionId) → <stateDir>/retrieve/img/<sessionId>/
  • buildIncomingImageIndex / writeRestoredImage take the session id; server.ts passes session.id
  • regression test: two sessions, identical ref numbering, distinct bytes → distinct files, each restores its own pixels

Branch rebased onto current master (resolveDecompress migrated to ProxyToolResult there — the imageRef intercept now returns toolOk/toolFail outcomes). Local: image-restore 8/8 (incl. new regression), strip-images/image/wire-contract/decompress family 15 suites 109/109, tsc clean.

Still open from review (not addressed in this commit): tool-result-nested images (anthropic tool_result.content, responses function_call_output.output, google functionResponse.parts) are stripped by stripNestedImages but not indexed by messageImageBytes — that class remains unrecoverable.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 第二轮审查完成(head 75259ca1,含 66b2d287d 内存有界化 + 75259ca12 会话命名空间两个新提交)。逐项核验如下。

① 是什么问题
两个 review 发现:(a) blocker——mNNNNN 是每会话独立编号,扁平布局 <stateDir>/retrieve/img/<ref>.png 下两个会话的同号 ref 撞车,skip-if-exists 让先写者永久占坑,其余会话恢复出别人的像素(列表元数据却描述调用方自己的图——不可见的错误内容恢复);(b) round-1 遗留——索引持有 base64 字符串,常驻内存 ≈ 会话累计图片字节,无界。

② 什么原因导致的
(a) 路径只含 ref 不含会话身份,而 ref 的命名空间是 per-session;(b) 索引设计为"存字节、恢复时落盘",把可恢复性押在内存上。

③ 怎么修复的(机制层面,已读 diff 核验)

  • restoreExportDir(sessionId) → <stateDir>/retrieve/img/<sanitized-sessionId>/;sanitize = [^a-zA-Z0-9_-]→-、截断 100 字符、空值兜底 "session" —— traversal-safe(/、..、| 全部中和),server.ts 传 session.id,skip-if-exists 保留(与 CCR 导出一致的语义)。
  • buildIncomingImageIndex 增加 sessionId 参数,索引时即落盘(spill-at-index-time):索引改存 {mediaType, bytes, width?, height?, path} 的引用记录,不再持 base64;尺寸解码一次缓存进索引(listing 不再重复解码);稳态每轮每图只剩一次 stat。
  • resolveImageRestore 变为纯查找:existsSync 逐条定位,全部缺失返回 toolFail("no longer on disk…下次请求自动重新落盘"),部分缺失 toolOk 附注 "N image(s) could not be located on disk"——诚实消息,无假成功。rebase 到 ProxyToolResult 后的 toolOk/toolFail 集成正确([decompress] toFile 将虚拟 URI 当磁盘路径,导出写入失败仍返回成功 #2204/fix: decompress toFile export carries real failure outcome (#2204) #2215 约定一致)。

④ 是否有回归问题:无。既有行为清点:wire-contract goldens 相对新 master 的 delta 只有 decompress 描述尾注 + imageRef 属性(5 个变体全覆盖,无杂项);持久化格式未动(incomingImageIndex 仍不落盘);非 stripImages 会话字节级不变(stripImages off 时索引构建整段跳过并清空);剥离行为本身未变。rebase 后 resolveDecompress 迁移到 ProxyToolResult 的适配已核对。验证证据:CI 全绿(head 75259ca1 共 13 个 workflow:4-OS test matrix、ci-image、e2e-fake-codex、real codex、local-registry、native opencode/dsh/pi、Windows codex overlay、Build Artifact、Theorem Lane);本地 typecheck clean + 定向套件 54/54(image-restore 8/8 含新跨会话回归、search-context-cross-session schema guard、wire-contract、strip-images/decompress 家族)。新增回归测试有牙:双会话同 m00001、png vs gif 不同字节 → assert.notEqual(pa,pb) + 字节级断言各文件持有各自像素(旧扁平布局必挂),外加经 buildIncomingImageIndex 的端到端双 body 用例。

⑤ 是否破坏缓存:不涉及前缀缓存(索引构建不改 wire 字节,剥离时机不变);磁盘侧 skip-if-exists 使文件稳定不重写。已知限制:retrieve/ 树(含新增 img/)不在 session GC 覆盖内(src/session-gc.ts 只清 sessions 目录 + .content-store.json 伴生文件),恢复出的图片会累积直到手动清理——与既有 CCR 导出的行为同类,不是对现状的回归;opt-in 功能域,如在意可后续把 retrieve/img/<sanitized-id>/ 纳入 GC(同一 sanitize 函数即可反推目录)。

⑥ 是否改了设计方向:没有,同一机制族原位加固。tool_result 嵌套图(anthropic tool_result.content / responses function_call_output.output / google functionResponse.parts)仍未覆盖——你已在评论中确认留作本 issue 内的后续项,同意不另立项(同一失败域)。

⑦ 是否引入新配置:不涉及。

两个次要发现(均不阻塞):

  1. sanitize 后的 id 碰撞残余风险(理论):不同的原始 session id 可能映射到同一目录(a/b vs a-b,或差异在第 100 字符之后),会以极小概率复现碰撞类问题。廉价加固:目录名追加原始 id 的短 sha256 后缀。需要构造性输入才触发,爆炸半径限于本机 state dir,建议作为可选 follow-up。
  2. 合并时序提示:rebase 之后 master 又前进了 3 个提交(fix: codex / claude-over-Responses instructions drift migrates the persona anchor instead of forking (#2250) #2271 codex-persona-continuity,触碰 src/server.ts +20 行);GitHub 当前报 mergeable=true 无文本冲突,两处改动区域不相交(PR 在 runPrepare 图像索引块,fix: codex / claude-over-Responses instructions drift migrates the persona anchor instead of forking (#2250) #2271 在 persona anchor 解析),但建议合并前再 rebase 一次让 CI 对着最终 base 跑一轮收口。

判定:blocker 修复正确且有牙测试钉住,round-1 内存问题已消解,CI 全绿。可以合入——按 auto-merge 门禁(feat + wire 形状变更)需人工合并;建议先做上面第 2 点的最终 rebase。

@ranxianglei

Copy link
Copy Markdown
Owner Author

Second review finding fixed (0a50040a): tool-result-nested images now indexed.

stripNestedImages removes images from anthropic tool_result.content, Responses function_call_output/custom_tool_call_output .output, and Gemini functionResponse.parts — but messageImageBytes only walked the plain-content sidecars, so that entire class was stripped with no recovery path (the exact #1995 failure mode, for nested shapes). The index now mirrors the strip side's shape knowledge:

  • anthropic: tool_result.content[] image blocks (base64 + data-URL sources)
  • responses: parts array picked by item type (.output for the two tool-output item types, .content otherwise) — same key choice as the strip code
  • google: functionResponse.parts image-mime inlineData. Nested fileData stays unindexable: it is a remote Files-API reference whose bytes never transit the proxy (same already-disclosed class as URL-sourced images — stripped, unrecoverable, and worth a strip-side carve-out if that pattern ever shows up in the wild)

Tests: per-wire nested extraction (multi-image order, pdf part untouched, fileData skip) + end-to-end anthropic tool_result recovery through the index builder — the screenshot is spilled under the tool message's ref and the pixels round-trip. image-restore 10/10; strip-images / image / wire-contract / decompress family green; tsc clean.

With this, every shape the strip side removes has a recovery path except the two no-bytes classes (non-data URLs, Files-API fileData).

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Round-3 review — 0a50040a (tool-result-nested image indexing): 通过。 逐项结论:

1. 是什么问题
tool 结果里嵌套的图片(anthropic tool_result.content、Responses function_call_output/custom_tool_call_output、Gemini functionResponse.parts)被 strip 侧移除后没有恢复路径——这正是 #1995 的失败模式在嵌套形态上的翻版。

2. 什么原因导致的
索引侧(messageImageBytes)的 shape 知识只覆盖平铺内容 sidecar,与 strip 侧(stripNestedImages)的嵌套 shape 知识不同步——同一个"哪个字段携带图片"的事实,两侧各写了一份且漂移了。

3. 怎么修复的
让索引侧逐一对齐 strip 侧的 shape 知识:anthropic 走 tool_result.content[] 的 image block(base64 + data-URL);responses 按 item type 选 .output/.content(与 strip 侧 key 选择完全一致);google 下钻 functionResponse.parts 取 image-mime inlineData;嵌套 fileData 仍不索引(远端 Files-API 引用,字节不过代理,与 URL 源同类)。

4. 是否有回归问题
我对照了仓库内 kernel 的实际 strip 代码(kernel/src/wire/strip-images.ts)逐 wire 核对谓词:anthropic(:74–90)、responses(:158–171)、google(:91–114)两侧判定完全一致;旧 responses 分支对非 tool 类型的 fall-through 语义保留(空 .content 时仍落到 google/singular sidecar),行为不回退;openai chat wire 无嵌套,无需改。一个无害边界:Gemini-3 $ref guard 下 strip 侧会跳过该 part(避免悬空指针),索引侧仍会把字节 spill 下来——多占一点磁盘,无正确性问题。本 commit 只动 src/image-restore.ts + 测试,未碰 kernel/、goldens、config。测试有牙:per-wire 提取(pdf part 不受影响、fileData 跳过)+ anthropic tool_result 端到端像素 round-trip。

5. 是否破坏缓存
不涉及。索引构建仍 gated 在 stripImages && protocol,非 strip 会话零开销;spill-at-index-time + skip-if-exists,稳态每图每轮至多一次 stat,wire 字节与 prefix cache 均无变化。

6. 是否改了设计方向
不涉及。仍是"从客户端每轮重发的完整 raw history 恢复",file-first 恢复路径不变。至此(strip 侧移除的)每个有字节的形态都有恢复路径,仅剩两个无字节类(非 data URL、Files-API fileData),与你声明一致。

7. 是否引入了新的配置
不涉及。

证据:本地 typecheck clean;定向套件 56/56(image-restore 10/10 含新增 nested 用例);CI 在 0a50040a 全绿(13 条 workflow:4-OS test matrix、ci-image、real/fake codex e2e、native opencode/dsh/pi lanes、local registry、Windows overlay、artifact、theorem)。

仍 open(round-2 的 advisory 小项,未处理,非阻塞):① sanitized-id 碰撞残差(两个不同 raw id 净化后可映射同目录,如 a/b vs a-b)——建议目录名追加短 sha256(id) 后缀;② retrieve/img/ 不在 session GC 覆盖内(与既有 CCR exports 同类,磁盘留存随使用增长)——若在意可后续扩展 gcSessionFiles 清扫。两项都留给你定,不挡合并。

合并判定:机制本身审查通过,可合并。但分支现在落后 master 15 个 commit,其中 #2271(persona continuity,+44/−8)动了 src/server.ts、#1820(+48)动了 src/session.ts——PR 也改这两个文件(区域不同、机制正交,但 server.ts runPrepare 附近可能有文本冲突)。建议合并前 rebase 一次当前 master(CI 会自动重跑全套门禁)。按 auto-merge gate(feat + wire tool schema 变更),合并需人工执行。

@ranxianglei

Copy link
Copy Markdown
Owner Author

Follow-up to the two review commits (75259ca session-namespacing, 0a50040 nested tool-result indexing): gap 2 is now implemented on this branch (ecbe6b4) — the strip boundary is fold-anchored on anthropic instead of sliding, so the forwarded body's image-strip prefix is byte-stable between compression events and the prompt cache stops re-billing the window every turn. Design notes in the PR body (kernel changes: cutoffIndex option, wireIndex tagging, empty-string tool_result collapse for id stability; kernel 0.0.104 → 0.0.105). Also in: ref-carrying summary notes ([image: png 1024x768 · m00042]) and 7-day TTL eviction for the spilled restore files. Local: kernel 1247/1247, host image/strip/wire suites 67/67, tsc clean; full-matrix CI running.

@ranxianglei ranxianglei closed this Oct 6, 2026
@ranxianglei ranxianglei reopened this Oct 6, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 第四轮审查结论(gap 2:折叠锚定剥离边界,ecbe6b4a)

机制审查通过。逐层核对了实现与 kernel 侧实际代码(kernel/src/wire/strip-images.ts、anthropicToCore 的文本种子机制),关键前提都成立且被测试钉住。先按七问给结论,再列本轮动作与遗留项。

① 是什么问题
滑动窗口剥离边界每轮随消息数移动,被剥离前缀的字节构成每轮都在变 → prompt cache 在图像位置每轮断裂、整段重计费(#1995 的 gap2,pi#593 成本来源)。

② 什么原因导致的
边界由 len − keepRecent 推导,是消息数的函数而非事件的函数——客户端每轮追加消息,窗口整体平移,上一轮的 [image] 占位符位置这轮变成真实图像字节(或反之)。根因是「边界跟着计数走」,不是图像本身。

③ 怎么修复的
边界改为锚定到活跃折叠覆盖的最后一个 wire 消息:host 从持久化的 state.blocks 收集 covered raw ids,经 wireIndex 映射回 wire 位置,显式 cutoffIndex 传入 kernel 的 stripHistoricalImages——边界只在压缩事件时移动。三个支撑件:(a) anthropic wireIndex 标注;(b) 空字符串 tool_result 塌缩(纯图 tool_result 剥离前后 kernel message id 必须稳定,否则索引引用错位——kernel 测试专门钉死这个不变量);(c) 部分覆盖边界保守处理(边界 wire 消息里有未被折叠覆盖的 live image 时整条保留)。无活跃折叠或非 anthropic wire → 回退经典滑动窗口(其他 wire 的占位符会翻转 kernel message id,不能锚定,理由成立)。附带:preflight 摘要注释携带 ref([image: png 1024x768 · m00042])+ spill 文件 7 天 TTL 驱逐。

④ 是否有回归问题

  • 行为变更(旧→新,有意):stripImages 生效时机从「除最近 N 条外全剥」变为「仅 anthropic 且有活跃折叠时按折叠覆盖剥离」;无折叠会话与其他 wire 字节不变(回退路径同一函数同一参数)。输出格式变化:占位符注释带 ref。PR body 已披露 Gap2 设计,但——注意:PR body 顶部旧 "Behavior changes" 段落仍写着 "No change to stripImages defaults, thresholds, timing, or output format",与 Gap2 直接矛盾,建议更新该段(我没动你的 PR body)。
  • kernel 变更合规:kernel-change: 声明在位、版本 0.0.104→0.0.105、human-only tier 遵守。
  • count_tokens 用同一 cutoff 跳过索引重建 → token 对等,计费口径不漂移。
  • 两种压缩模式均过:门控相同(cs.stripImages && protocol),plugin 模式用 proxy 侧 state blocks,无模式特有风险。
  • 本地证据:typecheck clean;定向套件 host 70/70(image-restore、strip-cutoff-anchor、strip-images 家族、wire-contract、decompress 家族)+ kernel wire-strip 24/24;你报的 kernel 全量 1247/1247 未本地复跑(CI 职责)。
  • 新测试有牙:锚定 vs 滑动的跨轮前缀 deepEqual、id-stability 不变量、部分边界 live-image 保留(cutoff 停在 2 不是 3)、TTL 用 utimesSync 确定性构造——回归时抓得住。

⑤ 是否破坏缓存
这正是修复目标本身:两次折叠之间剥离前缀字节稳定 → cache 命中;cache break 从「每轮」降为「每次压缩事件」。其余缓存/重试/去重键不受影响(索引内存态、文件按 session 隔离)。

⑥ 是否改了设计方向
没有。恢复通道仍是「客户端每轮重发 raw history + file-first 落盘读取」;anthropic-only 锚定是刻意的 wire 约束,不是架构转向。

⑦ 是否引入了新的配置
没有。config.ts 改动仅注释;TTL 硬编码 7 天未暴露旋钮(如后续要调再说,现在不加面是对的)。


本轮我直接修掉的两个小项(已推分支,独立标注 commit):

  1. 3ed3206df refactor:foldAnchoredCutoff 里一行无效代码 else if (m.wireIndex === last) boundaryFull = boundaryFull && true;(x && true === x,恒等赋值)——删除。
  2. 2e15e6a06 docs:CONFIGURATION.md en+zh 同步——stripImages/stripImagesKeepRecent 两节此前仍只描述滑动窗口,与 Gap2 后行为不符(keepRecent 的实际角色已是回退窗口),补上折叠锚定语义 + 恢复通道说明 + 表格行注记。

修后复验:typecheck clean + 相关套件 25/25 绿。push 后新 head 2e15e6a06 的全矩阵 CI 已排队。

仍 open 的小项(不阻塞,延续前几轮清单): ① sanitize 后 session id 碰撞残差(a/b vs a-b 这类,理论面,建议后续加短哈希后缀);② retrieve/ 树不在 session GC 范围内(与既有 CCR export 同类);③ TTL 按 mtime 计(首次 spill 起算,过期后自动 re-spill 自愈);④ ref 注释目前只进 preflight 摘要路径,模型自驱动折叠的摘要不带 ref(可发现性缺口非正确性问题);⑤ Gemini $ref 守卫消息被无害过度索引(浪费非损坏)。

合并判定:机制审查通过,测试有牙,本地定向验证绿,CI 在新 head 上跑。但含 kernel 变更 → 永远 human-gate(§7.4 + Kernel Boundary),且分支落后 master 15 个 commit,热文件重叠(src/server.ts ← #2250 persona resolver、src/session.ts ← #1820 postRebuildAnchor)——当前 GitHub 报 mergeable,但建议 rebase 到最新 master 并看一轮完整 CI 后再人工合并。 请自行合并:#2022

ework-agent and others added 11 commits October 7, 2026 11:32
stripImages drops historical image parts with no way back: decompress is text-only and image_full (#1095) only restores downsampled originals, so once stripped the pixels are gone from the model's view forever — while the sliding keep-recent window rewrites one message per turn and busts the prompt cache on the most expensive bytes (the pi#593 cost source). Either way the user pays.

Add a recovery channel. Each request indexes the images still present in the client's resent raw history by their mNNNNN ref (via stable message ids), gated on stripImages so non-strip sessions pay nothing. decompress gains an optional imageRef: "list" enumerates what is restorable; an mNNNNN ref writes the original bytes to a host-readable file under <stateDir>/retrieve/img/ and returns the path for the model's read tool. File-first delivery is uniform across all four wires — no per-protocol inline-image rendering. The index is built from the UNSTRIPPED body before strip drops the parts, and cleared when stripImages is off.

Wires imageRef into every decompress variant (range and no-range alike; it is CCR-independent, unlike startId/endId). Regenerates the wire-contract goldens accordingly — verified the diff is exactly the decompress description note plus the imageRef property, nothing else.

Proxy-mode coverage: the proxy never mutates client state, so every inbound request carries full raw history and stripped pixels are always recoverable. Native agents own their own decompress (their self-folded images are theirs, cf pi#594); this recovers what the PROXY strips. Gap2 (reducing cache-bust frequency via a compression-anchored strip boundary) stays tracked as the remaining facet of #1995 — a token-vs-cache tradeoff pending owner sign-off, not shipped here.

Closes #1995
…ageRef addition

The PR added an optional imageRef param plus an exact description note to
decompress in all wire shapes but left the #1179 drift guard in
tests/search-context-cross-session.test.ts pinning 'kernel + startId/endId
only', so CI failed on all four test-matrix jobs. The guard now treats
imageRef as a third sanctioned bili-only optional param and strips the note
by exact suffix match (wording drift still fails the test).
…bits)

writeRestoredImage passes {mode:0o600} which NTFS does not apply, so the
restored-file permission check failed both Windows test-matrix jobs with
438 !== 384. Byte round-trip and idempotency assertions stay platform-wide.
…x-time

The review of #1995 found incomingImageIndex pinned every resent image's base64 in session memory for the session's lifetime — for screenshot-dense sessions that is ~cumulative image bytes, unbounded. Fix at the root: spill each image to <stateDir>/retrieve/img/ at index-time (skip-if-exists) and retain only metadata + path (IndexedImage), so residency is O(refs) regardless of image volume.

decompress({ imageRef }) now returns the stored path (a pure lookup, never re-writing bytes); an externally-evicted file degrades to an explicit 're-spilled on next request' message instead of a dangling path. Non-strip sessions still pay nothing (index build gated off). No tool-schema change, so wire-contract goldens are untouched.
mNNNNN refs are per-session sequence numbers, so the flat
<stateDir>/retrieve/img/<ref>.png layout let two sessions' same-numbered
refs collide: with skip-if-exists, whichever session spilled first owned
the file forever, and every other session's decompress({imageRef}) for
that number returned the FIRST session's pixels — with listing metadata
(dims/bytes) describing the caller's own image, so the mismatch was
invisible to the model. Adjacent CCR exports avoid this by rewriting on
every retrieve; recovery here stays skip-if-exists (refs are
deterministic within one session) and takes the other half of the fix:
the session id is now part of the path.

- restoreExportDir(sessionId) -> <stateDir>/retrieve/img/<sessionId>/
- buildIncomingImageIndex / writeRestoredImage take the session id
- server.ts passes session.id at the index call site
- regression test: two sessions, identical ref numbering, distinct
  bytes -> distinct files, each restores its own pixels

Also resolves the rebase onto master's ProxyToolResult migration:
resolveImageRestore now returns toolOk/toolFail outcomes.
…erable (#1995 review)

stripNestedImages removes images from anthropic tool_result.content,
Responses function_call_output/custom_tool_call_output .output, and
Gemini functionResponse.parts — but messageImageBytes only walked the
plain-content sidecars, so that whole class was stripped with no
recovery path (the exact #1995 failure, just for nested shapes).

- anthropic: walk tool_result.content[] image blocks (base64 + data-URL)
- responses: pick the parts array by item type (.output for
  function_call_output / custom_tool_call_output, .content otherwise),
  mirroring the strip side's key choice exactly
- google: descend into functionResponse.parts for image-mime inlineData;
  nested fileData stays unindexable (remote reference, no bytes transit
  the proxy — same disclosed class as URL-sourced images)

Tests: per-wire nested extraction (incl. pdf part untouched, fileData
skip) + end-to-end anthropic tool_result recovery through the index
builder (spilled under the tool message's ref, pixels round-trip).
…store-file eviction (#1995 gap 2)

Kernel:
- stripHistoricalImages gains opts.cutoffIndex (protocol-neutral): an explicit
  wire-message index replaces the sliding len-keepRecent cutoff, so a host can
  pin the strip boundary and keep the stripped prefix byte-stable between
  compression events (prompt-cache stability — the sliding window breaks the
  cache at the image bytes every turn).
- anthropicToCore tags every flattened core message with its source wire
  ordinal (BiliMessage.wireIndex) so hosts can map fold coverage (core ids)
  back to wire positions without re-deriving codec split behavior.
- image-only anthropic tool_results collapse to the empty string instead of a
  "[image]" text part: the derived id is seeded from concatenated TEXT parts,
  so "" keeps it byte-identical across the strip ("[image]" would flip it).
- kernel 0.0.104 -> 0.0.105.

Host:
- foldAnchoredCutoff (anthropic only — the other wires flip ids on strip and
  keep the sliding window until placeholders are id-neutral): with an active
  fold, the strip cutoff anchors to the last covered wire message; a
  partially-covered boundary wire message (live image in the same message) is
  never stripped. Falls back to the sliding window when nothing is covered.
- server wires the anchor into stripHistoricalImages; count_tokens requests
  keep the same cutoff (token parity) but skip the bookkeeping index rebuild.
- summary image notes now carry the ref ([image: png 1024x768 · m00042]) so
  the fold's own text points at decompress({imageRef}) long after the wire
  dropped the pixels.
- pruneRetrieveImgExports: best-effort 7-day TTL eviction for spilled restore
  files (throttled to once a minute in the request path; emptied dirs removed).

Tests: kernel wire-strip-cutoff (5), host strip-cutoff-anchor (7); existing
kernel pins updated for the empty-string tool_result collapse.
…ns, GC the image-spill tree, mirror the Gemini $ref guard, ref footers on model-driven folds
@ranxianglei
ranxianglei force-pushed the 2026-10-03_stripimage-recovery-channel branch from f2ced6f to 59c49cf Compare October 7, 2026 03:42
@ranxianglei
ranxianglei merged commit 433def4 into master Oct 7, 2026
26 checks passed
@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.91-master.433def4 (rolling master tag).

npm install -g billion-context@0.0.91-master.433def4  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

stripImages 滑窗剥离的图片无恢复通道,且滑窗每轮击穿 prompt cache(billion-context-pi#593 同族缺口)

1 participant