@compilr-dev/agents 0.3.9 → 0.3.11

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

@@ -1231,6 +1231,11 @@ export declare class Agent {
      * Get the context manager (if configured)
      */
     getContextManager(): ContextManager | undefined;
+    /**
+     * Get the tool registry instance.
+     * Useful for setting up fallback handlers or inspecting registered tools.
+     */
+    getToolRegistry(): ToolRegistry;
     /**
      * Get context statistics
      */