From 8abb9bcb2858b6c575ca4005e66359fc4298bb54 Mon Sep 17 00:00:00 2001 From: ework-agent Date: Tue, 15 Sep 2026 18:22:23 +0800 Subject: [PATCH] feat: per-request cache reconciliation ledger (acp_cache tool) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Issue #800: prove with data that compression does not wreck the prompt cache. Every provider usage report is decomposed into an exact additive identity — missed = new content + compression re-pay + ttl/other — so the grand ledger always closes against the provider-reported totals. - src/cache-ledger.ts: session-scoped ledger in metadata.cacheLedger (512-line ring + exact aggregates + fold events with measured T/h/k); folds detected from state.blocks diff (proxy mode eager at applyRanges, plugin mode lazy at usage time), X via tokenSnapshot prefix sums; incremental math delegates to acp-kernel decomposeSample so streaming and batch reports agree bit-for-bit. - executeProxyTool / executeAnthropicProxyTool dispatch the new read-only acp_cache tool (kernel-defined) -> formatted report. - GET /__bili/cache-report?session= management endpoint (JSON). - recordUsage (proxy mode) and applyUsageSample (plugin mode) feed the ledger; acp-kernel pinned to the release containing PR ranxianglei/acp-kernel#297. --- src/cache-ledger.ts | 274 +++++++++++++++++++++ src/compress-tool.ts | 24 +- src/loop/core.ts | 7 + src/plugin.ts | 2 + src/server.ts | 20 ++ src/stream.ts | 11 + tests/cache-ledger.test.ts | 210 ++++++++++++++++ tests/codex-official.test.ts | 2 +- tests/launcher-plugin-mode.test.ts | 4 +- tests/plugin-protocol.test.ts | 8 +- tests/search-context-cross-session.test.ts | 12 +- 11 files changed, 540 insertions(+), 34 deletions(-) create mode 100644 src/cache-ledger.ts create mode 100644 tests/cache-ledger.test.ts diff --git a/src/cache-ledger.ts b/src/cache-ledger.ts new file mode 100644 index 0000000000..2414d5f176 --- /dev/null +++ b/src/cache-ledger.ts @@ -0,0 +1,274 @@ +import { + computeFoldEconomics, + decomposeSample, + formatCacheReport, + summarizeFoldEconomics, + type CacheReport, + type CacheTotals, + type CompressionBlock, + type FoldEvent, +} from "acp-kernel"; +import { log as loggerLog } from "./logger.js"; +import type { Session } from "./session.js"; + +const SAMPLE_CAP = 512; +const FOLD_CAP = 256; + +interface LedgerFold { + seq: number; + at: number; + S: number; + sigma: number; + X?: number; + V?: number; + Vp?: number; + T: number; + hPct: number | null; + requestsAfter: number; + k: number | null; +} + +interface LedgerLine { + seq: number; + at: number; + input: number; + cached: number; + output: number; + hitPct: number; + missed: number; + nc: number; + cr: number; + tr: number; + foldSeq: number | null; +} + +export interface CacheLedger { + v: 1; + lastBlockId: number; + consumedFoldSeq: number; + sampleSeq: number; + foldSeqCounter: number; + folds: LedgerFold[]; + lines: LedgerLine[]; + agg: { + requests: number; + input: number; + cached: number; + output: number; + nc: number; + cr: number; + tr: number; + }; +} + +const LEDGER_KEY = "cacheLedger"; + +function refNum(ref: string): number { + return Number(ref.replace(/\D/g, "")) || 0; +} + +function round1(n: number): number { + return Math.round(n * 10) / 10; +} + +/** Token offset of the view prefix that survives a fold starting at `ref`: + * sum of first-render token counts of all refs chronologically before it. + * Refs are assigned in message order and never reused (kernel contract), + * so numeric order IS view order. */ +function prefixTokensBeforeRef(session: Session, ref: string): number { + const byRef = session.state?.messageRefs?.byRef; + const snap = session.state?.tokenSnapshot; + if (!byRef || !snap || refNum(ref) === 0) return 0; + let n = 0; + for (const key of Object.keys(byRef)) { + if (refNum(key) < refNum(ref)) n += snap[key] ?? 0; + } + return n; +} + +export function getCacheLedger(session: Session): CacheLedger { + const meta = session.metadata ?? (session.metadata = {}); + const existing = meta[LEDGER_KEY] as CacheLedger | undefined; + if (existing && existing.v === 1) return existing; + // Bootstrap: blocks already present predate ledger tracking — record + // their high-water mark WITHOUT fold events (no usage baseline existed). + const maxBlockId = (session.state?.blocks ?? []).reduce((n, b) => Math.max(n, refNum(b.blockId)), 0); + const led: CacheLedger = { + v: 1, + lastBlockId: maxBlockId, + consumedFoldSeq: 0, + sampleSeq: 0, + foldSeqCounter: 0, + folds: [], + lines: [], + agg: { requests: 0, input: 0, cached: 0, output: 0, nc: 0, cr: 0, tr: 0 }, + }; + meta[LEDGER_KEY] = led; + return led; +} + +function pushFold(led: CacheLedger, f: Omit): void { + for (const open of led.folds) { + if (open.k === null) open.k = open.requestsAfter; + } + led.foldSeqCounter += 1; + led.folds.push({ ...f, seq: led.foldSeqCounter, T: 0, hPct: null, requestsAfter: 0, k: null }); + if (led.folds.length > FOLD_CAP) led.folds.splice(0, led.folds.length - FOLD_CAP); +} + +/** Record compression folds materialized as new kernel blocks. Proxy mode + * calls this eagerly at the applyCompression site; plugin mode folds are + * caught lazily by detectNewFolds() via the blockId high-water mark. */ +export function recordCacheFoldsFromBlocks(session: Session, blocks: CompressionBlock[], geo?: { V?: number; Vp?: number }): void { + if (blocks.length === 0) return; + const led = getCacheLedger(session); + for (const b of blocks) { + const id = refNum(b.blockId); + if (id <= led.lastBlockId) continue; + pushFold(led, { + at: b.createdAt || Date.now(), + S: b.compressedTokens, + sigma: Math.ceil(b.summary.length / 4), + X: b.startRef ? prefixTokensBeforeRef(session, b.startRef) : undefined, + V: geo?.V, + Vp: geo?.Vp, + }); + led.lastBlockId = Math.max(led.lastBlockId, id); + } +} + +function detectNewFolds(session: Session, led: CacheLedger): void { + const blocks = session.state?.blocks ?? []; + let maxId = led.lastBlockId; + for (const b of blocks) maxId = Math.max(maxId, refNum(b.blockId)); + if (maxId > led.lastBlockId) { + recordCacheFoldsFromBlocks(session, blocks.filter((b) => refNum(b.blockId) > led.lastBlockId)); + } +} + +/** Record one provider usage report into the session ledger. `input` must be + * NORMALIZED (cached included — promptInputTotal semantics). */ +export function recordCacheSample(session: Session, s: { at: number; input: number; cached: number; output?: number }): void { + const led = getCacheLedger(session); + detectNewFolds(session, led); + const prevLine = led.lines[led.lines.length - 1]; + // Same window as buildCacheReport: a fold counts once its timestamp has + // elapsed (f.at <= s.at), never earlier — keeps incremental and batch math + // identical under clock skew between block.createdAt and settle time. + const pendRefs = led.folds.filter((f) => f.seq > led.consumedFoldSeq && f.at <= s.at); + const pending: FoldEvent[] = pendRefs.map((f) => ({ + at: f.at, + tokensCompressed: f.S, + summaryTokens: f.sigma, + firstFoldStartTokens: f.X, + viewBefore: f.V, + viewAfter: f.Vp, + })); + const dec = decomposeSample( + prevLine ? { at: prevLine.at, input: prevLine.input, cached: prevLine.cached } : null, + { at: s.at, input: s.input, cached: s.cached }, + pending, + ); + let foldSeq: number | null = null; + if (dec.foldIndex !== null) foldSeq = pendRefs[dec.foldIndex]?.seq ?? null; + if (pendRefs.length > 0) { + let hi = 0; + for (const f of pendRefs) hi = Math.max(hi, f.seq); + led.consumedFoldSeq = Math.max(led.consumedFoldSeq, hi); + } + const hitPct = s.input > 0 ? round1((s.cached / s.input) * 100) : 0; + for (const f of pendRefs) { + if (f.at <= s.at) { + f.requestsAfter += 1; + if (f.hPct === null) f.hPct = hitPct; + } + } + if (foldSeq !== null) { + const owner = led.folds.find((f) => f.seq === foldSeq); + if (owner) owner.T += dec.compRepay; + } + led.sampleSeq += 1; + led.lines.push({ + seq: led.sampleSeq, + at: s.at, + input: s.input, + cached: s.cached, + output: s.output ?? 0, + hitPct, + missed: dec.missed, + nc: dec.newContent, + cr: dec.compRepay, + tr: dec.ttlRepay, + foldSeq, + }); + if (led.lines.length > SAMPLE_CAP) led.lines.splice(0, led.lines.length - SAMPLE_CAP); + const agg = led.agg; + agg.requests += 1; + agg.input += s.input; + agg.cached += s.cached; + agg.output += s.output ?? 0; + agg.nc += dec.newContent; + agg.cr += dec.compRepay; + agg.tr += dec.ttlRepay; +} + +export function buildSessionCacheReport(session: Session): CacheReport { + const led = getCacheLedger(session); + const a = led.agg; + const totals: CacheTotals = { + requests: a.requests, + input: a.input, + cached: a.cached, + output: a.output, + hitPct: a.input > 0 ? round1((a.cached / a.input) * 100) : 0, + newContent: a.nc, + compRepay: a.cr, + ttlRepay: a.tr, + residual: a.input - a.cached - (a.nc + a.cr + a.tr), + balanced: true, + }; + totals.balanced = totals.residual === 0; + const folds = led.folds.map((f) => + computeFoldEconomics({ + seq: f.seq, + at: f.at, + S: f.S, + sigma: f.sigma, + Vprime: f.Vp ?? null, + hPct: f.hPct, + T: f.T, + requestsAfter: f.requestsAfter, + turnsToNextFold: f.k, + }), + ); + return { + generatedAt: Date.now(), + profile: { w: 1.0, r: 0.1, q: 4.0 }, + totals, + economics: summarizeFoldEconomics(folds), + folds, + lines: led.lines.map((l) => ({ + seq: l.seq, + at: l.at, + input: l.input, + cached: l.cached, + output: l.output, + hitPct: l.hitPct, + missed: l.missed, + newContent: l.nc, + compRepay: l.cr, + ttlRepay: l.tr, + foldSeq: l.foldSeq, + })), + linesOmitted: led.sampleSeq - led.lines.length, + }; +} + +export function handleAcpCache(session: Session): string { + try { + return formatCacheReport(buildSessionCacheReport(session), session.id); + } catch (err) { + loggerLog("warn", `[${session.id}] [acp_cache] report failed: ${String(err)}`); + return `[acp_cache FAILED: ${String(err)}]`; + } +} diff --git a/src/compress-tool.ts b/src/compress-tool.ts index d00a465674..5d8ef99638 100644 --- a/src/compress-tool.ts +++ b/src/compress-tool.ts @@ -4,9 +4,8 @@ * The schemas, prompt builders, text tags and parseCompressInput moved to * acp-kernel `src/compress-tools.ts` verbatim; this module keeps the proxy's * historical import paths and names stable: - * - MUTATING_PROXY_TOOLS / READONLY_PROXY_TOOLS alias the kernel's ACP_* names - * ("proxy" is a misnomer once shared); PROXY_TOOL_NAMES is a filtered copy - * of kernel ACP_TOOL_NAMES — see UNADOPTED_KERNEL_TOOLS below; + * - PROXY_TOOL_NAMES / MUTATING_PROXY_TOOLS / READONLY_PROXY_TOOLS alias the + * kernel's ACP_* names ("proxy" is a misnomer once shared); * - parseCompressInput wires the kernel's onWarn hook into the proxy logger. * (The #603 single-quote salvage lives in the kernel ladder since 0.0.59; * this wrapper only surfaces its diagnostics.) @@ -22,8 +21,6 @@ import { ACP_TOOLS_OPENAI, ACP_TOOLS_RESPONSES, ACP_READONLY_TOOLS_RESPONSES, - ACP_CACHE_TOOL_NAME, - ACP_TOOL_NAMES, } from "acp-kernel"; import { log as loggerLog } from "./logger.js"; import { maxShrinkPerCompress } from "./fetch-util.js"; @@ -66,14 +63,7 @@ export { buildAbsorbSystemPrompt, } from "acp-kernel"; export type { ParsedRange, AbsorbConfig } from "acp-kernel"; -// #800: acp-kernel >=0.0.75 ships acp_cache (prompt-cache reconciliation report) -// but this proxy has no execution path for it yet — executeProxyTool would answer -// a call with "[Unknown proxy tool: acp_cache]" reported as success. Keep it off -// every wire surface until adoption lands (kernel constants are shared and never -// mutated; the filtered copies below are the single choke point all injection consumes). -export const UNADOPTED_KERNEL_TOOLS: ReadonlySet = new Set([ACP_CACHE_TOOL_NAME]); -export const PROXY_TOOL_NAMES: ReadonlySet = new Set([...ACP_TOOL_NAMES].filter((n) => !UNADOPTED_KERNEL_TOOLS.has(n))); -export { ACP_MUTATING_TOOLS as MUTATING_PROXY_TOOLS, ACP_READONLY_TOOLS as READONLY_PROXY_TOOLS } from "acp-kernel"; +export { ACP_TOOL_NAMES as PROXY_TOOL_NAMES, ACP_MUTATING_TOOLS as MUTATING_PROXY_TOOLS, ACP_READONLY_TOOLS as READONLY_PROXY_TOOLS } from "acp-kernel"; // #841: host-side conversation_id extension of search_context. Kernel constants // are shared and never mutated; ALL wire-mode injection points must use these @@ -112,10 +102,10 @@ export const BILI_SEARCH_CONTEXT_TOOL_RESPONSES = { parameters: withConversationId(SEARCH_CONTEXT_TOOL_RESPONSES.parameters), }; -export const BILI_ACP_TOOLS_ANTHROPIC = ACP_TOOLS_ANTHROPIC.filter((t) => !UNADOPTED_KERNEL_TOOLS.has(t.name)).map((t) => (t.name === SEARCH_CONTEXT_TOOL_NAME ? BILI_SEARCH_CONTEXT_TOOL : t)); -export const BILI_ACP_TOOLS_OPENAI = ACP_TOOLS_OPENAI.filter((t) => !UNADOPTED_KERNEL_TOOLS.has(t.function.name)).map((t) => (t.function.name === SEARCH_CONTEXT_TOOL_NAME ? BILI_SEARCH_CONTEXT_TOOL_OPENAI : t)); -export const BILI_ACP_TOOLS_RESPONSES = ACP_TOOLS_RESPONSES.filter((t) => !UNADOPTED_KERNEL_TOOLS.has(t.name)).map((t) => (t.name === SEARCH_CONTEXT_TOOL_NAME ? BILI_SEARCH_CONTEXT_TOOL_RESPONSES : t)); -export const BILI_ACP_READONLY_TOOLS_RESPONSES = ACP_READONLY_TOOLS_RESPONSES.filter((t) => !UNADOPTED_KERNEL_TOOLS.has(t.name)).map((t) => (t.name === SEARCH_CONTEXT_TOOL_NAME ? BILI_SEARCH_CONTEXT_TOOL_RESPONSES : t)); +export const BILI_ACP_TOOLS_ANTHROPIC = ACP_TOOLS_ANTHROPIC.map((t) => (t.name === SEARCH_CONTEXT_TOOL_NAME ? BILI_SEARCH_CONTEXT_TOOL : t)); +export const BILI_ACP_TOOLS_OPENAI = ACP_TOOLS_OPENAI.map((t) => (t.function.name === SEARCH_CONTEXT_TOOL_NAME ? BILI_SEARCH_CONTEXT_TOOL_OPENAI : t)); +export const BILI_ACP_TOOLS_RESPONSES = ACP_TOOLS_RESPONSES.map((t) => (t.name === SEARCH_CONTEXT_TOOL_NAME ? BILI_SEARCH_CONTEXT_TOOL_RESPONSES : t)); +export const BILI_ACP_READONLY_TOOLS_RESPONSES = ACP_READONLY_TOOLS_RESPONSES.map((t) => (t.name === SEARCH_CONTEXT_TOOL_NAME ? BILI_SEARCH_CONTEXT_TOOL_RESPONSES : t)); // The kernel ships no Responses-format absorb const (the four ACP tools have // *_RESPONSES variants; absorb is host-registered opt-in). Synthesize it in diff --git a/src/loop/core.ts b/src/loop/core.ts index 25547464fe..947d427755 100644 --- a/src/loop/core.ts +++ b/src/loop/core.ts @@ -5,6 +5,7 @@ import { type CoreMessage, } from "acp-kernel"; import { handleAcpStatus } from "../acp-status.js"; +import { handleAcpCache, recordCacheSample } from "../cache-ledger.js"; import { lastCompressSuffix, type Session } from "../session.js"; import type { BiliMessage } from "acp-kernel/wire"; import { @@ -151,6 +152,9 @@ export function executeProxyTool( if (toolName === "acp_status") { return handleAcpStatus(args, ctx); } + if (toolName === "acp_cache") { + return handleAcpCache(ctx.session); + } const absorb = effectiveAbsorbConfig(ctx.session, ctx.config); if (absorb?.enabled === true && toolName === (absorb.toolName ?? ABSORB_TOOL_NAME)) { return executeAbsorb(args, callId, absorb, ctx); @@ -190,6 +194,9 @@ function recordUsage( ctx.log( `[acp-usage] round ${round} input=${total} cached=${cached ?? 0} (cache hit ${hitPct}%)${foldNew ? " fold=new" : ""}${total <= 0 ? " (zero-total: lastInputTokens kept)" : ""}`, ); + if (total > 0 || typeof cached === "number") { + recordCacheSample(ctx.session, { at: Date.now(), input: total, cached: cached ?? 0, output: out }); + } } export async function* runCompressLoop( diff --git a/src/plugin.ts b/src/plugin.ts index 909e3e8a4c..2d90cab881 100644 --- a/src/plugin.ts +++ b/src/plugin.ts @@ -15,6 +15,7 @@ import { emitStreamError, emitUpstreamTruncation } from "./stream-error.js"; import { degenerateTurnWarning } from "./degenerate-turn.js"; import { noteWeakOverflow, recordProvenInput } from "./weak-overflow.js"; import { warnCacheCollapse } from "./cache-warn.js"; +import { recordCacheSample } from "./cache-ledger.js"; import { promptInputTotal, type WireProtocol } from "./util.js"; import { stateDir } from "./paths.js"; @@ -759,6 +760,7 @@ export function applyUsageSample(session: Session, sample: UsageSample, protocol const foldNew = session.stats.pendingFoldUsage === true; if (foldNew) session.stats.pendingFoldUsage = false; loggerLog("info", `[${session.id}] [plugin] [acp-usage] input=${total} cached=${sample.cachedTokens ?? "n/a"}${hit === undefined ? "" : ` (cache hit ${hit}%)`}${foldNew ? " fold=new" : ""}`); + recordCacheSample(session, { at: Date.now(), input: total, cached: sample.cachedTokens ?? 0, output: sample.outputTokens }); } if (sample.outputTokens !== undefined) session.stats.outputTokens += sample.outputTokens; } diff --git a/src/server.ts b/src/server.ts index 84da4601cb..ce2dfaff95 100644 --- a/src/server.ts +++ b/src/server.ts @@ -49,6 +49,7 @@ import { ABSORB_TOOL, ABSORB_TOOL_OPENAI, ABSORB_TOOL_RESPONSES, COMPRESS_TOOL, import { applyAbsorbView, absorbEnabled, absorbToolName, storeEffectiveAbsorb } from "./absorb.js"; import { rewriteJsonResponse, type RewriteCtx } from "./stream.js"; import { applyRanges } from "./stream.js"; +import { buildSessionCacheReport } from "./cache-ledger.js"; import { preflightCompress, estimateCoreMessages, estimateRawBodyTokens, estimateCoreMessagesUpper, type PreflightResult } from "./preflight.js"; import { imageTokensInRawBody, imageTokensInParsedBody, resolveImageBilling, type ResolvedImageBilling } from "./image-tokens.js"; import { renderUI, handleConfigGet, handleConfigPut } from "./web/index.js"; @@ -629,6 +630,7 @@ async function handle( return; } if (req.method === "GET" && req.url === "/__bili/stats") return sendStats(res); + if (req.method === "GET" && req.url?.startsWith("/__bili/cache-report")) return sendCacheReport(res, req.url); if (req.method === "GET" && req.url === "/") { // Browser visits root → redirect to the web UI. curl / health probes // (Accept: */* or no Accept) still get the JSON health check so @@ -4164,6 +4166,24 @@ function handleConfigReload(opts: ProxyOptions, res: http.ServerResponse, log: ( res.end(JSON.stringify({ ok: true, count: names.length, routes: names })); } +function sendCacheReport(res: http.ServerResponse, url: string): void { + const sessionParam = new URL(url, "http://localhost").searchParams.get("session"); + let sessions = listSessions(); + if (sessionParam !== null) { + const hit = sessions.filter((s) => s.id === sessionParam); + if (hit.length === 0) { + res.writeHead(404, { "content-type": "application/json" }); + res.end(JSON.stringify({ error: `unknown session: ${sessionParam}` })); + return; + } + sessions = hit; + } else { + sessions = sessions.slice().sort((a, b) => b.lastSeen - a.lastSeen); + } + res.writeHead(200, { "content-type": "application/json" }); + res.end(JSON.stringify({ reports: sessions.map((s) => ({ id: s.id, report: buildSessionCacheReport(s) })) }, null, 2)); +} + function sendStats(res: http.ServerResponse): void { const sessions = listSessions().map((s) => ({ id: s.id, diff --git a/src/stream.ts b/src/stream.ts index 1ec3a7932b..0c2f410548 100644 --- a/src/stream.ts +++ b/src/stream.ts @@ -1,5 +1,6 @@ import { collectBlockContent, type CompressionCore, type Config, type CoreMessage, type CompressionState } from "acp-kernel"; import { handleAcpStatus } from "./acp-status.js"; +import { handleAcpCache, recordCacheFoldsFromBlocks } from "./cache-ledger.js"; import { type Session, cacheBlockContent } from "./session.js"; import { COMPRESS_TOOL_NAME, parseCompressInput, ABSORB_TOOL_NAME } from "./compress-tool.js"; import { effectiveAbsorbConfig, executeAbsorb, isProxyToolFor } from "./absorb.js"; @@ -37,6 +38,9 @@ function executeAnthropicProxyTool(toolName: string, args: Record, ctx: const postCtx = Math.max(0, preContext - r.tokensCompressed); const ceiling = postCtx > 0 ? Math.floor((100 * anchorTok) / postCtx) : 0; ctx.log(`[acp-compress-obs] shrink ${Math.round(shrinkRatio * 100)}% (~${r.tokensCompressed}/${preContext} tok) foldPoint=${foldPoint} blocks=${r.blocksCreated} anchor≈${anchorTok} tok (${res.state.blocks.filter((b) => b.active).length} active blocks, sys excluded) postCtx≈${postCtx} → next-request cache ceiling ≥${ceiling}%`); + // #800: feed the cache ledger — the next request's usage report will + // attribute its re-pay cliff to these folds via decomposeSample. + recordCacheFoldsFromBlocks( + ctx.session, + res.state.blocks.filter((b) => !beforeIds.has(b.blockId)), + { V: preContext, Vp: postCtx }, + ); const warn = r.warnings.length > 0 ? ` ${r.warnings.join("; ")}` : ""; let msg = `[Compressed ${detail} → ${r.blocksCreated} block(s), ~${r.tokensCompressed} tokens saved.${warn}]`; diff --git a/tests/cache-ledger.test.ts b/tests/cache-ledger.test.ts new file mode 100644 index 0000000000..6d2c68ec4c --- /dev/null +++ b/tests/cache-ledger.test.ts @@ -0,0 +1,210 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { buildCacheReport, type CacheSample, type FoldEvent, type CompressionBlock } from "acp-kernel"; +import { buildSessionCacheReport, handleAcpCache, recordCacheFoldsFromBlocks, recordCacheSample } from "../src/cache-ledger.ts"; +import type { Session } from "../src/session.ts"; + +let seq = 0; +function makeSession(): Session { + seq += 1; + return { + id: `cl-${seq}`, + metadata: {}, + stats: {}, + state: { blocks: [], messageRefs: { byRaw: {}, byRef: {} }, tokenSnapshot: {} }, + } as unknown as Session; +} + +/** tokenSnapshot: m00001..m00020 @ 500 tok each; byRef maps ref→raw. */ +function withView20(session: Session): void { + const st = session.state as { messageRefs: { byRaw: Record; byRef: Record }; tokenSnapshot: Record; blocks: CompressionBlock[] }; + for (let i = 1; i <= 20; i++) { + const ref = `m${String(i).padStart(5, "0")}`; + st.messageRefs.byRef[ref] = `raw${i}`; + st.messageRefs.byRaw[`raw${i}`] = ref; + st.tokenSnapshot[ref] = 500; + } +} + +function block(id: string, at: number, S: number, sigmaChars: number, startRef?: string): CompressionBlock { + return { + blockId: id, + createdAt: at, + compressedTokens: S, + summary: "s".repeat(sigmaChars), + startRef, + } as unknown as CompressionBlock; +} + +const T0 = Date.parse("2026-09-15T10:00:00Z"); + +test("incremental ledger closes the same identity as kernel batch", () => { + const session = makeSession(); + withView20(session); + + // t=1000: cold start, 10% miss → all residual. + recordCacheSample(session, { at: T0 + 1000, input: 10000, cached: 9000 }); + // t=1500: fold b1 removes 5000 tok, summary 2048 tok, diverges at m00010 (X=4500). + recordCacheFoldsFromBlocks(session, [block("b1", T0 + 1500, 5000, 8192, "m00010")], { V: 10000, Vp: 5000 }); + // t=2000: post-fold cliff: 6000 billed, only 1000 cached. + recordCacheSample(session, { at: T0 + 2000, input: 6000, cached: 1000 }); + // t=2500: fold b2 removes 2000 tok, diverges at m00015 (X=7000 — near the tail). + recordCacheFoldsFromBlocks(session, [block("b2", T0 + 2500, 2000, 4096, "m00015")], { V: 6000, Vp: 4000 }); + // t=3000: growth 1000 + a miss beyond it with no structural excess. + recordCacheSample(session, { at: T0 + 3000, input: 7000, cached: 2000 }); + // t=4000: warm append, fully explained by growth. + recordCacheSample(session, { at: T0 + 4000, input: 7500, cached: 7000 }); + + const rawSamples: CacheSample[] = [ + { at: T0 + 1000, input: 10000, cached: 9000 }, + { at: T0 + 2000, input: 6000, cached: 1000 }, + { at: T0 + 3000, input: 7000, cached: 2000 }, + { at: T0 + 4000, input: 7500, cached: 7000 }, + ]; + const rawFolds: FoldEvent[] = [ + { at: T0 + 1500, tokensCompressed: 5000, summaryTokens: 2048, firstFoldStartTokens: 4500, viewBefore: 10000, viewAfter: 5000 }, + { at: T0 + 2500, tokensCompressed: 2000, summaryTokens: 1024, firstFoldStartTokens: 7000, viewBefore: 6000, viewAfter: 4000 }, + ]; + + const inc = buildSessionCacheReport(session); + const batch = buildCacheReport(rawSamples, rawFolds); + assert.equal(inc.totals.input, batch.totals.input); + assert.equal(inc.totals.cached, batch.totals.cached); + assert.equal(inc.totals.newContent, batch.totals.newContent); + assert.equal(inc.totals.compRepay, batch.totals.compRepay); + assert.equal(inc.totals.ttlRepay, batch.totals.ttlRepay); + assert.equal(inc.totals.residual, 0); + assert.equal(inc.totals.balanced, true); + + // Hand-computed expectations. + assert.equal(inc.totals.input, 30500); + assert.equal(inc.totals.cached, 19000); + assert.equal(inc.totals.newContent, 1500); + assert.equal(inc.totals.compRepay, 1500); + assert.equal(inc.totals.ttlRepay, 8500); + // Line-level: the cliff request splits into comp 1500 (= input − X) / ttl 3500. + const cliff = inc.lines.find((l) => l.seq === 2)!; + assert.equal(cliff.missed, 5000); + assert.equal(cliff.newContent, 0); + assert.equal(cliff.compRepay, 1500); + assert.equal(cliff.ttlRepay, 3500); + assert.equal(cliff.foldSeq, 1); + // Fold economics carry the measured values. + const f1 = inc.folds.find((f) => f.seq === 1)!; + assert.equal(f1.T, 1500); + assert.equal(f1.hPct, 16.7); + assert.equal(f1.S, 5000); + assert.equal(f1.sigma, 2048); + // k counts samples with f.at < s.at <= nextFold.at: only the @2000 cliff. + assert.equal(f1.turnsToNextFold, 1); +}); + +test("cold-start miss lands in the ttl bucket; pure append is new content", () => { + const session = makeSession(); + recordCacheSample(session, { at: T0 + 1000, input: 1000, cached: 0 }); + recordCacheSample(session, { at: T0 + 2000, input: 2000, cached: 1000 }); + const r = buildSessionCacheReport(session); + const l1 = r.lines.find((l) => l.seq === 1)!; + assert.equal(l1.ttlRepay, 1000); + assert.equal(l1.compRepay, 0); + const l2 = r.lines.find((l) => l.seq === 2)!; + assert.equal(l2.newContent, 1000); + assert.equal(l2.ttlRepay, 0); + assert.equal(r.totals.balanced, true); +}); + +test("bootstrap ignores pre-existing blocks; later blocks become folds", () => { + const session = makeSession(); + withView20(session); + const st = session.state as { blocks: CompressionBlock[] }; + st.blocks.push(block("b1", T0 + 100, 4000, 6400, "m00005")); + st.blocks.push(block("b2", T0 + 200, 3000, 4800, "m00012")); + recordCacheSample(session, { at: T0 + 1000, input: 9000, cached: 8000 }); + let led = (session.metadata as Record & object)["cacheLedger"]!; + assert.equal(led.folds.length, 0, "historical blocks are not folds"); + assert.equal(led.lastBlockId, 2); + st.blocks.push(block("b3", T0 + 1500, 5000, 8192, "m00010")); + recordCacheSample(session, { at: T0 + 2000, input: 5000, cached: 1000 }); + led = (session.metadata as Record & object)["cacheLedger"]!; + assert.equal(led.folds.length, 1); + const r = buildSessionCacheReport(session); + const l2 = r.lines.find((l) => l.seq === 2)!; + assert.ok(l2.compRepay > 0, "post-bootstrap fold attributes re-pay"); + assert.equal(l2.foldSeq, 1); +}); + +test("plugin-mode lazy detection catches pi-created blocks at usage time", () => { + const session = makeSession(); + withView20(session); + recordCacheSample(session, { at: T0 + 1000, input: 10000, cached: 9000 }); + // pi compresses locally between requests; proxy sees the new block only + // when the next request's state sync lands — no eager call here. + const st = session.state as { blocks: CompressionBlock[] }; + st.blocks.push(block("b1", T0 + 1400, 5000, 8192, "m00010")); + recordCacheSample(session, { at: T0 + 2000, input: 6000, cached: 1000 }); + const r = buildSessionCacheReport(session); + assert.equal(r.folds.length, 1); + const l2 = r.lines.find((l) => l.seq === 2)!; + assert.equal(l2.compRepay, 1500); + assert.equal(l2.ttlRepay, 3500); + assert.equal(r.folds[0]!.T, 1500); +}); + +test("folds stamped after the current sample wait for the next one", () => { + const session = makeSession(); + withView20(session); + recordCacheSample(session, { at: T0 + 1000, input: 10000, cached: 9000 }); + recordCacheFoldsFromBlocks(session, [block("b1", T0 + 2500, 5000, 8192, "m00010")], { V: 10000, Vp: 5000 }); + // Sample before the fold's timestamp: nothing to attribute yet. + recordCacheSample(session, { at: T0 + 2000, input: 10500, cached: 9000 }); + const mid = buildSessionCacheReport(session).lines.find((l) => l.seq === 2)!; + assert.equal(mid.compRepay, 0); + assert.equal(mid.newContent, 500); + assert.equal(mid.ttlRepay, 1000); + recordCacheSample(session, { at: T0 + 3000, input: 6000, cached: 1000 }); + const after = buildSessionCacheReport(session).lines.find((l) => l.seq === 3)!; + assert.equal(after.compRepay, 1500); + assert.equal(after.foldSeq, 1); +}); + +test("ring eviction keeps aggregates exact", () => { + const session = makeSession(); + let input = 1000; + for (let i = 0; i < 520; i++) { + recordCacheSample(session, { at: T0 + 1000 + i * 60_000, input, cached: Math.floor(input * 0.9), output: 100 }); + input += 100; + } + const led = (session.metadata as Record & object)["cacheLedger"]!; + assert.equal(led.sampleSeq, 520); + assert.equal(led.lines.length, 512); + assert.equal(led.agg.requests, 520); + const expectedInput = Array.from({ length: 520 }, (_, i) => 1000 + i * 100).reduce((a, b) => a + b, 0); + assert.equal(led.agg.input, expectedInput); + const r = buildSessionCacheReport(session); + assert.equal(r.linesOmitted, 8); + assert.equal(r.lines[0]!.seq, 9); + assert.equal(r.totals.requests, 520); + assert.equal(r.totals.balanced, true); +}); + +test("handleAcpCache renders the grand ledger with a closing identity", () => { + const session = makeSession(); + withView20(session); + recordCacheSample(session, { at: T0 + 1000, input: 10000, cached: 9000 }); + recordCacheFoldsFromBlocks(session, [block("b1", T0 + 1500, 5000, 8192, "m00010")], { V: 10000, Vp: 5000 }); + recordCacheSample(session, { at: T0 + 2000, input: 6000, cached: 1000 }); + const text = handleAcpCache(session); + assert.match(text, /ACP CACHE REPORT \(cl-\d+\)/); + assert.match(text, /GRAND LEDGER/); + assert.match(text, /identity check\s+OK/); + assert.match(text, /FOLD ECONOMICS/); + assert.match(text, /LINE ITEMS/); +}); + +test("empty session reports zero balanced totals", () => { + const session = makeSession(); + const r = buildSessionCacheReport(session); + assert.equal(r.totals.requests, 0); + assert.equal(r.totals.balanced, true); + assert.match(handleAcpCache(session), /identity check\s+OK/); +}); diff --git a/tests/codex-official.test.ts b/tests/codex-official.test.ts index f1f3eb51c0..f175621bb7 100644 --- a/tests/codex-official.test.ts +++ b/tests/codex-official.test.ts @@ -119,7 +119,7 @@ test("Codex official transport preserves OAuth headers, decodes bodies, and reba assert.deepEqual(forwarded.additional_tools, requestBody.additional_tools); assert.deepEqual( forwarded.tools.map((t: { name: string }) => t.name), - ["shell", "compress", "decompress", "search_context", "acp_status"], + ["shell", "compress", "decompress", "search_context", "acp_status", "acp_cache"], ); const session = listSessions().find((candidate) => candidate.meta.label === sessionId); diff --git a/tests/launcher-plugin-mode.test.ts b/tests/launcher-plugin-mode.test.ts index ca3c2abe15..9ed758cfdc 100644 --- a/tests/launcher-plugin-mode.test.ts +++ b/tests/launcher-plugin-mode.test.ts @@ -340,7 +340,7 @@ test("mcp stdio shell: manifest → tools/list → tools/call forwards to the pl const init = byId(1) as { result?: { serverInfo?: { name?: string } } }; assert.equal(init.result?.serverInfo?.name, "bili"); const tools = byId(2) as { result?: { tools?: { name: string }[] } }; - assert.deepEqual(tools.result?.tools?.map((t) => t.name).sort(), ["absorb", "acp_status", "compress", "decompress", "search_context"]); + assert.deepEqual(tools.result?.tools?.map((t) => t.name).sort(), ["absorb", "acp_cache", "acp_status", "compress", "decompress", "search_context"]); const call = byId(3) as { result?: { content?: { text?: string }[]; isError?: boolean } }; assert.equal(call.result?.isError, false); assert.match(call.result?.content?.[0]?.text ?? "", /CONTEXT BREAKDOWN/, "acp_status result forwarded verbatim"); @@ -411,7 +411,7 @@ test("mcp stdio shell (codex style): BILI_CONVERSATION_ID self-register → head const byId = (n: number): Record => JSON.parse(lines.find((l) => (JSON.parse(l) as { id?: number }).id === n) ?? "{}"); const tools = byId(2) as { result?: { tools?: { name: string }[] } }; - assert.deepEqual(tools.result?.tools?.map((t) => t.name).sort(), ["absorb", "acp_status", "compress", "decompress", "search_context"], "tools listed"); + assert.deepEqual(tools.result?.tools?.map((t) => t.name).sort(), ["absorb", "acp_cache", "acp_status", "compress", "decompress", "search_context"], "tools listed"); const call = byId(3) as { result?: { content?: { text?: string }[]; isError?: boolean } }; assert.equal(call.result?.isError, false, `tools/call succeeded (self-registered conversation bound)${call.result?.isError ? ": " + (call.result?.content?.[0]?.text ?? "") : ""}`); assert.match(call.result?.content?.[0]?.text ?? "", /CONTEXT BREAKDOWN/); diff --git a/tests/plugin-protocol.test.ts b/tests/plugin-protocol.test.ts index 6b794172a4..4951f7fb5f 100644 --- a/tests/plugin-protocol.test.ts +++ b/tests/plugin-protocol.test.ts @@ -222,11 +222,11 @@ test("plugin manifest serves the exact wire tool schemas, headers and version", assert.equal(manifest.ok, true); assert.equal(manifest.protocolVersion, 1); assert.ok(/^\d+\.\d+\.\d+/.test(manifest.version), `version looks wrong: ${manifest.version}`); - assert.deepEqual([...manifest.toolNames].sort(), ["absorb", "acp_status", "compress", "decompress", "search_context"]); + assert.deepEqual([...manifest.toolNames].sort(), ["absorb", "acp_cache", "acp_status", "compress", "decompress", "search_context"]); const names = manifest.tools.anthropic!.map((t) => String(t.name)).sort(); - assert.deepEqual(names, ["absorb", "acp_status", "compress", "decompress", "search_context"]); - assert.equal(manifest.tools.openai!.length, 5); - assert.equal(manifest.tools.responses!.length, 5); + assert.deepEqual(names, ["absorb", "acp_cache", "acp_status", "compress", "decompress", "search_context"]); + assert.equal(manifest.tools.openai!.length, 6); + assert.equal(manifest.tools.responses!.length, 6); // #841: search_context's conversation_id doubles as a cross-session // read-only search target — its param description must carry the // historical-search wording in every wire shape. diff --git a/tests/search-context-cross-session.test.ts b/tests/search-context-cross-session.test.ts index 0ad9ef24fb..c85fc19120 100644 --- a/tests/search-context-cross-session.test.ts +++ b/tests/search-context-cross-session.test.ts @@ -6,7 +6,7 @@ import { tmpdir } from "node:os"; import { createHash } from "node:crypto"; import { ACP_READONLY_TOOLS_RESPONSES, ACP_TOOLS_ANTHROPIC, ACP_TOOLS_OPENAI, ACP_TOOLS_RESPONSES, SEARCH_CONTEXT_TOOL_NAME, createCore, createInitialState, defaultConfig } from "acp-kernel"; import { anthropicToCore, type AnthropicRequestBody } from "acp-kernel/wire"; -import { BILI_ACP_READONLY_TOOLS_RESPONSES, BILI_ACP_TOOLS_ANTHROPIC, BILI_ACP_TOOLS_OPENAI, BILI_ACP_TOOLS_RESPONSES, UNADOPTED_KERNEL_TOOLS } from "../src/compress-tool.ts"; +import { BILI_ACP_READONLY_TOOLS_RESPONSES, BILI_ACP_TOOLS_ANTHROPIC, BILI_ACP_TOOLS_OPENAI, BILI_ACP_TOOLS_RESPONSES } from "../src/compress-tool.ts"; import { SessionStore, _setStoreForTest } from "../src/persist.ts"; import { _resetSessionsForTest, getSession, type Session } from "../src/session.ts"; import { executeSearchContext, executeSearchContextTarget } from "../src/decompress-shared.ts"; @@ -78,16 +78,8 @@ test("#841 schema: BILI arrays add optional conversation_id to search_context on const kernelProps = paramsOf(kernelEntry!).properties as Record; assert.equal(kernelProps.conversation_id, undefined, "kernel constant must not be mutated"); - // The kernel may ship tools the host has not adopted yet (acp_cache, #800); - // those are intentionally absent from the BILI arrays, so drop them from the - // kernel side only — a BILI-side leak of an unadopted tool must still fail. - const adoptedInKernel = (t: unknown): boolean => { - const e = t as FlatTool; - const name = shape === "openai" ? e.function?.name : e.name; - return !UNADOPTED_KERNEL_TOOLS.has(name as string); - }; const biliRest = bili.filter((t) => t !== entry); - const kernelRest = kernel.filter((t) => t !== kernelEntry && adoptedInKernel(t)); + const kernelRest = kernel.filter((t) => t !== kernelEntry); assert.deepEqual(biliRest, kernelRest, "no other tool may change"); } const ro = searchEntry(BILI_ACP_READONLY_TOOLS_RESPONSES, "flat")!;