@compilr-dev/agents 0.0.1

package/dist/providers/types.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Core types for LLM providers
+ */
+/**
+ * Message roles in a conversation
+ */
+export type MessageRole = 'user' | 'assistant' | 'system';
+/**
+ * Content block types
+ */
+export type ContentBlockType = 'text' | 'tool_use' | 'tool_result' | 'thinking';
+/**
+ * Text content block
+ */
+export interface TextBlock {
+    type: 'text';
+    text: string;
+}
+/**
+ * Tool use content block (AI wants to call a tool)
+ */
+export interface ToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+/**
+ * Tool result content block (result of a tool call)
+ */
+export interface ToolResultBlock {
+    type: 'tool_result';
+    toolUseId: string;
+    content: string;
+    isError?: boolean;
+}
+/**
+ * Thinking content block (Claude's reasoning process)
+ */
+export interface ThinkingBlock {
+    type: 'thinking';
+    thinking: string;
+    /**
+     * Encrypted signature for verification when passing back to API
+     */
+    signature?: string;
+}
+/**
+ * Union of all content block types
+ */
+export type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock | ThinkingBlock;
+/**
+ * A message in a conversation
+ */
+export interface Message {
+    role: MessageRole;
+    content: string | ContentBlock[];
+}
+/**
+ * Token usage from an LLM response (returned on 'done' chunks)
+ */
+export interface LLMUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+}
+/**
+ * Streaming chunk types
+ */
+export interface StreamChunk {
+    type: 'text' | 'tool_use_start' | 'tool_use_delta' | 'tool_use_end' | 'thinking_start' | 'thinking_delta' | 'thinking_end' | 'done';
+    text?: string;
+    toolUse?: {
+        id: string;
+        name: string;
+        input?: Record<string, unknown>;
+    };
+    /**
+     * Thinking block data (for thinking_start/thinking_end)
+     */
+    thinking?: {
+        thinking?: string;
+        signature?: string;
+    };
+    /**
+     * Token usage (only present on 'done' chunks)
+     */
+    usage?: LLMUsage;
+    /**
+     * Model that generated this response (only present on 'done' chunks)
+     */
+    model?: string;
+}
+/**
+ * Extended thinking configuration
+ *
+ * @see https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking
+ */
+export interface ThinkingConfig {
+    /**
+     * Enable or disable extended thinking
+     */
+    type: 'enabled' | 'disabled';
+    /**
+     * Token budget for thinking (minimum 1024, must be less than maxTokens)
+     */
+    budgetTokens: number;
+}
+/**
+ * Options for chat requests
+ */
+export interface ChatOptions {
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+    stopSequences?: string[];
+    tools?: ToolDefinition[];
+    /**
+     * Extended thinking configuration (Claude-specific)
+     *
+     * When enabled, Claude will show its reasoning process before
+     * providing the final response. Requires budget_tokens >= 1024.
+     *
+     * @example
+     * ```typescript
+     * thinking: { type: 'enabled', budgetTokens: 10000 }
+     * ```
+     */
+    thinking?: ThinkingConfig;
+}
+/**
+ * Tool definition for the LLM
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * Result of a tool execution
+ */
+export interface ToolResult {
+    toolUseId: string;
+    result: unknown;
+    isError?: boolean;
+}
+/**
+ * LLM Provider interface - all providers must implement this
+ */
+export interface LLMProvider {
+    /**
+     * Provider name (e.g., 'claude', 'openai', 'gemini')
+     */
+    readonly name: string;
+    /**
+     * Send messages and get a streaming response
+     */
+    chat(messages: Message[], options?: ChatOptions): AsyncIterable<StreamChunk>;
+    /**
+     * Count tokens in messages (optional, provider-specific)
+     */
+    countTokens?(messages: Message[]): Promise<number>;
+}

package/dist/providers/types.js

@@ -0,0 +1,4 @@
+/**
+ * Core types for LLM providers
+ */
+export {};

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

