opencode-acp 1.14.4 → 1.14.6

package/README.md

@@ -238,7 +238,6 @@ ACP provides an `/acp` slash command (also accepts `/dcp` for backward compatibi
 | `/acp`                  | Shows available ACP commands                                                                                                               |
 | `/acp context`          | Token usage breakdown by category (system, user, assistant, tools, etc.) and how much has been saved through pruning                       |
 | `/acp stats`            | Cumulative pruning statistics across all sessions                                                                                          |
-| `/acp sweep [n]`        | Prunes all tools since the last user message. Optional count: `/acp sweep 10` prunes the last 10 tools. Respects `commands.protectedTools` |
 | `/acp manual [on\|off]` | Toggle manual mode. When on, the AI will not autonomously use context management tools                                                     |
 | `/acp compress [focus]` | Trigger a single compress tool execution. Optional focus text directs what content to compress, following the active `compress.mode`       |
 | `/acp decompress <n>`   | Restore a specific active compression by ID. Running without an argument shows available compression IDs, token sizes, and topics          |
@@ -258,6 +257,8 @@ If no `acp.jsonc` is found, ACP falls back to `dcp.jsonc` / `dcp.json` (for back
 
 Each level overrides the previous, so project settings take priority over global. Restart OpenCode after making config changes.
 
+> **📖 Full parameter reference:** See [CONFIGURATION.md](./CONFIGURATION.md) for a complete reference of every configurable parameter with type, default value, and description.
+
 > [!IMPORTANT]
 > **Disable OpenCode's built-in auto-compaction.** ACP handles context management itself — OpenCode's compaction conflicts with ACP and can cause issues (re-expanded messages, lost compression state). Add to your `opencode.json`:
 >
@@ -294,16 +295,13 @@ Each level overrides the previous, so project settings take priority over global
     // Slash commands configuration
     "commands": {
         "enabled": true,
-        // Additional tools to protect from pruning via commands (e.g., /acp sweep)
+        // Additional tools to protect from pruning via commands
         "protectedTools": [],
     },
     // Manual mode: disables autonomous context management,
     // tools only run when explicitly triggered via /acp commands
     "manualMode": {
         "enabled": false,
-        // When true, automatic cleanup (deduplication, purgeErrors)
-        // still runs even in manual mode
-        "automaticStrategies": true,
     },
     // Protect from pruning for <turns> message turns past tool invocation
     "turnProtection": {
@@ -374,23 +372,6 @@ Each level overrides the previous, so project settings take priority over global
         // Warning: large copy-pasted prompts will never be compressed away
         "protectUserMessages": false,
     },
-    // Automatic pruning strategies
-    "strategies": {
-        // Remove duplicate tool calls (same tool with same arguments)
-        "deduplication": {
-            "enabled": true,
-            // Additional tools to protect from pruning
-            "protectedTools": [],
-        },
-        // Prune tool inputs for errored tools after X turns
-        "purgeErrors": {
-            "enabled": true,
-            // Number of turns before errored tool inputs are pruned
-            "turns": 4,
-            // Additional tools to protect from pruning
-            "protectedTools": [],
-        },
-    },
     // Garbage collection — hardcoded 100% fallback only
     "gc": {
         "algorithm": "truncate",
@@ -454,7 +435,7 @@ To reset an override, delete the matching file from your overrides directory.
 By default, these tools are always protected from pruning:
 `task`, `skill`, `todowrite`, `todoread`, `compress`, `decompress`, `batch`, `plan_enter`, `plan_exit`, `write`, `edit`
 
-The `protectedTools` arrays in `commands` and `strategies` add to this default list.
+The `protectedTools` array in `commands` adds to this default list.
 
 For the `compress` tool, `compress.protectedTools` ensures specific tool outputs are **hard-excluded** from compression ranges (v1.10.0+). When the model compresses a range that includes a protected tool message, that message survives intact in visible context — only the surrounding non-protected messages are compressed. The root default is `["skill", "compress"]` (the `compress` entry protects compress tool calls — which carry summaries — from being eaten by subsequent sequential compressions); an explicit array replaces the inherited policy. **`"compress"` is always force-protected regardless of user config** — its `summary` parameter is the sole record of compressed conversation and cannot be recovered if lost. Setting `[]` protects only `compress`; setting `["task"]` protects `task` and `compress`.
 
@@ -528,6 +509,22 @@ For the complete list with root cause analysis, see the [bug tracker](https://gi
 
 ## Changelog
 
+### v1.14.6 — Debug Nudge Chat Visibility (PR #226)
+
+**Problem**: With `debug: true`, ACP nudge injections (compression suggestions, context breakdown, tier triggers) were only visible via a 5-second toast and log files. The nudge suffix message is ephemeral — injected by the message-transform hook but never persisted to the conversation DB — so users could not see what the model was actually seeing in the chat UI. This made debugging nudge behavior very difficult.
+
+**Fix**: When `config.debug` is on, the `debugNotify` callback in `hooks.ts` now also calls `sendIgnoredMessage()` to persist the full nudge text to the conversation DB as an `ignored: true` user message (user-visible, model-invisible). The message is prefixed with `[ACP Debug Nudge]` for easy identification. Toast notification still shown alongside for backward compat. Debug OFF: behavior unchanged (no persisted messages).
+
+Files: `lib/hooks.ts`. No source logic changes. No config changes. No persisted-state schema changes. 937 tests pass.
+
+### v1.14.5 — GC Module Removal + Property-Based Tests + Issue #176 Fix + Config Docs (PRs #222, #206, #221, #223, #224)
+
+**Problem**: Five issues bundled. (1) **GC data-loss bugs** (PR #222): The `gc/truncate.ts` module had 4 confirmed bugs that could silently lose summaries — single-line truncation exceeded maxLength by 19 chars, barely-over-maxLength silently failed (longer than input), long-header output overrun, and off-by-one marker reservation. GC only triggered at 100% context (default), so it was rarely reached but catastrophic when it did. (2) **Dead code** (PR #206): Prune tool, sweep command, and strategies (~2309 lines) were never used — `prune` tool was replaced by `compress` tool, `sweep` was superseded by batch cleanup, strategies were vestigial. (3) **No property-based tests** (PR #221): All tests were targeted/unit tests — invariant violations across edge cases were undetectable. (4) **Missing config docs** (PR #223): No comprehensive config reference — users had to read source to discover parameters. (5) **Nudge permanently stops after compress** (PR #224, Issue #176): In autonomous sessions (single user message + many assistant/tool turns), `injectCompressNudges` had an unconditional early return when any compress was detected in the current turn. Since the entire session IS one turn, once compress happened, `currentTurnHasCompress` was always true → function always returned early → nudges never fired again → unbounded context growth.
+
+**Fix**: (1) PR #222 — Removed `gc/truncate.ts` entirely. Added `lib/messages/truncate-tools.ts`: emergency tool output truncation at `majorGcThresholdPercent` that truncates largest tool outputs (keeps prefix+suffix, skips summaries/text/messages, protects last 3 messages, skips already-truncated outputs). Never touches model-written summaries. Removed aging warning from nudge extension. `config.gc` fields kept for backward compat. (2) PR #206 — Removed dead prune tool, sweep command, dedup/purge strategies. ~2309 lines deleted. (3) PR #221 — Added `tests/property-invariants.test.ts`: 10 property-based tests using fast-check covering range exclusion invariants, compressible group construction, protected ref computation, nudge decision properties, pipeline consistency, and idempotency. ~1,400 random inputs per run. (4) PR #223 — Added `CONFIGURATION.md` + `CONFIGURATION.zh-CN.md`: comprehensive parameter reference documenting all 60+ config parameters with type, default, status (ACTIVE/DEPRECATED/EXPERIMENTAL), and description. (5) PR #224 — Added `lastProcessedCompressMessageId` to `Nudges` state (transient, not persisted). In `injectCompressNudges`, the early-return block now tracks which compress message was already processed. If the same compress ID is seen again, the early return is skipped and normal nudge evaluation proceeds. First-time compress still processes (clears anchors, adjusts baseline) and returns early. Failed/repeated compress calls are handled correctly.
+
+Files: `lib/gc/truncate.ts` (DELETED), `lib/messages/truncate-tools.ts` (NEW), `lib/hooks.ts`, `lib/prompts/extensions/nudge.ts`, `lib/compress/{prune-tool,status,decompress-logic,decompress,index}.ts` (DELETED), `lib/strategies/` (DELETED), `lib/commands/{sweep,stats,manual}.ts` (modified), `tests/property-invariants.test.ts` (NEW), `tests/property-bughunt.test.ts` (NEW), `CONFIGURATION.md` (NEW), `CONFIGURATION.zh-CN.md` (NEW), `lib/state/types.ts`, `lib/state/{state,utils}.ts`, `lib/messages/inject/inject.ts`. Tests: 937+ tests, 0 failures. E2E: 10 scenarios (added 09 + 10).
+
 ### v1.14.4 — Tier Detection + E2E Tests + Debug Notification + Nudge Loop Fix (PRs #215, #214, #217, #218)
 
 **Problem**: Four issues accumulated since v1.14.3. (1) **Tier misclassification** (PR #215): `applyCompressionState` determined the compression tier from `consumedBlockIds` — any consumed block bumped the tier up. This misclassified T1 compressions that incidentally overlapped existing T1 blocks as T2 (6 of 18 T2-labeled blocks in a real session were misclassified). (2) **E2E test gaps** (PR #214): E2E tests disabled all protection (`preserveRecentMessages: 0`), CI ran only 4/6 scenarios, and `verify.ts` only checked `blockCount` — the protection mechanism fixed 3× in v1.14.x was completely untested in E2E. (3) **Debug notifications invisible** (PR #217): With `debug: true`, compression notifications went to toast only — users couldn't see them in the chat session for debugging. (4) **Nudge injection loop** (PR #218, issue #216): `applyAnchoredNudges` fired before `nothingToCompress` was computed, so the nudge text ("compress now") was injected even when there was nothing to compress — the model saw a nudge with an empty recommendation list, tried random compressions, failed, and looped. Additionally, `messageHasCompress` only recognized `status === "completed"`, so failed compressions never reset the halved nudge threshold, keeping the loop alive.

package/README.zh-CN.md

@@ -193,7 +193,6 @@ ACP 提供 `/acp` 斜杠命令（为向后兼容也接受 `/dcp`）：
 | `/acp`                  | 显示可用的 ACP 命令                                                                                                 |
 | `/acp context`          | 按类别（system、user、assistant、tools 等）显示 token 用量明细，以及通过剪枝节省的量                                |
 | `/acp stats`            | 跨所有会话的累计剪枝统计                                                                                            |
-| `/acp sweep [n]`        | 剪除自上次用户消息以来的所有工具。可选数量：`/acp sweep 10` 剪除最近 10 个工具。遵循 `commands.protectedTools` 设置 |
 | `/acp manual [on\|off]` | 切换手动模式。开启后，AI 不会自动使用上下文管理工具                                                                 |
 | `/acp compress [focus]` | 触发一次 `compress` 工具执行。可选的焦点文本指示要压缩的内容，遵循当前 `compress.mode`                              |
 | `/acp decompress <n>`   | 按 ID 恢复特定的活动压缩。不带参数运行时显示可用的压缩 ID、token 大小和主题                                         |
@@ -213,6 +212,8 @@ ACP 使用自己的配置文件，按以下顺序搜索：
 
 每一层覆盖前一层，因此项目设置优先于全局设置。修改配置后请重启 OpenCode。
 
+> **📖 完整参数参考：** 请查看 [CONFIGURATION.zh-CN.md](./CONFIGURATION.zh-CN.md)（中文）或 [CONFIGURATION.md](./CONFIGURATION.md)（英文），包含每个可配置参数的类型、默认值和详细说明。
+
 > [!IMPORTANT]
 > **禁用 OpenCode 的内置自动压缩。** ACP 自行处理上下文管理 — OpenCode 的压缩与 ACP 冲突，可能导致问题（消息重新展开、压缩状态丢失）。请在 `opencode.json` 中添加：
 >
@@ -249,16 +250,13 @@ ACP 使用自己的配置文件，按以下顺序搜索：
     // Slash commands configuration
     "commands": {
         "enabled": true,
-        // Additional tools to protect from pruning via commands (e.g., /acp sweep)
+        // Additional tools to protect from pruning via commands
         "protectedTools": [],
     },
     // Manual mode: disables autonomous context management,
     // tools only run when explicitly triggered via /acp commands
     "manualMode": {
         "enabled": false,
-        // When true, automatic cleanup (deduplication, purgeErrors)
-        // still runs even in manual mode
-        "automaticStrategies": true,
     },
     // Protect from pruning for <turns> message turns past tool invocation
     "turnProtection": {
@@ -329,23 +327,6 @@ ACP 使用自己的配置文件，按以下顺序搜索：
         // Warning: large copy-pasted prompts will never be compressed away
         "protectUserMessages": false,
     },
-    // Automatic pruning strategies
-    "strategies": {
-        // Remove duplicate tool calls (same tool with same arguments)
-        "deduplication": {
-            "enabled": true,
-            // Additional tools to protect from pruning
-            "protectedTools": [],
-        },
-        // Prune tool inputs for errored tools after X turns
-        "purgeErrors": {
-            "enabled": true,
-            // Number of turns before errored tool inputs are pruned
-            "turns": 4,
-            // Additional tools to protect from pruning
-            "protectedTools": [],
-        },
-    },
     // 垃圾回收与批量清理
     "gc": {
         "algorithm": "truncate",
@@ -408,7 +389,7 @@ ACP 暴露六个可编辑的 prompt：
 默认情况下，以下工具始终受保护不被剪枝：
 `task`、`skill`、`todowrite`、`todoread`、`compress`、`decompress`、`batch`、`plan_enter`、`plan_exit`、`write`、`edit`
 
-`commands` 和 `strategies` 中的 `protectedTools` 数组会添加到此默认列表。
+`commands` 中的 `protectedTools` 数组会添加到此默认列表。
 
 对于 `compress` 工具，`compress.protectedTools` 确保特定工具的输出被**硬排除**在压缩范围之外（v1.10.0+）。当模型压缩包含受保护工具消息的范围时，该消息完整保留在可见上下文中 — 只有周围的非受保护消息被压缩。根默认值为 `["skill", "compress"]`（`compress` 条目保护携带 summary 的 compress 工具调用，防止被后续顺序压缩吞噬）；显式数组会替换继承的策略。**`"compress"` 无论用户如何配置都会被强制保护** — 其 `summary` 参数是已压缩对话的唯一记录，一旦丢失无法恢复。设置 `[]` 仅保护 `compress`；设置 `["task"]` 保护 `task` 和 `compress`。
 
@@ -482,6 +463,22 @@ ACP 在首次启动时自动将配置从 `dcp.jsonc` 迁移到 `acp.jsonc`，将
 
 ## 更新日志
 
+### v1.14.6 — Debug Nudge 聊天界面可见性（PR #226）
+
+**问题**：开启 `debug: true` 时，ACP nudge 注入（压缩建议、上下文分类、分层触发器）只能通过 5 秒 toast 和日志文件查看。nudge 后缀消息是临时的——由消息变换 hook 注入但从未持久化到会话数据库——因此用户无法在聊天界面看到模型实际看到的内容。这使得调试 nudge 行为非常困难。
+
+**修复**：当 `config.debug` 开启时，`hooks.ts` 中的 `debugNotify` 回调现在额外调用 `sendIgnoredMessage()`，将完整 nudge 文本以 `ignored: true` 用户消息形式持久化到会话数据库（用户可见，模型不可见）。消息前缀为 `[ACP Debug Nudge]` 便于识别。Toast 通知仍同时显示以保持向后兼容。Debug 关闭：行为不变（无持久化消息）。
+
+文件：`lib/hooks.ts`。无源逻辑变更。无配置变更。无持久化状态架构变更。937 项测试通过。
+
+### v1.14.5 — GC 模块移除 + 属性测试 + Issue #176 修复 + 配置文档（PRs #222, #206, #221, #223, #224）
+
+**问题**：打包修复 5 个问题。(1) **GC 数据丢失 Bug**（PR #222）：`gc/truncate.ts` 有 4 个已确认的 bug，可能静默丢失摘要——单行截断超过 maxLength 19 字符、刚好超过 maxLength 时静默失败（输出比输入更长）、长 header 输出溢出、标记预留 off-by-one。GC 默认只在 100% 上下文时触发，所以很少触发但触发时是灾难性的。(2) **死代码**（PR #206）：prune 工具、sweep 命令和策略（约 2309 行）从未被使用。(3) **无属性测试**（PR #221）：所有测试都是针对性/单元测试——不变量违反在边界情况下无法检测。(4) **缺少配置文档**（PR #223）：没有完整的配置参考——用户必须读源码才能发现参数。(5) **压缩后 nudge 永久停止**（PR #224，Issue #176）：在自治会话（单条用户消息 + 大量助手/工具消息）中，`injectCompressNudges` 在检测到当前 turn 有压缩时无条件 early return。由于整个会话就是一个 turn，一旦发生压缩，`currentTurnHasCompress` 永远为 true → 函数永远 early return → nudge 不再触发 → 上下文无限增长。
+
+**修复**：(1) PR #222——完全移除 `gc/truncate.ts`。新增 `lib/messages/truncate-tools.ts`：在 `majorGcThresholdPercent` 时紧急截断最大的工具输出（保留前后缀，跳过摘要/文本/消息，保护最后 3 条消息，跳过已截断的输出）。从不触碰模型写的摘要。从 nudge 扩展中移除老化警告。`config.gc` 字段保留以兼容旧配置。(2) PR #206——移除死掉的 prune 工具、sweep 命令、去重/清除策略。约 2309 行删除。(3) PR #221——新增 `tests/property-invariants.test.ts`：10 个基于 fast-check 的属性测试，覆盖范围排除不变量、可压缩分组构造、保护 ref 计算、nudge 决策属性、管线一致性和幂等性。每次运行约 1,400 个随机输入。(4) PR #223——新增 `CONFIGURATION.md` + `CONFIGURATION.zh-CN.md`：完整参数参考文档，记录所有 60+ 配置参数的类型、默认值、状态（活跃/废弃/实验性）和描述。(5) PR #224——在 `Nudges` 状态中新增 `lastProcessedCompressMessageId`（瞬态，不持久化）。在 `injectCompressNudges` 中，early-return 块现在跟踪已处理的 compress 消息 ID。如果再次看到同一个 compress ID，跳过 early return，进入正常 nudge 评估。首次 compress 仍然处理（清除锚点、调整基线）并 early return。
+
+文件：`lib/gc/truncate.ts`（删除）、`lib/messages/truncate-tools.ts`（新增）、`lib/hooks.ts`、`lib/prompts/extensions/nudge.ts`、`lib/compress/{prune-tool,status,decompress-logic,decompress,index}.ts`（删除）、`lib/strategies/`（删除）、`tests/property-invariants.test.ts`（新增）、`tests/property-bughunt.test.ts`（新增）、`CONFIGURATION.md`（新增）、`CONFIGURATION.zh-CN.md`（新增）、`lib/state/types.ts`、`lib/state/{state,utils}.ts`、`lib/messages/inject/inject.ts`。测试：937+ 通过，0 失败。E2E：10 个场景（新增 09 + 10）。
+
 ### v1.14.4 — Tier 检测 + E2E 测试 + Debug 通知 + Nudge 循环修复（PRs #215, #214, #217, #218）
 
 **问题**：自 v1.14.3 以来积累的 4 个问题。(1) **Tier 误分类**（PR #215）：`applyCompressionState` 从 `consumedBlockIds` 判断压缩层级——只要消费了任何已有 block 就会提升层级。这导致那些恰好覆盖了已有 T1 block 的 T1 压缩被错误分类为 T2（在一个真实 session 中，18 个标记为 T2 的 block 里有 6 个被误分类）。(2) **E2E 测试缺口**（PR #214）：E2E 测试禁用了所有保护（`preserveRecentMessages: 0`），CI 只运行 4/6 个场景，`verify.ts` 只检查 `blockCount`——v1.14.x 修了 3 次的保护机制在 E2E 里完全没有覆盖。(3) **Debug 通知不可见**（PR #217）：开启 `debug: true` 时，压缩通知只发到 toast——用户无法在 chat session 里看到用于调试的通知。(4) **Nudge 注入循环**（PR #218，issue #216）：`applyAnchoredNudges` 在 `nothingToCompress` 计算之前就触发，导致即使没有可压缩内容，nudge 文本（"compress now"）也被注入——模型看到 nudge 但推荐列表为空，尝试随机压缩、失败、循环。此外 `messageHasCompress` 只识别 `status === "completed"`，失败的压缩不会重置被减半的 nudge 阈值，循环持续。

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;AA6BjD,QAAA,MAAM,MAAM,EAAE,MAuHK,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;AA4BjD,QAAA,MAAM,MAAM,EAAE,MAoHK,CAAA;AAEnB,eAAe,MAAM,CAAA"}