@compilr-dev/agents 0.0.1 → 0.2.0

package/dist/context/file-tracker.js

@@ -0,0 +1,358 @@
+/**
+ * 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 path from 'path';
+// ============================================================================
+// FileAccessTracker Class
+// ============================================================================
+/**
+ * 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 class FileAccessTracker {
+    accesses = new Map();
+    maxEntries;
+    deduplicateReferences;
+    constructor(options = {}) {
+        this.maxEntries = options.maxEntries ?? 100;
+        this.deduplicateReferences = options.deduplicateReferences ?? true;
+    }
+    // ==========================================================================
+    // Track Methods
+    // ==========================================================================
+    /**
+     * Track a file that was fully read
+     */
+    trackRead(filePath, lineCount, summary) {
+        const normalizedPath = this.normalizePath(filePath);
+        // Read supersedes reference - remove any existing reference
+        const existing = this.accesses.get(normalizedPath);
+        if (existing && existing.type === 'referenced') {
+            this.accesses.delete(normalizedPath);
+        }
+        // Update or create read entry
+        this.accesses.set(normalizedPath, {
+            path: normalizedPath,
+            type: 'read',
+            timestamp: Date.now(),
+            lineCount,
+            summary,
+        });
+        this.enforceMaxEntries();
+    }
+    /**
+     * Track a file that was referenced (e.g., appeared in grep/glob results)
+     */
+    trackReference(filePath) {
+        const normalizedPath = this.normalizePath(filePath);
+        // Don't downgrade read/modified to reference
+        const existing = this.accesses.get(normalizedPath);
+        if (existing && (existing.type === 'read' || existing.type === 'modified')) {
+            return;
+        }
+        // Deduplicate references
+        if (this.deduplicateReferences && existing && existing.type === 'referenced') {
+            // Update timestamp only
+            existing.timestamp = Date.now();
+            return;
+        }
+        this.accesses.set(normalizedPath, {
+            path: normalizedPath,
+            type: 'referenced',
+            timestamp: Date.now(),
+        });
+        this.enforceMaxEntries();
+    }
+    /**
+     * Track a file that was modified (written or edited)
+     */
+    trackModification(filePath, summary) {
+        const normalizedPath = this.normalizePath(filePath);
+        this.accesses.set(normalizedPath, {
+            path: normalizedPath,
+            type: 'modified',
+            timestamp: Date.now(),
+            summary,
+        });
+        this.enforceMaxEntries();
+    }
+    // ==========================================================================
+    // Query Methods
+    // ==========================================================================
+    /**
+     * Get all file accesses, optionally filtered
+     */
+    getAccesses(options) {
+        let accesses = Array.from(this.accesses.values());
+        if (options?.type) {
+            accesses = accesses.filter((a) => a.type === options.type);
+        }
+        if (options?.since !== undefined) {
+            const since = options.since;
+            accesses = accesses.filter((a) => a.timestamp >= since);
+        }
+        // Sort by timestamp descending (most recent first)
+        return accesses.sort((a, b) => b.timestamp - a.timestamp);
+    }
+    /**
+     * Get most recent file accesses
+     */
+    getRecentAccesses(limit = 10) {
+        return this.getAccesses().slice(0, limit);
+    }
+    /**
+     * Check if a file has been accessed
+     */
+    hasAccessed(filePath) {
+        return this.accesses.has(this.normalizePath(filePath));
+    }
+    /**
+     * Get access record for a specific file
+     */
+    getAccess(filePath) {
+        return this.accesses.get(this.normalizePath(filePath));
+    }
+    /**
+     * Get statistics about file accesses
+     */
+    getStats() {
+        const stats = { read: 0, referenced: 0, modified: 0, total: 0 };
+        for (const access of this.accesses.values()) {
+            stats[access.type]++;
+            stats.total++;
+        }
+        return stats;
+    }
+    // ==========================================================================
+    // Format Methods
+    // ==========================================================================
+    /**
+     * Format restoration hints for injection after compaction
+     */
+    formatRestorationHints(options = {}) {
+        const { includeLineCount = true, includeSummary = false, includeTimestamp = false, groupByType = true, maxFiles = 20, verbosityLevel = 'normal', } = options;
+        // Adjust based on verbosity
+        const effectiveMaxFiles = this.getEffectiveMaxFiles(maxFiles, verbosityLevel);
+        if (this.accesses.size === 0) {
+            return '';
+        }
+        const allAccesses = this.getAccesses();
+        // Apply limit
+        const limitedAccesses = allAccesses.slice(0, effectiveMaxFiles);
+        const hasMore = allAccesses.length > effectiveMaxFiles;
+        // Use compact format for tight context
+        if (verbosityLevel === 'minimal' || verbosityLevel === 'abbreviated') {
+            return this.formatCompact(limitedAccesses, hasMore);
+        }
+        // Full format with grouping
+        if (groupByType) {
+            return this.formatGrouped(limitedAccesses, hasMore, {
+                includeLineCount,
+                includeSummary,
+                includeTimestamp,
+            });
+        }
+        // Flat format (not grouped)
+        return this.formatFlat(limitedAccesses, hasMore, {
+            includeLineCount,
+            includeSummary,
+            includeTimestamp,
+        });
+    }
+    // ==========================================================================
+    // Lifecycle Methods
+    // ==========================================================================
+    /**
+     * Clear all tracked accesses
+     */
+    clear() {
+        this.accesses.clear();
+    }
+    /**
+     * Get the number of tracked files
+     */
+    get size() {
+        return this.accesses.size;
+    }
+    // ==========================================================================
+    // Private Helpers
+    // ==========================================================================
+    normalizePath(filePath) {
+        // Resolve to absolute path
+        return path.resolve(filePath);
+    }
+    enforceMaxEntries() {
+        if (this.accesses.size <= this.maxEntries) {
+            return;
+        }
+        // Evict oldest references first, then oldest reads
+        const sorted = this.getAccesses().reverse(); // Oldest first
+        // Separate by type for eviction priority
+        const references = sorted.filter((a) => a.type === 'referenced');
+        const reads = sorted.filter((a) => a.type === 'read');
+        const modified = sorted.filter((a) => a.type === 'modified');
+        // Build eviction order: references first, then reads, modified last
+        const evictionOrder = [...references, ...reads, ...modified];
+        // Evict until under limit
+        while (this.accesses.size > this.maxEntries && evictionOrder.length > 0) {
+            const toEvict = evictionOrder.shift();
+            if (toEvict) {
+                this.accesses.delete(toEvict.path);
+            }
+        }
+    }
+    getEffectiveMaxFiles(maxFiles, verbosityLevel) {
+        switch (verbosityLevel) {
+            case 'minimal':
+                return Math.min(maxFiles, 3);
+            case 'abbreviated':
+                return Math.min(maxFiles, 5);
+            case 'normal':
+                return Math.min(maxFiles, 10);
+            case 'full':
+            default:
+                return maxFiles;
+        }
+    }
+    formatCompact(accesses, hasMore) {
+        const byType = this.groupByType(accesses);
+        const parts = [];
+        if (byType.read.length > 0) {
+            const names = byType.read.map((a) => this.getDisplayName(a.path)).join(', ');
+            parts.push(`${names} (read)`);
+        }
+        if (byType.modified.length > 0) {
+            const names = byType.modified.map((a) => this.getDisplayName(a.path)).join(', ');
+            parts.push(`${names} (modified)`);
+        }
+        if (byType.referenced.length > 0) {
+            const count = byType.referenced.length;
+            if (count <= 2) {
+                const names = byType.referenced.map((a) => this.getDisplayName(a.path)).join(', ');
+                parts.push(`${names} (referenced)`);
+            }
+            else {
+                const first = this.getDisplayName(byType.referenced[0].path);
+                parts.push(`${first} +${String(count - 1)} more (referenced)`);
+            }
+        }
+        const moreNote = hasMore ? ' +more' : '';
+        return `[Previously accessed: ${parts.join('; ')}${moreNote}]`;
+    }
+    formatGrouped(accesses, hasMore, opts) {
+        const byType = this.groupByType(accesses);
+        const lines = ['[Context compacted. Previously accessed files:]', ''];
+        if (byType.read.length > 0) {
+            const count = byType.read.length;
+            lines.push(`Read (${String(count)} file${count > 1 ? 's' : ''}):`);
+            for (const access of byType.read) {
+                lines.push(this.formatAccessLine(access, opts));
+            }
+            lines.push('');
+        }
+        if (byType.modified.length > 0) {
+            const count = byType.modified.length;
+            lines.push(`Modified (${String(count)} file${count > 1 ? 's' : ''}):`);
+            for (const access of byType.modified) {
+                lines.push(this.formatAccessLine(access, opts));
+            }
+            lines.push('');
+        }
+        if (byType.referenced.length > 0) {
+            const count = byType.referenced.length;
+            lines.push(`Referenced (${String(count)} file${count > 1 ? 's' : ''}):`);
+            for (const access of byType.referenced) {
+                lines.push(this.formatAccessLine(access, opts));
+            }
+            lines.push('');
+        }
+        if (hasMore) {
+            lines.push('(Additional files truncated)');
+            lines.push('');
+        }
+        lines.push('[Use read_file to re-access content if needed.]');
+        return lines.join('\n');
+    }
+    formatFlat(accesses, hasMore, opts) {
+        const lines = ['[Context compacted. Previously accessed files:]', ''];
+        for (const access of accesses) {
+            const typeLabel = access.type === 'read' ? 'R' : access.type === 'modified' ? 'M' : 'ref';
+            lines.push(`  [${typeLabel}] ${this.formatAccessLine(access, opts).trim()}`);
+        }
+        if (hasMore) {
+            lines.push('');
+            lines.push('(Additional files truncated)');
+        }
+        lines.push('');
+        lines.push('[Use read_file to re-access content if needed.]');
+        return lines.join('\n');
+    }
+    formatAccessLine(access, opts) {
+        const parts = [`  • ${this.getDisplayPath(access.path)}`];
+        if (opts.includeLineCount && access.lineCount !== undefined) {
+            parts.push(`(${String(access.lineCount)} lines)`);
+        }
+        if (opts.includeSummary && access.summary) {
+            parts.push(`- ${access.summary}`);
+        }
+        if (opts.includeTimestamp) {
+            const date = new Date(access.timestamp);
+            parts.push(`@ ${date.toISOString().slice(11, 19)}`);
+        }
+        return parts.join(' ');
+    }
+    groupByType(accesses) {
+        const result = {
+            read: [],
+            referenced: [],
+            modified: [],
+        };
+        for (const access of accesses) {
+            result[access.type].push(access);
+        }
+        return result;
+    }
+    getDisplayName(filePath) {
+        return path.basename(filePath);
+    }
+    getDisplayPath(filePath) {
+        // Try to make path shorter for display
+        const cwd = process.cwd();
+        if (filePath.startsWith(cwd)) {
+            return filePath.slice(cwd.length + 1); // Remove cwd + leading slash
+        }
+        // Truncate long absolute paths
+        if (filePath.length > 60) {
+            const parts = filePath.split(path.sep);
+            if (parts.length > 4) {
+                return `...${path.sep}${parts.slice(-3).join(path.sep)}`;
+            }
+        }
+        return filePath;
+    }
+}

