@compilr-dev/agents 0.3.1 → 0.3.4

package/dist/index.d.ts

@@ -15,14 +15,29 @@ export { OpenAIProvider, createOpenAIProvider } from './providers/index.js';
 export type { OpenAIProviderConfig } from './providers/index.js';
 export { GeminiProvider, createGeminiProvider } from './providers/index.js';
 export type { GeminiProviderConfig } from './providers/index.js';
+export { GeminiNativeProvider, createGeminiNativeProvider } from './providers/index.js';
+export type { GeminiNativeProviderConfig } from './providers/index.js';
+export { GeminiLegacyProvider, createGeminiLegacyProvider } from './providers/index.js';
+export type { GeminiLegacyProviderConfig } from './providers/index.js';
 export { OpenAICompatibleProvider } from './providers/index.js';
 export type { OpenAICompatibleConfig } from './providers/index.js';
+export { TogetherProvider, createTogetherProvider } from './providers/index.js';
+export type { TogetherProviderConfig } from './providers/index.js';
+export { GroqProvider, createGroqProvider } from './providers/index.js';
+export type { GroqProviderConfig } from './providers/index.js';
+export { FireworksProvider, createFireworksProvider } from './providers/index.js';
+export type { FireworksProviderConfig } from './providers/index.js';
+export { PerplexityProvider, createPerplexityProvider } from './providers/index.js';
+export type { PerplexityProviderConfig } from './providers/index.js';
+export { OpenRouterProvider, createOpenRouterProvider } from './providers/index.js';
+export type { OpenRouterProviderConfig } from './providers/index.js';
 export type { Tool, ToolHandler, ToolRegistry, ToolInputSchema, ToolExecutionResult, ToolRegistryOptions, DefineToolOptions, ReadFileInput, WriteFileInput, BashInput, BashResult, FifoDetectionResult, GrepInput, GlobInput, EditInput, TodoWriteInput, TodoReadInput, TodoItem, TodoStatus, TodoContextCleanupOptions, TaskInput, TaskResult, AgentTypeConfig, TaskToolOptions, ContextMode, ThoroughnessLevel, SubAgentEventInfo, SuggestInput, SuggestToolOptions, } from './tools/index.js';
 export { defineTool, createSuccessResult, createErrorResult, wrapToolExecute, DefaultToolRegistry, createToolRegistry, } from './tools/index.js';
 export { readFileTool, createReadFileTool, writeFileTool, createWriteFileTool, bashTool, createBashTool, execStream, detectFifoUsage, bashOutputTool, createBashOutputTool, killShellTool, createKillShellTool, ShellManager, getDefaultShellManager, setDefaultShellManager, grepTool, createGrepTool, globTool, createGlobTool, editTool, createEditTool, todoWriteTool, todoReadTool, createTodoTools, TodoStore, resetDefaultTodoStore, getDefaultTodoStore, createIsolatedTodoStore, cleanupTodoContextMessages, getTodoContextStats, webFetchTool, createWebFetchTool, createTaskTool, defaultAgentTypes, suggestTool, createSuggestTool, builtinTools, allBuiltinTools, TOOL_NAMES, TOOL_SETS, } from './tools/index.js';
 export { userMessage, assistantMessage, systemMessage, textBlock, toolUseBlock, toolResultBlock, getTextContent, getToolUses, getToolResults, hasToolUses, validateToolUseResultPairing, repairToolPairing, ensureMessageContent, normalizeMessages, } from './messages/index.js';
 export type { ToolPairingValidation } from './messages/index.js';
