@compilr-dev/agents 0.0.1

package/dist/rate-limit/provider-wrapper.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Provider Wrapper with Rate Limiting and Retry
+ *
+ * Wraps an LLMProvider with automatic rate limiting and retry functionality.
+ */
+import type { LLMProvider, Message, ChatOptions, StreamChunk } from '../providers/types.js';
+import type { RateLimiter, RateLimitRetryConfig } from './types.js';
+/**
+ * Wrapper that adds rate limiting and retry to any LLMProvider
+ *
+ * @example
+ * ```typescript
+ * const provider = new ClaudeProvider({ apiKey: 'xxx' });
+ * const wrapped = new RateLimitedProvider(provider, {
+ *   rateLimit: {
+ *     requestsPerMinute: 60,
+ *     tokensPerMinute: 100000,
+ *   },
+ *   retry: {
+ *     maxRetries: 3,
+ *     baseDelayMs: 1000,
+ *   },
+ * });
+ *
+ * // Use wrapped provider like normal
+ * const agent = new Agent({ provider: wrapped });
+ * ```
+ */
+export declare class RateLimitedProvider implements LLMProvider {
+    readonly name: string;
+    private readonly provider;
+    private readonly rateLimiter;
+    private readonly retryConfig;
+    constructor(provider: LLMProvider, config?: RateLimitRetryConfig);
+    /**
+     * Get the rate limiter instance for statistics
+     */
+    getRateLimiter(): RateLimiter;
+    /**
+     * Send messages with rate limiting and retry
+     */
+    chat(messages: Message[], options?: ChatOptions): AsyncIterable<StreamChunk>;
+    /**
+     * Count tokens with rate limiting
+     */
+    countTokens(messages: Message[]): Promise<number>;
+    /**
+     * Estimate tokens from messages (rough approximation)
+     */
+    private estimateTokens;
+}
+/**
+ * Create a rate-limited provider wrapper
+ *
+ * @param provider - The base LLM provider
+ * @param config - Rate limit and retry configuration
+ * @returns Wrapped provider with rate limiting and retry
+ *
+ * @example
+ * ```typescript
+ * const provider = createClaudeProvider();
+ * const rateLimited = wrapWithRateLimit(provider, {
+ *   rateLimit: { requestsPerMinute: 60 },
+ *   retry: { maxRetries: 3 },
+ * });
+ * ```
+ */
+export declare function wrapWithRateLimit(provider: LLMProvider, config?: RateLimitRetryConfig): RateLimitedProvider;
+/**
+ * Default rate limits for known providers
+ */
+export declare const ProviderRateLimits: {
+    /**
+     * Anthropic Claude API limits (Tier 1)
+     * @see https://docs.anthropic.com/en/api/rate-limits
+     */
+    readonly claude: {
+        readonly tier1: {
+            readonly requestsPerMinute: 50;
+            readonly tokensPerMinute: 40000;
+        };
+        readonly tier2: {
+            readonly requestsPerMinute: 1000;
+            readonly tokensPerMinute: 80000;
+        };
+        readonly tier3: {
+            readonly requestsPerMinute: 2000;
+            readonly tokensPerMinute: 160000;
+        };
+        readonly tier4: {
+            readonly requestsPerMinute: 4000;
+            readonly tokensPerMinute: 400000;
+        };
+    };
+    /**
+     * OpenAI GPT-4 API limits (approximate)
+     */
+    readonly openai: {
+        readonly gpt4: {
+            readonly requestsPerMinute: 500;
+            readonly tokensPerMinute: 10000;
+        };
+        readonly gpt4Turbo: {
+            readonly requestsPerMinute: 500;
+            readonly tokensPerMinute: 30000;
+        };
+        readonly gpt35Turbo: {
+            readonly requestsPerMinute: 3500;
+            readonly tokensPerMinute: 90000;
+        };
+    };
+};

package/dist/rate-limit/provider-wrapper.js

