astrabot 0.1.0

package/ai/retry-prompt.ts

@@ -0,0 +1,30 @@
+import { confirm, isCancel } from "@clack/prompts";
+import chalk from "chalk";
+
+function extractMessage(error: unknown): string {
+    if (error instanceof Error) {
+        const firstLine = error.message.split("\n")[0]?.trim();
+        if (firstLine) return firstLine;
+    }
+
+    if (typeof error === "string" && error.trim()) {
+        return error.trim();
+    }
+
+    return "The AI provider returned an error.";
+}
+
+export async function promptToRetryAiCall(
+    context: string,
+    error: unknown,
+): Promise<boolean> {
+    console.log(chalk.red(`\n${context}`));
+    console.log(chalk.dim(extractMessage(error)));
+
+    const retry = await confirm({
+        message: "Try again?",
+        initialValue: true,
+    });
+
+    return !isCancel(retry) && !!retry;
+}

package/bin/astra

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../index.ts";

package/core/retry/error-classifier.ts

@@ -0,0 +1,208 @@
+/**
+ * Error Classification Module
+ *
+ * Analyzes errors to determine if they are retryable and
+ * suggests appropriate retry delays.
+ */
+
+import { ErrorCategory, type ClassifiedError } from './retry-config';
+
+/**
+ * HTTP status codes that indicate rate limiting
+ */
+const RATE_LIMIT_STATUS_CODES = [429, 503];
+
+/**
+ * HTTP status codes that indicate server errors (potentially transient)
+ */
+const SERVER_ERROR_STATUS_CODES = [500, 502, 504];
+
+/**
+ * HTTP status codes that indicate authentication failures
+ */
+const AUTH_STATUS_CODES = [401, 403];
+
+/**
+ * Network error codes that indicate connectivity issues
+ */
+const NETWORK_ERROR_CODES = [
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'ENETUNREACH',
+    'EHOSTUNREACH',
+    'EPIPE',
+    'ECONNABORTED',
+];
+
+/**
+ * Error message patterns that indicate specific error categories
+ */
+const ERROR_PATTERNS: { pattern: RegExp; category: ErrorCategory }[] = [
+    // Rate limiting
+    { pattern: /rate\s*limit/i, category: ErrorCategory.RATE_LIMIT },
+    { pattern: /too\s*many\s*requests/i, category: ErrorCategory.RATE_LIMIT },
+    { pattern: /throttl/i, category: ErrorCategory.RATE_LIMIT },
+    { pattern: /quota\s*exceeded/i, category: ErrorCategory.RATE_LIMIT },
+
+    // Network errors
+    { pattern: /network\s*error/i, category: ErrorCategory.NETWORK },
+    { pattern: /connection\s*refused/i, category: ErrorCategory.NETWORK },
+    { pattern: /connection\s*reset/i, category: ErrorCategory.NETWORK },
+    { pattern: /dns\s*error/i, category: ErrorCategory.NETWORK },
+    { pattern: /socket\s*hang\s*up/i, category: ErrorCategory.NETWORK },
+
+    // Timeout errors
+    { pattern: /timeout/i, category: ErrorCategory.TIMEOUT },
+    { pattern: /timed?\s*out/i, category: ErrorCategory.TIMEOUT },
+    { pattern: /deadline\s*exceeded/i, category: ErrorCategory.TIMEOUT },
+
+    // Authentication errors
+    { pattern: /unauthorized/i, category: ErrorCategory.AUTH },
+    { pattern: /forbidden/i, category: ErrorCategory.AUTH },
+    { pattern: /invalid\s*api\s*key/i, category: ErrorCategory.AUTH },
+    { pattern: /authentication\s*failed/i, category: ErrorCategory.AUTH },
+    { pattern: /api\s*key\s*invalid/i, category: ErrorCategory.AUTH },
+
+    // Permanent errors
+    { pattern: /not\s*found/i, category: ErrorCategory.PERMANENT },
+    { pattern: /invalid\s*request/i, category: ErrorCategory.PERMANENT },
+    { pattern: /bad\s*request/i, category: ErrorCategory.PERMANENT },
+    { pattern: /malformed/i, category: ErrorCategory.PERMANENT },
+    { pattern: /unsupported/i, category: ErrorCategory.PERMANENT },
+];
+
+/**
+ * Extract status code from various error formats
+ */
+function extractStatusCode(error: Error): number | undefined {
+    // Direct status code property
+    if ('status' in error && typeof error.status === 'number') {
+        return error.status;
+    }
+    if ('statusCode' in error && typeof error.statusCode === 'number') {
+        return error.statusCode;
+    }
+
+    // Extract from error message
+    const statusMatch = error.message.match(/\b(\d{3})\b/);
+    if (statusMatch) {
+        return parseInt(statusMatch[1]!, 10);
+    }
+
+    return undefined;
+}
+
+/**
+ * Extract error code from various error formats
+ */
+function extractErrorCode(error: Error): string | undefined {
+    if ('code' in error && typeof error.code === 'string') {
+        return error.code;
+    }
+    return undefined;
+}
+
+/**
+ * Determine if an error category is retryable
+ */
+function isRetryableCategory(category: ErrorCategory): boolean {
+    switch (category) {
+        case ErrorCategory.TRANSIENT:
+        case ErrorCategory.RATE_LIMIT:
+        case ErrorCategory.NETWORK:
+        case ErrorCategory.TIMEOUT:
+        case ErrorCategory.UNKNOWN:
+            return true;
+        case ErrorCategory.PERMANENT:
+        case ErrorCategory.AUTH:
+            return false;
+    }
+}
+
+/**
+ * Get suggested delay for an error category
+ */
+function getSuggestedDelay(category: ErrorCategory): number {
+    switch (category) {
+        case ErrorCategory.RATE_LIMIT:
+            return 5000; // 5 seconds for rate limits
+        case ErrorCategory.NETWORK:
+            return 2000; // 2 seconds for network issues
+        case ErrorCategory.TIMEOUT:
+            return 3000; // 3 seconds for timeouts
+        case ErrorCategory.TRANSIENT:
+        case ErrorCategory.UNKNOWN:
+            return 1000; // 1 second for transient/unknown
+        case ErrorCategory.PERMANENT:
+        case ErrorCategory.AUTH:
+            return 0; // No delay for permanent errors
+    }
+}
+
+/**
+ * Classify an error to determine retry behavior
+ */
+export function classifyError(error: Error): ClassifiedError {
+    const message = error.message || 'Unknown error';
+    const statusCode = extractStatusCode(error);
+    const errorCode = extractErrorCode(error);
+
+    let category: ErrorCategory = ErrorCategory.UNKNOWN;
+
+    // Check HTTP status codes first
+    if (statusCode) {
+        if (RATE_LIMIT_STATUS_CODES.includes(statusCode)) {
+            category = ErrorCategory.RATE_LIMIT;
+        } else if (AUTH_STATUS_CODES.includes(statusCode)) {
+            category = ErrorCategory.AUTH;
+        } else if (SERVER_ERROR_STATUS_CODES.includes(statusCode)) {
+            category = ErrorCategory.TRANSIENT;
+        } else if (statusCode >= 400 && statusCode < 500) {
+            category = ErrorCategory.PERMANENT;
+        }
+    }
+
+    // Check error codes
+    if (errorCode && NETWORK_ERROR_CODES.includes(errorCode)) {
+        category = ErrorCategory.NETWORK;
+    }
+
+    // Check error message patterns (if not already classified)
+    if (category === ErrorCategory.UNKNOWN) {
+        for (const { pattern, category: cat } of ERROR_PATTERNS) {
+            if (pattern.test(message)) {
+                category = cat;
+                break;
+            }
+        }
+    }
+
+    const isRetryable = isRetryableCategory(category);
+    const suggestedDelayMs = getSuggestedDelay(category);
+
+    return {
+        originalError: error,
+        category,
+        message,
+        statusCode,
+        isRetryable,
+        suggestedDelayMs,
+    };
+}
+
+/**
+ * Check if an error is retryable
+ */
+export function isRetryable(error: Error): boolean {
+    return classifyError(error).isRetryable;
+}
+
+/**
+ * Get retry delay for an error
+ */
+export function getRetryDelay(error: Error): number {
+    return classifyError(error).suggestedDelayMs;
+}

