@compilr-dev/agents 0.3.1 → 0.3.2

package/dist/utils/index.d.ts

@@ -1,16 +1,131 @@
 /**
- * Utility functions
+ * Utility functions for @compilr-dev/agents
  */
 /**
  * Generate a unique ID for tool uses
  */
 export declare function generateId(): string;
 /**
- * Sleep for a specified duration
+ * Sleep for a specified duration, respecting AbortSignal
+ *
+ * @param ms - Duration in milliseconds
+ * @param signal - Optional AbortSignal to cancel sleep
+ * @throws Error if signal is aborted
  */
-export declare function sleep(ms: number): Promise<void>;
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
 /**
- * Retry a function with exponential backoff
+ * Configuration for LLM retry behavior
+ */
+export interface RetryConfig {
+    /**
+     * Enable/disable automatic retry.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Maximum number of retry attempts (not including initial attempt).
+     * Total attempts = maxAttempts + 1
+     * @default 10
+     */
+    maxAttempts?: number;
+    /**
+     * Base delay in milliseconds for exponential backoff.
+     * Actual delay = min(baseDelayMs * 2^attempt, maxDelayMs) + jitter
+     * @default 1000
+     */
+    baseDelayMs?: number;
+    /**
+     * Maximum delay in milliseconds (cap for exponential growth).
+     * @default 30000
+     */
+    maxDelayMs?: number;
+}
+/**
+ * Default retry configuration
+ */
+export declare const DEFAULT_RETRY_CONFIG: Required<RetryConfig>;
+/**
+ * Options for the withRetry function
+ */
+export interface WithRetryOptions<E extends Error> {
+    /**
+     * Maximum retry attempts (default: 10)
+     */
+    maxAttempts?: number;
+    /**
+     * Base delay in milliseconds (default: 1000)
+     */
+    baseDelayMs?: number;
+    /**
+     * Maximum delay cap in milliseconds (default: 30000)
+     */
+    maxDelayMs?: number;
+    /**
+     * Function to determine if an error is retryable
+     */
+    isRetryable?: (error: E) => boolean;
+    /**
+     * Callback invoked before each retry attempt
+     */
+    onRetry?: (attempt: number, maxAttempts: number, error: E, delayMs: number) => void;
+    /**
+     * Callback invoked when all retries are exhausted
+     */
+    onExhausted?: (attempts: number, error: E) => void;
+    /**
+     * AbortSignal to cancel retries
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Calculate delay with exponential backoff and jitter
+ *
+ * @param attempt - Current attempt number (0-indexed)
+ * @param baseDelayMs - Base delay in milliseconds
+ * @param maxDelayMs - Maximum delay cap in milliseconds
+ * @returns Delay in milliseconds
+ */
+export declare function calculateBackoffDelay(attempt: number, baseDelayMs?: number, maxDelayMs?: number): number;
+/**
+ * Execute an async function with automatic retry on failure
+ *
+ * @param fn - Async function to execute
+ * @param options - Retry options
+ * @returns Result of the function
+ * @throws Last error if all retries exhausted
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   async () => {
+ *     const response = await fetch(url);
+ *     if (!response.ok) throw new Error(`HTTP ${response.status}`);
+ *     return response.json();
+ *   },
+ *   {
+ *     maxAttempts: 5,
+ *     isRetryable: (error) => error.message.includes('HTTP 5'),
+ *     onRetry: (attempt, max, error, delay) => {
+ *       console.log(`Retry ${attempt}/${max} in ${delay}ms: ${error.message}`);
+ *     },
+ *   }
+ * );
+ * ```
+ */
+export declare function withRetry<T, E extends Error = Error>(fn: () => Promise<T>, options?: WithRetryOptions<E>): Promise<T>;
+/**
+ * Create a retryable async generator for streaming responses
+ *
+ * This is specifically designed for streaming LLM responses where we need to
+ * retry the entire stream if it fails partway through.
+ *
+ * @param fn - Function that returns an async iterable
+ * @param options - Retry options
+ * @returns Async generator that retries on failure
+ */
+export declare function withRetryGenerator<T, E extends Error = Error>(fn: () => AsyncIterable<T>, options?: WithRetryOptions<E>): AsyncGenerator<T, void, undefined>;
+/**
+ * @deprecated Use withRetry instead. This function is kept for backward compatibility.
  */
 export declare function retry<T>(fn: () => Promise<T>, options?: {
     maxRetries?: number;

package/dist/utils/index.js

@@ -1,5 +1,5 @@
 /**
- * Utility functions
+ * Utility functions for @compilr-dev/agents
  */
 /**
  * Generate a unique ID for tool uses
@@ -8,30 +8,181 @@ export function generateId() {
     return `toolu_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 9)}`;
 }
 /**
- * Sleep for a specified duration
+ * Sleep for a specified duration, respecting AbortSignal
+ *
+ * @param ms - Duration in milliseconds
+ * @param signal - Optional AbortSignal to cancel sleep
+ * @throws Error if signal is aborted
  */
-export function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new Error('Aborted'));
+            return;
+        }
+        const timeout = setTimeout(resolve, ms);
+        if (signal) {
+            const abortHandler = () => {
+                clearTimeout(timeout);
+                reject(new Error('Aborted'));
+            };
+            signal.addEventListener('abort', abortHandler, { once: true });
+            // Clean up abort listener when timer completes
+            const cleanup = () => {
+                signal.removeEventListener('abort', abortHandler);
+                resolve();
+            };
+            clearTimeout(timeout);
+            setTimeout(cleanup, ms);
+        }
+    });
 }
 /**
- * Retry a function with exponential backoff
+ * Default retry configuration
  */
