Two model-facing texts still demoed the retired raw-array shape for
compress content (schema accepts ONE string only; strict hosts reject
the array):
- tierActionHint (kernel/src/compress.ts): tier distillation/
condensation offer — appended to the 'range already compressed'
receipt, exactly where a weak model is most likely to copy it
- armed-breaker format reminder (src/stream.ts): taught 'content'
must be a non-empty array of {startId,endId,summary} objects
Both now mirror the compress tool schema and the nudge example
(content: "b1-b5 optional topic\nsummary markdown..."); PLUGIN.md's
/__bili/plugin/tool example shows the string form with a note that a
JSON-encoded array inside that same string is still accepted.
Tests: regression-bili-470 pins the new wording; issue4812 gains a
negative assert against the old array phrasing. Kernel 1565/1565,
host typecheck green.
33 KiB
billion-context Cooperative Plugin Protocol
Status: protocol v2, experimental. Implemented by the proxy (
src/plugin.ts), exercised bytests/plugin-protocol.test.ts. Issue: dog/billion-context#1 ("内外呼应" — inside/outside cooperation).
Why
Pure proxy mode works with any agent but is blind inside the agent: tools are injected at the wire level, the compress tool-call loop is emulated by intercepting and re-requesting SSE streams, and session identity has to be guessed from headers or content fingerprints. Pure extension mode (see billion-context-pi) has native integration but needs one adapter per agent.
The cooperative plugin mode splits the job:
| Concern | Owner |
|---|---|
| Tool registration (native UI, permissions, audit) | plugin (inside) |
| The agent's own tool loop (multi-round calls) | plugin / agent (inside) |
| Session identity | plugin (inside) — sends the real conversation id |
| Compression engine + state + blocks | proxy (outside) |
| History folding / ref tags / nudges | proxy (outside) |
| Tool schemas + compression philosophy prompt | proxy — single source of truth, served to the plugin |
The plugin is deliberately a thin pipe: it registers whatever tools the manifest serves, forwards executions to the proxy, and returns the result text as a native tool result. Schema/prompt content always comes from the running proxy, so proxy and plugin can never drift.
Protocol
All endpoints live under the proxy's admin gate (loopback + trusted-origin only).
1. GET /__bili/plugin/manifest
Fetch once at plugin startup.
{
"ok": true,
"protocolVersion": 2,
"proxy": "billion-context",
"version": "0.1.42",
"toolNames": ["compress", "decompress", "search_context", "acp_status"],
"tools": {
"anthropic": [ /* Anthropic tool schemas */ ],
"openai": [ /* OpenAI function schemas */ ],
"responses": [ /* Responses API schemas */ ]
},
"headers": {
"agent": "x-bili-plugin",
"conversation": "x-bili-plugin-conversation",
"contextWindow": "x-bili-plugin-context-window",
"maxOutput": "x-bili-plugin-max-output",
"model": "x-bili-plugin-model",
"instructionsMutable": "x-bili-plugin-instructions-mutable",
"compression": "x-bili-plugin-compression"
},
"toolEndpoint": "/__bili/plugin/tool",
"statusEndpoint": "/__bili/plugin/status",
"capabilities": {
"fork": { "protocolVersion": 2, "acceptsProtocolVersions": [1, 2], "endpoint": "/__bili/plugin/fork", "snapshotEndpoint": "/__bili/plugin/snapshot" }
}
}
Register the tools natively with your agent, in whichever wire format your agent speaks — register exactly what toolNames lists. absorb appears only when the proxy's config enables it; acp_rule is advertised only when the proxy's config enables it (compress.rules: true, opt-in). Calling a tool that is known but disabled answers 200 with an explanatory result instead of an error (#1192). If protocolVersion is higher than you know, still register the tools — extra fields in schemas are ignored by agents. headers.compression names an optional per-request override (#4855): when your host keeps the registered ACP tools out of the outgoing request (Hermes defers every plugin toolset behind tool_search), stamp proxy on that header alongside the identity headers — the proxy then keeps the session identity and model budget bound to your conversation but serves compression through its own wire channel (it injects the tools and executes compress server-side). Use it only when advertised; older proxies omit it, and the proxy honors it only from a request that already carries headers.agent.
2. Request headers
On every model request the plugin sends:
-
x-bili-plugin: <agent-name>— announces plugin mode for this session. -
x-bili-plugin-conversation: <conversation-id>— the agent's real conversation/session id, stable for the whole conversation. -
x-bili-plugin-context-window: <tokens>(optional but recommended) — the model's context window as configured inside the agent (e.g. a pinned/overriddencontextWindow). This becomes the authoritative "native" window for nudge decisions — it outranks the proxy's built-in table and the models.dev registry (most valuable for private relays and MITM mode), while operator tuning (compress.modelContextLimit) still outranks it. -
x-bili-plugin-instructions-mutable: 1(optional; send only if true) — declares that your conversation ids are persona-scoped: one id per persona, and the request's system/instructions text may change mid-conversation without changing the persona (e.g. opencode re-renders AGENTS.md intoinstructionson every edit). The proxy now keys plugin conversation ids verbatim by default (#1106), so this flag is vestigial for current proxies — keep stamping it for compatibility with older proxy versions, which use it to stop mixing the instructions text into the compression-namespace fingerprint. -
x-bili-plugin-agent: main(optional) — vetoes side-request demotion for this one request. Requests are otherwise demoted to the verbatim side lane when they look like auxiliary traffic (#388: smallmax_tokens, or a known side persona such as opencode's title generator). A full main turn that re-sends the conversation can still trip those heuristics; stampingmainkeeps it on the kernel path so it captures history, stays compressible and remains forkable. Any other value declares the side persona id itself (it is then matched against the known side-request persona set, not treated asmain).
Every proxied 2xx response carries x-bili-session: <server-side session id> (#4082) — the id the proxy itself keys this conversation by. A client that keeps its own conversation object may store it from any response and send it back as x-bili-plugin-conversation on later requests (retries, model switches, resends after resume), keeping identity stable even when the request is driven from an execution context the plugin cannot attribute. The dsh bridge does this automatically in-process (it learns the mapping while attribution works and re-stamps when it breaks); other hosts may adopt the header directly.
Effects on the proxy for that session:
- Wire-level tool injection is suppressed (tools are native; no duplicates).
- The compress loop never intercepts proxy-named tool calls — a model-emitted
compresscall is forwarded to the agent verbatim, as a normal native tool call. - Session identity is keyed by the conversation id (strongest signal, ahead of all legacy session headers). This also fixes multi-session safety for agents that send no session headers at all.
- The compression philosophy system prompt, ref tags and nudges keep flowing from the proxy, exactly as in wire mode.
3. POST /__bili/plugin/tool
Execute a tool against the conversation's compression state.
{
"conversationId": "the same value you send as x-bili-plugin-conversation",
"tool": "compress",
"args": { "content": "m00001–m00042 optional topic\nsummary markdown..." }
}
content is ONE string holding every range (batch multiple mNNNNN–mNNNNN blocks in one call); a JSON-encoded array of {startId, endId, summary, topic?} objects as that same string is also accepted. A raw JSON array argument is no longer the advertised shape — do not emit one.
Response:
{ "ok": true, "tool": "compress", "conversationId": "...", "outcome": "applied", "blocksCreated": 1, "result": "[Compressed m00001–m00042 → 1 block(s), ~1742 tokens saved.]" }
Return result verbatim as the native tool result content. ok reflects transport + execution only (it stays true when the kernel refuses a fold range — the refusal receipt then sits in result). The machine-readable business outcome rides in the additive outcome field (#1875): for compress it is applied / partial / refused plus blocksCreated; for every other tool success / failure. Older proxies omit both fields; the #1192 disabled-note answer stays exactly { ok: true, result }.
Notes:
- Execution happens under the session lock, against the same view the model was shown on the last request (refs match what the model sees).
- Optional
expectedRevisionis the opaqueparentRevisionfrom a snapshot. It requires an explicitconversationIdand is checked under the same session lock immediately before execution. A stale revision returns409 PARENT_REVISION_CONFLICTwithout executing the tool. This also avoids witness routing to another conversation. Existing callers omitting it retain their routing and execution behavior. compressmutates state. Inlinedecompressmarks a block restored for re-folding; range restores queue content for the next request. Successful restores also update the estimated context footprint.search_context/acp_statusare read-only.- Errors:
400invalid JSON / missingconversationId/ unknown tool,404unknown conversation (no model request has arrived with that conversation id yet),500execution failure. A known but disabled opt-in tool (absorb/acp_rule) is not an error: it answers200withok: trueand aresultexplaining that the feature is off on this proxy (#1192).
4. GET /__bili/plugin/status?conversationId=<id>
Context-level visibility for plugin UIs (status bars / slash commands):
{
"ok": true,
"conversationId": "...",
"sessionId": "...",
"pluginAgent": "pi",
"contextLimit": 200000,
"contextTokens": 138211,
"contextTokensSource": "usage",
"contextTokensAt": 1755300000000,
"contextGeneration": "opaque-generation",
"sessionRevision": "opaque-revision",
"model": "claude-sonnet-4",
"inputTokens": 251000,
"outputTokens": 40021,
"cachedTokens": 180000,
"requests": 42,
"blocks": [{ "id": "b3", "tier": 1, "active": true }],
"lastSeen": 1755300000000
}
contextTokens is the effective current input footprint, not accumulated billing. contextTokensSource is usage only for a real positive upstream input measurement with no outstanding fold credit, estimate for a local projection, or unavailable with contextTokens: null. Manual compress subtracts only its new credit from the previous observation, once; successful decompress adds the returned content (or file pointer) and any newly queued range content. Both publish an independent estimate observation without replacing the last-usage calibration baseline or changing cumulative inputTokens / cachedTokens. Never add those billing fields to infer effective context.
Forwarding a new model request replaces the previous observation with an estimate until a real positive usage report arrives. That report restores usage; zero/missing usage cannot revive an older measured generation. A real report netted against outstanding fold credit remains an estimate of the effective view, not a measurement of that view. Forks start with independent estimates, not inherited parent usage.
contextTokensAt is the observation time in Unix milliseconds (not the status read time), independently of the last usage timestamp. contextGeneration is an opaque change detector covering a unique observation id, context, revision, model and limit: successive observations remain distinct even at the same timestamp with identical token counts; repeated status reads do not create observations. Unavailable context has null tokens, timestamp and generation. Legacy persisted sessions without an independently attributed observation are unavailable until another request establishes one. sessionId and nullable sessionRevision identify the resolved session and its fork state. Pre-first-request/chain-only responses explicitly report unavailable context. Persisted sessions are loaded by the requested id before considering an explicitly requested fallback=latest. Errors: 400 missing conversationId, 404 unknown conversation.
compressibleRanges is the live kernel recommendation as structured {startRef, endRef, count, ...} entries for sessionRevision, or null if it cannot be computed. An empty list means there is no recommended range. Read the exact conversation without fallback=latest, match the snapshot revision and ordered refs, and submit manual compress with expectedRevision; never parse the human panel or guess a fixed prefix. Hosts must exclude their retained first-user anchor from summaries: kernel pruning retains it even if a recommendation spans it. A concurrent mutation is rejected by the revision guard.
5. POST /__bili/plugin/compact
Notify the proxy that the agent performed an in-session native compaction (e.g. omp's /compact or its auto threshold): the next model request re-sends a shortened history (compaction summary + retained tail) under the SAME conversation id. Fire-and-forget is fine — a failed notification must never break the agent's compaction.
{ "conversationId": "the same value you send as x-bili-plugin-conversation" }
Effect: the proxy marks a one-shot compaction boundary on the session. On the next model request, blocks that were active before the compaction but no longer anchor into the shortened history are downgraded to a pre-compaction archive (listed by acp_status with a reason; decompress on one returns an explicit "unavailable" error instead of failing silently), and stale byRaw/byRef mappings are pruned to the live ids. Errors: 400 invalid JSON / missing conversationId, 404 unknown conversation.
6. MITM transparent-proxy mode
The /bili/ prefix is absent in MITM mode, so URL-based detection cannot work. Instead the proxy's own launcher (bili pi / bili codex / bili claude) exports BILLION_CONTEXT_PROXY=http://127.0.0.1:<port> in the child env, next to the HTTPS_PROXY + CA vars it already sets. A plugin detects cooperative mode by reading that env var (the proxy origin for all /__bili/plugin/* calls); everything else (headers, tool forwarding, status) is identical — the x-bili-plugin* headers pass through the MITM tunnel into the same pipeline. This is also where x-bili-plugin-context-window matters most: MITM upstreams are often private relays the models.dev registry doesn't know.
7. Lifecycle of one compression (what the plugin does)
- Model replies with a native
compresstool call (args containstartId/endIdrefs it read from the tag-annotated context). - The agent ends the assistant turn; the plugin's tool handler fires.
- Plugin POSTs
{conversationId, tool: "compress", args}to/__bili/plugin/tool. - Plugin returns
resultas the tool result; the agent appends it to history and re-requests. - The next model request carries the tool call + result in history; the proxy's
processTurnhides the consumed call and folds the compressed range out of the wire body. The summary lives in block state, retrievable viasearch_context/decompress— the same as wire mode.
No special handling is needed for decompression: decompress results come back through the same endpoint.
8. Public snapshot and fork (fork protocol 2; v1 clients still accepted)
Discover capabilities.fork from the manifest; do not infer support from the package version. No new configuration is required. These endpoints use the same admin gate and request-body limit as the tool API.
GET /__bili/plugin/snapshot?conversationId=<stable-parent-id> returns:
{
"ok": true, "protocolVersion": 2, "status": "exact",
"conversationId": "parent", "sessionId": "parent",
"parentRevision": "<opaque SHA-256 revision>",
"orderHash": "<SHA-256 of the full orderedMessages JSON>",
"orderedMessages": [{ "rawId": "h_example", "ref": "m00001", "identityHash": "<opaque SHA-256 identity>" }],
"messages": [{ "rawId": "h_example", "ref": "m00001", "role": "user", "text": "original text", "contentType": "text" }]
}
messages is in exactly the same order as orderedMessages, describes the raw pluginSnapshot rather than a folded view, and includes optional text, toolName, and toolCallId. Compare original text and role to establish the longest matching prefix; tool identities/content type must match too. Copy the corresponding ordered identities verbatim; identityHash and revisions are opaque and clients do not need a content-hash algorithm. A message the kernel hard-excludes from compression (compress.protectedTools) carries "ref": null in both arrays — it participates in ordering and identity but has no addressable ref; copy it verbatim like any other prefix entry. Only mNNNNN strings or null are legal ref values. Multimodal/opaque content that cannot be verified by this text projection returns 409, status: unavailable, code: SNAPSHOT_UNAVAILABLE, not a guessed text match. Missing raw snapshots or inconsistent raw/ref/CCR mappings likewise fail closed. Raw snapshot retention is capped (BILI_PUBLIC_SNAPSHOT_CAP_BYTES, default 16 MiB, 0 disables): a session whose serialized raw snapshot grows past the cap stops being forkable — snapshot/fork answer 409 SNAPSHOT_UNAVAILABLE — instead of retaining an unbounded raw copy forever.
POST /__bili/plugin/fork body:
{
"protocolVersion": 2,
"parentConversationId": "parent", "childConversationId": "new-child",
"parentRevision": "<snapshot.parentRevision>",
"branchPoint": { "messageCount": 1, "orderHash": "<prefix order hash>" },
"orderedMessages": [{ "rawId": "h_example", "ref": "m00001", "identityHash": "<snapshot identity>" }],
"idempotencyKey": "stable-operation-id"
}
protocolVersion is 2 (current) or 1 (legacy) in both directions; the proxy accepts either (acceptsProtocolVersions in the manifest advertises this) and rejects anything newer with 400 INVALID_REQUEST. Under protocol 2 the parentRevision token covers exactly the session id, the ordered-prefix length (messageCount), and the active block set — so routine stats churn (context estimates, usage bookkeeping) no longer changes the revision, while any structural change (messages appended or rewritten, a block folded or unfolded) still does. Protocol-1 clients that present the legacy whole-store revision token are still matched during the transition window; treat parentRevision as opaque in both cases: on 409 PARENT_REVISION_CONFLICT take a fresh snapshot and re-match, regardless of which protocol version you speak.
The branch is an ordered prefix, including an empty prefix. Compute its existing order hash as lowercase SHA-256 of UTF-8 JSON.stringify(orderedMessages) with each identity object's keys in order rawId, ref, identityHash; for a full prefix reuse snapshot orderHash. Do not hash descriptors or folded text. Extra child messages, including a final model reply that has not left the proxy yet, may be appended on the child's first model request after copying the matched prefix.
New success is 201; exact payload replay is 200 with replayed: true, even after restart or later parent changes. Both return status, parentRevision, childRevision, sessionId, branchPoint, inheritedBlocks, and expandedBlocks. Reusing the child id with another parent, key or payload returns 409 CHILD_CONFLICT. Invalid shapes/version/identifiers return 400 INVALID_REQUEST; absent parent returns 404 PARENT_NOT_FOUND; stale parent returns 409 PARENT_REVISION_CONFLICT; altered order/raw/ref/identity returns 409 BRANCH_POINT_CONFLICT. Missing nested originals return 409 PARENT_STATE_INCOMPLETE with status: unavailable. Publication/persistence failure returns 503 FORK_FAILED with status: unavailable and exposes no child; the same request may be retried.
Boundary handling is exact when complete blocks fit inside the prefix, expanded when a block crosses it (crossing summaries are omitted, affected nested descendants are expanded, matched originals are retained), and unavailable when safe reconstruction is impossible. Blocks, nested caches, raw messages, issued ref namespace, token snapshots, rules and prefix CCR payloads are independent copies. Note that the child inherits the parent's ENTIRE issued-ref namespace (dead refs included): refs are never reused, so forks keep allocating fresh refs without colliding with ids a sibling may still hold. The child never reads its parent's later state as a fallback. Registration and first-request resume heuristics do not replace its copied state. With existing persistence enabled, raw snapshots, receipts, nested originals and the child's CCR payloads survive restart; with persistence disabled, durability is not promised. Atomic child publication/idempotency covers concurrent requests to one proxy process; concurrent writers sharing one state directory across processes are not supported by this protocol.
Lineage-only declaration (#2408): a host that cannot drive the full fork protocol (no snapshot matching, e.g. claude --fork-session) may still declare the parent by sending a plain identity register — POST /__bili/plugin/register with conversationId (the fresh child id), identity: true and parentConversationId — from its SessionStart hook. The declaration scopes the proxy's content-match resume inheritance (#1486) to that parent chain, so a byte-exact replay of the parent's wire history seeds refs/blocks on the child's first request, and a non-matching replay falls back to the read-only parent link (#1333). A later register without parentConversationId never erases the declared parent. This is strictly weaker than §8 (no dead-ref namespace, no nudge inheritance, no receipt verification) but needs no snapshot access.
Incremental turns (#3248; not yet advertised in the plugin manifest — detect by trying the endpoint and handling the 503): a host that keeps its own full local history may stop resending it. POST /__bili/plugin/turn (same /__bili/ gate; headers x-bili-plugin + optional x-bili-plugin-model, x-bili-plugin-context-window, x-bili-plugin-max-output) with { conversationId, sinceSeq, resync?, system?, path?, request, messages }. The first turn (or any recovery) sends sinceSeq: 0 + the full messages[] (resync: true is implied on seed — a wholesale replacement never 409s and works whether the canonical is empty or already live); every later turn sends ONLY what the client added since the last ack — including the previous assistant reply (client-owned). request carries anthropic params (model, max_tokens, temperature, top_p, top_k, stop_sequences, stream, tools, tool_choice, metadata, thinking, service_tier, parallel_tool_calls); system is sticky (omit to keep the last one); path defaults to /v1/messages (bare relative rides the lane's default upstream; the /bili/<upstream>/… form is explicit). The response is the upstream body streamed through, with x-bili-applied-seq = the canonical length after applying the delta — echo that value as the next turn's sinceSeq. 409 { error: "seq-mismatch" | "turn-in-flight", serverSeq } means the client MUST recover with a resync turn (sinceSeq: serverSeq if it still has the history, else resync: true full seed). 503 means the lane runs without storage.unified (the canonical log lives in the unified messages table). The lane owns no session identity of its own: the assembled request carries the client's own x-bili-plugin-conversation, so incremental and normal full-resend traffic for one conversation share one session, one fold ledger and one canonical — switching modes needs no ceremony, and a conversation may interleave them (e.g. fall back to full resend while a resync is pending). Folding, nudges, tools and the plugin tool endpoints all work unchanged on the assembled body; the model never sees the difference. v1 caveats: the canonical log is the session's messages table — a turn is acked after the assembled body is persisted (best-effort immediate flush; a crash in between surfaces as 409 → resync), and the pipeline still walks the assembled prefix (O(full) CPU, cheap and zero-hit — the server-authored fast path is tracked on #3248). A resync: true that replaces a diverged canonical records a base-seq epoch (session_ext key inc:base-seq): the stale branch's rows stay in the append-only log for audit, but cold rebuilds slice past them — one resync heals, restarts included. On legacy-only storage (no ext surface) the marker degrades and cold rebuilds serve the full row union (409 → resync once, as before).
Marker divert (#3248 phase 2 — native extensions): instead of switching the provider URL to the turn endpoint, a host may send the incremental body on its ORDINARY model request. Stamp x-bili-plugin-turn: 1 on the request (the lane requires x-bili-plugin too, as for every plugin signal); the body shape — top-level conversationId + sinceSeq + messages, no top-level model — is the final word: a marker'd body that is NOT incremental-shaped rides the normal pipeline byte-identically, so a host may stamp the marker whenever the feature is enabled and only convert turns it wants. Incremental-SHAPED turns are lane traffic and carry the same trust class as the direct turn endpoint (#3343): non-loopback / tunnel / untrusted-origin callers get 403 on them (their capability probe already 403s, so a well-behaved host never sends deltas from afar), and management prefixes (/__bili/, /__acp/) never ride the divert. The lane forwards the assembled request to the ORIGINAL request path (bare or /bili/… — no provider reconfiguration). Capability probe: GET /__bili/plugin/turn → { ok, protocol: 1, feature: "pluginIncrementalTurns", enabled, storage } (loopback-gated like every /__bili/ surface; a 404 = older server, stay full-resend). Gating: rollout feature pluginIncrementalTurns (default 0% = every install byte-identical to before) — enable with rollout.features.pluginIncrementalTurns: true (or a percent) in the bili config, or BILI_ROLLOUT_PLUGIN_INCREMENTAL_TURNS=1; the feature additionally requires a live unified sidecar (shadow or full). When disabled mid-flight the lane answers 503 on incremental-shaped turns — fall back to a plain full-resend request. Reference host wiring: pi rides its before_provider_headers (marker) + before_provider_request (payload replacement) + after_provider_response (ack) extension events; dsh-native rides the fetch patch's beforeSend (body conversion) + headersFor (marker) + onResponse (ack). pi-native inherits the pi wiring unchanged (same extension factory — only proxy discovery differs). opencode rides its http.request hook (an incremental adapter callback appended after routing/stamping swaps the request body via replaceRequestPayload and stamps the marker on the replaced request; acks land on the fetch intercept's onResponse). omp has no header events at all — its native adapter reads the extension-stamped prompt_cache_key body field as the conversation id inside beforeSend, stamps the plugin headers directly on the request init (identity upgrades, never forks: wire mode already resolves the same value via preferPromptCacheKeyIdentity), and acks on onResponse. Non-Anthropic wire shapes (OpenAI tool_calls/role:"tool") are detected by wireMessagesLookAnthropic and left on full resend — the lane's message ingestion is the anthropic wire. Planned turns are single-in-flight per URL and age out after 30s (a network-dead request must not block the URL forever). The shared client state machine lives in src/agent/incremental-client.ts (probe TTL cache, prefix-hash diffing, sticky system, per-conversation dead flag) — new native hosts should reuse it rather than re-implement the diffing.
中文增量要点(#3248):POST /__bili/plugin/turn,首次/恢复用 sinceSeq:0 全量(种子隐含 resync:true,永不 409);此后每轮只发新增(含上一轮 assistant 回复,客户端自持)。响应即上游原文,x-bili-applied-seq 为应用后的长度,下一轮作 sinceSeq 回传。409 必须按 serverSeq 对齐或全量重同步;503 表示未开 storage.unified。会话身份沿用客户端自己的 conversation id——增量与全量重发同一会话可任意切换,折叠/工具/状态栏不变。阶段 2(标记分流):普通模型请求上盖 x-bili-plugin-turn: 1 头 + 增量形状 body(顶层 conversationId/sinceSeq/messages、无顶层 model)即可,增量形状 turn 属 lane 流量,与直连 turn 端点同信任级(#3343):非回环/隧道/不可信源一律 403(其探针本就 403,正常宿主不会远程发增量);管理前缀(/__bili/、/__acp/)永不走分流。lane 按原始 URL 转发;探针 GET /__bili/plugin/turn;开关 rollout pluginIncrementalTurns(默认 0%=零变化,BILI_ROLLOUT_PLUGIN_INCREMENTAL_TURNS=1 或配置强制开)。客户端状态机在 src/agent/incremental-client.ts,新宿主复用勿重写。已接宿主:pi/pi-native(同一扩展工厂,后者零代码继承)、dsh-native(fetch 补丁 beforeSend/headersFor/onResponse)、opencode(http.request 钩子 incremental 适配回调换 body+盖章)、omp(无头事件通道,读 body 里 prompt_cache_key 当会话 id,直接在 init 上盖章);OpenAI 工具形状(tool_calls/role:tool)自动回退全量重发;每 URL 单飞行+30s 过期。
中文集成要点:fork 协议现为 2(服务端同时接受 1);先读取 manifest 能力及 snapshot,按原文、role、工具身份确认匹配前缀,仅提交该前缀的 orderedMessages,不猜测多模态分支点。被 compress.protectedTools 硬排除的消息在两个数组中均为 "ref": null(参与顺序与身份、无地址 ref),与其他前缀条目一样逐字提交;ref 合法值仅 mNNNNN 字符串或 null。父 revision 变化必须重新取快照并重新匹配。子会话使用独立稳定 id,首次请求可追加尚未出站的模型回复,不能重置继承的 refs/blocks。手动摘要使用 snapshot 的 refs 和 expectedRevision: snapshot.parentRevision 调用公开 tool;摘要期间历史发生变化时返回 409,不执行旧摘要。状态栏读取 contextTokens、contextTokensSource、contextTokensAt、model、contextLimit、contextGeneration、sessionId 与 sessionRevision,不得用累计账单 input/cache 冒充有效上下文。手动 compress/decompress 后为独立时间及 generation 的 estimate,不改累计账单或 last-usage 基线;下一次正数 usage 才恢复 usage,零值或缺失 usage 不得复活旧观测。未知来源返回 unavailable,tokens/time/generation 为 null。
Incremental cache-mark updates
GET /__bili/plugin/turn advertises cacheControlRetouch: true when the server
supports changing cache marks on already acknowledged wire messages. This is an
optional protocol-1 extension: clients MUST NOT send it unless the capability
is explicitly true. Older servers can ignore unknown envelope fields; an older
or unadvertised server must receive the original full request when marks move.
A delta can include retouch: [{ index, message }], where index is the
zero-based ordinal in the acknowledged wire history and message is that
complete Anthropic wire message with its current block-level cache_control.
Only those decorations may differ. Tool arguments, thinking signatures and
opaque media bytes must remain identical. The server validates every update
before applying either the delta or its marks. A changed payload, unknown span,
or cold canonical returns 409; the client recovers with its existing full-resync
path. Retouches do not append messages or advance the acknowledgement sequence.
Their warm wire-to-core span map is rebuilt by a seed; no storage schema change
is required. The acknowledged boundary still hashes the original wire bytes.
The OpenCode V2 adapter collects acknowledgements from http.response, using
the outgoing request's turn-id header to correlate them. Its request hook can
therefore send deltas when attached to a proxy without a fetch interceptor.
Security
- The tool endpoints sit behind the
/__bili/admin gate: loopback-only + trusted-origin. A plugin on the same machine as the proxy can call them; nothing else can. - Plugins only need to talk to the proxy on localhost; no extra credentials. Do NOT expose the proxy's plugin endpoints through reverse proxies.
Obligations of a plugin
- Register the tools from the manifest (all of them as listed; the model relies on the full set).
- Send both headers on every model request through the proxy.
- Forward tool executions verbatim; return
resultas the tool result. - Self-disable when not running behind bili (e.g. the agent's baseURL does not point at the proxy) — same convention as billion-context-pi / opencode-acp extensions.
- Keep tool-call ids byte-stable within one conversation, including when projecting it onto another provider. Tool-message identity keys on
toolCallIdas the protocol-stable pairing factor; a projection that rewrites those ids (e.g. sanitizing stored composite ids for a foreign Responses provider) silently loses fold coverage — compressed tool outputs re-enter the wire unfolded (#2396). Canonicalize ids at the host boundary before the payload reaches the proxy; the proxy detects the shape and names it in the fold-drift log, but never repairs onto guessed pairings (see message-identity.md).
Reference
- Proxy implementation:
src/plugin.ts, wiring insrc/server.ts(searchpluginMode). - Tests:
tests/plugin-protocol.test.ts.