@dev4s/opencode-dcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tarquinen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# Dynamic Context Pruning Plugin
+
+[![npm version](https://img.shields.io/npm/v/@tarquinen/opencode-dcp.svg)](https://www.npmjs.com/package/@tarquinen/opencode-dcp)
+
+Automatically reduces token usage in OpenCode by removing obsolete tool outputs from conversation history.
+
+![DCP in action](dcp-demo3.png)
+
+## Installation
+
+Add to your OpenCode config:
+
+```jsonc
+// opencode.jsonc
+{
+    "plugin": ["@tarquinen/opencode-dcp@latest"],
+}
+```
+
+Using `@latest` ensures you always get the newest version automatically when OpenCode starts.
+
+> **Note:** If you use OAuth plugins (e.g., for Google or other services), place this plugin last in your `plugin` array to avoid interfering with their authentication flows.
+
+Restart OpenCode. The plugin will automatically start optimizing your sessions.
+
+## How Pruning Works
+
+DCP uses multiple tools and strategies to reduce context size:
+
+### Tools
+
+**Discard** — Exposes a `discard` tool that the AI can call to remove completed or noisy tool content from context.
+
+**Extract** — Exposes an `extract` tool that the AI can call to distill valuable context into concise summaries before removing the tool content.
+
+### Strategies
+
+**Deduplication** — Identifies repeated tool calls (e.g., reading the same file multiple times) and keeps only the most recent output. Runs automatically on every request with zero LLM cost.
+
+**Supersede Writes** — Prunes write tool inputs for files that have subsequently been read. When a file is written and later read, the original write content becomes redundant since the current file state is captured in the read result. Runs automatically on every request with zero LLM cost.
+
+**Purge Errors** — Prunes tool inputs for tools that returned errors after a configurable number of turns (default: 4). Error messages are preserved for context, but the potentially large input content is removed. Runs automatically on every request with zero LLM cost.
+
+**On Idle Analysis** — Uses a language model to semantically analyze conversation context during idle periods and identify tool outputs that are no longer relevant. Disabled by default (legacy behavior).
+
+Your session history is never modified—DCP replaces pruned content with placeholders before sending requests to your LLM.
+
+## Impact on Prompt Caching
+
+LLM providers like Anthropic and OpenAI cache prompts based on exact prefix matching. When DCP prunes a tool output, it changes the message content, which invalidates cached prefixes from that point forward.
+
+**Trade-off:** You lose some cache read benefits but gain larger token savings from reduced context size and performance improvements through reduced context poisoning. In most cases, the token savings outweigh the cache miss cost—especially in long sessions where context bloat becomes significant.
+
+**Best use case:** Providers that count usage in requests, such as Github Copilot and Google Antigravity have no negative price impact.
+
+## Configuration
+
+DCP uses its own config file:
+
+- Global: `~/.config/opencode/dcp.jsonc` (or `dcp.json`), created automatically on first run
+- Custom config directory: `$OPENCODE_CONFIG_DIR/dcp.jsonc` (or `dcp.json`), if `OPENCODE_CONFIG_DIR` is set
+- Project: `.opencode/dcp.jsonc` (or `dcp.json`) in your project’s `.opencode` directory
+
+<details>
+<summary><strong>Default Configuration</strong> (click to expand)</summary>
+
+```jsonc
+{
+    // Enable or disable the plugin
+    "enabled": true,
+    // Enable debug logging to ~/.config/opencode/logs/dcp/
+    "debug": false,
+    // Notification display: "off", "minimal", or "detailed"
+    "pruneNotification": "detailed",
+    // Protect from pruning for <turns> message turns
+    "turnProtection": {
+        "enabled": false,
+        "turns": 4,
+    },
+    // LLM-driven context pruning tools
+    "tools": {
+        // Shared settings for all prune tools
+        "settings": {
+            // Nudge the LLM to use prune tools (every <nudgeFrequency> tool results)
+            "nudgeEnabled": true,
+            "nudgeFrequency": 10,
+            // Additional tools to protect from pruning
+            "protectedTools": [],
+        },
+        // Removes tool content from context without preservation (for completed tasks or noise)
+        "discard": {
+            "enabled": true,
+        },
+        // Distills key findings into preserved knowledge before removing raw content
+        "extract": {
+            "enabled": true,
+            // Show distillation content as an ignored message notification
+            "showDistillation": 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 write tool inputs when the file has been subsequently read
+        "supersedeWrites": {
+            "enabled": true,
+        },
+        // 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": [],
+        },
+        // (Legacy) Run an LLM to analyze what tool calls are no longer relevant on idle
+        "onIdle": {
+            "enabled": false,
+            // Additional tools to protect from pruning
+            "protectedTools": [],
+            // Override model for analysis (format: "provider/model")
+            // "model": "anthropic/claude-haiku-4-5",
+            // Show toast notifications when model selection fails
+            "showModelErrorToasts": true,
+            // When true, fallback models are not permitted
+            "strictModelSelection": false,
+        },
+    },
+}
+```
+
+</details>
+
+### Turn Protection
+
+When enabled, turn protection prevents tool outputs from being pruned for a configurable number of message turns. This gives the AI time to reference recent tool outputs before they become prunable. Applies to both `discard` and `extract` tools, as well as automatic strategies.
+
+### Protected Tools
+
+By default, these tools are always protected from pruning across all strategies:
+`task`, `todowrite`, `todoread`, `discard`, `extract`, `batch`
+
+The `protectedTools` arrays in each section add to this default list.
+
+### Config Precedence
+
+Settings are merged in order:
+Defaults → Global (`~/.config/opencode/dcp.jsonc`) → Config Dir (`$OPENCODE_CONFIG_DIR/dcp.jsonc`) → Project (`.opencode/dcp.jsonc`).
+Each level overrides the previous, so project settings take priority over config-dir and global, which take priority over defaults.
+
+Restart OpenCode after making config changes.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from "@opencode-ai/plugin";
+declare const plugin: Plugin;
+export default plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,87 @@
+import { getConfig } from "./lib/config";
+import { Logger } from "./lib/logger";
+import { loadPrompt } from "./lib/prompt";
+import { createSessionState } from "./lib/state";
+import { createDiscardTool, createExtractTool } from "./lib/strategies";
+import { createChatMessageTransformHandler, createEventHandler } from "./lib/hooks";
+import { preloadTokenizer } from "./lib/tokenizer";
+const plugin = (async (ctx) => {
+    const config = getConfig(ctx);
+    if (!config.enabled) {
+        return {};
+    }
+    // Start loading tokenizer in background (non-blocking)
+    preloadTokenizer();
+    // Suppress AI SDK warnings
+    if (typeof globalThis !== "undefined") {
+        ;
+        globalThis.AI_SDK_LOG_WARNINGS = false;
+    }
+    const logger = new Logger(config.debug);
+    const state = createSessionState();
+    logger.info("DCP initialized", {
+        strategies: config.strategies,
+    });
+    return {
+        "experimental.chat.system.transform": async (_input, output) => {
+            const discardEnabled = config.tools.discard.enabled;
+            const extractEnabled = config.tools.extract.enabled;
+            let promptName;
+            if (discardEnabled && extractEnabled) {
+                promptName = "user/system/system-prompt-both";
+            }
+            else if (discardEnabled) {
+                promptName = "user/system/system-prompt-discard";
+            }
+            else if (extractEnabled) {
+                promptName = "user/system/system-prompt-extract";
+            }
+            else {
+                return;
+            }
+            const syntheticPrompt = loadPrompt(promptName);
+            output.system.push(syntheticPrompt);
+        },
+        "experimental.chat.messages.transform": createChatMessageTransformHandler(ctx.client, state, logger, config),
+        tool: {
+            ...(config.tools.discard.enabled && {
+                discard: createDiscardTool({
+                    client: ctx.client,
+                    state,
+                    logger,
+                    config,
+                    workingDirectory: ctx.directory,
+                }),
+            }),
+            ...(config.tools.extract.enabled && {
+                extract: createExtractTool({
+                    client: ctx.client,
+                    state,
+                    logger,
+                    config,
+                    workingDirectory: ctx.directory,
+                }),
+            }),
+        },
+        config: async (opencodeConfig) => {
+            // Add enabled tools to primary_tools by mutating the opencode config
+            // This works because config is cached and passed by reference
+            const toolsToAdd = [];
+            if (config.tools.discard.enabled)
+                toolsToAdd.push("discard");
+            if (config.tools.extract.enabled)
+                toolsToAdd.push("extract");
+            if (toolsToAdd.length > 0) {
+                const existingPrimaryTools = opencodeConfig.experimental?.primary_tools ?? [];
+                opencodeConfig.experimental = {
+                    ...opencodeConfig.experimental,
+                    primary_tools: [...existingPrimaryTools, ...toolsToAdd],
+                };
+                logger.info(`Added ${toolsToAdd.map((t) => `'${t}'`).join(" and ")} to experimental.primary_tools via config mutation`);
+            }
+        },
+        event: createEventHandler(ctx.client, config, state, logger, ctx.directory),
+    };
+});
+export default plugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}

package/dist/lib/config.d.ts

@@ -0,0 +1,58 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+export interface Deduplication {
+    enabled: boolean;
+    protectedTools: string[];
+}
+export interface OnIdle {
+    enabled: boolean;
+    model?: string;
+    showModelErrorToasts?: boolean;
+    strictModelSelection?: boolean;
+    protectedTools: string[];
+}
+export interface DiscardTool {
+    enabled: boolean;
+}
+export interface ExtractTool {
+    enabled: boolean;
+    showDistillation: boolean;
+}
+export interface ToolSettings {
+    nudgeEnabled: boolean;
+    nudgeFrequency: number;
+    protectedTools: string[];
+}
+export interface Tools {
+    settings: ToolSettings;
+    discard: DiscardTool;
+    extract: ExtractTool;
+}
+export interface SupersedeWrites {
+    enabled: boolean;
+}
+export interface PurgeErrors {
+    enabled: boolean;
+    turns: number;
+    protectedTools: string[];
+}
+export interface TurnProtection {
+    enabled: boolean;
+    turns: number;
+}
+export interface PluginConfig {
+    enabled: boolean;
+    debug: boolean;
+    pruneNotification: "off" | "minimal" | "detailed";
+    turnProtection: TurnProtection;
+    tools: Tools;
+    strategies: {
+        deduplication: Deduplication;
+        supersedeWrites: SupersedeWrites;
+        purgeErrors: PurgeErrors;
+        onIdle: OnIdle;
+    };
+}
+export declare const VALID_CONFIG_KEYS: Set<string>;
+export declare function getInvalidConfigKeys(userConfig: Record<string, any>): string[];
+export declare function getConfig(ctx: PluginInput): PluginConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/lib/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../lib/config.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEtD,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,OAAO,CAAA;IAChB,cAAc,EAAE,MAAM,EAAE,CAAA;CAC3B;AAED,MAAM,WAAW,MAAM;IACnB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,cAAc,EAAE,MAAM,EAAE,CAAA;CAC3B;AAED,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,OAAO,CAAA;IAChB,gBAAgB,EAAE,OAAO,CAAA;CAC5B;AAED,MAAM,WAAW,YAAY;IACzB,YAAY,EAAE,OAAO,CAAA;IACrB,cAAc,EAAE,MAAM,CAAA;IACtB,cAAc,EAAE,MAAM,EAAE,CAAA;CAC3B;AAED,MAAM,WAAW,KAAK;IAClB,QAAQ,EAAE,YAAY,CAAA;IACtB,OAAO,EAAE,WAAW,CAAA;IACpB,OAAO,EAAE,WAAW,CAAA;CACvB;AAED,MAAM,WAAW,eAAe;IAC5B,OAAO,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,cAAc,EAAE,MAAM,EAAE,CAAA;CAC3B;AAED,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;IACd,iBAAiB,EAAE,KAAK,GAAG,SAAS,GAAG,UAAU,CAAA;IACjD,cAAc,EAAE,cAAc,CAAA;IAC9B,KAAK,EAAE,KAAK,CAAA;IACZ,UAAU,EAAE;QACR,aAAa,EAAE,aAAa,CAAA;QAC5B,eAAe,EAAE,eAAe,CAAA;QAChC,WAAW,EAAE,WAAW,CAAA;QACxB,MAAM,EAAE,MAAM,CAAA;KACjB,CAAA;CACJ;AAKD,eAAO,MAAM,iBAAiB,aAuC5B,CAAA;AAgBF,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE,CAG9E;AAgmBD,wBAAgB,SAAS,CAAC,GAAG,EAAE,WAAW,GAAG,YAAY,CA2GxD"}