@@ -0,0 +1,201 @@
+/**
+ * Provider Wrapper with Rate Limiting and Retry
+ *
+ * Wraps an LLMProvider with automatic rate limiting and retry functionality.
+ */
+import { createRateLimiter } from './limiter.js';
+import { withRetry } from './retry.js';
+/**
+ * Wrapper that adds rate limiting and retry to any LLMProvider
+ *
+ * @example
+ * ```typescript
+ * const provider = new ClaudeProvider({ apiKey: 'xxx' });
+ * const wrapped = new RateLimitedProvider(provider, {
+ *   rateLimit: {
+ *     requestsPerMinute: 60,
+ *     tokensPerMinute: 100000,
+ *   },
+ *   retry: {
+ *     maxRetries: 3,
+ *     baseDelayMs: 1000,
+ *   },
+ * });
+ *
+ * // Use wrapped provider like normal
+ * const agent = new Agent({ provider: wrapped });
+ * ```
+ */
+export class RateLimitedProvider {
+    name;
+    provider;
+    rateLimiter;
+    retryConfig;
+    constructor(provider, config = {}) {
+        this.provider = provider;
+        this.name = `${provider.name}:rate-limited`;
+        this.rateLimiter = config.rateLimit ? createRateLimiter(config.rateLimit) : createRateLimiter();
+        this.retryConfig = config.retry ?? {};
+    }
+    /**
+     * Get the rate limiter instance for statistics
+     */
+    getRateLimiter() {
+        return this.rateLimiter;
+    }
+    /**
+     * Send messages with rate limiting and retry
+     */
+    async *chat(messages, options) {
+        // Estimate tokens for rate limiting (rough estimate: 4 chars = 1 token)
+        const estimatedInputTokens = this.estimateTokens(messages);
+        const estimatedOutputTokens = options?.maxTokens ?? 4096;
+        const estimatedTotalTokens = estimatedInputTokens + estimatedOutputTokens;
+        // Acquire rate limit token
+        const acquireResult = await this.rateLimiter.acquire(estimatedTotalTokens);
+        if (!acquireResult.acquired) {
+            throw new Error(`Failed to acquire rate limit token after ${String(acquireResult.waitedMs)}ms`);
+        }
+        try {
+            // Use retry wrapper for the actual API call
+            // For streaming, we need to handle retry differently
+            let actualUsage;
+            const streamWithRetry = async function* (provider, retryConfig) {
+                // Collect chunks and re-yield them
+                // On retry, we restart from the beginning
+                const executeStream = async () => {
+                    const chunks = [];
+                    for await (const chunk of provider.chat(messages, options)) {
+                        chunks.push(chunk);
+                        if (chunk.type === 'done' && chunk.usage) {
+                            actualUsage = chunk.usage;
+                        }
+                    }
+                    return chunks;
+                };
+                // Wrap the stream execution in retry logic
+                const chunks = await withRetry(executeStream, retryConfig);
+                // Yield all collected chunks
+                for (const chunk of chunks) {
+                    yield chunk;
+                }
+            };
+            // Yield chunks from the retried stream
+            yield* streamWithRetry(this.provider, this.retryConfig);
+            // Report actual usage to rate limiter
+            if (actualUsage) {
+                const totalTokens = actualUsage.inputTokens + actualUsage.outputTokens;
+                this.rateLimiter.reportUsage(totalTokens);
+            }
+        }
+        finally {
+            // Release the concurrent slot
+            this.rateLimiter.release();
+        }
+    }
+    /**
+     * Count tokens with rate limiting
+     */
+    async countTokens(messages) {
+        if (!this.provider.countTokens) {
+            // Fallback estimation
+            return this.estimateTokens(messages);
+        }
+        const countTokensFn = this.provider.countTokens.bind(this.provider);
+        return withRetry(() => countTokensFn(messages), this.retryConfig);
+    }
+    /**
+     * Estimate tokens from messages (rough approximation)
+     */
+    estimateTokens(messages) {
+        let charCount = 0;
+        for (const msg of messages) {
+            if (typeof msg.content === 'string') {
+                charCount += msg.content.length;
+            }
+            else {
+                for (const block of msg.content) {
+                    switch (block.type) {
+                        case 'text':
+                            charCount += block.text.length;
+                            break;
+                        case 'tool_use':
+                            charCount += JSON.stringify(block.input).length;
+                            break;
+                        case 'tool_result':
+                            charCount += block.content.length;
+                            break;
+                        case 'thinking':
+                            charCount += block.thinking.length;
+                            break;
+                    }
+                }
+            }
+        }
+        // Rough estimate: 4 characters per token
+        return Math.ceil(charCount / 4);
+    }
+}
+/**
+ * Create a rate-limited provider wrapper
+ *
+ * @param provider - The base LLM provider
+ * @param config - Rate limit and retry configuration
+ * @returns Wrapped provider with rate limiting and retry
+ *
+ * @example
+ * ```typescript
+ * const provider = createClaudeProvider();
+ * const rateLimited = wrapWithRateLimit(provider, {
+ *   rateLimit: { requestsPerMinute: 60 },
+ *   retry: { maxRetries: 3 },
+ * });
+ * ```
+ */
+export function wrapWithRateLimit(provider, config) {
+    return new RateLimitedProvider(provider, config);
+}
+/**
+ * Default rate limits for known providers
+ */
+export const ProviderRateLimits = {
+    /**
+     * Anthropic Claude API limits (Tier 1)
+     * @see https://docs.anthropic.com/en/api/rate-limits
+     */
+    claude: {
+        tier1: {
+            requestsPerMinute: 50,
+            tokensPerMinute: 40000,
+        },
+        tier2: {
+            requestsPerMinute: 1000,
+            tokensPerMinute: 80000,
+        },
+        tier3: {
+            requestsPerMinute: 2000,
+            tokensPerMinute: 160000,
+        },
+        tier4: {
+            requestsPerMinute: 4000,
+            tokensPerMinute: 400000,
+        },
+    },
+    /**
+     * OpenAI GPT-4 API limits (approximate)
+     */
+    openai: {
+        gpt4: {
+            requestsPerMinute: 500,
+            tokensPerMinute: 10000,
+        },
+        gpt4Turbo: {
+            requestsPerMinute: 500,
+            tokensPerMinute: 30000,
+        },
+        gpt35Turbo: {
+            requestsPerMinute: 3500,
+            tokensPerMinute: 90000,
+        },
+    },
+};

