From 9a8698116a9bb767d7a7c4bd41981309347933ce Mon Sep 17 00:00:00 2001 From: ework-agent Date: Thu, 24 Sep 2026 19:32:58 +0800 Subject: [PATCH 1/3] feat: enable CCR (acp_retrieve) on host/plugin lanes (#1271) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- src/plugin.ts | 15 ++- src/server.ts | 48 +++++++--- src/store.ts | 13 +++ tests/ccr-plugin.test.ts | 195 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 255 insertions(+), 16 deletions(-) create mode 100644 tests/ccr-plugin.test.ts diff --git a/src/plugin.ts b/src/plugin.ts index c44400e9d4..7fc0cf4ac3 100644 --- a/src/plugin.ts +++ b/src/plugin.ts @@ -5,7 +5,7 @@ import type { ServerResponse } from "node:http"; import fs from "node:fs"; import path from "node:path"; import { acquireInFlight, effectiveConfig, findSessionByCanonicalId, listSessions, markCompactionBoundary, markDirty, peekSession, releaseInFlight, withSessionLock, type Session } from "./session.js"; -import { ABSORB_TOOL, ABSORB_TOOL_NAME, ABSORB_TOOL_OPENAI, ABSORB_TOOL_RESPONSES, BILI_ACP_TOOLS_ANTHROPIC, BILI_ACP_TOOLS_OPENAI, BILI_ACP_TOOLS_RESPONSES, PROXY_TOOL_NAMES, RULE_TOOL, RULE_TOOL_NAME, RULE_TOOL_OPENAI, RULE_TOOL_RESPONSES, SEARCH_CONTEXT_CONVERSATION_ID_PARAM, SEARCH_CONTEXT_TOOL_NAME } from "./compress-tool.js"; +import { ABSORB_TOOL, ABSORB_TOOL_NAME, ABSORB_TOOL_OPENAI, ABSORB_TOOL_RESPONSES, BILI_ACP_TOOLS_ANTHROPIC, BILI_ACP_TOOLS_OPENAI, BILI_ACP_TOOLS_RESPONSES, PROXY_TOOL_NAMES, RETRIEVE_TOOL_NAME, RULE_TOOL, RULE_TOOL_NAME, RULE_TOOL_OPENAI, RULE_TOOL_RESPONSES, SEARCH_CONTEXT_CONVERSATION_ID_PARAM, SEARCH_CONTEXT_TOOL_NAME, retrieveToolsFor } from "./compress-tool.js"; import { absorbEnabled, effectiveAbsorbConfig, isProxyToolFor } from "./absorb.js"; import { effectiveRulesConfig, rulesEnabled } from "./rules-feature.js"; import { executeProxyTool } from "./loop/core.js"; @@ -540,16 +540,23 @@ export function handlePluginManifest(res: import("node:http").ServerResponse, co // enablement stays enforced at execution (isProxyToolFor / executeProxyTool). const absorbOn = absorbEnabled(config); const rulesOn = rulesEnabled(config); + // [#1271] acp_retrieve is advertised only while the base config enables CCR (same + // #1192 conservative rule as absorb/acp_rule). The proxy wires it on the anthropic/ + // openai lanes in plugin mode; the responses wire is deliberately NOT advertised — + // that proxy disarms CCR there, so advertising would break #1192. + const ccrOn = config.ccr?.enabled === true; + const ccrName = config.ccr?.toolName ?? RETRIEVE_TOOL_NAME; + const ccrTools = ccrOn ? retrieveToolsFor(ccrName) : undefined; res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify({ ok: true, protocolVersion: PLUGIN_PROTOCOL_VERSION, proxy: "billion-context", version: VERSION, - toolNames: [...PROXY_TOOL_NAMES, ...(absorbOn ? [ABSORB_TOOL_NAME] : []), ...(rulesOn ? [RULE_TOOL_NAME] : [])], + toolNames: [...PROXY_TOOL_NAMES, ...(absorbOn ? [ABSORB_TOOL_NAME] : []), ...(rulesOn ? [RULE_TOOL_NAME] : []), ...(ccrOn ? [ccrName] : [])], tools: { - anthropic: withSearchContextConversationDescription([...BILI_ACP_TOOLS_ANTHROPIC, ...(absorbOn ? [ABSORB_TOOL] : []), ...(rulesOn ? [RULE_TOOL] : [])].map(withConversationIdParam)), - openai: withSearchContextConversationDescription([...BILI_ACP_TOOLS_OPENAI, ...(absorbOn ? [ABSORB_TOOL_OPENAI] : []), ...(rulesOn ? [RULE_TOOL_OPENAI] : [])].map(withConversationIdParam)), + anthropic: withSearchContextConversationDescription([...BILI_ACP_TOOLS_ANTHROPIC, ...(absorbOn ? [ABSORB_TOOL] : []), ...(rulesOn ? [RULE_TOOL] : []), ...(ccrTools ? [ccrTools.anthropic] : [])].map(withConversationIdParam)), + openai: withSearchContextConversationDescription([...BILI_ACP_TOOLS_OPENAI, ...(absorbOn ? [ABSORB_TOOL_OPENAI] : []), ...(rulesOn ? [RULE_TOOL_OPENAI] : []), ...(ccrTools ? [ccrTools.openai] : [])].map(withConversationIdParam)), responses: withSearchContextConversationDescription([...BILI_ACP_TOOLS_RESPONSES, ...(absorbOn ? [ABSORB_TOOL_RESPONSES] : []), ...(rulesOn ? [RULE_TOOL_RESPONSES] : [])].map(withConversationIdParam)), }, headers: { agent: PLUGIN_AGENT_HEADER, conversation: PLUGIN_CONVERSATION_HEADER, contextWindow: PLUGIN_CONTEXT_WINDOW_HEADER, maxOutput: PLUGIN_MAX_OUTPUT_HEADER, model: PLUGIN_MODEL_HEADER, instructionsMutable: PLUGIN_INSTRUCTIONS_MUTABLE_HEADER }, diff --git a/src/server.ts b/src/server.ts index 8bda9dd8b0..863e53aa32 100644 --- a/src/server.ts +++ b/src/server.ts @@ -3,7 +3,7 @@ import fs from "node:fs"; import path from "node:path"; import { createHash, randomUUID } from "node:crypto"; import { performance } from "node:perf_hooks"; -import { createCore, type CompressionCore, type CompressionState, type Config, type CoreMessage, type NudgeDecision, type Prompts, type PackSurface, type ToolPrompts, applyAcpToolOverrides, defaultPrompts, defaultCountTokens, estimateTokensFast, renderNudgeText, deactivateBlock, viableRanges, resolveOutputSteeringConfig } from "acp-kernel"; +import { createCore, type CompressionCore, type CompressionState, type Config, type CoreMessage, type NudgeDecision, type Prompts, type PackSurface, type ToolPrompts, applyAcpToolOverrides, defaultPrompts, defaultCountTokens, estimateTokensFast, renderNudgeText, deactivateBlock, viableRanges, resolveOutputSteeringConfig, DEFAULT_CCR_CONFIG } from "acp-kernel"; import { DEFAULT_STRIP_IMAGES_KEEP_RECENT, resolveCompress, resolveCompressPrompts, resolveCompressSurfaceDetailed, resolveRequestConfig } from "./compress-settings.js"; import { dropCompressReasoning, type CompressReasoningConfig } from "./reasoning-drop.js"; import type { ProxyOptions } from "./config.js"; @@ -62,7 +62,7 @@ import { } from "acp-kernel/wire"; import { ABSORB_TOOL, ABSORB_TOOL_GOOGLE, ABSORB_TOOL_OPENAI, ABSORB_TOOL_RESPONSES, COMPRESS_TOOL, BILI_ACP_TOOLS_ANTHROPIC, BILI_ACP_TOOLS_GOOGLE, BILI_ACP_TOOLS_OPENAI, BILI_ACP_TOOLS_RESPONSES, BILI_ACP_READONLY_TOOLS_RESPONSES, COMPRESS_TOOL_NAME, IMAGE_FULL_TOOL, IMAGE_FULL_TOOL_GOOGLE, IMAGE_FULL_TOOL_OPENAI, IMAGE_FULL_TOOL_RESPONSES, RULE_TOOL, RULE_TOOL_GOOGLE, RULE_TOOL_OPENAI, RULE_TOOL_RESPONSES, retrieveToolsFor, buildAbsorbSystemPrompt, buildCompressSystemPrompt, buildCompressHybridSystemPrompt, withConversationIdNote, withMarkerIntegrityNote, withStagedCompressGuidance, withSummaryBudgetNote } from "./compress-tool.js"; import { applyAbsorbView, absorbEnabled, absorbToolName, storeEffectiveAbsorb } from "./absorb.js"; -import { adoptContentStore, ccrEnabled, contentStoreOf, executeRetrieve, retrieveToolName, storeEffectiveCcr, type CcrSettings } from "./store.js"; +import { adoptContentStore, ccrEnabled, ccrPluginWireOk, contentStoreOf, drainPendingRetrievals, executeRetrieve, retrieveToolName, storeEffectiveCcr, type CcrSettings } from "./store.js"; import { applyImageCompressionPass, imageCompressionEnabled, imageFullTrailingNote, storeEffectiveImageCompression, type ImageCompressionSettings } from "./image-compress.js"; import { rulesEnabled, storeEffectiveRules } from "./rules-feature.js"; import { rewriteJsonResponse, type RewriteCtx } from "./stream.js"; @@ -961,7 +961,13 @@ async function handle( // tool endpoint lets an agent-side plugin execute compress/decompress/ // search_context/acp_status against the session the plugin drives. Both // live under the /__bili/ loopback + trusted-origin gate above. - if (req.method === "GET" && req.url === "/__bili/plugin/manifest") return handlePluginManifest(res, config); + if (req.method === "GET" && req.url === "/__bili/plugin/manifest") { + // [#1271] kernelConfig carries no file/global compress settings; layer the global + // CCR view onto base config so acp_retrieve is advertised exactly when the operator + // enabled it (DEFAULT_CCR_CONFIG floors unset fields; per-request overrides are still + // enforced at execution, so the manifest stays conservative as #1192 requires). + return handlePluginManifest(res, { ...config, ccr: { ...DEFAULT_CCR_CONFIG, ...config.ccr, ...opts.compress.ccr } }); + } if (req.method === "GET" && req.url?.startsWith("/__bili/plugin/status")) { const query = req.url.slice(req.url.indexOf("?") + 1); const params = new URLSearchParams(query); @@ -1780,21 +1786,27 @@ async function handle( // exactly one system at index 0, #377) accept it and the head system // message stays byte-stable for the prefix cache. const pluginMode = pluginAgent !== undefined; - // [#1097] Stamp the resolved CCR policy. acp_retrieve needs a tool - // channel, so CCR is only armed in proxy mode with tool injection - // armed (mirrors absorb); every processTurn site strips `ccr` from the - // loop config unless this stamp says armed — the kernel's ccr-store - // node must never substitute placeholders the wire cannot resolve. - // on — we must never emit a placeholder the model cannot retrieve (silent - // loss). Plugin mode is out of scope for v1: the agent would need - // acp_retrieve advertised in the plugin manifest to avoid that same trap. + // [#1097/#1271] Stamp the resolved CCR policy. acp_retrieve needs a tool + // channel that can round-trip the full original, so CCR arms only where + // that channel exists and is resolvable: proxy mode always (the proxy + // executes compress/retrieve server-side), and — #1271 — plugin mode on + // the anthropic/openai wires (the agent advertises acp_retrieve from the + // manifest and rides the full text back via the request-only injection in + // prepare*). Every processTurn site strips `ccr` from the loop config + // unless this stamp says armed — the kernel's ccr-store node must never + // substitute placeholders the wire cannot resolve (we must never emit a + // placeholder the model cannot retrieve = silent loss). + // The responses wire stays out even in plugin mode: its developer-message / + // strict-alternation injection mechanics have no proven request-only carrier + // here (and no real plugin lane uses it), so arming it would risk silent loss. // The responses text/marker protocol has no native tool channel either // (absorb/rules strip themselves there for the same reason), and // ACP_NO_INJECT_TOOL disables all injection on that wire — both would // leave placeholders unretrievable. const storeChannelOk = protocol !== "responses" || (!process.env.ACP_NO_INJECT_TOOL && !FORCE_TEXT_PROTOCOL && resolveCompressProtocol(opts.routes, upstreamOrigin) !== "marker"); - storeEffectiveCcr(session, opts.compress.injectTool && !pluginMode && storeChannelOk && resolvedCcrCfg?.enabled === true ? resolvedCcrCfg : undefined); + const pluginCcrOk = !pluginMode || ccrPluginWireOk(protocol); + storeEffectiveCcr(session, opts.compress.injectTool && pluginCcrOk && storeChannelOk && resolvedCcrCfg?.enabled === true ? resolvedCcrCfg : undefined); // [#1095] same channel/plugin-mode gating as CCR: image_full's restore // round-trip needs a tool channel on this wire; without one the model // could request originals it never gets back (silent-loss trap). @@ -2546,6 +2558,12 @@ async function prepareAnthropic( // decision + recipe; originals cached for the image_full restore channel). // Deterministic encode ⇒ re-runs are byte-stable for the prefix cache. await applyImageCompressionPass(session, processedMessages as BiliMessage[], { config, billing: imageBillingFor(opts, upstreamOrigin), log }); + // [#1271] plugin mode: acp_retrieve ran via the tool API; ride the full original + // back on this forward as a request-only trailing message (ephemeral, never persisted). + if (pluginMode && ccrEnabled(session)) { + const retrInj = drainPendingRetrievals(session); + if (retrInj.length > 0) processedMessages = [...processedMessages, ...retrInj]; + } rebuiltMessages = coreToAnthropic(processedMessages as BiliMessage[], cacheControls); if (sysNotes.length > 0) { rebuiltMessages = [...rebuiltMessages, ...sysNotes.map((text) => ({ role: "user" as const, content: text }))]; @@ -2723,6 +2741,12 @@ async function prepareOpenai( // [#1095] arrival-time image downscale (see prepareAnthropic) — one // deterministic encode per fingerprint; byte-stable re-runs. await applyImageCompressionPass(session, processedMessages as BiliMessage[], { config, billing: imageBillingFor(opts, billingUpstream ?? upstreamOrigin), log }); + // [#1271] plugin mode: acp_retrieve ran via the tool API; ride the full original + // back on this forward as a request-only trailing message (ephemeral, never persisted). + if (pluginMode && ccrEnabled(session)) { + const retrInj = drainPendingRetrievals(session); + if (retrInj.length > 0) processedMessages = [...processedMessages, ...retrInj]; + } rebuiltMessages = systemToUser(hardenOpenaiAssistantContent(coreToOpenai(processedMessages as BiliMessage[]))); // ONLY the static compress prompt goes into the system message — the diff --git a/src/store.ts b/src/store.ts index 620cdf3980..2fbe25617a 100644 --- a/src/store.ts +++ b/src/store.ts @@ -42,6 +42,19 @@ export function retrieveToolName(session: Session | undefined): string { return effectiveCcr(session)?.toolName ?? RETRIEVE_TOOL_NAME; } +// [#1271] Wire protocols that support plugin-mode CCR. The agent advertises +// acp_retrieve from the manifest and rides the full original back via the +// request-only injection in prepare* — which exists only for these two wires. +// google (strict role-alternation) and responses (fragile developer-message +// mechanics, no real plugin lane) are excluded so a placeholder is never emitted +// on a wire that cannot round-trip it (silent loss, #1097). The arming gate and +// the drain sites must stay in lockstep with this set. +export const PLUGIN_CCR_WIRES: ReadonlySet = new Set(["anthropic", "openai"]); + +export function ccrPluginWireOk(protocol: string): boolean { + return PLUGIN_CCR_WIRES.has(protocol); +} + /** Lazily materialize the session's kernel content-store envelope: loaded * from the session's content-store.json on first touch, fresh when the file * is absent (or corrupt — degraded to retrieve misses, never a crash). */ diff --git a/tests/ccr-plugin.test.ts b/tests/ccr-plugin.test.ts new file mode 100644 index 0000000000..511621c166 --- /dev/null +++ b/tests/ccr-plugin.test.ts @@ -0,0 +1,195 @@ +// #1271: CCR enablement on host lanes (plugin mode). Covers the two NEW decision +// surfaces plus the round-trip: +// 1. the manifest advertises acp_retrieve ONLY while CCR is enabled (#1192 +// conservative rule) and only on the wires whose prepare* can ride the full +// original back (anthropic/openai) — never responses; +// 2. the plugin-mode arming gate scopes CCR to exactly those wires, so a +// placeholder is never emitted on a wire that cannot round-trip it +// (silent loss, #1097); +// 3. a plugin-lane e2e proving an oversized tool result is stored + placeholdered +// on the wire, then acp_retrieve rides the full original back on the next +// forward (request-only, never persisted). + +import test from "node:test"; +import assert from "node:assert/strict"; +import http from "node:http"; +import { once } from "node:events"; + +process.env.NODE_ENV = "test"; +process.env.BILI_PERSIST = "0"; + +import { defaultConfig } from "acp-kernel"; +import { startServer, type ProxyOptions } from "../src/server.ts"; +import { SessionStore, _setStoreForTest } from "../src/persist.ts"; +import { _setForTest as setRegistryForTest } from "../src/registry.ts"; +import { listSessions } from "../src/session.ts"; +import { ccrEnabled, ccrPluginWireOk, contentStoreOf, executeRetrieve, PLUGIN_CCR_WIRES, retrieveToolName } from "../src/store.ts"; +import { handlePluginManifest } from "../src/plugin.ts"; + +const MODEL = "test-model"; +const BIG_TEXT = "line of build output ".repeat(400); + +// — manifest advertising (acceptance: "advertises only while enabled", #1192) — + +function readManifest(config: Parameters[1]): { toolNames: string[]; tools: Record } { + let body = ""; + const res = { writeHead: () => {}, end: (b: string) => { body = b; } } as unknown as Parameters[0]; + handlePluginManifest(res, config); + return JSON.parse(body) as { toolNames: string[]; tools: Record }; +} + +function namesOnWire(wire: unknown[]): string[] { + return wire.map((t) => { + const o = t as Record; + return typeof o.name === "string" ? o.name : String((o.function as { name?: unknown } | undefined)?.name ?? ""); + }); +} + +test("handlePluginManifest: acp_retrieve NOT advertised by default (CCR off)", () => { + const m = readManifest(defaultConfig(200_000)); + assert.ok(!m.toolNames.includes("acp_retrieve"), "default config must not advertise acp_retrieve"); + for (const wire of ["anthropic", "openai", "responses"]) { + assert.ok(!namesOnWire(m.tools[wire] ?? []).includes("acp_retrieve"), `${wire} must not carry acp_retrieve when CCR off`); + } +}); + +test("handlePluginManifest: acp_retrieve advertised on anthropic+openai only when CCR enabled", () => { + const m = readManifest({ ...defaultConfig(200_000), ccr: { enabled: true } }); + assert.ok(m.toolNames.includes("acp_retrieve"), "enabled CCR advertises acp_retrieve"); + assert.ok(namesOnWire(m.tools.anthropic).includes("acp_retrieve"), "anthropic wire carries acp_retrieve"); + assert.ok(namesOnWire(m.tools.openai).includes("acp_retrieve"), "openai wire carries acp_retrieve"); + // #1192: the proxy disarms CCR on the responses wire in plugin mode, so it must + // NOT be advertised there (advertising would guarantee a rejected call). + assert.ok(!namesOnWire(m.tools.responses).includes("acp_retrieve"), "responses wire must NOT carry acp_retrieve"); +}); + +test("handlePluginManifest: custom ccr.toolName is honored", () => { + const m = readManifest({ ...defaultConfig(200_000), ccr: { enabled: true, toolName: "fetch_full" } }); + assert.ok(m.toolNames.includes("fetch_full"), "custom retrieve tool name advertised"); + assert.ok(namesOnWire(m.tools.anthropic).includes("fetch_full")); +}); + +// — plugin-mode arming gate: wire scoping (silent-loss boundary, #1097/#1271) — + +test("plugin-mode CCR is scoped to exactly the anthropic/openai wires", () => { + assert.deepEqual([...PLUGIN_CCR_WIRES].sort(), ["anthropic", "openai"]); + assert.equal(ccrPluginWireOk("anthropic"), true); + assert.equal(ccrPluginWireOk("openai"), true); + assert.equal(ccrPluginWireOk("responses"), false, "responses cannot round-trip the retrieval"); + assert.equal(ccrPluginWireOk("google"), false, "google strict alternation cannot ride the injection"); +}); + +// — plugin-lane e2e: store → placeholder → acp_retrieve → full text rides back — + +type Rig = { proxyPort: number; upstreamPort: number; forwards: string[]; proxy: http.Server; upstream: http.Server }; + +function okJson(): string { + return JSON.stringify({ + id: "chatcmpl-1", + object: "chat.completion", + choices: [{ index: 0, message: { role: "assistant", content: "ok" }, finish_reason: "stop" }], + usage: { prompt_tokens: 10, completion_tokens: 3, total_tokens: 13 }, + }); +} + +async function startRig(): Promise { + const forwards: string[] = []; + const upstream = http.createServer((req, res) => { + let b = ""; + req.on("data", (c) => (b += c)); + req.on("end", () => { + forwards.push(b); + res.writeHead(200, { "content-type": "application/json" }); + res.end(okJson()); + }); + }); + upstream.listen(0, "127.0.0.1"); + await once(upstream, "listening"); + const upstreamPort = upstream.address().port as number; + + _setStoreForTest(new SessionStore({ enabled: false })); + setRegistryForTest({}); + const proxy = await startServer({ + port: 0, + host: "127.0.0.1", + upstream: "http://127.0.0.1", + routes: { [`http://127.0.0.1:${upstreamPort}`]: {} }, + modelContextLimit: 200_000, + kernelConfig: defaultConfig(200_000), + compress: { injectTool: true, injectNudge: false, ccr: { enabled: true, minToolTokens: 50 } }, + promptCache: { routing: "auto" }, + sessionHeader: "x-acp-session", + log: false, + debug: false, + passthrough: false, + autoUpdate: false, + mitm: { enabled: false, domains: [] }, + } as ProxyOptions); + await once(proxy, "listening"); + return { proxyPort: proxy.address().port as number, upstreamPort, forwards, proxy, upstream }; +} + +async function postOpenai(rig: Rig, messages: unknown[]): Promise { + const url = `http://127.0.0.1:${rig.proxyPort}/bili/http://127.0.0.1:${rig.upstreamPort}/v1/chat/completions`; + const res = await fetch(url, { + method: "POST", + headers: { "content-type": "application/json", "x-bili-plugin": "test-agent", "x-acp-session": "ccr-e2e-conv" }, + // max_tokens must exceed SIDE_REQUEST_MAX_TOKENS or the side-request + // guard forwards verbatim without touching kernel state (#554). + body: JSON.stringify({ model: MODEL, max_tokens: 64_000, messages }), + }); + const txt = await res.text(); + if (res.status !== 200) throw new Error(`proxy returned ${res.status}: ${txt}`); +} + +const BASE_MSGS = (): unknown[] => [ + { role: "user", content: "run a big build" }, + { role: "assistant", content: null, tool_calls: [{ id: "call_1", type: "function", function: { name: "bash", arguments: '{"command":"npm run build"}' } }] }, + { role: "tool", tool_call_id: "call_1", content: BIG_TEXT }, +]; + +async function closeRig(rig: Rig): Promise { + rig.proxy.close(); + await once(rig.proxy, "close"); + rig.upstream.close(); + await once(rig.upstream, "close"); +} + +test("e2e plugin lane: CCR arms, stores+placeholderes, and acp_retrieve rides full text back", async () => { + const rig = await startRig(); + try { + // Turn 1: agent sends history with an oversized tool result. + await postOpenai(rig, BASE_MSGS()); + assert.equal(rig.forwards.length, 1, "one outbound forward after turn 1"); + const f1 = rig.forwards[0]!; + assert.ok(f1.includes("[acp-stored"), "turn-1 wire carries the stored placeholder, got: " + f1.slice(0, 200)); + assert.ok(!f1.includes(BIG_TEXT), "full original must NOT leak onto the turn-1 wire"); + + // Discover the armed session (only our plugin-mode session has CCR stamped). + const armed = listSessions().filter((s) => ccrEnabled(s)); + assert.equal(armed.length, 1, "exactly one CCR-armed session exists"); + const sess = armed[0]!; + assert.equal(retrieveToolName(sess), "acp_retrieve"); + const ref = Object.keys(contentStoreOf(sess).byRef)[0]; + assert.ok(ref, "oversized tool result was stored under a ref"); + + // The agent calls acp_retrieve (via the tool endpoint in reality); here we + // drive the same executeRetrieve the endpoint dispatches to. + const ack = executeRetrieve({ ref }, sess); + assert.match(ack, new RegExp(`retrieved ${ref}: [\\d,]+ tok`), "retrieve returns the ack receipt"); + + // Turn 2: agent re-sends history plus the acp_retrieve call + ack. The + // drained injection rides the full original back on this forward. + const msgs2 = [ + ...BASE_MSGS(), + { role: "assistant", content: null, tool_calls: [{ id: "call_r", type: "function", function: { name: "acp_retrieve", arguments: JSON.stringify({ ref }) } }] }, + { role: "tool", tool_call_id: "call_r", content: ack }, + ]; + await postOpenai(rig, msgs2); + assert.equal(rig.forwards.length, 2, "second outbound forward after turn 2"); + const f2 = rig.forwards[1]!; + assert.ok(f2.includes(BIG_TEXT.slice(0, 120)), "full original rides back onto the turn-2 wire"); + } finally { + await closeRig(rig); + } +}); From 0a24e75386af670428e45164559e6d364131b35e Mon Sep 17 00:00:00 2001 From: ework-daemon Date: Thu, 24 Sep 2026 20:07:41 +0800 Subject: [PATCH 2/3] docs: reflect plugin-lane CCR scope in README + CONFIGURATION (en/zh) (#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. --- CONFIGURATION.md | 4 ++-- CONFIGURATION.zh-CN.md | 4 ++-- README.md | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CONFIGURATION.md b/CONFIGURATION.md index 7bc678f13b..676d83e584 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -364,14 +364,14 @@ For each request, the proxy resolves the settings by longest-URL-prefix match (t - **Type:** `object` (`{ enabled?, minToolTokens?, excludeTools?, toolName?, maxHeadChars? }`) - **Default:** *(disabled — the feature is off unless you set `enabled: true`)* -- **Status:** ACTIVE (v1 — proxy mode, native-tools wires only) +- **Status:** ACTIVE (v1 — proxy mode; plugin lanes on the anthropic + openai wires, #1271) - **Description:** Opt-in **content-addressed message store** / built-in CCR (issue #1097, via the `acp-kernel` CCR API, acp-kernel >= 0.0.84). Instead of force-distilling oversized tool results (like `absorb`) or carrying them on the wire forever, the kernel ID-references them at arrival (the ccr-store node runs between prune and absorb within `processTurn` — ID-referencing wins over distillation): the wire keeps a deterministic, byte-stable placeholder (`📦 [acp-stored #m00423 · shell output · 4,213 tok] \`npm run build\`\n → acp_retrieve("m00423") returns the full text`) and the original goes into the session's content store. The model retrieves the full original on demand via the injected `acp_retrieve` tool; a retrieve is ephemeral (it rides the intra-request tool-result channel, never enters fold space, consumes no message ref). Lossless by default: a retrieve not made costs one cheap tool call; a detail distilled away by absorb is gone for good. Sub-fields (merged deepest-wins like every other CompressSettings field): - `enabled: boolean` — master switch; anything other than `true` keeps the feature fully off (no placeholders, no tool). - `minToolTokens: number` — only tool results at or above this many tokens are ID-referenced (kernel default `4000`); smaller results stay verbatim. - `excludeTools: string[]` — tool-name patterns never stored (glob suffixes allowed; kernel default: none). - `toolName: string` — rename the retrieval tool (default `"acp_retrieve"`); declaration, dispatch and the placeholder hint all follow the name. Must stay unique against the client's own tool names. - `maxHeadChars: number` — head/command preview length inside the placeholder (kernel default `96`). - The store persists as a single envelope file (`.content-store.json`) next to the session JSON, using the same at-rest codec as the session file when `BILI_ENCRYPTION_KEY` is set; entries are deduped by content hash and lazily loaded per session. Only the *content* inside a `tool` result shrinks — pairing with the assistant `tool_calls` is untouched. v1 scope gates: **proxy mode only** (plugin agents would need `acp_retrieve` advertised in their plugin manifest before a placeholder could be emitted — otherwise silent loss), and **native-tools wires only**: responses marker/text-protocol routes and `ACP_NO_INJECT_TOOL` have no channel to execute the retrieve, so the store disarms itself there instead of losing content. Known limitation: no eviction policy yet — the envelope grows with the unique originals held (tracked as a follow-up). Per-session stats (stored bytes, current wire bytes saved, retrieve rate) surface in `acp_status`; each retrieve logs a `[ccr] retrieve …` line. + The store persists as a single envelope file (`.content-store.json`) next to the session JSON, using the same at-rest codec as the session file when `BILI_ENCRYPTION_KEY` is set; entries are deduped by content hash and lazily loaded per session. Only the *content* inside a `tool` result shrinks — pairing with the assistant `tool_calls` is untouched. v1 scope gates: **proxy mode**, plus **plugin mode on the anthropic + openai wires** where the plugin manifest advertises `acp_retrieve` while CCR is enabled (#1271); responses marker/text-protocol routes, `ACP_NO_INJECT_TOOL`, and the responses/google wires in plugin mode have no proven request-only round-trip channel to execute the retrieve, so the store disarms itself there instead of losing content. Known limitation: no eviction policy yet — the envelope grows with the unique originals held (tracked as a follow-up). Per-session stats (stored bytes, current wire bytes saved, retrieve rate) surface in `acp_status`; each retrieve logs a `[ccr] retrieve …` line. #### `imageCompression` diff --git a/CONFIGURATION.zh-CN.md b/CONFIGURATION.zh-CN.md index b2bc5888d1..179fa208b7 100644 --- a/CONFIGURATION.zh-CN.md +++ b/CONFIGURATION.zh-CN.md @@ -364,14 +364,14 @@ - **类型:** `object`(`{ enabled?, minToolTokens?, excludeTools?, toolName?, maxHeadChars? }`) - **默认值:** *(禁用 — 除非显式设置 `enabled: true`,该特性完全关闭)* -- **状态:** ACTIVE(v1 — 仅代理模式、仅原生工具线) +- **状态:** ACTIVE(v1 — 代理模式;插件通道限 anthropic + openai wire,#1271) - **说明:** 可选开启的**内容寻址消息存储**/内置 CCR(issue #1097,经 `acp-kernel` CCR API,需 acp-kernel >= 0.0.84)。超大工具结果不再被强制蒸馏(如 `absorb`)或永远挂在线上:kernel 在到达时将其 ID 引用(ccr-store 节点位于 `processTurn` 内 prune 与 absorb 之间 —— ID 引用优先于蒸馏),线上保留一个确定性、字节稳定的占位符(`📦 [acp-stored #m00423 · shell output · 4,213 tok] \`npm run build\`\n → acp_retrieve("m00423") returns the full text`),原文进入该会话的内容存储。模型通过注入的 `acp_retrieve` 工具按需取回完整原文;retrieve 是临时的(走请求内工具结果通道,不进入折叠空间,不占用消息 ref)。默认无损:未执行的 retrieve 只花一次廉价工具调用;而被 absorb 蒸馏掉的细节则永久丢失。子字段(按字段最深层级胜出,与其他 CompressSettings 字段一致): - `enabled: boolean` — 主开关;任何值不为 `true` 时特性完全关闭(无占位符、无工具)。 - `minToolTokens: number` — 仅达到此 token 数的工具结果被 ID 引用(kernel 默认 `4000`);更小的结果保持原样。 - `excludeTools: string[]` — 从不存储的工具名模式(允许 glob 后缀;kernel 默认为空)。 - `toolName: string` — 重命名检索工具(默认 `"acp_retrieve"`);声明、分发与占位符提示都跟随名称。必须与客户端自身工具名保持唯一。 - `maxHeadChars: number` — 占位符中头部/命令预览的长度(kernel 默认 `96`)。 - 存储以单个信封文件(`.content-store.json`)持久化在会话 JSON 旁边,设置 `BILI_ENCRYPTION_KEY` 时使用与会话文件相同的静态加密编解码器;条目按内容哈希去重,按会话懒加载。只有 `tool` 结果*内部的内容*缩小——与 assistant `tool_calls` 的配对不受影响。v1 范围门控:**仅代理模式**(插件 agent 需要在其插件清单中声明 `acp_retrieve`,否则占位符会造成静默丢失);且**仅限原生工具线**:responses marker/文本协议路由与 `ACP_NO_INJECT_TOOL` 没有执行 retrieve 的通道,因此存储在这些场景下自动解除武装,而不是丢失内容。已知限制:尚无驱逐策略——信封随持有的唯一原文数量增长(已记录为后续项)。按会话统计(已存字节、当前线上节省字节、retrieve 率)在 `acp_status` 中展示;每次 retrieve 记录一条 `[ccr] retrieve …` 日志。 + 存储以单个信封文件(`.content-store.json`)持久化在会话 JSON 旁边,设置 `BILI_ENCRYPTION_KEY` 时使用与会话文件相同的静态加密编解码器;条目按内容哈希去重,按会话懒加载。只有 `tool` 结果*内部的内容*缩小——与 assistant `tool_calls` 的配对不受影响。v1 范围门控:**代理模式**,外加 **anthropic + openai wire 上的插件模式**(CCR 启用时插件清单会声明 `acp_retrieve`,#1271);responses marker/文本协议路由、`ACP_NO_INJECT_TOOL`、以及插件模式下的 responses/google wire 没有经过验证的请求内往返通道来执行 retrieve,因此存储在这些场景下自动解除武装,而不是丢失内容。已知限制:尚无驱逐策略——信封随持有的唯一原文数量增长(已记录为后续项)。按会话统计(已存字节、当前线上节省字节、retrieve 率)在 `acp_status` 中展示;每次 retrieve 记录一条 `[ccr] retrieve …` 日志。 #### `imageCompression` diff --git a/README.md b/README.md index fd5857c9f6..95f65f5fa5 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ An opt-in fifth tool, `absorb` (`compress.absorb.enabled: true` — see [CONFIGU An opt-in sixth tool, `acp_rule` (`compress.rules: true` — see [CONFIGURATION.md](CONFIGURATION.md)), records **persistent principle-level reminders**: a short rule recorded by the model (user-emphasized lessons, behaviors to remember, major pitfalls hit) is hard-protected from compression — the call and its result stay in context across every fold — and omitting the argument lists the recorded rules ([ranxianglei/billion-context-pi#433](https://github.com/ranxianglei/billion-context-pi/issues/433)). -An opt-in seventh tool, `acp_retrieve` (`compress.ccr.enabled: true` — see [CONFIGURATION.md](CONFIGURATION.md)), backs the **content-addressed message store** (built-in CCR, #1097): oversized tool results are **ID-referenced at arrival instead of force-distilled** — the wire keeps a byte-stable placeholder and the original goes into a per-session content-store envelope (hash-deduped), retrievable on demand via one cheap tool call. Lossless by default: a retrieve not made costs nothing but the call; a detail distilled away by absorb is gone for good. Proxy mode and native-tools wires only in v1 (the marker/text protocol has no channel to execute the retrieve, so the store disarms itself there rather than silently losing content). +An opt-in seventh tool, `acp_retrieve` (`compress.ccr.enabled: true` — see [CONFIGURATION.md](CONFIGURATION.md)), backs the **content-addressed message store** (built-in CCR, #1097): oversized tool results are **ID-referenced at arrival instead of force-distilled** — the wire keeps a byte-stable placeholder and the original goes into a per-session content-store envelope (hash-deduped), retrievable on demand via one cheap tool call. Lossless by default: a retrieve not made costs nothing but the call; a detail distilled away by absorb is gone for good. Proxy mode plus plugin lanes on the anthropic + openai wires in v1 (`acp_retrieve` is advertised in the plugin manifest while CCR is enabled, #1271); responses marker/text routes and google stay disarmed because no request-only round-trip channel exists there (silent loss, #1097). An opt-in tool, `image_full` (`compress.imageCompression.enabled: true` — see [CONFIGURATION.md](CONFIGURATION.md)), backs **image pre-compression** (#1095): screenshot-like images in tool results are downscaled once at arrival — the kernel decides routing and recipe, the host encodes via optional `sharp` — cutting billed pixels before they enter the wire (providers bill by pixel area; halving dimensions cuts billed tokens ~4×). Non-screenshot images pass through byte-identical. Lossy by nature: when the model can't read details it calls `image_full` with the message's ref to restore the original resolution for the rest of the session — no proxy-side storage needed, since the client's own history still carries the original bytes (it never saw the shrunk form). Default off. From eb3a95c903e679e393b6088e79df1261b5d12a5f Mon Sep 17 00:00:00 2001 From: ework-agent Date: Thu, 24 Sep 2026 22:39:12 +0800 Subject: [PATCH 3/3] fix: gate plugin-lane CCR arming on base-config enablement; clear pending retrievals on disarm MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- src/server.ts | 10 +++++- src/store.ts | 7 +++++ tests/ccr-plugin.test.ts | 67 +++++++++++++++++++++++++++++++++++----- 3 files changed, 76 insertions(+), 8 deletions(-) diff --git a/src/server.ts b/src/server.ts index 863e53aa32..def26b42f1 100644 --- a/src/server.ts +++ b/src/server.ts @@ -1805,7 +1805,15 @@ async function handle( // leave placeholders unretrievable. const storeChannelOk = protocol !== "responses" || (!process.env.ACP_NO_INJECT_TOOL && !FORCE_TEXT_PROTOCOL && resolveCompressProtocol(opts.routes, upstreamOrigin) !== "marker"); - const pluginCcrOk = !pluginMode || ccrPluginWireOk(protocol); + // [review #1273] The plugin arm MUST gate on the BASE config because that + // is the only source the manifest reads (handlePluginManifest sees + // opts.compress.ccr, never the route/model-scoped merge). Route-scoped + // enablement without a base-level enabled flag would otherwise arm the + // store and emit placeholders while the manifest never advertised + // acp_retrieve — the model would see "→ acp_retrieve(...)" with no + // retrieval channel (silent loss). Route-scoped-only enablement stays + // proxy-mode-only (the proxy injects the tool itself, per-request). + const pluginCcrOk = !pluginMode || (ccrPluginWireOk(protocol) && opts.compress.ccr?.enabled === true); storeEffectiveCcr(session, opts.compress.injectTool && pluginCcrOk && storeChannelOk && resolvedCcrCfg?.enabled === true ? resolvedCcrCfg : undefined); // [#1095] same channel/plugin-mode gating as CCR: image_full's restore // round-trip needs a tool channel on this wire; without one the model diff --git a/src/store.ts b/src/store.ts index 2fbe25617a..6464e21175 100644 --- a/src/store.ts +++ b/src/store.ts @@ -21,6 +21,13 @@ const EFFECTIVE_CCR_KEY = "effectiveCcr"; * processTurn loop config must match or be stripped, mirroring absorb). */ export function storeEffectiveCcr(session: Session, ccr: CcrSettings | undefined): void { session.metadata[EFFECTIVE_CCR_KEY] = ccr ?? null; + // [review #1273] Disarming must also drop any queued full-text injection: + // a retrieve issued on a lane that later switches to a non-CCR wire + // (responses/google, or the plugin base-config gate above) would otherwise + // flush as a stale trailing full-text message whenever the lane re-arms at + // an unrelated conversation point. Not persisted either way (#persist resets + // on load) — this only tightens the in-memory window. + if (!ccr) session.pendingRetrievals.length = 0; } /** Read back the CCR policy stamped by {@link storeEffectiveCcr}. */ diff --git a/tests/ccr-plugin.test.ts b/tests/ccr-plugin.test.ts index 511621c166..b4cd63e3ad 100644 --- a/tests/ccr-plugin.test.ts +++ b/tests/ccr-plugin.test.ts @@ -23,7 +23,7 @@ import { startServer, type ProxyOptions } from "../src/server.ts"; import { SessionStore, _setStoreForTest } from "../src/persist.ts"; import { _setForTest as setRegistryForTest } from "../src/registry.ts"; import { listSessions } from "../src/session.ts"; -import { ccrEnabled, ccrPluginWireOk, contentStoreOf, executeRetrieve, PLUGIN_CCR_WIRES, retrieveToolName } from "../src/store.ts"; +import { ccrEnabled, ccrPluginWireOk, contentStoreOf, PLUGIN_CCR_WIRES, retrieveToolName } from "../src/store.ts"; import { handlePluginManifest } from "../src/plugin.ts"; const MODEL = "test-model"; @@ -92,7 +92,7 @@ function okJson(): string { }); } -async function startRig(): Promise { +async function startRig(mode?: "route-scoped"): Promise { const forwards: string[] = []; const upstream = http.createServer((req, res) => { let b = ""; @@ -109,14 +109,22 @@ async function startRig(): Promise { _setStoreForTest(new SessionStore({ enabled: false })); setRegistryForTest({}); + // "route-scoped": CCR enabled ONLY under the route block — the base config + // stays off, so the plugin manifest never advertises acp_retrieve (#1273 + // review regression rig). + const routes = mode === "route-scoped" + ? { [`http://127.0.0.1:${upstreamPort}`]: { compress: { ccr: { enabled: true, minToolTokens: 50 } } } } + : { [`http://127.0.0.1:${upstreamPort}`]: {} }; const proxy = await startServer({ port: 0, host: "127.0.0.1", upstream: "http://127.0.0.1", - routes: { [`http://127.0.0.1:${upstreamPort}`]: {} }, + routes, modelContextLimit: 200_000, kernelConfig: defaultConfig(200_000), - compress: { injectTool: true, injectNudge: false, ccr: { enabled: true, minToolTokens: 50 } }, + compress: mode === "route-scoped" + ? { injectTool: true, injectNudge: false } + : { injectTool: true, injectNudge: false, ccr: { enabled: true, minToolTokens: 50 } }, promptCache: { routing: "auto" }, sessionHeader: "x-acp-session", log: false, @@ -173,9 +181,18 @@ test("e2e plugin lane: CCR arms, stores+placeholderes, and acp_retrieve rides fu const ref = Object.keys(contentStoreOf(sess).byRef)[0]; assert.ok(ref, "oversized tool result was stored under a ref"); - // The agent calls acp_retrieve (via the tool endpoint in reality); here we - // drive the same executeRetrieve the endpoint dispatches to. - const ack = executeRetrieve({ ref }, sess); + // The agent calls acp_retrieve through the REAL plugin tool endpoint + // (`POST /__bili/plugin/tool`, the same dispatch the MCP shim drives) — + // covers the conversation gate (isProxyToolFor under the armed session) + // and the ack round-trip, not just the inner executeRetrieve. + const toolRes = await fetch(`http://127.0.0.1:${rig.proxyPort}/__bili/plugin/tool`, { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ conversationId: "ccr-e2e-conv", tool: "acp_retrieve", args: { ref } }), + }); + const toolJson = JSON.parse(await toolRes.text()) as { ok: boolean; result?: string; error?: string }; + assert.ok(toolRes.status === 200 && toolJson.ok === true, `plugin tool endpoint returned ${toolRes.status}: ${JSON.stringify(toolJson)}`); + const ack = toolJson.result!; assert.match(ack, new RegExp(`retrieved ${ref}: [\\d,]+ tok`), "retrieve returns the ack receipt"); // Turn 2: agent re-sends history plus the acp_retrieve call + ack. The @@ -193,3 +210,39 @@ test("e2e plugin lane: CCR arms, stores+placeholderes, and acp_retrieve rides fu await closeRig(rig); } }); + +// [review #1273] Route-scoped CCR (base config off) must NOT arm the plugin +// lane: the manifest reads only the base config (server.ts:969 builds it from +// opts.compress.ccr), so arming from the route merge would emit placeholders +// advertising an acp_retrieve the host never registered — silent loss. The +// proxy lane keeps working: it injects the tool itself, per-request. +test("e2e route-scoped CCR: plugin lane stays verbatim, proxy lane arms", async () => { + const rig = await startRig("route-scoped"); + try { + // Plugin lane (x-bili-plugin header): the oversized tool result must + // ride the wire byte-exact — no store, no placeholder, no arming. + await postOpenai(rig, BASE_MSGS()); + assert.equal(rig.forwards.length, 1, "one outbound forward after the plugin turn"); + const f1 = rig.forwards[0]!; + assert.ok(f1.includes(BIG_TEXT), "plugin lane forwards the oversized result verbatim when CCR is route-scoped only"); + assert.ok(!f1.includes("[acp-stored"), "no stored placeholder on the plugin wire"); + assert.equal(listSessions().filter((s) => ccrEnabled(s)).length, 0, "no session arms CCR from a route-scoped-only config on the plugin lane"); + + // Proxy lane (no plugin header, fresh conversation id): the + // route-level merge arms CCR and the proxy injects acp_retrieve. + const url = `http://127.0.0.1:${rig.proxyPort}/bili/http://127.0.0.1:${rig.upstreamPort}/v1/chat/completions`; + const res = await fetch(url, { + method: "POST", + headers: { "content-type": "application/json", "x-acp-session": "ccr-e2e-conv-proxy" }, + body: JSON.stringify({ model: MODEL, max_tokens: 64_000, messages: BASE_MSGS() }), + }); + const txt = await res.text(); + assert.equal(res.status, 200, `proxy lane returned ${res.status}: ${txt}`); + assert.equal(rig.forwards.length, 2, "second outbound forward after the proxy turn"); + const f2 = rig.forwards[1]!; + assert.ok(f2.includes("[acp-stored"), "proxy lane arms CCR from the route-scoped config"); + assert.ok(!f2.includes(BIG_TEXT), "full original must not leak on the proxy wire"); + } finally { + await closeRig(rig); + } +});