@compilr-dev/agents 0.3.19 → 0.3.21

package/dist/agent.d.ts

@@ -1311,12 +1311,13 @@ 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).

package/dist/agent.js

@@ -835,7 +835,7 @@ 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();

package/dist/context/index.d.ts

@@ -21,7 +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,7 +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, 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 { 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,8 @@ 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, 
+// 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

package/dist/providers/claude.js

@@ -352,7 +352,7 @@ export class ClaudeProvider {
             return new ProviderError('Rate limit exceeded', 'claude', 429, error);
         }
         if (error instanceof Anthropic.AuthenticationError) {
-            return new ProviderError('Authentication failed: Invalid API key', 'claude', 401, error);
+            return new ProviderError(`Authentication failed: Invalid API key. (${error.message})`, 'claude', 401, error);
         }
         if (error instanceof Error) {
             return new ProviderError(error.message, 'claude', undefined, error);

package/dist/providers/fireworks.js

@@ -96,9 +96,9 @@ export class FireworksProvider extends OpenAICompatibleProvider {
         }
         switch (status) {
             case 401:
-                return new ProviderError('Invalid Fireworks AI API key. Check your FIREWORKS_API_KEY.', 'fireworks', 401);
+                return new ProviderError(`Invalid Fireworks AI API key. Check your FIREWORKS_API_KEY. (${message})`, 'fireworks', 401);
             case 403:
-                return new ProviderError('Access denied. Check your Fireworks AI API key permissions.', 'fireworks', 403);
+                return new ProviderError(`Access denied. Check your Fireworks AI API key permissions. (${message})`, 'fireworks', 403);
             case 429:
                 return new ProviderError('Fireworks AI rate limit exceeded. Please wait and try again.', 'fireworks', 429);
             case 500:

package/dist/providers/gemini.js

@@ -93,9 +93,9 @@ export class GeminiProvider extends OpenAICompatibleProvider {
             case 400:
                 return new ProviderError(`Invalid request to Gemini API: ${message}`, 'gemini', 400);
             case 401:
-                return new ProviderError('Invalid Gemini API key. Check your GOOGLE_AI_API_KEY or GEMINI_API_KEY.', 'gemini', 401);
+                return new ProviderError(`Invalid Gemini API key. Check your GOOGLE_AI_API_KEY or GEMINI_API_KEY. (${message})`, 'gemini', 401);
             case 403:
-                return new ProviderError('Access denied to Gemini API. Check your API key permissions.', 'gemini', 403);
+                return new ProviderError(`Access denied to Gemini API. Check your API key permissions. (${message})`, 'gemini', 403);
             case 429:
                 return new ProviderError('Gemini rate limit exceeded. Please wait and try again.', 'gemini', 429);
             case 500:

package/dist/providers/groq.js

@@ -81,9 +81,9 @@ export class GroqProvider extends OpenAICompatibleProvider {
         }
         switch (status) {
             case 401:
-                return new ProviderError('Invalid Groq API key. Check your GROQ_API_KEY.', 'groq', 401);
+                return new ProviderError(`Invalid Groq API key. Check your GROQ_API_KEY. (${message})`, 'groq', 401);
             case 403:
-                return new ProviderError('Access denied. Check your Groq API key permissions.', 'groq', 403);
+                return new ProviderError(`Access denied. Check your Groq API key permissions. (${message})`, 'groq', 403);
             case 429:
                 return new ProviderError('Groq rate limit exceeded. Please wait and try again.', 'groq', 429);
             case 500:

package/dist/providers/openai.js

@@ -87,9 +87,9 @@ export class OpenAIProvider extends OpenAICompatibleProvider {
         }
         switch (status) {
             case 401:
-                return new ProviderError('Invalid OpenAI API key. Check your OPENAI_API_KEY.', 'openai', 401);
+                return new ProviderError(`Invalid OpenAI API key. Check your OPENAI_API_KEY. (${message})`, 'openai', 401);
             case 403:
-                return new ProviderError('Access denied. Check your OpenAI API key permissions.', 'openai', 403);
+                return new ProviderError(`Access denied. Check your OpenAI API key permissions. (${message})`, 'openai', 403);
             case 429:
                 return new ProviderError('OpenAI rate limit exceeded. Please wait and try again.', 'openai', 429);
             case 500:

package/dist/providers/openrouter.js

@@ -94,9 +94,9 @@ export class OpenRouterProvider extends OpenAICompatibleProvider {
         }
         switch (status) {
             case 401:
-                return new ProviderError('Invalid OpenRouter API key. Check your OPENROUTER_API_KEY.', 'openrouter', 401);
+                return new ProviderError(`Invalid OpenRouter API key. Check your OPENROUTER_API_KEY. (${message})`, 'openrouter', 401);
             case 403:
-                return new ProviderError('Access denied. Check your OpenRouter API key permissions or credits.', 'openrouter', 403);
+                return new ProviderError(`Access denied. Check your OpenRouter API key permissions or credits. (${message})`, 'openrouter', 403);
             case 429:
                 return new ProviderError('OpenRouter rate limit exceeded. Please wait and try again.', 'openrouter', 429);
             case 500:

package/dist/providers/perplexity.js

@@ -81,9 +81,9 @@ export class PerplexityProvider extends OpenAICompatibleProvider {
         }
         switch (status) {
             case 401:
-                return new ProviderError('Invalid Perplexity API key. Check your PERPLEXITY_API_KEY.', 'perplexity', 401);
+                return new ProviderError(`Invalid Perplexity API key. Check your PERPLEXITY_API_KEY. (${message})`, 'perplexity', 401);
             case 403:
-                return new ProviderError('Access denied. Check your Perplexity API key permissions.', 'perplexity', 403);
+                return new ProviderError(`Access denied. Check your Perplexity API key permissions. (${message})`, 'perplexity', 403);
             case 429:
                 return new ProviderError('Perplexity rate limit exceeded. Please wait and try again.', 'perplexity', 429);
             case 500:

package/dist/providers/together.js

@@ -81,9 +81,9 @@ export class TogetherProvider extends OpenAICompatibleProvider {
         }
         switch (status) {
             case 401:
-                return new ProviderError('Invalid Together AI API key. Check your TOGETHER_API_KEY.', 'together', 401);
+                return new ProviderError(`Invalid Together AI API key. Check your TOGETHER_API_KEY. (${message})`, 'together', 401);
             case 403:
-                return new ProviderError('Access denied. Check your Together AI API key permissions.', 'together', 403);
+                return new ProviderError(`Access denied. Check your Together AI API key permissions. (${message})`, 'together', 403);
             case 429:
                 return new ProviderError('Together AI rate limit exceeded. Please wait and try again.', 'together', 429);
             case 500:

package/package.json

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