package/dist/context/file-tracking-hook.d.ts

@@ -0,0 +1,29 @@
+/**
+ * File Tracking Hook
+ *
+ * An afterTool hook that automatically tracks file accesses based on tool calls.
+ * This approach is cleaner than modifying each tool directly.
+ *
+ * Usage:
+ * ```typescript
+ * const tracker = new FileAccessTracker();
+ * const agent = new Agent({
+ *   hooks: {
+ *     afterTool: [createFileTrackingHook(tracker)]
+ *   }
+ * });
+ * ```
+ */
+import type { AfterToolHook } from '../hooks/types.js';
+import type { FileAccessTracker } from './file-tracker.js';
+/**
+ * Create an afterTool hook that tracks file accesses
+ *
+ * @param tracker - FileAccessTracker instance to record accesses
+ * @returns An afterTool hook function
+ */
+export declare function createFileTrackingHook(tracker: FileAccessTracker): AfterToolHook;
+/**
+ * Tool names that this hook tracks
+ */
+export declare const TRACKED_TOOLS: readonly ["read_file", "write_file", "edit", "grep", "glob"];

package/dist/context/file-tracking-hook.js

@@ -0,0 +1,103 @@
+/**
+ * File Tracking Hook
+ *
+ * An afterTool hook that automatically tracks file accesses based on tool calls.
+ * This approach is cleaner than modifying each tool directly.
+ *
+ * Usage:
+ * ```typescript
+ * const tracker = new FileAccessTracker();
+ * const agent = new Agent({
+ *   hooks: {
+ *     afterTool: [createFileTrackingHook(tracker)]
+ *   }
+ * });
+ * ```
+ */
+import { TOOL_NAMES } from '../tools/builtin/tool-names.js';
+/**
+ * Create an afterTool hook that tracks file accesses
+ *
+ * @param tracker - FileAccessTracker instance to record accesses
+ * @returns An afterTool hook function
+ */
+export function createFileTrackingHook(tracker) {
+    return (context) => {
+        const { toolName, input, result } = context;
+        // Only track successful operations
+        if (!result.success) {
+            return undefined;
+        }
+        switch (toolName) {
+            case TOOL_NAMES.READ_FILE: {
+                const readInput = input;
+                const readResult = result;
+                const lineCount = readResult.result?.lineCount ?? 0;
+                tracker.trackRead(readInput.file_path, lineCount);
+                break;
+            }
+            case TOOL_NAMES.WRITE_FILE: {
+                const writeInput = input;
+                tracker.trackModification(writeInput.file_path, 'File written');
+                break;
+            }
+            case TOOL_NAMES.EDIT: {
+                const editInput = input;
+                tracker.trackModification(editInput.file_path, 'File edited');
+                break;
+            }
+            case TOOL_NAMES.GREP: {
+                const grepInput = input;
+                const grepResult = result;
+                // Track the search path if specified
+                if (grepInput.path) {
+                    tracker.trackReference(grepInput.path);
+                }
+                // Track all files that matched
+                if (grepResult.result?.matches) {
+                    const seenFiles = new Set();
+                    for (const match of grepResult.result.matches) {
+                        if (!seenFiles.has(match.file)) {
+                            seenFiles.add(match.file);
+                            tracker.trackReference(match.file);
+                        }
+                    }
+                }
+                if (grepResult.result?.files) {
+                    for (const file of grepResult.result.files) {
+                        tracker.trackReference(file);
+                    }
+                }
+                break;
+            }
+            case TOOL_NAMES.GLOB: {
+                const globInput = input;
+                const globResult = result;
+                // Track the search path if specified
+                if (globInput.path) {
+                    tracker.trackReference(globInput.path);
+                }
+                // Track all matched files
+                if (globResult.result?.files) {
+                    for (const file of globResult.result.files) {
+                        tracker.trackReference(file);
+                    }
+                }
+                break;
+            }
+            // Note: bash tool could potentially be tracked for file operations,
+            // but it's complex to parse shell commands. Skip for now.
+        }
+        return undefined;
+    };
+}
+/**
+ * Tool names that this hook tracks
+ */
+export const TRACKED_TOOLS = [
+    TOOL_NAMES.READ_FILE,
+    TOOL_NAMES.WRITE_FILE,
+    TOOL_NAMES.EDIT,
+    TOOL_NAMES.GREP,
+    TOOL_NAMES.GLOB,
+];

