Skip to content

feat(codex): announce cloud checkpoints to the proxy on the wire - #251

Closed
NewbieXvwu wants to merge 1 commit into
WSL043:mainfrom
NewbieXvwu:2026-11-11_codex-cloud-checkpoint-headers
Closed

NewbieXvwu wants to merge 1 commit into
WSL043:mainfrom
NewbieXvwu:2026-11-11_codex-cloud-checkpoint-headers

Conversation

@NewbieXvwu

@NewbieXvwu NewbieXvwu commented Nov 11, 2026 •

Copy link
Copy Markdown

Fixes #250 (companion: ranxianglei/billion-context#6215 / PR #6217).

Problem

With compactionMode: cloud the server compacts and the plugin reuses the encrypted checkpoint, but nothing on the wire says so. A fronting proxy has to guess the remote boundary from summary text or from history diffs — fragile, and a session that never sends another request never closes at all.

Change

  • The per-request state records a checkpoint signal when a validated checkpoint is reused: { id, digest, seq, covered }, where id is the stored checkpoint digest (the same identity the proxy can hash from the replayed item) and seq is derived from the durable carrier count so a restart keeps the same identity.
  • stampHeaders(headers) adds the five announcement headers (x-bili-codex-checkpoint, -seq, -state, -covered, -digest) to the outbound request.
  • src/index.js passes prepareHeaders: (_request, headers) => compaction.stampHeaders(headers) to the PiAiAdapter; this is the only live header seam in the DSH adapter.
  • announced is a bounded (256) FIFO set of checkpoint ids announced in this process; a restart re-announces as fresh and the proxy dedupes on (id, seq) by design.

Nothing changes for users who do not run a proxy: the headers are ignored by the backend, preferences/defaults/diagnostics and the stored checkpoint format are untouched.

Tests

  • tests/subscription-compaction.test.mjs — 13 tests, including two new ones: a reused checkpoint stamps the exact five headers (stable id/seq, covered counted from non-system messages, reuse on the second run), and a fresh bridge over the durable carrier re-announces the same id/seq as fresh.
  • Full node --test tests/*.test.mjs: 1394 pass, 1 pre-existing environment failure (tests/subagent-cli.test.mjs compares /var/... with macOS's /private/var/...).
  • pnpm run build OK; lib/ regenerated (not hand-edited).

Risk

Low: adds headers only to requests that already replay a validated checkpoint. If the proxy is absent, nothing reads them. The follow-up (stacked, not in this PR) credits proxy-side folds to the next request's budget; it depends on this PR for the header plumbing.


中文说明

修复 #250(配套:ranxianglei/billion-context#6215 / PR #6217)。

问题:开启云端压缩(compactionMode: cloud)后,服务端完成压缩、插件在后续轮次复用加密 checkpoint,但线上没有任何信号说明这件事。前面的代理只能靠摘要文本或历史 diff 去猜远程边界——很脆弱,而且如果客户端此后再也不发请求,边界就永远不会被识别。

改动:

  • 当一轮请求复用了已校验的 checkpoint 时,记录信号 { id, digest, seq, covered }:id 就是已存的 checkpoint digest(代理从回放的 item 哈希出来也是同一个值),seq 由持久化载体数量推导,重启后身份不变。
  • stampHeaders(headers) 把 5 个通告头(x-bili-codex-checkpoint、-seq、-state、-covered、-digest)加到出站请求上。
  • src/index.js 给 PiAiAdapter 传入 prepareHeaders: (_request, headers) => compaction.stampHeaders(headers)——这是 DSH 适配器里真正生效的头字段入口。
  • announced 是本进程内已通告 checkpoint id 的有界(256)FIFO 集合;进程重启后会以 fresh 重新通告,代理按(id, seq)去重即可。

不接代理的用户完全无感:这些头后端会忽略,偏好项/默认值/诊断计数和已存 checkpoint 格式都没有变化。

测试:tests/subscription-compaction.test.mjs 13 项,其中新增 2 项——复用 checkpoint 时精确打上 5 个头(id/seq 稳定、covered 只数非 system 消息、第二次复用为 reuse),以及用持久化载体新建 bridge 会以 fresh 通告同样的 id/seq。全量 node --test tests/*.test.mjs:1394 通过,1 个既有环境失败(tests/subagent-cli.test.mjs 在 macOS 上 /var 与 /private/var 路径不一致)。pnpm run build 通过,lib/ 为构建产物而非手改。

风险:很低——只对“已经在复用已校验 checkpoint”的请求追加头;没有代理时无人读取。后续 PR(叠在本 PR 之上,不含在本 PR 中)会把代理侧的折叠额度抵扣进下一次请求预算,它依赖本 PR 的头字段能力。

When the ChatGPT backend compacts the conversation it returns an encrypted
compaction item which this plugin replays on the next request. Nothing told
the local ACP proxy that the history it had been compressing was replaced,
so it could only guess from message text.

A validated checkpoint now stamps x-bili-codex-checkpoint, -seq, -state,
-covered and -digest on that request via the adapter's prepareHeaders hook
(mutating payload headers is inert). The id is the durable checkpoint digest
and seq counts the checkpoints already carried by the history, so a restart
re-announces the same identity and the proxy dedupes instead of rebasing
twice.
@WSL043

WSL043 commented Nov 11, 2026

Copy link
Copy Markdown
Owner

I’m going to close this PR. The headers identify a replay only when DSH sends another request, so they cannot save history when the conversation ends immediately after compaction. They would also be sent on direct OpenAI requests, and the sequence can change when the number of checkpoint records in the history changes, even if the replayed checkpoint is the same.

In the real-account test, billion-context could save the history from the completed compaction response and detect adoption by matching the checkpoint in the next request. The subscription-side proxy fix is on main in 9f33187. The archive behavior is tracked on the billion-context side in ranxianglei/billion-context#6217.

If a remaining case needs a signal that the proxy cannot observe in the request or response, please reopen with a reproduction.

@NewbieXvwu

Copy link
Copy Markdown
Author

Agreed on closing — the rationale holds. The sequence instability you point out (it moves with the number of checkpoint records in the history, not with the checkpoint) is real, and hashing the replayed item per request just moves the problem. I won't reopen.

For the record: upstream 9f33187 is the better seam — the proxy now sees the compaction response itself, so the history can be saved from the completed response and adoption matched against the checkpoint in the next request. That is exactly what the billion-context side does in ranxianglei/billion-context#6217 (and its follow-up closes the generation on the response that caused the compaction, covering the conversation-ends-immediately case).

If a signal is ever needed that the proxy cannot observe, the natural one is the item id already present in the next request's input — no new header required.

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.

Announce the cloud compaction checkpoint on the wire for a fronting proxy

2 participants