package/core/retry/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Retry Module Public API
+ */
+
+export {
+    ErrorCategory,
+    type ClassifiedError,
+    type RetryConfig,
+    type RetryStats,
+    type RetryResult,
+    DEFAULT_RETRY_CONFIG,
+    AGGRESSIVE_RETRY_CONFIG,
+    CONSERVATIVE_RETRY_CONFIG,
+    NO_RETRY_CONFIG,
+    mergeRetryConfig,
+} from './retry-config';
+
+export {
+    classifyError,
+    isRetryable,
+    getRetryDelay,
+} from './error-classifier';
+
+export {
+    withRetry,
+    withRetryOrNull,
+    createRetryWrapper,
+    RetryPresets,
+} from './retry-engine';

package/core/retry/retry-config.ts

@@ -0,0 +1,142 @@
+/**
+ * Retry Configuration Module
+ *
+ * Provides configurable retry policies with exponential backoff,
+ * jitter, and error classification for resilient execution.
+ */
+
+/**
+ * Error classification for determining retry behavior
+ */
+export enum ErrorCategory {
+    /** Transient errors that are likely to succeed on retry */
+    TRANSIENT = 'transient',
+    /** Permanent errors that will never succeed */
+    PERMANENT = 'permanent',
+    /** Rate limiting errors - need longer backoff */
+    RATE_LIMIT = 'rate_limit',
+    /** Network connectivity issues */
+    NETWORK = 'network',
+    /** Authentication/authorization failures */
+    AUTH = 'auth',
+    /** Timeout errors */
+    TIMEOUT = 'timeout',
+    /** Unknown errors - treat as transient by default */
+    UNKNOWN = 'unknown',
+}
+
+/**
+ * Classified error with metadata for retry decisions
+ */
+export interface ClassifiedError {
+    originalError: Error;
+    category: ErrorCategory;
+    message: string;
+    statusCode?: number;
+    isRetryable: boolean;
+    suggestedDelayMs: number;
+}
+
+/**
+ * Retry configuration options
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts (0 = no retries) */
+    maxRetries: number;
+    /** Base delay in ms before first retry */
+    baseDelayMs: number;
+    /** Maximum delay in ms between retries */
+    maxDelayMs: number;
+    /** Exponential backoff multiplier */
+    backoffMultiplier: number;
+    /** Add random jitter to prevent thundering herd */
+    jitter: boolean;
+    /** Maximum jitter in ms */
+    maxJitterMs: number;
+    /** Timeout for individual attempts in ms */
+    attemptTimeoutMs?: number;
+    /** Custom error classifier */
+    errorClassifier?: (error: Error) => ErrorCategory;
+    /** Callback invoked before each retry */
+    onRetry?: (attempt: number, error: ClassifiedError, delayMs: number) => void | Promise<void>;
+    /** Callback invoked when all retries are exhausted */
+    onExhausted?: (error: ClassifiedError, totalAttempts: number) => void | Promise<void>;
+}
+
+/**
+ * Retry execution statistics
+ */
+export interface RetryStats {
+    totalAttempts: number;
+    totalRetries: number;
+    totalDelayMs: number;
+    errors: ClassifiedError[];
+    succeeded: boolean;
+    finalAttemptNumber: number;
+}
+
+/**
+ * Result of a retryable operation
+ */
+export interface RetryResult<T> {
+    result: T;
+    stats: RetryStats;
+}
+
+/**
+ * Default retry configuration
+ */
+export const DEFAULT_RETRY_CONFIG: RetryConfig = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+    backoffMultiplier: 2,
+    jitter: true,
+    maxJitterMs: 1000,
+};
+
+/**
+ * Aggressive retry configuration for critical operations
+ */
+export const AGGRESSIVE_RETRY_CONFIG: RetryConfig = {
+    maxRetries: 5,
+    baseDelayMs: 500,
+    maxDelayMs: 60000,
+    backoffMultiplier: 2,
+    jitter: true,
+    maxJitterMs: 2000,
+};
+
+/**
+ * Conservative retry configuration for sensitive operations
+ */
+export const CONSERVATIVE_RETRY_CONFIG: RetryConfig = {
+    maxRetries: 2,
+    baseDelayMs: 2000,
+    maxDelayMs: 10000,
+    backoffMultiplier: 3,
+    jitter: false,
+    maxJitterMs: 500,
+};
+
+/**
+ * No retry configuration
+ */
+export const NO_RETRY_CONFIG: RetryConfig = {
+    maxRetries: 0,
+    baseDelayMs: 0,
+    maxDelayMs: 0,
+    backoffMultiplier: 1,
+    jitter: false,
+    maxJitterMs: 0,
+};
+
+/**
+ * Merge user config with defaults
+ */
+export function mergeRetryConfig(userConfig: Partial<RetryConfig>): RetryConfig {
+    return {
+        ...DEFAULT_RETRY_CONFIG,
+        ...userConfig,
+    };
+}