-export { generateId, sleep, retry, truncate } from './utils/index.js';
+export { generateId, sleep, retry, truncate, withRetryGenerator, calculateBackoffDelay, DEFAULT_RETRY_CONFIG, } from './utils/index.js';
+export type { RetryConfig as LLMRetryConfig, WithRetryOptions } from './utils/index.js';
 export { AgentError, ProviderError, ToolError, ToolTimeoutError, ToolLoopError, ValidationError, MaxIterationsError, AbortError, ContextOverflowError, isAgentError, isProviderError, isToolError, isToolTimeoutError, isToolLoopError, isContextOverflowError, wrapError, } from './errors.js';
 export { ContextManager, DEFAULT_CONTEXT_CONFIG, FileAccessTracker, createFileTrackingHook, TRACKED_TOOLS, } from './context/index.js';
 export type { ContextManagerOptions, ContextCategory, BudgetAllocation, CategoryBudgetInfo, PreflightResult, VerbosityLevel, VerbosityConfig, ContextConfig, FilteringConfig, CompactionConfig, SummarizationConfig, CompactionResult, SummarizationResult, FilteringResult, ContextEvent, ContextEventHandler, ContextStats, FileAccessType, FileAccess, FileAccessTrackerOptions, FormatHintsOptions, FileAccessStats, } from './context/index.js';

package/dist/index.js

@@ -11,7 +11,17 @@ export { ClaudeProvider, createClaudeProvider } from './providers/index.js';
 export { OllamaProvider, createOllamaProvider } from './providers/index.js';
 export { OpenAIProvider, createOpenAIProvider } from './providers/index.js';
 export { GeminiProvider, createGeminiProvider } from './providers/index.js';
+// Also export native Gemini provider explicitly for clarity
+export { GeminiNativeProvider, createGeminiNativeProvider } from './providers/index.js';
+// Legacy Gemini provider (OpenAI-compatible endpoint)
+export { GeminiLegacyProvider, createGeminiLegacyProvider } from './providers/index.js';
 export { OpenAICompatibleProvider } from './providers/index.js';
+// "Others" providers - OpenAI-compatible cloud APIs
+export { TogetherProvider, createTogetherProvider } from './providers/index.js';
+export { GroqProvider, createGroqProvider } from './providers/index.js';
+export { FireworksProvider, createFireworksProvider } from './providers/index.js';
+export { PerplexityProvider, createPerplexityProvider } from './providers/index.js';
+export { OpenRouterProvider, createOpenRouterProvider } from './providers/index.js';
 // Tool utilities
 export { defineTool, createSuccessResult, createErrorResult, wrapToolExecute, DefaultToolRegistry, createToolRegistry, } from './tools/index.js';
 // Built-in tools
@@ -25,7 +35,9 @@ TOOL_NAMES, TOOL_SETS, } from './tools/index.js';
 // Message utilities
 export { userMessage, assistantMessage, systemMessage, textBlock, toolUseBlock, toolResultBlock, getTextContent, getToolUses, getToolResults, hasToolUses, validateToolUseResultPairing, repairToolPairing, ensureMessageContent, normalizeMessages, } from './messages/index.js';
 // Utilities
-export { generateId, sleep, retry, truncate } from './utils/index.js';
+export { generateId, sleep, 
+// eslint-disable-next-line @typescript-eslint/no-deprecated -- Kept for backward compatibility
+retry, truncate, withRetryGenerator, calculateBackoffDelay, DEFAULT_RETRY_CONFIG, } from './utils/index.js';
 // Errors
 export { AgentError, ProviderError, ToolError, ToolTimeoutError, ToolLoopError, ValidationError, MaxIterationsError, AbortError, ContextOverflowError, isAgentError, isProviderError, isToolError, isToolTimeoutError, isToolLoopError, isContextOverflowError, wrapError, } from './errors.js';
 // Context management

package/dist/messages/index.d.ts