-export async function retry(fn, options = {}) {
-    const { maxRetries = 3, baseDelay = 1000, maxDelay = 10000 } = options;
+export const DEFAULT_RETRY_CONFIG = {
+    enabled: true,
+    maxAttempts: 10,
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+};
+/**
+ * Calculate delay with exponential backoff and jitter
+ *
+ * @param attempt - Current attempt number (0-indexed)
+ * @param baseDelayMs - Base delay in milliseconds
+ * @param maxDelayMs - Maximum delay cap in milliseconds
+ * @returns Delay in milliseconds
+ */
+export function calculateBackoffDelay(attempt, baseDelayMs = DEFAULT_RETRY_CONFIG.baseDelayMs, maxDelayMs = DEFAULT_RETRY_CONFIG.maxDelayMs) {
+    // Exponential backoff: baseDelay * 2^attempt
+    const exponentialDelay = baseDelayMs * Math.pow(2, attempt);
+    // Cap at maxDelay
+    const cappedDelay = Math.min(exponentialDelay, maxDelayMs);
+    // Add jitter (0 to 50% of base delay)
+    const jitter = Math.random() * baseDelayMs * 0.5;
+    return Math.floor(cappedDelay + jitter);
+}
+/**
+ * Execute an async function with automatic retry on failure
+ *
+ * @param fn - Async function to execute
+ * @param options - Retry options
+ * @returns Result of the function
+ * @throws Last error if all retries exhausted
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   async () => {
+ *     const response = await fetch(url);
+ *     if (!response.ok) throw new Error(`HTTP ${response.status}`);
+ *     return response.json();
+ *   },
+ *   {
+ *     maxAttempts: 5,
+ *     isRetryable: (error) => error.message.includes('HTTP 5'),
+ *     onRetry: (attempt, max, error, delay) => {
+ *       console.log(`Retry ${attempt}/${max} in ${delay}ms: ${error.message}`);
+ *     },
+ *   }
+ * );
+ * ```
+ */
+export async function withRetry(fn, options = {}) {
+    const { maxAttempts = DEFAULT_RETRY_CONFIG.maxAttempts, baseDelayMs = DEFAULT_RETRY_CONFIG.baseDelayMs, maxDelayMs = DEFAULT_RETRY_CONFIG.maxDelayMs, isRetryable = () => true, onRetry, onExhausted, signal, } = options;
     let lastError;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    let attempt = 0;
+    while (attempt <= maxAttempts) {
+        // Check for abort before each attempt
+        if (signal?.aborted) {
+            throw new Error('Aborted');
+        }
         try {
             return await fn();
         }
         catch (error) {
-            lastError = error instanceof Error ? error : new Error(String(error));
-            if (attempt < maxRetries) {
-                const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
-                await sleep(delay);
+            lastError = error;
+            // Check if error is retryable
+            if (!isRetryable(lastError)) {
+                throw lastError;
+            }
+            // Check if we have attempts remaining
+            if (attempt >= maxAttempts) {
+                onExhausted?.(attempt + 1, lastError);
+                throw lastError;
+            }
+            // Calculate delay and notify
+            const delayMs = calculateBackoffDelay(attempt, baseDelayMs, maxDelayMs);
+            onRetry?.(attempt + 1, maxAttempts, lastError, delayMs);
+            // Wait before next attempt
+            await sleep(delayMs, signal);
+            attempt++;
+        }
+    }
+    // This should never be reached, but TypeScript needs it
+    throw lastError ?? new Error('Retry failed with no error');
+}
+/**
+ * Create a retryable async generator for streaming responses
+ *
+ * This is specifically designed for streaming LLM responses where we need to
+ * retry the entire stream if it fails partway through.
+ *
+ * @param fn - Function that returns an async iterable
+ * @param options - Retry options
+ * @returns Async generator that retries on failure
+ */
+export async function* withRetryGenerator(fn, options = {}) {
+    const { maxAttempts = DEFAULT_RETRY_CONFIG.maxAttempts, baseDelayMs = DEFAULT_RETRY_CONFIG.baseDelayMs, maxDelayMs = DEFAULT_RETRY_CONFIG.maxDelayMs, isRetryable = () => true, onRetry, onExhausted, signal, } = options;
+    let attempt = 0;
+    while (attempt <= maxAttempts) {
+        // Check for abort before each attempt
+        if (signal?.aborted) {
+            throw new Error('Aborted');
+        }
+        try {
+            // Yield all items from the generator
+            for await (const item of fn()) {
+                // Check for abort during iteration
+                if (signal?.aborted) {
+                    throw new Error('Aborted');
+                }
+                yield item;
+            }
+            // Successfully completed, return
+            return;
+        }
+        catch (error) {
+            const typedError = error;
+            // Check if error is retryable
+            if (!isRetryable(typedError)) {
+                throw typedError;
+            }
+            // Check if we have attempts remaining
+            if (attempt >= maxAttempts) {
+                onExhausted?.(attempt + 1, typedError);
+                throw typedError;
             }
+            // Calculate delay and notify
+            const delayMs = calculateBackoffDelay(attempt, baseDelayMs, maxDelayMs);
+            onRetry?.(attempt + 1, maxAttempts, typedError, delayMs);
+            // Wait before next attempt
+            await sleep(delayMs, signal);
+            attempt++;
         }
     }
-    throw lastError ?? new Error('Retry failed with no error captured');
+}
+/**
+ * @deprecated Use withRetry instead. This function is kept for backward compatibility.
+ */
+export async function retry(fn, options = {}) {
+    const { maxRetries = 3, baseDelay = 1000, maxDelay = 10000 } = options;
+    return withRetry(fn, {
+        maxAttempts: maxRetries,
+        baseDelayMs: baseDelay,
+        maxDelayMs: maxDelay,
+    });
 }
 /**
  * Truncate a string to a maximum length

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",
@@ -75,5 +75,8 @@
     "typescript": "^5.3.0",
     "typescript-eslint": "^8.48.0",
     "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "@google/genai": "^1.38.0"
   }
 }