package/dist/context/index.d.ts

@@ -6,7 +6,11 @@
  * - Filtering (truncate large content)
  * - Compaction (save to files, replace with references)
  * - Summarization (compress history when near limit)
+ * - File access tracking (for context restoration hints)
  */
 export { ContextManager, DEFAULT_CONTEXT_CONFIG } from './manager.js';
 export type { ContextManagerOptions } from './manager.js';
-export type { ContextCategory, BudgetAllocation, CategoryBudgetInfo, PreflightResult, VerbosityLevel, VerbosityConfig, ContextConfig, FilteringConfig, CompactionConfig, SummarizationConfig, CompactionResult, SummarizationResult, FilteringResult, ContextEvent, ContextEventHandler, ContextStats, } from './types.js';
+export { FileAccessTracker } from './file-tracker.js';
+export type { FileAccessType, FileAccess, FileAccessTrackerOptions, FormatHintsOptions, FileAccessStats, } from './file-tracker.js';
+export { createFileTrackingHook, TRACKED_TOOLS } from './file-tracking-hook.js';
+export type { ContextCategory, BudgetAllocation, CategoryBudgetInfo, PreflightResult, VerbosityLevel, VerbosityConfig, ContextConfig, FilteringConfig, CompactionConfig, SummarizationConfig, CompactionResult, SummarizationResult, FilteringResult, ContextEvent, ContextEventHandler, ContextStats, CategorizedMessages, SmartCompactOptions, SmartCompactionResult, } from './types.js';

package/dist/context/index.js

@@ -6,5 +6,8 @@
  * - Filtering (truncate large content)
  * - Compaction (save to files, replace with references)
  * - Summarization (compress history when near limit)
+ * - File access tracking (for context restoration hints)
  */
 export { ContextManager, DEFAULT_CONTEXT_CONFIG } from './manager.js';
+export { FileAccessTracker } from './file-tracker.js';
+export { createFileTrackingHook, TRACKED_TOOLS } from './file-tracking-hook.js';

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
      */