Add context_pruning tool and refactor config to strategies-based system

- Add AI-callable context_pruning tool that lets the model trigger pruning on demand
- Replace pruningMode (auto/smart) with strategies config (onIdle/onTool arrays)
- Add config validation with automatic backup (.bak) and reset on deprecated keys
- Show toast notification when config is upgraded
- Refactor janitor to support both idle-triggered and tool-triggered pruning

Author: Tarquinen

.gitignore

@@ -30,3 +30,6 @@ Thumbs.db
 
 # Tests (local development only)
 tests/
+
+# Development notes
+notes/

index.ts

@@ -1,8 +1,10 @@
 // index.ts - Main plugin entry point for Dynamic Context Pruning
 import type { Plugin } from "@opencode-ai/plugin"
+import { tool } from "@opencode-ai/plugin"
 import { getConfig } from "./lib/config"
 import { Logger } from "./lib/logger"
 import { Janitor, type SessionStats } from "./lib/janitor"
+import { formatTokenCount } from "./lib/tokenizer"
 import { checkForUpdates } from "./lib/version-checker"
 
 /**
@@ -20,7 +22,7 @@ async function isSubagentSession(client: any, sessionID: string): Promise<boolea
 }
 
 const plugin: Plugin = (async (ctx) => {
-    const config = getConfig(ctx)
+    const { config, migrations } = getConfig(ctx)
 
     // Exit early if plugin is disabled
     if (!config.enabled) {
@@ -38,7 +40,7 @@ const plugin: Plugin = (async (ctx) => {
     const statsState = new Map<string, SessionStats>()
     const toolParametersCache = new Map<string, any>() // callID -> parameters
     const modelCache = new Map<string, { providerID: string; modelID: string }>() // sessionID -> model info
-    const janitor = new Janitor(ctx.client, prunedIdsState, statsState, logger, toolParametersCache, config.protectedTools, modelCache, config.model, config.showModelErrorToasts, config.pruningMode, config.pruning_summary, ctx.directory)
+    const janitor = new Janitor(ctx.client, prunedIdsState, statsState, logger, toolParametersCache, config.protectedTools, modelCache, config.model, config.showModelErrorToasts, config.pruning_summary, ctx.directory)
 
     const cacheToolParameters = (messages: any[]) => {
         for (const message of messages) {
@@ -142,13 +144,31 @@ const plugin: Plugin = (async (ctx) => {
     }
 
     logger.info("plugin", "DCP initialized", {
-        mode: config.pruningMode,
+        strategies: config.strategies,
         model: config.model || "auto"
     })
 
     // Check for updates on launch (fire and forget)
     checkForUpdates(ctx.client, logger).catch(() => {})
 
+    // Show migration toast if config was migrated (delayed to not overlap with version toast)
+    if (migrations.length > 0) {
+        setTimeout(async () => {
+            try {
+                await ctx.client.tui.showToast({
+                    body: {
+                        title: "DCP: Config upgraded",
+                        message: migrations.join('\n'),
+                        variant: "info",
+                        duration: 8000
+                    }
+                })
+            } catch {
+                // Silently fail - toast is non-critical
+            }
+        }, 7000) // 7s delay to show after version toast (6s) completes
+    }
+
     return {
         /**
          * Event Hook: Triggers janitor analysis when session becomes idle
@@ -157,9 +177,12 @@ const plugin: Plugin = (async (ctx) => {
             if (event.type === "session.status" && event.properties.status.type === "idle") {
                 // Skip pruning for subagent sessions
                 if (await isSubagentSession(ctx.client, event.properties.sessionID)) return
+                
+                // Skip if no idle strategies configured
+                if (config.strategies.onIdle.length === 0) return
 
                 // Fire and forget the janitor - don't block the event handler
-                janitor.run(event.properties.sessionID).catch(err => {
+                janitor.runOnIdle(event.properties.sessionID, config.strategies.onIdle).catch(err => {
                     logger.error("janitor", "Failed", { error: err.message })
                 })
             }
@@ -188,6 +211,37 @@ const plugin: Plugin = (async (ctx) => {
                 })
             }
         },
+
+        /**
+         * Tool Hook: Exposes context_pruning tool to AI (if configured)
+         */
+        tool: config.strategies.onTool.length > 0 ? {
+            context_pruning: tool({
+                description: "Performs semantic pruning on session tool outputs that are no longer " +
+                    "relevant to the current task. Use this to declutter the conversation context and " +
+                    "filter signal from noise when you notice the context is getting cluttered with " +
+                    "outdated information (e.g., after completing a debugging session, switching to a " +
+                    "new task, or when old file reads are no longer needed).",
+                args: {
+                    reason: tool.schema.string().optional().describe(
+                        "Brief reason for triggering pruning (e.g., 'task complete', 'switching focus')"
+                    ),
+                },
+                async execute(args, ctx) {
+                    const result = await janitor.runForTool(
+                        ctx.sessionID,
+                        config.strategies.onTool,
+                        args.reason
+                    )
+
+                    if (!result || result.prunedCount === 0) {
+                        return "No prunable tool outputs found. Context is already optimized."
+                    }
+
+                    return `Context pruning complete. Pruned ${result.prunedCount} tool outputs (~${formatTokenCount(result.tokensSaved)} tokens saved).`
+                },
+            }),
+        } : undefined,
     }
 }) satisfies Plugin
 

