Skip to content

fix: plugin manifest / session-effective ccr toolName divergence (#1345) - #1352

Closed
ranxianglei wants to merge 1 commit into
masterfrom
2026-09-25_plugin-ccr-toolname
Closed

ranxianglei wants to merge 1 commit into
masterfrom
2026-09-25_plugin-ccr-toolname

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Fixes #1345

What & why

ccr.toolName merges deepest-wins (global → provider → model), but the plugin manifest reads only the base config — a provider/model-level override left the host registering acp_retrieve while the runtime dispatched under retrieve_original: the model's calls rejected as unknown/disabled tools, CCR otherwise reporting enabled, zero diagnostics. Silent half-applied config.

Implements the issue's preferred direction (option 1: normalize with a visible load-time signal) — option 2 (alias registry) stays rejected for the same #1192 reason: it makes the static manifest surface dynamic.

Fix

Plugin mode stamps the session under the ADVERTISED name (src/store.ts):

  • advertisedRetrieveToolName(ccr) — the base-config name the manifest serves (extracted; handlePluginManifest now uses the same helper = single source of truth);
  • normalizePluginCcrName(stamped, optsCcr, session, log) — folds a divergent resolved toolName back to the advertised name (all sub-fields — enabled, minToolTokens, excludeTools, maxHeadChars — ride along untouched), warns once per session;
  • server.ts applies it to the CCR stamp in plugin mode only — proxy mode injects the tool per-request under the session-effective name, so per-route renaming keeps working on all four proxy wires (acceptance criterion);
  • config.ts warnCcrToolNameOverrides(routes, globalCcr) fires at loadOptions time and names the level, the rejected value, and the effective base name for both provider- and model-level overrides (acceptance criterion: load-time diagnostic, never the model's first tool call). Route/model levels keep control over every other CCR sub-field.

Model switching within a plugin session can no longer split the registered surface from the effective config: whatever the deepest resolution produces, the stamp is normalized before storeEffectiveCcr, so gate (retrieveToolName(session)), placeholder hints (buildStoredPlaceholder), and manifest always agree.

Tests

tests/issue1345-plugin-ccr-name.test.ts (new, 4):

  1. divergent override normalized to the advertised name, sub-fields intact, warned once (sticky per session);
  2. matching name (explicit or both-default) passes through untouched (identical reference);
  3. stamped session dispatches under the advertised name end-to-end (retrieveToolName(session) == manifest);
  4. manifest advertises the base name while provider+model overrides exist, and warnCcrToolNameOverrides logs both levels with the naming pattern (matching names stay silent).

Existing store/ccr-plugin/ccr-v2: 31/31 unaffected. Typecheck 0. Red-on-master: import failure (new API).

ccr.toolName merges deepest-wins across global → provider → model, but
the plugin manifest reads only the base config — a provider/model-level
override left the host registering one name while execution gated on
another, so the model's calls were rejected as unknown tools with CCR
reporting enabled.

Plugin mode now stamps the session under the ADVERTISED name:

- store.ts: advertisedRetrieveToolName() = the base-config name the
  manifest serves; normalizePluginCcrName() folds a divergent resolved
  toolName back to it (sub-fields untouched), warns once per session.
- plugin.ts: manifest name comes from the same helper (single source).
- server.ts: the session stamp is normalized in plugin mode only — proxy
  mode injects per-request under the session name, so per-route
  renaming keeps working there.
- config.ts: warnCcrToolNameOverrides() at load names the level, the
  rejected value, and the effective base name — a half-applied override
  surfaces at load time, never at the model's first tool call.

Fixes #1345
@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-25_plugin-ccr-toolname (0b0e593)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-1352

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

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1352.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] 🏷 Review verdict: correct within its narrow scope, but the scope is incomplete against the contract approved in #1345 — superseded by #1360. Closing this PR; details below.

What I verified

Pulled 2026-09-25_plugin-ccr-toolname @ 0b0e5933, read every hunk, traced the call sites, and ran local pre-flight on the head: tsc --noEmit clean, tests/issue1345-plugin-ccr-name.test.ts 4/4 pass. CI on the head is fully green (test ubuntu/windows 22+24, e2e, hermetic registry, codex/pi lanes, build-artifact, version-guard).

① Original issue (#1345) — direction check

The bug is real and the mechanism was confirmed during #1345 triage: the manifest is built from the GLOBAL view only (src/server.ts:981 — handlePluginManifest(res, applyCompressSettings(config, opts.modelContextLimit, opts.compress))), while the session stamp resolves deepest-wins. A provider/model toolName override therefore splits the registered surface from the dispatched name. Option 1 (normalize + visible signal) is the issue's preferred direction; rejecting the alias registry for the #1192 reason is right. ✅

② Regression review — existing behaviors on the touched paths

Touched path Existing behavior Verdict
handlePluginManifest (src/plugin.ts:570) advertises config.ccr?.toolName ?? RETRIEVE_TOOL_NAME from the base block preserved — pure extraction into advertisedRetrieveToolName, semantics identical
CCR stamp site (src/server.ts:1855) arm iff injectTool && pluginCcrOk && storeChannelOk && resolved.enabled === true; pluginCcrOk gates on BASE enabled (#1273) preserved — condition unchanged; normalization inserted strictly inside pluginMode (owner requirement honored)
Proxy mode, all four wires per-route rename works (proxy declares+dispatches per request) preserved — byte-unchanged path
loadOptions builds options from file+env+flags preserved — additive warn-only call, no option mutation

Behavior changes are disclosed in the PR body (plugin sessions now dispatch under the base name when an override diverged; new load-time + per-session warnings) — Deliverables rule 4 satisfied. ✅

③ Code review

The implementation of what it sets out to do is correct: fast-path returns the identical reference when names match, the sticky session.metadata.ccrNameOverrideWarned flag makes the runtime warn fire once per session, sub-fields ride along untouched, and the load-time diagnostic names level + rejected value + effective base name (acceptance criterion 5). Two nits:

  • Nit: warnCcrToolNameOverrides runs inside loadOptions, and the web hot-reload path calls loadOptions() three times (src/server.ts:5358-5360) — so a reload logs the same warning up to 3× instead of once per config load.
  • Nit: the actual wiring line in server.ts (if (pluginMode && ccrCfg) …) is never exercised through handle() — test 3 calls storeEffectiveCcr(normalizePluginCcrName(…)) manually. Deleting that one line would leave all four tests green.

④ Test validity

The 4 new tests are real (exact-string assertions, sticky-flag check, reference-identity check, live manifest render) — but they pin only the toolName field, and none of them drives the real request pipeline.

⑤ Diff cleanliness

Clean: 1 commit, 5 files, every line relevant. ✅

The decisive finding — the enabled half of the same root cause

BsoBird's approved direction in #1345 (floor 5) widened the contract deliberately: "in plugin mode the whole ccr block follows the base config (arm iff base enabled; toolName = base name)" — because a divergent enabled produces the identical failure class through a different field. This PR does not fix that case, and its body concedes it ("Route/model levels keep control over every other CCR sub-field"):

base:    compress.ccr.enabled = true      → manifest advertises acp_retrieve
provider: compress.ccr.enabled = false    → merged stamp has enabled=false

Trace on this branch: resolvedCcrCfg?.enabled === true fails → ccrCfg = undefined → storeEffectiveCcr(session, undefined) → session disarmed → the host-registered, manifest-advertised acp_retrieve is rejected as unknown/disabled on the model's first call. Silent half-applied config — exactly the defect #1345 reports, still present, no diagnostic, no test.

Duplicate situation & action taken

PR #1360 (same account, opened later in the #1345 thread) implements the full approved scope, and I reviewed its diff to substantiate the superset claim rather than trust the description:

  • stamp site executes the base block verbatim in plugin mode (arms iff base enabled: true) — fixes both the toolName and the enabled divergence; proxy mode unchanged, verified by e2e;
  • ccrLoopConfig() makes the session stamp the single CCR policy source at all eight processTurn sites (incl. preflight, countTokens previews, compact handoff, plugin status) — which also closes the test-gap above, since fix(ccr): plugin-mode sessions execute the base ccr block exclusively #1360's e2e tests drive the real handle() path;
  • findCcrPluginDivergences() reports every divergent field at both levels (per-field value + effective value), once per config load, and the hot-reload triple loadOptions() collapse fixes my nit above;
  • e2e regression tests for both divergences (manifest/base-name/store/retrieve round-trip/renamed-name-400 on the plugin lane; proxy lane keeps the rename / honors enabled=false), plus unit tests for the divergence scanner and the load-time diagnostic;
  • CONFIGURATION.md + zh-CN doc sync for the new governance contract.

CI on #1360 is fully green as well.

Per the one-issue-one-PR loop guard, #1345 cannot carry both — and merging this PR first would additionally plant a semantic conflict for #1360 on the very same stamp-site line. So:

中文摘要: 本 PR 的 toolName 归一化实现本身正确且测试有效,但它只修了 #1345 根因的一半——owner 已拍板的「插件模式整个 ccr 块跟随基础配置」契约中,enabled 分歧仍会导致清单声明的工具被拒绝(静默半生效配置);后续 PR #1360 完整实现了批准方向并覆盖全部场景,故按「一个 issue 一个 PR」原则关闭本 PR,正在把 #1360 rebase 到最新 master 后交回人工合并。

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.

bug(ccr): plugin manifest tool name can diverge from the route/model-resolved CCR tool name

1 participant