@compilr-dev/agents 0.1.0 → 0.2.1

package/dist/agent.d.ts

@@ -3,7 +3,7 @@
  */
 import type { LLMProvider, Message, ChatOptions, StreamChunk } from './providers/types.js';
 import type { Tool, ToolDefinition, ToolRegistry, ToolExecutionResult } from './tools/types.js';
-import type { ContextStats, VerbosityLevel } from './context/types.js';
+import type { ContextStats, VerbosityLevel, SmartCompactionResult } from './context/types.js';
 import type { AgentState, Checkpointer, SessionMetadata } from './state/types.js';
 import type { Anchor, AnchorInput, AnchorQueryOptions, AnchorClearOptions, AnchorManagerOptions } from './anchors/types.js';
 import type { Guardrail, GuardrailInput, GuardrailResult, GuardrailManagerOptions } from './guardrails/types.js';
@@ -13,6 +13,7 @@ import type { UsageTrackerOptions, UsageStats, BudgetStatus, TokenUsage } from '
 import type { HooksConfig } from './hooks/types.js';
 import { PermissionManager } from './permissions/manager.js';
 import { ContextManager } from './context/manager.js';
+import { FileAccessTracker } from './context/file-tracker.js';
 import { AnchorManager } from './anchors/manager.js';
 import { GuardrailManager } from './guardrails/manager.js';
 /**
@@ -125,6 +126,18 @@ export type AgentEvent = {
 } | {
     type: 'usage_budget_exceeded';
     status: BudgetStatus;
+} | {
+    type: 'suggest';
+    action: string;
+    reason?: string;
+} | {
+    type: 'iteration_limit_reached';
+    iteration: number;
+    maxIterations: number;
+} | {
+    type: 'iteration_limit_extended';
+    newMaxIterations: number;
+    addedIterations: number;
 };
 /**
  * Event handler function type
@@ -189,8 +202,36 @@ export interface AgentConfig {
      * - 'error': Throw MaxIterationsError immediately
      * - 'summarize': Generate a final summary response before throwing
      * - 'continue': Return partial result without throwing (response will be empty)
+     *
+     * Note: If onIterationLimitReached callback is provided, it takes precedence.
      */
     iterationLimitBehavior?: 'error' | 'summarize' | 'continue';
+    /**
+     * Callback invoked when the agent reaches its iteration limit.
+     * Allows the caller to decide whether to continue or stop.
+     *
+     * @param context - Information about the current state
+     * @returns Promise resolving to:
+     *   - `false` to stop the agent gracefully
+     *   - A positive number to continue with that many additional iterations
+     *
+     * If this callback is provided and returns a number, the agent will continue
+     * running with the extended iteration limit. This takes precedence over
+     * iterationLimitBehavior.
+     *
+     * @example
+     * ```typescript
+     * onIterationLimitReached: async ({ iteration, toolCallCount }) => {
+     *   const answer = await askUser(`Agent used ${iteration} iterations. Continue?`);
+     *   return answer === 'yes' ? 50 : false; // Add 50 more or stop
+     * }
+     * ```
+     */
+    onIterationLimitReached?: (context: {
+        iteration: number;
+        maxIterations: number;
+        toolCallCount: number;
+    }) => Promise<number | false>;
     /**
      * Chat options (model, temperature, etc.)
      */
