@compilr-dev/agents 0.3.11 → 0.3.13

package/dist/agent.d.ts

@@ -11,6 +11,7 @@ import type { ToolPermission, PermissionLevel, PermissionManagerOptions } from '
 import type { ProjectMemoryOptions, ProjectMemory } from './memory/types.js';
 import type { UsageTrackerOptions, UsageStats, BudgetStatus, TokenUsage } from './costs/types.js';
 import type { HooksConfig } from './hooks/types.js';
+import type { DelegationConfig } from './context/delegation-types.js';
 import { PermissionManager } from './permissions/manager.js';
 import { ContextManager } from './context/manager.js';
 import { FileAccessTracker } from './context/file-tracker.js';
@@ -528,6 +529,28 @@ export interface AgentConfig {
      * ```
      */
     hooks?: HooksConfig;
+    /**
+     * Tool result delegation config. When set and enabled, large tool results
+     * are automatically summarized to conserve context tokens. Full results are
+     * stored in-memory for optional recall via `recall_full_result`.
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent({
+     *   provider,
+     *   delegation: {
+     *     enabled: true,
+     *     delegationThreshold: 8000, // tokens above which to delegate
+     *     strategy: 'auto',         // try LLM, fall back to extractive
+     *     toolOverrides: {
+     *       bash: { threshold: 12000 },
+     *       grep: { threshold: 4000 },
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    delegation?: DelegationConfig;
     /**
      * Enable file access tracking for context restoration hints.
      *
@@ -553,6 +576,19 @@ export interface AgentConfig {
      * ```
      */
     enableFileTracking?: boolean;
+    /**
+     * Options for file context restoration after compaction.
+     *
+     * Controls how file contents are re-injected into the context after
+     * compaction. Small files get their content inlined; large files get
+     * reference-only hints.
+     *
+     * Only applies when `enableFileTracking` is true.
+     */
+    fileRestoration?: {
+        /** Max total tokens for inline file content after compaction (default: 4000) */
+        maxInlineTokens?: number;
+    };
 }
 /**
  * Options for a single run
@@ -838,6 +874,10 @@ export declare class Agent {
      * File access tracker for context restoration hints
      */
     private readonly fileTracker?;
+    /**
+     * File restoration options for post-compaction content injection
+     */
+    private readonly fileRestorationConfig?;
     constructor(config: AgentConfig);
     /**
      * Create an agent with project memory loaded from files.
@@ -1255,7 +1295,8 @@ export declare class Agent {
     formatRestorationHints(): string;
     /**
      * Inject context restoration hints into messages after compaction/summarization.
-     * Modifies messages array in place if hints are available.
+     * Uses content-aware format: small files get content inlined, large files get
+     * reference-only notes. Each file is injected as a separate user message.
      *
      * @internal
      */

package/dist/agent.js

@@ -9,6 +9,8 @@ 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 { ToolResultDelegator, DELEGATION_SYSTEM_PROMPT } from './context/tool-result-delegator.js';
+import { createRecallResultTool } from './tools/builtin/recall-result.js';
 import { AnchorManager } from './anchors/manager.js';
 import { GuardrailManager } from './guardrails/manager.js';
 import { MaxIterationsError, ToolLoopError, ProviderError } from './errors.js';
@@ -91,6 +93,10 @@ export class Agent {
      * File access tracker for context restoration hints
      */
     fileTracker;
+    /**
+     * File restoration options for post-compaction content injection
+     */
+    fileRestorationConfig;
     constructor(config) {
         this.provider = config.provider;
         this.systemPrompt = config.systemPrompt ?? '';
@@ -177,19 +183,51 @@ export class Agent {
                 }
             });
         }