@@ -0,0 +1,45 @@
+/**
+ * Rate Limiting & Automatic Retry
+ *
+ * This module provides:
+ * - Token bucket rate limiter for API calls
+ * - Automatic retry with exponential backoff
+ * - Provider wrapper combining both features
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createRateLimiter,
+ *   withRetry,
+ *   wrapWithRateLimit,
+ *   RetryPresets,
+ *   ProviderRateLimits,
+ * } from '@compilr-dev/agents';
+ *
+ * // Use rate limiter directly
+ * const limiter = createRateLimiter({
+ *   requestsPerMinute: 60,
+ *   tokensPerMinute: 100000,
+ * });
+ *
+ * // Wrap existing provider
+ * const provider = createClaudeProvider();
+ * const rateLimited = wrapWithRateLimit(provider, {
+ *   rateLimit: ProviderRateLimits.claude.tier1,
+ *   retry: RetryPresets.respectful(),
+ * });
+ *
+ * // Use with retry only
+ * const result = await withRetry(
+ *   () => someApiCall(),
+ *   { maxRetries: 3, baseDelayMs: 1000 }
+ * );
+ * ```
+ *
+ * @module rate-limit
+ */
+export type { RateLimiterConfig, RateLimiterStats, RetryConfig, RateLimitRetryConfig, AcquireResult, RateLimiter, } from './types.js';
+export { RateLimitExceededError, isRateLimitExceededError } from './types.js';
+export { TokenBucketRateLimiter, createRateLimiter, createNoopRateLimiter } from './limiter.js';
+export { withRetry, createRetryWithRateLimit, RetryPresets, RetryStats } from './retry.js';
+export { RateLimitedProvider, wrapWithRateLimit, ProviderRateLimits } from './provider-wrapper.js';

package/dist/rate-limit/index.js

@@ -0,0 +1,47 @@
+/**
+ * Rate Limiting & Automatic Retry
+ *
+ * This module provides:
+ * - Token bucket rate limiter for API calls
+ * - Automatic retry with exponential backoff
+ * - Provider wrapper combining both features
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createRateLimiter,
+ *   withRetry,
+ *   wrapWithRateLimit,
+ *   RetryPresets,
+ *   ProviderRateLimits,
+ * } from '@compilr-dev/agents';
+ *
+ * // Use rate limiter directly
+ * const limiter = createRateLimiter({
+ *   requestsPerMinute: 60,
+ *   tokensPerMinute: 100000,
+ * });
+ *
+ * // Wrap existing provider
+ * const provider = createClaudeProvider();
+ * const rateLimited = wrapWithRateLimit(provider, {
+ *   rateLimit: ProviderRateLimits.claude.tier1,
+ *   retry: RetryPresets.respectful(),
+ * });
+ *
+ * // Use with retry only
+ * const result = await withRetry(
+ *   () => someApiCall(),
+ *   { maxRetries: 3, baseDelayMs: 1000 }
+ * );
+ * ```
+ *
+ * @module rate-limit
+ */
+export { RateLimitExceededError, isRateLimitExceededError } from './types.js';
+// Rate Limiter
+export { TokenBucketRateLimiter, createRateLimiter, createNoopRateLimiter } from './limiter.js';
+// Retry
+export { withRetry, createRetryWithRateLimit, RetryPresets, RetryStats } from './retry.js';
+// Provider Wrapper
+export { RateLimitedProvider, wrapWithRateLimit, ProviderRateLimits } from './provider-wrapper.js';

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

