@compilr-dev/agents 0.1.0 → 0.2.0

package/dist/context/manager.d.ts

@@ -18,7 +18,8 @@
  * ```
  */
 import type { Message, LLMProvider } from '../providers/types.js';
-import type { ContextConfig, ContextStats, CompactionResult, SummarizationResult, ContextEventHandler, ContextCategory, CategoryBudgetInfo, BudgetAllocation, PreflightResult, VerbosityLevel } from './types.js';
+import type { ContextConfig, ContextStats, CompactionResult, SummarizationResult, ContextEventHandler, ContextCategory, CategoryBudgetInfo, BudgetAllocation, PreflightResult, VerbosityLevel, CategorizedMessages, SmartCompactOptions, SmartCompactionResult } from './types.js';
+import type { FileAccessTracker } from './file-tracker.js';
 /**
  * Default budget allocation
  */
@@ -43,6 +44,12 @@ export interface ContextManagerOptions {
      * Event handler for context events
      */
     onEvent?: ContextEventHandler;
+    /**
+     * File access tracker for context restoration hints.
+     * When provided, compaction/summarization will inject hints
+     * about previously accessed files.
+     */
+    fileTracker?: FileAccessTracker;
 }
 /**
  * ContextManager tracks and manages context window usage
@@ -51,6 +58,7 @@ export declare class ContextManager {
     private readonly provider;
     private readonly config;
     private readonly onEvent?;
+    private readonly fileTracker?;
     private cachedTokenCount;
     private turnCount;
     private compactionCount;
@@ -110,6 +118,23 @@ export declare class ContextManager {
      * Get the current configuration
      */
     getConfig(): ContextConfig;
+    /**
+     * Get the file access tracker (if configured)
+     */
+    getFileTracker(): FileAccessTracker | undefined;
+    /**
+     * Format context restoration hints based on current verbosity level.
+     * Returns empty string if no file tracker is configured or no files have been accessed.
+     */
+    formatRestorationHints(): string;
+    /**
+     * Create a system message with context restoration hints.
+     * Returns undefined if no hints are available.
+     *
+     * The caller (Agent) is responsible for injecting this message
+     * after compaction or summarization.
+     */
+    createRestorationHintMessage(): Message | undefined;
     /**
      * Get budget information for a specific category
      */
@@ -144,6 +169,49 @@ export declare class ContextManager {
      * Determine which category a message belongs to
      */
     private categorizeMessage;
+    /**
+     * Categorize all messages by type for smart compaction
+     *
+     * This method:
+     * 1. Identifies system messages
+     * 2. Separates recent messages (last N turns) that should never be compacted
+     * 3. Identifies tool results in older messages
+     * 4. Classifies remaining older messages as history
+     *
+     * @param messages All messages to categorize
+     * @param preserveRecentTurns Number of recent turns to preserve (default: config value)
+     */
+    categorizeMessages(messages: Message[], preserveRecentTurns?: number): Promise<CategorizedMessages>;
+    /**
+     * Find which categories are over their budget allocation
+     *
+     * @param categorized Categorized messages from categorizeMessages()
+     * @returns Array of categories that exceed their budget, sorted by how much they exceed
+     */
+    findOverBudgetCategories(categorized: CategorizedMessages): ContextCategory[];
+    /**
+     * Smart compaction that respects category budgets
+     *
+     * Strategy:
+     * 1. System messages: Never compacted (critical for agent behavior)
+     * 2. Recent messages: Never compacted (needed for conversation continuity)
+     * 3. Tool results: Save large results to files, replace with references
+     * 4. History: Summarize with LLM
+     *
+     * The method compacts categories in order of how much they exceed their budget.
+     */
+    smartCompact(messages: Message[], options: SmartCompactOptions): Promise<{
+        messages: Message[];
+        result: SmartCompactionResult;
+    }>;
+    /**
+     * Compact tool results by saving large ones to files
+     */
+    private compactToolResults;
+    /**
+     * Calculate utilization given a token count
+     */
+    private calculateUtilization;
     /**
      * Estimate tokens for a string content
      */

package/dist/context/manager.js

@@ -66,6 +66,7 @@ export class ContextManager {
     provider;
     config;
     onEvent;
+    fileTracker;
     cachedTokenCount = 0;
     turnCount = 0;
     compactionCount = 0;
@@ -82,6 +83,7 @@ export class ContextManager {
         this.provider = options.provider;
         this.config = this.mergeConfig(options.config);
         this.onEvent = options.onEvent;
+        this.fileTracker = options.fileTracker;
     }
     /**
      * Merge partial config with defaults
@@ -221,6 +223,41 @@ export class ContextManager {
     getConfig() {
         return { ...this.config };
     }
+    /**
+     * Get the file access tracker (if configured)
+     */
+    getFileTracker() {
+        return this.fileTracker;
+    }
+    /**
+     * Format context restoration hints based on current verbosity level.
+     * Returns empty string if no file tracker is configured or no files have been accessed.
+     */
+    formatRestorationHints() {
+        if (!this.fileTracker || this.fileTracker.size === 0) {
+            return '';
+        }
+        return this.fileTracker.formatRestorationHints({
+            verbosityLevel: this.getVerbosityLevel(),
+        });
+    }
+    /**
+     * Create a system message with context restoration hints.
+     * Returns undefined if no hints are available.
+     *
+     * The caller (Agent) is responsible for injecting this message
+     * after compaction or summarization.
+     */
+    createRestorationHintMessage() {
+        const hints = this.formatRestorationHints();
+        if (!hints) {
+            return undefined;
+        }
+        return {
+            role: 'user',
+            content: hints,
+        };
+    }
     // ==========================================================================
     // Budget System (Novel Technique #1)
     // ==========================================================================
@@ -371,6 +408,273 @@ export class ContextManager {
         return 'recentMessages';
     }
     // ==========================================================================
+    // Smart Compaction (Phase 1)
+    // ==========================================================================
+    /**
+     * Categorize all messages by type for smart compaction
+     *
+     * This method:
+     * 1. Identifies system messages
+     * 2. Separates recent messages (last N turns) that should never be compacted
+     * 3. Identifies tool results in older messages
+     * 4. Classifies remaining older messages as history
+     *
+     * @param messages All messages to categorize
+     * @param preserveRecentTurns Number of recent turns to preserve (default: config value)
+     */
+    async categorizeMessages(messages, preserveRecentTurns) {
+        const recentTurns = preserveRecentTurns ?? this.config.compaction.preserveRecentTurns;
+        const preserveCount = recentTurns * 2; // 2 messages per turn (user + assistant)
+        const result = {
+            system: [],
+            recentMessages: [],
+            toolResults: [],
+            history: [],
+            tokenCounts: {
+                system: 0,
+                recentMessages: 0,
+                toolResults: 0,
+                history: 0,
+            },
+            originalIndices: new Map(),
+        };
+        // First pass: separate system messages and track indices
+        const nonSystemMessages = [];
+        for (let i = 0; i < messages.length; i++) {
+            const msg = messages[i];
+            result.originalIndices.set(msg, i);
+            if (msg.role === 'system') {
+                result.system.push(msg);
+            }
+            else {
+                nonSystemMessages.push(msg);
+            }
+        }
+        // Second pass: separate recent vs older messages
+        const recentStartIndex = Math.max(0, nonSystemMessages.length - preserveCount);
+        const recentMessages = nonSystemMessages.slice(recentStartIndex);
+        const olderMessages = nonSystemMessages.slice(0, recentStartIndex);
+        result.recentMessages = recentMessages;
+        // Third pass: categorize older messages
+        for (const msg of olderMessages) {
+            const category = this.categorizeMessage(msg);
+            if (category === 'toolResults') {
+                result.toolResults.push(msg);
+            }
+            else {
+                result.history.push(msg);
+            }
+        }
+        // Count tokens for each category
+        if (result.system.length > 0) {
+            result.tokenCounts.system = await this.countTokens(result.system);
+        }
+        if (result.recentMessages.length > 0) {
+            result.tokenCounts.recentMessages = await this.countTokens(result.recentMessages);
+        }
+        if (result.toolResults.length > 0) {
+            result.tokenCounts.toolResults = await this.countTokens(result.toolResults);
+        }
+        if (result.history.length > 0) {
+            result.tokenCounts.history = await this.countTokens(result.history);
+        }
+        return result;
+    }
+    /**
+     * Find which categories are over their budget allocation
+     *
+     * @param categorized Categorized messages from categorizeMessages()
+     * @returns Array of categories that exceed their budget, sorted by how much they exceed
+     */
+    findOverBudgetCategories(categorized) {
+        const overBudget = [];
+        for (const category of ['system', 'toolResults', 'history']) {
+            // Skip recentMessages - they're never compacted
+            const budget = this.getCategoryBudget(category);
+            const used = categorized.tokenCounts[category];
+            const allocated = budget.allocatedTokens;
+            if (used > allocated) {
+                overBudget.push({
+                    category,
+                    excess: used - allocated,
+                });
+            }
+        }
+        // Sort by excess (most over-budget first)
+        overBudget.sort((a, b) => b.excess - a.excess);
+        return overBudget.map((item) => item.category);
+    }
+    /**
+     * Smart compaction that respects category budgets
+     *
+     * Strategy:
+     * 1. System messages: Never compacted (critical for agent behavior)
+     * 2. Recent messages: Never compacted (needed for conversation continuity)
+     * 3. Tool results: Save large results to files, replace with references
+     * 4. History: Summarize with LLM
+     *
+     * The method compacts categories in order of how much they exceed their budget.
+     */
+    async smartCompact(messages, options) {
+        const emergency = options.emergency ?? this.needsEmergencySummarization();
+        const targetUtilization = options.targetUtilization ?? this.config.summarization.targetUtilization;
+        const preserveRecentTurns = options.preserveRecentTurns ?? this.config.compaction.preserveRecentTurns;
+        // Categorize all messages
+        const categorized = await this.categorizeMessages(messages, preserveRecentTurns);
+        const tokensBefore = categorized.tokenCounts.system +
+            categorized.tokenCounts.recentMessages +
+            categorized.tokenCounts.toolResults +
+            categorized.tokenCounts.history;
+        const filesCreated = [];
+        let fileIndex = 0;
+        let summarizationRounds = 0;
+        let summary;
+        // Initialize category stats
+        const categoryStats = {
+            system: {
+                tokensBefore: categorized.tokenCounts.system,
+                tokensAfter: categorized.tokenCounts.system,
+                action: 'preserved',
+            },
+            recentMessages: {
+                tokensBefore: categorized.tokenCounts.recentMessages,
+                tokensAfter: categorized.tokenCounts.recentMessages,
+                action: 'preserved',
+            },
+            toolResults: {
+                tokensBefore: categorized.tokenCounts.toolResults,
+                tokensAfter: categorized.tokenCounts.toolResults,
+                action: 'preserved',
+            },
+            history: {
+                tokensBefore: categorized.tokenCounts.history,
+                tokensAfter: categorized.tokenCounts.history,
+                action: 'preserved',
+            },
+        };
+        // Find which categories need compaction
+        const overBudgetCategories = this.findOverBudgetCategories(categorized);
+        // Process tool results if over budget
+        let compactedToolResults = categorized.toolResults;
+        if (overBudgetCategories.includes('toolResults') && categorized.toolResults.length > 0) {
+            const { messages: compacted, files } = await this.compactToolResults(categorized.toolResults, options.saveToFile, fileIndex);
+            compactedToolResults = compacted;
+            filesCreated.push(...files);
+            fileIndex += files.length;
+            const tokensAfter = await this.countTokens(compactedToolResults);
+            categoryStats.toolResults.tokensAfter = tokensAfter;
+            categoryStats.toolResults.action = 'compacted';
+        }
+        // Process history if over budget or if we need to reach target utilization
+        let compactedHistory = categorized.history;
+        const currentUtilization = this.calculateUtilization(categoryStats.system.tokensAfter +
+            categoryStats.recentMessages.tokensAfter +
+            categoryStats.toolResults.tokensAfter +
+            categorized.tokenCounts.history);
+        if ((overBudgetCategories.includes('history') || currentUtilization > targetUtilization) &&
+            categorized.history.length > 0) {
+            // Summarize history
+            summary = await options.generateSummary(categorized.history);
+            summarizationRounds = 1;
+            // Create summary message
+            const summaryMessage = {
+                role: 'user',
+                content: `[Previous conversation summary]\n\n${summary}\n\n[End of summary]`,
+            };
+            compactedHistory = [summaryMessage];
+            const tokensAfter = await this.countTokens(compactedHistory);
+            categoryStats.history.tokensAfter = tokensAfter;
+            categoryStats.history.action = 'summarized';
+        }
+        // Reconstruct messages in original order
+        // System messages come first, then summary (if any), then tool results, then recent
+        const finalMessages = [
+            ...categorized.system,
+            ...compactedHistory,
+            ...compactedToolResults,
+            ...categorized.recentMessages,
+        ];
+        // If history was summarized, add assistant acknowledgment after summary
+        if (categoryStats.history.action === 'summarized' && compactedHistory.length > 0) {
+            // Insert assistant acknowledgment after the summary message
+            const summaryIndex = categorized.system.length + 1; // After system + summary
+            finalMessages.splice(summaryIndex, 0, {
+                role: 'assistant',
+                content: 'I understand. I have the context from our previous conversation.',
+            });
+        }
+        const tokensAfter = await this.countTokens(finalMessages);
+        this.cachedTokenCount = tokensAfter;
+        this.compactionCount++;
+        this.lastCompactionTurn = this.turnCount;
+        const result = {
+            tokensBefore,
+            tokensAfter,
+            categoryStats,
+            filesCreated,
+            summary,
+            summarizationRounds,
+            emergency,
+        };
+        return { messages: finalMessages, result };
+    }
+    /**
+     * Compact tool results by saving large ones to files
+     */
+    async compactToolResults(messages, saveToFile, startIndex) {
+        const compactedMessages = [];
+        const files = [];
+        let fileIndex = startIndex;
+        for (const msg of messages) {
+            if (typeof msg.content === 'string') {
+                // String content - check if large enough to compact
+                const tokens = this.estimateTokens(msg.content);
+                if (tokens >= this.config.compaction.minTokensToCompact) {
+                    const filePath = await saveToFile(msg.content, fileIndex++);
+                    files.push(filePath);
+                    compactedMessages.push({
+                        ...msg,
+                        content: `[Content saved to ${filePath}]`,
+                    });
+                }
+                else {
+                    compactedMessages.push(msg);
+                }
+            }
+            else {
+                // Content blocks - compact large tool_results
+                const compactedBlocks = [];
+                for (const block of msg.content) {
+                    if (block.type === 'tool_result') {
+                        const tokens = this.estimateTokens(block.content);
+                        if (tokens >= this.config.compaction.minTokensToCompact) {
+                            const filePath = await saveToFile(block.content, fileIndex++);
+                            files.push(filePath);
+                            compactedBlocks.push({
+                                ...block,
+                                content: `[Content saved to ${filePath}]`,
+                            });
+                        }
+                        else {
+                            compactedBlocks.push(block);
+                        }
+                    }
+                    else {
+                        compactedBlocks.push(block);
+                    }
+                }
+                compactedMessages.push({ ...msg, content: compactedBlocks });
+            }
+        }
+        return { messages: compactedMessages, files };
+    }
+    /**
+     * Calculate utilization given a token count
+     */
+    calculateUtilization(tokens) {
+        return tokens / this.config.maxContextTokens;
+    }
+    // ==========================================================================
     // Pre-flight Checks (Novel Technique #2)
     // ==========================================================================
     /**

package/dist/context/types.d.ts

@@ -4,6 +4,7 @@
  * Types for managing agent context windows, including token tracking,
  * compaction, summarization, and filtering.
  */
+import type { Message } from '../providers/types.js';
 /**
  * Context categories for budget allocation
  *
@@ -342,6 +343,100 @@ export type ContextEvent = {
  * Context event handler
  */
 export type ContextEventHandler = (event: ContextEvent) => void;
+/**
+ * Categorized messages for smart compaction
+ */
+export interface CategorizedMessages {
+    /**
+     * System prompt message(s)
+     */
+    system: Message[];
+    /**
+     * Recent messages (last N turns, never compacted)
+     */
+    recentMessages: Message[];
+    /**
+     * Messages containing tool results
+     */
+    toolResults: Message[];
+    /**
+     * Older conversation history
+     */
+    history: Message[];
+    /**
+     * Token counts per category
+     */
+    tokenCounts: Record<ContextCategory, number>;
+    /**
+     * Original message indices for reconstruction
+     */
+    originalIndices: Map<Message, number>;
+}
+/**
+ * Options for smart compaction
+ */
+export interface SmartCompactOptions {
+    /**
+     * Function to generate LLM summary for history messages
+     */
+    generateSummary: (messages: Message[]) => Promise<string>;
+    /**
+     * Function to save content to a file (for tool results)
+     */
+    saveToFile: (content: string, index: number) => Promise<string>;
+    /**
+     * Number of recent turns to preserve (not compact)
+     * @default from config.compaction.preserveRecentTurns
+     */
+    preserveRecentTurns?: number;
+    /**
+     * Target utilization after compaction (0-1)
+     * @default from config.summarization.targetUtilization
+     */
+    targetUtilization?: number;
+    /**
+     * Whether to use emergency mode (more aggressive)
+     * @default auto-detect based on utilization
+     */
+    emergency?: boolean;
+}
+/**
+ * Result of smart compaction
+ */
+export interface SmartCompactionResult {
+    /**
+     * Total tokens before compaction
+     */
+    tokensBefore: number;
+    /**
+     * Total tokens after compaction
+     */
+    tokensAfter: number;
+    /**
+     * Per-category statistics
+     */
+    categoryStats: Record<ContextCategory, {
+        tokensBefore: number;
+        tokensAfter: number;
+        action: 'preserved' | 'compacted' | 'summarized';
+    }>;
+    /**
+     * Files created during tool result compaction
+     */
+    filesCreated: string[];
+    /**
+     * Generated summary (for history)
+     */
+    summary?: string;
+    /**
+     * Number of summarization rounds performed
+     */
+    summarizationRounds: number;
+    /**
+     * Whether emergency mode was used
+     */
+    emergency: boolean;
+}
 /**
  * Context statistics
  */

package/dist/index.d.ts

@@ -17,15 +17,15 @@ export { GeminiProvider, createGeminiProvider } from './providers/index.js';
 export type { GeminiProviderConfig } from './providers/index.js';
 export { OpenAICompatibleProvider } from './providers/index.js';
 export type { OpenAICompatibleConfig } from './providers/index.js';
-export type { Tool, ToolHandler, ToolRegistry, ToolInputSchema, ToolExecutionResult, ToolRegistryOptions, DefineToolOptions, ReadFileInput, WriteFileInput, BashInput, BashResult, FifoDetectionResult, GrepInput, GlobInput, EditInput, TodoWriteInput, TodoReadInput, TodoItem, TodoStatus, TodoContextCleanupOptions, TaskInput, TaskResult, AgentTypeConfig, TaskToolOptions, ContextMode, ThoroughnessLevel, SubAgentEventInfo, } from './tools/index.js';
+export type { Tool, ToolHandler, ToolRegistry, ToolInputSchema, ToolExecutionResult, ToolRegistryOptions, DefineToolOptions, ReadFileInput, WriteFileInput, BashInput, BashResult, FifoDetectionResult, GrepInput, GlobInput, EditInput, TodoWriteInput, TodoReadInput, TodoItem, TodoStatus, TodoContextCleanupOptions, TaskInput, TaskResult, AgentTypeConfig, TaskToolOptions, ContextMode, ThoroughnessLevel, SubAgentEventInfo, SuggestInput, SuggestToolOptions, } from './tools/index.js';
 export { defineTool, createSuccessResult, createErrorResult, wrapToolExecute, DefaultToolRegistry, createToolRegistry, } from './tools/index.js';
-export { readFileTool, createReadFileTool, writeFileTool, createWriteFileTool, bashTool, createBashTool, execStream, detectFifoUsage, bashOutputTool, createBashOutputTool, killShellTool, createKillShellTool, ShellManager, getDefaultShellManager, setDefaultShellManager, grepTool, createGrepTool, globTool, createGlobTool, editTool, createEditTool, todoWriteTool, todoReadTool, createTodoTools, TodoStore, resetDefaultTodoStore, getDefaultTodoStore, createIsolatedTodoStore, cleanupTodoContextMessages, getTodoContextStats, webFetchTool, createWebFetchTool, createTaskTool, defaultAgentTypes, builtinTools, allBuiltinTools, } from './tools/index.js';
-export { userMessage, assistantMessage, systemMessage, textBlock, toolUseBlock, toolResultBlock, getTextContent, getToolUses, getToolResults, hasToolUses, validateToolUseResultPairing, ensureMessageContent, normalizeMessages, } from './messages/index.js';
+export { readFileTool, createReadFileTool, writeFileTool, createWriteFileTool, bashTool, createBashTool, execStream, detectFifoUsage, bashOutputTool, createBashOutputTool, killShellTool, createKillShellTool, ShellManager, getDefaultShellManager, setDefaultShellManager, grepTool, createGrepTool, globTool, createGlobTool, editTool, createEditTool, todoWriteTool, todoReadTool, createTodoTools, TodoStore, resetDefaultTodoStore, getDefaultTodoStore, createIsolatedTodoStore, cleanupTodoContextMessages, getTodoContextStats, webFetchTool, createWebFetchTool, createTaskTool, defaultAgentTypes, suggestTool, createSuggestTool, builtinTools, allBuiltinTools, TOOL_NAMES, TOOL_SETS, } from './tools/index.js';
+export { userMessage, assistantMessage, systemMessage, textBlock, toolUseBlock, toolResultBlock, getTextContent, getToolUses, getToolResults, hasToolUses, validateToolUseResultPairing, repairToolPairing, ensureMessageContent, normalizeMessages, } from './messages/index.js';
 export type { ToolPairingValidation } from './messages/index.js';
 export { generateId, sleep, retry, truncate } 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 } from './context/index.js';
-export type { ContextManagerOptions, ContextCategory, BudgetAllocation, CategoryBudgetInfo, PreflightResult, VerbosityLevel, VerbosityConfig, ContextConfig, FilteringConfig, CompactionConfig, SummarizationConfig, CompactionResult, SummarizationResult, FilteringResult, ContextEvent, ContextEventHandler, ContextStats, } from './context/index.js';
+export { ContextManager, DEFAULT_CONTEXT_CONFIG, FileAccessTracker, createFileTrackingHook, TRACKED_TOOLS, } 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, } 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

@@ -17,15 +17,19 @@ export { defineTool, createSuccessResult, createErrorResult, wrapToolExecute, De
 // Built-in tools
 export { readFileTool, createReadFileTool, writeFileTool, createWriteFileTool, bashTool, createBashTool, execStream, detectFifoUsage, bashOutputTool, createBashOutputTool, killShellTool, createKillShellTool, ShellManager, getDefaultShellManager, setDefaultShellManager, grepTool, createGrepTool, globTool, createGlobTool, editTool, createEditTool, todoWriteTool, todoReadTool, createTodoTools, TodoStore, resetDefaultTodoStore, getDefaultTodoStore, createIsolatedTodoStore, cleanupTodoContextMessages, getTodoContextStats, webFetchTool, createWebFetchTool, 
 // Task tool (sub-agent spawning)
-createTaskTool, defaultAgentTypes, builtinTools, allBuiltinTools, } from './tools/index.js';
+createTaskTool, defaultAgentTypes, 
+// Suggest tool (next action suggestions)
+suggestTool, createSuggestTool, builtinTools, allBuiltinTools, 
+// Tool names - single source of truth
+TOOL_NAMES, TOOL_SETS, } from './tools/index.js';
 // Message utilities
-export { userMessage, assistantMessage, systemMessage, textBlock, toolUseBlock, toolResultBlock, getTextContent, getToolUses, getToolResults, hasToolUses, validateToolUseResultPairing, ensureMessageContent, normalizeMessages, } from './messages/index.js';
+export { userMessage, assistantMessage, systemMessage, textBlock, toolUseBlock, toolResultBlock, getTextContent, getToolUses, getToolResults, hasToolUses, validateToolUseResultPairing, repairToolPairing, ensureMessageContent, normalizeMessages, } from './messages/index.js';
 // Utilities
 export { generateId, sleep, retry, truncate } from './utils/index.js';
 // Errors
 export { AgentError, ProviderError, ToolError, ToolTimeoutError, ToolLoopError, ValidationError, MaxIterationsError, AbortError, ContextOverflowError, isAgentError, isProviderError, isToolError, isToolTimeoutError, isToolLoopError, isContextOverflowError, wrapError, } from './errors.js';
 // Context management
-export { ContextManager, DEFAULT_CONTEXT_CONFIG } from './context/index.js';
+export { ContextManager, DEFAULT_CONTEXT_CONFIG, FileAccessTracker, createFileTrackingHook, TRACKED_TOOLS, } from './context/index.js';
 // Skills system
 export { SkillRegistry, defineSkill, createSkillRegistry, builtinSkills, getDefaultSkillRegistry, resetDefaultSkillRegistry, } from './skills/index.js';
 // State management

package/dist/messages/index.d.ts

@@ -80,3 +80,16 @@ export declare function ensureMessageContent(message: Message | {
  * @returns Normalized messages
  */
 export declare function normalizeMessages(messages: Message[]): Message[];
+/**
+ * Repair tool use/result pairing issues in a message array.
+ *
+ * This function removes orphaned tool_result blocks (those without a matching tool_use)
+ * which can cause API errors like "function_response.name: Name cannot be empty" in Gemini.
+ *
+ * This is particularly useful after context compaction/summarization, which may remove
+ * tool_use messages while preserving tool_result messages in the "recent" window.
+ *
+ * @param messages - Array of messages to repair
+ * @returns New array with orphaned tool_results removed
+ */
+export declare function repairToolPairing(messages: Message[]): Message[];

package/dist/messages/index.js

@@ -153,3 +153,54 @@ export function ensureMessageContent(message) {
 export function normalizeMessages(messages) {
     return messages.map(ensureMessageContent);
 }
+/**
+ * Repair tool use/result pairing issues in a message array.
+ *
+ * This function removes orphaned tool_result blocks (those without a matching tool_use)
+ * which can cause API errors like "function_response.name: Name cannot be empty" in Gemini.
+ *
+ * This is particularly useful after context compaction/summarization, which may remove
+ * tool_use messages while preserving tool_result messages in the "recent" window.
+ *
+ * @param messages - Array of messages to repair
+ * @returns New array with orphaned tool_results removed
+ */
+export function repairToolPairing(messages) {
+    // First, collect all tool_use IDs
+    const toolUseIds = new Set();
+    for (const message of messages) {
+        if (typeof message.content === 'string')
+            continue;
+        for (const block of message.content) {
+            if (block.type === 'tool_use') {
+                toolUseIds.add(block.id);
+            }
+        }
+    }
+    // Now filter out orphaned tool_results
+    const repairedMessages = [];
+    for (const message of messages) {
+        if (typeof message.content === 'string') {
+            repairedMessages.push(message);
+            continue;
+        }
+        // Filter content blocks to remove orphaned tool_results
+        const filteredBlocks = message.content.filter((block) => {
+            if (block.type === 'tool_result') {
+                // Only keep if there's a matching tool_use
+                return toolUseIds.has(block.toolUseId);
+            }
+            return true;
+        });
+        // If all blocks were removed, skip this message entirely
+        if (filteredBlocks.length === 0) {
+            continue;
+        }
+        // If some blocks remain, include the message with filtered content
+        repairedMessages.push({
+            ...message,
+            content: filteredBlocks,
+        });
+    }
+    return repairedMessages;
+}

package/dist/permissions/manager.js

@@ -243,7 +243,12 @@ export class PermissionManager {
                 };
             }
             case 'once': {
-                // Always ask for permission
+                // Check if user explicitly granted session permission (via 'allow-always')
+                if (this.sessionGrants.has(toolName)) {
+                    this.emit({ type: 'permission:granted', toolName, level, input, rule });
+                    return { allowed: true, level, askedUser: false, rule };
+                }
+                // Ask for permission each time (unless session-granted above)
                 const allowed = await this.askPermission(toolName, input, level, rule);
                 if (allowed) {
                     this.emit({ type: 'permission:granted', toolName, level, input, rule });