@lexwdex-org/opencode-dcp 3.4.10 → 3.4.12

package/README.en.md

@@ -1,290 +1,91 @@
-# Dynamic Context Pruning Plugin
+# Dynamic Context Pruning for OpenCode
 
-[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/dansmolsky)
 [![npm version](https://img.shields.io/npm/v/@lexwdex-org/opencode-dcp.svg)](https://www.npmjs.com/package/@lexwdex-org/opencode-dcp)
 
-[**中文文档**](./README.md) | **English**
+**English** | [中文](./README.md)
 
-Automatically reduces token usage in OpenCode by managing conversation context.
+DCP supplies a semantic-pruning policy and proactive triggers to OpenCode's native compaction lifecycle. It does not own message markers, message IDs, compression blocks, anchors, or placeholders.
 
-![DCP in action](assets/images/dcp-demo9.png)
+## How it works
 
-## Installation
+OpenCode owns one rolling checkpoint. After compaction, the model sees only:
 
-Install from the CLI:
-
-```bash
-opencode plugin @lexwdex-org/opencode-dcp@latest --global
+```text
+latest pruned checkpoint + uncompacted recent tail
 ```
 
-This installs the package and adds it to your global OpenCode config.
-
-## How It Works
+During `experimental.session.compacting`, DCP asks the summarizer to organize the checkpoint into a fixed three-tier structure:
 
-DCP reduces context size through a compress tool and automatic cleanup. Your session history is never modified — DCP replaces pruned content with placeholders before sending requests to your LLM.
+- `## 系统上下文` (System context) — system-level rules such as AGENTS.md, carried forward verbatim from the previous checkpoint;
+- `## 历史概要` (History digest) — early and middle history heavily compressed: one-line outcomes only, no process;
+- Recent tasks — lightly compressed: completed tasks summarized in one line each; in-progress tasks keep full detail (goal, finished steps, file paths, key decisions, blockers, next actions). Details related to the current task are preserved first so work can continue from the checkpoint alone.
 
-### Compress
+Unrelated chat, other-project context, tool retries, and repeated edits are folded away as before.
 
-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.
+## Trigger compaction
 
-DCP supports two compression modes:
+- **OpenCode automatic compaction** uses the policy automatically.
+- **The `dcp_prune` model tool** — DCP registers an LLM-invokable tool whose description carries heuristic guidance: call it immediately when the topic clearly changes, when a task wraps up, or when the context has grown noticeably.
+- **Heuristic auto-prune** (`autoPrune`) — observes incoming user messages and triggers native compaction at turn boundaries (`session.idle`) on:
+    - topic drift: lexical similarity between the newest message and recent history drops sharply (CJK bigrams + Jaccard);
+    - message volume since the last prune crossing a threshold;
+    - resuming after a long idle gap.
+      Auto-triggers respect a cooldown; native `/compact` or host compaction also resets the counters.
+- OpenCode's native `/compact` command uses the same path.
+- `/dcp summarize` calls native `session.summarize()` manually.
 
-- `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.
+All entries share one coordinator: concurrent requests for the same session share a single native call. A failed call is fail-open and keeps the original context; retries are cooled down for 30 seconds by default.
 
-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.
+Pruned prefixes stop being sent to the model, but the original session history is not physically deleted from OpenCode's database. A later compaction replaces the previous checkpoint with one merged checkpoint instead of nesting summaries or building a compression-block graph.
 
-### Deduplication
+## Install
 
-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.
-
-### Purge Errors
-
-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.
+```bash
+opencode plugin @lexwdex-org/opencode-dcp@latest --global
+```
 
 ## Configuration
 
-DCP uses its own config file, searched in order:
-
-1. Global: `~/.config/opencode/dcp.jsonc` (or `dcp.json`), created automatically on first run
-2. Custom config directory: `$OPENCODE_CONFIG_DIR/dcp.jsonc` (or `dcp.json`), if `OPENCODE_CONFIG_DIR` is set
-3. Project: `.opencode/dcp.jsonc` (or `dcp.json`) in your project's `.opencode` directory
-
-Each level overrides the previous, so project settings take priority over global. Restart OpenCode after making config changes.
-
-> [!NOTE]
-> If you use models with smaller context windows, such as GitHub Copilot models or local models, lower `compress.minContextLimit` and `compress.maxContextLimit` in your configuration to match the available context.
-
-> [!IMPORTANT]
-> Defaults are applied automatically. Expand this if you want to review or override settings.
-
-<details>
-<summary><strong>Default Configuration</strong> (click to expand)</summary>
+DCP loads global, custom-config-directory, then project configuration:
 
 ```jsonc
 {
     "$schema": "https://raw.githubusercontent.com/LeXwDeX/opencode-dynamic-context-pruning/master/dcp.schema.json",
-    // Enable or disable the plugin
     "enabled": true,
-    // Check npm for a newer DCP release and show an update notification.
-    // The plugin never deletes or replaces its active installation.
     "autoUpdate": true,
-    // Enable debug logging to ~/.config/opencode/logs/dcp/
     "debug": false,
-    // Notification display: "off", "minimal", or "detailed"
-    "pruneNotification": "detailed",
-    // Notification type: "chat" (in-conversation) or "toast" (system toast)
-    "pruneNotificationType": "chat",
-    // Slash commands configuration
-    "commands": {
+    "commands": { "enabled": true },
+    "experimental": { "customPrompts": false },
+    "summarize": { "failureCooldownMs": 30000 },
+    "tool": { "enabled": true },
+    "autoPrune": {
         "enabled": true,
-        // Additional tools to protect from pruning via commands (e.g., /dcp sweep)
-        "protectedTools": [],
-    },
-    // Manual mode: disables autonomous context management,
-    // tools only run when explicitly triggered via /dcp 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": {
-        "enabled": false,
-        "turns": 4,
-    },
-    // Experimental settings
-    "experimental": {
-        // Allow DCP processing in subagent sessions
-        "allowSubAgents": false,
-        // Enable user-editable prompt overrides under dcp-prompts directories
-        // When false (default), prompt override files/directories are ignored
-        "customPrompts": false,
-    },
-    // Protect file operations from pruning via glob patterns
-    // Patterns match tool parameters.filePath (e.g. read/write/edit)
-    "protectedFilePatterns": [],
-    // Unified context compression tool and behavior settings
-    "compress": {
-        // Compression mode: "range" (compress spans into block summaries)
-        // or experimental "message" (compress individual raw messages)
-        "mode": "range",
-        // Permission mode: "allow" (no prompt), "ask" (prompt), "deny" (tool not registered)
-        "permission": "allow",
-        // Show compression content in a chat notification
-        "showCompression": false,
-        // Let active summary tokens extend the effective maxContextLimit
-        "summaryBuffer": true,
-        // Soft upper threshold: above this, DCP keeps injecting strong
-        // compression nudges (based on nudgeFrequency), so compression is
-        // much more likely. Accepts: number or "X%" of model context window.
-        "maxContextLimit": "85%",
-        // Soft lower threshold for reminder nudges: below this, turn/iteration
-        // reminders are off (compression less likely). At/above this, reminders
-        // are on. Accepts: number or "X%" of model context window.
-        "minContextLimit": "50%",
-        // Optional per-model override for maxContextLimit by providerID/modelID.
-        // If present, this wins over the global maxContextLimit.
-        // Accepts: number or "X%".
-        // Example:
-        // "modelMaxLimits": {
-        //     "openai/gpt-5.3-codex": 120000,
-        //     "anthropic/claude-sonnet-4.6": "80%"
-        // },
-        // Optional per-model override for minContextLimit.
-        // If present, this wins over the global minContextLimit.
-        // "modelMinLimits": {
-        //     "openai/gpt-5.3-codex": 50000,
-        //     "anthropic/claude-sonnet-4.6": "25%"
-        // },
-        // How often the context-limit nudge fires (1 = every fetch, 2 = every 2nd)
-        "nudgeFrequency": 2,
-        // Start adding compression reminders after this many
-        // messages have happened since the last user message
-        "iterationNudgeThreshold": 15,
-        // Controls how likely compression is after user messages
-        // ("strong" = more likely, "soft" = less likely)
-        "nudgeForce": "strong",
-        // Tool names whose completed outputs are appended to the compression
-        "protectedTools": [],
-        // Preserve text wrapped in <protect>...</protect> when compressed
-        "protectTags": false,
-        // Preserve your messages during compression.
-        // 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": [],
-        },
+        "minMessages": 8,
+        "volumeThreshold": 30,
+        "driftThreshold": 0.18,
+        "idleGapMs": 1800000,
+        "cooldownMs": 300000,
     },
 }
 ```
 
-</details>
-
-### Commands
-
-DCP provides a `/dcp` slash command:
-
-- `/dcp` — Shows available DCP commands
-- `/dcp context` — Shows a breakdown of your current session's token usage by category (system, user, assistant, tools, etc.) and how much has been saved through pruning.
-- `/dcp stats` — Shows cumulative pruning statistics across all sessions.
-- `/dcp sweep` — Prunes all tools since the last user message. Accepts an optional count: `/dcp sweep 10` prunes the last 10 tools. Respects `commands.protectedTools`.
-- `/dcp manual [on|off]` — Toggle manual mode or set explicit state. When on, the AI will not autonomously use context management tools.
-- `/dcp compress [focus]` — Trigger a single compress tool execution. Optional focus text directs what content to compress, following the active `compress.mode`.
-- `/dcp decompress <n>` — Restore a specific active compression by ID (for example `/dcp decompress 2`). Running without an argument shows available compression IDs, token sizes, and topics.
-- `/dcp recompress <n>` — Re-apply a user-decompressed compression by ID (for example `/dcp recompress 2`). Running without an argument shows recompressible IDs, token sizes, and topics.
-
-### Prompt Overrides
-
-DCP exposes six editable prompts:
-
-- `system`
-- `compress-range`
-- `compress-message`
-- `context-limit-nudge`
-- `turn-nudge`
-- `iteration-nudge`
-
-This feature is disabled by default. Set `experimental.customPrompts` to `true` in your DCP config to activate it.
-
-When enabled, managed defaults are written to `~/.config/opencode/dcp-prompts/defaults/` as plain-text prompt files. A single `README.md` in that directory explains each prompt and how to create overrides.
-
-To customize behavior, add a file with the same name under an overrides directory and edit it as plain text.
-
-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`
-
-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`.
-
-### External Model Compression
-
-Offload compression summaries to a cheaper model instead of using the expensive main model.
-
-#### Priority Chain
-
-| Priority     | Source                | Description                                            |
-| ------------ | --------------------- | ------------------------------------------------------ |
-| 1 (highest)  | Environment variables | `OPENCODE_DCP_EXTERNAL_COMPRESS_*`                     |
-| 2            | Project config        | `<project>/.opencode/dcp.jsonc:compress.externalModel` |
-| 3            | Global config         | `~/.config/opencode/dcp.jsonc:compress.externalModel`  |
-| 4 (fallback) | Main model            | Original behavior unchanged                            |
-
-#### Usage
-
-**Method 1 — Environment variables (recommended for quick setup):**
-
-```bash
-export OPENCODE_DCP_EXTERNAL_COMPRESS_URL="http://your-proxy-url/v1"
-export OPENCODE_DCP_EXTERNAL_COMPRESS_MODEL="your-model-name"
-# Optional:
-export OPENCODE_DCP_EXTERNAL_COMPRESS_KEY="your-api-key"
-export OPENCODE_DCP_EXTERNAL_COMPRESS_TIMEOUT="120000"
-export OPENCODE_DCP_EXTERNAL_COMPRESS_RETRIES="1"
-```
-
-Persist in shell RC (`~/.zshrc`, `~/.bashrc`) for automatic availability across sessions.
-
-**Method 2 — Config file (`dcp.jsonc`):**
-
-```jsonc
-{
-    "compress": {
-        "externalModel": {
-            "url": "http://your-proxy-url/v1",
-            "model": "your-model-name",
-            "apiKey": "your-api-key",
-            "timeout": 120000,
-            "retries": 1,
-        },
-    },
-}
-```
-
-#### Behavior
-
-| Scenario                                       | Behavior                                                                       |
-| ---------------------------------------------- | ------------------------------------------------------------------------------ |
-| External model configured + `summary` omitted  | Plugin fetches range content → calls external model → stores generated summary |
-| External model configured + `summary` provided | Plugin uses provided `summary` directly (backward compatible)                  |
-| External model call fails                      | Tool throws error; main model retries with fallback summary                    |
-| Not configured                                 | Everything unchanged — main model writes summaries as before                   |
-| `url` is not OpenAI-compatible                 | External model call fails → falls to error path above                          |
-
-**Compatibility:** Only OpenAI-compatible `/chat/completions` endpoints are supported (local proxies, OpenAI, DeepSeek, etc.).
-
-## Impact on Prompt Caching
-
-LLM providers cache prompts based on exact prefix matching. When DCP prunes content, it changes messages, which invalidates cached prefixes from that point forward.
+| Key                         | Meaning                                                                           |
+| --------------------------- | --------------------------------------------------------------------------------- |
+| `tool.enabled`              | Register the model-invokable `dcp_prune` tool with heuristic usage guidance       |
+| `autoPrune.enabled`         | Enable plugin-side heuristic auto-compaction                                      |
+| `autoPrune.minMessages`     | Minimum user messages before any auto-prune signal is considered                  |
+| `autoPrune.volumeThreshold` | User messages since the last prune that trigger compaction by volume              |
+| `autoPrune.driftThreshold`  | Jaccard similarity below which consecutive messages count as a topic change (0–1) |
+| `autoPrune.idleGapMs`       | Gap between user messages that counts as resuming after a long break              |
+| `autoPrune.cooldownMs`      | Minimum interval between two automatic prunes of the same session                 |
 
-**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.
+When `experimental.customPrompts` is enabled, copy the generated
+`~/.config/opencode/dcp-prompts/defaults/compaction.md` to a project, custom-config, or global `dcp-prompts/overrides/compaction.md` path.
 
-> [!NOTE]
-> In testing, cache hit rates were approximately 85% with DCP vs 90% without.
+## Migrating from the legacy 3.x pipeline
 
-**No impact for:**
+Legacy `compress`, `manualMode`, `strategies`, `turnProtection`, notification, protected-file, and command-protection settings are removed. DCP reports them as deprecated and ignores them.
 
-- **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.
+The old model tools, range/message compression, `/dcp compress`, decompression/recompression/sweep commands, message markers, and plugin compression persistence are gone. Existing legacy DCP state files are neither read nor modified; remove them manually only after deciding that you will not roll back.
 
-## License
+License: AGPL-3.0-or-later.