From 877711463f912c6fd3783ffb5406b1380b674bef Mon Sep 17 00:00:00 2001 From: ework-agent Date: Mon, 31 Aug 2026 23:51:48 +0800 Subject: [PATCH 1/2] fix: archive blocks across omp native compaction instead of silently deactivating them (#395) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit omp's in-session native compaction re-sends a shortened history (its summary + retained tail) without rotating the session id, so bili's per-sid registry reuses stale state and syncBlocks silently deactivates every block whose raw ids left the history — making decompress permanently unreachable and decoupling acp_status from the real visible context (the ledger break #19 shelved). Wire the omp session_compact hook bili was ignoring: - agent plugin (pi/omp) POSTs /__bili/plugin/compact on session_compact - proxy marks a compaction boundary; the next processTurn degrades the active->inactive blocks into an auditable pre-compaction archive - acp_status lists archived blocks with reason; decompress returns an explicit error instead of silent failure or wrong-block content - prune byRaw/byRef to live raw ids at the boundary (stops the #390 additive leak); nextIndex is left alone so a freed ref slot is never re-allocated onto a retained tail's live tag --- src/agent/pi.ts | 16 +++++ src/decompress-shared.ts | 6 +- src/loop/core.ts | 11 ++- src/plugin.ts | 29 +++++++- src/server.ts | 19 ++++- src/session.ts | 76 ++++++++++++++++++++ tests/compaction-archive.test.ts | 116 +++++++++++++++++++++++++++++++ 7 files changed, 268 insertions(+), 5 deletions(-) create mode 100644 tests/compaction-archive.test.ts diff --git a/src/agent/pi.ts b/src/agent/pi.ts index 967f844ffe..e5fca5f17c 100644 --- a/src/agent/pi.ts +++ b/src/agent/pi.ts @@ -304,6 +304,22 @@ export function createBiliPlugin(agentOverride?: string, opts?: { retryIntervalM state.sid = undefined; void registerTools(pi, ctx, state, agent).catch((err: unknown) => console.error(`bili-plugin(${agent}): ${err instanceof Error ? err.message : String(err)}`)); }); + // omp fires session_compact on in-session native compaction (sid does + // not rotate), so the proxy reuses stale state — notify it to archive + // the now-unreachable blocks (#395). Fire-and-forget: a failed + // notification must never break the agent's compaction. + pi.on("session_compact", (_event, ctx) => { + const proxyBase = proxyBaseForCtx(ctx); + if (proxyBase === undefined) return; + const sid = sessionIdOf(ctx); + if (sid === undefined || sid.length === 0) return; + fetch(`${proxyBase}/__bili/plugin/compact`, { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ conversationId: sid }), + signal: AbortSignal.timeout(5000), + }).catch(() => {}); + }); }; } diff --git a/src/decompress-shared.ts b/src/decompress-shared.ts index cf6e176fed..fdf789a1e8 100644 --- a/src/decompress-shared.ts +++ b/src/decompress-shared.ts @@ -8,7 +8,7 @@ import { import { mkdirSync, unlinkSync, writeFileSync } from "node:fs"; import { dirname, join } from "node:path"; import { tmpdir } from "node:os"; -import type { Session } from "./session.js"; +import { preCompactionArchiveOf, type Session } from "./session.js"; /** Bounded retention for large-decompress temp files. Each decompress with * body > 10000 writes one file under tmpdir(); the reaper unlinks oldest past @@ -73,6 +73,10 @@ export function resolveDecompress( const blockId = rawBlockId.trim(); const block = ctx.core.decompress(blockId, ctx.session.state); if (!block) return `[Block ${blockId} not found]`; + const archived = preCompactionArchiveOf(ctx.session); + if (archived[blockId] !== undefined) { + return `[decompress FAILED: block ${blockId} is a pre-compaction archive — its content was in the history BEFORE the client's native compaction and is no longer reachable (replaced by the client's compaction summary). decompress is unavailable for archived blocks.]`; + } const full = args.full === true; const cached = ctx.session.blockContents.get(blockId); diff --git a/src/loop/core.ts b/src/loop/core.ts index ca10e68df0..e4331c3c1d 100644 --- a/src/loop/core.ts +++ b/src/loop/core.ts @@ -8,7 +8,7 @@ import { type CoreMessage, type NudgeDecision, } from "acp-kernel"; -import { lastCompressSuffix, type Session } from "../session.js"; +import { lastCompressSuffix, preCompactionArchiveOf, type Session } from "../session.js"; import type { BiliMessage } from "acp-kernel/wire"; import { parseCompressInput, @@ -141,6 +141,8 @@ function handleAcpStatus(args: Record, ctx: LoopCtx): string { const nudge = ctx.nudge; const ranges = nudge?.compressibleRanges ?? []; const protectedRanges = nudge?.protectedRanges ?? []; + const archive = preCompactionArchiveOf(ctx.session); + const archivedIds = Object.keys(archive); const extra: string[] = []; if (nudge) { extra.push(""); @@ -150,6 +152,13 @@ function handleAcpStatus(args: Record, ctx: LoopCtx): string { extra.push(""); extra.push(formatRanges(ranges, protectedRanges)); } + if (archivedIds.length > 0) { + extra.push(""); + extra.push(`PRE-COMPACTION ARCHIVE — ${archivedIds.length} block(s): content was replaced by the client's native compaction summary, so it is no longer in the session history and decompress is unavailable.`); + for (const id of archivedIds) { + extra.push(` ${id} — ${archive[id].reason}`); + } + } return extra.length > 0 ? `${base}\n${extra.join("\n")}` : base; } diff --git a/src/plugin.ts b/src/plugin.ts index 093bdb440e..f5caa9e416 100644 --- a/src/plugin.ts +++ b/src/plugin.ts @@ -3,7 +3,7 @@ import { buildStatusPanel } from "acp-kernel/panel"; import { fileURLToPath } from "node:url"; import fs from "node:fs"; import path from "node:path"; -import { acquireInFlight, listSessions, markDirty, peekSession, releaseInFlight, withSessionLock, type Session } from "./session.js"; +import { acquireInFlight, listSessions, markCompactionBoundary, markDirty, peekSession, releaseInFlight, withSessionLock, type Session } from "./session.js"; import { ACP_TOOLS_ANTHROPIC, ACP_TOOLS_OPENAI, ACP_TOOLS_RESPONSES, PROXY_TOOL_NAMES } from "./compress-tool.js"; import { executeProxyTool } from "./loop/core.js"; import { normalizeSseLineEndings } from "./sse-util.js"; @@ -279,6 +279,33 @@ export function handlePluginRegister(payload: string, res: import("node:http").S res.end(JSON.stringify({ ok: true, conversationId, agent })); } +export function handlePluginCompact(payload: string, res: import("node:http").ServerResponse): void { + let parsed: { conversationId?: unknown }; + try { + parsed = JSON.parse(payload) as { conversationId?: unknown }; + } catch { + res.writeHead(400, { "content-type": "application/json" }); + res.end(JSON.stringify({ ok: false, error: "invalid JSON body" })); + return; + } + const conversationId = typeof parsed.conversationId === "string" ? parsed.conversationId.trim() : ""; + if (!conversationId) { + res.writeHead(400, { "content-type": "application/json" }); + res.end(JSON.stringify({ ok: false, error: "conversationId is required" })); + return; + } + const entry = conversations.get(conversationId); + const session = entry ? peekSession(entry.sessionId) : undefined; + if (!entry || !session) { + res.writeHead(404, { "content-type": "application/json" }); + res.end(JSON.stringify({ ok: false, error: "unknown plugin conversation (no model request has arrived with this conversation id yet)" })); + return; + } + markCompactionBoundary(session); + entry.lastSeen = Date.now(); + res.end(JSON.stringify({ ok: true, conversationId })); +} + export function handlePluginManifest(res: import("node:http").ServerResponse): void { res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify({ diff --git a/src/server.ts b/src/server.ts index 351ea5f517..bae7382695 100644 --- a/src/server.ts +++ b/src/server.ts @@ -41,7 +41,7 @@ import { conversationSignalResponses, subagentNamespace, } from "acp-kernel/wire"; -import { getSession, listSessions, type Session, initSessions, markDirty, flushAllSessions, acquireInFlight, releaseInFlight, withSessionLock, markNativeCompactionBoundary, reconcileNativeCompactionBoundary, snapshotMessages } from "./session.js"; +import { getSession, listSessions, type Session, initSessions, markDirty, flushAllSessions, acquireInFlight, releaseInFlight, withSessionLock, markNativeCompactionBoundary, reconcileNativeCompactionBoundary, snapshotMessages, applyCompactionArchive } from "./session.js"; import { COMPRESS_TOOL, ACP_TOOLS_ANTHROPIC, ACP_TOOLS_OPENAI, ACP_TOOLS_RESPONSES, ACP_READONLY_TOOLS_RESPONSES, COMPRESS_TOOL_NAME, buildCompressSystemPrompt, buildCompressHybridSystemPrompt, withStagedCompressGuidance } from "./compress-tool.js"; import { rewriteSseStream, rewriteJsonResponse, type RewriteCtx } from "./stream.js"; import { applyRanges } from "./stream.js"; @@ -62,7 +62,7 @@ import { observeResponsesTerminalState } from "./stream-terminal.js"; import { emitStreamError } from "./stream-error.js"; import { affinityToken, clientConversationHeader, codexTurnIdentity, preferPromptCacheKeyIdentity, type ConversationIdentity } from "./session-id.js"; import { prefixAffinity, type AnonymousAffinity } from "./prefix-affinity.js"; -import { consumePluginRegisterFor, flushConversations, handlePluginManifest, handlePluginRegister, handlePluginStatus, handlePluginTool, loadConversations, pipePluginJson, pipePluginResponsesWithStrip, pipeThroughWithUsage, pluginAgentHeader, pluginConversationHeader, pluginReportedContextWindow, recordPluginSession, rememberPluginMessages, takePendingPluginRegister } from "./plugin.js"; +import { consumePluginRegisterFor, flushConversations, handlePluginCompact, handlePluginManifest, handlePluginRegister, handlePluginStatus, handlePluginTool, loadConversations, pipePluginJson, pipePluginResponsesWithStrip, pipeThroughWithUsage, pluginAgentHeader, pluginConversationHeader, pluginReportedContextWindow, recordPluginSession, rememberPluginMessages, takePendingPluginRegister } from "./plugin.js"; import { setupMitm, readMitmUpstream } from "./mitm.js"; import type { BiliMessage } from "acp-kernel/wire"; import { hoistMidSystemMessages, isLoopbackAddress, inspectContextOverflow, reserveOutputHeadroom, shouldReserveOutputHeadroom, usageTotals } from "./util.js"; @@ -681,6 +681,17 @@ async function handle( return; } } + if (req.method === "POST" && req.url === "/__bili/plugin/compact") { + try { + const body = await readBody(req); + handlePluginCompact(body.toString("utf8"), res); + return; + } catch (err) { + res.writeHead(err instanceof BodyTooLargeError ? 413 : 400, { "content-type": "application/json" }); + res.end(JSON.stringify({ ok: false, error: String(err) })); + return; + } + } // Unknown /__bili/ or /__acp/ path → 404 locally. These are bili's own // management prefixes; forwarding would leak the internal path to the // upstream (which 403s it) — #346. @@ -1314,6 +1325,7 @@ function prepareAnthropic( // estimates to the kernel. extractSystem(parsed.system); const tokenCount = session.stats.lastInputTokens; + const activeBefore = new Set(session.state.blocks.filter((b) => b.active).map((b) => b.blockId)); const turn = core.processTurn({ messages: msgs, state: session.state, config, tokenCount, renderTags: "text-only" }); session.state = turn.state; // The fold from last turn's compress has now materialized in state — @@ -1332,6 +1344,7 @@ function prepareAnthropic( log("info", diagTagSummary(turn.messages, sessionId, "text-only")); log("info", diagNudge(turn, sessionId, tokenCount, config.modelContextLimit, parsed.model)); processedMessages = stripKernelSummaries(turn.messages, turn.state); + applyCompactionArchive(session, activeBefore, new Set(msgs.map((m) => m.id)), log); reapOrphanBlocks(session, msgs, deactivateBlock); rebuiltMessages = coreToAnthropic(processedMessages as BiliMessage[], cacheControls); @@ -1408,6 +1421,7 @@ function prepareOpenai( // tokenCount = upstream's real input_tokens from the previous turn // (see anthropic branch comment). Never an estimate. const tokenCount = session.stats.lastInputTokens; + const activeBefore = new Set(session.state.blocks.filter((b) => b.active).map((b) => b.blockId)); const turn = core.processTurn({ messages: msgs, state: session.state, config, tokenCount, renderTags: "text-only" }); session.state = turn.state; // The fold from last turn's compress has now materialized in state — @@ -1426,6 +1440,7 @@ function prepareOpenai( log("info", diagTagSummary(turn.messages, sessionId, "text-only")); log("info", diagNudge(turn, sessionId, tokenCount, config.modelContextLimit, parsed.model)); processedMessages = stripKernelSummaries(turn.messages, turn.state); + applyCompactionArchive(session, activeBefore, new Set(msgs.map((m) => m.id)), log); reapOrphanBlocks(session, msgs, deactivateBlock); rebuiltMessages = hoistMidSystemMessages(coreToOpenai(processedMessages as BiliMessage[])); diff --git a/src/session.ts b/src/session.ts index c180c2ab38..a313166309 100644 --- a/src/session.ts +++ b/src/session.ts @@ -287,6 +287,82 @@ export function reconcileNativeCompactionBoundary(session: Session): boolean { return true; } +/** Mark a client-side native compaction (omp /compact on the anthropic wire). + * The sid does NOT rotate on in-session compaction, so the per-sid registry + * reuses the same key with stale state. Consumed by the NEXT processTurn via + * applyCompactionArchive (#395). Distinct from nativeCompactionBoundary + * (Responses/codex, which rebases by resetting state). */ +export function markCompactionBoundary(session: Session): void { + session.metadata.compactionBoundary = { + at: Date.now(), + pending: true, + }; + markDirty(session); +} + +type PreCompactionArchive = Record; + +function readPreCompactionArchive(session: Session): PreCompactionArchive { + const raw = session.metadata.preCompactionArchive; + if (raw && typeof raw === "object" && !Array.isArray(raw)) { + return raw as PreCompactionArchive; + } + return {}; +} + +export function preCompactionArchiveOf(session: Session): PreCompactionArchive { + return readPreCompactionArchive(session); +} + +// Must run AFTER the processTurn that followed markCompactionBoundary (so +// syncBlocks has deactivated the blocks whose raw ids left the shortened +// history). Blocks active in `activeBefore` but inactive now are archived; +// byRaw/byRef are pruned to liveRawIds (stops the #390 additive leak). +// nextIndex is left alone so a freed ref slot is never re-allocated onto a +// retained tail's live tag. +export function applyCompactionArchive( + session: Session, + activeBefore: Set, + liveRawIds: Set, + log: (level: string, msg: string) => void, +): void { + const boundary = session.metadata.compactionBoundary; + if (!boundary || typeof boundary !== "object" || !(boundary as Record).pending) { + return; + } + const activeAfter = new Set(session.state.blocks.filter((b) => b.active).map((b) => b.blockId)); + const deactivated = [...activeBefore].filter((id) => !activeAfter.has(id)); + if (deactivated.length > 0) { + const archive = readPreCompactionArchive(session); + const at = Date.now(); + for (const id of deactivated) { + archive[id] = { at, reason: "content replaced by client native compaction summary" }; + } + session.metadata.preCompactionArchive = archive; + } + + const { byRaw, byRef } = session.state.messageRefs; + const prunedByRaw: Record = {}; + for (const [rawId, ref] of Object.entries(byRaw)) { + if (liveRawIds.has(rawId)) prunedByRaw[rawId] = ref; + } + const prunedByRef: Record = {}; + for (const [ref, rawId] of Object.entries(byRef)) { + if (liveRawIds.has(rawId)) prunedByRef[ref] = rawId; + } + session.state.messageRefs.byRaw = prunedByRaw; + session.state.messageRefs.byRef = prunedByRef; + + session.metadata.compactionBoundary = { + ...(boundary as Record), + pending: false, + archivedAt: Date.now(), + archivedBlocks: deactivated, + }; + markDirty(session); + log("info", `[${session.id}] native compaction boundary: archived ${deactivated.length} pre-compaction block(s)${deactivated.length > 0 ? ` (${deactivated.join(", ")})` : ""}; pruned ref maps to ${prunedByRaw.length} live raw id(s)`); +} + /** Flush a session to disk and drop it from memory (LRU eviction). Refuses to * evict sessions that are in-flight or whose flush failed (would lose a * never-persisted session permanently). Returns true if a slot was freed. */ diff --git a/tests/compaction-archive.test.ts b/tests/compaction-archive.test.ts new file mode 100644 index 0000000000..354f6fdb0d --- /dev/null +++ b/tests/compaction-archive.test.ts @@ -0,0 +1,116 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { createCore, createInitialState, defaultConfig, type CoreMessage } from "acp-kernel"; +import type { Session } from "../src/session.ts"; +import { applyCompactionArchive, markCompactionBoundary, preCompactionArchiveOf } from "../src/session.ts"; +import { resolveDecompress } from "../src/decompress-shared.ts"; +import { executeProxyTool, type LoopCtx } from "../src/loop/core.ts"; + +function makeSession(): Session { + return { + id: `test-${Math.random().toString(36).slice(2)}`, + meta: {}, + stats: { requests: 0, tokensSaved: 0, inputTokens: 0, cachedTokens: 0, outputTokens: 0, cacheSamples: 0, lastInputTokens: 0, contextTokens: 0 }, + metadata: {}, + state: createInitialState(), + createdAt: Date.now(), + lastSeen: Date.now(), + blockContents: new Map(), + inFlight: 0, + persisted: false, + }; +} + +const noLog = (_level: string, _msg: string): void => {}; + +// One active block over m00001-m00007; tail = m00008-m00012 (omp's post-compact resend). +function sessionWithActiveBlock(): { session: Session; blockId: string; tail: CoreMessage[] } { + const session = makeSession(); + const core = createCore(); + const config = defaultConfig(200000); + const msgs: CoreMessage[] = []; + for (let i = 0; i < 12; i++) { + msgs.push({ id: `h_distinct${i}`, role: i % 2 === 0 ? "user" : "assistant", contentType: "text", text: `message ${i} ${"x".repeat(2000)}` }); + } + const turn = core.processTurn({ messages: msgs, state: session.state, config, tokenCount: 9999, renderTags: "text-only" }); + session.state = turn.state; + const res = core.applyCompression({ + ranges: [{ startRef: "m00001", endRef: "m00007", summary: "compressed early history that is long enough to pass the min summary length check" }], + messages: turn.messages, + state: turn.state, + config, + }); + session.state = res.state; + const block = session.state.blocks[session.state.blocks.length - 1]; + const tail: CoreMessage[] = []; + for (let i = 7; i < 12; i++) { + tail.push({ id: `h_distinct${i}`, role: i % 2 === 0 ? "user" : "assistant", contentType: "text", text: `message ${i} ${"x".repeat(2000)}` }); + } + return { session, blockId: block.blockId, tail }; +} + +// Mirrors server.ts prepareAnthropic: capture active ids → shortened-history +// turn (syncBlocks deactivates) → applyCompactionArchive. +function runShortenedTurn(session: Session, tail: CoreMessage[], boundary: boolean): string { + const core = createCore(); + const config = defaultConfig(200000); + const activeBefore = new Set(session.state.blocks.filter((b) => b.active).map((b) => b.blockId)); + if (boundary) markCompactionBoundary(session); + const turn = core.processTurn({ messages: tail, state: session.state, config, tokenCount: 9999, renderTags: "text-only" }); + session.state = turn.state; + applyCompactionArchive(session, activeBefore, new Set(tail.map((m) => m.id)), noLog); + return [...activeBefore].join(","); +} + +test("compaction archive: shortened-history resend degrades the block into an auditable archive", () => { + const { session, blockId, tail } = sessionWithActiveBlock(); + runShortenedTurn(session, tail, true); + const block = session.state.blocks.find((b) => b.blockId === blockId); + assert.equal(block?.active, false, "syncBlocks deactivates the block whose raw ids left the history"); + const archive = preCompactionArchiveOf(session); + assert.ok(archive[blockId] !== undefined, "block is recorded in the pre-compaction archive (not silently deactivated)"); + assert.match(archive[blockId]!.reason, /native compaction/); + const boundary = session.metadata.compactionBoundary as Record; + assert.equal(boundary.pending, false, "boundary is consumed"); + assert.ok(Array.isArray(boundary.archivedBlocks) && (boundary.archivedBlocks as string[]).includes(blockId), "archivedBlocks records the generation"); +}); + +test("compaction archive: WITHOUT the boundary the block is silently deactivated (old behavior preserved)", () => { + const { session, blockId, tail } = sessionWithActiveBlock(); + runShortenedTurn(session, tail, false); + const block = session.state.blocks.find((b) => b.blockId === blockId); + assert.equal(block?.active, false, "still deactivated by syncBlocks"); + const archive = preCompactionArchiveOf(session); + assert.equal(archive[blockId], undefined, "no archive entry without a marked boundary"); +}); + +test("compaction archive: byRaw/byRef are pruned to live ids (stops the additive leak)", () => { + const { session, tail } = sessionWithActiveBlock(); + const before = Object.keys(session.state.messageRefs.byRaw).length; + runShortenedTurn(session, tail, true); + const liveIds = new Set(tail.map((m) => m.id)); + for (const rawId of Object.keys(session.state.messageRefs.byRaw)) { + assert.ok(liveIds.has(rawId), `byRaw entry ${rawId} should have been pruned`); + } + assert.ok(Object.keys(session.state.messageRefs.byRaw).length < before, "byRaw shrank after the boundary"); +}); + +test("compaction archive: decompress on an archived block gives an explicit reason, not silent/wrong content", () => { + const { session, blockId, tail } = sessionWithActiveBlock(); + runShortenedTurn(session, tail, true); + const ctx = { core: createCore(), config: defaultConfig(200000), messages: tail, session, log: (_msg: string) => {} }; + const out = resolveDecompress({ blockId }, ctx); + assert.match(out, /decompress FAILED/); + assert.match(out, /pre-compaction archive/); + assert.match(out, /no longer reachable/); +}); + +test("compaction archive: acp_status surfaces the archive instead of listing it as active", () => { + const { session, blockId, tail } = sessionWithActiveBlock(); + runShortenedTurn(session, tail, true); + const ctx: LoopCtx = { core: createCore(), config: defaultConfig(200000), messages: tail, session, log: (_msg: string) => {} }; + const out = executeProxyTool("acp_status", {}, ctx); + assert.match(out, /PRE-COMPACTION ARCHIVE/); + assert.match(out, /decompress is unavailable/); + assert.ok(out.includes(blockId), "acp_status names the archived block"); +}); From 1b258eef0f26e331ffcd48c3330097923e7c1a15 Mon Sep 17 00:00:00 2001 From: ework-agent Date: Mon, 31 Aug 2026 23:57:17 +0800 Subject: [PATCH 2/2] docs: document POST /__bili/plugin/compact in the plugin protocol (#395) --- PLUGIN.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/PLUGIN.md b/PLUGIN.md index 8eeae76a96..8faf25363b 100644 --- a/PLUGIN.md +++ b/PLUGIN.md @@ -115,11 +115,21 @@ Context-level visibility for plugin UIs (status bars / slash commands): `contextTokens` is the last reported context size (input + cache-read) — the same value the nudge decision reads. Errors: `400` missing `conversationId`, `404` unknown conversation. -### 5. MITM transparent-proxy mode +### 5. `POST /__bili/plugin/compact` + +Notify the proxy that the agent performed an **in-session native compaction** (e.g. omp's `/compact` or its auto threshold): the next model request re-sends a shortened history (compaction summary + retained tail) under the SAME conversation id. Fire-and-forget is fine — a failed notification must never break the agent's compaction. + +```json +{ "conversationId": "the same value you send as x-bili-plugin-conversation" } +``` + +Effect: the proxy marks a one-shot compaction boundary on the session. On the next model request, blocks that were active before the compaction but no longer anchor into the shortened history are downgraded to a pre-compaction archive (listed by `acp_status` with a reason; `decompress` on one returns an explicit "unavailable" error instead of failing silently), and stale `byRaw`/`byRef` mappings are pruned to the live ids. Errors: `400` invalid JSON / missing `conversationId`, `404` unknown conversation. + +### 6. MITM transparent-proxy mode The `/bili/` prefix is absent in MITM mode, so URL-based detection cannot work. Instead the proxy's own launcher (`bili pi` / `bili codex` / `bili claude`) exports `BILLION_CONTEXT_PROXY=http://127.0.0.1:` in the child env, next to the `HTTPS_PROXY` + CA vars it already sets. A plugin detects cooperative mode by reading that env var (the proxy origin for all `/__bili/plugin/*` calls); everything else (headers, tool forwarding, status) is identical — the `x-bili-plugin*` headers pass through the MITM tunnel into the same pipeline. This is also where `x-bili-plugin-context-window` matters most: MITM upstreams are often private relays the models.dev registry doesn't know. -### 6. Lifecycle of one compression (what the plugin does) +### 7. Lifecycle of one compression (what the plugin does) 1. Model replies with a native `compress` tool call (args contain `startId`/`endId` refs it read from the tag-annotated context). 2. The agent ends the assistant turn; the plugin's tool handler fires.