@compilr-dev/agents 0.3.18 → 0.3.20

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.
@@ -1301,12 +1311,22 @@ export declare class Agent {
      */
     getContextStats(): ContextStats | undefined;
     /**
-     * Get observation masking statistics (tokens saved, observations masked).
+     * Get observation masking statistics (tokens saved, observations masked, inputs compacted).
      */
     getObservationMaskStats(): {
         maskedCount: number;
         tokensSaved: number;
         activeStamps: number;
+        inputsCompacted: 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;
     }
     /**
@@ -825,11 +835,17 @@ export class Agent {
         return this.contextManager?.getStats(this.conversationHistory.length);
     }
     /**
-     * Get observation masking statistics (tokens saved, observations masked).
+     * Get observation masking statistics (tokens saved, observations masked, inputs compacted).
      */
     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

@@ -21,5 +21,7 @@ export type { ToolResultDelegatorOptions } from './tool-result-delegator.js';
 export { DEFAULT_DELEGATION_CONFIG } from './delegation-types.js';
 export type { DelegationConfig, StoredResult, DelegationEvent } from './delegation-types.js';
 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 { ObservationMasker, DEFAULT_MASK_CONFIG, DEFAULT_INPUT_COMPACTION, extractInputSummary, buildMaskText, isMasked, } from './observation-masker.js';
+export type { InputCompactionRule, 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

@@ -17,5 +17,7 @@ export { ToolResultDelegator, DELEGATION_SYSTEM_PROMPT } from './tool-result-del
 export { DEFAULT_DELEGATION_CONFIG } from './delegation-types.js';
 // Compact Tool Result Formatting (Phase 2 Token Optimization)
 export { compactToolResult } from './result-compactor.js';
-// Observation Masking (Phase 1 Token Optimization)
-export { ObservationMasker, DEFAULT_MASK_CONFIG, extractInputSummary, buildMaskText, isMasked, } from './observation-masker.js';
+// Observation Masking (Phase 1 Token Optimization) + Tool Input Compaction (Phase 1b)
+export { ObservationMasker, DEFAULT_MASK_CONFIG, DEFAULT_INPUT_COMPACTION, 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/context/observation-masker.d.ts

@@ -9,6 +9,14 @@
  * The agent can re-read from the environment if needed (files, git, etc.).
  */
 import type { Message } from '../providers/types.js';
+/**
+ * Defines which input fields to keep when compacting a tool_use input.
+ * All other fields are removed.
+ */
+export interface InputCompactionRule {
+    /** Fields to preserve in the compacted input */
+    keepFields: string[];
+}
 export interface ObservationMaskConfig {
     /** Turns after which tool results are masked (default: 6) */
     maskAfterTurns: number;
@@ -18,7 +26,15 @@ export interface ObservationMaskConfig {
     neverMask: string[];
     /** Tool names to mask after just 1 turn (large reads, bash output) */
     alwaysMaskEarly: string[];
+    /**
+     * Tool input compaction rules (Phase 1b). Keys are tool names.
+     * After the turn threshold, large input fields are removed, keeping only the fields listed.
+     * Set to false to disable input compaction entirely.
+     * Default: compact edit (keep filePath) and write_file (keep path, mode).
+     */
+    inputCompaction: Map<string, InputCompactionRule> | false;
 }
+export declare const DEFAULT_INPUT_COMPACTION: Map<string, InputCompactionRule>;
 export declare const DEFAULT_MASK_CONFIG: ObservationMaskConfig;
 interface TurnStamp {
     turn: number;
@@ -39,6 +55,8 @@ export interface ObservationMaskStats {
     tokensSaved: number;
     /** Active stamps (pending masking) */
     activeStamps: number;
+    /** Total tool_use inputs compacted this session (Phase 1b) */
+    inputsCompacted: number;
 }
 export declare class ObservationMasker {
     private readonly stamps;
@@ -51,8 +69,9 @@ export declare class ObservationMasker {
      */
     stamp(toolUseId: string, toolName: string, input: Record<string, unknown>, contentLength: number, turn: number): void;
     /**
-     * Mask old tool results in-place in the messages array.
-     * Modifies ToolResultBlock.content directly.
+     * Mask old tool results and compact old tool_use inputs in-place.
+     * - tool_result: replaces content with compact mask text (Phase 1)
+     * - tool_use input: strips large fields, keeping only identifying fields (Phase 1b)
      */
     maskHistory(messages: Message[], currentTurn: number): MaskResult;
     getStats(): ObservationMaskStats;
@@ -64,6 +83,11 @@ export declare class ObservationMasker {
      * Get current configuration (for testing/inspection).
      */
     getConfig(): ObservationMaskConfig;
+    /**
+     * Compact a tool_use input in-place by stripping large fields.
+     * Returns estimated tokens saved (0 if no compaction performed).
+     */
+    private compactInput;
 }
 /**
  * Extract a short summary from tool input for the mask text.

package/dist/context/observation-masker.js

@@ -8,11 +8,16 @@
  * Strategy: In-place masking of conversationHistory after N turns.
  * The agent can re-read from the environment if needed (files, git, etc.).
  */
+export const DEFAULT_INPUT_COMPACTION = new Map([
+    ['edit', { keepFields: ['filePath'] }],
+    ['write_file', { keepFields: ['path', 'mode'] }],
+]);
 export const DEFAULT_MASK_CONFIG = {
     maskAfterTurns: 6,
     minCharsToMask: 400,
     neverMask: ['recall_full_result', 'recall_work'],
     alwaysMaskEarly: ['read_file', 'bash', 'bash_output', 'grep', 'glob'],
+    inputCompaction: new Map(DEFAULT_INPUT_COMPACTION),
 };
 // ============================================================
 // ObservationMasker
@@ -20,7 +25,7 @@ export const DEFAULT_MASK_CONFIG = {
 export class ObservationMasker {
     stamps = new Map();
     config;
-    stats = { maskedCount: 0, tokensSaved: 0 };
+    stats = { maskedCount: 0, tokensSaved: 0, inputsCompacted: 0 };
     constructor(config) {
         this.config = { ...DEFAULT_MASK_CONFIG, ...config };
     }
@@ -43,43 +48,59 @@ export class ObservationMasker {
     // Masking — called after incrementTurn()
     // ----------------------------------------------------------
     /**
-     * Mask old tool results in-place in the messages array.
-     * Modifies ToolResultBlock.content directly.
+     * Mask old tool results and compact old tool_use inputs in-place.
+     * - tool_result: replaces content with compact mask text (Phase 1)
+     * - tool_use input: strips large fields, keeping only identifying fields (Phase 1b)
      */
     maskHistory(messages, currentTurn) {
         let tokensSaved = 0;
         let maskedCount = 0;
         for (const msg of messages) {
-            if (msg.role !== 'user' || typeof msg.content === 'string')
+            if (typeof msg.content === 'string')
                 continue;
-            for (const block of msg.content) {
-                if (block.type !== 'tool_result')
-                    continue;
-                if (isMasked(block.content))
-                    continue;
-                const stamp = this.stamps.get(block.toolUseId);
-                if (!stamp)
-                    continue;
-                if (this.config.neverMask.includes(stamp.toolName))
-                    continue;
-                const age = currentTurn - stamp.turn;
-                const threshold = this.config.alwaysMaskEarly.includes(stamp.toolName)
-                    ? 1
-                    : this.config.maskAfterTurns;
-                if (age < threshold)
-                    continue;
-                if (stamp.contentLength < this.config.minCharsToMask)
-                    continue;
-                // Build mask and calculate savings
-                const maskText = buildMaskText(stamp);
-                const savedChars = stamp.contentLength - maskText.length;
-                const savedTokens = Math.max(0, Math.ceil(savedChars / 4));
-                // Mask in-place
-                block.content = maskText;
-                tokensSaved += savedTokens;
-                maskedCount++;
-                // Clean up stamp
-                this.stamps.delete(block.toolUseId);
+            // Phase 1: Mask old tool_result content in user messages
+            if (msg.role === 'user') {
+                for (const block of msg.content) {
+                    if (block.type !== 'tool_result')
+                        continue;
+                    if (isMasked(block.content))
+                        continue;
+                    const stamp = this.stamps.get(block.toolUseId);
+                    if (!stamp)
+                        continue;
+                    if (this.config.neverMask.includes(stamp.toolName))
+                        continue;
+                    const age = currentTurn - stamp.turn;
+                    const threshold = this.config.alwaysMaskEarly.includes(stamp.toolName)
+                        ? 1
+                        : this.config.maskAfterTurns;
+                    if (age < threshold)
+                        continue;
+                    if (stamp.contentLength < this.config.minCharsToMask)
+                        continue;
+                    // Build mask and calculate savings
+                    const maskText = buildMaskText(stamp);
+                    const savedChars = stamp.contentLength - maskText.length;
+                    const savedTokens = Math.max(0, Math.ceil(savedChars / 4));
+                    // Mask in-place
+                    block.content = maskText;
+                    tokensSaved += savedTokens;
+                    maskedCount++;
+                    // Clean up stamp
+                    this.stamps.delete(block.toolUseId);
+                }
+            }
+            // Phase 1b: Compact old tool_use inputs in assistant messages
+            if (msg.role === 'assistant') {
+                for (const block of msg.content) {
+                    if (block.type !== 'tool_use')
+                        continue;
+                    const saved = this.compactInput(block, currentTurn);
+                    if (saved > 0) {
+                        tokensSaved += saved;
+                        this.stats.inputsCompacted++;
+                    }
+                }
             }
         }
         this.stats.maskedCount += maskedCount;
@@ -100,7 +121,7 @@ export class ObservationMasker {
      */
     reset() {
         this.stamps.clear();
-        this.stats = { maskedCount: 0, tokensSaved: 0 };
+        this.stats = { maskedCount: 0, tokensSaved: 0, inputsCompacted: 0 };
     }
     /**
      * Get current configuration (for testing/inspection).
@@ -108,6 +129,47 @@ export class ObservationMasker {
     getConfig() {
         return { ...this.config };
     }
+    // ----------------------------------------------------------
+    // Phase 1b: Tool input compaction
+    // ----------------------------------------------------------
+    /**
+     * Compact a tool_use input in-place by stripping large fields.
+     * Returns estimated tokens saved (0 if no compaction performed).
+     */
+    compactInput(block, currentTurn) {
+        if (this.config.inputCompaction === false)
+            return 0;
+        const rule = this.config.inputCompaction.get(block.name);
+        if (!rule)
+            return 0;
+        const stamp = this.stamps.get(block.id);
+        if (!stamp)
+            return 0;
+        const age = currentTurn - stamp.turn;
+        const threshold = this.config.alwaysMaskEarly.includes(stamp.toolName)
+            ? 1
+            : this.config.maskAfterTurns;
+        if (age < threshold)
+            return 0;
+        // Check if there are any fields to remove
+        const fieldKeys = Object.keys(block.input);
+        const removableKeys = fieldKeys.filter((k) => !rule.keepFields.includes(k));
+        if (removableKeys.length === 0)
+            return 0;
+        // Estimate tokens before compaction
+        const beforeChars = JSON.stringify(block.input).length;
+        // Build compacted input with only kept fields
+        const compacted = {};
+        for (const field of rule.keepFields) {
+            if (field in block.input) {
+                compacted[field] = block.input[field];
+            }
+        }
+        block.input = compacted;
+        // Estimate tokens saved
+        const afterChars = JSON.stringify(compacted).length;
+        return Math.max(0, Math.ceil((beforeChars - afterChars) / 4));
+    }
 }
 // ============================================================
 // Pure functions (exported for testing)
@@ -116,9 +178,9 @@ export class ObservationMasker {
  * Extract a short summary from tool input for the mask text.
  */
 export function extractInputSummary(toolName, input) {
-    // File operations — use path
+    // File operations — use path (supports path, file_path, and filePath conventions)
     if (toolName === 'read_file' || toolName === 'edit' || toolName === 'write_file') {
-        const path = input.path ?? input.file_path;
+        const path = input.path ?? input.file_path ?? input.filePath;
         if (typeof path === 'string')
             return path;
     }

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, DEFAULT_INPUT_COMPACTION, 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, InputCompactionRule, 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

@@ -50,8 +50,10 @@ export { ContextManager, DEFAULT_CONTEXT_CONFIG, FileAccessTracker, createFileTr
 DelegatedResultStore, ToolResultDelegator, DELEGATION_SYSTEM_PROMPT, DEFAULT_DELEGATION_CONFIG, 
 // 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';
+// Observation masking (Phase 1 Token Optimization) + Tool Input Compaction (Phase 1b)
+ObservationMasker, DEFAULT_MASK_CONFIG, DEFAULT_INPUT_COMPACTION, 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.20",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",