@compilr-dev/agents 0.5.8 → 0.6.0

package/README.md

@@ -14,6 +14,9 @@
 
 [![npm version](https://img.shields.io/npm/v/@compilr-dev/agents.svg)](https://www.npmjs.com/package/@compilr-dev/agents)
 [![License: FSL-1.1-MIT](https://img.shields.io/badge/License-FSL--1.1--MIT-blue.svg)](https://fsl.software/)
+[![API Docs](https://img.shields.io/badge/API_Docs-GitHub_Pages-blue)](https://compilr-dev.github.io/agents/)
+
+**[API Reference](https://compilr-dev.github.io/agents/)** | **[llms.txt](https://compilr.dev/llms.txt)** (for AI agents)
 
 > [!WARNING]
 > This package is in beta. APIs may change between minor versions.

package/dist/agent.d.ts

@@ -86,6 +86,11 @@ export type AgentEvent = {
     type: 'tool_loop_warning';
     toolName: string;
     consecutiveCalls: number;
+} | {
+    type: 'tool_loop_nudge';
+    toolName: string;
+    consecutiveCalls: number;
+    nudgeCount: number;
 } | {
     type: 'abort_checkpoint_saved';
     sessionId: string;
@@ -222,10 +227,22 @@ export interface AgentConfig {
      */
     maxIterations?: number;
     /**
-     * Maximum consecutive identical tool calls before throwing ToolLoopError (default: 3).
-     * Set to 0 to disable loop detection.
+     * Maximum consecutive identical tool calls (same name + input + result) before
+     * the loop detector trips (default: 5). Set to 0 to disable loop detection.
+     *
+     * Detection is result-aware: a repeated call only counts when its result is
+     * also identical to the previous one, so legitimate polling that returns
+     * changing output (e.g. `bash_output` while a build runs) does not trip.
      */
     maxConsecutiveToolCalls?: number;
+    /**
+     * On a loop trip, how many times to inject a corrective "self-heal" message
+     * and let the agent continue before throwing ToolLoopError (default: 1).
+     * Set to 0 to throw immediately on the first trip (no self-heal).
+     *
+     * Ignored when `onToolLoopDetected` is provided (that callback takes over).
+     */
+    maxToolLoopNudges?: number;
     /**
      * Behavior when max iterations is reached (default: 'error').
      * - 'error': Throw MaxIterationsError immediately
@@ -888,6 +905,7 @@ export declare class Agent {
     private readonly systemPrompt;
     private readonly maxIterations;
     private readonly maxConsecutiveToolCalls;
+    private readonly maxToolLoopNudges;
     private readonly iterationLimitBehavior;
     private readonly chatOptions;
     private readonly toolRegistry;
@@ -1134,13 +1152,33 @@ export declare class Agent {
     hasPins(): boolean;
     /**
      * Get the current model ID for this agent.
+     *
+     * @returns The model ID string (e.g., 'claude-sonnet-4-20250514')
      */
     getModel(): string;
     /**
-     * Change the model for subsequent LLM calls. Same provider only.
-     * Takes effect on the next chat() call, not mid-stream.
+     * Change the model for subsequent LLM calls (same provider only).
+     *
+     * Takes effect on the next `run()` or `stream()` call — never interrupts
+     * a running turn. Conversation history is preserved (it's provider-agnostic).
+     * Emits a `model_changed` event.
+     *
+     * Use this to switch between models within the same provider, e.g.,
+     * Claude Sonnet → Claude Opus for a harder task, then back.
      *
      * @param modelId - The new model ID (e.g., 'claude-opus-4-20250514')
+     * @throws If modelId is empty or not a string
+     *
+     * @example
+     * ```typescript
+     * console.log(agent.getModel()); // 'claude-sonnet-4-20250514'
+     * agent.setModel('claude-opus-4-20250514');
+     * // Next run() uses Opus
+     * const result = await agent.run('Solve this complex problem');
+     * agent.setModel('claude-sonnet-4-20250514'); // Switch back
+     * ```
+     *
+     * @since 0.5.8
      */
     setModel(modelId: string): void;
     /** @deprecated Use addPin() instead */
@@ -1647,11 +1685,38 @@ export declare class Agent {
      */
     private generateContextSummary;
     /**
-     * Register a tool for the agent to use
+     * Register a tool that the agent can call during conversations.
+     *
+     * Tools are functions the LLM can invoke to perform actions like reading
+     * files, running commands, or querying APIs. The LLM sees the tool's name,
+     * description, and parameter schema, then decides when to call it.
+     *
+     * @param tool - Tool definition created with `defineTool()`
+     * @returns The agent instance (for chaining)
+     *
+     * @example
+     * ```typescript
+     * agent.registerTool(defineTool({
+     *   name: 'get_weather',
+     *   description: 'Get current weather for a city',
+     *   parameters: {
+     *     type: 'object',
+     *     properties: { city: { type: 'string' } },
+     *     required: ['city'],
+     *   },
+     *   execute: async ({ city }) => {
+     *     const data = await fetchWeather(city);
+     *     return { content: JSON.stringify(data) };
+     *   },
+     * }));
+     * ```
      */
     registerTool(tool: Tool): this;
     /**
-     * Register multiple tools at once
+     * Register multiple tools at once.
+     *
+     * @param tools - Array of tool definitions
+     * @returns The agent instance (for chaining)
      */
     registerTools(tools: Tool[]): this;
     /**
@@ -1663,14 +1728,62 @@ export declare class Agent {
      */
     isToolSilent(name: string): boolean;
     /**
-     * Run the agent with a user message
+     * Run the agent with a user message and return the result.
+     *
+     * This is the main entry point for agent interaction. The agent will:
+     * 1. Add the user message to conversation history
+     * 2. Send the conversation to the LLM
+     * 3. Execute any tool calls the LLM requests
+     * 4. Repeat steps 2-3 until the LLM responds with text (no tool calls)
+     * 5. Return the final text response and metadata
+     *
+     * Events are emitted throughout the process via the `onEvent` callback
+     * configured at construction time.
+     *
+     * @param userMessage - The user's message (string or content blocks for images)
+     * @param options - Optional run configuration (max iterations, abort signal, etc.)
+     * @returns The agent's response, tool call history, and context stats
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.run('What files are in this directory?');
+     * console.log(result.response);
+     * console.log(`Used ${result.toolCalls.length} tool calls`);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With abort signal
+     * const controller = new AbortController();
+     * const result = await agent.run('Refactor this file', {
+     *   signal: controller.signal,
+     * });
+     * ```
      */
     run(userMessage: string | ContentBlock[], options?: RunOptions): Promise<AgentRunResult>;
     /**
-     * Stream the agent's response with full tool use support
+     * Stream the agent's response as events.
+     *
+     * Yields `AgentEvent` objects in real time as the agent thinks, calls tools,
+     * and generates text. Use this for building interactive UIs that show
+     * progress as it happens.
+     *
+     * @param userMessage - The user's message
+     * @param options - Optional run configuration
+     * @returns An async iterable of agent events
      *
-     * Yields AgentEvent objects as the agent executes, allowing
-     * real-time monitoring of the agentic loop.
+     * @example
+     * ```typescript
+     * for await (const event of agent.stream('Explain this code')) {
+     *   if (event.type === 'llm_chunk') {
+     *     process.stdout.write(event.chunk.text ?? '');
+     *   } else if (event.type === 'tool_start') {
+     *     console.log(`\nCalling tool: ${event.name}`);
+     *   } else if (event.type === 'done') {
+     *     console.log('\n\nDone!');
+     *   }
+     * }
+     * ```
      */
     stream(userMessage: string, options?: RunOptions): AsyncIterable<AgentEvent>;
     /**

package/dist/agent.js

@@ -44,6 +44,7 @@ export class Agent {
     systemPrompt;
     maxIterations;
     maxConsecutiveToolCalls;
+    maxToolLoopNudges;
     iterationLimitBehavior;
     chatOptions;
     toolRegistry;
@@ -122,7 +123,8 @@ export class Agent {
         this.provider = config.provider;
         this.systemPrompt = config.systemPrompt ?? '';
         this.maxIterations = config.maxIterations ?? 10;
-        this.maxConsecutiveToolCalls = config.maxConsecutiveToolCalls ?? 3;
+        this.maxConsecutiveToolCalls = config.maxConsecutiveToolCalls ?? 5;
+        this.maxToolLoopNudges = config.maxToolLoopNudges ?? 1;
         this.iterationLimitBehavior = config.iterationLimitBehavior ?? 'error';
         this.chatOptions = config.chatOptions ?? {};
         this.toolRegistry =
@@ -526,15 +528,35 @@ export class Agent {
     // --- Model management -------------------------------------------------------
     /**
      * Get the current model ID for this agent.
+     *
+     * @returns The model ID string (e.g., 'claude-sonnet-4-20250514')
      */
     getModel() {
         return this.provider.getModel();
     }
     /**
-     * Change the model for subsequent LLM calls. Same provider only.
-     * Takes effect on the next chat() call, not mid-stream.
+     * Change the model for subsequent LLM calls (same provider only).
+     *
+     * Takes effect on the next `run()` or `stream()` call — never interrupts
+     * a running turn. Conversation history is preserved (it's provider-agnostic).
+     * Emits a `model_changed` event.
+     *
+     * Use this to switch between models within the same provider, e.g.,
+     * Claude Sonnet → Claude Opus for a harder task, then back.
      *
      * @param modelId - The new model ID (e.g., 'claude-opus-4-20250514')
+     * @throws If modelId is empty or not a string
+     *
+     * @example
+     * ```typescript
+     * console.log(agent.getModel()); // 'claude-sonnet-4-20250514'
+     * agent.setModel('claude-opus-4-20250514');
+     * // Next run() uses Opus
+     * const result = await agent.run('Solve this complex problem');
+     * agent.setModel('claude-sonnet-4-20250514'); // Switch back
+     * ```
+     *
+     * @since 0.5.8
      */
     setModel(modelId) {
         if (!modelId || typeof modelId !== 'string') {
@@ -1518,14 +1540,41 @@ export class Agent {
         return summaryParts.join('\n');
     }
     /**
-     * Register a tool for the agent to use
+     * Register a tool that the agent can call during conversations.
+     *
+     * Tools are functions the LLM can invoke to perform actions like reading
+     * files, running commands, or querying APIs. The LLM sees the tool's name,
+     * description, and parameter schema, then decides when to call it.
+     *
+     * @param tool - Tool definition created with `defineTool()`
+     * @returns The agent instance (for chaining)
+     *
+     * @example
+     * ```typescript
+     * agent.registerTool(defineTool({
+     *   name: 'get_weather',
+     *   description: 'Get current weather for a city',
+     *   parameters: {
+     *     type: 'object',
+     *     properties: { city: { type: 'string' } },
+     *     required: ['city'],
+     *   },
+     *   execute: async ({ city }) => {
+     *     const data = await fetchWeather(city);
+     *     return { content: JSON.stringify(data) };
+     *   },
+     * }));
+     * ```
      */
     registerTool(tool) {
         this.toolRegistry.register(tool);
         return this;
     }
     /**
-     * Register multiple tools at once
+     * Register multiple tools at once.
+     *
+     * @param tools - Array of tool definitions
+     * @returns The agent instance (for chaining)
      */
     registerTools(tools) {
         for (const tool of tools) {
@@ -1547,7 +1596,37 @@ export class Agent {
         return tool?.silent === true;
     }
     /**
-     * Run the agent with a user message
+     * Run the agent with a user message and return the result.
+     *
+     * This is the main entry point for agent interaction. The agent will:
+     * 1. Add the user message to conversation history
+     * 2. Send the conversation to the LLM
+     * 3. Execute any tool calls the LLM requests
+     * 4. Repeat steps 2-3 until the LLM responds with text (no tool calls)
+     * 5. Return the final text response and metadata
+     *
+     * Events are emitted throughout the process via the `onEvent` callback
+     * configured at construction time.
+     *
+     * @param userMessage - The user's message (string or content blocks for images)
+     * @param options - Optional run configuration (max iterations, abort signal, etc.)
+     * @returns The agent's response, tool call history, and context stats
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.run('What files are in this directory?');
+     * console.log(result.response);
+     * console.log(`Used ${result.toolCalls.length} tool calls`);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With abort signal
+     * const controller = new AbortController();
+     * const result = await agent.run('Refactor this file', {
+     *   signal: controller.signal,
+     * });
+     * ```
      */
     async run(userMessage, options) {
         let maxIterations = options?.maxIterations ?? this.maxIterations;
@@ -1682,6 +1761,8 @@ export class Agent {
         // Tool loop detection: track consecutive identical calls
         let lastToolCallHash = '';
         let consecutiveIdenticalCalls = 0;
+        // Self-heal: how many corrective nudges we've injected for the current streak
+        let loopNudgeCount = 0;
         // Hash function for tool call comparison.
         // Uses a JSON replacer that recursively sorts object keys for stable hashing.
         // NOTE: A simple `JSON.stringify(input, Object.keys(input).sort())` only sorts
@@ -1703,6 +1784,87 @@ export class Agent {
         const hashToolCall = (name, input) => {
             return `${name}:${stableStringify(input)}`;
         };
+        // Cheap djb2 string hash — keeps the result portion of the loop key small
+        // instead of carrying full (possibly large) tool output around.
+        const cheapHash = (s) => {
+            let h = 5381;
+            for (let i = 0; i < s.length; i++)
+                h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+            return String(h >>> 0);
+        };
+        /**
+         * Result-aware tool-loop detection with self-heal.
+         *
+         * A call counts toward a loop only when name + input + result all match the
+         * previous call (so progress-making polls don't trip). On a trip:
+         *  - if `onToolLoopDetected` is wired → legacy ask-continue/stop path;
+         *  - else inject a corrective message and continue, up to `maxToolLoopNudges`
+         *    times; after that, throw ToolLoopError.
+         *
+         * Pushes any nudge into both `messages` and `newMessages`, so it must run
+         * AFTER the tool result has been pushed (history stays valid on throw).
+         */
+        const handleToolLoop = async (toolUse, resultContent) => {
+            if (this.maxConsecutiveToolCalls <= 0)
+                return;
+            // Tools that are legitimately repeatable opt out entirely.
+            if (this.toolRegistry.get(toolUse.name)?.repeatable)
+                return;
+            const currentHash = `${hashToolCall(toolUse.name, toolUse.input)}#${cheapHash(resultContent)}`;
+            if (currentHash !== lastToolCallHash) {
+                // Different call/result → progress. Fresh slate.
+                lastToolCallHash = currentHash;
+                consecutiveIdenticalCalls = 1;
+                loopNudgeCount = 0;
+                return;
+            }
+            consecutiveIdenticalCalls++;
+            if (consecutiveIdenticalCalls < this.maxConsecutiveToolCalls) {
+                emit({
+                    type: 'tool_loop_warning',
+                    toolName: toolUse.name,
+                    consecutiveCalls: consecutiveIdenticalCalls,
+                });
+                return;
+            }
+            // ── Trip ──
+            // Legacy callback path (back-compat): ask the host to continue or stop.
+            if (this.onToolLoopDetected) {
+                const shouldContinue = await this.onToolLoopDetected({
+                    toolName: toolUse.name,
+                    consecutiveCalls: consecutiveIdenticalCalls,
+                    input: toolUse.input,
+                });
+                if (shouldContinue) {
+                    consecutiveIdenticalCalls = 0;
+                    return;
+                }
+                throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
+            }
+            // Default: self-heal with a corrective message, up to maxToolLoopNudges.
+            if (loopNudgeCount < this.maxToolLoopNudges) {
+                loopNudgeCount++;
+                const nudge = {
+                    role: 'user',
+                    content: `[system reminder] You've called \`${toolUse.name}\` with identical input and an ` +
+                        `unchanged result ${String(consecutiveIdenticalCalls)} times in a row. If a process ` +
+                        `is still running, wait before polling again or tell the user what you're waiting on. ` +
+                        `Otherwise stop repeating this call and take a different step toward the goal.`,
+                };
+                messages.push(nudge);
+                newMessages.push(nudge);
+                emit({
+                    type: 'tool_loop_nudge',
+                    toolName: toolUse.name,
+                    consecutiveCalls: consecutiveIdenticalCalls,
+                    nudgeCount: loopNudgeCount,
+                });
+                consecutiveIdenticalCalls = 0;
+                return;
+            }
+            // Nudges exhausted → hard stop.
+            throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
+        };
         // Wrap agentic loop in try/finally to ensure conversation history is always
         // preserved, even when ToolLoopError or MaxIterationsError is thrown.
         // Without this, a thrown error skips the history append and the agent
@@ -1835,9 +1997,19 @@ export class Agent {
                         durationMs: Date.now() - llmStartTime,
                     });
                 }
+                // Accumulate every iteration's text into finalResponse, separated by
+                // blank lines. The previous code only assigned finalResponse in the
+                // terminal iteration (no tool uses), which silently dropped any
+                // text the agent produced BEFORE intermediate tool calls. Pattern:
+                //   iter 1: "Running test 1..."  → tool t1   ← text was lost
+                //   iter 2: "Now test 2..."      → tool t2   ← text was lost
+                //   iter 3: "All done."          → no tool   ← only this survived
+                // Now every text segment is preserved in finalResponse.
+                if (text) {
+                    finalResponse = finalResponse ? finalResponse + '\n\n' + text : text;
+                }
                 // If no tool uses, we're done
                 if (toolUses.length === 0) {
-                    finalResponse = text;
                     // Add final assistant response to history (only if non-empty)
                     // Empty responses can occur after silent tools like 'suggest'
                     if (text) {
@@ -2166,41 +2338,8 @@ export class Agent {
                             // so the conversation history stays valid if we throw
                             messages.push(toolResultMsg);
                             newMessages.push(toolResultMsg);
-                            // Tool loop detection (still applies per-tool)
-                            if (this.maxConsecutiveToolCalls > 0) {
-                                const currentHash = hashToolCall(toolUse.name, toolUse.input);
-                                if (currentHash === lastToolCallHash) {
-                                    consecutiveIdenticalCalls++;
-                                    if (consecutiveIdenticalCalls >= this.maxConsecutiveToolCalls) {
-                                        if (this.onToolLoopDetected) {
-                                            // Ask user: continue or stop?
-                                            const shouldContinue = await this.onToolLoopDetected({
-                                                toolName: toolUse.name,
-                                                consecutiveCalls: consecutiveIdenticalCalls,
-                                                input: toolUse.input,
-                                            });
-                                            if (shouldContinue) {
-                                                consecutiveIdenticalCalls = 0; // Reset counter
-                                            }
-                                            else {
-                                                throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
-                                            }
-                                        }
-                                        else {
-                                            throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
-                                        }
-                                    }
-                                    emit({
-                                        type: 'tool_loop_warning',
-                                        toolName: toolUse.name,
-                                        consecutiveCalls: consecutiveIdenticalCalls,
-                                    });
-                                }
-                                else {
-                                    lastToolCallHash = currentHash;
-                                    consecutiveIdenticalCalls = 1;
-                                }
-                            }
+                            // Tool loop detection (result-aware + self-heal)
+                            await handleToolLoop(toolUse, toolResultMsg.content[0]?.content ?? '');
                             // Stamp for observation masking
                             if (this.observationMasker) {
                                 const block = toolResultMsg.content[0];
@@ -2227,40 +2366,8 @@ export class Agent {
                             // so the conversation history stays valid if we throw
                             messages.push(toolResultMsg);
                             newMessages.push(toolResultMsg);
-                            // Tool loop detection
-                            if (this.maxConsecutiveToolCalls > 0) {
-                                const currentHash = hashToolCall(toolUse.name, toolUse.input);
-                                if (currentHash === lastToolCallHash) {
-                                    consecutiveIdenticalCalls++;
-                                    if (consecutiveIdenticalCalls >= this.maxConsecutiveToolCalls) {
-                                        if (this.onToolLoopDetected) {
-                                            const shouldContinue = await this.onToolLoopDetected({
-                                                toolName: toolUse.name,
-                                                consecutiveCalls: consecutiveIdenticalCalls,
-                                                input: toolUse.input,
-                                            });
-                                            if (shouldContinue) {
-                                                consecutiveIdenticalCalls = 0;
-                                            }
-                                            else {
-                                                throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
-                                            }
-                                        }
-                                        else {
-                                            throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
-                                        }
-                                    }
-                                    emit({
-                                        type: 'tool_loop_warning',
-                                        toolName: toolUse.name,
-                                        consecutiveCalls: consecutiveIdenticalCalls,
-                                    });
-                                }
-                                else {
-                                    lastToolCallHash = currentHash;
-                                    consecutiveIdenticalCalls = 1;
-                                }
-                            }
+                            // Tool loop detection (result-aware + self-heal)
+                            await handleToolLoop(toolUse, toolResultMsg.content[0]?.content ?? '');
                             // Stamp for observation masking
                             if (this.observationMasker) {
                                 const block = toolResultMsg.content[0];
@@ -2425,10 +2532,28 @@ export class Agent {
         return result;
     }
     /**
-     * Stream the agent's response with full tool use support
+     * Stream the agent's response as events.
+     *
+     * Yields `AgentEvent` objects in real time as the agent thinks, calls tools,
+     * and generates text. Use this for building interactive UIs that show
+     * progress as it happens.
      *
-     * Yields AgentEvent objects as the agent executes, allowing
-     * real-time monitoring of the agentic loop.
+     * @param userMessage - The user's message
+     * @param options - Optional run configuration
+     * @returns An async iterable of agent events
+     *
+     * @example
+     * ```typescript
+     * for await (const event of agent.stream('Explain this code')) {
+     *   if (event.type === 'llm_chunk') {
+     *     process.stdout.write(event.chunk.text ?? '');
+     *   } else if (event.type === 'tool_start') {
+     *     console.log(`\nCalling tool: ${event.name}`);
+     *   } else if (event.type === 'done') {
+     *     console.log('\n\nDone!');
+     *   }
+     * }
+     * ```
      */
     async *stream(userMessage, options) {
         // Use a simple queue-based approach

package/dist/context/manager.d.ts

@@ -52,7 +52,29 @@ export interface ContextManagerOptions {
     fileTracker?: FileAccessTracker;
 }
 /**
- * ContextManager tracks and manages context window usage
+ * Manages the agent's context window — tracks token usage, triggers
+ * compaction when the conversation grows too large, and ensures the
+ * agent never exceeds the model's context limit.
+ *
+ * The context window is divided into budgets:
+ * - **System prompt** (~15%) — always present, never compacted
+ * - **Anchors/pins** (~10%) — critical info that survives compaction
+ * - **Conversation history** (~75%) — compacted when budget exceeded
+ *
+ * When conversation history exceeds its budget, the manager triggers
+ * smart windowing (3-zone compaction): recent messages preserved,
+ * middle messages summarized, old messages dropped.
+ *
+ * @example
+ * ```typescript
+ * const agent = new Agent({
+ *   provider,
+ *   contextManager: new ContextManager({
+ *     maxTokens: 100000,
+ *     budgets: { system: 0.15, anchors: 0.10, conversation: 0.75 },
+ *   }),
+ * });
+ * ```
  */
 export declare class ContextManager {
     private readonly provider;

package/dist/context/manager.js

@@ -62,7 +62,29 @@ export const DEFAULT_CONTEXT_CONFIG = {
     },
 };
 /**
- * ContextManager tracks and manages context window usage
+ * Manages the agent's context window — tracks token usage, triggers
+ * compaction when the conversation grows too large, and ensures the
+ * agent never exceeds the model's context limit.
+ *
+ * The context window is divided into budgets:
+ * - **System prompt** (~15%) — always present, never compacted
+ * - **Anchors/pins** (~10%) — critical info that survives compaction
+ * - **Conversation history** (~75%) — compacted when budget exceeded
+ *
+ * When conversation history exceeds its budget, the manager triggers
+ * smart windowing (3-zone compaction): recent messages preserved,
+ * middle messages summarized, old messages dropped.
+ *
+ * @example
+ * ```typescript
+ * const agent = new Agent({
+ *   provider,
+ *   contextManager: new ContextManager({
+ *     maxTokens: 100000,
+ *     budgets: { system: 0.15, anchors: 0.10, conversation: 0.75 },
+ *   }),
+ * });
+ * ```
  */
 export class ContextManager {
     provider;

package/dist/providers/claude.d.ts

@@ -67,7 +67,32 @@ export interface ClaudeProviderConfig {
     enableExtendedContext?: boolean;
 }
 /**
- * ClaudeProvider implements LLMProvider for Anthropic's Claude API
+ * LLM provider for Anthropic's Claude models (Opus, Sonnet, Haiku).
+ *
+ * Supports streaming, tool use, prompt caching, extended context (1M tokens),
+ * and token-efficient tool schemas.
+ *
+ * @example
+ * ```typescript
+ * const provider = new ClaudeProvider({
+ *   apiKey: process.env.ANTHROPIC_API_KEY,
+ *   model: 'claude-sonnet-4-20250514',
+ * });
+ *
+ * const agent = new Agent({
+ *   provider,
+ *   systemPrompt: 'You are a helpful assistant.',
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using the factory function
+ * const provider = createClaudeProvider({
+ *   apiKey: 'sk-ant-...',
+ *   enableExtendedContext: true, // 1M token context
+ * });
+ * ```
  */
 export declare class ClaudeProvider implements LLMProvider {
     readonly name = "claude";

package/dist/providers/claude.js

@@ -22,7 +22,32 @@ const DEFAULT_MODEL = 'claude-sonnet-4-6';
  */
 const DEFAULT_MAX_TOKENS = 4096;
 /**
- * ClaudeProvider implements LLMProvider for Anthropic's Claude API
+ * LLM provider for Anthropic's Claude models (Opus, Sonnet, Haiku).
+ *
+ * Supports streaming, tool use, prompt caching, extended context (1M tokens),
+ * and token-efficient tool schemas.
+ *
+ * @example
+ * ```typescript
+ * const provider = new ClaudeProvider({
+ *   apiKey: process.env.ANTHROPIC_API_KEY,
+ *   model: 'claude-sonnet-4-20250514',
+ * });
+ *
+ * const agent = new Agent({
+ *   provider,
+ *   systemPrompt: 'You are a helpful assistant.',
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using the factory function
+ * const provider = createClaudeProvider({
+ *   apiKey: 'sk-ant-...',
+ *   enableExtendedContext: true, // 1M token context
+ * });
+ * ```
  */
 export class ClaudeProvider {
     name = 'claude';

package/dist/providers/types.d.ts

@@ -226,13 +226,26 @@ export interface ToolResult {
 /**
  * LLM Provider interface - all providers must implement this
  */
+/**
+ * Interface for LLM providers. Implement this to add support for a new AI model.
+ *
+ * Built-in providers: `ClaudeProvider`, `OpenAIProvider`, `GeminiProvider`,
+ * `OllamaProvider`, `TogetherProvider`, `GroqProvider`, `FireworksProvider`,
+ * `PerplexityProvider`, `OpenRouterProvider`.
+ *
+ * For OpenAI-compatible APIs, extend `OpenAICompatibleProvider` instead of
+ * implementing this interface directly.
+ */
 export interface LLMProvider {
     /**
-     * Provider name (e.g., 'claude', 'openai', 'gemini')
+     * Provider identifier (e.g., 'claude', 'openai', 'gemini')
      */
     readonly name: string;
     /**
-     * Send messages and get a streaming response
+     * Send messages to the LLM and stream the response.
+     *
+     * Yields `StreamChunk` objects containing text fragments, tool calls,
+     * usage stats, and other provider-specific data.
      */
     chat(messages: Message[], options?: ChatOptions): AsyncIterable<StreamChunk>;
     /**

package/dist/tools/define.d.ts

@@ -42,6 +42,11 @@ export interface DefineToolOptions<T extends object> {
      * Default: false
      */
     readonly?: boolean;
+    /**
+     * If true, this tool is exempt from tool-loop detection (repeated identical
+     * calls are always legitimate). Default: false.
+     */
+    repeatable?: boolean;
 }
 /**
  * Define a tool with type-safe input handling

package/dist/tools/define.js

@@ -35,6 +35,7 @@ export function defineTool(options) {
         parallel: options.parallel,
         silent: options.silent,
         readonly: options.readonly,
+        repeatable: options.repeatable,
     };
 }
 /**

package/dist/tools/types.d.ts

@@ -73,7 +73,36 @@ export interface ToolExecutionContext {
  */
 export type ToolHandler<T = object> = (input: T, context?: ToolExecutionContext) => Promise<ToolExecutionResult>;
 /**
- * Tool implementation - combines definition with handler
+ * A tool that the agent can call during conversations.
+ *
+ * Tools are the primary way agents interact with the outside world — reading
+ * files, running commands, querying APIs, etc. Each tool has a definition
+ * (name, description, parameters) that the LLM sees, and an execute function
+ * that runs when the LLM decides to call it.
+ *
+ * Use `defineTool()` to create tools with type-safe parameters.
+ *
+ * @typeParam T - The type of the tool's input parameters
+ *
+ * @example
+ * ```typescript
+ * const readFileTool: Tool<{ path: string }> = {
+ *   definition: {
+ *     name: 'read_file',
+ *     description: 'Read the contents of a file',
+ *     parameters: {
+ *       type: 'object',
+ *       properties: { path: { type: 'string', description: 'File path' } },
+ *       required: ['path'],
+ *     },
+ *   },
+ *   execute: async ({ path }) => {
+ *     const content = await fs.readFile(path, 'utf-8');
+ *     return { content };
+ *   },
+ *   readonly: true,  // Safe for parallel execution
+ * };
+ * ```
  */
 export interface Tool<T = object> {
     definition: ToolDefinition;
@@ -98,6 +127,13 @@ export interface Tool<T = object> {
      * Default: false
      */
     readonly?: boolean;
+    /**
+     * If true, this tool is exempt from tool-loop detection — repeated identical
+     * calls are always legitimate (e.g. genuinely idempotent pollers). Most
+     * polling tools do NOT need this: loop detection is result-aware, so calls
+     * that return changing output don't trip. Default: false.
+     */
+    repeatable?: boolean;
 }
 /**
  * Fallback handler for tools not found in the primary registry.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.5.8",
+  "version": "0.6.0",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,11 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "prepublishOnly": "npm run clean && npm run lint && npm run test && npm run build",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "docs": "typedoc && node scripts/inject-frontmatter.mjs && typedoc --options typedoc.llms.json && mv docs/llms/README.md docs/llms.txt",
+    "docs:api": "typedoc",
+    "docs:llms": "typedoc --options typedoc.llms.json",
+    "docs:watch": "typedoc --watch"
   },
   "repository": {
     "type": "git",
@@ -76,6 +80,8 @@
     "dotenv": "^17.2.3",
     "eslint": "^9.39.1",
     "prettier": "^3.7.1",
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.11.0",
     "typescript": "^5.3.0",
     "typescript-eslint": "^8.48.0",
     "vitest": "^4.0.18"
@@ -87,7 +93,7 @@
     "js-tiktoken": "^1.0.21"
   },
   "overrides": {
-    "hono": "^4.11.10",
+    "hono": "^4.12.21",
     "minimatch": ">=10.2.1",
     "glob": ">=11.0.0"
   }