Skip to content

feat: enable CCR (acp_retrieve) on host/plugin lanes (#1271) - #1273

Merged
ranxianglei merged 3 commits into
masterfrom
2026-09-24_ccr-plugin-lanes
Sep 25, 2026
Merged

ranxianglei merged 3 commits into
masterfrom
2026-09-24_ccr-plugin-lanes

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What

Wires the billion-context side of the three-repo CCR contract (#1271, follow-up to #1097/#1099 and the #1179 default-on discussion). CCR v1 shipped proxy-mode-only with a hard !pluginMode gate, so no real host lane could turn it on. This enables acp_retrieve on the plugin lanes where the round-trip channel provably works.

Changes

  • Manifest (src/plugin.ts): handlePluginManifest advertises acp_retrieve only while ccr.enabled (the dsh acp rule报错 #1192 conservative rule), on the anthropic + openai wires only — never responses, which the proxy disarms CCR on in plugin mode (advertising would guarantee a rejected call). Custom ccr.toolName honored.
  • Arming gate (src/server.ts): the session CCR stamp now allows plugin mode on exactly the round-trippable wires via ccrPluginWireOk(protocol). responses/google stay out so a placeholder is never emitted where it cannot be retrieved (silent loss, Feature: content-addressed message store — ID-referenced tool results + acp_retrieve (built-in CCR) #1097).
  • Drain (src/server.ts prepareAnthropic/prepareOpenai): in plugin mode the pending retrieval is drained so the full original rides back as a request-only trailing message (ephemeral, never persisted into the agent's history).
  • Config threading (src/server.ts manifest call site): global compress.ccr is threaded into the manifest config so advertising reflects operator config, not just the kernel default.
  • src/store.ts: new PLUGIN_CCR_WIRES set + ccrPluginWireOk() — single source of truth for wire scoping; the arming gate and drain sites stay in lockstep with it.

⚠️ Behavior change (disclosed per policy)

Scope note (three-repo issue)

This is the billion-context half of #1271. The companion work lives elsewhere and is sequenced manually per repo policy:

  • billion-context-pi: its own config surface + registering acp_retrieve in the pi package's native ACP pipeline.
  • acp-kernel: nothing blocking (0.0.86 already exports the full host contract).

The e2e here simulates a plugin-lane client (fake upstream, zero tokens) driving the proxy-side machinery end-to-end; the true pi-package dogfood milestone (the remaining acceptance item) lands once billion-context-pi ships its side.

Tests

New tests/ccr-plugin.test.ts (5 tests):

  1. manifest does not advertise acp_retrieve by default;
  2. advertises on anthropic+openai only when enabled, never responses;
  3. custom ccr.toolName honored;
  4. PLUGIN_CCR_WIRES / ccrPluginWireOk wire-scope truth table;
  5. plugin-lane e2e: oversized tool result → stored + placeholdered on the wire → acp_retrieve → full original rides back exactly once.

Pre-flight on rebased head (current master 8e5eb582): typecheck ✓, build ✓, full suite 2506 tests / 0 fail / 9 skipped (skips are upstream-gated claude-native live e2e subtests).

Part of #1271

CCR v1 shipped proxy-mode-only with a hard !pluginMode gate, so no real lane
could turn it on. This wires the bili side of the three-repo contract:

- plugin manifest advertises acp_retrieve only while ccr.enabled (#1192 rule),
  on anthropic/openai wires only — never responses, which the proxy disarms.
- arming gate now allows plugin mode on exactly those round-trippable wires
  (ccrPluginWireOk); responses/google stay out so a placeholder is never
  emitted where it cannot be retrieved (silent loss, #1097).
- prepare* drains pending retrievals in plugin mode so the full original rides
  back request-only (ephemeral, never persisted).
- global ccr config threaded into the manifest so advertising reflects operator
  config, not just the kernel default.

Adds tests/ccr-plugin.test.ts: manifest scoping + wire-scope unit tests + a
plugin-lane e2e (fake upstream, zero tokens) proving store->placeholder->
retrieve->full-text round-trip.
@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-24_ccr-plugin-lanes (eb3a95c)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-1273

Each push to this PR publishes a new version under the pr-1273 npm tag.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1273.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] 🏷 Reviewing PR #1273 (CCR on plugin lanes) now — pulling the branch, checking CI, and walking the diff against current master before I report. Full review verdict (with regression checklist) to follow shortly.

…#1271)

Reviewer fix: the behavior change disclosed in the PR body (plugin mode arms
CCR on anthropic/openai wires while acp_retrieve is manifest-advertised) was
not mirrored in the docs, which still stated 'proxy mode only / native-tools
wires only' as the v1 scope gate.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review complete — verdict: mergeable (one docs fix already pushed to the branch; one cross-PR hazard flagged for merge ordering). Details below.

① Direction / original issue (#1271)

Correct half of the three-repo contract, and it fixes the root cause at the decision point rather than masking: the hard !pluginMode disarm in the arming gate is replaced by wire-scoped permission (ccrPluginWireOk), and advertising is added at the source (manifest) under the same #1192 conservative rule. The fail-closed scoping (placeholder only where a proven request-only round-trip exists) matches the #1097/#1192 design intent; responses/google stay out for exactly the documented reasons.

② Regression audit (existing behaviors touched)

  • Proxy mode: byte-identical. The new gate evaluates !pluginMode || … → true for proxy sessions, so storeEffectiveCcr conditions are unchanged there.
  • responses/google wires: unchanged in both modes (still disarmed in plugin mode via the gate; storeChannelOk untouched).
  • Manifest conservative rule: preserved — advertise only while enabled; custom toolName honored; responses array deliberately not extended (advertising there would guarantee rejected calls). Verified against handlePluginManifest.
  • Prefix cache / wire stability: drain appends trailing messages only when a retrieval is actually pending (i.e., the turn right after an acp_retrieve call), after the image-compression pass, before wire conversion. All other forwards are byte-stable.
  • Persistence: snapshotMessages(session, originalMessages) snapshots the originals; drained injections live only in processedMessages, which is rebuilt per request — ephemeral as claimed. Kernel side guarantees this too: injection ids carry acp_retrieved_ prefix, structurally excluded from ref assignment and fold space, so the id-never-reused invariant holds.
  • Dispatch path: pre-existing on master — isProxyToolFor (src/absorb.ts:49-58) already accepts acp_retrieve/custom name for armed sessions, and disabledOptionalToolNote covers the disarmed case gracefully. No dispatch change needed; verified.

③ Code

Read all four changed files end-to-end plus the kernel contract (buildRetrievalInjection, coreToAnthropic/coreToOpenai). Two load-bearing checks that pass:

  • Anthropic role alternation: coreToAnthropic merges every non-assistant message (including the drained role:"system" injection) into user turns — no consecutive-role violation can arise from the trailing append.
  • OpenAI path: systemToUser(hardenOpenaiAssistantContent(coreToOpenai(...))) re-voices system→user in place; identical conversion proxy mode already ships (drain sites at src/loop/core.ts:704 etc.). This reuses a proven mechanism, not a novel one.
  • Config threading at the manifest site correctly layers global CCR over kernel defaults; per-provider/model overrides stay execution-side only, which is the conservative direction (advertised-but-off returns the disabled note; on-but-unadvertised simply doesn't register).

④ Test quality

The 5 tests have teeth: advertising truth-table including the negative (never responses), wire-scope boundary values for ccrPluginWireOk, custom toolName, and a real startServer e2e proving placeholder-on-wire + no-original-leak → retrieve → full original rides back. Deterministic (port via listen(0), BILI_PERSIST=0, stubbed registry). Minor nit (not blocking): the e2e drives executeRetrieve directly instead of POSTing /__bili/plugin/tool — acceptable since that dispatch path is master code covered elsewhere.

⑤ Diff & evidence

Clean single-purpose diff (+255/−16, 4 files, no churn). Evidence on head 9a869811: local typecheck ✓, build ✓, full suite 2506 pass / 0 fail / 9 skipped (one non-reproducible flake in my first local run; clean rerun); CI 9/9 green including both real-client e2e lanes (real pi package-native, real codex vs fake upstream). Base was current master (8e5eb582) — no stale-base risk.

Fixed directly on the branch (reviewer commit)

Docs lagged the disclosed behavior change — README.md:75, CONFIGURATION.md:367/374, CONFIGURATION.zh-CN.md:367/374 still stated "proxy mode only / native-tools wires only" as the v1 scope gate. Pushed 0a24e753 (docs-only, en+zh updated to "proxy mode + plugin lanes on anthropic/openai while advertised"). CI re-running on it: build-artifact, version-guard, and both real-client e2e lanes already green; test matrix completing. I'll confirm when it finishes.

Findings (not blocking this PR)

  1. ⚠️ Merge-order hazard with open PR feat: CCR v2 — covered-ref spans, range-level decompress, ID-returning search_context; CCR default-on (#1179) #1207 (CCR v2, default-on). feat: CCR v2 — covered-ref spans, range-level decompress, ID-returning search_context; CCR default-on (#1179) #1207 flips the resolved default to ON inside resolveCompress, but feat: enable CCR (acp_retrieve) on host/plugin lanes (#1271) #1273's manifest threading reads the raw global view. If both land without adjustment, zero-config plugin-lane sessions would be ARMED (placeholders emitted) while the manifest advertises nothing → hosts never register acp_retrieve → silent loss, precisely what dsh acp rule报错 #1192 designed out. Recommended order: merge this PR first, then land feat: CCR v2 — covered-ref spans, range-level decompress, ID-returning search_context; CCR default-on (#1179) #1207 with one added hunk making the manifest ccr view honor the same default-on rule (plus a test pinning advertisement-vs-gating under unset config). Commented on feat: CCR v2 — covered-ref spans, range-level decompress, ID-returning search_context; CCR default-on (#1179) #1207 with the full analysis.
  2. Pre-existing gap (out of scope, flagged for owner judgment): the manifest reads absorb/rules from raw opts.kernelConfig (pure kernel defaults, always enabled:false), so file-level compress.absorb/rules enablement is never advertised to MCP-based plugin lanes (dsh/kimi/zcode register manifest tools verbatim), even though the execution side honors file config. This PR fixes exactly this pattern for CCR but leaves absorb/rules behind. Per loop guard I'm not filing a separate issue from this auto-triggered thread — say the word if you want it tracked.
  3. Cosmetic, pre-existing: README.zh-CN.md has no CCR paragraph at all (en-only section). Noted, not touched.

中文摘要:本 PR 在插件通道(anthropic/openai wire)上按线启用 CCR 并同步声明 acp_retrieve,方向正确、代理模式与 responses/google 行为完全不变、wire 安全与临时性均有内核保证,测试有牙且全绿(本地 2506/0 fail,CI 9/9);我已在分支上补了一个纯文档 commit 修正 README/CONFIGURATION 中过时的"仅代理模式"范围描述,可以合并——但请注意与 #1207(CCR 默认开启)的合并顺序:先合本 PR,#1207 落地时须同步更新 manifest 的 ccr 视图,否则会出现"已武装但未声明工具"的静默丢失。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 CI confirmation: docs commit 0a24e753 is now 9/9 green (all four test-matrix jobs — ubuntu 24/22, windows 24/22 — plus build-artifact, version-guard, and both real-client e2e lanes). The branch is ready to merge whenever you are; remember the #1207 ordering note from my review above (merge this first; #1207 must then update the manifest ccr view when it flips the default).

中文摘要:文档修正 commit CI 全绿(9/9),分支可合并。

…ding retrievals on disarm

Review follow-ups for #1273:

- The plugin arm now also requires opts.compress.ccr.enabled === true — the
  exact source the plugin manifest reads (server.ts:969). Route/model-scoped
  enablement with the base flag off previously armed the store and emitted
  placeholders while the manifest never advertised acp_retrieve: silent loss.
  Route-scoped-only enablement stays proxy-mode-only (the proxy injects the
  tool itself, per-request).
- storeEffectiveCcr(undefined) now clears pendingRetrievals: a retrieve queued
  on a lane that later switches to a non-CCR wire would otherwise flush as a
  stale trailing full-text message when the lane re-arms. Not persisted either
  way; this only tightens the in-memory window.
- e2e: acp_retrieve now driven through the real POST /__bili/plugin/tool
  endpoint (covers the conversation gate + ack round-trip), and a new
  regression test pins both halves of the route-scoped behavior (plugin lane
  verbatim, proxy lane armed).

Fixes #1273 (review)
@ranxianglei

Copy link
Copy Markdown
Owner Author

Review follow-ups landed at eb3a95c (same branch):

Blocker fixed — plugin arm now gates on the manifest's exact source. pluginCcrOk additionally requires opts.compress.ccr.enabled === true; that field is precisely what handlePluginManifest merges in (server.ts:969), so the plugin lane can never arm while the manifest stays silent — route/model-scoped-only enablement stays proxy-mode-only, where the proxy injects the tool itself per-request. Regression test pins both halves: plugin lane forwards the oversized result byte-exact with zero armed sessions; proxy lane arms and emits the placeholder off the same route-scoped config.

Stale-injection window closed. storeEffectiveCcr(undefined) now drops pendingRetrievals (a retrieve queued on a lane that later lands on a non-CCR wire would otherwise flush as a stale trailing full-text message on a future re-arm; not persisted either way — this only tightens the in-memory window).

Test realism. The e2e retrieve now goes through the real POST /__bili/plugin/tool endpoint (conversation gate + ack round-trip covered), replacing the direct executeRetrieve call.

Gates on eb3a95c: typecheck clean, 2507 tests 0 fail (9 e2e-gated skips), build clean.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Follow-ups at eb3a95c verified — all three hold up. Branch is ready to merge.

① Base-config arm gate (the blocker). Confirmed in code: pluginCcrOk = !pluginMode || (ccrPluginWireOk(protocol) && opts.compress.ccr?.enabled === true) — the plugin branch now requires exactly the field handlePluginManifest reads (opts.compress.ccr, server.ts:969), so arm and advertise share one source and can never diverge. Two properties I checked specifically:

② Disarm drops pending retrievals. Safe: session.pendingRetrievals is a required Session field initialized to [] at construction (src/session.ts:199/337), so .length = 0 cannot throw on any path. Semantics strictly tighten — the stale trailing full-text flush on a later re-arm is gone; nothing persisted either way, so no data impact beyond closing the in-memory window. Armed-session behavior unchanged (clear only runs when ccr === undefined).

③ Test realism. The e2e retrieve now goes through the real POST /__bili/plugin/tool endpoint (conversation gate + ack round-trip asserted) — my earlier nit is addressed. The new route-scoped regression test has teeth on both halves: plugin lane asserts byte-exact verbatim forward, zero [acp-stored, and zero armed sessions; proxy lane asserts the placeholder appears and the original doesn't leak. That pair pins the exact invariant the gate encodes.

Evidence on eb3a95c: local typecheck ✓, build ✓, tests/ccr-plugin.test.ts 6/6 ✓, full suite 2507 pass / 0 fail / 9 skipped (exit 0) — matches your reported gates; CI 9/9 green including both real-client e2e lanes (real pi package-native, real codex vs fake upstream). Diff of the follow-up is minimal and single-purpose (+76/−8 across 3 files, all commented citing review #1273).

Nothing left on my side — merge whenever you're ready (human-only, per repo rules).

中文摘要:已逐条核实 eb3a95c 的三项跟进——插件通道武装现在与 manifest 共用同一配置源(从根本上消除与 #1207 的合并顺序隐患)、解除武装时清空待注入队列(字段恒有初始化,无风险)、e2e 改走真实 tool 端点并新增双向回归测试;本地 2507/0 fail、CI 9/9 全绿,分支可以合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Coordination note (from the #1281 review): open PR #1281 (fix: advertise absorb/acp_rule in plugin manifest when globally enabled) edits the same /__bili/plugin/manifest call site in src/server.ts — resolving global settings via applyCompressSettings(config, opts.modelContextLimit, opts.compress) — and #1281 just rebased onto current master and is green/mergeable.

No conflict with master today, but whichever of the two merges second will hit a textual conflict on that one line. Suggested union resolution: keep #1281's applyCompressSettings(...) line as-is — it already layers the global ccr block from opts.compress (see src/compress-settings.ts, the s.ccr → ccr mapping with DEFAULT_CCR_CONFIG floor), so it subsumes this PR's manual { ...config, ccr: { ...DEFAULT_CCR_CONFIG, ...config.ccr, ...opts.compress.ccr } } spread; this PR's handlePluginManifest extension (ccrOn) then works unchanged on top of the resolved config. If #1273 lands first, #1281's rebase is trivial (drop its call-site hunk, keep the import + tests). Flagging so the merge order is a conscious choice rather than a surprise conflict.

@ranxianglei
ranxianglei merged commit a37e018 into master Sep 25, 2026
9 checks passed
ranxianglei pushed a commit that referenced this pull request Sep 25, 2026
…ema legitimately shifts the recent-window boundary (#1207 rebase onto #1189/#1273/#1270)
@github-actions github-actions Bot mentioned this pull request Sep 25, 2026
@ranxianglei
ranxianglei deleted the 2026-09-24_ccr-plugin-lanes branch October 15, 2026 05:32
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.

1 participant