package/dist/rate-limit/retry.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Automatic Retry with Exponential Backoff
+ *
+ * Provides retry functionality for LLM API calls with:
+ * - Exponential backoff
+ * - Jitter to prevent thundering herd
+ * - Retry-After header support
+ * - Integration with rate limiter
+ */
+import type { RetryConfig, RateLimiter } from './types.js';
+/**
+ * Retry a function with exponential backoff
+ *
+ * @param fn - Function to retry
+ * @param config - Retry configuration
+ * @returns Result of the function
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => provider.chat(messages, options),
+ *   {
+ *     maxRetries: 3,
+ *     baseDelayMs: 1000,
+ *     onRetry: (attempt, error, delay) => {
+ *       console.log(`Retry ${attempt} after ${delay}ms: ${error.message}`);
+ *     },
+ *   }
+ * );
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, config?: RetryConfig): Promise<T>;
+/**
+ * Create a retry wrapper that also integrates with rate limiting
+ *
+ * @param rateLimiter - Rate limiter instance
+ * @param config - Retry configuration
+ * @returns Function wrapper with retry and rate limiting
+ *
+ * @example
+ * ```typescript
+ * const limiter = createRateLimiter({ requestsPerMinute: 60 });
+ * const retryWithLimit = createRetryWithRateLimit(limiter, { maxRetries: 3 });
+ *
+ * const result = await retryWithLimit(
+ *   () => provider.chat(messages, options),
+ *   1000 // estimated tokens
+ * );
+ * ```
+ */
+export declare function createRetryWithRateLimit(rateLimiter: RateLimiter, config?: RetryConfig): <T>(fn: () => Promise<T>, estimatedTokens?: number) => Promise<T>;
+/**
+ * Retry configuration builder for common scenarios
+ */
+export declare const RetryPresets: {
+    /**
+     * Conservative retry: few retries, long delays
+     */
+    readonly conservative: () => RetryConfig;
+    /**
+     * Aggressive retry: more retries, shorter delays
+     */
+    readonly aggressive: () => RetryConfig;
+    /**
+     * No retry: fail immediately
+     */
+    readonly none: () => RetryConfig;
+    /**
+     * Respect API limits: use Retry-After headers when available
+     */
+    readonly respectful: () => RetryConfig;
+};
+/**
+ * Retry statistics collector
+ */
+export declare class RetryStats {
+    private attempts;
+    private successes;
+    private failures;
+    private retries;
+    private totalDelayMs;
+    private lastError?;
+    /**
+     * Create retry config that tracks statistics
+     */
+    createConfig(baseConfig?: RetryConfig): RetryConfig;
+    /**
+     * Record an attempt outcome
+     */
+    recordAttempt(success: boolean): void;
+    /**
+     * Get statistics
+     */
+    getStats(): {
+        attempts: number;
+        successes: number;
+        failures: number;
+        retries: number;
+        totalDelayMs: number;
+        successRate: number;
+        averageRetries: number;
+        lastError?: string;
+    };
+    /**
+     * Reset statistics
+     */
+    reset(): void;
+}

