@compilr-dev/agents 0.5.8 → 0.5.9

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

@@ -1134,13 +1134,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 +1667,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 +1710,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.
      *
-     * 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!');
+     *   }
+     * }
+     * ```
      */
     stream(userMessage: string, options?: RunOptions): AsyncIterable<AgentEvent>;
     /**

package/dist/agent.js

@@ -526,15 +526,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 +1538,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 +1594,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;
@@ -1835,9 +1912,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) {
@@ -2425,10 +2512,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/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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "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"