@@ -0,0 +1,104 @@
+/**
+ * Token Bucket Rate Limiter
+ *
+ * Implements a token bucket algorithm for rate limiting API requests.
+ * Supports both request-based and token-based limits.
+ */
+import type { RateLimiterConfig, RateLimiterStats, RateLimiter, AcquireResult } from './types.js';
+/**
+ * Token bucket rate limiter implementation
+ *
+ * Uses the token bucket algorithm:
+ * - Tokens are added at a constant rate (refill rate)
+ * - Each request consumes tokens
+ * - If insufficient tokens, request waits or fails
+ *
+ * @example
+ * ```typescript
+ * const limiter = new TokenBucketRateLimiter({
+ *   requestsPerMinute: 60,
+ *   tokensPerMinute: 100000,
+ *   maxConcurrent: 5,
+ * });
+ *
+ * // Before making a request
+ * await limiter.acquire(1000); // estimated tokens
+ *
+ * try {
+ *   const result = await makeRequest();
+ *   limiter.reportUsage(actualTokens);
+ * } finally {
+ *   limiter.release();
+ * }
+ * ```
+ */
+export declare class TokenBucketRateLimiter implements RateLimiter {
+    private readonly config;
+    private requestTokens;
+    private lastRequestRefill;
+    private llmTokens;
+    private lastTokenRefill;
+    private concurrent;
+    private totalRequests;
+    private totalTokens;
+    private rateLimitHits;
+    private totalWaitTimeMs;
+    private waiters;
+    constructor(config?: RateLimiterConfig);
+    /**
+     * Acquire permission to make a request
+     */
+    acquire(estimatedTokens?: number): Promise<AcquireResult>;
+    /**
+     * Release a concurrent request slot
+     */
+    release(): void;
+    /**
+     * Report actual token usage
+     */
+    reportUsage(tokens: number): void;
+    /**
+     * Get current statistics
+     */
+    getStats(): RateLimiterStats;
+    /**
+     * Reset the rate limiter
+     */
+    reset(): void;
+    /**
+     * Check if a request can be made immediately
+     */
+    canAcquire(estimatedTokens?: number): boolean;
+    /**
+     * Refill token buckets based on elapsed time
+     */
+    private refill;
+    /**
+     * Check if can acquire without refilling
+     */
+    private canAcquireNow;
+    /**
+     * Actually acquire the tokens
+     */
+    private doAcquire;
+    /**
+     * Estimate wait time until tokens are available
+     */
+    private estimateWaitTime;
+    /**
+     * Wait and try to acquire
+     */
+    private waitAndAcquire;
+    /**
+     * Process waiting requests
+     */
+    private processWaiters;
+}
+/**
+ * Create a rate limiter with the given configuration
+ */
+export declare function createRateLimiter(config?: RateLimiterConfig): RateLimiter;
+/**
+ * Create a no-op rate limiter (for testing or unlimited access)
+ */
+export declare function createNoopRateLimiter(): RateLimiter;

package/dist/rate-limit/limiter.js