@@ -199,6 +240,12 @@ export interface AgentConfig {
      * Custom tool registry (optional, creates new one if not provided)
      */
     toolRegistry?: ToolRegistry;
+    /**
+     * Default timeout for tool execution in milliseconds (default: 30000 = 30s).
+     * Set to 0 to disable timeout. Only used when toolRegistry is not provided.
+     * Sub-agents inherit this timeout from the parent agent.
+     */
+    toolTimeoutMs?: number;
     /**
      * Context manager for tracking and managing context window usage.
      * If not provided, context management is disabled.
@@ -428,6 +475,31 @@ export interface AgentConfig {
      * ```
      */
     hooks?: HooksConfig;
+    /**
+     * Enable file access tracking for context restoration hints.
+     *
+     * When enabled, the agent tracks which files were read, referenced (grep/glob),
+     * and modified during execution. After context compaction, these hints are
+     * injected to help the LLM understand what files it previously accessed.
+     *
+     * Requires contextManager to be set (hints are injected after compaction).
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent({
+     *   provider,
+     *   contextManager: new ContextManager({ provider }),
+     *   enableFileTracking: true, // Automatically track file accesses
+     * });
+     *
+     * // After compaction, the agent will inject hints like:
+     * // [Context compacted. Previously accessed files:]
+     * // Read (3 files): file1.ts (100 lines), file2.ts (50 lines)...
+     * ```
+     */
+    enableFileTracking?: boolean;
 }
 /**
  * Options for a single run
@@ -631,6 +703,7 @@ export declare class Agent {
     private readonly contextManager?;
     private readonly autoContextManagement;
     private readonly onEvent?;
+    private readonly onIterationLimitReached?;
     private readonly checkpointer?;
     private readonly _sessionId;
     private readonly autoCheckpoint;
@@ -670,6 +743,10 @@ export declare class Agent {
      * Hooks manager for lifecycle hooks
      */
     private readonly hooksManager?;
+    /**
+     * File access tracker for context restoration hints
+     */
+    private readonly fileTracker?;
     constructor(config: AgentConfig);
     /**
      * Create an agent with project memory loaded from files.
@@ -1065,6 +1142,96 @@ export declare class Agent {
      * Get current verbosity level based on context pressure
      */
     getVerbosityLevel(): VerbosityLevel;
+    /**
+     * Get the file access tracker (if file tracking is enabled)
+     */
+    getFileTracker(): FileAccessTracker | undefined;
+    /**
+     * Format context restoration hints based on tracked file accesses.
+     * Returns empty string if no files have been accessed or file tracking is disabled.
+     */
+    formatRestorationHints(): string;
+    /**
+     * Inject context restoration hints into messages after compaction/summarization.
+     * Modifies messages array in place if hints are available.
+     *
+     * @internal
+     */
+    private injectRestorationHints;
+    /**
+     * Compact the conversation context to reduce token usage.
+     *
+     * This is the recommended way to trigger context compaction externally.
+     * It handles:
+     * 1. Summarizing older messages
+     * 2. Repairing tool use/result pairing (prevents API errors)
+     * 3. Injecting context restoration hints (if file tracking is enabled)
+     * 4. Updating the conversation history
+     *
+     * @param options - Compaction options
+     * @returns Compaction result with statistics
+     *
+     * @example
+     * ```typescript
+     * // Basic compaction
+     * const result = await agent.compact();
+     * console.log(`Reduced from ${result.originalTokens} to ${result.summaryTokens} tokens`);
+     *
+     * // Compaction without restoration hints
+     * await agent.compact({ injectRestorationHints: false });
+     *
+     * // Emergency compaction (more aggressive)
+     * await agent.compact({ emergency: true });
+     * ```
+     */
+    compact(options?: {
+        /**
+         * Inject file restoration hints after compaction.
+         * Only applies if file tracking is enabled.
+         * Default: true (if file tracking is enabled)
+         */
+        injectRestorationHints?: boolean;
+        /**
+         * Use emergency mode (more aggressive summarization).
+         * Default: auto-detect based on context utilization
+         */
+        emergency?: boolean;
+        /**
+         * Target utilization after compaction (0-1).
+         * Default: from context manager config (typically 0.5)
+         */
+        targetUtilization?: number;
+        /**
+         * Use smart category-aware compaction instead of simple summarization.
+         * Smart compaction:
+         * - Preserves system and recent messages completely
+         * - Saves large tool results to files
+         * - Summarizes history with LLM
+         * Default: true
+         */
+        useSmartCompaction?: boolean;
+    }): Promise<{
+        /** Whether compaction was successful */
+        success: boolean;
+        /** Original token count */
+        originalTokens: number;
+        /** Token count after compaction */
+        summaryTokens: number;
+        /** Number of summarization rounds performed */
+        rounds: number;
+        /** Number of messages preserved (not summarized) */
+        messagesPreserved: number;
+        /** Whether restoration hints were injected */
+        restorationHintsInjected: boolean;
+        /** Number of orphaned tool_results removed */
+        toolResultsRepaired: number;
+        /** The generated summary (for debugging/display) */
+        summary: string;
+        /** Files created during smart compaction (tool results saved to files) */
+        filesCreated?: string[];
+        /** Category-specific statistics (only for smart compaction) */
+        categoryStats?: SmartCompactionResult['categoryStats'];
+    }>;
     /**
      * Serialize the current agent state to an AgentState object.
      * This can be used for manual persistence or transferring state.

package/dist/agent.js

@@ -7,11 +7,14 @@ import { ProjectMemoryLoader } from './memory/loader.js';
 import { UsageTracker } from './costs/tracker.js';
 import { DefaultToolRegistry } from './tools/registry.js';
 import { ContextManager } from './context/manager.js';
+import { FileAccessTracker } from './context/file-tracker.js';
+import { createFileTrackingHook } from './context/file-tracking-hook.js';
 import { AnchorManager } from './anchors/manager.js';
 import { GuardrailManager } from './guardrails/manager.js';
 import { MaxIterationsError, ToolLoopError } from './errors.js';
 import { generateSessionId, createAgentState, deserializeTodos } from './state/agent-state.js';
 import { getDefaultTodoStore, createIsolatedTodoStore } from './tools/builtin/todo.js';
+import { repairToolPairing } from './messages/index.js';
 /**
  * Agent class - orchestrates LLM interactions with tool use
  *
@@ -40,6 +43,7 @@ export class Agent {
     contextManager;
     autoContextManagement;
     onEvent;
+    onIterationLimitReached;
     // State management
     checkpointer;
     _sessionId;
@@ -80,6 +84,10 @@ export class Agent {
      * Hooks manager for lifecycle hooks
      */
     hooksManager;
