@compilr-dev/agents 0.0.1 → 0.2.0

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 });
         }
     }
@@ -684,6 +707,17 @@ export class Agent {
     getHistory() {
         return [...this.conversationHistory];
     }
+    /**
+     * Set the conversation history (for manual compaction/restoration)
+     * Also updates the context manager's token count if configured.
+     */
+    async setHistory(messages) {
+        this.conversationHistory = [...messages];
+        if (this.contextManager) {
+            await this.contextManager.updateTokenCount(messages);
+        }
+        return this;
+    }
     /**
      * Get the context manager (if configured)
      */
@@ -702,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
     // ==========================================================================
@@ -902,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
@@ -1177,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
@@ -1232,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,
@@ -1290,6 +1494,11 @@ export class Agent {
             }
             // Get tool definitions
             let tools = this.toolRegistry.getDefinitions();
+            // Apply tool filter if specified (reduces token usage)
+            if (options?.toolFilter && options.toolFilter.length > 0) {
+                const filterSet = new Set(options.toolFilter);
+                tools = tools.filter((tool) => filterSet.has(tool.name));
+            }
             // Run beforeLLM hooks (can modify messages and tools)
             if (this.hooksManager) {
                 const llmHookResult = await this.hooksManager.runBeforeLLM({
@@ -1374,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({
@@ -1434,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 });
@@ -1456,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') {
@@ -1586,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,
@@ -1596,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,
@@ -1636,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 === '') {

package/dist/context/file-tracker.d.ts

@@ -0,0 +1,156 @@
+/**
+ * File Access Tracker
+ *
+ * Tracks file accesses during agent sessions to provide context restoration
+ * hints after compaction. Inspired by Claude Code's post-compaction file
+ * reference display.
+ *
+ * Features:
+ * - Track read, referenced, and modified files
+ * - Deduplication (read supersedes reference)
+ * - Max entries with LRU eviction
+ * - Verbosity-aware formatting
+ *
+ * @see /workspace/project-docs/00-requirements/compilr-dev-agents/context-restoration-hints.md
+ */
+import type { VerbosityLevel } from './types.js';
+/**
+ * Type of file access
+ */
+export type FileAccessType = 'read' | 'referenced' | 'modified';
+/**
+ * Record of a file access
+ */
+export interface FileAccess {
+    /** Absolute file path */
+    path: string;
+    /** Type of access */
+    type: FileAccessType;
+    /** When accessed (timestamp) */
+    timestamp: number;
+    /** Number of lines (for 'read' type) */
+    lineCount?: number;
+    /** Optional summary of what was found/changed */
+    summary?: string;
+}
+/**
+ * Options for FileAccessTracker constructor
+ */
+export interface FileAccessTrackerOptions {
+    /**
+     * Maximum number of entries to track
+     * @default 100
+     */
+    maxEntries?: number;
+    /**
+     * Deduplicate references (don't track same file twice as 'referenced')
+     * @default true
+     */
+    deduplicateReferences?: boolean;
+}
+/**
+ * Options for formatting restoration hints
+ */
+export interface FormatHintsOptions {
+    /** Include line counts for read files @default true */
+    includeLineCount?: boolean;
+    /** Include summaries @default false */
+    includeSummary?: boolean;
+    /** Include timestamps @default false */
+    includeTimestamp?: boolean;
+    /** Group by access type @default true */
+    groupByType?: boolean;
+    /** Maximum files to include @default 20 */
+    maxFiles?: number;
+    /** Verbosity level (adjusts format automatically) */
+    verbosityLevel?: VerbosityLevel;
+}
+/**
+ * Statistics about file accesses
+ */
+export interface FileAccessStats {
+    read: number;
+    referenced: number;
+    modified: number;
+    total: number;
+}
+/**
+ * Tracks file accesses during agent sessions for context restoration hints.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new FileAccessTracker();
+ *
+ * // Track file accesses
+ * tracker.trackRead('/path/to/file.ts', 597);
+ * tracker.trackReference('/path/to/other.ts');
+ * tracker.trackModification('/path/to/file.ts', 'Added function');
+ *
+ * // Get restoration hints after compaction
+ * const hints = tracker.formatRestorationHints();
+ * console.log(hints);
+ * ```
+ */
+export declare class FileAccessTracker {
+    private readonly accesses;
+    private readonly maxEntries;
+    private readonly deduplicateReferences;
+    constructor(options?: FileAccessTrackerOptions);
+    /**
+     * Track a file that was fully read
+     */
+    trackRead(filePath: string, lineCount: number, summary?: string): void;
+    /**
+     * Track a file that was referenced (e.g., appeared in grep/glob results)
+     */
+    trackReference(filePath: string): void;
+    /**
+     * Track a file that was modified (written or edited)
+     */
+    trackModification(filePath: string, summary?: string): void;
+    /**
+     * Get all file accesses, optionally filtered
+     */
+    getAccesses(options?: {
+        type?: FileAccessType;
+        since?: number;
+    }): FileAccess[];
+    /**
+     * Get most recent file accesses
+     */
+    getRecentAccesses(limit?: number): FileAccess[];
+    /**
+     * Check if a file has been accessed
+     */
+    hasAccessed(filePath: string): boolean;
+    /**
+     * Get access record for a specific file
+     */
+    getAccess(filePath: string): FileAccess | undefined;
+    /**
+     * Get statistics about file accesses
+     */
+    getStats(): FileAccessStats;
+    /**
+     * Format restoration hints for injection after compaction
+     */
+    formatRestorationHints(options?: FormatHintsOptions): string;
+    /**
+     * Clear all tracked accesses
+     */
+    clear(): void;
+    /**
+     * Get the number of tracked files
+     */
+    get size(): number;
+    private normalizePath;
+    private enforceMaxEntries;
+    private getEffectiveMaxFiles;
+    private formatCompact;
+    private formatGrouped;
+    private formatFlat;
+    private formatAccessLine;
+    private groupByType;
+    private getDisplayName;
+    private getDisplayPath;
+}