@@ -0,0 +1,326 @@
+/**
+ * Token Bucket Rate Limiter
+ *
+ * Implements a token bucket algorithm for rate limiting API requests.
+ * Supports both request-based and token-based limits.
+ */
+import { RateLimitExceededError } from './types.js';
+/**
+ * Default configuration values
+ */
+const DEFAULTS = {
+    requestsPerMinute: 60,
+    tokensPerMinute: 0,
+    maxConcurrent: 0,
+    throwOnLimit: false,
+};
+/**
+ * Token bucket rate limiter implementation
+ *
+ * Uses the token bucket algorithm:
+ * - Tokens are added at a constant rate (refill rate)
+ * - Each request consumes tokens
+ * - If insufficient tokens, request waits or fails
+ *
+ * @example
+ * ```typescript
+ * const limiter = new TokenBucketRateLimiter({
+ *   requestsPerMinute: 60,
+ *   tokensPerMinute: 100000,
+ *   maxConcurrent: 5,
+ * });
+ *
+ * // Before making a request
+ * await limiter.acquire(1000); // estimated tokens
+ *
+ * try {
+ *   const result = await makeRequest();
+ *   limiter.reportUsage(actualTokens);
+ * } finally {
+ *   limiter.release();
+ * }
+ * ```
+ */
+export class TokenBucketRateLimiter {
+    config;
+    // Request bucket
+    requestTokens;
+    lastRequestRefill;
+    // LLM token bucket
+    llmTokens;
+    lastTokenRefill;
+    // Concurrent request tracking
+    concurrent = 0;
+    // Statistics
+    totalRequests = 0;
+    totalTokens = 0;
+    rateLimitHits = 0;
+    totalWaitTimeMs = 0;
+    // Pending waiters queue
+    waiters = [];
+    constructor(config = {}) {
+        this.config = {
+            requestsPerMinute: config.requestsPerMinute ?? DEFAULTS.requestsPerMinute,
+            tokensPerMinute: config.tokensPerMinute ?? DEFAULTS.tokensPerMinute,
+            maxConcurrent: config.maxConcurrent ?? DEFAULTS.maxConcurrent,
+            throwOnLimit: config.throwOnLimit ?? DEFAULTS.throwOnLimit,
+        };
+        // Initialize buckets to full capacity
+        this.requestTokens = this.config.requestsPerMinute;
+        this.llmTokens = this.config.tokensPerMinute;
+        this.lastRequestRefill = Date.now();
+        this.lastTokenRefill = Date.now();
+    }
+    /**
+     * Acquire permission to make a request
+     */
+    async acquire(estimatedTokens = 0) {
+        const startTime = Date.now();
+        // Refill buckets
+        this.refill();
+        // Check if we can acquire immediately
+        if (this.canAcquireNow(estimatedTokens)) {
+            return this.doAcquire(estimatedTokens, startTime);
+        }
+        // Calculate wait time
+        const waitMs = this.estimateWaitTime(estimatedTokens);
+        // If throwOnLimit is true, throw immediately
+        if (this.config.throwOnLimit) {
+            this.rateLimitHits++;
+            throw new RateLimitExceededError(`Rate limit exceeded. Estimated wait: ${String(waitMs)}ms`, waitMs);
+        }
+        // Wait and retry
+        return this.waitAndAcquire(estimatedTokens, startTime);
+    }
+    /**
+     * Release a concurrent request slot
+     */
+    release() {
+        if (this.concurrent > 0) {
+            this.concurrent--;
+        }
+        // Process waiting requests
+        this.processWaiters();
+    }
+    /**
+     * Report actual token usage
+     */
+    reportUsage(tokens) {
+        this.totalTokens += tokens;
+        // Deduct from token bucket if tracking
+        if (this.config.tokensPerMinute > 0) {
+            // Already deducted estimated, adjust for actual
+            // This is a simplified approach - actual might be different from estimated
+            this.llmTokens = Math.max(0, this.llmTokens);
+        }
+    }
+    /**
+     * Get current statistics
+     */
+    getStats() {
+        this.refill();
+        return {
+            availableRequests: Math.floor(this.requestTokens),
+            availableTokens: Math.floor(this.llmTokens),
+            currentConcurrent: this.concurrent,
+            totalRequests: this.totalRequests,
+            totalTokens: this.totalTokens,
+            rateLimitHits: this.rateLimitHits,
+            totalWaitTimeMs: this.totalWaitTimeMs,
+        };
+    }
+    /**
+     * Reset the rate limiter
+     */
+    reset() {
+        this.requestTokens = this.config.requestsPerMinute;
+        this.llmTokens = this.config.tokensPerMinute;
+        this.lastRequestRefill = Date.now();
+        this.lastTokenRefill = Date.now();
+        this.concurrent = 0;
+        this.totalRequests = 0;
+        this.totalTokens = 0;
+        this.rateLimitHits = 0;
+        this.totalWaitTimeMs = 0;
+        // Reject all waiters
+        for (const waiter of this.waiters) {
+            waiter.resolve({
+                acquired: false,
+                waitedMs: Date.now() - waiter.startTime,
+                estimatedWaitMs: 0,
+            });
+        }
+        this.waiters = [];
+    }
+    /**
+     * Check if a request can be made immediately
+     */
+    canAcquire(estimatedTokens = 0) {
+        this.refill();
+        return this.canAcquireNow(estimatedTokens);
+    }
+    /**
+     * Refill token buckets based on elapsed time
+     */
+    refill() {
+        const now = Date.now();
+        // Refill request tokens
+        const requestElapsed = now - this.lastRequestRefill;
+        const requestRefillRate = this.config.requestsPerMinute / 60000; // per ms
+        this.requestTokens = Math.min(this.config.requestsPerMinute, this.requestTokens + requestElapsed * requestRefillRate);
+        this.lastRequestRefill = now;
+        // Refill LLM tokens
+        if (this.config.tokensPerMinute > 0) {
+            const tokenElapsed = now - this.lastTokenRefill;
+            const tokenRefillRate = this.config.tokensPerMinute / 60000; // per ms
+            this.llmTokens = Math.min(this.config.tokensPerMinute, this.llmTokens + tokenElapsed * tokenRefillRate);
+            this.lastTokenRefill = now;
+        }
+    }
+    /**
+     * Check if can acquire without refilling
+     */
+    canAcquireNow(estimatedTokens) {
+        // Check request limit
+        if (this.requestTokens < 1) {
+            return false;
+        }
+        // Check token limit
+        if (this.config.tokensPerMinute > 0 && this.llmTokens < estimatedTokens) {
+            return false;
+        }
+        // Check concurrent limit
+        if (this.config.maxConcurrent > 0 && this.concurrent >= this.config.maxConcurrent) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Actually acquire the tokens
+     */
+    doAcquire(estimatedTokens, startTime) {
+        this.requestTokens--;
+        if (this.config.tokensPerMinute > 0) {
+            this.llmTokens -= estimatedTokens;
+        }
+        this.concurrent++;
+        this.totalRequests++;
+        const waitedMs = Date.now() - startTime;
+        this.totalWaitTimeMs += waitedMs;
+        return {
+            acquired: true,
+            waitedMs,
+        };
+    }
+    /**
+     * Estimate wait time until tokens are available
+     */
+    estimateWaitTime(estimatedTokens) {
+        let waitMs = 0;
+        // Time to wait for request token
+        if (this.requestTokens < 1) {
+            const requestRefillRate = this.config.requestsPerMinute / 60000;
+            const requestWait = (1 - this.requestTokens) / requestRefillRate;
+            waitMs = Math.max(waitMs, requestWait);
+        }
+        // Time to wait for LLM tokens
+        if (this.config.tokensPerMinute > 0 && this.llmTokens < estimatedTokens) {
+            const tokenRefillRate = this.config.tokensPerMinute / 60000;
+            const tokenWait = (estimatedTokens - this.llmTokens) / tokenRefillRate;
+            waitMs = Math.max(waitMs, tokenWait);
+        }
+        // For concurrent limit, we can't estimate well - use a fixed delay
+        if (this.config.maxConcurrent > 0 && this.concurrent >= this.config.maxConcurrent) {
+            waitMs = Math.max(waitMs, 100); // Minimum wait for concurrent
+        }
+        return Math.ceil(waitMs);
+    }
+    /**
+     * Wait and try to acquire
+     */
+    waitAndAcquire(estimatedTokens, startTime) {
+        this.rateLimitHits++;
+        return new Promise((resolve) => {
+            this.waiters.push({
+                resolve,
+                estimatedTokens,
+                startTime,
+            });
+            // Set up a timer to check periodically
+            const checkInterval = setInterval(() => {
+                this.refill();
+                this.processWaiters();
+            }, 100);
+            // Timeout after 5 minutes max wait
+            const timeout = setTimeout(() => {
+                clearInterval(checkInterval);
+                const index = this.waiters.findIndex((w) => w.resolve === resolve);
+                if (index !== -1) {
+                    this.waiters.splice(index, 1);
+                    resolve({
+                        acquired: false,
+                        waitedMs: Date.now() - startTime,
+                        estimatedWaitMs: this.estimateWaitTime(estimatedTokens),
+                    });
+                }
+            }, 5 * 60 * 1000);
+            // Store cleanup function
+            const originalResolve = resolve;
+            const wrappedResolve = (result) => {
+                clearInterval(checkInterval);
+                clearTimeout(timeout);
+                originalResolve(result);
+            };
+            // Update the waiter with wrapped resolve
+            const waiterIndex = this.waiters.findIndex((w) => w.resolve === resolve);
+            if (waiterIndex !== -1) {
+                this.waiters[waiterIndex].resolve = wrappedResolve;
+            }
+        });
+    }
+    /**
+     * Process waiting requests
+     */
+    processWaiters() {
+        // Process waiters in FIFO order
+        while (this.waiters.length > 0) {
+            const waiter = this.waiters[0];
+            this.refill();
+            if (this.canAcquireNow(waiter.estimatedTokens)) {
+                this.waiters.shift();
+                waiter.resolve(this.doAcquire(waiter.estimatedTokens, waiter.startTime));
+            }
+            else {
+                // Can't process more waiters yet
+                break;
+            }
+        }
+    }
+}
+/**
+ * Create a rate limiter with the given configuration
+ */
+export function createRateLimiter(config) {
+    return new TokenBucketRateLimiter(config);
+}
+/**
+ * Create a no-op rate limiter (for testing or unlimited access)
+ */
+export function createNoopRateLimiter() {
+    return {
+        acquire: () => Promise.resolve({ acquired: true, waitedMs: 0 }),
+        release: () => { },
+        reportUsage: () => { },
+        getStats: () => ({
+            availableRequests: Infinity,
+            availableTokens: Infinity,
+            currentConcurrent: 0,
+            totalRequests: 0,
+            totalTokens: 0,
+            rateLimitHits: 0,
+            totalWaitTimeMs: 0,
+        }),
+        reset: () => { },
+        canAcquire: () => true,
+    };
+}