package/core/retry/retry-engine.ts

@@ -0,0 +1,215 @@
+/**
+ * Retry Engine Module
+ *
+ * Core retry execution logic with exponential backoff, jitter,
+ * and comprehensive error handling.
+ */
+
+import {
+    type RetryConfig,
+    type RetryStats,
+    type RetryResult,
+    type ClassifiedError,
+    DEFAULT_RETRY_CONFIG,
+    mergeRetryConfig,
+} from './retry-config';
+import { classifyError } from './error-classifier';
+
+/**
+ * Sleep for a specified duration
+ */
+function sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Calculate delay for a retry attempt using exponential backoff
+ */
+function calculateDelay(
+    attempt: number,
+    baseDelayMs: number,
+    maxDelayMs: number,
+    backoffMultiplier: number,
+    jitter: boolean,
+    maxJitterMs: number,
+    classifiedError: ClassifiedError,
+): number {
+    // Use suggested delay from error classification as base
+    const errorDelay = classifiedError.suggestedDelayMs;
+    const effectiveBase = Math.max(baseDelayMs, errorDelay);
+
+    // Calculate exponential backoff
+    const backoffDelay = effectiveBase * Math.pow(backoffMultiplier, attempt - 1);
+
+    // Cap at max delay
+    let delay = Math.min(backoffDelay, maxDelayMs);
+
+    // Add jitter if enabled
+    if (jitter && maxJitterMs > 0) {
+        const jitterAmount = Math.random() * maxJitterMs;
+        delay += jitterAmount;
+    }
+
+    return Math.round(delay);
+}
+
+/**
+ * Execute an operation with automatic retry on failure
+ */
+export async function withRetry<T>(
+    operation: () => Promise<T>,
+    config: Partial<RetryConfig> = {},
+): Promise<RetryResult<T>> {
+    const fullConfig = mergeRetryConfig(config);
+    const stats: RetryStats = {
+        totalAttempts: 0,
+        totalRetries: 0,
+        totalDelayMs: 0,
+        errors: [],
+        succeeded: false,
+        finalAttemptNumber: 0,
+    };
+
+    let lastError: ClassifiedError | null = null;
+
+    for (let attempt = 1; attempt <= fullConfig.maxRetries + 1; attempt++) {
+        stats.totalAttempts++;
+        stats.finalAttemptNumber = attempt;
+
+        try {
+            // Execute the operation with optional timeout
+            let result: T;
+
+            if (fullConfig.attemptTimeoutMs) {
+                result = await Promise.race([
+                    operation(),
+                    new Promise<never>((_, reject) => {
+                        setTimeout(() => {
+                            reject(new Error(`Operation timed out after ${fullConfig.attemptTimeoutMs}ms`));
+                        }, fullConfig.attemptTimeoutMs);
+                    }),
+                ]);
+            } else {
+                result = await operation();
+            }
+
+            // Success!
+            stats.succeeded = true;
+            return { result, stats };
+
+        } catch (error) {
+            const classifiedError = classifyError(error instanceof Error ? error : new Error(String(error)));
+            lastError = classifiedError;
+            stats.errors.push(classifiedError);
+
+            // Check if we should retry
+            const isLastAttempt = attempt > fullConfig.maxRetries;
+
+            if (!classifiedError.isRetryable || isLastAttempt) {
+                // Don't retry permanent errors or if we've exhausted retries
+                if (isLastAttempt && fullConfig.onExhausted) {
+                    await fullConfig.onExhausted(classifiedError, stats.totalAttempts);
+                }
+                throw classifiedError.originalError;
+            }
+
+            // Calculate delay before next retry
+            const delayMs = calculateDelay(
+                attempt,
+                fullConfig.baseDelayMs,
+                fullConfig.maxDelayMs,
+                fullConfig.backoffMultiplier,
+                fullConfig.jitter,
+                fullConfig.maxJitterMs,
+                classifiedError,
+            );
+
+            stats.totalRetries++;
+            stats.totalDelayMs += delayMs;
+
+            // Call onRetry callback if provided
+            if (fullConfig.onRetry) {
+                await fullConfig.onRetry(attempt, classifiedError, delayMs);
+            }
+
+            // Wait before retrying
+            await sleep(delayMs);
+        }
+    }
+
+    // This should never be reached, but just in case
+    throw lastError?.originalError || new Error('Retry exhausted');
+}
+
+/**
+ * Execute an operation with retry, returning the result or null on failure
+ */
+export async function withRetryOrNull<T>(
+    operation: () => Promise<T>,
+    config: Partial<RetryConfig> = {},
+): Promise<T | null> {
+    try {
+        const { result } = await withRetry(operation, config);
+        return result;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Create a retry wrapper for a function
+ */
+export function createRetryWrapper<TArgs extends unknown[], TReturn>(
+    fn: (...args: TArgs) => Promise<TReturn>,
+    config: Partial<RetryConfig> = {},
+): (...args: TArgs) => Promise<TReturn> {
+    return async (...args: TArgs): Promise<TReturn> => {
+        const { result } = await withRetry(() => fn(...args), config);
+        return result;
+    };
+}
+
+/**
+ * Retry configuration presets for common scenarios
+ */
+export const RetryPresets = {
+    /** For AI API calls - moderate retries with backoff */
+    aiCall: {
+        maxRetries: 3,
+        baseDelayMs: 1000,
+        maxDelayMs: 30000,
+        backoffMultiplier: 2,
+        jitter: true,
+        maxJitterMs: 1000,
+    },
+
+    /** For tool execution - fewer retries, shorter delays */
+    toolExecution: {
+        maxRetries: 2,
+        baseDelayMs: 500,
+        maxDelayMs: 5000,
+        backoffMultiplier: 2,
+        jitter: false,
+        maxJitterMs: 0,
+    },
+
+    /** For network operations - more retries, longer delays */
+    network: {
+        maxRetries: 5,
+        baseDelayMs: 2000,
+        maxDelayMs: 60000,
+        backoffMultiplier: 2,
+        jitter: true,
+        maxJitterMs: 2000,
+    },
+
+    /** For critical operations - aggressive retries */
+    critical: {
+        maxRetries: 5,
+        baseDelayMs: 1000,
+        maxDelayMs: 60000,
+        backoffMultiplier: 2,
+        jitter: true,
+        maxJitterMs: 1500,
+    },
+} as const;