lib/config.ts

@@ -1,30 +1,59 @@
 // lib/config.ts
-import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from 'fs'
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync, copyFileSync } from 'fs'
 import { join, dirname } from 'path'
 import { homedir } from 'os'
 import { parse } from 'jsonc-parser'
 import { Logger } from './logger'
 import type { PluginInput } from '@opencode-ai/plugin'
 
+// Pruning strategy types
+export type PruningStrategy = "deduplication" | "llm-analysis"
+
 export interface PluginConfig {
     enabled: boolean
     debug: boolean
     protectedTools: string[]
     model?: string // Format: "provider/model" (e.g., "anthropic/claude-haiku-4-5")
     showModelErrorToasts?: boolean // Show toast notifications when model selection fails
-    pruningMode: "auto" | "smart" // Pruning strategy: auto (deduplication only) or smart (deduplication + LLM analysis)
     pruning_summary: "off" | "minimal" | "detailed" // UI summary display mode
+    strategies: {
+        // Strategies for automatic pruning (on session idle). Empty array = idle pruning disabled
+        onIdle: PruningStrategy[]
+        // Strategies for the AI-callable tool. Empty array = tool not exposed to AI
+        onTool: PruningStrategy[]
+    }
+}
+
+export interface ConfigResult {
+    config: PluginConfig
+    migrations: string[] // List of migration messages to show user
 }
 
 const defaultConfig: PluginConfig = {
     enabled: true, // Plugin is enabled by default
     debug: false, // Disable debug logging by default
-    protectedTools: ['task', 'todowrite', 'todoread'], // Tools that should never be pruned (including stateful tools)
+    protectedTools: ['task', 'todowrite', 'todoread', 'context_pruning'], // Tools that should never be pruned
     showModelErrorToasts: true, // Show model error toasts by default
-    pruningMode: 'smart', // Default to smart mode (deduplication + LLM analysis)
-    pruning_summary: 'detailed' // Default to detailed summary
+    pruning_summary: 'detailed', // Default to detailed summary
+    strategies: {
+        // Default: Full analysis on idle (like previous "smart" mode)
+        onIdle: ['deduplication', 'llm-analysis'],
+        // Default: Only deduplication when AI calls the tool (faster, no extra LLM cost)
+        onTool: ['deduplication']
+    }
 }
 
+// Valid top-level keys in the current config schema
+const VALID_CONFIG_KEYS = new Set([
+    'enabled',
+    'debug',
+    'protectedTools',
+    'model',
+    'showModelErrorToasts',
+    'pruning_summary',
+    'strategies'
+])
+
 const GLOBAL_CONFIG_DIR = join(homedir(), '.config', 'opencode')
 const GLOBAL_CONFIG_PATH_JSONC = join(GLOBAL_CONFIG_DIR, 'dcp.jsonc')
 const GLOBAL_CONFIG_PATH_JSON = join(GLOBAL_CONFIG_DIR, 'dcp.json')