package/dist/rate-limit/retry.js

@@ -0,0 +1,287 @@
+/**
+ * Automatic Retry with Exponential Backoff
+ *
+ * Provides retry functionality for LLM API calls with:
+ * - Exponential backoff
+ * - Jitter to prevent thundering herd
+ * - Retry-After header support
+ * - Integration with rate limiter
+ */
+import { isProviderError } from '../errors.js';
+/**
+ * Default retry configuration
+ */
+const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 60000,
+    backoffMultiplier: 2,
+    jitter: true,
+};
+/**
+ * Sleep for a specified duration
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Default function to determine if an error is retryable
+ */
+function defaultIsRetryable(error) {
+    // Check for ProviderError with retryable status
+    if (isProviderError(error)) {
+        return error.isRetryable();
+    }
+    // Check for network/connection errors
+    const message = error.message.toLowerCase();
+    if (message.includes('network') ||
+        message.includes('connection') ||
+        message.includes('timeout') ||
+        message.includes('econnreset') ||
+        message.includes('econnrefused') ||
+        message.includes('socket hang up')) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Extract Retry-After header value in milliseconds
+ */
+function extractRetryAfter(error) {
+    // Check if error has a response with Retry-After header
+    const anyError = error;
+    let retryAfter;
+    // Try to get from response headers
+    if (anyError.response?.headers?.get) {
+        retryAfter = anyError.response.headers.get('retry-after');
+    }
+    else if (anyError.headers?.['retry-after']) {
+        retryAfter = anyError.headers['retry-after'];
+    }
+    if (!retryAfter)
+        return undefined;
+    // Retry-After can be a number of seconds or an HTTP date
+    const seconds = parseInt(retryAfter, 10);
+    if (!isNaN(seconds)) {
+        return seconds * 1000;
+    }
+    // Try parsing as HTTP date
+    const date = new Date(retryAfter);
+    if (!isNaN(date.getTime())) {
+        return Math.max(0, date.getTime() - Date.now());
+    }
+    return undefined;
+}
+/**
+ * Calculate delay for a retry attempt
+ */
+function calculateDelay(attempt, config, retryAfterMs) {
+    // Use Retry-After if available and reasonable
+    if (retryAfterMs !== undefined && retryAfterMs > 0 && retryAfterMs <= config.maxDelayMs) {
+        return retryAfterMs;
+    }
+    // Exponential backoff: baseDelay * (multiplier ^ attempt)
+    let delay = config.baseDelayMs * Math.pow(config.backoffMultiplier, attempt);
+    // Add jitter (±25%)
+    if (config.jitter) {
+        const jitterRange = delay * 0.25;
+        delay = delay + (Math.random() * 2 - 1) * jitterRange;
+    }
+    // Cap at maxDelay
+    return Math.min(delay, config.maxDelayMs);
+}
+/**
+ * Retry a function with exponential backoff
+ *
+ * @param fn - Function to retry
+ * @param config - Retry configuration
+ * @returns Result of the function
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => provider.chat(messages, options),
+ *   {
+ *     maxRetries: 3,
+ *     baseDelayMs: 1000,
+ *     onRetry: (attempt, error, delay) => {
+ *       console.log(`Retry ${attempt} after ${delay}ms: ${error.message}`);
+ *     },
+ *   }
+ * );
+ * ```
+ */
+export async function withRetry(fn, config = {}) {
+    const mergedConfig = {
+        ...DEFAULT_RETRY_CONFIG,
+        ...config,
+    };
+    const isRetryable = config.isRetryable ?? defaultIsRetryable;
+    let lastError;
+    for (let attempt = 0; attempt <= mergedConfig.maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // Check if we should retry
+            const shouldRetry = attempt < mergedConfig.maxRetries && isRetryable(lastError);
+            if (!shouldRetry) {
+                throw lastError;
+            }
+            // Calculate delay
+            const retryAfterMs = extractRetryAfter(lastError);
+            const delayMs = calculateDelay(attempt, mergedConfig, retryAfterMs);
+            // Call onRetry callback
+            if (config.onRetry) {
+                config.onRetry(attempt + 1, lastError, delayMs);
+            }
+            // Wait before retrying
+            await sleep(delayMs);
+        }
+    }
+    // Should never reach here, but TypeScript needs it
+    throw lastError ?? new Error('Retry failed with no error captured');
+}
+/**
+ * Create a retry wrapper that also integrates with rate limiting
+ *
+ * @param rateLimiter - Rate limiter instance
+ * @param config - Retry configuration
+ * @returns Function wrapper with retry and rate limiting
+ *
+ * @example
+ * ```typescript
+ * const limiter = createRateLimiter({ requestsPerMinute: 60 });
+ * const retryWithLimit = createRetryWithRateLimit(limiter, { maxRetries: 3 });
+ *
+ * const result = await retryWithLimit(
+ *   () => provider.chat(messages, options),
+ *   1000 // estimated tokens
+ * );
+ * ```
+ */
+export function createRetryWithRateLimit(rateLimiter, config = {}) {
+    return async (fn, estimatedTokens) => {
+        // Acquire rate limit token before attempting
+        const acquireResult = await rateLimiter.acquire(estimatedTokens);
+        if (!acquireResult.acquired) {
+            throw new Error(`Failed to acquire rate limit token after ${String(acquireResult.waitedMs)}ms`);
+        }
+        try {
+            // Execute with retry
+            return await withRetry(fn, config);
+        }
+        finally {
+            // Always release the concurrent slot
+            rateLimiter.release();
+        }
+    };
+}
+/**
+ * Retry configuration builder for common scenarios
+ */
+export const RetryPresets = {
+    /**
+     * Conservative retry: few retries, long delays
+     */
+    conservative: () => ({
+        maxRetries: 2,
+        baseDelayMs: 2000,
+        maxDelayMs: 30000,
+        backoffMultiplier: 3,
+        jitter: true,
+    }),
+    /**
+     * Aggressive retry: more retries, shorter delays
+     */
+    aggressive: () => ({
+        maxRetries: 5,
+        baseDelayMs: 500,
+        maxDelayMs: 10000,
+        backoffMultiplier: 1.5,
+        jitter: true,
+    }),
+    /**
+     * No retry: fail immediately
+     */
+    none: () => ({
+        maxRetries: 0,
+    }),
+    /**
+     * Respect API limits: use Retry-After headers when available
+     */
+    respectful: () => ({
+        maxRetries: 3,
+        baseDelayMs: 1000,
+        maxDelayMs: 120000, // Allow longer waits based on Retry-After
+        backoffMultiplier: 2,
+        jitter: true,
+    }),
+};
+/**
+ * Retry statistics collector
+ */
+export class RetryStats {
+    attempts = 0;
+    successes = 0;
+    failures = 0;
+    retries = 0;
+    totalDelayMs = 0;
+    lastError;
+    /**
+     * Create retry config that tracks statistics
+     */
+    createConfig(baseConfig = {}) {
+        return {
+            ...baseConfig,
+            onRetry: (attempt, error, delayMs) => {
+                this.retries++;
+                this.totalDelayMs += delayMs;
+                this.lastError = error;
+                // Call original onRetry if provided
+                if (baseConfig.onRetry) {
+                    baseConfig.onRetry(attempt, error, delayMs);
+                }
+            },
+        };
+    }
+    /**
+     * Record an attempt outcome
+     */
+    recordAttempt(success) {
+        this.attempts++;
+        if (success) {
+            this.successes++;
+        }
+        else {
+            this.failures++;
+        }
+    }
+    /**
+     * Get statistics
+     */
+    getStats() {
+        return {
+            attempts: this.attempts,
+            successes: this.successes,
+            failures: this.failures,
+            retries: this.retries,
+            totalDelayMs: this.totalDelayMs,
+            successRate: this.attempts > 0 ? this.successes / this.attempts : 0,
+            averageRetries: this.attempts > 0 ? this.retries / this.attempts : 0,
+            lastError: this.lastError?.message,
+        };
+    }
+    /**
+     * Reset statistics
+     */
+    reset() {
+        this.attempts = 0;
+        this.successes = 0;
+        this.failures = 0;
+        this.retries = 0;
+        this.totalDelayMs = 0;
+        this.lastError = undefined;
+    }
+}