opencode-acp 1.3.1 → 1.4.1

package/README.md

@@ -22,19 +22,41 @@ The model decides <em>when</em> and <em>what</em> to compress — not a hard lim
 
 ## Why ACP
 
-ACP is a hardened fork of [DCP](https://github.com/Tarquinen/opencode-dynamic-context-pruning) with **35 bug fixes** applied. It turns context management from a passive, crash-prone mechanism into something stable enough for production use.
+ACP hands all context-management authority to the model itself — not relying on
+external models or any complex external mechanism to do context management. It
+is, to date, the best context-management implementation on the market.
 
-| | DCP (original) | ACP (this fork) |
-|---|---|---|
-| **Max stable session** | ~200 messages | 10,000+ messages |
-| **Per-turn overhead** | 20 -- 50 seconds | ~90ms |
-| **State persistence** | Lost on restart | Survives restart |
-| **GC effectiveness** | Never deactivates old blocks | Age-based auto-cleanup |
-| **Compress reliability** | Fails on edge cases, model gives up | Auto-recovers reversed boundaries |
+This brings two concrete effects:
+
+- **It saves about two-thirds of tokens.** A model with a 1,000,000-token context
+  window effectively runs in the **200,000–300,000 token range**.
+- **It supports ultra-long sessions without losing key content** — **500M-token-level
+  cumulative context, 100,000 messages per session**.
+
+---
 
-> **Active** means the model proactively decides *when* and *what* to compress -- as opposed to passive approaches that only react when context hits a hard limit. The model uses the `compress` tool to produce high-fidelity summaries of completed conversation segments, preserving important details while freeing context space. This is superior to passive truncation because the model controls what information to keep.
+## Proven at scale
 
-Key fixes include: state persistence across restarts, token usage reporting (was returning 0), summary message ID resolution, GC age-based deactivation, 268x logger/tokenizer speedup, auto-swap for reversed compress boundaries, and aging warning suppression at low context usage.
+Real engineering context, in practice.
+
+**Supports 500M-token-level cumulative context, with p95 context around 30% and
+an average prompt-cache hit ratio above 85%.** (That average — not per-session —
+is explained in [Impact on Prompt Caching](#impact-on-prompt-caching), where it
+turns out to save far more tokens than traditional compression.)
+
+| | Session 1 | Session 2 |
+|---|---|---|
+| **Messages** | 3,024 | 2,028 |
+| **Total tokens processed** | 582 M | 463 M |
+| **Prompt-cache hit ratio** | 86.2% | 89.0% |
+| **Context p50 (median)** | 1.2 K (<1%) | 1.8 K (<1%) |
+| **Context p75** | 2.8 K | 3.5 K |
+| **Context p90** | 108 K (11%) | 58 K (6%) |
+| **Context p95** | 251 K (25%) | 335 K (34%) |
+| **Context p99** | 425 K (43%) | 442 K (44%) |
+| **Peak** | 488 K (49%) | 769 K (77%) |
+
+(Context percentages are of the 1M window.)
 
 ---
 
@@ -58,26 +80,70 @@ Or add to your opencode config:
 
 ## How It Works
 
-ACP reduces context size through a compress tool and automatic cleanup. Your session history is never modified -- ACP replaces pruned content with placeholders before sending requests to your LLM.
+ACP hands the context-compression tool directly to the model. The model is
+**100% responsible** for context compression. The model's available tools are
+mainly: **compress**, **decompress**, and **delete** (`mark_block` / `unmark_block`).
+
+### Lifecycle
+
+Three operations: **compress**, **decompress**, and **delete**. Content loops
+between raw and compressed, and eventually terminates in deletion:
+
+```mermaid
+stateDiagram-v2
+    Raw --> Compressed : compress
+    Compressed --> Raw : decompress
+    Compressed --> Deleted : delete
+```
+
+### Compression strategy
+
+The system injects a prompt telling the model the current context ratio, the
+compression ratio, whether context is idle, and compression suggestions. When the
+trigger ratio is hit, content is compressed in **priority order**:
+
+1. Agent/subagent review & consultation results (largest block of uncompressed content)
+2. Verbose command output (build/test runs, git diff/log/status, directory listings)
+3. Exploration that led nowhere (failed approaches, dead-end searches)
+4. Redundant tool results (reading the same file repeatedly, repeated status checks)
+5. Intermediate steps of completed multi-step tasks
+6. Resolved discussion threads (once a decision is recorded)
+7. Large file contents already used
+
+After compression, the original content is replaced by a short **block** that
+references the original (recoverable via `decompress`).
 
-### Compress
+### Decompression strategy
 
-Compress is a tool exposed to your model that replaces closed, stale conversation content with high-fidelity technical summaries. You can think of this as a much smarter version of Opencode's compaction process. Instead of triggering statically when your session reaches its maximum context and on the entire coding session, Compress allows the model to pick when to activate based on task completion, and to only compress the specific messages that are no longer needed verbatim.
+The model decides when to decompress. When the context is large enough to
+interfere with the model's self-attention, short blocks lead the model to compress
+some content first, handle the urgent matter, then decompress what it needs in
+later work.
 
-ACP supports two compression modes:
+### Deletion strategy
 
-- **`range` mode** compresses contiguous spans of conversation into one or more summaries.
-- **`message` mode** (experimental) compresses individual raw messages independently, letting the model manage context much more surgically.
+To handle the accumulation of many small historical blocks, the new version adds
+a deletion strategy. The model decides whether to delete. **Once deleted, content
+is irrecoverable.** This replaces the original forced GC, so that forced garbage
+collection no longer deletes things the model considers important.
 
-In `range` mode, when a new compression overlaps an earlier one, the earlier summary is nested inside the new one so information is preserved through layers of compression rather than diluted away. In both modes, protected tool outputs (such as subagents and skills) and protected file patterns are kept in compression summaries, ensuring that the most important information is never lost. You can also enable `protectUserMessages` to preserve your messages verbatim during compression, though note that large prompts (e.g. copy-pasting log files in the prompt) will then never be compressed away.
+---
+
+## Impact on Prompt Caching
 
-### Deduplication
+Historically, ACP has fixed many of the low-cache-hit-rate problems caused by
+DCP. The overall cache hit rate is now **~87%**.
 
-Identifies repeated tool calls (same tool, same arguments) and keeps only the most recent output. Recalculated when the compress tool runs, so prompt cache is only impacted alongside compression.
+Compared to traditional compression — which only compresses at 80–90% and, once it
+compresses, forces 100% of the context to re-hit — ACP's hit rate is effectively
+higher.
 
-### Purge Errors
+Additionally, ACP keeps total context around **~30% most of the time**, versus the
+traditional **50–80%**. So total token savings are far higher than traditional
+compression.
 
-Prunes inputs from errored tool calls after a configurable number of turns (default: 4). Error messages are preserved; only the potentially large input content is removed. Recalculated on compress tool use.
+**Conclusion:** ACP simultaneously raises the overall cache hit rate **and**
+ensures key context information is not lost.
 
 ---
 
@@ -131,7 +197,7 @@ Each level overrides the previous, so project settings take priority over global
 
 ```jsonc
 {
-    "$schema": "https://raw.githubusercontent.com/Opencode-DCP/opencode-dynamic-context-pruning/master/dcp.schema.json",
+    "$schema": "https://raw.githubusercontent.com/ranxianglei/opencode-acp/master/dcp.schema.json",
     // Enable or disable the plugin
     "enabled": true,
     // Automatically update npm-installed ACP when a newer npm latest is available.
@@ -239,6 +305,28 @@ Each level overrides the previous, so project settings take priority over global
             "protectedTools": [],
         },
     },
+    // Garbage collection and batch cleanup
+    "gc": {
+        "algorithm": "truncate",
+        // young → old generation promotion after this many survivals
+        "promotionThreshold": 5,
+        // deactivate a block after this many survivals
+        "maxBlockAge": 15,
+        // truncate old-gen summaries exceeding this length (chars)
+        "maxOldGenSummaryLength": 3000,
+        // run major GC when context usage exceeds this
+        "majorGcThresholdPercent": "100%",
+        // Three-tier batch merge-cleanup for blocks flagged via mark_block.
+        // Accepts a number or "X%" of the model context window.
+        "batchCleanup": {
+            // At/above this usage, remind the model about marked blocks
+            "lowThreshold": "60%",
+            // At/above this usage, auto merge-compress all marked blocks into one
+            "highThreshold": "75%",
+            // At/above this usage, force-merge all old-gen blocks (before GC)
+            "forceThreshold": "90%",
+        },
+    },
 }
 ```
 
@@ -266,27 +354,11 @@ To reset an override, delete the matching file from your overrides directory.
 ### Protected Tools
 
 By default, these tools are always protected from pruning:
-`task`, `skill`, `todowrite`, `todoread`, `compress`, `batch`, `plan_enter`, `plan_exit`, `write`, `edit`
+`task`, `skill`, `todowrite`, `todoread`, `compress`, `decompress`, `mark_block`, `unmark_block`, `batch`, `plan_enter`, `plan_exit`, `write`, `edit`
 
 The `protectedTools` arrays in `commands` and `strategies` add to this default list.
 
-For the `compress` tool, `compress.protectedTools` ensures specific tool outputs are appended to the compressed summary. By default it includes `task`, `skill`, `todowrite`, and `todoread`.
-
----
-
-## Impact on Prompt Caching
-
-LLM providers cache prompts based on exact prefix matching. When ACP prunes content, it changes messages, which invalidates cached prefixes from that point forward.
-
-**Trade-off:** You lose some cache reads but gain token savings from reduced context size and fewer hallucinations from stale context. In most cases, especially in long sessions, the savings outweigh the cache miss cost.
-
-> [!NOTE]
-> In testing, cache hit rates were approximately 85% with ACP vs 90% without.
-
-**No impact for:**
-
-- **Request-based billing** -- Providers like GitHub Copilot that charge per request, not tokens.
-- **Uniform token pricing** -- Providers like Cerebras that bill cached and uncached tokens at the same rate.
+For the `compress` tool, `compress.protectedTools` ensures specific tool outputs are appended to the compressed summary. By default it includes `task`, `skill`, `todowrite`, `todoread`, and `decompress`.
 
 ---
 
@@ -317,7 +389,7 @@ ACP auto-migrates config from `dcp.jsonc` to `acp.jsonc` and prompts from `dcp-p
 ---
 
 <details>
-<summary><strong>Bug Fixes (35 total)</strong> -- applied on top of DCP v3.1.11</summary>
+<summary><strong>Bug Fixes (37 total)</strong> -- applied on top of DCP v3.1.11</summary>
 
 | # | Severity | Summary |
 |---|----------|---------|
@@ -345,6 +417,8 @@ ACP auto-migrates config from `dcp.jsonc` to `acp.jsonc` and prompts from `dcp-p
 | 22 | HIGH | compress throws hard error on reversed block boundaries -- model gives up |
 | 23--34 | MEDIUM | Various fixes for dedup, purge errors, schema validation, hook timing, etc. |
 | 35 | HIGH | Aging warnings shown at low context usage (<50%) -- triggers unnecessary compress, wastes tokens |
+| 36 | HIGH | Compression summary emitted as a standalone user message before the user's real turn -- model reads its own prior assistant output as user input, causing dialog role confusion / self-Q&A loops |
+| 37 | HIGH | Message-transform pipeline runs on OpenCode's hidden title/summary/compaction agent requests -- corrupts the request and shared session state, breaking session title generation |
 
 For the complete list with root cause analysis, see the [bug tracker](https://github.com/ranxianglei/opencode-acp/issues).
 

package/README.zh-CN.md

@@ -22,19 +22,34 @@
 
 ## 为什么选择 ACP
 
-ACP 是 [DCP](https://github.com/Tarquinen/opencode-dynamic-context-pruning) 的强化分支，已应用 **35 项错误修复**。它将上下文管理从一种被动、易崩溃的机制，转变为足以稳定运行于生产环境的方案。
+ACP 将上下文管理的所有权限全部交给模型自己，而不依靠外部模型或各种复杂的机制去做上下文管理。它是迄今为止，市面上对上下文管理最好的实现。
 
-| | DCP（原版） | ACP（本分支） |
-|---|---|---|
-| **最大稳定会话** | ~200 条消息 | 10,000+ 条消息 |
-| **每轮开销** | 20 -- 50 秒 | ~90ms |
-| **状态持久化** | 重启后丢失 | 重启后保留 |
-| **GC 有效性** | 从不停用旧块 | 基于年龄的自动清理 |
-| **Compress 可靠性** | 边界情况失败，模型放弃 | 自动恢复反转的边界 |
+这带来两个影响：
+
+- **省 token（约三分之二）。** 一个 100 万 token 上下文窗口的模型，实际只在 **20 万–30 万 token** 区间运行。
+- **超长上下文不丢关键内容** —— 支持 **5 亿级别上下文、单会话 10 万条消息**。
+
+---
 
-> **Active（主动）** 意味着模型主动决定*何时*压缩以及*压缩什么* — 与被动方式不同，被动方式仅在上下文触及硬性限制时才做出反应。模型使用 `compress` 工具对已完成的对话片段生成高保真摘要，在保留重要细节的同时释放上下文空间。这优于被动截断，因为模型可以自行控制保留哪些信息。
+## 实战验证
 
-主要修复包括：跨重启状态持久化、token 用量报告（此前返回 0）、摘要消息 ID 解析、基于年龄的 GC 停用、268 倍的日志/tokenizer 加速、压缩边界反转的自动交换，以及低上下文使用率时的老化警告抑制。
+真实工程中的上下文情况。
+
+**支持 5 亿级别 token，p95 上下文比例在 30% 左右，平均缓存命中率 85% 以上。**（注意这是平均缓存命中率，不是单会话命中率——后面[对 Prompt 缓存的影响](#对-prompt-缓存的影响)会解释，这实际上比传统压缩算法大幅度节省了 token。）
+
+| | 会话一 | 会话二 |
+|---|---|---|
+| **消息总条数** | 3,024 | 2,028 |
+| **累计处理 token** | 5.82 亿 | 4.63 亿 |
+| **prompt-cache 命中率** | 86.2% | 89.0% |
+| **上下文 p50（中位）** | 1.2 K（<1%） | 1.8 K（<1%） |
+| **上下文 p75** | 2.8 K | 3.5 K |
+| **上下文 p90** | 10.8 万（11%） | 5.8 万（6%） |
+| **上下文 p95** | 25.1 万（25%） | 33.5 万（34%） |
+| **上下文 p99** | 42.5 万（43%） | 44.2 万（44%） |
+| **峰值** | 48.8 万（49%） | 76.9 万（77%） |
+
+（上下文百分比均以 1M 窗口计。）
 
 ---
 
@@ -58,26 +73,52 @@ opencode plugin opencode-acp@latest --global
 
 ## 工作原理
 
-ACP 通过 `compress` 工具和自动清理来缩减上下文大小。你的会话历史永远不会被修改 — ACP 在向 LLM 发送请求之前，用占位符替换已剪枝的内容。
+ACP 把上下文压缩工具直接交给模型。模型对上下文压缩**负全责**。模型可用的工具主要是：**compress**、**decompress** 和 **delete**（`mark_block` / `unmark_block`）。
+
+### 生命周期
+
+三个操作：**压缩**、**解压缩**、**删除**。内容在原始与压缩之间循环，最终以删除终结：
+
+```mermaid
+stateDiagram-v2
+    Raw --> Compressed : compress
+    Compressed --> Raw : decompress
+    Compressed --> Deleted : delete
+```
+
+### 压缩策略
+
+系统会注入一段 prompt，告诉模型当前的上下文比例、压缩比例、上下文是否空闲，以及压缩建议。当触发比例被命中时，内容按**优先级顺序**被压缩：
+
+1. Agent/子代理的评审与咨询结果（最大一块未压缩内容）
+2. 冗长的命令输出（构建/测试运行、git diff/log/status、目录列表）
+3. 无结果的探索（失败的方法、死胡同式的搜索）
+4. 冗余的工具结果（反复读同一个文件、重复的状态检查）
+5. 已完成多步任务的中间步骤
+6. 已尘埃落定的讨论（一旦决策被记录）
+7. 已经用过的大段文件内容
+
+压缩完成后，原始内容被一个简短的 **block** 替换，该 block 引用原始内容（可通过 `decompress` 恢复）。
 
-### Compress
+### 解压策略
 
-Compress 是一个暴露给模型的工具，用高保真的技术摘要替换已关闭、过时的对话内容。你可以将其视为 OpenCode 内置压缩过程的更智能版本。与在会话达到最大上下文时静态触发并对整个编码会话进行压缩不同，Compress 允许模型根据任务完成情况选择何时激活，并且只压缩不再需要逐字保留的特定消息。
+由模型决定何时解压。当上下文大到足以干扰模型的 self-attention 时，简短的 block 会让模型先压缩一部分内容，处理完紧急事务，再在后续工作中按需解压。
 
-ACP 支持两种压缩模式：
+### 删除策略
 
-- **`range` 模式**将连续的对话片段压缩为一个或多个摘要。
-- **`message` 模式**（实验性）独立压缩单条原始消息，使模型能够更精细地管理上下文。
+为了应对大量小块历史内容的堆积，新版本增加了删除策略。由模型决定是否删除。**一旦删除，内容不可恢复。** 这取代了原先的强制 GC，使得强制垃圾回收不再删除模型认为重要的内容。
 
-在 `range` 模式下，当新的压缩与较早的压缩重叠时，较早的摘要会嵌套在新的摘要中，使信息通过压缩层级得以保留而非被稀释。在两种模式下，受保护的工具输出（如子代理和技能）以及受保护的文件模式会在压缩摘要中保留，确保最重要的信息永远不会丢失。你还可以启用 `protectUserMessages` 以在压缩过程中逐字保留你的消息，但请注意，大型提示（例如在提示中复制粘贴日志文件）将永远不会被压缩掉。
+---
+
+## 对 Prompt 缓存的影响
 
-### 去重
+历史上 ACP 修复了大量由 DCP 导致的低缓存命中率问题。目前整体缓存命中率约为 **87%**。
 
-识别重复的工具调用（相同工具、相同参数），仅保留最近的输出。在 `compress` 工具运行时重新计算，因此提示缓存仅在压缩时受到影响。
+相比传统压缩——只在 80–90% 时才压缩，一旦压缩就强制 100% 的上下文重新命中——ACP 的命中率实际上更高。
 
-### 清除错误
+此外：ACP 大部分时间将总上下文维持在 **~30%** 左右，而传统方案是 50–80%。因此总 token 节省远高于传统压缩。
 
-在可配置的轮次后（默认：4 轮）剪除出错工具调用的输入。错误消息被保留；仅移除可能很大的输入内容。在 `compress` 工具使用时重新计算。
+**结论：** ACP 在提高整体缓存命中率的同时，确保关键上下文信息不丢失。
 
 ---
 
@@ -131,7 +172,7 @@ ACP 使用自己的配置文件，按以下顺序搜索：
 
 ```jsonc
 {
-    "$schema": "https://raw.githubusercontent.com/Opencode-DCP/opencode-dynamic-context-pruning/master/dcp.schema.json",
+    "$schema": "https://raw.githubusercontent.com/ranxianglei/opencode-acp/master/dcp.schema.json",
     // Enable or disable the plugin
     "enabled": true,
     // Automatically update npm-installed ACP when a newer npm latest is available.
@@ -239,6 +280,28 @@ ACP 使用自己的配置文件，按以下顺序搜索：
             "protectedTools": [],
         },
     },
+    // 垃圾回收与批量清理
+    "gc": {
+        "algorithm": "truncate",
+        // 存活此次数后从新生代晋升为老年代
+        "promotionThreshold": 5,
+        // 存活此次数后停用该块
+        "maxBlockAge": 15,
+        // 截断超过此长度（字符）的老年代摘要
+        "maxOldGenSummaryLength": 3000,
+        // 上下文使用率超过此值时执行主 GC
+        "majorGcThresholdPercent": "100%",
+        // 通过 mark_block 标记的块的三级批量合并清理阈值。
+        // 接受数字或 "X%"（模型上下文窗口的百分比）。
+        "batchCleanup": {
+            // 达到此使用率时，提醒模型已标记的块
+            "lowThreshold": "60%",
+            // 达到此使用率时，自动将所有已标记块合并压缩为一个
+            "highThreshold": "75%",
+            // 达到此使用率时，强制合并所有老年代块（GC 之前）
+            "forceThreshold": "90%",
+        },
+    },
 }
 ```
 
@@ -266,27 +329,11 @@ ACP 暴露六个可编辑的 prompt：
 ### 受保护工具
 
 默认情况下，以下工具始终受保护不被剪枝：
-`task`、`skill`、`todowrite`、`todoread`、`compress`、`batch`、`plan_enter`、`plan_exit`、`write`、`edit`
+`task`、`skill`、`todowrite`、`todoread`、`compress`、`decompress`、`mark_block`、`unmark_block`、`batch`、`plan_enter`、`plan_exit`、`write`、`edit`
 
 `commands` 和 `strategies` 中的 `protectedTools` 数组会添加到此默认列表。
 
-对于 `compress` 工具，`compress.protectedTools` 确保特定工具的输出会被附加到压缩摘要中。默认包含 `task`、`skill`、`todowrite` 和 `todoread`。
-
----
-
-## 对 Prompt 缓存的影响
-
-LLM 提供商基于精确前缀匹配来缓存 prompt。当 ACP 剪枝内容时，它会修改消息，从而从该点开始使缓存的前缀失效。
-
-**权衡：** 你会损失一些缓存读取，但从缩减的上下文大小中获得 token 节省，并减少因过时上下文产生的幻觉。在大多数情况下，尤其是长会话中，节省的开销超过缓存未命中的代价。
-
-> [!NOTE]
-> 在测试中，使用 ACP 的缓存命中率约为 85%，不使用时约为 90%。
-
-**以下场景无影响：**
-
-- **按请求计费** — 如 GitHub Copilot 等按请求而非按 token 计费的提供商。
-- **统一 token 定价** — 如 Cerebras 等对缓存和未缓存 token 统一价格的提供商。
+对于 `compress` 工具，`compress.protectedTools` 确保特定工具的输出会被附加到压缩摘要中。默认包含 `task`、`skill`、`todowrite`、`todoread` 和 `decompress`。
 
 ---
 
@@ -317,7 +364,7 @@ ACP 在首次启动时自动将配置从 `dcp.jsonc` 迁移到 `acp.jsonc`，将
 ---
 
 <details>
-<summary><strong>错误修复（共 35 项）</strong> — 基于 DCP v3.1.11</summary>
+<summary><strong>错误修复（共 37 项）</strong> — 基于 DCP v3.1.11</summary>
 
 | # | 严重程度 | 摘要 |
 |---|----------|------|
@@ -345,6 +392,8 @@ ACP 在首次启动时自动将配置从 `dcp.jsonc` 迁移到 `acp.jsonc`，将
 | 22 | 高 | compress 在块边界反转时抛出硬错误 — 模型放弃 |
 | 23--34 | 中 | 去重、错误清除、schema 验证、hook 时序等方面的多项修复 |
 | 35 | 高 | 在低上下文使用率（<50%）时显示老化警告 — 触发不必要的 compress，浪费 token |
+| 36 | 高 | 压缩摘要作为独立的 user 消息插入在用户真实发言之前 — 模型把自己先前的 assistant 输出误读为用户输入，导致对话角色混乱 / 自问自答循环 |
+| 37 | 高 | 消息转换管线对 OpenCode 隐藏的 title/summary/compaction agent 请求也运行 — 污染请求并破坏共享会话状态，导致会话标题生成失效 |
 
 完整列表及根因分析，请参见 [Bug Tracker](https://github.com/ranxianglei/opencode-acp/issues)。
 

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAyBjD,QAAA,MAAM,MAAM,EAAE,MAkHK,CAAA;AAEnB,eAAe,MAAM,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AA2BjD,QAAA,MAAM,MAAM,EAAE,MAoHK,CAAA;AAEnB,eAAe,MAAM,CAAA"}