From 0e3a28dca9ccc10d607b99e87a8d87aabff5c80c Mon Sep 17 00:00:00 2001 From: Daniel Smolsky Date: Sat, 20 Dec 2025 02:56:57 -0500 Subject: [PATCH 01/13] Update config and state management for discard and extract tools --- lib/config.ts | 204 +++++++++++++++++++------- lib/messages/prune.ts | 14 +- lib/state/tool-cache.ts | 23 ++- lib/strategies/index.ts | 2 +- lib/strategies/prune-tool.ts | 267 ++++++++++++++++++++--------------- 5 files changed, 337 insertions(+), 173 deletions(-) diff --git a/lib/config.ts b/lib/config.ts index 9a670fe8..44c2fe1d 100644 --- a/lib/config.ts +++ b/lib/config.ts @@ -34,6 +34,20 @@ 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 +} + export interface SupersedeWrites { enabled: boolean } @@ -45,12 +59,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 +89,26 @@ 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' ]) // Extract all key paths from a config object for validation @@ -159,28 +184,54 @@ 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.pruneTool.protectedTools !== undefined && !Array.isArray(strategies.pruneTool.protectedTools)) { - errors.push({ key: 'strategies.pruneTool.protectedTools', expected: 'string[]', actual: typeof strategies.pruneTool.protectedTools }) + 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.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.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.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.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.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.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.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.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.extractTool.protectedTools !== undefined && !Array.isArray(strategies.extractTool.protectedTools)) { + errors.push({ key: 'strategies.extractTool.protectedTools', expected: 'string[]', actual: typeof strategies.extractTool.protectedTools }) + } + 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.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.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.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 }) } } } @@ -254,7 +305,19 @@ const defaultConfig: PluginConfig = { supersedeWrites: { enabled: true }, - pruneTool: { + discardTool: { + enabled: true, + protectedTools: [...DEFAULT_PROTECTED_TOOLS], + turnProtection: { + enabled: false, + turns: 4 + }, + nudge: { + enabled: true, + frequency: 10 + } + }, + extractTool: { enabled: true, protectedTools: [...DEFAULT_PROTECTED_TOOLS], turnProtection: { @@ -357,18 +420,34 @@ function createDefaultConfig(): void { "supersedeWrites": { "enabled": true }, - // Exposes a prune tool to your LLM to call when it determines pruning is necessary - \"pruneTool\": { - \"enabled\": true, + // Exposes a discard tool to your LLM to call when it determines pruning is necessary + "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 + } + }, + // Exposes an extract tool to your LLM to call when it determines pruning is necessary + "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 } @@ -444,21 +523,38 @@ 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 } }, supersedeWrites: { @@ -479,11 +575,17 @@ 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 } }, supersedeWrites: { ...config.strategies.supersedeWrites diff --git a/lib/messages/prune.ts b/lib/messages/prune.ts index f9348bf3..3c54bba9 100644 --- a/lib/messages/prune.ts +++ b/lib/messages/prune.ts @@ -34,7 +34,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 +65,7 @@ export const insertPruneToolContext = ( logger: Logger, messages: WithParts[] ): void => { - if (!config.strategies.pruneTool.enabled) { + if (!config.strategies.discardTool.enabled && !config.strategies.extractTool.enabled) { return } @@ -84,7 +88,11 @@ export const insertPruneToolContext = ( logger.debug("prunable-tools: \n" + prunableToolsList) let nudgeString = "" - if (state.nudgeCounter >= config.strategies.pruneTool.nudge.frequency) { + 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 } diff --git a/lib/state/tool-cache.ts b/lib/state/tool-cache.ts index f8ad2b3b..6e2650b9 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 869a2431..c30bd8cb 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 "./prune-tool" export { supersedeWrites } from "./supersede-writes" diff --git a/lib/strategies/prune-tool.ts b/lib/strategies/prune-tool.ts index a0ab83d7..b13da70e 100644 --- a/lib/strategies/prune-tool.ts +++ b/lib/strategies/prune-tool.ts @@ -10,8 +10,8 @@ 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") +const DISCARD_TOOL_DESCRIPTION = loadPrompt("discard-tool-spec") +const EXTRACT_TOOL_DESCRIPTION = loadPrompt("extract-tool-spec") export interface PruneToolContext { client: any @@ -21,135 +21,178 @@ export interface PruneToolContext { workingDirectory: string } -/** - * Creates the prune tool definition. - * Accepts numeric IDs from the list and prunes those tool outputs. - */ -export function createPruneTool( +// Shared logic for executing prune operations. +async function executePruneOperation( + ctx: PruneToolContext, + toolCtx: { sessionID: string }, + ids: string[], + reason: PruneReason, + toolName: string +): 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 + ) + + 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: TOOL_DESCRIPTION, + description: DISCARD_TOOL_DESCRIPTION, args: { ids: tool.schema.array( tool.schema.string() ).describe( - "Numeric IDs as strings to prune from the list" + "First element is the reason ('completion' or 'noise'), followed by numeric IDs as strings to discard" ), - 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." - } + // 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 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) + const numericIds = args.ids.slice(1) - await sendUnifiedNotification( - client, - logger, - config, - state, - sessionId, - pruneToolIds, - toolMetadata, + return executePruneOperation( + ctx, + toolCtx, + numericIds, reason as PruneReason, - currentParams, - workingDirectory + "Discard" ) + }, + }) +} - state.stats.totalPruneTokens += state.stats.pruneTokenCounter - state.stats.pruneTokenCounter = 0 - state.nudgeCounter = 0 +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... } }" + } - saveSessionState(state, logger) - .catch(err => logger.error("Failed to persist state", { error: err.message })) + // Log the distillation for debugging/analysis + ctx.logger.info("Distillation data received:") + ctx.logger.info(JSON.stringify(args.distillation, null, 2)) - const result = formatPruningResultForTool( - pruneToolIds, - toolMetadata, - workingDirectory + return executePruneOperation( + ctx, + toolCtx, + args.ids, + "consolidation" as PruneReason, + "Extract" ) - // - // if (distillation) { - // logger.info("Distillation data received:", distillation) - // } - - return result }, }) } - From ef0f25dcfafea3c420477cba2b3c89e6a55bc2d3 Mon Sep 17 00:00:00 2001 From: Daniel Smolsky Date: Sat, 20 Dec 2025 02:57:04 -0500 Subject: [PATCH 02/13] Register discard/extract tools and update system prompts --- index.ts | 21 ++++++--- lib/prompts/discard-tool-spec.txt | 56 ++++++++++++++++++++++++ lib/prompts/extract-tool-spec.txt | 68 +++++++++++++++++++++++++++++ lib/prompts/prune-nudge.txt | 8 ++-- lib/prompts/prune-system-prompt.txt | 30 +++++++------ 5 files changed, 159 insertions(+), 24 deletions(-) create mode 100644 lib/prompts/discard-tool-spec.txt create mode 100644 lib/prompts/extract-tool-spec.txt diff --git a/index.ts b/index.ts index ac877050..fa31e041 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) => { @@ -38,8 +38,15 @@ const plugin: Plugin = (async (ctx) => { logger, config ), - tool: config.strategies.pruneTool.enabled ? { - prune: createPruneTool({ + tool: (config.strategies.discardTool.enabled || config.strategies.extractTool.enabled) ? { + discard: createDiscardTool({ + client: ctx.client, + state, + logger, + config, + workingDirectory: ctx.directory + }), + extract: createExtractTool({ client: ctx.client, state, logger, @@ -48,15 +55,15 @@ const plugin: Plugin = (async (ctx) => { }), } : undefined, config: async (opencodeConfig) => { - // Add prune to primary_tools by mutating the opencode config + // Add discard and extract to primary_tools by mutating the opencode config // This works because config is cached and passed by reference - if (config.strategies.pruneTool.enabled) { + if (config.strategies.discardTool.enabled || config.strategies.extractTool.enabled) { const existingPrimaryTools = opencodeConfig.experimental?.primary_tools ?? [] opencodeConfig.experimental = { ...opencodeConfig.experimental, - primary_tools: [...existingPrimaryTools, "prune"], + primary_tools: [...existingPrimaryTools, "discard", "extract"], } - logger.info("Added 'prune' to experimental.primary_tools via config mutation") + logger.info("Added 'discard' and 'extract' to experimental.primary_tools via config mutation") } }, event: createEventHandler(ctx.client, config, state, logger, ctx.directory), diff --git a/lib/prompts/discard-tool-spec.txt b/lib/prompts/discard-tool-spec.txt new file mode 100644 index 00000000..51ca5781 --- /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:** Use the `consolidate` tool instead when you want to keep distilled findings from the tool outputs. +- **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 00000000..e85fb8cb --- /dev/null +++ b/lib/prompts/extract-tool-spec.txt @@ -0,0 +1,68 @@ +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: + +**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 discard 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 don't need to preserve information:** Use the `discard` tool instead for completed tasks or noise removal. +- **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. + +## 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/prune-nudge.txt b/lib/prompts/prune-nudge.txt index ef84d35c..549e34a0 100644 --- a/lib/prompts/prune-nudge.txt +++ b/lib/prompts/prune-nudge.txt @@ -2,9 +2,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 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, discard the tools used. +2. **Noise Removal:** If you read files or ran commands that yielded no value, discard them NOW. +3. **Extraction:** If you are holding valuable raw data, you *must* use the `extract` tool 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 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 perform context management. diff --git a/lib/prompts/prune-system-prompt.txt b/lib/prompts/prune-system-prompt.txt index 88ba3079..7bd11d39 100644 --- a/lib/prompts/prune-system-prompt.txt +++ b/lib/prompts/prune-system-prompt.txt @@ -2,21 +2,25 @@ 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. +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 use the `prune` tool when ANY of these are true: +WHEN TO PRUNE? THE SCENARIOS TO CONSIDER +1. TASK COMPLETION: When work is done, quietly discard the tools that aren't needed anymore. +2. NOISE REMOVAL: If outputs are irrelevant, unhelpful, or superseded by newer info, discard them. +3. CONTEXT EXTRACTION: When you have valuable context you want to preserve but need to reduce size, use `extract` with 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 use `discard` or `extract` 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 +- You have gathered enough information to extract from related tools and preserve their value via distillation +- Context contains tool outputs 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 +30,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 From c351d20e1531f5bb3c8d3557507327903815a5e1 Mon Sep 17 00:00:00 2001 From: Daniel Smolsky Date: Sat, 20 Dec 2025 02:57:11 -0500 Subject: [PATCH 03/13] Update documentation and remove obsolete prune-tool-spec --- README.md | 28 ++++++++-- lib/prompts/prune-tool-spec.txt | 95 --------------------------------- 2 files changed, 23 insertions(+), 100 deletions(-) delete mode 100644 lib/prompts/prune-tool-spec.txt diff --git a/README.md b/README.md index 9d15e730..a5a13702 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,24 @@ 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": { + // Exposes a discard tool to your LLM for removing unneeded tool outputs + "discardTool": { + "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 discard tool (every tool results) + "nudge": { + "enabled": true, + "frequency": 10 + } + }, + // Exposes an extract tool to your LLM for distilling context before removal + "extractTool": { "enabled": true, // Additional tools to protect from pruning "protectedTools": [], @@ -82,7 +100,7 @@ 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 extract tool (every tool results) "nudge": { "enabled": true, "frequency": 10 @@ -109,7 +127,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/lib/prompts/prune-tool-spec.txt b/lib/prompts/prune-tool-spec.txt deleted file mode 100644 index 6d59aa3d..00000000 --- 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" }] - From 46c623a24d6a8cbaec4038da3283b32eff1a0422 Mon Sep 17 00:00:00 2001 From: Daniel Smolsky Date: Sat, 20 Dec 2025 12:21:50 -0500 Subject: [PATCH 04/13] feat: dynamically load system and nudge prompts based on enabled tools - Splits system and nudge prompts into separate files for discard, extract, or both. - Updates to load the appropriate system prompt based on configuration. - Updates to dynamically select the nudge string. - Deletes the previous monolithic prompt files. --- index.ts | 16 +++++- lib/messages/prune.ts | 16 +++++- .../{prune-nudge.txt => nudge/nudge-both.txt} | 0 lib/prompts/nudge/nudge-discard.txt | 9 ++++ lib/prompts/nudge/nudge-extract.txt | 10 ++++ .../system-prompt-both.txt} | 0 lib/prompts/system/system-prompt-discard.txt | 50 ++++++++++++++++++ lib/prompts/system/system-prompt-extract.txt | 52 +++++++++++++++++++ 8 files changed, 150 insertions(+), 3 deletions(-) rename lib/prompts/{prune-nudge.txt => nudge/nudge-both.txt} (100%) create mode 100644 lib/prompts/nudge/nudge-discard.txt create mode 100644 lib/prompts/nudge/nudge-extract.txt rename lib/prompts/{prune-system-prompt.txt => system/system-prompt-both.txt} (100%) create mode 100644 lib/prompts/system/system-prompt-discard.txt create mode 100644 lib/prompts/system/system-prompt-extract.txt diff --git a/index.ts b/index.ts index fa31e041..89bf8b2a 100644 --- a/index.ts +++ b/index.ts @@ -29,7 +29,21 @@ const plugin: Plugin = (async (ctx) => { 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 // No context management tools enabled + } + + const syntheticPrompt = loadPrompt(promptName) output.system.push(syntheticPrompt) }, "experimental.chat.messages.transform": createChatMessageTransformHandler( diff --git a/lib/messages/prune.ts b/lib/messages/prune.ts index 3c54bba9..c26c1bd4 100644 --- a/lib/messages/prune.ts +++ b/lib/messages/prune.ts @@ -8,7 +8,19 @@ 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. @@ -94,7 +106,7 @@ export const insertPruneToolContext = ( ) 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/prune-nudge.txt b/lib/prompts/nudge/nudge-both.txt similarity index 100% rename from lib/prompts/prune-nudge.txt rename to lib/prompts/nudge/nudge-both.txt diff --git a/lib/prompts/nudge/nudge-discard.txt b/lib/prompts/nudge/nudge-discard.txt new file mode 100644 index 00000000..7ded42f9 --- /dev/null +++ b/lib/prompts/nudge/nudge-discard.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 a sub-task is complete, discard the tools used. +2. **Noise Removal:** If you read files or ran commands that yielded no value, discard them NOW. + +**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 00000000..3d9ea9a4 --- /dev/null +++ b/lib/prompts/nudge/nudge-extract.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, extract findings and remove the raw tool outputs. +2. **Noise Removal:** If you read files or ran commands that yielded no value, extract them with minimal distillation NOW. +3. **Extraction:** If you are holding valuable raw data, you *must* use the `extract` tool 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 extract and remove unneeded tool outputs. + diff --git a/lib/prompts/prune-system-prompt.txt b/lib/prompts/system/system-prompt-both.txt similarity index 100% rename from lib/prompts/prune-system-prompt.txt rename to lib/prompts/system/system-prompt-both.txt diff --git a/lib/prompts/system/system-prompt-discard.txt b/lib/prompts/system/system-prompt-discard.txt new file mode 100644 index 00000000..a3ecb46b --- /dev/null +++ b/lib/prompts/system/system-prompt-discard.txt @@ -0,0 +1,50 @@ + + + +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? THE SCENARIOS TO CONSIDER +1. TASK COMPLETION: When work is done, quietly discard the tools that aren't needed anymore. +2. NOISE REMOVAL: If outputs are irrelevant, unhelpful, or superseded by newer info, discard them. + +You WILL use `discard` when ANY of these are true: +- Task or sub-task is complete +- You are about to start a new phase of work +- Context contains tool outputs that are unhelpful, noise, or made obsolete by newer outputs +- 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 00000000..317a9496 --- /dev/null +++ b/lib/prompts/system/system-prompt-extract.txt @@ -0,0 +1,52 @@ + + + +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 into distilled knowledge before removing raw outputs. 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 unless it is pure noise. Evaluate what SHOULD be extracted before jumping the gun. + +WHEN TO EXTRACT? THE SCENARIOS TO CONSIDER +1. TASK COMPLETION: When work is done, extract any valuable findings and remove the raw outputs. +2. NOISE REMOVAL: If outputs are irrelevant, unhelpful, or superseded by newer info, extract them with minimal distillation. +3. CONTEXT PRESERVATION: When you have valuable context you want to preserve but need to reduce size, use `extract` with 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 use `extract` 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 extract from related tools and preserve their value via distillation +- Context contains tool outputs that are unhelpful, noise, or made obsolete by newer outputs +- 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. + + From bd96bdfebea8938cc1c3201e638ad89fa8b231f1 Mon Sep 17 00:00:00 2001 From: Daniel Smolsky Date: Sat, 20 Dec 2025 12:29:27 -0500 Subject: [PATCH 05/13] cleanup --- index.ts | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/index.ts b/index.ts index 89bf8b2a..4acd86df 100644 --- a/index.ts +++ b/index.ts @@ -18,11 +18,9 @@ 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, }) @@ -31,7 +29,7 @@ const plugin: Plugin = (async (ctx) => { "experimental.chat.system.transform": async (_input: unknown, output: { system: string[] }) => { const discardEnabled = config.strategies.discardTool.enabled const extractEnabled = config.strategies.extractTool.enabled - + let promptName: string if (discardEnabled && extractEnabled) { promptName = "system/system-prompt-both" @@ -40,9 +38,9 @@ const plugin: Plugin = (async (ctx) => { } else if (extractEnabled) { promptName = "system/system-prompt-extract" } else { - return // No context management tools enabled + return } - + const syntheticPrompt = loadPrompt(promptName) output.system.push(syntheticPrompt) }, From 36ed1ef49a552eb8a99cc4abbcda0bfee78f5689 Mon Sep 17 00:00:00 2001 From: Daniel Smolsky Date: Sat, 20 Dec 2025 12:30:13 -0500 Subject: [PATCH 06/13] refactor: rename prune-tool.ts to tools.ts to better reflect its contents --- lib/strategies/index.ts | 2 +- lib/strategies/{prune-tool.ts => tools.ts} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename lib/strategies/{prune-tool.ts => tools.ts} (100%) diff --git a/lib/strategies/index.ts b/lib/strategies/index.ts index c30bd8cb..02d2f831 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 { createDiscardTool, createExtractTool } from "./prune-tool" +export { createDiscardTool, createExtractTool } from "./tools" export { supersedeWrites } from "./supersede-writes" diff --git a/lib/strategies/prune-tool.ts b/lib/strategies/tools.ts similarity index 100% rename from lib/strategies/prune-tool.ts rename to lib/strategies/tools.ts From 7a91b9b7cfafde6df983c7816a6ca30015219f8b Mon Sep 17 00:00:00 2001 From: Daniel Smolsky Date: Sat, 20 Dec 2025 15:02:28 -0500 Subject: [PATCH 07/13] refactor: consolidate and clarify tool prompts for standalone use - Remove cross-references between discard/extract tools so each works independently - Add decision hierarchy in both-mode: discard as default, extract for preservation - Consolidate redundant 'WHEN TO X' scenarios with trigger lists - Change trigger lists to focus on timing ('evaluate when') vs prescriptive action - Remove confusing 'minimal distillation for cleanup' concept from extract prompts - Standardize structure across all system prompts and nudges --- lib/prompts/discard-tool-spec.txt | 2 +- lib/prompts/extract-tool-spec.txt | 1 - lib/prompts/nudge/nudge-both.txt | 6 +++--- lib/prompts/nudge/nudge-discard.txt | 4 ++-- lib/prompts/nudge/nudge-extract.txt | 7 +++---- lib/prompts/system/system-prompt-both.txt | 21 ++++++++++++-------- lib/prompts/system/system-prompt-discard.txt | 9 ++++----- lib/prompts/system/system-prompt-extract.txt | 15 ++++++-------- 8 files changed, 32 insertions(+), 33 deletions(-) diff --git a/lib/prompts/discard-tool-spec.txt b/lib/prompts/discard-tool-spec.txt index 51ca5781..4cbf50a5 100644 --- a/lib/prompts/discard-tool-spec.txt +++ b/lib/prompts/discard-tool-spec.txt @@ -19,7 +19,7 @@ Use `discard` for removing tool outputs that are no longer needed **without pres ## When NOT to Use This Tool -- **If you need to preserve information:** Use the `consolidate` tool instead when you want to keep distilled findings from the tool outputs. +- **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 diff --git a/lib/prompts/extract-tool-spec.txt b/lib/prompts/extract-tool-spec.txt index e85fb8cb..895effa1 100644 --- a/lib/prompts/extract-tool-spec.txt +++ b/lib/prompts/extract-tool-spec.txt @@ -24,7 +24,6 @@ You MUST provide distilled findings in the `distillation` parameter. This is not ## When NOT to Use This Tool -- **If you don't need to preserve information:** Use the `discard` tool instead for completed tasks or noise removal. - **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. diff --git a/lib/prompts/nudge/nudge-both.txt b/lib/prompts/nudge/nudge-both.txt index 549e34a0..f9fa4926 100644 --- a/lib/prompts/nudge/nudge-both.txt +++ b/lib/prompts/nudge/nudge-both.txt @@ -2,9 +2,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 a sub-task is complete, discard the tools used. -2. **Noise Removal:** If you read files or ran commands that yielded no value, discard them NOW. -3. **Extraction:** If you are holding valuable raw data, you *must* use the `extract` tool to distill the insights and remove the raw entry. +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/nudge/nudge-discard.txt b/lib/prompts/nudge/nudge-discard.txt index 7ded42f9..1ccecf9e 100644 --- a/lib/prompts/nudge/nudge-discard.txt +++ b/lib/prompts/nudge/nudge-discard.txt @@ -2,8 +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, discard the tools used. -2. **Noise Removal:** If you read files or ran commands that yielded no value, discard them NOW. +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 discard unneeded tool outputs. diff --git a/lib/prompts/nudge/nudge-extract.txt b/lib/prompts/nudge/nudge-extract.txt index 3d9ea9a4..4ee8dc05 100644 --- a/lib/prompts/nudge/nudge-extract.txt +++ b/lib/prompts/nudge/nudge-extract.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, extract findings and remove the raw tool outputs. -2. **Noise Removal:** If you read files or ran commands that yielded no value, extract them with minimal distillation NOW. -3. **Extraction:** If you are holding valuable raw data, you *must* use the `extract` tool to distill the insights and remove the raw entry. +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 and remove unneeded tool outputs. +**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 unneeded tool outputs. diff --git a/lib/prompts/system/system-prompt-both.txt b/lib/prompts/system/system-prompt-both.txt index 7bd11d39..f1e88aa2 100644 --- a/lib/prompts/system/system-prompt-both.txt +++ b/lib/prompts/system/system-prompt-both.txt @@ -8,19 +8,24 @@ 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. +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) + +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. -WHEN TO PRUNE? THE SCENARIOS TO CONSIDER -1. TASK COMPLETION: When work is done, quietly discard the tools that aren't needed anymore. -2. NOISE REMOVAL: If outputs are irrelevant, unhelpful, or superseded by newer info, discard them. -3. CONTEXT EXTRACTION: When you have valuable context you want to preserve but need to reduce size, use `extract` with 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 use `discard` or `extract` when ANY of these are true: +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 extract from related tools and preserve their value via distillation -- Context contains tool outputs 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: diff --git a/lib/prompts/system/system-prompt-discard.txt b/lib/prompts/system/system-prompt-discard.txt index a3ecb46b..796852e3 100644 --- a/lib/prompts/system/system-prompt-discard.txt +++ b/lib/prompts/system/system-prompt-discard.txt @@ -10,14 +10,13 @@ CONTEXT MANAGEMENT TOOL 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? THE SCENARIOS TO CONSIDER -1. TASK COMPLETION: When work is done, quietly discard the tools that aren't needed anymore. -2. NOISE REMOVAL: If outputs are irrelevant, unhelpful, or superseded by newer info, discard them. +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 use `discard` when ANY of these are true: +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 -- Context contains tool outputs that are unhelpful, noise, or made obsolete by newer outputs - Write or edit operations are complete (discarding removes the large input content) You MUST NOT discard when: diff --git a/lib/prompts/system/system-prompt-extract.txt b/lib/prompts/system/system-prompt-extract.txt index 317a9496..2a1a0568 100644 --- a/lib/prompts/system/system-prompt-extract.txt +++ b/lib/prompts/system/system-prompt-extract.txt @@ -5,21 +5,18 @@ 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 into distilled knowledge before removing raw outputs. Use this to preserve important information while reducing context size. +- `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 unless it is pure noise. Evaluate what SHOULD be extracted before jumping the gun. +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? THE SCENARIOS TO CONSIDER -1. TASK COMPLETION: When work is done, extract any valuable findings and remove the raw outputs. -2. NOISE REMOVAL: If outputs are irrelevant, unhelpful, or superseded by newer info, extract them with minimal distillation. -3. CONTEXT PRESERVATION: When you have valuable context you want to preserve but need to reduce size, use `extract` with 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. +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 use `extract` when ANY of these are true: +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 -- You have gathered enough information to extract from related tools and preserve their value via distillation -- Context contains tool outputs that are unhelpful, noise, or made obsolete by newer outputs - Write or edit operations are complete (extracting removes the large input content) You MUST NOT extract when: From 571ba30ca07a180244f4ae56a05fe109b65fd89f Mon Sep 17 00:00:00 2001 From: Daniel Smolsky Date: Sat, 20 Dec 2025 15:03:37 -0500 Subject: [PATCH 08/13] refactor: add task completion scenario to extract-tool-spec for parity with discard --- lib/prompts/extract-tool-spec.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/lib/prompts/extract-tool-spec.txt b/lib/prompts/extract-tool-spec.txt index 895effa1..cfc90eef 100644 --- a/lib/prompts/extract-tool-spec.txt +++ b/lib/prompts/extract-tool-spec.txt @@ -7,8 +7,13 @@ A `` list is injected into user messages showing available 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 discard large outputs (like full file reads) while keeping only the specific parts you need (like a single function signature or constant). +**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 From 95cf48c96246a6fd77f6a0af3c7d3a6c8be2331a Mon Sep 17 00:00:00 2001 From: Daniel Smolsky Date: Sat, 20 Dec 2025 20:44:22 -0500 Subject: [PATCH 09/13] fix: improve extract prompts with correct wording and format section --- lib/prompts/extract-tool-spec.txt | 7 +++++++ lib/prompts/nudge/nudge-extract.txt | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/lib/prompts/extract-tool-spec.txt b/lib/prompts/extract-tool-spec.txt index cfc90eef..9af5b666 100644 --- a/lib/prompts/extract-tool-spec.txt +++ b/lib/prompts/extract-tool-spec.txt @@ -37,6 +37,13 @@ You MUST provide distilled findings in the `distillation` parameter. This is not - **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 diff --git a/lib/prompts/nudge/nudge-extract.txt b/lib/prompts/nudge/nudge-extract.txt index 4ee8dc05..5bdb370f 100644 --- a/lib/prompts/nudge/nudge-extract.txt +++ b/lib/prompts/nudge/nudge-extract.txt @@ -5,5 +5,5 @@ 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 unneeded tool outputs. +**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. From e34a9daad7d71c7178f28dafe7b62befe3ce8f26 Mon Sep 17 00:00:00 2001 From: Daniel Smolsky Date: Sat, 20 Dec 2025 21:17:32 -0500 Subject: [PATCH 10/13] fix: make cooldown message dynamic based on enabled tools --- lib/messages/prune.ts | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/lib/messages/prune.ts b/lib/messages/prune.ts index c26c1bd4..19cdb0e8 100644 --- a/lib/messages/prune.ts +++ b/lib/messages/prune.ts @@ -26,9 +26,24 @@ 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" @@ -90,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) { From a3eb386f723445d862d1a5200d91993c4bea7042 Mon Sep 17 00:00:00 2001 From: Daniel Smolsky Date: Sat, 20 Dec 2025 21:32:11 -0500 Subject: [PATCH 11/13] docs: clarify discardTool and extractTool comments --- README.md | 4 ++-- lib/config.ts | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a5a13702..b37401b7 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ DCP uses its own config file: "supersedeWrites": { "enabled": true }, - // Exposes a discard tool to your LLM for removing unneeded tool outputs + // Removes tool content from context without preservation (for completed tasks or noise) "discardTool": { "enabled": true, // Additional tools to protect from pruning @@ -90,7 +90,7 @@ DCP uses its own config file: "frequency": 10 } }, - // Exposes an extract tool to your LLM for distilling context before removal + // Distills key findings into preserved knowledge before removing raw content "extractTool": { "enabled": true, // Additional tools to protect from pruning diff --git a/lib/config.ts b/lib/config.ts index 44c2fe1d..1d06ac9a 100644 --- a/lib/config.ts +++ b/lib/config.ts @@ -420,7 +420,7 @@ function createDefaultConfig(): void { "supersedeWrites": { "enabled": true }, - // Exposes a discard tool to your LLM to call when it determines pruning is necessary + // Removes tool content from context without preservation (for completed tasks or noise) "discardTool": { "enabled": true, // Additional tools to protect from pruning @@ -436,7 +436,7 @@ function createDefaultConfig(): void { "frequency": 10 } }, - // Exposes an extract tool to your LLM to call when it determines pruning is necessary + // Distills key findings into preserved knowledge before removing raw content "extractTool": { "enabled": true, // Additional tools to protect from pruning From 5cbc48381d89a16d38864c680ecaa0ac21d49a79 Mon Sep 17 00:00:00 2001 From: Daniel Smolsky Date: Sat, 20 Dec 2025 22:24:28 -0500 Subject: [PATCH 12/13] fix: only register enabled prune tools --- index.ts | 44 ++++++++++++++++++++++++----------------- lib/messages/prune.ts | 8 +++++--- lib/strategies/utils.ts | 1 - 3 files changed, 31 insertions(+), 22 deletions(-) diff --git a/index.ts b/index.ts index 4acd86df..770c5a6b 100644 --- a/index.ts +++ b/index.ts @@ -50,32 +50,40 @@ const plugin: Plugin = (async (ctx) => { logger, config ), - tool: (config.strategies.discardTool.enabled || config.strategies.extractTool.enabled) ? { - discard: createDiscardTool({ - 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 + }), }), - extract: createExtractTool({ - client: ctx.client, - state, - logger, - config, - workingDirectory: ctx.directory + ...(config.strategies.extractTool.enabled && { + extract: createExtractTool({ + client: ctx.client, + state, + logger, + config, + workingDirectory: ctx.directory + }), }), - } : undefined, + }, config: async (opencodeConfig) => { - // Add discard and extract 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.discardTool.enabled || config.strategies.extractTool.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, "discard", "extract"], + primary_tools: [...existingPrimaryTools, ...toolsToAdd], } - logger.info("Added 'discard' and 'extract' 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/messages/prune.ts b/lib/messages/prune.ts index 19cdb0e8..0257afc9 100644 --- a/lib/messages/prune.ts +++ b/lib/messages/prune.ts @@ -11,7 +11,7 @@ const PRUNED_TOOL_OUTPUT_REPLACEMENT = '[Output removed to save context - inform 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) { @@ -30,7 +30,7 @@ ${content} 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" @@ -39,7 +39,7 @@ const getCooldownMessage = (config: PluginConfig): string => { } 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. ` @@ -115,6 +115,8 @@ export const insertPruneToolContext = ( logger.debug("prunable-tools: \n" + prunableToolsList) let nudgeString = "" + // 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 diff --git a/lib/strategies/utils.ts b/lib/strategies/utils.ts index 3c6a1b1b..ca610beb 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, From de76de1569c114e3587dca28870d9df5c28e059d Mon Sep 17 00:00:00 2001 From: Daniel Smolsky Date: Sun, 21 Dec 2025 00:56:28 -0500 Subject: [PATCH 13/13] feat: add showDistillation option to display extracted findings as notification --- README.md | 4 +++- lib/config.ts | 20 +++++++++++++++----- lib/strategies/tools.ts | 18 +++++++++++++++--- lib/ui/notification.ts | 31 +++++++++++++++++++++++++++++++ 4 files changed, 64 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index b37401b7..7a1aa276 100644 --- a/README.md +++ b/README.md @@ -104,7 +104,9 @@ DCP uses its own config file: "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": { diff --git a/lib/config.ts b/lib/config.ts index 1d06ac9a..1ae9ce33 100644 --- a/lib/config.ts +++ b/lib/config.ts @@ -46,6 +46,7 @@ export interface ExtractTool { protectedTools: string[] turnProtection: PruneToolTurnProtection nudge: PruneToolNudge + showDistillation: boolean } export interface SupersedeWrites { @@ -108,7 +109,8 @@ export const VALID_CONFIG_KEYS = new Set([ 'strategies.extractTool.turnProtection.turns', 'strategies.extractTool.nudge', 'strategies.extractTool.nudge.enabled', - 'strategies.extractTool.nudge.frequency' + 'strategies.extractTool.nudge.frequency', + 'strategies.extractTool.showDistillation' ]) // Extract all key paths from a config object for validation @@ -234,6 +236,9 @@ function validateConfigTypes(config: Record): ValidationError[] { 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 @@ -327,7 +332,8 @@ const defaultConfig: PluginConfig = { nudge: { enabled: true, frequency: 10 - } + }, + showDistillation: false }, onIdle: { enabled: false, @@ -450,7 +456,9 @@ function createDefaultConfig(): void { "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": { @@ -555,7 +563,8 @@ function mergeStrategies( 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 @@ -585,7 +594,8 @@ function deepCloneConfig(config: PluginConfig): PluginConfig { ...config.strategies.extractTool, protectedTools: [...config.strategies.extractTool.protectedTools], turnProtection: { ...config.strategies.extractTool.turnProtection }, - nudge: { ...config.strategies.extractTool.nudge } + nudge: { ...config.strategies.extractTool.nudge }, + showDistillation: config.strategies.extractTool.showDistillation }, supersedeWrites: { ...config.strategies.supersedeWrites diff --git a/lib/strategies/tools.ts b/lib/strategies/tools.ts index b13da70e..b11eb2e9 100644 --- a/lib/strategies/tools.ts +++ b/lib/strategies/tools.ts @@ -2,7 +2,7 @@ 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 { PruneReason, sendUnifiedNotification, sendDistillationNotification } from "../ui/notification" import { formatPruningResultForTool } from "../ui/utils" import { ensureSessionInitialized } from "../state" import { saveSessionState } from "../state/persistence" @@ -27,7 +27,8 @@ async function executePruneOperation( toolCtx: { sessionID: string }, ids: string[], reason: PruneReason, - toolName: string + toolName: string, + distillation?: Record ): Promise { const { client, state, logger, config, workingDirectory } = ctx const sessionId = toolCtx.sessionID @@ -113,6 +114,16 @@ async function executePruneOperation( 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 @@ -191,7 +202,8 @@ export function createExtractTool( toolCtx, args.ids, "consolidation" as PruneReason, - "Extract" + "Extract", + args.distillation ) }, }) diff --git a/lib/ui/notification.ts b/lib/ui/notification.ts index ead50acf..079d582d 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,