@@ -106,10 +135,17 @@ function createDefaultConfig(): void {
   // Set to false to disable these informational toasts
   "showModelErrorToasts": true,
 
-  // Pruning strategy:
-  // "auto": Automatic duplicate removal only (fast, no LLM cost)
-  // "smart": Deduplication + AI analysis for intelligent pruning (recommended)
-  "pruningMode": "smart",
+  // Pruning strategies configuration
+  // Available strategies: "deduplication", "llm-analysis"
+  // Empty array = disabled
+  "strategies": {
+    // Strategies to run when session goes idle (automatic)
+    "onIdle": ["deduplication", "llm-analysis"],
+    
+    // Strategies to run when AI calls the context_pruning tool
+    // Empty array = tool not exposed to AI
+    "onTool": ["deduplication"]
+  },
 
   // Pruning summary display mode:
   // "off": No UI summary (silent pruning)
@@ -120,7 +156,8 @@ function createDefaultConfig(): void {
   // List of tools that should never be pruned from context
   // "task": Each subagent invocation is intentional
   // "todowrite"/"todoread": Stateful tools where each call matters
-  "protectedTools": ["task", "todowrite", "todoread"]
+  // "context_pruning": The pruning tool itself
+  "protectedTools": ["task", "todowrite", "todoread", "context_pruning"]
 }
 `
 
@@ -130,15 +167,65 @@ function createDefaultConfig(): void {
 /**
  * Loads a single config file and parses it
  */
-function loadConfigFile(configPath: string): Partial<PluginConfig> | null {
+function loadConfigFile(configPath: string): Record<string, any> | null {
     try {
         const fileContent = readFileSync(configPath, 'utf-8')
-        return parse(fileContent) as Partial<PluginConfig>
+        return parse(fileContent)
     } catch (error: any) {
         return null
     }
 }
 
+/**
+ * Check if config has any unknown or deprecated keys
+ */
+function getInvalidKeys(config: Record<string, any>): string[] {
+    const invalidKeys: string[] = []
+    for (const key of Object.keys(config)) {
+        if (!VALID_CONFIG_KEYS.has(key)) {
+            invalidKeys.push(key)
+        }
+    }
+    return invalidKeys
+}
+
+/**
+ * Backs up existing config and creates fresh default config
+ * Returns the backup path if successful, null if failed
+ */
+function backupAndResetConfig(configPath: string, logger: Logger): string | null {
+    try {
+        const backupPath = configPath + '.bak'
+        
+        // Create backup
+        copyFileSync(configPath, backupPath)
+        logger.info('config', 'Created config backup', { backup: backupPath })
+        
+        // Write fresh default config
+        createDefaultConfig()
+        logger.info('config', 'Created fresh default config', { path: GLOBAL_CONFIG_PATH_JSONC })
+        
+        return backupPath
+    } catch (error: any) {
+        logger.error('config', 'Failed to backup/reset config', { error: error.message })
+        return null
+    }
+}
+
+/**
+ * Merge strategies config, handling partial overrides
+ */
+function mergeStrategies(
+    base: PluginConfig['strategies'],
+    override?: Partial<PluginConfig['strategies']>
+): PluginConfig['strategies'] {
+    if (!override) return base
+    return {
+        onIdle: override.onIdle ?? base.onIdle,
+        onTool: override.onTool ?? base.onTool
+    }
+}
+
 /**
  * Loads configuration with support for both global and project-level configs
  * 
@@ -147,30 +234,47 @@ function loadConfigFile(configPath: string): Partial<PluginConfig> | null {
  * 2. Merge with global config (~/.config/opencode/dcp.jsonc)
  * 3. Merge with project config (.opencode/dcp.jsonc) if found
  * 
+ * If config has invalid/deprecated keys, backs up and resets to defaults.
+ * 
  * Project config overrides global config, which overrides defaults.
  * 
  * @param ctx - Plugin input context (optional). If provided, will search for project-level config.
- * @returns Merged configuration
+ * @returns ConfigResult with merged configuration and any migration messages
  */
-export function getConfig(ctx?: PluginInput): PluginConfig {
-    let config = { ...defaultConfig }
+export function getConfig(ctx?: PluginInput): ConfigResult {
+    let config = { ...defaultConfig, protectedTools: [...defaultConfig.protectedTools] }
     const configPaths = getConfigPaths(ctx)
     const logger = new Logger(true) // Always log config loading
+    const migrations: string[] = []
 
     // 1. Load global config
     if (configPaths.global) {
         const globalConfig = loadConfigFile(configPaths.global)
         if (globalConfig) {
-            config = {
-                enabled: globalConfig.enabled ?? config.enabled,
-                debug: globalConfig.debug ?? config.debug,
-                protectedTools: globalConfig.protectedTools ?? config.protectedTools,
-                model: globalConfig.model ?? config.model,
-                showModelErrorToasts: globalConfig.showModelErrorToasts ?? config.showModelErrorToasts,
-                pruningMode: globalConfig.pruningMode ?? config.pruningMode,
-                pruning_summary: globalConfig.pruning_summary ?? config.pruning_summary
+            // Check for invalid keys
+            const invalidKeys = getInvalidKeys(globalConfig)
+            
+            if (invalidKeys.length > 0) {
+                // Config has deprecated/unknown keys - backup and reset
+                logger.info('config', 'Found invalid config keys', { keys: invalidKeys })
+                const backupPath = backupAndResetConfig(configPaths.global, logger)
+                if (backupPath) {
+                    migrations.push(`Old config backed up to ${backupPath}`)
+                }
+                // Config is now reset to defaults, no need to merge
+            } else {
+                // Valid config - merge with defaults
+                config = {
+                    enabled: globalConfig.enabled ?? config.enabled,
+                    debug: globalConfig.debug ?? config.debug,
+                    protectedTools: globalConfig.protectedTools ?? config.protectedTools,
+                    model: globalConfig.model ?? config.model,
+                    showModelErrorToasts: globalConfig.showModelErrorToasts ?? config.showModelErrorToasts,
+                    strategies: mergeStrategies(config.strategies, globalConfig.strategies as any),
+                    pruning_summary: globalConfig.pruning_summary ?? config.pruning_summary
+                }
+                logger.info('config', 'Loaded global config', { path: configPaths.global })
             }
-            logger.info('config', 'Loaded global config', { path: configPaths.global })
         }
     } else {
         // Create default global config if it doesn't exist
@@ -182,20 +286,32 @@ export function getConfig(ctx?: PluginInput): PluginConfig {
     if (configPaths.project) {
         const projectConfig = loadConfigFile(configPaths.project)
         if (projectConfig) {
-            config = {
-                enabled: projectConfig.enabled ?? config.enabled,
-                debug: projectConfig.debug ?? config.debug,
-                protectedTools: projectConfig.protectedTools ?? config.protectedTools,
-                model: projectConfig.model ?? config.model,
-                showModelErrorToasts: projectConfig.showModelErrorToasts ?? config.showModelErrorToasts,
-                pruningMode: projectConfig.pruningMode ?? config.pruningMode,
-                pruning_summary: projectConfig.pruning_summary ?? config.pruning_summary
+            // Check for invalid keys
+            const invalidKeys = getInvalidKeys(projectConfig)
+            
+            if (invalidKeys.length > 0) {
+                // Project config has deprecated/unknown keys - just warn, don't reset project configs
+                logger.warn('config', 'Project config has invalid keys (ignored)', { 
+                    path: configPaths.project,
+                    keys: invalidKeys 
+                })
+            } else {
+                // Valid config - merge with current config
+                config = {
+                    enabled: projectConfig.enabled ?? config.enabled,
+                    debug: projectConfig.debug ?? config.debug,
+                    protectedTools: projectConfig.protectedTools ?? config.protectedTools,
+                    model: projectConfig.model ?? config.model,
+                    showModelErrorToasts: projectConfig.showModelErrorToasts ?? config.showModelErrorToasts,
+                    strategies: mergeStrategies(config.strategies, projectConfig.strategies as any),
+                    pruning_summary: projectConfig.pruning_summary ?? config.pruning_summary
+                }
+                logger.info('config', 'Loaded project config (overrides global)', { path: configPaths.project })
             }
-            logger.info('config', 'Loaded project config (overrides global)', { path: configPaths.project })
         }
     } else if (ctx?.directory) {
         logger.debug('config', 'No project config found', { searchedFrom: ctx.directory })
     }
 
-    return config
+    return { config, migrations }
 }