+        // Build hooks config (may be extended by file tracking and delegation)
+        const hooksConfig = config.hooks ? { ...config.hooks } : {};
+        let needsHooksManager = config.hooks !== undefined;
+        // Tool result delegation — auto-summarize large results
+        if (config.delegation?.enabled) {
+            const delegator = new ToolResultDelegator({
+                provider: config.provider,
+                config: config.delegation,
+                onEvent: (event) => {
+                    this.onEvent?.({
+                        type: 'custom',
+                        name: event.type,
+                        data: event,
+                    });
+                },
+            });
+            hooksConfig.afterTool = hooksConfig.afterTool ?? [];
+            hooksConfig.afterTool.push(delegator.createHook());
+            needsHooksManager = true;
+            // Register recall_full_result tool
+            this.registerTool(createRecallResultTool({
+                store: delegator.getStore(),
+                onEvent: (event) => {
+                    this.onEvent?.({
+                        type: 'custom',
+                        name: event.type,
+                        data: event,
+                    });
+                },
+            }));
+            // Append delegation instructions to system prompt
+            this.systemPrompt += DELEGATION_SYSTEM_PROMPT;
+        }
         // File tracking for context restoration hints
         if (config.enableFileTracking && config.contextManager) {
             this.fileTracker = new FileAccessTracker();
+            this.fileRestorationConfig = config.fileRestoration;
             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 });
+            needsHooksManager = true;
         }
-        else if (config.hooks !== undefined) {
-            // Hooks manager without file tracking
-            this.hooksManager = new HooksManager({ hooks: config.hooks });
+        // Create hooks manager if any hooks were configured
+        if (needsHooksManager) {
+            this.hooksManager = new HooksManager({ hooks: hooksConfig });
         }
         // Retry configuration with defaults
         this.retryConfig = {
@@ -792,7 +830,8 @@ export class Agent {
     }
     /**
      * Inject context restoration hints into messages after compaction/summarization.
-     * Modifies messages array in place if hints are available.
+     * Uses content-aware format: small files get content inlined, large files get
+     * reference-only notes. Each file is injected as a separate user message.
      *
      * @internal
      */
@@ -800,17 +839,22 @@ export class Agent {
         if (!this.fileTracker || this.fileTracker.size === 0) {
             return;
         }
-        const hints = this.formatRestorationHints();
-        if (!hints) {
+        const hints = this.fileTracker.formatRestorationHintsWithContent({
+            maxInlineTokens: this.fileRestorationConfig?.maxInlineTokens ?? 4000,
+        });
+        if (hints.length === 0) {
             return;
         }
-        // Inject as a user message after the last system message
+        // Insert after system prompt, each as a separate user message
         const systemIndex = messages.findIndex((m) => m.role === 'system');
         const insertIndex = systemIndex >= 0 ? systemIndex + 1 : 0;
-        messages.splice(insertIndex, 0, {
-            role: 'user',
-            content: hints,
-        });
+        // Insert in reverse order so they end up in the correct order
+        for (let i = hints.length - 1; i >= 0; i--) {
+            messages.splice(insertIndex, 0, {
+                role: 'user',
+                content: hints[i].text,
+            });
+        }
     }
     // ==========================================================================
     // Context Compaction
@@ -1499,6 +1543,7 @@ export class Agent {
                 this.contextManager.updateCategoryUsage('system', systemTokens);
             }
             // Check if we need to manage context before starting
+            // Order: emergency (95%) → compaction (50%/20 turns) → warning (90%)
             if (this.contextManager.needsEmergencySummarization()) {
                 emit({
                     type: 'context_warning',
@@ -1517,6 +1562,27 @@ export class Agent {
                     rounds: result.rounds,
                 });
             }
+            else if (this.contextManager.needsCompaction()) {
+                // Proactive compaction (50% utilization or 20+ turns since last compaction)
+                // compact() reads this.conversationHistory which has all previous runs' messages
+                const compactResult = await this.compact({ useSmartCompaction: true });
+                if (compactResult.success) {
+                    // Rebuild messages: compacted history + current userMsg (still in newMessages)
+                    messages = this.systemPrompt
+                        ? [
+                            { role: 'system', content: this.systemPrompt },
+                            ...this.conversationHistory,
+                            ...newMessages,
+                        ]
+                        : [...this.conversationHistory, ...newMessages];
+                    // Don't touch newMessages — it still has [userMsg] which finally needs to append
+                    emit({
+                        type: 'context_compacted',
+                        tokensBefore: compactResult.originalTokens,
+                        tokensAfter: compactResult.summaryTokens,
+                    });
+                }
+            }
             else if (this.contextManager.needsSummarization()) {
                 emit({
                     type: 'context_warning',
@@ -2044,6 +2110,36 @@ export class Agent {
                         completedWithText: false,
                     });
                 }
+                // Auto-compaction: check if context needs compaction after this iteration
+                if (this.contextManager && this.autoContextManagement) {
+                    await this.contextManager.updateTokenCount(messages);
+                    if (this.contextManager.needsCompaction()) {
+                        // Flush current run's messages to conversationHistory so compact() can see them.
+                        // compact() reads this.conversationHistory, which normally only updates in finally.
+                        this.conversationHistory.push(...newMessages);
+                        newMessages.length = 0;
+                        const compactResult = await this.compact({ useSmartCompaction: true });
+                        if (compactResult.success) {
+                            // compact() already replaced this.conversationHistory with compacted version.
+                            // Rebuild local messages array from it.
+                            messages = this.systemPrompt
+                                ? [
+                                    { role: 'system', content: this.systemPrompt },
+                                    ...this.conversationHistory,
+                                ]
+                                : [...this.conversationHistory];
+                            // newMessages stays empty — subsequent iterations will push new messages into it,
+                            // and finally block will correctly append only post-compaction messages.
+                            emit({
+                                type: 'context_compacted',
+                                tokensBefore: compactResult.originalTokens,
+                                tokensAfter: compactResult.summaryTokens,
+                            });
+                        }
+                        // If compact() failed, messages are already flushed to conversationHistory.
+                        // newMessages is empty so finally won't double-push.
+                    }
+                }
                 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
@@ -2098,7 +2194,8 @@ export class Agent {
                     throw new MaxIterationsError(maxIterations);
                 }
             }
-            if (!aborted && !(iterations >= maxIterations && this.iterationLimitBehavior === 'summarize')) {
+            if (!aborted &&
+                !(iterations >= maxIterations && this.iterationLimitBehavior === 'summarize')) {
                 emit({ type: 'done', response: finalResponse });
             }
         }
@@ -2268,13 +2365,15 @@ export class Agent {
      * @param signal - Optional abort signal
      */
     chatWithRetry(messages, options, emit, signal) {
+        // Merge signal into chat options so providers can abort the request
+        const chatOptions = signal ? { ...options, signal } : options;
         // If retry is disabled, return the raw provider stream
         if (!this.retryConfig.enabled) {
-            return this.provider.chat(messages, options);
+            return this.provider.chat(messages, chatOptions);
         }
         const providerName = this.provider.name;
         const { maxAttempts, baseDelayMs, maxDelayMs } = this.retryConfig;
-        return withRetryGenerator(() => this.provider.chat(messages, options), {
+        return withRetryGenerator(() => this.provider.chat(messages, chatOptions), {
             maxAttempts,
             baseDelayMs,
             maxDelayMs,

package/dist/anchors/manager.js

@@ -4,6 +4,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { generateId } from '../utils/index.js';
+import { countTokens } from '../utils/tokenizer.js';
 import { getDefaultAnchors, isBuiltinAnchor } from './builtin.js';
 /**
  * Default options for AnchorManager
@@ -14,10 +15,10 @@ const DEFAULT_OPTIONS = {
     includeDefaults: true,
 };
 /**
- * Default token estimator (rough estimate: ~4 chars per token)
+ * Default token estimator using tiktoken (cl100k_base encoding)
  */
 function defaultEstimateTokens(content) {
-    return Math.ceil(content.length / 4);
+    return countTokens(content);
 }
 /**
  * AnchorManager - Manages critical information that survives context compaction

package/dist/context/delegated-result-store.d.ts

@@ -0,0 +1,67 @@
+/**
+ * In-memory store for delegated tool results.
+ *
+ * Stores full tool results that were replaced by summaries, allowing
+ * the agent to recall them via `recall_full_result`. Implements TTL
+ * expiration and LRU eviction.
+ */
+import type { StoredResult } from './delegation-types.js';
+/**
+ * Statistics about the delegation store.
+ */
+export interface DelegatedResultStoreStats {
+    /** Number of currently stored results */
+    size: number;
+    /** Maximum capacity (LRU limit) */
+    maxSize: number;
+    /** Total results stored since creation */
+    totalStored: number;
+    /** Total results evicted (TTL or LRU) */
+    totalEvicted: number;
+    /** Total results successfully recalled */
+    totalRecalled: number;
+}
+/**
+ * In-memory store for delegated results with TTL expiration and LRU eviction.
+ */
+export declare class DelegatedResultStore {
+    private readonly results;
+    private readonly maxSize;
+    private readonly defaultTTL;
+    private counter;
+    private totalStored;
+    private totalEvicted;
+    private totalRecalled;
+    constructor(options?: {
+        maxSize?: number;
+        defaultTTL?: number;
+    });
+    /**
+     * Generate a unique delegation ID.
+     */
+    generateId(): string;
+    /**
+     * Store a delegated result. Evicts oldest entries if at capacity.
+     */
+    add(result: StoredResult): void;
+    /**
+     * Get a stored result by ID. Returns undefined if not found or expired.
+     */
+    get(id: string): StoredResult | undefined;
+    /**
+     * Remove all expired entries.
+     */
+    cleanup(): void;
+    /**
+     * Clear all stored results.
+     */
+    clear(): void;
+    /**
+     * Get the default TTL for this store.
+     */
+    getDefaultTTL(): number;
+    /**
+     * Get store statistics.
+     */
+    getStats(): DelegatedResultStoreStats;
+}

package/dist/context/delegated-result-store.js

@@ -0,0 +1,99 @@
+/**
+ * In-memory store for delegated tool results.
+ *
+ * Stores full tool results that were replaced by summaries, allowing
+ * the agent to recall them via `recall_full_result`. Implements TTL
+ * expiration and LRU eviction.
+ */
+/**
+ * In-memory store for delegated results with TTL expiration and LRU eviction.
+ */
+export class DelegatedResultStore {
+    results = new Map();
+    maxSize;
+    defaultTTL;
+    counter = 0;
+    totalStored = 0;
+    totalEvicted = 0;
+    totalRecalled = 0;
+    constructor(options) {
+        this.maxSize = options?.maxSize ?? 50;
+        this.defaultTTL = options?.defaultTTL ?? 600_000;
+    }
+    /**
+     * Generate a unique delegation ID.
+     */
+    generateId() {
+        return `dr_${String(Date.now())}_${String(this.counter++)}`;
+    }
+    /**
+     * Store a delegated result. Evicts oldest entries if at capacity.
+     */
+    add(result) {
+        // Evict expired entries first
+        this.cleanup();
+        // LRU eviction: remove oldest entries if at capacity
+        while (this.results.size >= this.maxSize) {
+            const oldestKey = this.results.keys().next().value;
+            this.results.delete(oldestKey);
+            this.totalEvicted++;
+        }
+        this.results.set(result.id, result);
+        this.totalStored++;
+    }
+    /**
+     * Get a stored result by ID. Returns undefined if not found or expired.
+     */
+    get(id) {
+        const result = this.results.get(id);
+        if (!result)
+            return undefined;
+        // Check TTL
+        if (Date.now() > result.expiresAt) {
+            this.results.delete(id);
+            this.totalEvicted++;
+            return undefined;
+        }
+        // Move to end for LRU (delete + re-insert)
+        this.results.delete(id);
+        this.results.set(id, result);
+        this.totalRecalled++;
+        return result;
+    }
+    /**
+     * Remove all expired entries.
+     */
+    cleanup() {
+        const now = Date.now();
+        for (const [id, result] of this.results) {
+            if (now > result.expiresAt) {
+                this.results.delete(id);
+                this.totalEvicted++;
+            }
+        }
+    }
+    /**
+     * Clear all stored results.
+     */
+    clear() {
+        this.results.clear();
+    }
+    /**
+     * Get the default TTL for this store.
+     */
+    getDefaultTTL() {
+        return this.defaultTTL;
+    }
+    /**
+     * Get store statistics.
+     */
+    getStats() {
+        return {
+            size: this.results.size,
+            maxSize: this.maxSize,
+            totalStored: this.totalStored,
+            totalEvicted: this.totalEvicted,
+            totalRecalled: this.totalRecalled,
+        };
+    }
+}

package/dist/context/delegation-types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Types for tool result auto-delegation.
+ *
+ * When large tool results exceed a token threshold, they are automatically
+ * summarized and stored for optional recall. This conserves context tokens
+ * while preserving access to the full data.
+ */
+/**
+ * Configuration for tool result delegation.
+ * Controls when and how large tool results are summarized.
+ */
+export interface DelegationConfig {
+    /** Whether delegation is enabled. Default: false (opt-in) */
+    enabled: boolean;
+    /** Token count above which results are delegated. Default: 8000 */
+    delegationThreshold: number;
+    /** Maximum tokens for the summary. Default: 800 */
+    summaryMaxTokens: number;
+    /** Milliseconds before stored results expire. Default: 600_000 (10 min) */
+    resultTTL: number;
+    /** Maximum number of stored results (LRU eviction). Default: 50 */
+    maxStoredResults: number;
+    /** Summarization strategy. Default: 'auto' */
+    strategy: 'llm' | 'extractive' | 'auto';
+    /** Per-tool threshold/strategy overrides */
+    toolOverrides?: Record<string, {
+        enabled?: boolean;
+        threshold?: number;
+        strategy?: 'llm' | 'extractive' | 'auto';
+    }>;
+}
+/**
+ * A stored full result that was replaced by a summary.
+ */
+export interface StoredResult {
+    /** Unique delegation ID, e.g., 'dr_1707900000_0' */
+    id: string;
+    /** Name of the tool that produced the result */
+    toolName: string;
+    /** Input parameters passed to the tool */
+    toolInput: Record<string, unknown>;
+    /** The full serialized result content */
+    fullContent: string;
+    /** Token count of the full content */
+    fullTokens: number;
+    /** The generated summary */
+    summary: string;
+    /** Token count of the summary */
+    summaryTokens: number;
+    /** Timestamp when stored */
+    storedAt: number;
+    /** Timestamp when this result expires */
+    expiresAt: number;
+}
+/**
+ * Events emitted during the delegation lifecycle.
+ */
+export type DelegationEvent = {
+    type: 'delegation:started';
+    toolName: string;
+    originalTokens: number;
+    delegationId: string;
+} | {
+    type: 'delegation:completed';
+    toolName: string;
+    originalTokens: number;
+    summaryTokens: number;
+    delegationId: string;
+    strategy: 'llm' | 'extractive';
+} | {
+    type: 'delegation:failed';
+    toolName: string;
+    error: string;
+} | {
+    type: 'delegation:recall';
+    delegationId: string;
+    found: boolean;
+};
+/**
+ * Default delegation configuration values.
+ */
+export declare const DEFAULT_DELEGATION_CONFIG: DelegationConfig;

package/dist/context/delegation-types.js

@@ -0,0 +1,18 @@
+/**
+ * Types for tool result auto-delegation.
+ *
+ * When large tool results exceed a token threshold, they are automatically
+ * summarized and stored for optional recall. This conserves context tokens
+ * while preserving access to the full data.
+ */
+/**
+ * Default delegation configuration values.
+ */
+export const DEFAULT_DELEGATION_CONFIG = {
+    enabled: false,
+    delegationThreshold: 8000,
+    summaryMaxTokens: 800,
+    resultTTL: 600_000,
+    maxStoredResults: 50,
+    strategy: 'auto',
+};

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

@@ -32,6 +32,10 @@ export interface FileAccess {
     lineCount?: number;
     /** Optional summary of what was found/changed */
     summary?: string;
+    /** Stored file content (only for small reads, used for post-compaction restoration) */
+    content?: string;
+    /** Token count of stored content */
+    tokenCount?: number;
 }
 /**
  * Options for FileAccessTracker constructor
@@ -47,6 +51,18 @@ export interface FileAccessTrackerOptions {
      * @default true
      */
     deduplicateReferences?: boolean;
+    /**
+     * Maximum line count for a file to have its content stored inline.
+     * Files with more lines than this threshold will only store path/lineCount.
+     * @default 200
+     */
+    inlineThreshold?: number;
+    /**
+     * Maximum number of files that can have stored content at once.
+     * When exceeded, oldest content entries are evicted (path still tracked).
+     * @default 10
+     */
+    maxContentEntries?: number;
 }
 /**
  * Options for formatting restoration hints
@@ -65,6 +81,19 @@ export interface FormatHintsOptions {
     /** Verbosity level (adjusts format automatically) */
     verbosityLevel?: VerbosityLevel;
 }
+/**
+ * A single restoration hint message for post-compaction context injection
+ */
+export interface RestorationHintMessage {
+    /** File path */
+    path: string;
+    /** Whether content is inlined or just referenced */
+    type: 'inline' | 'reference';
+    /** The formatted hint text */
+    text: string;
+    /** Estimated token count of this hint */
+    tokens: number;
+}
 /**
  * Statistics about file accesses
  */
@@ -95,11 +124,13 @@ export declare class FileAccessTracker {
     private readonly accesses;
     private readonly maxEntries;
     private readonly deduplicateReferences;
+    private readonly inlineThreshold;
+    private readonly maxContentEntries;
     constructor(options?: FileAccessTrackerOptions);
     /**
      * Track a file that was fully read
      */
-    trackRead(filePath: string, lineCount: number, summary?: string): void;
+    trackRead(filePath: string, lineCount: number, summary?: string, content?: string): void;
     /**
      * Track a file that was referenced (e.g., appeared in grep/glob results)
      */
@@ -135,6 +166,23 @@ export declare class FileAccessTracker {
      * Format restoration hints for injection after compaction
      */
     formatRestorationHints(options?: FormatHintsOptions): string;
+    /**
+     * Format restoration hints with inline file content (Claude Code style).
+     *
+     * Small files with stored content are inlined up to a token budget.
+     * Large files or files exceeding the budget get reference-only hints.
+     * Each file produces a separate hint message for individual injection.
+     *
+     * Priority order for inlining:
+     * 1. Modified files (most critical context)
+     * 2. Read files, most recent first
+     * 3. Once budget exhausted → remaining become reference-only
+     * 4. Referenced-only files → always reference-only
+     */
+    formatRestorationHintsWithContent(options?: {
+        /** Total token budget for all inline content (default: 4000) */
+        maxInlineTokens?: number;
+    }): RestorationHintMessage[];
     /**
      * Clear all tracked accesses
      */
@@ -143,6 +191,16 @@ export declare class FileAccessTracker {
      * Get the number of tracked files
      */
     get size(): number;
+    /**
+     * Rough token estimate (4 chars ≈ 1 token). Avoids heavy tiktoken dependency
+     * in the tracker — exact counts aren't critical for budget enforcement.
+     */
+    private estimateTokens;
+    /**
+     * Evict oldest stored content when maxContentEntries is exceeded.
+     * Only drops the `content`/`tokenCount` fields — the access entry itself is preserved.
+     */
+    private enforceMaxContentEntries;
     private normalizePath;
     private enforceMaxEntries;
     private getEffectiveMaxFiles;