+    /**
+     * File access tracker for context restoration hints
+     */
+    fileTracker;
     constructor(config) {
         this.provider = config.provider;
         this.systemPrompt = config.systemPrompt ?? '';
@@ -87,11 +95,16 @@ export class Agent {
         this.maxConsecutiveToolCalls = config.maxConsecutiveToolCalls ?? 3;
         this.iterationLimitBehavior = config.iterationLimitBehavior ?? 'error';
         this.chatOptions = config.chatOptions ?? {};
-        this.toolRegistry = config.toolRegistry ?? new DefaultToolRegistry();
+        this.toolRegistry =
+            config.toolRegistry ??
+                new DefaultToolRegistry({
+                    defaultTimeoutMs: config.toolTimeoutMs,
+                });
         this.contextManager = config.contextManager;
         this.autoContextManagement =
             config.autoContextManagement ?? config.contextManager !== undefined;
         this.onEvent = config.onEvent;
+        this.onIterationLimitReached = config.onIterationLimitReached;
         // State management
         this.checkpointer = config.checkpointer;
         this._sessionId = config.sessionId ?? generateSessionId();
@@ -156,8 +169,18 @@ export class Agent {
                 }
             });
         }
-        // Hooks manager
-        if (config.hooks !== undefined) {
+        // File tracking for context restoration hints
+        if (config.enableFileTracking && config.contextManager) {
+            this.fileTracker = new FileAccessTracker();
+            const trackingHook = createFileTrackingHook(this.fileTracker);
+            // Merge with existing hooks or create new hooks config
+            const hooksConfig = config.hooks ?? {};
+            hooksConfig.afterTool = hooksConfig.afterTool ?? [];
+            hooksConfig.afterTool.push(trackingHook);
+            this.hooksManager = new HooksManager({ hooks: hooksConfig });
+        }
+        else if (config.hooks !== undefined) {
+            // Hooks manager without file tracking
             this.hooksManager = new HooksManager({ hooks: config.hooks });
         }
     }