@@ -83,13 +83,20 @@ export declare function normalizeMessages(messages: Message[]): Message[];
 /**
  * Repair tool use/result pairing issues in a message array.
  *
- * This function removes orphaned tool_result blocks (those without a matching tool_use)
- * which can cause API errors like "function_response.name: Name cannot be empty" in Gemini.
+ * This function handles BOTH types of orphans with POSITIONAL requirements:
+ * 1. Orphaned tool_result blocks (those without a matching tool_use BEFORE them)
+ *    - Causes: "function_response.name: Name cannot be empty" in Gemini
+ * 2. Orphaned tool_use blocks (those without tool_result in IMMEDIATELY NEXT message)
+ *    - Causes: "tool_use ids were found without tool_result blocks" in Claude
  *
- * This is particularly useful after context compaction/summarization, which may remove
- * tool_use messages while preserving tool_result messages in the "recent" window.
+ * CRITICAL: Claude API requires tool_result to be in the IMMEDIATELY NEXT message
+ * after the assistant message containing tool_use. This function validates that
+ * positional requirement, not just existence anywhere in the array.
+ *
+ * This is particularly useful after context compaction/summarization, which may
+ * remove messages and break tool_use/tool_result pairing.
  *
  * @param messages - Array of messages to repair
- * @returns New array with orphaned tool_results removed
+ * @returns New array with orphaned tool_use and tool_result blocks removed
  */
 export declare function repairToolPairing(messages: Message[]): Message[];

package/dist/messages/index.js

