diff --git a/README.md b/README.md index 9d15e73..7a1aa27 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,9 @@ DCP uses multiple strategies to reduce context size: **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. -**Prune Tool** — Exposes a `prune` tool that the AI can call to manually trigger pruning when it determines context cleanup is needed. +**Discard Tool** — Exposes a `discard` tool that the AI can call to remove completed or noisy tool outputs from context. Use this for task completion cleanup and removing irrelevant outputs. + +**Extract Tool** — Exposes an `extract` tool that the AI can call to distill valuable context into concise summaries before removing the raw outputs. Use this when you need to preserve key findings while reducing context size. **On Idle Analysis** — Uses a language model to semantically analyze conversation context during idle periods and identify tool outputs that are no longer relevant. @@ -72,8 +74,8 @@ DCP uses its own config file: "supersedeWrites": { "enabled": true }, - // Exposes a prune tool to your LLM to call when it determines pruning is necessary - "pruneTool": { + // Removes tool content from context without preservation (for completed tasks or noise) + "discardTool": { "enabled": true, // Additional tools to protect from pruning "protectedTools": [], @@ -82,12 +84,30 @@ DCP uses its own config file: "enabled": false, "turns": 4 }, - // Nudge the LLM to use the prune tool (every tool results) + // Nudge the LLM to use the discard tool (every tool results) "nudge": { "enabled": true, "frequency": 10 } }, + // Distills key findings into preserved knowledge before removing raw content + "extractTool": { + "enabled": true, + // Additional tools to protect from pruning + "protectedTools": [], + // Protect from pruning for message turns + "turnProtection": { + "enabled": false, + "turns": 4 + }, + // Nudge the LLM to use the extract tool (every tool results) + "nudge": { + "enabled": true, + "frequency": 10 + }, + // Show distillation content as an ignored message notification + "showDistillation": false + }, // (Legacy) Run an LLM to analyze what tool calls are no longer relevant on idle "onIdle": { "enabled": false, @@ -109,7 +129,7 @@ DCP uses its own config file: ### Protected Tools By default, these tools are always protected from pruning across all strategies: -`task`, `todowrite`, `todoread`, `prune`, `batch` +`task`, `todowrite`, `todoread`, `discard`, `extract`, `batch` The `protectedTools` arrays in each strategy add to this default list. diff --git a/index.ts b/index.ts index ac87705..770c5a6 100644 --- a/index.ts +++ b/index.ts @@ -3,7 +3,7 @@ import { getConfig } from "./lib/config" import { Logger } from "./lib/logger" import { loadPrompt } from "./lib/prompt" import { createSessionState } from "./lib/state" -import { createPruneTool } from "./lib/strategies" +import { createDiscardTool, createExtractTool } from "./lib/strategies" import { createChatMessageTransformHandler, createEventHandler } from "./lib/hooks" const plugin: Plugin = (async (ctx) => { @@ -18,18 +18,30 @@ const plugin: Plugin = (async (ctx) => { (globalThis as any).AI_SDK_LOG_WARNINGS = false } - // Initialize core components const logger = new Logger(config.debug) const state = createSessionState() - // Log initialization logger.info("DCP initialized", { strategies: config.strategies, }) return { "experimental.chat.system.transform": async (_input: unknown, output: { system: string[] }) => { - const syntheticPrompt = loadPrompt("prune-system-prompt") + const discardEnabled = config.strategies.discardTool.enabled + const extractEnabled = config.strategies.extractTool.enabled + + let promptName: string + if (discardEnabled && extractEnabled) { + promptName = "system/system-prompt-both" + } else if (discardEnabled) { + promptName = "system/system-prompt-discard" + } else if (extractEnabled) { + promptName = "system/system-prompt-extract" + } else { + return + } + + const syntheticPrompt = loadPrompt(promptName) output.system.push(syntheticPrompt) }, "experimental.chat.messages.transform": createChatMessageTransformHandler( @@ -38,25 +50,40 @@ const plugin: Plugin = (async (ctx) => { logger, config ), - tool: config.strategies.pruneTool.enabled ? { - prune: createPruneTool({ - client: ctx.client, - state, - logger, - config, - workingDirectory: ctx.directory + tool: { + ...(config.strategies.discardTool.enabled && { + discard: createDiscardTool({ + client: ctx.client, + state, + logger, + config, + workingDirectory: ctx.directory + }), }), - } : undefined, + ...(config.strategies.extractTool.enabled && { + extract: createExtractTool({ + client: ctx.client, + state, + logger, + config, + workingDirectory: ctx.directory + }), + }), + }, config: async (opencodeConfig) => { - // Add prune to primary_tools by mutating the opencode config + // Add enabled tools to primary_tools by mutating the opencode config // This works because config is cached and passed by reference - if (config.strategies.pruneTool.enabled) { + const toolsToAdd: string[] = [] + if (config.strategies.discardTool.enabled) toolsToAdd.push("discard") + if (config.strategies.extractTool.enabled) toolsToAdd.push("extract") + + if (toolsToAdd.length > 0) { const existingPrimaryTools = opencodeConfig.experimental?.primary_tools ?? [] opencodeConfig.experimental = { ...opencodeConfig.experimental, - primary_tools: [...existingPrimaryTools, "prune"], + primary_tools: [...existingPrimaryTools, ...toolsToAdd], } - logger.info("Added 'prune' to experimental.primary_tools via config mutation") + 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), diff --git a/lib/config.ts b/lib/config.ts index 9a670fe..1ae9ce3 100644 --- a/lib/config.ts +++ b/lib/config.ts @@ -34,6 +34,21 @@ export interface PruneTool { nudge: PruneToolNudge } +export interface DiscardTool { + enabled: boolean + protectedTools: string[] + turnProtection: PruneToolTurnProtection + nudge: PruneToolNudge +} + +export interface ExtractTool { + enabled: boolean + protectedTools: string[] + turnProtection: PruneToolTurnProtection + nudge: PruneToolNudge + showDistillation: boolean +} + export interface SupersedeWrites { enabled: boolean } @@ -45,12 +60,13 @@ export interface PluginConfig { strategies: { deduplication: Deduplication onIdle: OnIdle - pruneTool: PruneTool + discardTool: DiscardTool + extractTool: ExtractTool supersedeWrites: SupersedeWrites } } -const DEFAULT_PROTECTED_TOOLS = ['task', 'todowrite', 'todoread', 'prune', 'batch'] +const DEFAULT_PROTECTED_TOOLS = ['task', 'todowrite', 'todoread', 'discard', 'extract', 'batch'] // Valid config keys for validation against user config export const VALID_CONFIG_KEYS = new Set([ @@ -74,16 +90,27 @@ export const VALID_CONFIG_KEYS = new Set([ 'strategies.onIdle.showModelErrorToasts', 'strategies.onIdle.strictModelSelection', 'strategies.onIdle.protectedTools', - // strategies.pruneTool - 'strategies.pruneTool', - 'strategies.pruneTool.enabled', - 'strategies.pruneTool.protectedTools', - 'strategies.pruneTool.turnProtection', - 'strategies.pruneTool.turnProtection.enabled', - 'strategies.pruneTool.turnProtection.turns', - 'strategies.pruneTool.nudge', - 'strategies.pruneTool.nudge.enabled', - 'strategies.pruneTool.nudge.frequency' + // strategies.discardTool + 'strategies.discardTool', + 'strategies.discardTool.enabled', + 'strategies.discardTool.protectedTools', + 'strategies.discardTool.turnProtection', + 'strategies.discardTool.turnProtection.enabled', + 'strategies.discardTool.turnProtection.turns', + 'strategies.discardTool.nudge', + 'strategies.discardTool.nudge.enabled', + 'strategies.discardTool.nudge.frequency', + // strategies.extractTool + 'strategies.extractTool', + 'strategies.extractTool.enabled', + 'strategies.extractTool.protectedTools', + 'strategies.extractTool.turnProtection', + 'strategies.extractTool.turnProtection.enabled', + 'strategies.extractTool.turnProtection.turns', + 'strategies.extractTool.nudge', + 'strategies.extractTool.nudge.enabled', + 'strategies.extractTool.nudge.frequency', + 'strategies.extractTool.showDistillation' ]) // Extract all key paths from a config object for validation @@ -159,30 +186,59 @@ function validateConfigTypes(config: Record): ValidationError[] { } } - // pruneTool - if (strategies.pruneTool) { - if (strategies.pruneTool.enabled !== undefined && typeof strategies.pruneTool.enabled !== 'boolean') { - errors.push({ key: 'strategies.pruneTool.enabled', expected: 'boolean', actual: typeof strategies.pruneTool.enabled }) + // discardTool + if (strategies.discardTool) { + if (strategies.discardTool.enabled !== undefined && typeof strategies.discardTool.enabled !== 'boolean') { + errors.push({ key: 'strategies.discardTool.enabled', expected: 'boolean', actual: typeof strategies.discardTool.enabled }) + } + if (strategies.discardTool.protectedTools !== undefined && !Array.isArray(strategies.discardTool.protectedTools)) { + errors.push({ key: 'strategies.discardTool.protectedTools', expected: 'string[]', actual: typeof strategies.discardTool.protectedTools }) + } + if (strategies.discardTool.turnProtection) { + if (strategies.discardTool.turnProtection.enabled !== undefined && typeof strategies.discardTool.turnProtection.enabled !== 'boolean') { + errors.push({ key: 'strategies.discardTool.turnProtection.enabled', expected: 'boolean', actual: typeof strategies.discardTool.turnProtection.enabled }) + } + if (strategies.discardTool.turnProtection.turns !== undefined && typeof strategies.discardTool.turnProtection.turns !== 'number') { + errors.push({ key: 'strategies.discardTool.turnProtection.turns', expected: 'number', actual: typeof strategies.discardTool.turnProtection.turns }) + } + } + if (strategies.discardTool.nudge) { + if (strategies.discardTool.nudge.enabled !== undefined && typeof strategies.discardTool.nudge.enabled !== 'boolean') { + errors.push({ key: 'strategies.discardTool.nudge.enabled', expected: 'boolean', actual: typeof strategies.discardTool.nudge.enabled }) + } + if (strategies.discardTool.nudge.frequency !== undefined && typeof strategies.discardTool.nudge.frequency !== 'number') { + errors.push({ key: 'strategies.discardTool.nudge.frequency', expected: 'number', actual: typeof strategies.discardTool.nudge.frequency }) + } + } + } + + // extractTool + if (strategies.extractTool) { + if (strategies.extractTool.enabled !== undefined && typeof strategies.extractTool.enabled !== 'boolean') { + errors.push({ key: 'strategies.extractTool.enabled', expected: 'boolean', actual: typeof strategies.extractTool.enabled }) } - if (strategies.pruneTool.protectedTools !== undefined && !Array.isArray(strategies.pruneTool.protectedTools)) { - errors.push({ key: 'strategies.pruneTool.protectedTools', expected: 'string[]', actual: typeof strategies.pruneTool.protectedTools }) + if (strategies.extractTool.protectedTools !== undefined && !Array.isArray(strategies.extractTool.protectedTools)) { + errors.push({ key: 'strategies.extractTool.protectedTools', expected: 'string[]', actual: typeof strategies.extractTool.protectedTools }) } - if (strategies.pruneTool.turnProtection) { - if (strategies.pruneTool.turnProtection.enabled !== undefined && typeof strategies.pruneTool.turnProtection.enabled !== 'boolean') { - errors.push({ key: 'strategies.pruneTool.turnProtection.enabled', expected: 'boolean', actual: typeof strategies.pruneTool.turnProtection.enabled }) + if (strategies.extractTool.turnProtection) { + if (strategies.extractTool.turnProtection.enabled !== undefined && typeof strategies.extractTool.turnProtection.enabled !== 'boolean') { + errors.push({ key: 'strategies.extractTool.turnProtection.enabled', expected: 'boolean', actual: typeof strategies.extractTool.turnProtection.enabled }) } - if (strategies.pruneTool.turnProtection.turns !== undefined && typeof strategies.pruneTool.turnProtection.turns !== 'number') { - errors.push({ key: 'strategies.pruneTool.turnProtection.turns', expected: 'number', actual: typeof strategies.pruneTool.turnProtection.turns }) + if (strategies.extractTool.turnProtection.turns !== undefined && typeof strategies.extractTool.turnProtection.turns !== 'number') { + errors.push({ key: 'strategies.extractTool.turnProtection.turns', expected: 'number', actual: typeof strategies.extractTool.turnProtection.turns }) } } - if (strategies.pruneTool.nudge) { - if (strategies.pruneTool.nudge.enabled !== undefined && typeof strategies.pruneTool.nudge.enabled !== 'boolean') { - errors.push({ key: 'strategies.pruneTool.nudge.enabled', expected: 'boolean', actual: typeof strategies.pruneTool.nudge.enabled }) + if (strategies.extractTool.nudge) { + if (strategies.extractTool.nudge.enabled !== undefined && typeof strategies.extractTool.nudge.enabled !== 'boolean') { + errors.push({ key: 'strategies.extractTool.nudge.enabled', expected: 'boolean', actual: typeof strategies.extractTool.nudge.enabled }) } - if (strategies.pruneTool.nudge.frequency !== undefined && typeof strategies.pruneTool.nudge.frequency !== 'number') { - errors.push({ key: 'strategies.pruneTool.nudge.frequency', expected: 'number', actual: typeof strategies.pruneTool.nudge.frequency }) + if (strategies.extractTool.nudge.frequency !== undefined && typeof strategies.extractTool.nudge.frequency !== 'number') { + errors.push({ key: 'strategies.extractTool.nudge.frequency', expected: 'number', actual: typeof strategies.extractTool.nudge.frequency }) } } + if (strategies.extractTool.showDistillation !== undefined && typeof strategies.extractTool.showDistillation !== 'boolean') { + errors.push({ key: 'strategies.extractTool.showDistillation', expected: 'boolean', actual: typeof strategies.extractTool.showDistillation }) + } } // supersedeWrites @@ -254,7 +310,7 @@ const defaultConfig: PluginConfig = { supersedeWrites: { enabled: true }, - pruneTool: { + discardTool: { enabled: true, protectedTools: [...DEFAULT_PROTECTED_TOOLS], turnProtection: { @@ -266,6 +322,19 @@ const defaultConfig: PluginConfig = { frequency: 10 } }, + extractTool: { + enabled: true, + protectedTools: [...DEFAULT_PROTECTED_TOOLS], + turnProtection: { + enabled: false, + turns: 4 + }, + nudge: { + enabled: true, + frequency: 10 + }, + showDistillation: false + }, onIdle: { enabled: false, protectedTools: [...DEFAULT_PROTECTED_TOOLS], @@ -357,22 +426,40 @@ function createDefaultConfig(): void { "supersedeWrites": { "enabled": true }, - // Exposes a prune tool to your LLM to call when it determines pruning is necessary - \"pruneTool\": { - \"enabled\": true, + // Removes tool content from context without preservation (for completed tasks or noise) + "discardTool": { + "enabled": true, // Additional tools to protect from pruning - \"protectedTools\": [], + "protectedTools": [], // Protect from pruning for message turns - \"turnProtection\": { - \"enabled\": false, - \"turns\": 4 + "turnProtection": { + "enabled": false, + "turns": 4 }, - // Nudge the LLM to use the prune tool (every tool results) - \"nudge\": { + // Nudge the LLM to use the discard tool (every tool results) + "nudge": { "enabled": true, "frequency": 10 } }, + // Distills key findings into preserved knowledge before removing raw content + "extractTool": { + "enabled": true, + // Additional tools to protect from pruning + "protectedTools": [], + // Protect from pruning for message turns + "turnProtection": { + "enabled": false, + "turns": 4 + }, + // Nudge the LLM to use the extract tool (every tool results) + "nudge": { + "enabled": true, + "frequency": 10 + }, + // Show distillation content as an ignored message notification + "showDistillation": false + }, // (Legacy) Run an LLM to analyze what tool calls are no longer relevant on idle "onIdle": { "enabled": false, @@ -444,23 +531,41 @@ function mergeStrategies( ]) ] }, - pruneTool: { - enabled: override.pruneTool?.enabled ?? base.pruneTool.enabled, + discardTool: { + enabled: override.discardTool?.enabled ?? base.discardTool.enabled, protectedTools: [ ...new Set([ - ...base.pruneTool.protectedTools, - ...(override.pruneTool?.protectedTools ?? []) + ...base.discardTool.protectedTools, + ...(override.discardTool?.protectedTools ?? []) ]) ], turnProtection: { - enabled: override.pruneTool?.turnProtection?.enabled ?? base.pruneTool.turnProtection.enabled, - turns: override.pruneTool?.turnProtection?.turns ?? base.pruneTool.turnProtection.turns + enabled: override.discardTool?.turnProtection?.enabled ?? base.discardTool.turnProtection.enabled, + turns: override.discardTool?.turnProtection?.turns ?? base.discardTool.turnProtection.turns }, nudge: { - enabled: override.pruneTool?.nudge?.enabled ?? base.pruneTool.nudge.enabled, - frequency: override.pruneTool?.nudge?.frequency ?? base.pruneTool.nudge.frequency + enabled: override.discardTool?.nudge?.enabled ?? base.discardTool.nudge.enabled, + frequency: override.discardTool?.nudge?.frequency ?? base.discardTool.nudge.frequency } }, + extractTool: { + enabled: override.extractTool?.enabled ?? base.extractTool.enabled, + protectedTools: [ + ...new Set([ + ...base.extractTool.protectedTools, + ...(override.extractTool?.protectedTools ?? []) + ]) + ], + turnProtection: { + enabled: override.extractTool?.turnProtection?.enabled ?? base.extractTool.turnProtection.enabled, + turns: override.extractTool?.turnProtection?.turns ?? base.extractTool.turnProtection.turns + }, + nudge: { + enabled: override.extractTool?.nudge?.enabled ?? base.extractTool.nudge.enabled, + frequency: override.extractTool?.nudge?.frequency ?? base.extractTool.nudge.frequency + }, + showDistillation: override.extractTool?.showDistillation ?? base.extractTool.showDistillation + }, supersedeWrites: { enabled: override.supersedeWrites?.enabled ?? base.supersedeWrites.enabled } @@ -479,11 +584,18 @@ function deepCloneConfig(config: PluginConfig): PluginConfig { ...config.strategies.onIdle, protectedTools: [...config.strategies.onIdle.protectedTools] }, - pruneTool: { - ...config.strategies.pruneTool, - protectedTools: [...config.strategies.pruneTool.protectedTools], - turnProtection: { ...config.strategies.pruneTool.turnProtection }, - nudge: { ...config.strategies.pruneTool.nudge } + discardTool: { + ...config.strategies.discardTool, + protectedTools: [...config.strategies.discardTool.protectedTools], + turnProtection: { ...config.strategies.discardTool.turnProtection }, + nudge: { ...config.strategies.discardTool.nudge } + }, + extractTool: { + ...config.strategies.extractTool, + protectedTools: [...config.strategies.extractTool.protectedTools], + turnProtection: { ...config.strategies.extractTool.turnProtection }, + nudge: { ...config.strategies.extractTool.nudge }, + showDistillation: config.strategies.extractTool.showDistillation }, supersedeWrites: { ...config.strategies.supersedeWrites diff --git a/lib/messages/prune.ts b/lib/messages/prune.ts index f9348bf..0257afc 100644 --- a/lib/messages/prune.ts +++ b/lib/messages/prune.ts @@ -8,15 +8,42 @@ import { UserMessage } from "@opencode-ai/sdk" const PRUNED_TOOL_INPUT_REPLACEMENT = '[Input removed to save context]' const PRUNED_TOOL_OUTPUT_REPLACEMENT = '[Output removed to save context - information superseded or no longer needed]' -const NUDGE_STRING = loadPrompt("prune-nudge") +const getNudgeString = (config: PluginConfig): string => { + const discardEnabled = config.strategies.discardTool.enabled + const extractEnabled = config.strategies.extractTool.enabled + + if (discardEnabled && extractEnabled) { + return loadPrompt("nudge/nudge-both") + } else if (discardEnabled) { + return loadPrompt("nudge/nudge-discard") + } else if (extractEnabled) { + return loadPrompt("nudge/nudge-extract") + } + return "" +} const wrapPrunableTools = (content: string): string => ` The following tools have been invoked and are available for pruning. This list does not mandate immediate action. Consider your current goals and the resources you need before discarding valuable tool inputs or outputs. Consolidate your prunes for efficiency; it is rarely worth pruning a single tiny tool output. Keep the context free of noise. ${content} ` -const PRUNABLE_TOOLS_COOLDOWN = ` -Pruning was just performed. Do not use the prune tool again. A fresh list will be available after your next tool use. + +const getCooldownMessage = (config: PluginConfig): string => { + const discardEnabled = config.strategies.discardTool.enabled + const extractEnabled = config.strategies.extractTool.enabled + + let toolName: string + if (discardEnabled && extractEnabled) { + toolName = "discard or extract tools" + } else if (discardEnabled) { + toolName = "discard tool" + } else { + toolName = "extract tool" + } + + return ` +Context management was just performed. Do not use the ${toolName} again. A fresh list will be available after your next tool use. ` +} const SYNTHETIC_MESSAGE_ID = "msg_01234567890123456789012345" const SYNTHETIC_PART_ID = "prt_01234567890123456789012345" @@ -34,7 +61,11 @@ const buildPrunableToolsList = ( if (state.prune.toolIds.includes(toolCallId)) { return } - if (config.strategies.pruneTool.protectedTools.includes(toolParameterEntry.tool)) { + const allProtectedTools = [ + ...config.strategies.discardTool.protectedTools, + ...config.strategies.extractTool.protectedTools + ] + if (allProtectedTools.includes(toolParameterEntry.tool)) { return } const numericId = toolIdList.indexOf(toolCallId) @@ -61,7 +92,7 @@ export const insertPruneToolContext = ( logger: Logger, messages: WithParts[] ): void => { - if (!config.strategies.pruneTool.enabled) { + if (!config.strategies.discardTool.enabled && !config.strategies.extractTool.enabled) { return } @@ -74,7 +105,7 @@ export const insertPruneToolContext = ( if (state.lastToolPrune) { logger.debug("Last tool was prune - injecting cooldown message") - prunableToolsContent = PRUNABLE_TOOLS_COOLDOWN + prunableToolsContent = getCooldownMessage(config) } else { const prunableToolsList = buildPrunableToolsList(state, config, logger, messages) if (!prunableToolsList) { @@ -84,9 +115,15 @@ export const insertPruneToolContext = ( logger.debug("prunable-tools: \n" + prunableToolsList) let nudgeString = "" - if (state.nudgeCounter >= config.strategies.pruneTool.nudge.frequency) { + // TODO: Using Math.min() means the lower frequency dominates when both tools are enabled. + // Consider using separate counters for each tool's nudge, or documenting this behavior. + const nudgeFrequency = Math.min( + config.strategies.discardTool.nudge.frequency, + config.strategies.extractTool.nudge.frequency + ) + if (state.nudgeCounter >= nudgeFrequency) { logger.info("Inserting prune nudge message") - nudgeString = "\n" + NUDGE_STRING + nudgeString = "\n" + getNudgeString(config) } prunableToolsContent = prunableToolsList + nudgeString diff --git a/lib/prompts/discard-tool-spec.txt b/lib/prompts/discard-tool-spec.txt new file mode 100644 index 0000000..4cbf50a --- /dev/null +++ b/lib/prompts/discard-tool-spec.txt @@ -0,0 +1,56 @@ +Discards tool outputs from context to manage conversation size and reduce noise. + +## IMPORTANT: The Prunable List +A `` list is injected into user messages showing available tool outputs you can discard when there are tools available for pruning. Each line has the format `ID: tool, parameter` (e.g., `20: read, /path/to/file.ts`). You MUST only use numeric IDs that appear in this list to select which tools to discard. + +**Note:** For `write` and `edit` tools, discarding removes the input content (the code being written/edited) while preserving the output confirmation. This is useful after completing a file modification when you no longer need the raw content in context. + +## When to Use This Tool + +Use `discard` for removing tool outputs that are no longer needed **without preserving their content**: + +### 1. Task Completion (Clean Up) +**When:** You have successfully completed a specific unit of work (e.g., fixed a bug, wrote a file, answered a question). +**Action:** Discard the tools used for that task with reason `completion`. + +### 2. Removing Noise (Garbage Collection) +**When:** You have read files or run commands that turned out to be irrelevant, unhelpful, or outdated (meaning later tools have provided fresher, more valid information). +**Action:** Discard these specific tool outputs immediately with reason `noise`. + +## When NOT to Use This Tool + +- **If you need to preserve information:** Keep the raw output in context rather than discarding it. +- **If you'll need the output later:** Don't discard files you plan to edit, or context you'll need for implementation. + +## Best Practices +- **Strategic Batching:** Don't discard single small tool outputs (like short bash commands) unless they are pure noise. Wait until you have several items to perform high-impact discards. +- **Think ahead:** Before discarding, ask: "Will I need this output for an upcoming task?" If yes, keep it. + +## Format +The `ids` parameter is an array where the first element is the reason, followed by numeric IDs: +`ids: ["reason", "id1", "id2", ...]` + +## Examples + + +Assistant: [Reads 'wrong_file.ts'] +This file isn't relevant to the auth system. I'll remove it to clear the context. +[Uses discard with ids: ["noise", "5"]] + + + +Assistant: [Runs tests, they pass] +The tests passed. I'll clean up now. +[Uses discard with ids: ["completion", "20", "21"]] + + + +Assistant: [Reads 'auth.ts' to understand the login flow] +I've understood the auth flow. I'll need to modify this file to add the new validation, so I'm keeping this read in context rather than discarding. + + + +Assistant: [Edits 'auth.ts' to add validation] +The edit was successful. I no longer need the raw edit content in context. +[Uses discard with ids: ["completion", "15"]] + diff --git a/lib/prompts/extract-tool-spec.txt b/lib/prompts/extract-tool-spec.txt new file mode 100644 index 0000000..9af5b66 --- /dev/null +++ b/lib/prompts/extract-tool-spec.txt @@ -0,0 +1,79 @@ +Extracts key findings from tool outputs into distilled knowledge, then removes the raw outputs from context. + +## IMPORTANT: The Prunable List +A `` list is injected into user messages showing available tool outputs you can extract from when there are tools available for pruning. Each line has the format `ID: tool, parameter` (e.g., `20: read, /path/to/file.ts`). You MUST only use numeric IDs that appear in this list to select which tools to extract. + +## When to Use This Tool + +Use `extract` when you have gathered useful information that you want to **preserve in distilled form** before removing the raw outputs: + +### 1. Task Completion +**When:** You have completed a unit of work and want to preserve key findings. +**Action:** Extract with distillation scaled to the value of the content. High-value insights require comprehensive capture; routine completions can use lighter distillation. + +### 2. Knowledge Preservation +**When:** You have read files, run commands, or gathered context that contains valuable information you'll need to reference later, but the full raw output is too large to keep. +**Action:** Convert raw data into distilled knowledge. This allows you to remove large outputs (like full file reads) while keeping only the specific parts you need (like a single function signature or constant). + +## CRITICAL: Distillation Requirements + +You MUST provide distilled findings in the `distillation` parameter. This is not optional. + +- **Comprehensive Capture:** Distillation is not just a summary. It must be a high-fidelity representation of the technical details. If you read a file, the distillation should include function signatures, specific logic flows, constant values, and any constraints or edge cases discovered. +- **Task-Relevant Verbosity:** Be as verbose as necessary to ensure that the "distilled" version is a complete substitute for the raw output for the task at hand. If you will need to reference a specific algorithm or interface later, include it in its entirety within the distillation. +- **Extract Per-ID:** When extracting from multiple tools, your `distillation` object MUST contain a corresponding entry for EVERY ID being extracted. You must capture high-fidelity findings for each tool individually to ensure no signal is lost. +- **Structure:** Map EVERY `ID` from the `ids` array to its specific distilled findings. + Example: `{ "20": { ... }, "21": { ... } }` +- Capture all relevant details (function names, logic, constraints) to ensure no signal is lost. +- Prioritize information that is essential for the immediate next steps of your plan. + +## When NOT to Use This Tool + +- **If you need precise syntax:** If you'll need to edit a file, grep for exact strings, or reference precise syntax, keep the raw output. Distillation works for understanding; implementation often requires the original. +- **If uncertain:** Prefer keeping over re-fetching. The cost of retaining context is lower than the cost of redundant tool calls. + +## Best Practices +- **Technical Fidelity:** Ensure that types, parameters, and return values are preserved if they are relevant to upcoming implementation steps. +- **Strategic Batching:** Wait until you have several items or a few large outputs to extract, rather than doing tiny, frequent extractions. Aim for high-impact extractions that significantly reduce context size. +- **Think ahead:** Before extracting, ask: "Will I need the raw output for an upcoming task?" If you researched a file you'll later edit, do NOT extract it. + +## Format +The `ids` parameter is an array of numeric IDs as strings: +`ids: ["id1", "id2", ...]` + +The `distillation` parameter is an object mapping each ID to its distilled findings: +`distillation: { "id1": { ...findings... }, "id2": { ...findings... } }` + +## Example + + +Assistant: [Reads service implementation, types, and config] +I'll preserve the full technical specification and implementation logic before extracting. +[Uses extract with ids: ["10", "11", "12"], distillation: { + "10": { + "file": "src/services/auth.ts", + "signatures": [ + "async function validateToken(token: string): Promise", + "function hashPassword(password: string): string" + ], + "logic": "The validateToken function first checks the local cache before calling the external OIDC provider. It uses a 5-minute TTL for cached tokens.", + "dependencies": ["import { cache } from '../utils/cache'", "import { oidc } from '../config'"], + "constraints": "Tokens must be at least 128 chars long. hashPassword uses bcrypt with 12 rounds." + }, + "11": { + "file": "src/types/user.ts", + "interface": "interface User { id: string; email: string; permissions: ('read' | 'write' | 'admin')[]; status: 'active' | 'suspended'; }", + "context": "The permissions array is strictly typed and used by the RBAC middleware." + }, + "12": { + "file": "config/default.json", + "values": { "PORT": 3000, "RETRY_STRATEGY": "exponential", "MAX_ATTEMPTS": 5 }, + "impact": "The retry strategy affects all outgoing HTTP clients in the core module." + } +}] + + + +Assistant: [Reads 'auth.ts' to understand the login flow] +I've understood the auth flow. I'll need to modify this file to add the new validation, so I'm keeping this read in context rather than extracting. + diff --git a/lib/prompts/nudge/nudge-both.txt b/lib/prompts/nudge/nudge-both.txt new file mode 100644 index 0000000..f9fa492 --- /dev/null +++ b/lib/prompts/nudge/nudge-both.txt @@ -0,0 +1,10 @@ + +**CRITICAL CONTEXT WARNING:** Your context window is filling with tool outputs. Strict adherence to context hygiene is required. + +**Immediate Actions Required:** +1. **Task Completion:** If a sub-task is complete, decide: use `discard` if no valuable context to preserve (default), or use `extract` if insights are worth keeping. +2. **Noise Removal:** If you read files or ran commands that yielded no value, use `discard` to remove them. +3. **Knowledge Preservation:** If you are holding valuable raw data you'll need to reference later, use `extract` to distill the insights and remove the raw entry. + +**Protocol:** You should prioritize this cleanup, but do not interrupt a critical atomic operation if one is in progress. Once the immediate step is done, you must perform context management. + diff --git a/lib/prompts/prune-nudge.txt b/lib/prompts/nudge/nudge-discard.txt similarity index 56% rename from lib/prompts/prune-nudge.txt rename to lib/prompts/nudge/nudge-discard.txt index ef84d35..1ccecf9 100644 --- a/lib/prompts/prune-nudge.txt +++ b/lib/prompts/nudge/nudge-discard.txt @@ -2,9 +2,8 @@ **CRITICAL CONTEXT WARNING:** Your context window is filling with tool outputs. Strict adherence to context hygiene is required. **Immediate Actions Required:** -1. **Task Completion:** If a sub-task is complete, prune the tools used. No distillation. -2. **Noise Removal:** If you read files or ran commands that yielded no value, prune them NOW. No distillation. -3. **Consolidation:** If you are holding valuable raw data, you *must* distill the insights into `metadata.distillation` and prune the raw entry. +1. **Task Completion:** If a sub-task is complete, use the `discard` tool to remove the tools used. +2. **Noise Removal:** If you read files or ran commands that yielded no value, use the `discard` tool to remove them. -**Protocol:** You should prioritize this cleanup, but do not interrupt a critical atomic operation if one is in progress. Once the immediate step is done, you must prune. +**Protocol:** You should prioritize this cleanup, but do not interrupt a critical atomic operation if one is in progress. Once the immediate step is done, you must discard unneeded tool outputs. diff --git a/lib/prompts/nudge/nudge-extract.txt b/lib/prompts/nudge/nudge-extract.txt new file mode 100644 index 0000000..5bdb370 --- /dev/null +++ b/lib/prompts/nudge/nudge-extract.txt @@ -0,0 +1,9 @@ + +**CRITICAL CONTEXT WARNING:** Your context window is filling with tool outputs. Strict adherence to context hygiene is required. + +**Immediate Actions Required:** +1. **Task Completion:** If you have completed work, extract key findings from the tools used. Scale distillation depth to the value of the content. +2. **Knowledge Preservation:** If you are holding valuable raw data you'll need to reference later, use the `extract` tool with high-fidelity distillation to preserve the insights and remove the raw entry. + +**Protocol:** You should prioritize this cleanup, but do not interrupt a critical atomic operation if one is in progress. Once the immediate step is done, you must extract valuable findings from tool outputs. + diff --git a/lib/prompts/prune-tool-spec.txt b/lib/prompts/prune-tool-spec.txt deleted file mode 100644 index 6d59aa3..0000000 --- a/lib/prompts/prune-tool-spec.txt +++ /dev/null @@ -1,95 +0,0 @@ -Prunes tool outputs from context to manage conversation size and reduce noise. - -## IMPORTANT: The Prunable List -A `` list is injected into user messages showing available tool outputs you can prune when there are tools available for pruning. Each line has the format `ID: tool, parameter` (e.g., `20: read, /path/to/file.ts`). You MUST only use numeric IDs that appear in this list to select which tools to prune. - -**Note:** For `write` and `edit` tools, pruning removes the input content (the code being written/edited) while preserving the output confirmation. This is useful after completing a file modification when you no longer need the raw content in context. - -## CRITICAL: When and How to Prune - -You must use this tool in three specific scenarios. The rules for distillation (summarizing findings) differ for each. **You must provide a `metadata` object with a `reason` and optional `distillation`** to indicate which scenario applies. - -### 1. Task Completion (Clean Up) — reason: `completion` -**When:** You have successfully completed a specific unit of work (e.g., fixed a bug, wrote a file, answered a question). -**Action:** Prune the tools used for that task. -**Distillation:** FORBIDDEN. Do not summarize completed work. - -### 2. Removing Noise (Garbage Collection) — reason: `noise` -**When:** You have read files or run commands that turned out to be irrelevant, unhelpful, or outdated (meaning later tools have provided fresher, more valid information). -**Action:** Prune these specific tool outputs immediately. -**Distillation:** FORBIDDEN. Do not summarize noise. - -### 3. Context Conservation (Research & Consolidation) — reason: `consolidation` -**When:** You have gathered useful information. Wait until you have several items or a few large outputs to prune, rather than doing tiny, frequent prunes. Aim for high-impact prunes that significantly reduce context size. -**Action:** Convert raw data into distilled knowledge. This allows you to discard large outputs (like full file reads) while keeping only the specific parts you need (like a single function signature or constant). -**Distillation:** MANDATORY. You MUST provide the distilled findings in the `metadata.distillation` parameter of the `prune` tool (as an object). - - **Comprehensive Capture:** Distillation is not just a summary. It must be a high-fidelity representation of the technical details. If you read a file, the distillation should include function signatures, specific logic flows, constant values, and any constraints or edge cases discovered. - - **Task-Relevant Verbosity:** Be as verbose as necessary to ensure that the "distilled" version is a complete substitute for the raw output for the task at hand. If you will need to reference a specific algorithm or interface later, include it in its entirety within the distillation. - - **Consolidate:** When pruning multiple tools, your `distillation` object MUST contain a corresponding entry for EVERY ID being pruned. You must capture high-fidelity findings for each tool individually to ensure no signal is lost. - - Structure: Map EVERY `ID` from the `ids` array to its specific distilled findings. - Example: `{ "20": { ... }, "21": { ... } }` - - Capture all relevant details (function names, logic, constraints) to ensure no signal is lost. - - Prioritize information that is essential for the immediate next steps of your plan. - - Once distilled into the `metadata` object, the raw tool output can be safely pruned. - - **Know when distillation isn't enough:** If you'll need to edit a file, grep for exact strings, or reference precise syntax, keep the raw output. Distillation works for understanding; implementation often requires the original. - - **Prefer keeping over re-fetching:** If uncertain whether you'll need the output again, keep it. The cost of retaining context is lower than the cost of redundant tool calls. - -## Best Practices -- **Technical Fidelity:** Ensure that types, parameters, and return values are preserved if they are relevant to upcoming implementation steps. -- **Strategic Consolidation:** Don't prune single small tool outputs (like short bash commands) unless they are pure noise. Instead, wait until you have several items or large outputs to perform high-impact prunes. This balances the need for an agile context with the efficiency of larger batches. -- **Think ahead:** Before pruning, ask: "Will I need this output for an upcoming task?" If you researched a file you'll later edit, or gathered context for implementation, do NOT prune it. - -## Examples - - -Assistant: [Reads 'wrong_file.ts'] -This file isn't relevant to the auth system. I'll remove it to clear the context. -[Uses prune with ids: ["5"], metadata: { "reason": "noise" }] - - - -Assistant: [Reads service implementation, types, and config] -I'll preserve the full technical specification and implementation logic before pruning. -[Uses prune with ids: ["10", "11", "12"], metadata: { - "reason": "consolidation", - "distillation": { - "10": { - "file": "src/services/auth.ts", - "signatures": [ - "async function validateToken(token: string): Promise", - "function hashPassword(password: string): string" - ], - "logic": "The validateToken function first checks the local cache before calling the external OIDC provider. It uses a 5-minute TTL for cached tokens.", - "dependencies": ["import { cache } from '../utils/cache'", "import { oidc } from '../config'"], - "constraints": "Tokens must be at least 128 chars long. hashPassword uses bcrypt with 12 rounds." - }, - "11": { - "file": "src/types/user.ts", - "interface": "interface User { id: string; email: string; permissions: ('read' | 'write' | 'admin')[]; status: 'active' | 'suspended'; }", - "context": "The permissions array is strictly typed and used by the RBAC middleware." - }, - "12": { - "file": "config/default.json", - "values": { "PORT": 3000, "RETRY_STRATEGY": "exponential", "MAX_ATTEMPTS": 5 }, - "impact": "The retry strategy affects all outgoing HTTP clients in the core module." - } - } -}] - - - -Assistant: [Runs tests, they pass] -The tests passed. I'll clean up now. -[Uses prune with ids: ["20", "21"], metadata: { "reason": "completion" }] - - - -Assistant: [Reads 'auth.ts' to understand the login flow] -I've understood the auth flow. I'll need to modify this file to add the new validation, so I'm keeping this read in context rather than distilling and pruning. - - - -Assistant: [Edits 'auth.ts' to add validation] -The edit was successful. I no longer need the raw edit content in context. -[Uses prune with ids: ["15"], metadata: { "reason": "completion" }] - diff --git a/lib/prompts/prune-system-prompt.txt b/lib/prompts/system/system-prompt-both.txt similarity index 53% rename from lib/prompts/prune-system-prompt.txt rename to lib/prompts/system/system-prompt-both.txt index 88ba307..f1e88aa 100644 --- a/lib/prompts/prune-system-prompt.txt +++ b/lib/prompts/system/system-prompt-both.txt @@ -2,21 +2,30 @@ ENVIRONMENT -You are operating in a context-constrained environment and thus must proactively manage your context window using the `prune` tool. A list is injected by the environment as a user message, and always contains up to date information. Use this information when deciding what to prune. +You are operating in a context-constrained environment and thus must proactively manage your context window using the `discard` and `extract` tools. A list is injected by the environment as a user message, and always contains up to date information. Use this information when deciding what to prune. -PRUNE METHODICALLY - CONSOLIDATE YOUR ACTIONS -Every tool call adds to your context debt. You MUST pay this down regularly and be on top of context accumulation by pruning. Consolidate your prunes for efficiency; it is rarely worth pruning a single tiny tool output unless it is pure noise. Evaluate what SHOULD be pruned before jumping the gun. +TWO TOOLS FOR CONTEXT MANAGEMENT +- `discard`: Remove tool outputs that are no longer needed (completed tasks, noise, outdated info). No preservation of content. +- `extract`: Extract key findings into distilled knowledge before removing raw outputs. Use when you need to preserve information. -WHEN TO PRUNE? THE THREE SCENARIOS TO CONSIDER -1. TASK COMPLETION: When work is done, quietly prune the tools that aren't needed anymore. No distillation. -2. NOISE REMOVAL: If outputs are irrelevant, unhelpful, or superseded by newer info, prune. No distillation. -3. CONTEXT CONSOLIDATION: When pruning valuable context to the task at hand, you MUST ALWAYS provide the key findings in the `metadata.distillation` parameter of the `prune` tool (as an object). Your distillation must be high-fidelity and comprehensive, capturing technical details (signatures, logic, constraints) such that the raw output is no longer needed. THINK: high signal, complete technical substitute. +CHOOSING THE RIGHT TOOL +Ask: "Do I need to preserve any information from this output?" +- **No** → `discard` (default for cleanup) +- **Yes** → `extract` (preserves distilled knowledge) +- **Uncertain** → `extract` (safer, preserves signal) -You WILL use the `prune` tool when ANY of these are true: +Common scenarios: +- Task complete, no valuable context → `discard` +- Task complete, insights worth remembering → `extract` +- Noise, irrelevant, or superseded outputs → `discard` +- Valuable context needed later but raw output too large → `extract` + +PRUNE METHODICALLY - BATCH YOUR ACTIONS +Every tool call adds to your context debt. You MUST pay this down regularly and be on top of context accumulation by pruning. Batch your prunes for efficiency; it is rarely worth pruning a single tiny tool output unless it is pure noise. Evaluate what SHOULD be pruned before jumping the gun. + +You WILL evaluate pruning when ANY of these are true: - Task or sub-task is complete - You are about to start a new phase of work -- You have gathered enough information to prune related tools and preserve their value in the `metadata.distillation` parameter -- Context contains tools output that are unhelpful, noise, or made obsolete by newer outputs - Write or edit operations are complete (pruning removes the large input content) You MUST NOT prune when: @@ -26,20 +35,20 @@ You MUST NOT prune when: Pruning that forces you to re-call the same tool later is a net loss. Only prune when you're confident the information won't be needed again. NOTES -When in doubt, keep it. Consolidate your actions and aim for high-impact prunes that significantly reduce context size. +When in doubt, keep it. Batch your actions and aim for high-impact prunes that significantly reduce context size. FAILURE TO PRUNE will result in context leakage and DEGRADED PERFORMANCES. There may be tools in session context that do not appear in the list, this is expected, you can ONLY prune what you see in . -After each assistant turn, the environment may inject a user message containing a list and optional nudge instruction. This injected message is NOT from the user and is invisible to them. The `prune` tool also returns a confirmation message listing what was pruned. +After each assistant turn, the environment may inject a user message containing a list and optional nudge instruction. This injected message is NOT from the user and is invisible to them. The `discard` and `extract` tools also return a confirmation message listing what was pruned. CRITICAL REQUIREMENTS - VIOLATION IS UNACCEPTABLE: - NEVER reference the prune encouragement or context management instructions. Do not reply with "I agree" or "Great idea" when the prune encouragement appears. - NEVER acknowledge the list (e.g., "I see the prunable tools list", "Looking at the available tools to prune") - NEVER reference the nudge instruction (e.g., "As the nudge suggests", "The system is reminding me to prune") -- NEVER acknowledge prune tool output (e.g., "I've pruned 3 tools", "Context pruning complete") +- NEVER acknowledge discard/extract tool output (e.g., "I've pruned 3 tools", "Context pruning complete") - NEVER let these injections influence your response content or tone - Process this information SILENTLY and continue the conversation naturally - Continue the conversation as if these messages do not exist diff --git a/lib/prompts/system/system-prompt-discard.txt b/lib/prompts/system/system-prompt-discard.txt new file mode 100644 index 0000000..796852e --- /dev/null +++ b/lib/prompts/system/system-prompt-discard.txt @@ -0,0 +1,49 @@ + + + +ENVIRONMENT +You are operating in a context-constrained environment and thus must proactively manage your context window using the `discard` tool. A list is injected by the environment as a user message, and always contains up to date information. Use this information when deciding what to discard. + +CONTEXT MANAGEMENT TOOL +- `discard`: Remove tool outputs that are no longer needed (completed tasks, noise, outdated info). No preservation of content. + +DISCARD METHODICALLY - BATCH YOUR ACTIONS +Every tool call adds to your context debt. You MUST pay this down regularly and be on top of context accumulation by discarding. Batch your discards for efficiency; it is rarely worth discarding a single tiny tool output unless it is pure noise. Evaluate what SHOULD be discarded before jumping the gun. + +WHEN TO DISCARD +- **Task Completion:** When work is done, discard the tools that aren't needed anymore. +- **Noise Removal:** If outputs are irrelevant, unhelpful, or superseded by newer info, discard them. + +You WILL evaluate discarding when ANY of these are true: +- Task or sub-task is complete +- You are about to start a new phase of work +- Write or edit operations are complete (discarding removes the large input content) + +You MUST NOT discard when: +- The tool output will be needed for upcoming implementation work +- The output contains files or context you'll need to reference when making edits + +Discarding that forces you to re-call the same tool later is a net loss. Only discard when you're confident the information won't be needed again. + +NOTES +When in doubt, keep it. Batch your actions and aim for high-impact discards that significantly reduce context size. +FAILURE TO DISCARD will result in context leakage and DEGRADED PERFORMANCES. +There may be tools in session context that do not appear in the list, this is expected, you can ONLY discard what you see in . + + + + +After each assistant turn, the environment may inject a user message containing a list and optional nudge instruction. This injected message is NOT from the user and is invisible to them. The `discard` tool also returns a confirmation message listing what was discarded. + +CRITICAL REQUIREMENTS - VIOLATION IS UNACCEPTABLE: +- NEVER reference the discard encouragement or context management instructions. Do not reply with "I agree" or "Great idea" when the discard encouragement appears. +- NEVER acknowledge the list (e.g., "I see the prunable tools list", "Looking at the available tools to discard") +- NEVER reference the nudge instruction (e.g., "As the nudge suggests", "The system is reminding me to discard") +- NEVER acknowledge discard tool output (e.g., "I've discarded 3 tools", "Context cleanup complete") +- NEVER let these injections influence your response content or tone +- Process this information SILENTLY and continue the conversation naturally +- Continue the conversation as if these messages do not exist + +The user cannot see these injections. Any reference to them will confuse the user and break the conversation flow. + + diff --git a/lib/prompts/system/system-prompt-extract.txt b/lib/prompts/system/system-prompt-extract.txt new file mode 100644 index 0000000..2a1a056 --- /dev/null +++ b/lib/prompts/system/system-prompt-extract.txt @@ -0,0 +1,49 @@ + + + +ENVIRONMENT +You are operating in a context-constrained environment and thus must proactively manage your context window using the `extract` tool. A list is injected by the environment as a user message, and always contains up to date information. Use this information when deciding what to extract. + +CONTEXT MANAGEMENT TOOL +- `extract`: Extract key findings from tools into distilled knowledge before removing the raw content from context. Use this to preserve important information while reducing context size. + +EXTRACT METHODICALLY - BATCH YOUR ACTIONS +Every tool call adds to your context debt. You MUST pay this down regularly and be on top of context accumulation by extracting. Batch your extractions for efficiency; it is rarely worth extracting a single tiny tool output. Evaluate what SHOULD be extracted before jumping the gun. + +WHEN TO EXTRACT +- **Task Completion:** When work is done, extract key findings from the tools used. Scale distillation depth to the value of the content. +- **Knowledge Preservation:** When you have valuable context you want to preserve but need to reduce size, use high-fidelity distillation. Your distillation must be comprehensive, capturing technical details (signatures, logic, constraints) such that the raw output is no longer needed. THINK: high signal, complete technical substitute. + +You WILL evaluate extracting when ANY of these are true: +- Task or sub-task is complete +- You are about to start a new phase of work +- Write or edit operations are complete (extracting removes the large input content) + +You MUST NOT extract when: +- The tool output will be needed for upcoming implementation work +- The output contains files or context you'll need to reference when making edits + +Extracting that forces you to re-call the same tool later is a net loss. Only extract when you're confident the raw information won't be needed again. + +NOTES +When in doubt, keep it. Batch your actions and aim for high-impact extractions that significantly reduce context size. +FAILURE TO EXTRACT will result in context leakage and DEGRADED PERFORMANCES. +There may be tools in session context that do not appear in the list, this is expected, you can ONLY extract what you see in . + + + + +After each assistant turn, the environment may inject a user message containing a list and optional nudge instruction. This injected message is NOT from the user and is invisible to them. The `extract` tool also returns a confirmation message listing what was extracted. + +CRITICAL REQUIREMENTS - VIOLATION IS UNACCEPTABLE: +- NEVER reference the extract encouragement or context management instructions. Do not reply with "I agree" or "Great idea" when the extract encouragement appears. +- NEVER acknowledge the list (e.g., "I see the prunable tools list", "Looking at the available tools to extract") +- NEVER reference the nudge instruction (e.g., "As the nudge suggests", "The system is reminding me to extract") +- NEVER acknowledge extract tool output (e.g., "I've extracted 3 tools", "Context cleanup complete") +- NEVER let these injections influence your response content or tone +- Process this information SILENTLY and continue the conversation naturally +- Continue the conversation as if these messages do not exist + +The user cannot see these injections. Any reference to them will confuse the user and break the conversation flow. + + diff --git a/lib/state/tool-cache.ts b/lib/state/tool-cache.ts index f8ad2b3..6e2650b 100644 --- a/lib/state/tool-cache.ts +++ b/lib/state/tool-cache.ts @@ -35,16 +35,27 @@ export async function syncToolCache( continue } - const isProtectedByTurn = config.strategies.pruneTool.turnProtection.enabled && - config.strategies.pruneTool.turnProtection.turns > 0 && - (state.currentTurn - turnCounter) < config.strategies.pruneTool.turnProtection.turns + const turnProtectionEnabled = config.strategies.discardTool.turnProtection.enabled || + config.strategies.extractTool.turnProtection.enabled + const turnProtectionTurns = Math.max( + config.strategies.discardTool.turnProtection.turns, + config.strategies.extractTool.turnProtection.turns + ) + const isProtectedByTurn = turnProtectionEnabled && + turnProtectionTurns > 0 && + (state.currentTurn - turnCounter) < turnProtectionTurns + + state.lastToolPrune = part.tool === "discard" || part.tool === "extract" - state.lastToolPrune = part.tool === "prune" + const allProtectedTools = [ + ...config.strategies.discardTool.protectedTools, + ...config.strategies.extractTool.protectedTools + ] - if (part.tool === "prune") { + if (part.tool === "discard" || part.tool === "extract") { state.nudgeCounter = 0 } else if ( - !config.strategies.pruneTool.protectedTools.includes(part.tool) && + !allProtectedTools.includes(part.tool) && !isProtectedByTurn ) { state.nudgeCounter++ diff --git a/lib/strategies/index.ts b/lib/strategies/index.ts index 869a243..02d2f83 100644 --- a/lib/strategies/index.ts +++ b/lib/strategies/index.ts @@ -1,4 +1,4 @@ export { deduplicate } from "./deduplication" export { runOnIdle } from "./on-idle" -export { createPruneTool } from "./prune-tool" +export { createDiscardTool, createExtractTool } from "./tools" export { supersedeWrites } from "./supersede-writes" diff --git a/lib/strategies/prune-tool.ts b/lib/strategies/prune-tool.ts deleted file mode 100644 index a0ab83d..0000000 --- a/lib/strategies/prune-tool.ts +++ /dev/null @@ -1,155 +0,0 @@ -import { tool } from "@opencode-ai/plugin" -import type { SessionState, ToolParameterEntry, WithParts } from "../state" -import type { PluginConfig } from "../config" -import { buildToolIdList } from "../messages/utils" -import { PruneReason, sendUnifiedNotification } from "../ui/notification" -import { formatPruningResultForTool } from "../ui/utils" -import { ensureSessionInitialized } from "../state" -import { saveSessionState } from "../state/persistence" -import type { Logger } from "../logger" -import { loadPrompt } from "../prompt" -import { calculateTokensSaved, getCurrentParams } from "./utils" - -/** Tool description loaded from prompts/prune-tool-spec.txt */ -const TOOL_DESCRIPTION = loadPrompt("prune-tool-spec") - -export interface PruneToolContext { - client: any - state: SessionState - logger: Logger - config: PluginConfig - workingDirectory: string -} - -/** - * Creates the prune tool definition. - * Accepts numeric IDs from the list and prunes those tool outputs. - */ -export function createPruneTool( - ctx: PruneToolContext, -): ReturnType { - return tool({ - description: TOOL_DESCRIPTION, - args: { - ids: tool.schema.array( - tool.schema.string() - ).describe( - "Numeric IDs as strings to prune from the list" - ), - metadata: tool.schema.object({ - reason: tool.schema.enum(["completion", "noise", "consolidation"]).describe("The reason for pruning"), - distillation: tool.schema.record(tool.schema.string(), tool.schema.any()).optional().describe( - "An object containing detailed summaries or extractions of the key findings from the tools being pruned. This is REQUIRED for 'consolidation'." - ), - }).describe("Metadata about the pruning operation."), - }, - async execute(args, toolCtx) { - const { client, state, logger, config, workingDirectory } = ctx - const sessionId = toolCtx.sessionID - - logger.info("Prune tool invoked") - logger.info(JSON.stringify(args)) - - if (!args.ids || args.ids.length === 0) { - logger.debug("Prune tool called but args.ids is empty or undefined: " + JSON.stringify(args)) - return "No IDs provided. Check the list for available IDs to prune." - } - - if (!args.metadata || !args.metadata.reason) { - logger.debug("Prune tool called without metadata.reason: " + JSON.stringify(args)) - return "Missing metadata.reason. Provide metadata: { reason: 'completion' | 'noise' | 'consolidation' }" - } - - const { reason, distillation } = args.metadata; - - const numericToolIds: number[] = args.ids - .map(id => parseInt(id, 10)) - .filter((n): n is number => !isNaN(n)) - - if (numericToolIds.length === 0) { - logger.debug("No numeric tool IDs provided for pruning, yet prune tool was called: " + JSON.stringify(args)) - return "No numeric IDs provided. Format: ids: [id1, id2, ...]" - } - - // Fetch messages to calculate tokens and find current agent - const messagesResponse = await client.session.messages({ - path: { id: sessionId } - }) - const messages: WithParts[] = messagesResponse.data || messagesResponse - - await ensureSessionInitialized(ctx.client, state, sessionId, logger, messages) - - const currentParams = getCurrentParams(messages, logger) - const toolIdList: string[] = buildToolIdList(state, messages, logger) - - // Validate that all numeric IDs are within bounds - if (numericToolIds.some(id => id < 0 || id >= toolIdList.length)) { - logger.debug("Invalid tool IDs provided: " + numericToolIds.join(", ")) - return "Invalid IDs provided. Only use numeric IDs from the list." - } - - // Validate that all IDs exist in cache and aren't protected - // (rejects hallucinated IDs and turn-protected tools not shown in ) - for (const index of numericToolIds) { - const id = toolIdList[index] - const metadata = state.toolParameters.get(id) - if (!metadata) { - logger.debug("Rejecting prune request - ID not in cache (turn-protected or hallucinated)", { index, id }) - return "Invalid IDs provided. Only use numeric IDs from the list." - } - if (config.strategies.pruneTool.protectedTools.includes(metadata.tool)) { - logger.debug("Rejecting prune request - protected tool", { index, id, tool: metadata.tool }) - return "Invalid IDs provided. Only use numeric IDs from the list." - } - } - - const pruneToolIds: string[] = numericToolIds.map(index => toolIdList[index]) - state.prune.toolIds.push(...pruneToolIds) - - const toolMetadata = new Map() - for (const id of pruneToolIds) { - const toolParameters = state.toolParameters.get(id) - if (toolParameters) { - toolMetadata.set(id, toolParameters) - } else { - logger.debug("No metadata found for ID", { id }) - } - } - - state.stats.pruneTokenCounter += calculateTokensSaved(state, messages, pruneToolIds) - - await sendUnifiedNotification( - client, - logger, - config, - state, - sessionId, - pruneToolIds, - toolMetadata, - reason as PruneReason, - currentParams, - workingDirectory - ) - - state.stats.totalPruneTokens += state.stats.pruneTokenCounter - state.stats.pruneTokenCounter = 0 - state.nudgeCounter = 0 - - saveSessionState(state, logger) - .catch(err => logger.error("Failed to persist state", { error: err.message })) - - const result = formatPruningResultForTool( - pruneToolIds, - toolMetadata, - workingDirectory - ) - // - // if (distillation) { - // logger.info("Distillation data received:", distillation) - // } - - return result - }, - }) -} - diff --git a/lib/strategies/tools.ts b/lib/strategies/tools.ts new file mode 100644 index 0000000..b11eb2e --- /dev/null +++ b/lib/strategies/tools.ts @@ -0,0 +1,210 @@ +import { tool } from "@opencode-ai/plugin" +import type { SessionState, ToolParameterEntry, WithParts } from "../state" +import type { PluginConfig } from "../config" +import { buildToolIdList } from "../messages/utils" +import { PruneReason, sendUnifiedNotification, sendDistillationNotification } from "../ui/notification" +import { formatPruningResultForTool } from "../ui/utils" +import { ensureSessionInitialized } from "../state" +import { saveSessionState } from "../state/persistence" +import type { Logger } from "../logger" +import { loadPrompt } from "../prompt" +import { calculateTokensSaved, getCurrentParams } from "./utils" + +const DISCARD_TOOL_DESCRIPTION = loadPrompt("discard-tool-spec") +const EXTRACT_TOOL_DESCRIPTION = loadPrompt("extract-tool-spec") + +export interface PruneToolContext { + client: any + state: SessionState + logger: Logger + config: PluginConfig + workingDirectory: string +} + +// Shared logic for executing prune operations. +async function executePruneOperation( + ctx: PruneToolContext, + toolCtx: { sessionID: string }, + ids: string[], + reason: PruneReason, + toolName: string, + distillation?: Record +): Promise { + const { client, state, logger, config, workingDirectory } = ctx + const sessionId = toolCtx.sessionID + + logger.info(`${toolName} tool invoked`) + logger.info(JSON.stringify({ ids, reason })) + + if (!ids || ids.length === 0) { + logger.debug(`${toolName} tool called but ids is empty or undefined`) + return `No IDs provided. Check the list for available IDs to ${toolName.toLowerCase()}.` + } + + const numericToolIds: number[] = ids + .map(id => parseInt(id, 10)) + .filter((n): n is number => !isNaN(n)) + + if (numericToolIds.length === 0) { + logger.debug(`No numeric tool IDs provided for ${toolName}: ` + JSON.stringify(ids)) + return "No numeric IDs provided. Format: ids: [id1, id2, ...]" + } + + // Fetch messages to calculate tokens and find current agent + const messagesResponse = await client.session.messages({ + path: { id: sessionId } + }) + const messages: WithParts[] = messagesResponse.data || messagesResponse + + await ensureSessionInitialized(ctx.client, state, sessionId, logger, messages) + + const currentParams = getCurrentParams(messages, logger) + const toolIdList: string[] = buildToolIdList(state, messages, logger) + + // Validate that all numeric IDs are within bounds + if (numericToolIds.some(id => id < 0 || id >= toolIdList.length)) { + logger.debug("Invalid tool IDs provided: " + numericToolIds.join(", ")) + return "Invalid IDs provided. Only use numeric IDs from the list." + } + + // Validate that all IDs exist in cache and aren't protected + // (rejects hallucinated IDs and turn-protected tools not shown in ) + for (const index of numericToolIds) { + const id = toolIdList[index] + const metadata = state.toolParameters.get(id) + if (!metadata) { + logger.debug("Rejecting prune request - ID not in cache (turn-protected or hallucinated)", { index, id }) + return "Invalid IDs provided. Only use numeric IDs from the list." + } + const allProtectedTools = [ + ...config.strategies.discardTool.protectedTools, + ...config.strategies.extractTool.protectedTools + ] + if (allProtectedTools.includes(metadata.tool)) { + logger.debug("Rejecting prune request - protected tool", { index, id, tool: metadata.tool }) + return "Invalid IDs provided. Only use numeric IDs from the list." + } + } + + const pruneToolIds: string[] = numericToolIds.map(index => toolIdList[index]) + state.prune.toolIds.push(...pruneToolIds) + + const toolMetadata = new Map() + for (const id of pruneToolIds) { + const toolParameters = state.toolParameters.get(id) + if (toolParameters) { + toolMetadata.set(id, toolParameters) + } else { + logger.debug("No metadata found for ID", { id }) + } + } + + state.stats.pruneTokenCounter += calculateTokensSaved(state, messages, pruneToolIds) + + await sendUnifiedNotification( + client, + logger, + config, + state, + sessionId, + pruneToolIds, + toolMetadata, + reason, + currentParams, + workingDirectory + ) + + if (distillation && config.strategies.extractTool.showDistillation) { + await sendDistillationNotification( + client, + logger, + sessionId, + distillation, + currentParams + ) + } + + state.stats.totalPruneTokens += state.stats.pruneTokenCounter + state.stats.pruneTokenCounter = 0 + state.nudgeCounter = 0 + + saveSessionState(state, logger) + .catch(err => logger.error("Failed to persist state", { error: err.message })) + + return formatPruningResultForTool( + pruneToolIds, + toolMetadata, + workingDirectory + ) +} + +export function createDiscardTool( + ctx: PruneToolContext, +): ReturnType { + return tool({ + description: DISCARD_TOOL_DESCRIPTION, + args: { + ids: tool.schema.array( + tool.schema.string() + ).describe( + "First element is the reason ('completion' or 'noise'), followed by numeric IDs as strings to discard" + ), + }, + async execute(args, toolCtx) { + // Parse reason from first element, numeric IDs from the rest + const reason = args.ids?.[0] + const validReasons = ["completion", "noise"] as const + if (typeof reason !== "string" || !validReasons.includes(reason as any)) { + ctx.logger.debug("Invalid discard reason provided: " + reason) + return "No valid reason found. Use 'completion' or 'noise' as the first element." + } + + const numericIds = args.ids.slice(1) + + return executePruneOperation( + ctx, + toolCtx, + numericIds, + reason as PruneReason, + "Discard" + ) + }, + }) +} + +export function createExtractTool( + ctx: PruneToolContext, +): ReturnType { + return tool({ + description: EXTRACT_TOOL_DESCRIPTION, + args: { + ids: tool.schema.array( + tool.schema.string() + ).describe( + "Numeric IDs as strings to extract from the list" + ), + distillation: tool.schema.record(tool.schema.string(), tool.schema.any()).describe( + "REQUIRED. An object mapping each ID to its distilled findings. Must contain an entry for every ID being pruned." + ), + }, + async execute(args, toolCtx) { + if (!args.distillation || Object.keys(args.distillation).length === 0) { + ctx.logger.debug("Extract tool called without distillation: " + JSON.stringify(args)) + return "Missing distillation. You must provide distillation data when using extract. Format: distillation: { \"id\": { ...findings... } }" + } + + // Log the distillation for debugging/analysis + ctx.logger.info("Distillation data received:") + ctx.logger.info(JSON.stringify(args.distillation, null, 2)) + + return executePruneOperation( + ctx, + toolCtx, + args.ids, + "consolidation" as PruneReason, + "Extract", + args.distillation + ) + }, + }) +} diff --git a/lib/strategies/utils.ts b/lib/strategies/utils.ts index 3c6a1b1..ca610be 100644 --- a/lib/strategies/utils.ts +++ b/lib/strategies/utils.ts @@ -37,7 +37,6 @@ function estimateTokensBatch(texts: string[]): number[] { /** * Calculates approximate tokens saved by pruning the given tool call IDs. - * TODO: Make it count message content that are not tool outputs. Currently it ONLY covers tool outputs and errors */ export const calculateTokensSaved = ( state: SessionState, diff --git a/lib/ui/notification.ts b/lib/ui/notification.ts index ead50ac..079d582 100644 --- a/lib/ui/notification.ts +++ b/lib/ui/notification.ts @@ -82,6 +82,37 @@ export async function sendUnifiedNotification( return true } +function formatDistillationMessage(distillation: Record): string { + const lines: string[] = ['▣ DCP | Extracted Distillation'] + + for (const [id, findings] of Object.entries(distillation)) { + lines.push(`\n─── ID ${id} ───`) + if (typeof findings === 'object' && findings !== null) { + lines.push(JSON.stringify(findings, null, 2)) + } else { + lines.push(String(findings)) + } + } + + return lines.join('\n') +} + +export async function sendDistillationNotification( + client: any, + logger: Logger, + sessionId: string, + distillation: Record, + params: any +): Promise { + if (!distillation || Object.keys(distillation).length === 0) { + return false + } + + const message = formatDistillationMessage(distillation) + await sendIgnoredMessage(client, sessionId, message, params, logger) + return true +} + export async function sendIgnoredMessage( client: any, sessionID: string,