Repository navigation
Description
Problem
External hosts such as Ekko Studio can route a model request through billion-context and expose the five public plugin tools, but they cannot currently branch a conversation at a selected history point through a public, revision-checked interface. Reusing a parent's conversation ID leaks sibling mutations. Copying session files or calling private persistence helpers bypasses the public contract and is not a safe integration boundary.
The host also needs to distinguish the effective live context from the last provider billing/cache ledger. After manual compression or decompression, a previous request's input token count is not a current context observation.
Related integration request: EKKOLearnAI/ekko-studio#3279.
Requested Public Contract
- Advertise versioned fork support through the plugin manifest, alongside the existing five public tools.
- Expose a public snapshot with a revision and ordered raw/ref identities so a host can select and verify a branch prefix without accessing private storage.
- Create a distinct child conversation using the expected parent revision, an ordered prefix proof, a branch point, and an idempotency key. Retry must replay the original receipt; stale parents, conflicting children, missing originals, and unverifiable branch points must fail closed.
- Preserve restorable original messages, nested compression blocks, refs, CCR state, and effective-context metadata in an independent child. Return
exactorexpandedsemantics explicitly; do not silently treat a summary as recoverable original content. - Verify the child's first real model request consumes the selected inherited compression state, rather than merely copying files that are discarded on the next request.
- Keep parent, child, and sibling search/decompression/mutations isolated, including after proxy restart.
- Expose attributed effective-context observations with source, timestamp, model, context window, and generation. Manual state changes should invalidate or recalculate this observation without overwriting the provider billing ledger or subtracting compression credit twice.
Scope And Prior Work
This is an explicit external-plugin API, not automatic prefix-affinity adoption or rollover into an empty session. #629 and #1539 are related designs, but neither defines this public ordered-prefix fork contract with independent original/CCR state. Multi-proxy processes sharing one state directory remain unsupported; this proposal does not add a shared-directory writer protocol.
Both default and plugin-mode behavior must remain covered. The API should be opt-in through manifest discovery and must not require hosts to import private billion-context functions.
Acceptance
Exercise a live loopback proxy and a real protocol request against a controlled upstream: compressed-prefix forks, branch points inside and across compression blocks, nested blocks, divergent siblings, missing originals, stale revisions, idempotent retry, concurrent forks, restart persistence, first child model request, and independently searchable/decompressible content. Cover observation provenance and ledger isolation separately. Cross-repository identity and persistent-state changes require human review before merging.
Activity
ranxianglei commentedon Oct 3, 2026
[bot] 🏷 收到。这是功能类需求(外部插件公开 API:revision-checked 的会话 fork + 归因式 effective-context observation),按仓库规范先评估、后实现,方向确认前不动手。
重复判定(已完成):检索了 open/closed issue 中 fork / snapshot / branch / handoff / context-observation 相关项——最接近的既有工作:#1539/#1543(handoff rollover,用户主动切新空会话继承压缩状态,PR 已开)、#629/#1834/#1850(prefix-affinity resume/branch 的自动状态收养,非显式 API)、#1333/#1362(derivedFrom 只读血缘链,不复制状态)、#1921(fold-state reconciliation,识别重发历史的 edit/fork 分歧)。本 issue 明确定义为「公开、有序前缀证明、revision-checked、独立 original/CCR 状态的显式 fork API」,与上述均不同;判定不重复,保持打开。
接下来我会细查三块代码给出设计评估:① 插件 manifest/tool endpoint 现状(
src/plugin.ts)与「五个公开工具」的确切集合;② session 状态模型与持久化格式(src/session.ts/src/persist.ts/src/store.tsCCR sidecar)以及既有状态拷贝先例src/fork-adoption.ts的可复用面;③ billing/cache ledger(src/cache-ledger.ts)与 effective-context 观测的现状边界。之后按结构化体例给出方案对比与需要你拍板的决策点。ranxianglei commentedon Oct 3, 2026
[bot] 🏷 Triage verdict: reasonable and buildable on existing primitives — recommending we proceed, with owner sign-off on 5 decision points below. No code written yet (feature class → design sign-off first per project rules).
What I verified (triage evidence)
Not a duplicate. Closest prior work, all distinct from this contract:
bili handoff— user-triggered rollover via token-in-message, minimal visible set (refs + active summaries + derivedFrom link; deliberately no blocks/originals/CCR copy). Different carrier, different completeness guarantee.Root cause check: the gap is a missing public contract, not a defect in any existing mechanism. Reusing the parent conv id leaks siblings (single-valued conversations map, verbatim-id session keying #286); copying session files bypasses the codec/envelope/lane ownership (#991/#1196) and breaks the moment the child's first request resolves to a different key than the copy was written under — which is exactly the "files discarded on the next request" failure mode you describe.
Load-bearing facts found in code that shape the design:
src/server.ts:2076-2082); plugin requests key byx-bili-plugin-conversation. A pre-seeded child session file withid == childConversationIdis picked up on the child's first request via memory-miss →loadSync(src/session.ts:421-453) — the seed is NOT discarded, as long as it is keyed exactly right andmeta.label == id(boot migration rekeys/deletes label≠id records unlesspfa-*,src/persist.ts:428+).planForkAdoption/applyForkAdoption(src/fork-adoption.ts) — set-semantics adoptability (block adoptable iff everyeffectiveMessageIdsis present), tier-block closure dragging, CCR slice viacloneStoreForRefs, kernel ref cursor =highestUsedIndex+1so seeded refs push new assignments above the parent's space (id-never-reused holds).src/cache-ledger.ts:169-172) — ordered-prefix proofs are well-defined overmessageRefs.byRefsorted numerically.CacheLedger,metadata.cacheLedger) is cumulative per-request attribution — a separate concept from a live context observation, and nothing in the proposed design touches it.BlockContent.full), not per-message. Consequence handled below (branch points inside a block).Recommended public contract (host-facing, NOT model tools)
Fork/snapshot are conversation-management operations performed by the host app, not the model — the five model-facing tools stay untouched. Opt-in via manifest discovery, same loopback/trusted-origin admin gate as the existing plugin endpoints:
forkSupport: { "version": 1, "snapshotEndpoint": "/__bili/plugin/snapshot", "forkEndpoint": "/__bili/plugin/fork" }GET /__bili/plugin/snapshot?conversationId=X→{ revision, fingerprint, messages: [{ref, raw}] ascending by ref number, blocks: [{id, refs, nested, active}], ccr: {...} }POST /__bili/plugin/fork→{ conversationId, expectedRevision, branchAfterRef, prefixProof: [raw ids m00001..branch], childConversationId, idempotencyKey }→201 { receipt: { childConversationId, parentRevision, branchAfterRef, semantics: "exact"|"expanded", inheritedBlocks, seededRefs, ccrRefsCloned, missingOriginals[] } }Revision: monotonic counter bumped at every state-mutation chokepoint (processTurn commit, mutating tool execution, compaction boundaries, CCR store mutation) + a structural
fingerprint(hash of the ordered identity list + block structure + counters) in every snapshot. At fork time BOTH are checked: revision mismatch →409 stale_parent; the orderedprefixProofre-verified against live state is the authoritative check (revision is the fast path). Fail-closed matrix: stale parent → 409; conflicting child (id already bound/resident) → 409; unverifiable branch point → 400; missing originals → reject unlessrequireSemantics: "expanded"explicitly requested, with the exact gaps enumerated.Seed mechanics (the correctness core): everything runs under
withSessionLock(parent); seed = generalization ofplanForkAdoptionfrom set-semantics to prefix-semantics (incomingIds :=all raws with ref ≤ branch):messageRefs(counters take parent's currentnextBlockId/nextRunId— conservative, gaps legal, reuse impossible);effectiveMessageIds≤ branch), with nested/tier closure as inactive records; a block straddling the branch point is simply absent from the child — it did not exist yet at branch time, and the pre-branch originals stay live refs that the client supplies in the child's first request (clients always re-send what they sent; folding is proxy-internal). This makes branch points inside and across compression blocks both valid, with no partial-blob surgery;blockContentscopied for adopted blocks (decompress works independently); CCR store sliced to refs ≤ branch ∪ cited placeholders (bug(ccr): fork adoption carries covered refs without adopting their content-store entries #1341 pattern);stats+ freshCacheLedger(billing isolation), copiedprotocol/upstreamOrigin,label = childConversationId,metadata.pluginAgent(sticky plugin mode),metadata.derivedFrom = {parentId, branchAfterRef}(free [pi plugin] Prime RLM inline 派生子会话在代理模式下零继承:搜不到也解压不了父会话压缩块(billion-context-pi#531 同场景) #1333 lineage + ancestor search fallback);.content-store.jsonsidecar written synchronously before the 201 returns (writeNowpath exists,src/persist.ts:355) — survives a proxy restart between fork and first request;semantics:"exact"= every ref ≤ branch is in the seeded ref map and every inherited block's originals are in the child'sblockContents(nothing lost proxy-side);"expanded"= some refs ≤ branch are unrecoverable (compaction-archive-pruned raws, evicted CCR entries) — enumerated inmissingOriginals. A summary is never reported as recoverable original content.parent.metadata.forkReceipts(keyed by hashed idem key, capped + evicted oldest) → retry after restart replays the original receipt; same key + different body → 409. Concurrent forks serialize on the parent lock; independent children coexist, divergent mutations stay isolated (verified by test, incl. post-restart).Recommended attributed observation (Part B, both modes)
New typed persisted field on the session (forward-compat default like
mergeState), exposed onGET /__bili/plugin/statusand in snapshots:Stamped from the same places
contextTokens/lastInputTokensprovenance tiers (#857/#1839) are stamped today, plusmodel/windowfrom the request context. Every manual state change (compress/decompress/absorb/fork-seed/compaction boundary) bumpsgeneration, marksstale: true, and immediately recomputes a local estimate over the post-change folded view (kernel per-message counter) — the value self-heals to usage-grade at the next upstream report. The billing ledger (stats.inputTokens/cachedTokens,cacheLedger) is never read-modified by this path, andcompressCreditTokensnetting stays exactly where it is (applied at usage-report time only) — no double subtraction by construction.Decision points (need your sign-off before I implement)
forkReceiptsin parent metadata, theobservationfield. All additive/optional with forward-compat defaults (old files load fine), but per your own acceptance note this puts the PR in human-review-required territory regardless of how clean it is.Test plan (maps your acceptance list 1:1)
Hermetic loopback-proxy suite against a controlled mock upstream (same pattern as
tests/e2e/e2e-image-billing.test.ts, ungated/fast): compressed-prefix fork; branch inside block; branch across adjacent blocks; nested tier blocks with child-side decompress/search; divergent siblings incl. post-restart isolation; missing-originals (simulated archive prune + CCR eviction) → expanded/reject; stale revision + proof mismatch → 409; idempotent retry incl. across restart; concurrent forks; first-child-request verification (assert the upstream-bound body actually carries the inherited artifacts and new refs land strictly above the parent's max — not just file equality); observation provenance + ledger byte-stability across manual ops. Unit tests for the prefix-containment/closure math and revision-bump coverage. Plugin mode is the primary lane; the observation half covers default mode too.Sequencing note: no file conflict with open PR #1543 (
src/handoff.tsis new-file scoped); if it merges first its clone helpers may be reusable.server.ts/plugin.ts/session.tsare hot files — I'll rebase to current master before claiming mergeable.Say the word on D1–D5 and I'll open the implementation PR referencing this issue.
yingzhongshuoqi commentedon Oct 3, 2026
Draft implementation for design and human review: #2017. The draft records public snapshot/fork semantics, persistence/identity scope, observed test failures and rollout limits. No configuration surface is added and no production deployment or npm publication has been performed. Final independent review and baseline verification remain in progress; this is not a merge-ready claim.
ranxianglei commentedon Oct 3, 2026
[bot] 🏷 PR #2017 独立 review 完成(draft,非合并建议)。结论先行:方向正确、测试质量高、验收清单逐项有真断言;但还有 3 项需要拍板的设计决策,另有 1 处我直接修掉的小问题(已推 commit)。当前 not merge-ready。
验证证据(本地定向,全量回归留给 CI)
33d58e5e),不陈旧 ✓origin/master基线逐条一致;PR 本身与我的修复引入的增量诊断 = 0 ✓plugin-fork(20)+plugin-status-provenance(7)+tool-ring+wire-contract= 66/66,含真实 loopback proxy + mock upstream + spawn 第二进程真重启 ✓已直接修掉并推送(
ce734975,已在 PR 分支上)publishForkSession 磁盘存在性探测缺 meta:原探测
loadSync(id)无 protocol meta——按 kernel store 契约(namespaced 记录只在「本实例写过」或「loadAll 发现过」之后可解析),一个既没写过也没发现过该 child 文件的 store 实例会 miss,冲突重试直达flushSync,可覆盖已建立的 child 文件。改为 meta-aware 探测,并把对应 throw 映射为契约码409 CHILD_CONFLICT(原先落到泛化503 FORK_FAILED)。补了回归测试钉住 kernel-documented no-discovery 边界——已双向验证:pre-fix 失败(201 clobber)/ post-fix 通过。严重度修正说明:支持的单进程运行内,kernel discovered map(boot loadAll 发现全部文件)已覆盖此情形,所以此项实际是 LOW 级加固(跨进程/外部移动文件形态),比我初判的 MED 低一档。
需要你拍板(blocking)
D-A [HIGH] tool 路由翻转:
handlePluginTool里显式conversationId现在优先于 outbound witness,两者不一致 →409 TOOL_CONVERSATION_CONFLICT;旧行为是单 witness 胜出(#1685 info log)。这影响所有带显式 id 的 tool POST,不只是新增expectedRevision的用户——PLUGIN.md 里那句「Existing callers omitting it retain their routing and execution behavior」与代码不符。风险通道:dsh persona 分裂会话(raw key 归主 session 所有,子 session 为<id>|sub:<fp>)——host 发 raw id 而 witness 指向 suffixed session 时,master 路由正确、新代码 409。需要流量证据确认没有现存 host 踩中,或把翻转正作用域收窄(例如仅当 resolved session 带publicForkReceipt时才以显式 id 为准)。D-B [MED-HIGH] pluginSnapshot 持久化无界增长:
rememberPluginMessages现在对每个 plugin 请求把完整原始历史(structuredClone(original))存进session.pluginSnapshot,buildRecord无条件落盘且不截断——正是 #401 实测过的重复面(raw full history ≈ corpus 的 63%),外加每 session 三份内存副本(remembered.processed / remembered.original / pluginSnapshot)。契约在 snapshot 缺失时本就 fail-closed(“send a fresh plugin model request”),所以加 tail budget/TTL 与契约兼容;至少也应文档化增长行为。D-C [MED] child 克隆父的整个 messageRefs 命名空间:
child.state.messageRefs = structuredClone(parent.state.messageRefs)含 branch-point 之后的 refs(指向兄弟内容的 raw id;测试钉住追加消息拿到 m00004 ≠ 父 m00003)。今天演示不出内容泄漏(CCR 已按前缀切片、blockContents/snapshot 只含前缀),但污染 child 的 ref 空间:继承摘要若引用 post-branch ref,会在 child 内解析到兄弟历史的 id(decompress/range-restore 报错混乱,未来泄漏面)。计数器(nextBlockId/nextRunId)已防复用,prefix-only 克隆即可满足反复用目标。修,还是明确接受并留理由?小项(不阻塞,拍板后可一并处理)
b.summary.includes(a.summary)子串启发式可能误伤(child 隐藏了一个 stand-in 摘要不在其视图内的原始对)。forkContentStore永久重复 sidecar;reload 时 inline 遮蔽 sidecar;crash 窗口有界)。capabilities.fork)——§7.3 要求 golden 再生成在 PR 描述里写明依据,补一行即可。结构化七问结论
contextTokens字段语义 lastInputTokens→attributed observation(unavailable 时 null);settleUsageReport 现写stats.contextTokens=lastInputTokens("usage")——均在 PR body + PLUGIN.md 披露。parentConversationId/parentRevision而非 derivedFrom 链 → 失去 [pi plugin] Prime RLM inline 派生子会话在代理模式下零继承:搜不到也解压不了父会话压缩块(billion-context-pi#531 同场景) #1333 祖先搜索回退;按 issue 的独立性要求功能上没问题。capabilities.fork为 manifest 无条件通告,goldens 一致再生成)。判定:not merge-ready —— 等你对 D-A / D-B / D-C 拍板;定了我可以按决定把对应修改(含上面 4+1 小项)作为标注 commit 推进到 PR 分支。已推的
ce734975是独立小修,不影响你的设计空间。fix: probe fork child file with session meta and map its conflict to …
fix(#2016): cap public raw-snapshot retention, fail closed (BILI_PUBL…
fix(#2016): cap public raw-snapshot retention, fail closed (BILI_PUBL…
fix: stamp nativeCaller on host-native agent tool forwarding (ranxian…
fix(#2601): model-switch lineage — churn-tolerant chain continuity + …
fix(#2601): model-switch lineage — churn-tolerant chain continuity + …
fix(#2601): model-switch lineage — churn-tolerant chain continuity + …