@@ -156,39 +156,77 @@ export function normalizeMessages(messages) {
 /**
  * Repair tool use/result pairing issues in a message array.
  *
- * This function removes orphaned tool_result blocks (those without a matching tool_use)
- * which can cause API errors like "function_response.name: Name cannot be empty" in Gemini.
+ * This function handles BOTH types of orphans with POSITIONAL requirements:
+ * 1. Orphaned tool_result blocks (those without a matching tool_use BEFORE them)
+ *    - Causes: "function_response.name: Name cannot be empty" in Gemini
+ * 2. Orphaned tool_use blocks (those without tool_result in IMMEDIATELY NEXT message)
+ *    - Causes: "tool_use ids were found without tool_result blocks" in Claude
  *
- * This is particularly useful after context compaction/summarization, which may remove
- * tool_use messages while preserving tool_result messages in the "recent" window.
+ * CRITICAL: Claude API requires tool_result to be in the IMMEDIATELY NEXT message
+ * after the assistant message containing tool_use. This function validates that
+ * positional requirement, not just existence anywhere in the array.
+ *
+ * This is particularly useful after context compaction/summarization, which may
+ * remove messages and break tool_use/tool_result pairing.
  *
  * @param messages - Array of messages to repair
- * @returns New array with orphaned tool_results removed
+ * @returns New array with orphaned tool_use and tool_result blocks removed
  */
 export function repairToolPairing(messages) {
-    // First, collect all tool_use IDs
-    const toolUseIds = new Set();
-    for (const message of messages) {
+    // First pass: collect all tool_use IDs that appear BEFORE their tool_result
+    // Also track which tool_use IDs have their result in the IMMEDIATELY NEXT message
+    const validToolUseIds = new Set();
+    const allToolUseIds = new Set();
+    for (let i = 0; i < messages.length; i++) {
+        const message = messages[i];
         if (typeof message.content === 'string')
             continue;
-        for (const block of message.content) {
-            if (block.type === 'tool_use') {
-                toolUseIds.add(block.id);
+        // Check for tool_use blocks in assistant messages
+        if (message.role === 'assistant') {
+            const toolUseIdsInThisMessage = [];
+            for (const block of message.content) {
+                if (block.type === 'tool_use') {
+                    toolUseIdsInThisMessage.push(block.id);
+                    allToolUseIds.add(block.id);
+                }
+            }
+            // Check if the NEXT message contains tool_result for ALL these tool_use IDs
+            if (toolUseIdsInThisMessage.length > 0) {
+                // Next message may not exist if we're at the end of the array
+                const nextMessage = messages[i + 1];
+                if (nextMessage && typeof nextMessage.content !== 'string') {
+                    const toolResultIdsInNext = new Set();
+                    for (const block of nextMessage.content) {
+                        if (block.type === 'tool_result') {
+                            toolResultIdsInNext.add(block.toolUseId);
+                        }
+                    }
+                    // Mark tool_use IDs as valid only if their result is in the next message
+                    for (const id of toolUseIdsInThisMessage) {
+                        if (toolResultIdsInNext.has(id)) {
+                            validToolUseIds.add(id);
+                        }
+                    }
+                }
             }
         }
     }
-    // Now filter out orphaned tool_results
+    // Second pass: filter out orphaned blocks
     const repairedMessages = [];
     for (const message of messages) {
         if (typeof message.content === 'string') {
             repairedMessages.push(message);
             continue;
         }
-        // Filter content blocks to remove orphaned tool_results
+        // Filter content blocks to remove orphaned tool_use and tool_result
         const filteredBlocks = message.content.filter((block) => {
             if (block.type === 'tool_result') {
-                // Only keep if there's a matching tool_use
-                return toolUseIds.has(block.toolUseId);
+                // Only keep if there's a valid matching tool_use (that also has its result properly placed)
+                return validToolUseIds.has(block.toolUseId);
+            }
+            if (block.type === 'tool_use') {
+                // Only keep if this tool_use has its result in the immediately next message
+                return validToolUseIds.has(block.id);
             }
             return true;
         });

package/dist/providers/claude.js

@@ -43,6 +43,12 @@ export class ClaudeProvider {
         const { systemPrompt, anthropicMessages } = this.convertMessages(messages);
         const tools = this.convertTools(options?.tools);
         const thinking = this.convertThinking(options?.thinking);
+        // Calculate payload sizes for debugging (same as gemini-native.ts)
+        const debugPayload = {
+            systemChars: systemPrompt.length,
+            contentsChars: JSON.stringify(anthropicMessages).length,
+            toolsChars: JSON.stringify(tools).length,
+        };
         try {
             // Build request parameters
             const params = {
@@ -99,6 +105,7 @@ export class ClaudeProvider {
                     outputTokens: usage.output_tokens,
                     cacheReadTokens: usageWithCache.cache_read_input_tokens,
                     cacheCreationTokens: usageWithCache.cache_creation_input_tokens,
+                    debugPayload,
                 },
             };
         }

package/dist/providers/fireworks.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Fireworks AI LLM Provider
+ *
+ * Implements LLMProvider interface for Fireworks AI models.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createFireworksProvider({
+ *   model: 'accounts/fireworks/models/llama-v3p1-70b-instruct',
+ *   apiKey: process.env.FIREWORKS_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid Fireworks AI API key
+ * - Default model is accounts/fireworks/models/llama-v3p1-8b-instruct
+ * - Supports Llama, Mixtral, and fine-tuned models
+ */
+import type { ChatOptions } from './types.js';
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+/**
+ * Configuration for FireworksProvider
+ */
+export interface FireworksProviderConfig {
+    /** Fireworks AI API key (falls back to FIREWORKS_API_KEY env var) */
+    apiKey?: string;
+    /** Base URL for Fireworks API (default: https://api.fireworks.ai/inference) */
+    baseUrl?: string;
+    /** Default model to use (default: accounts/fireworks/models/llama-v3p1-8b-instruct) */
+    model?: string;
+    /** Default max tokens (default: 4096) */
+    maxTokens?: number;
+    /** Request timeout in milliseconds (default: 120000) */
+    timeout?: number;
+}
+/**
+ * Fireworks AI LLM Provider
+ *
+ * Provides streaming chat completion using Fireworks AI.
+ * Supports Llama, Mixtral, and custom fine-tuned models.
+ */
+export declare class FireworksProvider extends OpenAICompatibleProvider {
+    readonly name = "fireworks";
+    private readonly apiKey;
+    constructor(config?: FireworksProviderConfig);
+    /**
+     * Fireworks AI authentication with Bearer token
+     */
+    protected getAuthHeaders(): Record<string, string>;
+    /**
+     * Fireworks AI chat completions endpoint (OpenAI-compatible)
+     */
+    protected getEndpointPath(): string;
+    /**
+     * Fireworks AI uses standard OpenAI body format
+     */
+    protected buildProviderSpecificBody(_options?: ChatOptions): Record<string, unknown>;
+    /**
+     * Map HTTP errors with Fireworks AI-specific messages
+     */
+    protected mapHttpError(status: number, body: string, _model: string): ProviderError;
+    /**
+     * Map connection errors with Fireworks AI-specific messages
+     */
+    protected mapConnectionError(_error: Error): ProviderError;
+}
+/**
+ * Create a Fireworks AI provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (FIREWORKS_API_KEY)
+ * const provider = createFireworksProvider();
+ *
+ * // With explicit API key
+ * const provider = createFireworksProvider({ apiKey: 'fw_...' });
+ *
+ * // With custom model
+ * const provider = createFireworksProvider({
+ *   model: 'accounts/fireworks/models/llama-v3p1-70b-instruct'
+ * });
+ * ```
+ */
+export declare function createFireworksProvider(config?: FireworksProviderConfig): FireworksProvider;

package/dist/providers/fireworks.js

@@ -0,0 +1,123 @@
+/**
+ * Fireworks AI LLM Provider
+ *
+ * Implements LLMProvider interface for Fireworks AI models.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createFireworksProvider({
+ *   model: 'accounts/fireworks/models/llama-v3p1-70b-instruct',
+ *   apiKey: process.env.FIREWORKS_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid Fireworks AI API key
+ * - Default model is accounts/fireworks/models/llama-v3p1-8b-instruct
+ * - Supports Llama, Mixtral, and fine-tuned models
+ */
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+// Default configuration
+const DEFAULT_MODEL = 'accounts/fireworks/models/llama-v3p1-8b-instruct';
+const DEFAULT_BASE_URL = 'https://api.fireworks.ai/inference';
+/**
+ * Fireworks AI LLM Provider
+ *
+ * Provides streaming chat completion using Fireworks AI.
+ * Supports Llama, Mixtral, and custom fine-tuned models.
+ */
+export class FireworksProvider extends OpenAICompatibleProvider {
+    name = 'fireworks';
+    apiKey;
+    constructor(config = {}) {
+        const apiKey = config.apiKey ?? process.env.FIREWORKS_API_KEY;
+        if (!apiKey) {
+            throw new ProviderError('Fireworks AI API key not found. Set FIREWORKS_API_KEY environment variable or pass apiKey in config.', 'fireworks');
+        }
+        const baseConfig = {
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            model: config.model ?? DEFAULT_MODEL,
+            maxTokens: config.maxTokens,
+            timeout: config.timeout,
+        };
+        super(baseConfig);
+        this.apiKey = apiKey;
+    }
+    /**
+     * Fireworks AI authentication with Bearer token
+     */
+    getAuthHeaders() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+    }
+    /**
+     * Fireworks AI chat completions endpoint (OpenAI-compatible)
+     */
+    getEndpointPath() {
+        return '/v1/chat/completions';
+    }
+    /**
+     * Fireworks AI uses standard OpenAI body format
+     */
+    buildProviderSpecificBody(_options) {
+        return {};
+    }
+    /**
+     * Map HTTP errors with Fireworks AI-specific messages
+     */
+    mapHttpError(status, body, _model) {
+        let message = `Fireworks AI error (${String(status)})`;
+        try {
+            const parsed = JSON.parse(body);
+            if (parsed.error?.message) {
+                message = parsed.error.message;
+            }
+        }
+        catch {
+            message = body || message;
+        }
+        switch (status) {
+            case 401:
+                return new ProviderError('Invalid Fireworks AI API key. Check your FIREWORKS_API_KEY.', 'fireworks', 401);
+            case 403:
+                return new ProviderError('Access denied. Check your Fireworks AI API key permissions.', 'fireworks', 403);
+            case 429:
+                return new ProviderError('Fireworks AI rate limit exceeded. Please wait and try again.', 'fireworks', 429);
+            case 500:
+            case 502:
+            case 503:
+                return new ProviderError('Fireworks AI service temporarily unavailable. Please try again later.', 'fireworks', status);
+            default:
+                return new ProviderError(message, 'fireworks', status);
+        }
+    }
+    /**
+     * Map connection errors with Fireworks AI-specific messages
+     */
+    mapConnectionError(_error) {
+        return new ProviderError('Failed to connect to Fireworks AI API. Check your internet connection.', 'fireworks');
+    }
+}
+/**
+ * Create a Fireworks AI provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (FIREWORKS_API_KEY)
+ * const provider = createFireworksProvider();
+ *
+ * // With explicit API key
+ * const provider = createFireworksProvider({ apiKey: 'fw_...' });
+ *
+ * // With custom model
+ * const provider = createFireworksProvider({
+ *   model: 'accounts/fireworks/models/llama-v3p1-70b-instruct'
+ * });
+ * ```
+ */
+export function createFireworksProvider(config = {}) {
+    return new FireworksProvider(config);
+}

package/dist/providers/gemini-native.d.ts

@@ -0,0 +1,86 @@
+/**
+ * GeminiNativeProvider - Native Google Gen AI SDK implementation
+ *
+ * Uses the native @google/genai SDK instead of OpenAI-compatible endpoint.
+ * This enables proper support for Gemini 3 models with thought signatures.
+ *
+ * @example
+ * ```typescript
+ * const provider = new GeminiNativeProvider({
+ *   apiKey: process.env.GOOGLE_AI_API_KEY,
+ * });
+ *
+ * const agent = new Agent({ provider });
+ * ```
+ */
+import type { LLMProvider, Message, ChatOptions, StreamChunk } from './types.js';
+/**
+ * Configuration for GeminiNativeProvider
+ */
+export interface GeminiNativeProviderConfig {
+    /**
+     * Google AI API key
+     */
+    apiKey: string;
+    /**
+     * Default model to use
+     * @default 'gemini-2.5-flash'
+     */
+    model?: string;
+    /**
+     * Default max tokens
+     * @default 4096
+     */
+    maxTokens?: number;
+}
+/**
+ * GeminiNativeProvider implements LLMProvider using the native Google Gen AI SDK
+ *
+ * Benefits over OpenAI-compatible endpoint:
+ * - Automatic thought signature handling for Gemini 3
+ * - Native streaming support
+ * - Full access to Gemini-specific features
+ */
+export declare class GeminiNativeProvider implements LLMProvider {
+    readonly name = "gemini";
+    private readonly client;
+    private readonly defaultModel;
+    private readonly defaultMaxTokens;
+    constructor(config: GeminiNativeProviderConfig);
+    /**
+     * Send messages and stream the response
+     */
+    chat(messages: Message[], options?: ChatOptions): AsyncIterable<StreamChunk>;
+    /**
+     * Count tokens in messages (approximation)
+     */
+    countTokens(messages: Message[]): Promise<number>;
+    /**
+     * Convert our Message format to Google's format
+     */
+    private convertMessages;
+    /**
+     * Convert content to Google's Part format
+     */
+    private convertContent;
+    /**
+     * Extract tool name from tool_use block that matches the given toolUseId
+     */
+    private extractToolName;
+    /**
+     * Convert our ToolDefinition to Google's FunctionDeclaration format
+     */
+    private convertTools;
+    /**
+     * Process a streaming chunk into StreamChunks
+     */
+    private processChunk;
+    /**
+     * Map errors to ProviderError
+     */
+    private mapError;
+}
+/**
+ * Create a GeminiNativeProvider with API key from environment
+ */
+export declare function createGeminiNativeProvider(config?: Partial<GeminiNativeProviderConfig>): GeminiNativeProvider;