@compilr-dev/agents 0.3.17 → 0.3.19

package/dist/agent.d.ts

@@ -15,6 +15,8 @@ import type { DelegationConfig } from './context/delegation-types.js';
 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';
@@ -278,6 +280,22 @@ export interface AgentConfig {
      * Requires contextManager to be set. Default: true when contextManager is provided.
      */
     autoContextManagement?: boolean;
+    /**
+     * Observation masking configuration. Masks old tool results in history to reduce tokens.
+     * Enabled by default when contextManager is provided. Set to `false` to disable.
+     */
+    observationMask?: Partial<ObservationMaskConfig> | false;
+    /**
+     * Use compact text format for tool results in LLM messages.
+     * Strips JSON wrappers and metadata, reducing token usage.
+     * 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
      */
@@ -878,6 +896,18 @@ export declare class Agent {
      * File restoration options for post-compaction content injection
      */
     private readonly fileRestorationConfig?;
+    /**
+     * Observation masker for reducing token usage by masking old tool results
+     */
+    private readonly observationMasker?;
+    /**
+     * 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.
@@ -1280,6 +1310,23 @@ export declare class Agent {
      * Get context statistics
      */
     getContextStats(): ContextStats | undefined;
+    /**
+     * Get observation masking statistics (tokens saved, observations masked).
+     */
+    getObservationMaskStats(): {
+        maskedCount: number;
+        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

@@ -10,6 +10,9 @@ import { ContextManager } from './context/manager.js';
 import { FileAccessTracker } from './context/file-tracker.js';
 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';
@@ -97,6 +100,18 @@ export class Agent {
      * File restoration options for post-compaction content injection
      */
     fileRestorationConfig;
+    /**
+     * Observation masker for reducing token usage by masking old tool results
+     */
+    observationMasker;
+    /**
+     * 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 ?? '';
@@ -112,6 +127,16 @@ export class Agent {
         this.contextManager = config.contextManager;
         this.autoContextManagement =
             config.autoContextManagement ?? config.contextManager !== undefined;
+        // Observation masking: enabled by default when contextManager is provided, unless explicitly false
+        if (config.observationMask !== false && this.contextManager) {
+            this.observationMasker = new ObservationMasker(config.observationMask === undefined ? undefined : config.observationMask);
+        }
+        // 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
@@ -752,6 +777,8 @@ export class Agent {
     clearHistory() {
         this.conversationHistory = [];
         this.contextManager?.reset();
+        this.observationMasker?.reset();
+        this.deadMessagePruner?.reset();
         return this;
     }
     /**
@@ -807,6 +834,18 @@ export class Agent {
     getContextStats() {
         return this.contextManager?.getStats(this.conversationHistory.length);
     }
+    /**
+     * Get observation masking statistics (tokens saved, observations masked).
+     */
+    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
      */
@@ -1915,7 +1954,9 @@ export class Agent {
                                             type: 'tool_result',
                                             toolUseId: toolUse.id,
                                             content: result.success
-                                                ? JSON.stringify(result.result)
+                                                ? this.compactToolResults
+                                                    ? compactToolResult(toolUse.name, result.result, toolUse.input)
+                                                    : JSON.stringify(result.result)
                                                 : `Error: ${result.error ?? 'Unknown error'}`,
                                             isError: !result.success,
                                         },
@@ -1998,7 +2039,9 @@ export class Agent {
                     emit({ type: 'tool_end', name: toolUse.name, result, toolUseId: toolUse.id });
                     // Build tool result content
                     let toolResultContent = result.success
-                        ? JSON.stringify(result.result)
+                        ? this.compactToolResults
+                            ? compactToolResult(toolUse.name, result.result, toolUse.input)
+                            : JSON.stringify(result.result)
                         : `Error: ${result.error ?? 'Unknown error'}`;
                     // Context management (only for sequential - parallel handles this after)
                     if (!inParallelGroup && this.contextManager && this.autoContextManagement) {
@@ -2071,6 +2114,15 @@ export class Agent {
                             iterationToolCalls.push(toolCallEntry);
                             messages.push(toolResultMsg);
                             newMessages.push(toolResultMsg);
+                            // Stamp for observation masking
+                            if (this.observationMasker) {
+                                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 {
@@ -2105,6 +2157,15 @@ export class Agent {
                             iterationToolCalls.push(toolCallEntry);
                             messages.push(toolResultMsg);
                             newMessages.push(toolResultMsg);
+                            // Stamp for observation masking
+                            if (this.observationMasker) {
+                                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;
                             }
@@ -2223,6 +2284,14 @@ export class Agent {
             // Context management: increment turn count and update token count
             if (this.contextManager) {
                 this.contextManager.incrementTurn();
+                // Observation masking: mask old tool results in-place before token update
+                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

@@ -20,3 +20,8 @@ export { ToolResultDelegator, DELEGATION_SYSTEM_PROMPT } from './tool-result-del
 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 { 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

@@ -15,3 +15,9 @@ export { createFileTrackingHook, TRACKED_TOOLS } from './file-tracking-hook.js';
 export { DelegatedResultStore } from './delegated-result-store.js';
 export { ToolResultDelegator, DELEGATION_SYSTEM_PROMPT } from './tool-result-delegator.js';
 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';
+// 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

@@ -0,0 +1,80 @@
+/**
+ * Observation Masker — Phase 1 of Advanced Token Optimization
+ *
+ * Masks old tool results (observations) in conversation history to reduce token usage.
+ * Based on JetBrains Research (Dec 2025): observation masking outperforms LLM summarization,
+ * achieving 52% cost reduction with +2.6% higher solve rates.
+ *
+ * Strategy: In-place masking of conversationHistory after N turns.
+ * The agent can re-read from the environment if needed (files, git, etc.).
+ */
+import type { Message } from '../providers/types.js';
+export interface ObservationMaskConfig {
+    /** Turns after which tool results are masked (default: 6) */
+    maskAfterTurns: number;
+    /** Minimum content length (chars) to mask — skip tiny results (default: 400 ≈ 100 tokens) */
+    minCharsToMask: number;
+    /** Tool names to NEVER mask (e.g., recall tools, state queries) */
+    neverMask: string[];
+    /** Tool names to mask after just 1 turn (large reads, bash output) */
+    alwaysMaskEarly: string[];
+}
+export declare const DEFAULT_MASK_CONFIG: ObservationMaskConfig;
+interface TurnStamp {
+    turn: number;
+    toolName: string;
+    /** Short summary of input for mask text (e.g., file path, command) */
+    inputSummary: string;
+    /** Original content length in chars */
+    contentLength: number;
+}
+export interface MaskResult {
+    maskedCount: number;
+    tokensSaved: number;
+}
+export interface ObservationMaskStats {
+    /** Total observations masked this session */
+    maskedCount: number;
+    /** Estimated tokens saved this session */
+    tokensSaved: number;
+    /** Active stamps (pending masking) */
+    activeStamps: number;
+}
+export declare class ObservationMasker {
+    private readonly stamps;
+    private readonly config;
+    private stats;
+    constructor(config?: Partial<ObservationMaskConfig>);
+    /**
+     * Register a tool result with its turn number and input context.
+     * Called immediately after a tool result is added to the messages array.
+     */
+    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.
+     */
+    maskHistory(messages: Message[], currentTurn: number): MaskResult;
+    getStats(): ObservationMaskStats;
+    /**
+     * Reset all state (stamps and stats). Used when clearing history.
+     */
+    reset(): void;
+    /**
+     * Get current configuration (for testing/inspection).
+     */
+    getConfig(): ObservationMaskConfig;
+}
+/**
+ * Extract a short summary from tool input for the mask text.
+ */
+export declare function extractInputSummary(toolName: string, input: Record<string, unknown>): string;
+/**
+ * Build the compact mask text that replaces the original content.
+ */
+export declare function buildMaskText(stamp: TurnStamp): string;
+/**
+ * Check if a tool result content string is already masked.
+ */
+export declare function isMasked(content: string): boolean;
+export {};

package/dist/context/observation-masker.js

@@ -0,0 +1,192 @@
+/**
+ * Observation Masker — Phase 1 of Advanced Token Optimization
+ *
+ * Masks old tool results (observations) in conversation history to reduce token usage.
+ * Based on JetBrains Research (Dec 2025): observation masking outperforms LLM summarization,
+ * achieving 52% cost reduction with +2.6% higher solve rates.
+ *
+ * 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_MASK_CONFIG = {
+    maskAfterTurns: 6,
+    minCharsToMask: 400,
+    neverMask: ['recall_full_result', 'recall_work'],
+    alwaysMaskEarly: ['read_file', 'bash', 'bash_output', 'grep', 'glob'],
+};
+// ============================================================
+// ObservationMasker
+// ============================================================
+export class ObservationMasker {
+    stamps = new Map();
+    config;
+    stats = { maskedCount: 0, tokensSaved: 0 };
+    constructor(config) {
+        this.config = { ...DEFAULT_MASK_CONFIG, ...config };
+    }
+    // ----------------------------------------------------------
+    // Stamping — called when tool results are added to history
+    // ----------------------------------------------------------
+    /**
+     * Register a tool result with its turn number and input context.
+     * Called immediately after a tool result is added to the messages array.
+     */
+    stamp(toolUseId, toolName, input, contentLength, turn) {
+        this.stamps.set(toolUseId, {
+            turn,
+            toolName,
+            inputSummary: extractInputSummary(toolName, input),
+            contentLength,
+        });
+    }
+    // ----------------------------------------------------------
+    // Masking — called after incrementTurn()
+    // ----------------------------------------------------------
+    /**
+     * Mask old tool results in-place in the messages array.
+     * Modifies ToolResultBlock.content directly.
+     */
+    maskHistory(messages, currentTurn) {
+        let tokensSaved = 0;
+        let maskedCount = 0;
+        for (const msg of messages) {
+            if (msg.role !== 'user' || 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);
+            }
+        }
+        this.stats.maskedCount += maskedCount;
+        this.stats.tokensSaved += tokensSaved;
+        return { maskedCount, tokensSaved };
+    }
+    // ----------------------------------------------------------
+    // Stats
+    // ----------------------------------------------------------
+    getStats() {
+        return {
+            ...this.stats,
+            activeStamps: this.stamps.size,
+        };
+    }
+    /**
+     * Reset all state (stamps and stats). Used when clearing history.
+     */
+    reset() {
+        this.stamps.clear();
+        this.stats = { maskedCount: 0, tokensSaved: 0 };
+    }
+    /**
+     * Get current configuration (for testing/inspection).
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+// ============================================================
+// Pure functions (exported for testing)
+// ============================================================
+/**
+ * Extract a short summary from tool input for the mask text.
+ */
+export function extractInputSummary(toolName, input) {
+    // File operations — use path
+    if (toolName === 'read_file' || toolName === 'edit' || toolName === 'write_file') {
+        const path = input.path ?? input.file_path;
+        if (typeof path === 'string')
+            return path;
+    }
+    // Shell commands — use command (truncated)
+    if (toolName === 'bash' || toolName === 'bash_output') {
+        const cmd = input.command;
+        if (typeof cmd === 'string') {
+            return cmd.length > 40 ? cmd.slice(0, 40) + '...' : cmd;
+        }
+    }
+    // Search — use pattern
+    if (toolName === 'grep') {
+        const pattern = input.pattern;
+        if (typeof pattern === 'string')
+            return `"${pattern}"`;
+    }
+    // Glob — use pattern
+    if (toolName === 'glob') {
+        const pattern = input.pattern;
+        if (typeof pattern === 'string')
+            return pattern;
+    }
+    // Git tools — use subcommand or operation
+    if (toolName.startsWith('git_')) {
+        return toolName.slice(4); // "git_diff" → "diff"
+    }
+    // Web fetch — use URL
+    if (toolName === 'web_fetch') {
+        const url = input.url;
+        if (typeof url === 'string') {
+            return url.length > 60 ? url.slice(0, 60) + '...' : url;
+        }
+    }
+    // Default — just the tool name
+    return toolName;
+}
+/**
+ * Build the compact mask text that replaces the original content.
+ */
+export function buildMaskText(stamp) {
+    const { toolName, inputSummary, turn, contentLength } = stamp;
+    const lines = String(Math.ceil(contentLength / 80));
+    const t = String(turn);
+    if (toolName === 'read_file') {
+        return `[file:${inputSummary} ~${lines}L read@turn:${t}]`;
+    }
+    if (toolName === 'bash' || toolName === 'bash_output') {
+        return `[cmd:${inputSummary} ~${lines}L@turn:${t}]`;
+    }
+    if (toolName === 'grep') {
+        return `[search:${inputSummary}@turn:${t}]`;
+    }
+    if (toolName === 'glob') {
+        return `[glob:${inputSummary}@turn:${t}]`;
+    }
+    if (toolName.startsWith('git_')) {
+        return `[git:${inputSummary}@turn:${t}]`;
+    }
+    if (toolName === 'edit' || toolName === 'write_file') {
+        return `[write:${inputSummary}@turn:${t}]`;
+    }
+    // Generic
+    const tokens = String(Math.ceil(contentLength / 4));
+    return `[tool:${toolName} ${tokens}tok@turn:${t}]`;
+}
+/**
+ * Check if a tool result content string is already masked.
+ */
+export function isMasked(content) {
+    return content.startsWith('[') && content.endsWith(']') && content.includes('@turn:');
+}

package/dist/context/result-compactor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Compact Tool Result Formatting — Phase 2 of Advanced Token Optimization
+ *
+ * Replaces JSON.stringify for tool results in the LLM messages array.
+ * Per-tool formatters strip JSON overhead (escaped newlines, metadata fields)
+ * and produce a text format the LLM can parse just as well.
+ *
+ * Only affects what the LLM reads in its message history.
+ * CLI formatters, events, and hooks still receive the raw ToolExecutionResult.
+ */
+/**
+ * Format a tool result as compact text for LLM context.
+ * Falls back to JSON.stringify for unknown tools or non-object results.
+ */
+export declare function compactToolResult(toolName: string, result: unknown, input?: Record<string, unknown>): string;

package/dist/context/result-compactor.js

@@ -0,0 +1,165 @@
+/**
+ * Compact Tool Result Formatting — Phase 2 of Advanced Token Optimization
+ *
+ * Replaces JSON.stringify for tool results in the LLM messages array.
+ * Per-tool formatters strip JSON overhead (escaped newlines, metadata fields)
+ * and produce a text format the LLM can parse just as well.
+ *
+ * Only affects what the LLM reads in its message history.
+ * CLI formatters, events, and hooks still receive the raw ToolExecutionResult.
+ */
+// ============================================================
+// Helpers
+// ============================================================
+/** Safely extract a string field from an unknown record. */
+function str(value, fallback = '') {
+    return typeof value === 'string' ? value : fallback;
+}
+/** Safely extract a number field from an unknown record. */
+function num(value, fallback = 0) {
+    return typeof value === 'number' ? value : fallback;
+}
+// ============================================================
+// Public API
+// ============================================================
+/**
+ * Format a tool result as compact text for LLM context.
+ * Falls back to JSON.stringify for unknown tools or non-object results.
+ */
+export function compactToolResult(toolName, result, input) {
+    // String results — already compact
+    if (typeof result === 'string')
+        return result;
+    if (result === null || result === undefined)
+        return '';
+    // Per-tool formatters
+    const formatter = TOOL_FORMATTERS.get(toolName);
+    if (formatter)
+        return formatter(result, input);
+    // Fallback: JSON.stringify (current behavior)
+    return JSON.stringify(result);
+}
+const TOOL_FORMATTERS = new Map([
+    ['read_file', formatReadFile],
+    ['bash', formatBash],
+    ['bash_output', formatBash],
+    ['grep', formatGrep],
+    ['glob', formatGlob],
+    ['edit', formatEdit],
+    ['write_file', formatWriteFile],
+]);
+/**
+ * read_file → [path 200L] + content
+ */
+function formatReadFile(r) {
+    const path = str(r.path);
+    const content = str(r.content);
+    const totalLines = typeof r.totalLines === 'number' ? r.totalLines : undefined;
+    const linesReturned = typeof r.linesReturned === 'number' ? r.linesReturned : undefined;
+    const truncated = r.truncated === true;
+    // Header: [path NL] or [path M/NL] if truncated
+    let header;
+    if (truncated && linesReturned !== undefined && totalLines !== undefined) {
+        header = `[${path} ${String(linesReturned)}/${String(totalLines)}L]`;
+    }
+    else if (totalLines !== undefined) {
+        header = `[${path} ${String(totalLines)}L]`;
+    }
+    else {
+        header = `[${path}]`;
+    }
+    return `${header}\n${content}`;
+}
+/**
+ * bash → $ command\nstdout\n[stderr]\nstderr
+ * Non-zero exit: [exit:N] $ command\n...
+ * Background: shell_id message
+ */
+function formatBash(r, input) {
+    // Background execution has different shape
+    if (r.shell_id) {
+        return `[bg:${str(r.shell_id)}] ${str(r.message)}`;
+    }
+    const stdout = str(r.stdout);
+    const stderr = str(r.stderr);
+    const exitCode = num(r.exitCode);
+    const command = input ? str(input.command) : '';
+    const parts = [];
+    // Command line
+    if (command) {
+        const prefix = exitCode !== 0 ? `[exit:${String(exitCode)}] ` : '';
+        parts.push(`${prefix}$ ${command}`);
+    }
+    else if (exitCode !== 0) {
+        parts.push(`[exit:${String(exitCode)}]`);
+    }
+    // stdout
+    if (stdout) {
+        parts.push(stdout);
+    }
+    // stderr (only if non-empty)
+    if (stderr) {
+        parts.push('[stderr]');
+        parts.push(stderr);
+    }
+    return parts.join('\n');
+}
+/**
+ * grep → N matches in M files:\n...matches
+ * Files-only mode → N files matching:\n...files
+ */
+function formatGrep(r) {
+    const count = num(r.count);
+    // Files-only mode (has `files` array)
+    if (Array.isArray(r.files)) {
+        const files = r.files;
+        if (files.length === 0)
+            return '0 files matching';
+        return `${String(count)} files matching:\n${files.join('\n')}`;
+    }
+    // Matches mode
+    const matches = Array.isArray(r.matches) ? r.matches : undefined;
+    const filesSearched = typeof r.filesSearched === 'number' ? r.filesSearched : undefined;
+    if (!matches || matches.length === 0) {
+        return filesSearched ? `0 matches in ${String(filesSearched)} files` : '0 matches';
+    }
+    const summary = filesSearched
+        ? `${String(count)} matches in ${String(filesSearched)} files:`
+        : `${String(count)} matches:`;
+    return `${summary}\n${matches.join('\n')}`;
+}
+/**
+ * glob → N files:\n...files
+ */
+function formatGlob(r) {
+    const files = Array.isArray(r.files) ? r.files : undefined;
+    const count = num(r.count);
+    if (!files || files.length === 0)
+        return '0 files';
+    return `${String(count)} files:\n${files.join('\n')}`;
+}
+/**
+ * edit → OK path (N replacements)
+ */
+function formatEdit(r) {
+    const filePath = str(r.filePath);
+    const replacements = num(r.replacements);
+    const created = r.created === true;
+    if (created) {
+        return `OK created ${filePath}`;
+    }
+    return `OK ${filePath} (${String(replacements)} replacement${replacements !== 1 ? 's' : ''})`;
+}
+/**
+ * write_file → OK wrote path (NB)
+ */
+function formatWriteFile(r) {
+    const path = str(r.path);
+    const bytesWritten = typeof r.bytesWritten === 'number' ? r.bytesWritten : undefined;
+    const mode = str(r.mode);
+    const action = mode === 'appended' ? 'appended' : 'wrote';
+    if (bytesWritten !== undefined) {
+        return `OK ${action} ${path} (${String(bytesWritten)}B)`;
+    }
+    return `OK ${action} ${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, } 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, } 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

@@ -47,7 +47,13 @@ export { AgentError, ProviderError, ToolError, ToolTimeoutError, ToolLoopError,
 // Context management
 export { ContextManager, DEFAULT_CONTEXT_CONFIG, FileAccessTracker, createFileTrackingHook, TRACKED_TOOLS, 
 // Tool result delegation
-DelegatedResultStore, ToolResultDelegator, DELEGATION_SYSTEM_PROMPT, DEFAULT_DELEGATION_CONFIG, } from './context/index.js';
+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, 
+// 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.17",
+  "version": "0.3.19",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",