@compilr-dev/agents 0.3.18 → 0.3.19

package/dist/agent.d.ts

@@ -16,6 +16,7 @@ import { PermissionManager } from './permissions/manager.js';
 import { ContextManager } from './context/manager.js';
 import { FileAccessTracker } from './context/file-tracker.js';
 import type { ObservationMaskConfig } from './context/observation-masker.js';
+import type { PruneConfig } from './context/dead-message-pruner.js';
 import { AnchorManager } from './anchors/manager.js';
 import { GuardrailManager } from './guardrails/manager.js';
 import { type RetryConfig } from './utils/index.js';
@@ -290,6 +291,11 @@ export interface AgentConfig {
      * Enabled by default when contextManager is provided. Set to `false` to disable.
      */
     compactToolResults?: boolean;
+    /**
+     * Dead message pruning configuration. Prunes superseded errors and permission exchanges.
+     * Enabled by default when contextManager is provided. Set to `false` to disable.
+     */
+    deadMessagePruning?: Partial<PruneConfig> | false;
     /**
      * Event handler for monitoring agent execution
      */
@@ -898,6 +904,10 @@ export declare class Agent {
      * Whether to use compact text format for tool results in LLM messages
      */
     private readonly compactToolResults;
+    /**
+     * Dead message pruner for removing superseded errors and permission exchanges
+     */
+    private readonly deadMessagePruner?;
     constructor(config: AgentConfig);
     /**
      * Create an agent with project memory loaded from files.
@@ -1308,6 +1318,15 @@ export declare class Agent {
         tokensSaved: number;
         activeStamps: number;
     } | undefined;
+    /**
+     * Get dead message pruning statistics (errors pruned, permissions pruned, tokens saved).
+     */
+    getDeadMessagePruneStats(): {
+        prunedCount: number;
+        tokensSaved: number;
+        errorsPruned: number;
+        permissionsPruned: number;
+    } | undefined;
     /**
      * Get current verbosity level based on context pressure
      */

package/dist/agent.js

@@ -12,6 +12,7 @@ import { createFileTrackingHook } from './context/file-tracking-hook.js';
 import { ToolResultDelegator, DELEGATION_SYSTEM_PROMPT } from './context/tool-result-delegator.js';
 import { ObservationMasker } from './context/observation-masker.js';
 import { compactToolResult } from './context/result-compactor.js';
+import { DeadMessagePruner } from './context/dead-message-pruner.js';
 import { createRecallResultTool } from './tools/builtin/recall-result.js';
 import { AnchorManager } from './anchors/manager.js';
 import { GuardrailManager } from './guardrails/manager.js';
@@ -107,6 +108,10 @@ export class Agent {
      * Whether to use compact text format for tool results in LLM messages
      */
     compactToolResults;
+    /**
+     * Dead message pruner for removing superseded errors and permission exchanges
+     */
+    deadMessagePruner;
     constructor(config) {
         this.provider = config.provider;
         this.systemPrompt = config.systemPrompt ?? '';
@@ -128,6 +133,10 @@ export class Agent {
         }
         // Compact tool results: enabled by default when contextManager is provided
         this.compactToolResults = config.compactToolResults ?? this.contextManager !== undefined;
+        // Dead message pruning: enabled by default when contextManager is provided, unless explicitly false
+        if (config.deadMessagePruning !== false && this.contextManager) {
+            this.deadMessagePruner = new DeadMessagePruner(config.deadMessagePruning === undefined ? undefined : config.deadMessagePruning);
+        }
         this.onEvent = config.onEvent;
         this.onIterationLimitReached = config.onIterationLimitReached;
         // State management
@@ -769,6 +778,7 @@ export class Agent {
         this.conversationHistory = [];
         this.contextManager?.reset();
         this.observationMasker?.reset();
+        this.deadMessagePruner?.reset();
         return this;
     }
     /**
@@ -830,6 +840,12 @@ export class Agent {
     getObservationMaskStats() {
         return this.observationMasker?.getStats();
     }
+    /**
+     * Get dead message pruning statistics (errors pruned, permissions pruned, tokens saved).
+     */
+    getDeadMessagePruneStats() {
+        return this.deadMessagePruner?.getStats();
+    }
     /**
      * Get current verbosity level based on context pressure
      */
@@ -2103,6 +2119,10 @@ export class Agent {
                                 const block = toolResultMsg.content[0];
                                 this.observationMasker.stamp(toolUse.id, toolUse.name, toolUse.input, block.content.length, this.contextManager?.getTurnCount() ?? 0);
                             }
+                            // Stamp for dead message pruning
+                            if (this.deadMessagePruner) {
+                                this.deadMessagePruner.stamp(toolUse.id, toolUse.name, toolUse.input, !result.success, this.contextManager?.getTurnCount() ?? 0);
+                            }
                         }
                     }
                     else {
@@ -2142,6 +2162,10 @@ export class Agent {
                                 const block = toolResultMsg.content[0];
                                 this.observationMasker.stamp(toolUse.id, toolUse.name, toolUse.input, block.content.length, this.contextManager?.getTurnCount() ?? 0);
                             }
+                            // Stamp for dead message pruning
+                            if (this.deadMessagePruner) {
+                                this.deadMessagePruner.stamp(toolUse.id, toolUse.name, toolUse.input, !result.success, this.contextManager?.getTurnCount() ?? 0);
+                            }
                             if (skipped) {
                                 continue;
                             }
@@ -2264,6 +2288,10 @@ export class Agent {
                 if (this.observationMasker) {
                     this.observationMasker.maskHistory(messages, this.contextManager.getTurnCount());
                 }
+                // Dead message pruning: prune superseded errors and permission exchanges
+                if (this.deadMessagePruner) {
+                    this.deadMessagePruner.prune(messages, this.contextManager.getTurnCount());
+                }
                 await this.contextManager.updateTokenCount(messages);
             }
             // Update internal state tracking

package/dist/context/dead-message-pruner.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Dead Message Pruner — Phase 4 of Advanced Token Optimization
+ *
+ * Prunes provably obsolete messages in conversation history:
+ * 1. Superseded errors — tool error followed by same tool succeeding on same input
+ * 2. Permission exchanges — ask_user/ask_user_simple calls (purely procedural)
+ *
+ * Uses in-place content replacement (not message removal) to preserve
+ * the tool_use/tool_result pairing required by the Anthropic API.
+ */
+import type { Message } from '../providers/types.js';
+export interface PruneConfig {
+    /** Enable superseded error pruning (default: true) */
+    supersededErrors: boolean;
+    /** Enable permission exchange pruning (default: true) */
+    permissionExchanges: boolean;
+    /** Tool names considered permission exchanges */
+    permissionTools: string[];
+    /** Never prune messages newer than this many turns (default: 4) */
+    protectedTurns: number;
+}
+export declare const DEFAULT_PRUNE_CONFIG: PruneConfig;
+export interface PruneResult {
+    prunedCount: number;
+    tokensSaved: number;
+}
+export interface PruneStats {
+    prunedCount: number;
+    tokensSaved: number;
+    errorsPruned: number;
+    permissionsPruned: number;
+}
+/**
+ * Check if a tool result content string has been pruned.
+ */
+export declare function isPruned(content: string): boolean;
+export declare class DeadMessagePruner {
+    private readonly config;
+    private readonly stamps;
+    private stats;
+    constructor(config?: Partial<PruneConfig>);
+    /**
+     * Register a tool result for pruning analysis.
+     * Called at the same point as ObservationMasker.stamp().
+     */
+    stamp(toolUseId: string, toolName: string, input: Record<string, unknown>, isError: boolean, turn: number): void;
+    /**
+     * Prune dead messages in-place. Replaces content of dead tool_result
+     * blocks with short placeholders and clears corresponding tool_use input.
+     */
+    prune(messages: Message[], currentTurn: number): PruneResult;
+    getStats(): PruneStats;
+    /**
+     * Reset all state (stamps and stats). Used when clearing history.
+     */
+    reset(): void;
+    /**
+     * Get current configuration (for testing/inspection).
+     */
+    getConfig(): PruneConfig;
+    /**
+     * Identify tool_use IDs that should be pruned.
+     */
+    private identifyDeadMessages;
+}

package/dist/context/dead-message-pruner.js

@@ -0,0 +1,174 @@
+/**
+ * Dead Message Pruner — Phase 4 of Advanced Token Optimization
+ *
+ * Prunes provably obsolete messages in conversation history:
+ * 1. Superseded errors — tool error followed by same tool succeeding on same input
+ * 2. Permission exchanges — ask_user/ask_user_simple calls (purely procedural)
+ *
+ * Uses in-place content replacement (not message removal) to preserve
+ * the tool_use/tool_result pairing required by the Anthropic API.
+ */
+import { extractInputSummary } from './observation-masker.js';
+import { isMasked } from './observation-masker.js';
+export const DEFAULT_PRUNE_CONFIG = {
+    supersededErrors: true,
+    permissionExchanges: true,
+    permissionTools: ['ask_user', 'ask_user_simple'],
+    protectedTurns: 4,
+};
+// ============================================================
+// Pruned content detection
+// ============================================================
+const PRUNED_ERROR = '[pruned:error superseded]';
+const PRUNED_PERMISSION = '[pruned:permission]';
+/**
+ * Check if a tool result content string has been pruned.
+ */
+export function isPruned(content) {
+    return content.startsWith('[pruned:');
+}
+// ============================================================
+// DeadMessagePruner
+// ============================================================
+export class DeadMessagePruner {
+    config;
+    stamps = new Map();
+    stats = {
+        prunedCount: 0,
+        tokensSaved: 0,
+        errorsPruned: 0,
+        permissionsPruned: 0,
+    };
+    constructor(config) {
+        this.config = { ...DEFAULT_PRUNE_CONFIG, ...config };
+    }
+    // ----------------------------------------------------------
+    // Stamping — called when tool results are added to history
+    // ----------------------------------------------------------
+    /**
+     * Register a tool result for pruning analysis.
+     * Called at the same point as ObservationMasker.stamp().
+     */
+    stamp(toolUseId, toolName, input, isError, turn) {
+        this.stamps.set(toolUseId, {
+            turn,
+            toolName,
+            inputKey: extractInputSummary(toolName, input),
+            isError,
+        });
+    }
+    // ----------------------------------------------------------
+    // Pruning — called after ObservationMasker.maskHistory()
+    // ----------------------------------------------------------
+    /**
+     * Prune dead messages in-place. Replaces content of dead tool_result
+     * blocks with short placeholders and clears corresponding tool_use input.
+     */
+    prune(messages, currentTurn) {
+        // 1. Build set of tool_use IDs to prune
+        const toPrune = this.identifyDeadMessages(currentTurn);
+        if (toPrune.size === 0)
+            return { prunedCount: 0, tokensSaved: 0 };
+        // 2. Walk messages and replace content
+        let prunedCount = 0;
+        let tokensSaved = 0;
+        let errorsPruned = 0;
+        let permissionsPruned = 0;
+        for (const msg of messages) {
+            if (typeof msg.content === 'string')
+                continue;
+            for (const block of msg.content) {
+                if (block.type === 'tool_result' && toPrune.has(block.toolUseId)) {
+                    // Skip if already masked by Phase 1 or already pruned
+                    if (isMasked(block.content) || isPruned(block.content)) {
+                        toPrune.delete(block.toolUseId); // don't clear tool_use input either
+                        continue;
+                    }
+                    const stamp = this.stamps.get(block.toolUseId);
+                    if (!stamp)
+                        continue;
+                    const pruneLabel = stamp.isError ? PRUNED_ERROR : PRUNED_PERMISSION;
+                    const savedChars = block.content.length - pruneLabel.length;
+                    const savedTokens = Math.max(0, Math.ceil(savedChars / 4));
+                    block.content = pruneLabel;
+                    tokensSaved += savedTokens;
+                    prunedCount++;
+                    if (stamp.isError) {
+                        errorsPruned++;
+                    }
+                    else {
+                        permissionsPruned++;
+                    }
+                    // Clean up stamp
+                    this.stamps.delete(block.toolUseId);
+                }
+                // Clear tool_use input for pruned blocks
+                if (block.type === 'tool_use' && toPrune.has(block.id)) {
+                    const inputStr = JSON.stringify(block.input);
+                    if (inputStr.length > 2) {
+                        // Estimate savings from clearing input (subtract '{}')
+                        tokensSaved += Math.max(0, Math.ceil((inputStr.length - 2) / 4));
+                    }
+                    block.input = {};
+                }
+            }
+        }
+        this.stats.prunedCount += prunedCount;
+        this.stats.tokensSaved += tokensSaved;
+        this.stats.errorsPruned += errorsPruned;
+        this.stats.permissionsPruned += permissionsPruned;
+        return { prunedCount, tokensSaved };
+    }
+    // ----------------------------------------------------------
+    // Stats
+    // ----------------------------------------------------------
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Reset all state (stamps and stats). Used when clearing history.
+     */
+    reset() {
+        this.stamps.clear();
+        this.stats = { prunedCount: 0, tokensSaved: 0, errorsPruned: 0, permissionsPruned: 0 };
+    }
+    /**
+     * Get current configuration (for testing/inspection).
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    // ----------------------------------------------------------
+    // Internal
+    // ----------------------------------------------------------
+    /**
+     * Identify tool_use IDs that should be pruned.
+     */
+    identifyDeadMessages(currentTurn) {
+        const toPrune = new Set();
+        // Build set of successful {toolName:inputKey} pairs
+        const successKeys = new Set();
+        for (const stamp of this.stamps.values()) {
+            if (!stamp.isError) {
+                successKeys.add(`${stamp.toolName}:${stamp.inputKey}`);
+            }
+        }
+        for (const [toolUseId, stamp] of this.stamps) {
+            const age = currentTurn - stamp.turn;
+            if (age < this.config.protectedTurns)
+                continue;
+            // Rule 1: Superseded errors
+            if (this.config.supersededErrors && stamp.isError) {
+                const key = `${stamp.toolName}:${stamp.inputKey}`;
+                if (successKeys.has(key)) {
+                    toPrune.add(toolUseId);
+                }
+            }
+            // Rule 2: Permission exchanges
+            if (this.config.permissionExchanges && this.config.permissionTools.includes(stamp.toolName)) {
+                toPrune.add(toolUseId);
+            }
+        }
+        return toPrune;
+    }
+}

package/dist/context/index.d.ts

@@ -23,3 +23,5 @@ export type { DelegationConfig, StoredResult, DelegationEvent } from './delegati
 export { compactToolResult } from './result-compactor.js';
 export { ObservationMasker, DEFAULT_MASK_CONFIG, extractInputSummary, buildMaskText, isMasked, } from './observation-masker.js';
 export type { ObservationMaskConfig, MaskResult, ObservationMaskStats, } from './observation-masker.js';
+export { DeadMessagePruner, DEFAULT_PRUNE_CONFIG, isPruned } from './dead-message-pruner.js';
+export type { PruneConfig, PruneResult, PruneStats } from './dead-message-pruner.js';

package/dist/context/index.js

@@ -19,3 +19,5 @@ export { DEFAULT_DELEGATION_CONFIG } from './delegation-types.js';
 export { compactToolResult } from './result-compactor.js';
 // Observation Masking (Phase 1 Token Optimization)
 export { ObservationMasker, DEFAULT_MASK_CONFIG, extractInputSummary, buildMaskText, isMasked, } from './observation-masker.js';
+// Dead Message Pruning (Phase 4 Token Optimization)
+export { DeadMessagePruner, DEFAULT_PRUNE_CONFIG, isPruned } from './dead-message-pruner.js';

package/dist/index.d.ts

@@ -39,8 +39,8 @@ export type { ToolPairingValidation } from './messages/index.js';
 export { generateId, sleep, retry, truncate, withRetryGenerator, calculateBackoffDelay, DEFAULT_RETRY_CONFIG, countTokens, countMessageTokens, } from './utils/index.js';
 export type { RetryConfig as LLMRetryConfig, WithRetryOptions } from './utils/index.js';
 export { AgentError, ProviderError, ToolError, ToolTimeoutError, ToolLoopError, ValidationError, MaxIterationsError, AbortError, ContextOverflowError, isAgentError, isProviderError, isToolError, isToolTimeoutError, isToolLoopError, isContextOverflowError, wrapError, } from './errors.js';
-export { ContextManager, DEFAULT_CONTEXT_CONFIG, FileAccessTracker, createFileTrackingHook, TRACKED_TOOLS, DelegatedResultStore, ToolResultDelegator, DELEGATION_SYSTEM_PROMPT, DEFAULT_DELEGATION_CONFIG, compactToolResult, ObservationMasker, DEFAULT_MASK_CONFIG, extractInputSummary, buildMaskText, isMasked, } from './context/index.js';
-export type { ContextManagerOptions, ContextCategory, BudgetAllocation, CategoryBudgetInfo, PreflightResult, VerbosityLevel, VerbosityConfig, ContextConfig, FilteringConfig, CompactionConfig, SummarizationConfig, CompactionResult, SummarizationResult, FilteringResult, ContextEvent, ContextEventHandler, ContextStats, FileAccessType, FileAccess, FileAccessTrackerOptions, FormatHintsOptions, FileAccessStats, RestorationHintMessage, DelegatedResultStoreStats, ToolResultDelegatorOptions, DelegationConfig, StoredResult, DelegationEvent, ObservationMaskConfig, MaskResult, ObservationMaskStats, } from './context/index.js';
+export { ContextManager, DEFAULT_CONTEXT_CONFIG, FileAccessTracker, createFileTrackingHook, TRACKED_TOOLS, DelegatedResultStore, ToolResultDelegator, DELEGATION_SYSTEM_PROMPT, DEFAULT_DELEGATION_CONFIG, compactToolResult, ObservationMasker, DEFAULT_MASK_CONFIG, extractInputSummary, buildMaskText, isMasked, DeadMessagePruner, DEFAULT_PRUNE_CONFIG, isPruned, } from './context/index.js';
+export type { ContextManagerOptions, ContextCategory, BudgetAllocation, CategoryBudgetInfo, PreflightResult, VerbosityLevel, VerbosityConfig, ContextConfig, FilteringConfig, CompactionConfig, SummarizationConfig, CompactionResult, SummarizationResult, FilteringResult, ContextEvent, ContextEventHandler, ContextStats, FileAccessType, FileAccess, FileAccessTrackerOptions, FormatHintsOptions, FileAccessStats, RestorationHintMessage, DelegatedResultStoreStats, ToolResultDelegatorOptions, DelegationConfig, StoredResult, DelegationEvent, ObservationMaskConfig, MaskResult, ObservationMaskStats, PruneConfig, PruneResult, PruneStats, } from './context/index.js';
 export { SkillRegistry, defineSkill, createSkillRegistry, builtinSkills, getDefaultSkillRegistry, resetDefaultSkillRegistry, } from './skills/index.js';
 export type { Skill, SkillInvocationResult, SkillInvokeOptions } from './skills/index.js';
 export { JsonSerializer, CompactJsonSerializer, defaultSerializer, MemoryCheckpointer, FileCheckpointer, StateError, StateErrorCode, CURRENT_STATE_VERSION, } from './state/index.js';

package/dist/index.js

@@ -51,7 +51,9 @@ DelegatedResultStore, ToolResultDelegator, DELEGATION_SYSTEM_PROMPT, DEFAULT_DEL
 // Compact tool result formatting (Phase 2 Token Optimization)
 compactToolResult, 
 // Observation masking (Phase 1 Token Optimization)
-ObservationMasker, DEFAULT_MASK_CONFIG, extractInputSummary, buildMaskText, isMasked, } from './context/index.js';
+ObservationMasker, DEFAULT_MASK_CONFIG, extractInputSummary, buildMaskText, isMasked, 
+// Dead message pruning (Phase 4 Token Optimization)
+DeadMessagePruner, DEFAULT_PRUNE_CONFIG, isPruned, } from './context/index.js';
 // Skills system
 export { SkillRegistry, defineSkill, createSkillRegistry, builtinSkills, getDefaultSkillRegistry, resetDefaultSkillRegistry, } from './skills/index.js';
 // State management

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.3.18",
+  "version": "0.3.19",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",