Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -360,6 +360,19 @@ For each request, the proxy resolves the settings by longest-URL-prefix match (t
- `toolName: string` — rename the injected tool (default `"absorb"`); the schema, system-prompt section and per-session adjudication all follow the name.
Injection follows the wire's native-tool surface: proxy mode injects the tool + a static system-prompt section on the anthropic/openai/responses native-tools wires, plugin mode advertises it in the plugin manifest (the MCP shell picks it up for free). Responses **marker/text-protocol** routes are not supported (no native tool surface — the REQUIRED absorb instruction would be unsatisfiable), and title-generation requests (`max_tokens ≤ 200`) skip injection like the compress prompt does. Absorbed pairs stay hidden across restarts (persisted in the session state).

#### `ccr`

- **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)
- **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.

#### `rules`

- **Type:** `boolean`
Expand Down
13 changes: 13 additions & 0 deletions CONFIGURATION.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -360,6 +360,19 @@
- `toolName: string` — 重命名注入工具(默认 `"absorb"`);模式、系统提示段与按会话裁决都跟随名称。
注入跟随线上原生工具面:代理模式在 anthropic/openai/responses 原生工具线上注入工具 + 静态系统提示段,插件模式在插件清单中广告它(MCP shell 自动拾取)。Responses **marker/文本协议**路由不支持(无原生工具面 — 强制的 absorb 指令不可满足),标题生成请求(`max_tokens ≤ 200`)跳过注入如压缩提示一样。吸收配对在重启后保持隐藏(在会话状态持久化)。

#### `ccr`

- **类型:** `object`(`{ enabled?, minToolTokens?, excludeTools?, toolName?, maxHeadChars? }`)
- **默认值:** *(禁用 — 除非显式设置 `enabled: true`,该特性完全关闭)*
- **状态:** ACTIVE(v1 — 仅代理模式、仅原生工具线)
- **说明:** 可选开启的**内容寻址消息存储**/内置 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 …` 日志。

#### `rules`

- **类型:** `boolean`
Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,8 @@ 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).

A sibling protection knob, `compress.protectedLatestTools` (see [CONFIGURATION.md](CONFIGURATION.md)), keeps the **latest** snapshot of a cumulative tool (a client's todo/task list, e.g. `["todo_list", "TodoWrite"]`) un-compressible while older instances fold normally — so the agent never loses its live task list to a fold (#639). Its full-history counterpart `compress.protectedTools` hard-excludes **every** instance of a tool — for independent-content results no later result supersedes (e.g. opencode/pi `skill` loads); protecting all instances of a chatty or cumulative-snapshot tool grows context without bound (#639), so keep it to low-frequency, high-value tools.

### Two compression modes — who executes `compress`
Expand Down
2 changes: 2 additions & 0 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,8 @@ QQ群:

可选的第六个工具 `acp_rule`(`compress.rules: true` —— 见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md))记录**持久化的原则级提醒**:模型记录的简短规则(用户强调的教训、要求记住的行为、撞到的大坑)受硬性保护不被压缩——调用及结果在每次折叠中都保留在上下文中——省略参数则列出已记录规则([ranxianglei/billion-context-pi#433](https://github.com/ranxianglei/billion-context-pi/issues/433))。

可选的第七个工具 `acp_retrieve`(`compress.ccr.enabled: true` —— 见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md))支撑**内容寻址消息存储**(内置 CCR,#1097):超大工具结果**在到达时改为 ID 引用,而非强制蒸馏**——线上保留字节稳定的占位符,原文进入按会话的内容存储信封(按内容哈希去重),模型通过一次廉价工具调用按需取回。默认无损:未执行的 retrieve 只花一次调用;而被 absorb 蒸馏掉的细节则永久丢失。v1 仅代理模式、仅原生工具线(marker/文本协议没有执行 retrieve 的通道,存储在这些场景下自动解除武装,而不是静默丢失内容)。

同族的保护开关 `compress.protectedLatestTools`(见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md))让累积型工具(客户端的 todo/任务清单,如 `["todo_list", "TodoWrite"]`)的**最新**快照永远不被压缩,旧实例照常折叠 —— agent 的活跃任务清单不会在折叠中丢失(#639)。其全历史对应项 `compress.protectedTools` 对工具的**全部实例**做硬排除 —— 适用于各次结果相互独立、后续结果不会取代旧结果的内容(如 opencode/pi 的 `skill` 加载);对高频或累积快照型工具保护全部实例会让上下文无界增长(#639),请只用于低频高价值工具。

**如何确认压缩真的生效了。** 代理执行 `compress` 后会以普通 assistant 文本发出确认标记(`📦 [ACP] Compressed …`)—— 但曾观察到模型在持续上下文压力下*自行书写该标记格式*而从未调用工具(#717):约 2 小时内 17 次假"压缩",真实用量一路爬到 89%。因此对话中看到的标记行本身不是持久化完成的证据 —— 请先用 `acp_status` 复核(块数 +1、可压缩区间起点前移)再采信。作为兜底,代理会剥离模型自发的标记形文本并记录 `[marker-echo]` 警告;注入的 nudge 与系统提示词也明确声明标记只由代理发出。
Expand Down
2 changes: 2 additions & 0 deletions src/absorb.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import {
} from "acp-kernel";
import { PROXY_TOOL_NAMES, RULE_TOOL_NAME } from "./compress-tool.js";
import { effectiveRulesConfig } from "./rules-feature.js";
import { ccrEnabled, retrieveToolName } from "./store.js";
import { log as loggerLog } from "./logger.js";
import type { Session } from "./session.js";

Expand Down Expand Up @@ -48,6 +49,7 @@ export function isProxyToolFor(name: string, session: Session | undefined, confi
if (PROXY_TOOL_NAMES.has(name)) return true;
const absorb = effectiveAbsorbConfig(session, config);
if (absorb?.enabled === true && name === (absorb.toolName ?? ABSORB_TOOL_NAME)) return true;
if (ccrEnabled(session) && name === retrieveToolName(session)) return true;
return effectiveRulesConfig(session, config)?.enabled === true && name === RULE_TOOL_NAME;
}

Expand Down
24 changes: 22 additions & 2 deletions src/acp-status.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import {
type CoreMessage,
} from "acp-kernel";
import { getBlindTunnelStats } from "./mitm.js";
import { ccrEnabled, contentStoreOf } from "./store.js";
import { preCompactionArchiveOf, type Session } from "./session.js";
import { VERSION } from "./version.js";

Expand All @@ -23,7 +24,13 @@ export interface AcpStatusCtx {
// compress mutates state mid-turn without re-running prepare, so the snapshot
// goes stale and lists already-compressed refs as compressible (#389).
// processTurn is pure (nodes return new objects), so the returned state is
// intentionally NOT adopted — this is a read-only recompute.
// intentionally NOT adopted — this is a read-only recompute.
function fmtBytes(n: number): string {
if (n < 1024) return `${n}B`;
if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KiB`;
return `${(n / (1024 * 1024)).toFixed(1)}MiB`;
}