@@ -713,6 +736,173 @@ export class Agent {
     getVerbosityLevel() {
         return this.contextManager?.getVerbosityLevel() ?? 'full';
     }
+    /**
+     * Get the file access tracker (if file tracking is enabled)
+     */
+    getFileTracker() {
+        return this.fileTracker;
+    }
+    /**
+     * Format context restoration hints based on tracked file accesses.
+     * Returns empty string if no files have been accessed or file tracking is disabled.
+     */
+    formatRestorationHints() {
+        return (this.fileTracker?.formatRestorationHints({
+            verbosityLevel: this.getVerbosityLevel(),
+        }) ?? '');
+    }
+    /**
+     * Inject context restoration hints into messages after compaction/summarization.
+     * Modifies messages array in place if hints are available.
+     *
+     * @internal
+     */
+    injectRestorationHints(messages) {
+        if (!this.fileTracker || this.fileTracker.size === 0) {
+            return;
+        }
+        const hints = this.formatRestorationHints();
+        if (!hints) {
+            return;
+        }
+        // Inject as a user message after the last system message
+        const systemIndex = messages.findIndex((m) => m.role === 'system');
+        const insertIndex = systemIndex >= 0 ? systemIndex + 1 : 0;
+        messages.splice(insertIndex, 0, {
+            role: 'user',
+            content: hints,
+        });
+    }
+    // ==========================================================================
+    // Context Compaction
+    // ==========================================================================
+    /**
+     * Compact the conversation context to reduce token usage.
+     *
+     * This is the recommended way to trigger context compaction externally.
+     * It handles:
+     * 1. Summarizing older messages
+     * 2. Repairing tool use/result pairing (prevents API errors)
+     * 3. Injecting context restoration hints (if file tracking is enabled)
+     * 4. Updating the conversation history
+     *
+     * @param options - Compaction options
+     * @returns Compaction result with statistics
+     *
+     * @example
+     * ```typescript
+     * // Basic compaction
+     * const result = await agent.compact();
+     * console.log(`Reduced from ${result.originalTokens} to ${result.summaryTokens} tokens`);
+     *
+     * // Compaction without restoration hints
+     * await agent.compact({ injectRestorationHints: false });
+     *
+     * // Emergency compaction (more aggressive)
+     * await agent.compact({ emergency: true });
+     * ```
+     */
+    async compact(options) {
+        // Check if context manager is available
+        if (!this.contextManager) {
+            return {
+                success: false,
+                originalTokens: 0,
+                summaryTokens: 0,
+                rounds: 0,
+                messagesPreserved: this.conversationHistory.length,
+                restorationHintsInjected: false,
+                toolResultsRepaired: 0,
+                summary: '',
+            };
+        }
+        const shouldInjectHints = options?.injectRestorationHints !== false && this.fileTracker;
+        const useSmartCompaction = options?.useSmartCompaction !== false; // Default to true
+        // Build full message list including system prompt
+        const messages = this.systemPrompt
+            ? [{ role: 'system', content: this.systemPrompt }, ...this.conversationHistory]
+            : [...this.conversationHistory];
+        let summarized;
+        let originalTokens;
+        let summaryTokens;
+        let rounds;
+        let messagesPreserved;
+        let summary;
+        let filesCreated;
+        let categoryStats;
+        if (useSmartCompaction) {
+            // Use smart category-aware compaction
+            const { messages: compactedMessages, result: smartResult } = await this.contextManager.smartCompact(messages, {
+                generateSummary: (msgs) => this.generateSummary(msgs),
+                saveToFile: async (content, index) => {
+                    // Save to a temp file and return the path
+                    const path = `/tmp/compacted-tool-result-${String(Date.now())}-${String(index)}.txt`;
+                    const { writeFile } = await import('node:fs/promises');
+                    await writeFile(path, content, 'utf-8');
+                    return path;
+                },
+                emergency: options?.emergency,
+                targetUtilization: options?.targetUtilization,
+            });
+            summarized = compactedMessages;
+            originalTokens = smartResult.tokensBefore;
+            summaryTokens = smartResult.tokensAfter;
+            rounds = smartResult.summarizationRounds;
+            summary = smartResult.summary || '';
+            filesCreated = smartResult.filesCreated;
+            categoryStats = smartResult.categoryStats;
+            // Count preserved messages (system + recent)
+            messagesPreserved = compactedMessages.filter((m) => m.role === 'system' || categoryStats?.recentMessages.action === 'preserved').length;
+        }
+        else {
+            // Use simple summarization (legacy behavior)
+            const { messages: summarizedMessages, result } = await this.contextManager.summarizeWithRetry(messages, (msgs) => this.generateSummary(msgs), {
+                emergency: options.emergency,
+                targetUtilization: options.targetUtilization,
+            });
+            summarized = summarizedMessages;
+            originalTokens = result.originalTokens;
+            summaryTokens = result.summaryTokens;
+            rounds = result.rounds;
+            messagesPreserved = result.messagesPreserved;
+            summary = result.summary;
+        }
+        // Repair tool pairing issues (fixes Gemini API errors)
+        const repaired = repairToolPairing(summarized);
+        const toolResultsRepaired = summarized.length - repaired.length;
+        // Inject restoration hints if enabled
+        let restorationHintsInjected = false;
+        if (shouldInjectHints) {
+            const sizeBefore = repaired.length;
+            this.injectRestorationHints(repaired);
+            restorationHintsInjected = repaired.length > sizeBefore;
+        }
+        // Extract new history (skip system message)
+        const newHistory = repaired.filter((m) => m.role !== 'system');
+        // Update conversation history
+        this.conversationHistory = newHistory;
+        // Update context manager's token count
+        await this.contextManager.updateTokenCount(repaired);
+        // Emit event
+        this.onEvent?.({
+            type: 'context_summarized',
+            tokensBefore: originalTokens,
+            tokensAfter: summaryTokens,
+            rounds,
+        });
+        return {
+            success: true,
+            originalTokens,
+            summaryTokens,
+            rounds,
+            messagesPreserved,
+            restorationHintsInjected,
+            toolResultsRepaired,
+            summary,
+            filesCreated,
+            categoryStats,
+        };
+    }
     // ==========================================================================
     // State Management
     // ==========================================================================
@@ -913,8 +1103,9 @@ export class Agent {
                 maxContextTokens: subAgentMaxTokens,
             },
         });
