Skip to content

feat(plugin): public isolated conversation forks and attributed context observations #2016

Closed

Description

@yingzhongshuoqi

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 exact or expanded semantics 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

  1. ranxianglei commented on Oct 3, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [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.ts CCR sidecar)以及既有状态拷贝先例 src/fork-adoption.ts 的可复用面;③ billing/cache ledger(src/cache-ledger.ts)与 effective-context 观测的现状边界。之后按结构化体例给出方案对比与需要你拍板的决策点。

  2. ranxianglei commented on Oct 3, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [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:

    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:

    • Session id = client-provided conversation value verbatim (src/server.ts:2076-2082); plugin requests key by x-bili-plugin-conversation. A pre-seeded child session file with id == childConversationId is 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 and meta.label == id (boot migration rekeys/deletes label≠id records unless pfa-*, src/persist.ts:428+).
    • Copy-on-fork machinery already exists and is battle-tested: planForkAdoption/applyForkAdoption (src/fork-adoption.ts) — set-semantics adoptability (block adoptable iff every effectiveMessageIds is present), tier-block closure dragging, CCR slice via cloneStoreForRefs, kernel ref cursor = highestUsedIndex+1 so seeded refs push new assignments above the parent's space (id-never-reused holds).
    • Refs are assigned in message order and never reused ⇒ numeric ref order IS view order (src/cache-ledger.ts:169-172) — ordered-prefix proofs are well-defined over messageRefs.byRef sorted numerically.
    • The billing ledger (CacheLedger, metadata.cacheLedger) is cumulative per-request attribution — a separate concept from a live context observation, and nothing in the proposed design touches it.
    • One real retention limit: compressed-block originals are stored as one text blob per block (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:

    • Manifest gains: 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 ordered prefixProof re-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 unless requireSemantics: "expanded" explicitly requested, with the exact gaps enumerated.

    Seed mechanics (the correctness core): everything runs under withSessionLock(parent); seed = generalization of planForkAdoption from set-semantics to prefix-semantics (incomingIds := all raws with ref ≤ branch):

    • refs ≤ branch copied into child messageRefs (counters take parent's current nextBlockId/nextRunId — conservative, gaps legal, reuse impossible);
    • blocks adopted iff fully contained in the prefix (all 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;
    • blockContents copied 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);
    • child gets fresh stats + fresh CacheLedger (billing isolation), copied protocol/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);
    • child session file + .content-store.json sidecar written synchronously before the 201 returns (writeNow path 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's blockContents (nothing lost proxy-side); "expanded" = some refs ≤ branch are unrecoverable (compaction-archive-pruned raws, evicted CCR entries) — enumerated in missingOriginals. A summary is never reported as recoverable original content.
    • Idempotency receipts persist in 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 on GET /__bili/plugin/status and in snapshots:

    observation: { tokens, source: "usage"|"estimate"|"overflow-arm", at, model, window, generation, stale }
    

    Stamped from the same places contextTokens/lastInputTokens provenance tiers (#857/#1839) are stamped today, plus model/window from the request context. Every manual state change (compress/decompress/absorb/fork-seed/compaction boundary) bumps generation, marks stale: 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, and compressCreditTokens netting 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)

    1. Branch point inside an active block: support it (my recommendation — seed excludes the not-yet-born straddling block; the client's own re-sent history supplies those originals) vs reject-with-nearest-valid-points. Supporting it costs nothing extra given the seed math above.
    2. Child conversation id: host-supplied (my recommendation — the host must know the id before the child's first request; idempotency makes retries safe) vs proxy-minted. Validation: non-empty, length-capped, no collision with resident/bound/disk sessions.
    3. Default-on behind the existing admin gate (my recommendation — loopback-only exposure, manifest-advertised like the other plugin endpoints) vs a new opt-in env kill-switch (would be the only new config surface; I'd avoid it).
    4. Persistence surface grows: child session records, forkReceipts in parent metadata, the observation field. 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.
    5. Receipt cap: 256 idempotency receipts per parent, oldest evicted — fine?

    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.ts is new-file scoped); if it merges first its clone helpers may be reusable. server.ts/plugin.ts/session.ts are 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.

  3. yingzhongshuoqi commented on Oct 3, 2026

    @yingzhongshuoqi
    ContributorAuthor

    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.

  4. ranxianglei commented on Oct 3, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 PR #2017 独立 review 完成(draft,非合并建议)。结论先行:方向正确、测试质量高、验收清单逐项有真断言;但还有 3 项需要拍板的设计决策,另有 1 处我直接修掉的小问题(已推 commit)。当前 not merge-ready。

    验证证据(本地定向,全量回归留给 CI)

    • base = 当前 master(33d58e5e),不陈旧 ✓
    • typecheck 基线对比(你留 pending 的部分,已做完):head 上的错误全部落在 4 个未改动的上游测试文件(codex-responses-ws / issue1987-preflight-baseline-anchor / issue1993-preflight-400 / ws-bridge),与 origin/master 基线逐条一致;PR 本身与我的修复引入的增量诊断 = 0 ✓
    • 定向套件本地全绿:plugin-fork(20)+ plugin-status-provenance(7)+ tool-ring + wire-contract = 66/66,含真实 loopback proxy + mock upstream + spawn 第二进程真重启 ✓
    • 你之前全量套件的 2 个失败(main-path-transport-retry / tunnel-guard,传输层 DNS 断言)与本 diff 路径无关,等 CI 确认归属。

    已直接修掉并推送(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 克隆即可满足反复用目标。修,还是明确接受并留理由?

    小项(不阻塞,拍板后可一并处理)

    1. observation 失效缺口:absorb(隐藏原始对、上下文收缩)不触发任何失效条件(creditDelta/lastCompress/decompress 正则)→ observation 停在 stale-high 直到下个 usage report;acp_retrieve 注入只在 decompress 正则命中时计数。验收标准说 manual state changes 应失效,absorb 属于此类。
    2. status 端点每次轮询重算 forkSnapshot(全状态 sha256,含 blockContents + contentStore 文本)——高频廉价端点上做 MB 级工作;建议 bump-on-write 缓存 revision。
    3. absorbed 过滤的 b.summary.includes(a.summary) 子串启发式可能误伤(child 隐藏了一个 stand-in 摘要不在其视图内的原始对)。
    4. receipt session 双份 CCR 持久化(inline forkContentStore 永久重复 sidecar;reload 时 inline 遮蔽 sidecar;crash 窗口有界)。
    5. 流程项:wire-contract goldens 变了(manifest 两个 golden 加 capabilities.fork)——§7.3 要求 golden 再生成在 PR 描述里写明依据,补一行即可。

    结构化七问结论

    1. 是什么问题:非缺陷——显式外部插件 API 功能需求(feat(plugin): public isolated conversation forks and attributed context observations #2016):公共有序前缀会话分叉 + 归因化有效上下文观测,服务 Ekko Studio 类外部 host。
    2. 什么原因导致(为何需要):host 目前没有公共契约能在选定历史点安全分支(复用父 ID 泄漏兄弟变更;私有持久化 helper 不是安全集成边界);手动压缩/解压后无法区分有效 live context 与 provider 计费台账。
    3. 怎么修复的:host-facing snapshot/fork 端点(不是 model tools),revision + 有序前缀证明 fail-closed,copy-on-fork blocks/originals/CCR 切片,首请求验证门,独立 observation 对象与 CacheLedger 分离。方向正确,复用既有机制(withSessionLock / flushSync / cloneStoreForRefs / fork-adoption 语义),无架构转向。
    4. 是否有回归问题:diff 触碰路径逐项审过——1 HIGH(D-A 路由翻转)、1 MED-HIGH(D-B snapshot 增长)、1 MED(D-C refs 克隆)、4 个小项如上;其余保持既有行为(nudge 仍读 lastInputTokens;计费累计不变——provenance 套件钉死 [17000,3000] 等值;PERSIST_VERSION 不变,新字段可选且新旧双向兼容;manifest capability 纯增量)。已披露的行为变化:status contextTokens 字段语义 lastInputTokens→attributed observation(unavailable 时 null);settleUsageReport 现写 stats.contextTokens=lastInputTokens("usage")——均在 PR body + PLUGIN.md 披露。
    5. 是否破坏缓存:否。prefix-cache 语义不动(head system 字节稳定、CCR 内容寻址去重保留);status revision 重算是 CPU 成本不是缓存失效。唯一副作用:pluginSnapshot 增大磁盘体积,restart hydration 读写字节变多(正确性无关)。
    6. 是否改了设计方向:否。一处偏差注明:child 用自定义 parentConversationId/parentRevision 而非 derivedFrom 链 → 失去 [pi plugin] Prime RLM inline 派生子会话在代理模式下零继承:搜不到也解压不了父会话压缩块(billion-context-pi#531 同场景) #1333 祖先搜索回退;按 issue 的独立性要求功能上没问题。
    7. 是否引入新配置:无(env/config/flag/version 均未动;capabilities.fork 为 manifest 无条件通告,goldens 一致再生成)。

    判定:not merge-ready —— 等你对 D-A / D-B / D-C 拍板;定了我可以按决定把对应修改(含上面 4+1 小项)作为标注 commit 推进到 PR 分支。已推的 ce734975 是独立小修,不影响你的设计空间。

  5. added 3 commits that reference this issue on Oct 4, 2026
  6. added 3 commits that reference this issue on Oct 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions