@compilr-dev/agents 0.3.11 → 0.3.12

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

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';
@@ -177,19 +179,50 @@ 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();
             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 = {
@@ -2098,7 +2131,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 });
             }
         }

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/index.d.ts

@@ -14,3 +14,9 @@ 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';
+export { DelegatedResultStore } from './delegated-result-store.js';
+export type { DelegatedResultStoreStats } from './delegated-result-store.js';
+export { ToolResultDelegator, DELEGATION_SYSTEM_PROMPT } from './tool-result-delegator.js';
+export type { ToolResultDelegatorOptions } from './tool-result-delegator.js';
+export { DEFAULT_DELEGATION_CONFIG } from './delegation-types.js';
+export type { DelegationConfig, StoredResult, DelegationEvent } from './delegation-types.js';

package/dist/context/index.js

@@ -11,3 +11,7 @@
 export { ContextManager, DEFAULT_CONTEXT_CONFIG } from './manager.js';
 export { FileAccessTracker } from './file-tracker.js';
 export { createFileTrackingHook, TRACKED_TOOLS } from './file-tracking-hook.js';
+// Tool Result Delegation
+export { DelegatedResultStore } from './delegated-result-store.js';
+export { ToolResultDelegator, DELEGATION_SYSTEM_PROMPT } from './tool-result-delegator.js';
+export { DEFAULT_DELEGATION_CONFIG } from './delegation-types.js';

package/dist/context/manager.js

@@ -18,6 +18,7 @@
  * ```
  */
 import { repairToolPairing } from '../messages/index.js';
+import { countTokens, countMessageTokens } from '../utils/tokenizer.js';
 /**
  * Default budget allocation
  */
@@ -122,29 +123,8 @@ export class ContextManager {
         if (this.provider.countTokens) {
             return this.provider.countTokens(messages);
         }
-        // Fallback: rough estimate based on character count
-        let charCount = 0;
-        for (const msg of messages) {
-            if (typeof msg.content === 'string') {
-                charCount += msg.content.length;
-            }
-            else {
-                for (const block of msg.content) {
-                    switch (block.type) {
-                        case 'text':
-                            charCount += block.text.length;
-                            break;
-                        case 'tool_use':
-                            charCount += JSON.stringify(block.input).length;
-                            break;
-                        case 'tool_result':
-                            charCount += block.content.length;
-                            break;
-                    }
-                }
-            }
-        }
-        return Math.ceil(charCount / 4);
+        // Fallback: count tokens using tiktoken
+        return countMessageTokens(messages);
     }
     /**
      * Update token count for messages
@@ -351,7 +331,7 @@ export class ContextManager {
             }
             // Compact this message
             if (typeof msg.content === 'string') {
-                const tokens = Math.ceil(msg.content.length / 4);
+                const tokens = countTokens(msg.content);
                 if (tokens >= this.config.compaction.minTokensToCompact) {
                     const filePath = await saveToFile(msg.content, compactedIndex++);
                     filesCreated.push(filePath);
@@ -369,7 +349,7 @@ export class ContextManager {
                 const compactedBlocks = [];
                 for (const block of msg.content) {
                     if (block.type === 'tool_result' && category === 'toolResults') {
-                        const tokens = Math.ceil(block.content.length / 4);
+                        const tokens = countTokens(block.content);
                         if (tokens >= this.config.compaction.minTokensToCompact) {
                             const filePath = await saveToFile(block.content, compactedIndex++);
                             filesCreated.push(filePath);
@@ -702,7 +682,7 @@ export class ContextManager {
      * Estimate tokens for a string content
      */
     estimateTokens(content) {
-        return Math.ceil(content.length / 4);
+        return countTokens(content);
     }
     /**
      * Check if content can be added to a category
@@ -822,13 +802,13 @@ export class ContextManager {
                 maxLines = this.config.filtering.maxErrorLines;
                 break;
             default: {
-                // For tool results, check token count estimate
-                const estimatedTokens = Math.ceil(content.length / 4);
+                // For tool results, check token count
+                const estimatedTokens = countTokens(content);
                 if (estimatedTokens <= this.config.filtering.maxToolResultTokens) {
                     return { content, filtered: false, originalLength };
                 }
-                // Truncate to roughly maxToolResultTokens
-                const maxChars = this.config.filtering.maxToolResultTokens * 4;
+                // Truncate to roughly maxToolResultTokens (~3 chars per token)
+                const maxChars = this.config.filtering.maxToolResultTokens * 3;
                 const truncated = content.slice(0, maxChars);
                 return {
                     content: truncated + '\n\n[Content truncated - see file for full output]',
@@ -877,7 +857,7 @@ export class ContextManager {
         for (const msg of oldMessages) {
             if (typeof msg.content === 'string') {
                 // Check if string content is large enough to compact
-                const tokens = Math.ceil(msg.content.length / 4);
+                const tokens = countTokens(msg.content);
                 if (tokens >= this.config.compaction.minTokensToCompact) {
                     const filePath = await saveToFile(msg.content, compactedIndex++);
                     filesCreated.push(filePath);
@@ -895,7 +875,7 @@ export class ContextManager {
                 const compactedBlocks = [];
                 for (const block of msg.content) {
                     if (block.type === 'tool_result') {
-                        const tokens = Math.ceil(block.content.length / 4);
+                        const tokens = countTokens(block.content);
                         if (tokens >= this.config.compaction.minTokensToCompact) {
                             const filePath = await saveToFile(block.content, compactedIndex++);
                             filesCreated.push(filePath);

package/dist/context/tool-result-delegator.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Tool Result Delegator
+ *
+ * Intercepts large tool results via the AfterToolHook mechanism,
+ * stores the full result for optional recall, and replaces it
+ * with a compact summary to conserve context tokens.
+ */
+import type { LLMProvider } from '../providers/types.js';
+import type { AfterToolHook } from '../hooks/types.js';
+import type { DelegationConfig, DelegationEvent } from './delegation-types.js';
+import { DelegatedResultStore } from './delegated-result-store.js';
+/**
+ * Options for creating a ToolResultDelegator.
+ */
+export interface ToolResultDelegatorOptions {
+    /** LLM provider for summarization (small/medium tier preferred) */
+    provider: LLMProvider;
+    /** Delegation configuration (merged with defaults) */
+    config?: Partial<DelegationConfig>;
+    /** Event callback for delegation lifecycle events */
+    onEvent?: (event: DelegationEvent) => void;
+}
+/**
+ * Core class that creates an AfterToolHook for auto-delegating large tool results.
+ */
+export declare class ToolResultDelegator {
+    private readonly store;
+    private readonly config;
+    private readonly provider;
+    private readonly onEvent?;
+    constructor(options: ToolResultDelegatorOptions);
+    /**
+     * Returns an AfterToolHook to register with HooksManager.
+     */
+    createHook(): AfterToolHook;
+    /**
+     * Perform the actual delegation (async path).
+     */
+    private delegateResult;
+    /**
+     * Access the store (needed by recall_full_result tool).
+     */
+    getStore(): DelegatedResultStore;
+    /**
+     * Get the resolved config for a specific tool.
+     */
+    private getToolConfig;
+    /**
+     * Extractive summarization: first/last lines + prioritized structural markers.
+     * No LLM cost, fast, preserves actual code signatures.
+     */
+    private summarizeExtractive;
+    /**
+     * LLM-based summarization using the provider.
+     * Returns null if the LLM call fails.
+     */
+    private summarizeLLM;
+}
+/**
+ * System prompt addition when delegation is enabled.
+ * Append to the agent's system prompt.
+ */
+export declare const DELEGATION_SYSTEM_PROMPT: string;