@compilr-dev/agents 0.3.10 → 0.3.12

package/README.md

@@ -1,19 +1,35 @@
 # @compilr-dev/agents
 
-Lightweight multi-LLM agent library for building CLI AI assistants.
+```
+      \|/
+    ╭══════════╮     ___  ___  _ __ ___  _ __ (_) |_ __
+    ║'  ▐▌  ▐▌ │    / __|/ _ \| '_ ` _ \| '_ \| | | '__|
+    ║          │   | (__| (_) | | | | | | |_) | | | |
+    ╰─═──────═─╯    \___|\___/|_| |_| |_| .__/|_|_|_|
+      \________\                        | | .dev
+                                        |_| agents
+```
+
+> Lightweight multi-LLM agent library for building CLI AI assistants
+
+[![npm version](https://img.shields.io/npm/v/@compilr-dev/agents.svg)](https://www.npmjs.com/package/@compilr-dev/agents)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Features
 
-- **Multi-LLM Support**: Abstract provider interface supporting Claude, OpenAI, Gemini, and local models
-- **Tool System**: Type-safe tool definitions with JSON Schema validation
-- **Event Streaming**: Real-time execution monitoring with typed events
-- **Abort Support**: Cancel running agents with `AbortSignal`
-- **Built-in Tools**: Ready-to-use file and bash tools
+- **Multi-LLM Support**: 9 providers -- Claude, OpenAI, Gemini, Ollama (local), Together AI, Groq, Fireworks, Perplexity, OpenRouter
+- **17 Built-in Tools**: File ops, bash, grep, glob, edit, web fetch, sub-agents, todos, backlog, and more
+- **Sub-agents**: Spawn specialized agents for complex tasks (9 built-in agent types)
+- **11 Skills**: Reusable prompt templates for common workflows
+- **Context Management**: Token budgeting, compaction, summarization
+- **Event Streaming**: Real-time execution monitoring with typed events and abort support
 - **Anchors**: Critical information that survives context compaction
-- **Guardrails**: Pattern-based safety checks (warn/confirm/block dangerous operations)
-- **Permissions**: Tool-level permission management (always/session/once/deny)
-- **Project Memory**: Load project instructions from CLAUDE.md, GEMINI.md, etc.
-- **TypeScript First**: Full type safety throughout
+- **Guardrails**: 15 built-in patterns for safety checks (warn/confirm/block)
+- **Permissions**: Tool-level access control (always/session/once/deny) with wildcards
+- **Project Memory**: Auto-loads CLAUDE.md, GEMINI.md, CURSOR.md, and more
+- **Hooks System**: Lifecycle hooks for beforeChat, afterChat, beforeToolCall, afterToolCall
+- **Rate Limiting**: Automatic retry with exponential backoff
+- **TypeScript First**: Full type safety with strict mode
 
 ## Installation
 
@@ -282,15 +298,43 @@ try {
 
 ## Providers
 
-### ClaudeProvider
+### Built-in Providers
 
 ```typescript
-import { ClaudeProvider } from '@compilr-dev/agents';
+import {
+  ClaudeProvider,     // Anthropic Claude
+  OpenAIProvider,     // OpenAI GPT
+  GeminiProvider,     // Google Gemini
+  OllamaProvider,     // Local models (no API key)
+  TogetherProvider,   // Together AI
+  GroqProvider,       // Groq (fast inference)
+  FireworksProvider,  // Fireworks AI
+  PerplexityProvider, // Perplexity (search-augmented)
+  OpenRouterProvider, // OpenRouter (multi-provider)
+} from '@compilr-dev/agents';
 
-const provider = new ClaudeProvider({
+// Claude (recommended)
+const claude = new ClaudeProvider({
   apiKey: process.env.ANTHROPIC_API_KEY,
-  model: 'claude-sonnet-4-20250514',  // Default
-  maxTokens: 4096,
+  model: 'claude-sonnet-4-20250514',
+});
+
+// OpenAI
+const openai = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4o',
+});
+
+// Gemini
+const gemini = new GeminiProvider({
+  apiKey: process.env.GOOGLE_API_KEY,
+  model: 'gemini-2.0-flash',
+});
+
+// Ollama (local, no API key)
+const ollama = new OllamaProvider({
+  model: 'llama3.1:8b',
+  baseUrl: 'http://localhost:11434',
 });
 ```
 
@@ -1236,42 +1280,41 @@ const tracing = createOtelTracing({
 const agent = new Agent({ provider, tracing });
 ```
 
-## Examples
+## Requirements
 
-See the `examples/` directory for runnable demos:
+- **Node.js** 18 or higher
+- **API Key** for your chosen provider (except Ollama)
 
-```bash
-# Basic agent usage
-npx tsx examples/basic-agent.ts
+## Peer Dependencies
 
-# Agent with custom tools
-npx tsx examples/agent-with-tools.ts
-
-# Streaming events
-npx tsx examples/streaming-events.ts
-```
-
-## Testing
-
-```bash
-# Run tests
-npm test
-
-# Run with coverage
-npm run test:coverage
-
-# Watch mode
-npm run test:watch
-```
+- `@anthropic-ai/sdk` (optional, for Claude)
+- `@modelcontextprotocol/sdk` (optional, for MCP)
 
 ## Design Philosophy
 
-1. **Minimal dependencies**: Only `@anthropic-ai/sdk` as optional peer dep
+1. **Minimal dependencies**: Only `@anthropic-ai/sdk` and `@modelcontextprotocol/sdk` as optional peer deps
 2. **Type safety**: Full TypeScript support with strict mode
 3. **Extensibility**: Easy to add new providers and tools
 4. **Testability**: MockProvider for easy unit testing
 5. **Real-time feedback**: Event system for CLI applications
 
+## Related Packages
+
+- [@compilr-dev/cli](https://www.npmjs.com/package/@compilr-dev/cli) - AI-powered CLI assistant
+- [@compilr-dev/agents-coding](https://www.npmjs.com/package/@compilr-dev/agents-coding) - Coding-specific tools (git, runners, code search)
+
+## Links
+
+- [Website](https://compilr.dev)
+- [npm Package](https://www.npmjs.com/package/@compilr-dev/agents)
+- [Report Issues](https://github.com/compilr-dev/agents/issues)
+
 ## License
 
-MIT
+MIT - See [LICENSE](LICENSE) for details.
+
+---
+
+<p align="center">
+  <strong>Built with care by <a href="https://compilr.dev">compilr.dev</a></strong>
+</p>

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';