-        // Create tool registry for sub-agent
-        const subAgentToolRegistry = new DefaultToolRegistry();
+        // Create tool registry for sub-agent, inheriting timeout settings from parent
+        const parentRegistryOptions = this.toolRegistry.getOptions();
+        const subAgentToolRegistry = new DefaultToolRegistry(parentRegistryOptions);
         // If tools specified, use those; otherwise inherit from parent
         const toolsToRegister = config.tools ??
             this.toolRegistry
@@ -1188,7 +1379,7 @@ export class Agent {
      * Run the agent with a user message
      */
     async run(userMessage, options) {
-        const maxIterations = options?.maxIterations ?? this.maxIterations;
+        let maxIterations = options?.maxIterations ?? this.maxIterations;
         const chatOptions = { ...this.chatOptions, ...options?.chatOptions };
         const signal = options?.signal;
         // Combined event emitter
@@ -1243,6 +1434,8 @@ export class Agent {
                 // Perform emergency summarization
                 const { messages: summarized, result } = await this.contextManager.summarizeWithRetry(messages, (msgs) => this.generateSummary(msgs), { emergency: true });
                 messages = summarized;
+                // Inject restoration hints after summarization
+                this.injectRestorationHints(messages);
                 emit({
                     type: 'context_summarized',
                     tokensBefore: result.originalTokens,
@@ -1390,12 +1583,15 @@ export class Agent {
             // If no tool uses, we're done
             if (toolUses.length === 0) {
                 finalResponse = text;
-                // Add final assistant response to history
-                const finalAssistantMsg = {
-                    role: 'assistant',
-                    content: text,
-                };
-                newMessages.push(finalAssistantMsg);
+                // Add final assistant response to history (only if non-empty)
+                // Empty responses can occur after silent tools like 'suggest'
+                if (text) {
+                    const finalAssistantMsg = {
+                        role: 'assistant',
+                        content: text,
+                    };
+                    newMessages.push(finalAssistantMsg);
+                }
                 // Run afterIteration hooks
                 if (this.hooksManager) {
                     await this.hooksManager.runAfterIteration({
@@ -1450,11 +1646,26 @@ export class Agent {
                             success: false,
                             error: `Permission denied: ${permResult.reason ?? 'Tool execution not allowed'}`,
                         };
-                        // Skip to tool_end and continue to next tool
+                        // Emit tool_end and record the tool call
                         emit({ type: 'tool_end', name: toolUse.name, result });
                         const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
                         toolCalls.push(toolCallEntry);
                         iterationToolCalls.push(toolCallEntry);
+                        // CRITICAL: Add tool_result message to messages array
+                        // Claude API requires every tool_use to have a corresponding tool_result
+                        const toolResultMsg = {
+                            role: 'user',
+                            content: [
+                                {
+                                    type: 'tool_result',
+                                    toolUseId: toolUse.id,
+                                    content: `Error: ${result.error ?? 'Permission denied'}`,
+                                    isError: true,
+                                },
+                            ],
+                        };
+                        messages.push(toolResultMsg);
+                        newMessages.push(toolResultMsg);
                         continue;
                     }
                     emit({ type: 'permission_granted', toolName: toolUse.name, level: permResult.level });
@@ -1472,11 +1683,26 @@ export class Agent {
                                 success: false,
                                 error: `Guardrail blocked: ${message}`,
                             };
-                            // Skip to tool_end and continue to next tool
+                            // Emit tool_end and record the tool call
                             emit({ type: 'tool_end', name: toolUse.name, result });
                             const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
                             toolCalls.push(toolCallEntry);
                             iterationToolCalls.push(toolCallEntry);
+                            // CRITICAL: Add tool_result message to messages array
+                            // Claude API requires every tool_use to have a corresponding tool_result
+                            const toolResultMsg = {
+                                role: 'user',
+                                content: [
+                                    {
+                                        type: 'tool_result',
+                                        toolUseId: toolUse.id,
+                                        content: `Error: ${result.error ?? 'Blocked by guardrail'}`,
+                                        isError: true,
+                                    },
+                                ],
+                            };
+                            messages.push(toolResultMsg);
+                            newMessages.push(toolResultMsg);
                             continue;
                         }
                         else if (guardrailResult.action === 'warn') {
@@ -1602,6 +1828,8 @@ export class Agent {
                             const tokensBefore = this.contextManager.getTokenCount();
                             const compactResult = await this.contextManager.compactCategory(messages, 'toolResults', (content, index) => Promise.resolve(`[compacted_tool_result_${String(index)}]`));
                             messages = compactResult.messages;
+                            // Inject restoration hints after compaction
+                            this.injectRestorationHints(messages);
                             emit({
                                 type: 'context_compacted',
                                 tokensBefore,
@@ -1612,6 +1840,8 @@ export class Agent {
                             // Approaching context limit - summarize
                             const { messages: summarized, result: sumResult } = await this.contextManager.summarizeWithRetry(messages, (msgs) => this.generateSummary(msgs));
                             messages = summarized;
+                            // Inject restoration hints after summarization
+                            this.injectRestorationHints(messages);
                             emit({
                                 type: 'context_summarized',
                                 tokensBefore: sumResult.originalTokens,
@@ -1652,6 +1882,30 @@ export class Agent {
                 });
             }
             emit({ type: 'iteration_end', iteration: iterations });
+            // Check if we're about to hit the iteration limit
+            // If callback is defined, ask if we should continue
+            if (iterations >= maxIterations && this.onIterationLimitReached) {
+                emit({
+                    type: 'iteration_limit_reached',
+                    iteration: iterations,
+                    maxIterations,
+                });
+                const result = await this.onIterationLimitReached({
+                    iteration: iterations,
+                    maxIterations,
+                    toolCallCount: toolCalls.length,
+                });
+                if (typeof result === 'number' && result > 0) {
+                    // Extend the limit and continue
+                    maxIterations += result;
+                    emit({
+                        type: 'iteration_limit_extended',
+                        newMaxIterations: maxIterations,
+                        addedIterations: result,
+                    });
+                }
+                // If false or 0, loop will exit naturally on next condition check
+            }
         }
         // Check if we hit max iterations without completing
         if (!aborted && iterations >= maxIterations && finalResponse === '') {