export function handleAcpStatus(args: Record<string, unknown>, ctx: AcpStatusCtx): string {
const scope = typeof args.scope === "string" ? (args.scope as "compressed" | "uncompressed") : undefined;
const view = typeof args.view === "string" ? (args.view as "ranges" | "messages") : undefined;
Expand All @@ -47,9 +54,10 @@ export function handleAcpStatus(args: Record<string, unknown>, ctx: AcpStatusCtx
const turn = ctx.core.processTurn({
messages: ctx.messages,
state: ctx.session.state,
config: ctx.config,
config: ccrEnabled(ctx.session) ? ctx.config : { ...ctx.config, ccr: undefined },
tokenCount: ctx.session.stats.lastInputTokens,
renderTags: "none",
contentStore: contentStoreOf(ctx.session),
});
const nudge = turn.nudge;
if (nudge) {
Expand All @@ -69,6 +77,18 @@ export function handleAcpStatus(args: Record<string, unknown>, ctx: AcpStatusCtx
} catch {
// Base-only report; never fall back to a stale snapshot.
}
// #1097: the processTurn above already resolved the envelope when armed
// (contentStoreOf is idempotent); when disarmed skip the disk read.
const ccrArmed = ccrEnabled(ctx.session);
const storeCount = ccrArmed ? Object.keys(contentStoreOf(ctx.session).byRef).length : 0;
if (ccrArmed && (storeCount > 0 || (ctx.session.stats.retrieveCalls ?? 0) > 0)) {
const st = ctx.session.stats;
const calls = st.retrieveCalls ?? 0;
const hits = st.retrieveHits ?? 0;
const rate = calls > 0 ? Math.round((hits / calls) * 100) : 0;
extra.push("");
extra.push(`STORE (CCR) — ${storeCount} item(s) · ${fmtBytes(st.storedBytes ?? 0)} stored · ${fmtBytes(st.storeBytesSaved ?? 0)} saved on wire · retrieved ${hits}/${calls}${calls > 0 ? ` (${rate}%)` : ""}`);
}
const archive = preCompactionArchiveOf(ctx.session);
const archivedIds = Object.keys(archive);
if (archivedIds.length > 0) {
Expand Down
9 changes: 9 additions & 0 deletions src/compress-loop-responses.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import { parseCompressInput, PROXY_TOOL_NAMES, MUTATING_PROXY_TOOLS, COMPRESS_TO
import { log as loggerLog } from "./logger.js";
import { applyRanges } from "./stream.js";
import { executeSearchContextTarget, resolveDecompress } from "./decompress-shared.js";
import { ccrEnabled, drainPendingRetrievals, executeRetrieve, retrieveToolName } from "./store.js";
import { buildVisibilityMarker } from "./compress-loop.js";
import { hoistTrappedToolItems, type ToolPairItem } from "./tool-pair-order.js";
import { MAX_LOOP_ROUNDS } from "./loop/index.js";
Expand Down Expand Up @@ -104,6 +105,9 @@ function executeProxyTool(
if (toolName === "acp_cache") {
return handleAcpCache(ctx.session, args);
}
if (ccrEnabled(ctx.session) && toolName === retrieveToolName(ctx.session)) {
return executeRetrieve(args, ctx.session);
}
return `[Unknown proxy tool: ${toolName}]`;
}

Expand Down Expand Up @@ -221,6 +225,11 @@ export async function compressLoopResponsesJson(
ctx.log(`[acp-proxy: responses JSON ${call.name} → ${result.slice(0, 120).replace(/\n/g, " ")}]`);
if (ctx.visibilityMarkers !== false) inputItems.push({ type: "message", role: "developer", content: buildVisibilityMarker(call.name, result) });
}
// #1097: retrieval injections ride the re-request after their ack —
// coreToResponses re-voices system as developer, so mirror that here.
for (const injection of drainPendingRetrievals(ctx.session)) {
inputItems.push({ type: "message", role: "developer", content: [{ type: "output_text", text: injection.text }] });
}
requestBody.input = hoistTrappedToolItems(inputItems as ToolPairItem[]);
const result = await fetchWithRetry(requestOptions.url, {
method: "POST",
Expand Down
Loading
Loading