attocode 0.1.0 → 0.1.3

package/dist/src/providers/fallback-chain.js

@@ -0,0 +1,363 @@
+/**
+ * Provider Fallback Chain
+ *
+ * Wraps multiple LLM providers with automatic failover.
+ * When the primary provider fails, requests are routed to secondary providers.
+ *
+ * Features:
+ * - Priority-based provider ordering
+ * - Cooldown period for failed providers
+ * - Circuit breaker integration (optional)
+ * - Health tracking and metrics
+ *
+ * @example
+ * ```typescript
+ * const chain = createFallbackChain({
+ *   providers: [
+ *     { provider: anthropicProvider, priority: 1 },
+ *     { provider: openRouterProvider, priority: 2 },
+ *     { provider: openAIProvider, priority: 3 },
+ *   ],
+ *   cooldownMs: 60000,  // 1 minute cooldown after failure
+ * });
+ *
+ * // Uses first available provider, fails over automatically
+ * const response = await chain.chat(messages);
+ * ```
+ */
+import { ProviderError } from './types.js';
+// =============================================================================
+// FALLBACK CHAIN
+// =============================================================================
+/**
+ * Provider fallback chain with automatic failover.
+ */
+export class FallbackChain {
+    name = 'fallback-chain';
+    defaultModel;
+    config;
+    healthMap = new Map();
+    listeners = [];
+    constructor(config) {
+        // Sort providers by priority
+        const sortedProviders = [...config.providers].sort((a, b) => a.priority - b.priority);
+        this.config = {
+            providers: sortedProviders,
+            cooldownMs: config.cooldownMs ?? 60000,
+            failureThreshold: config.failureThreshold ?? 3,
+            skipUnconfigured: config.skipUnconfigured ?? true,
+            onFallback: config.onFallback,
+            onHealthChange: config.onHealthChange,
+        };
+        // Use first provider's default model
+        this.defaultModel = sortedProviders[0]?.provider.defaultModel ?? 'unknown';
+        // Initialize health tracking
+        for (const { provider } of sortedProviders) {
+            this.healthMap.set(provider.name, {
+                name: provider.name,
+                healthy: true,
+                consecutiveFailures: 0,
+                totalRequests: 0,
+                totalFailures: 0,
+                successRate: 1,
+            });
+        }
+    }
+    /**
+     * Check if any provider in the chain is configured.
+     */
+    isConfigured() {
+        return this.config.providers.some(({ provider }) => provider.isConfigured());
+    }
+    /**
+     * Send a chat request, falling back through providers on failure.
+     */
+    async chat(messages, options) {
+        return this.executeWithFallback((provider) => provider.chat(messages, options), 'chat');
+    }
+    /**
+     * Send a chat request with tools, falling back through providers on failure.
+     */
+    async chatWithTools(messages, options) {
+        return this.executeWithFallback((provider) => {
+            if (this.supportsTools(provider)) {
+                return provider.chatWithTools(messages, options);
+            }
+            // Fall back to regular chat if provider doesn't support tools
+            const simpleMessages = messages.map(m => ({
+                role: m.role,
+                content: typeof m.content === 'string' ? m.content : '[complex content]',
+            }));
+            return provider.chat(simpleMessages, options);
+        }, 'chatWithTools');
+    }
+    /**
+     * Get health status of all providers.
+     */
+    getHealth() {
+        return Array.from(this.healthMap.values());
+    }
+    /**
+     * Get health status of a specific provider.
+     */
+    getProviderHealth(name) {
+        return this.healthMap.get(name);
+    }
+    /**
+     * Manually mark a provider as healthy (e.g., after fixing an issue).
+     */
+    markHealthy(name) {
+        const health = this.healthMap.get(name);
+        if (health) {
+            health.healthy = true;
+            health.consecutiveFailures = 0;
+            health.cooldownUntil = undefined;
+            this.emit({ type: 'provider.cooldown.end', provider: name });
+            this.config.onHealthChange?.(name, health);
+        }
+    }
+    /**
+     * Manually mark a provider as unhealthy (e.g., for maintenance).
+     */
+    markUnhealthy(name, duration) {
+        const health = this.healthMap.get(name);
+        if (health) {
+            health.healthy = false;
+            health.cooldownUntil = Date.now() + (duration ?? this.config.cooldownMs);
+            this.emit({ type: 'provider.cooldown.start', provider: name, until: health.cooldownUntil });
+            this.config.onHealthChange?.(name, health);
+        }
+    }
+    /**
+     * Subscribe to events.
+     */
+    on(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const idx = this.listeners.indexOf(listener);
+            if (idx >= 0)
+                this.listeners.splice(idx, 1);
+        };
+    }
+    // ===========================================================================
+    // PRIVATE METHODS
+    // ===========================================================================
+    async executeWithFallback(operation, operationName) {
+        const errors = [];
+        const availableProviders = this.getAvailableProviders();
+        if (availableProviders.length === 0) {
+            throw new ProviderError('No providers available in fallback chain (all in cooldown or unconfigured)', this.name, 'NOT_CONFIGURED');
+        }
+        for (let i = 0; i < availableProviders.length; i++) {
+            const { provider } = availableProviders[i];
+            const health = this.healthMap.get(provider.name);
+            health.totalRequests++;
+            const startTime = Date.now();
+            try {
+                const result = await operation(provider);
+                // Success - update health
+                this.recordSuccess(provider.name, Date.now() - startTime);
+                return result;
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                errors.push({ provider: provider.name, error: err });
+                // Record failure
+                this.recordFailure(provider.name, err);
+                // Check if we should fall back
+                const nextProvider = availableProviders[i + 1];
+                if (nextProvider) {
+                    this.emit({
+                        type: 'provider.fallback',
+                        from: provider.name,
+                        to: nextProvider.provider.name,
+                        error: err,
+                    });
+                    this.config.onFallback?.(provider.name, nextProvider.provider.name, err);
+                }
+            }
+        }
+        // All providers failed
+        this.emit({ type: 'chain.exhausted', errors });
+        throw new ProviderError(`All providers in fallback chain failed for ${operationName}. ` +
+            `Errors: ${errors.map(e => `${e.provider}: ${e.error.message}`).join('; ')}`, this.name, this.determineErrorCode(errors));
+    }
+    getAvailableProviders() {
+        const now = Date.now();
+        return this.config.providers.filter(({ provider }) => {
+            // Check if configured
+            if (this.config.skipUnconfigured && !provider.isConfigured()) {
+                return false;
+            }
+            // Check health/cooldown
+            const health = this.healthMap.get(provider.name);
+            if (!health)
+                return true;
+            // Check if in cooldown
+            if (health.cooldownUntil && health.cooldownUntil > now) {
+                return false;
+            }
+            // Cooldown expired - reset health
+            if (health.cooldownUntil && health.cooldownUntil <= now) {
+                health.healthy = true;
+                health.cooldownUntil = undefined;
+                this.emit({ type: 'provider.cooldown.end', provider: provider.name });
+            }
+            return health.healthy;
+        });
+    }
+    recordSuccess(name, duration) {
+        const health = this.healthMap.get(name);
+        if (!health)
+            return;
+        health.consecutiveFailures = 0;
+        health.healthy = true;
+        health.successRate = this.calculateSuccessRate(health);
+        this.emit({ type: 'provider.success', provider: name, duration });
+        this.config.onHealthChange?.(name, health);
+    }
+    recordFailure(name, error) {
+        const health = this.healthMap.get(name);
+        if (!health)
+            return;
+        health.consecutiveFailures++;
+        health.totalFailures++;
+        health.lastFailureAt = Date.now();
+        health.lastError = error.message;
+        health.successRate = this.calculateSuccessRate(health);
+        const willRetry = health.consecutiveFailures < this.config.failureThreshold;
+        this.emit({
+            type: 'provider.failure',
+            provider: name,
+            error,
+            willRetry,
+        });
+        // Check if we should trigger cooldown
+        if (health.consecutiveFailures >= this.config.failureThreshold) {
+            health.healthy = false;
+            health.cooldownUntil = Date.now() + this.config.cooldownMs;
+            this.emit({
+                type: 'provider.cooldown.start',
+                provider: name,
+                until: health.cooldownUntil,
+            });
+        }
+        this.config.onHealthChange?.(name, health);
+    }
+    calculateSuccessRate(health) {
+        if (health.totalRequests === 0)
+            return 1;
+        return (health.totalRequests - health.totalFailures) / health.totalRequests;
+    }
+    supportsTools(provider) {
+        return 'chatWithTools' in provider && typeof provider.chatWithTools === 'function';
+    }
+    determineErrorCode(errors) {
+        // Check for specific error patterns
+        for (const { error } of errors) {
+            if (error instanceof ProviderError) {
+                // Propagate specific codes (prioritize rate limits and auth)
+                if (error.code === 'RATE_LIMITED')
+                    return 'RATE_LIMITED';
+                if (error.code === 'AUTHENTICATION_FAILED')
+                    return 'AUTHENTICATION_FAILED';
+            }
+        }
+        // Check if all errors are network-related
+        const allNetwork = errors.every(({ error }) => error.message.toLowerCase().includes('network') ||
+            error.message.toLowerCase().includes('timeout') ||
+            error.message.toLowerCase().includes('connection'));
+        if (allNetwork)
+            return 'NETWORK_ERROR';
+        return 'UNKNOWN';
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+}
+// =============================================================================
+// FACTORY FUNCTIONS
+// =============================================================================
+/**
+ * Create a fallback chain from providers.
+ *
+ * @example
+ * ```typescript
+ * const chain = createFallbackChain({
+ *   providers: [
+ *     { provider: anthropicProvider, priority: 1 },
+ *     { provider: openRouterProvider, priority: 2 },
+ *   ],
+ *   cooldownMs: 60000,
+ *   onFallback: (from, to, error) => {
+ *     console.log(`Falling back from ${from} to ${to}: ${error.message}`);
+ *   },
+ * });
+ * ```
+ */
+export function createFallbackChain(config) {
+    return new FallbackChain(config);
+}
+/**
+ * Create a fallback chain from the provider registry.
+ * Automatically includes all configured providers sorted by priority.
+ */
+export async function createFallbackChainFromRegistry(overrides) {
+    // Dynamic import to avoid circular dependency
+    const { listProviders, getProvider } = await import('./provider.js');
+    const available = listProviders().filter(p => p.configured);
+    const chainedProviders = [];
+    for (const { name, priority } of available) {
+        try {
+            const provider = await getProvider(name);
+            chainedProviders.push({ provider, priority });
+        }
+        catch {
+            // Skip providers that fail to initialize
+        }
+    }
+    if (chainedProviders.length === 0) {
+        throw new ProviderError('No providers could be initialized for fallback chain', 'fallback-chain', 'NOT_CONFIGURED');
+    }
+    return createFallbackChain({
+        providers: chainedProviders,
+        ...overrides,
+    });
+}
+// =============================================================================
+// UTILITIES
+// =============================================================================
+/**
+ * Format health status for display.
+ */
+export function formatHealthStatus(health) {
+    const lines = ['Provider Health Status:', ''];
+    for (const h of health) {
+        const status = h.healthy ? '✓' : '✗';
+        const rate = `${(h.successRate * 100).toFixed(1)}%`;
+        const cooldown = h.cooldownUntil
+            ? ` (cooldown until ${new Date(h.cooldownUntil).toLocaleTimeString()})`
+            : '';
+        lines.push(`  ${status} ${h.name}: ${rate} success, ${h.totalRequests} requests${cooldown}`);
+        if (h.lastError) {
+            lines.push(`      Last error: ${h.lastError}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Check if an error is from an exhausted fallback chain.
+ */
+export function isChainExhaustedError(error) {
+    return (error instanceof ProviderError &&
+        error.provider === 'fallback-chain' &&
+        error.message.includes('All providers in fallback chain failed'));
+}
+//# sourceMappingURL=fallback-chain.js.map

package/dist/src/providers/fallback-chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback-chain.js","sourceRoot":"","sources":["../../../src/providers/fallback-chain.ts"],"names":[],"mappings":"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"}

package/dist/src/providers/llm-resilience.d.ts

@@ -0,0 +1,126 @@
+/**
+ * LLM Resilience Utility
+ *
+ * Provides semantic-level resilience for LLM calls:
+ * - Empty response detection and retry
+ * - max_tokens truncation handling with continuation
+ * - Malformed response recovery
+ * - Graceful degradation with informative errors
+ *
+ * This complements resilient-fetch.ts (network level) with application-level resilience.
+ */
+import type { ChatResponse, Message } from '../types.js';
+/**
+ * Configuration for LLM resilience.
+ */
+export interface LLMResilienceConfig {
+    /** Maximum retries for empty responses (default: 2) */
+    maxEmptyRetries?: number;
+    /** Maximum continuation attempts for max_tokens (default: 3) */
+    maxContinuations?: number;
+    /** Whether to auto-continue on max_tokens (default: true) */
+    autoContinue?: boolean;
+    /** Minimum acceptable content length (default: 1) */
+    minContentLength?: number;
+    /** Callback for resilience events */
+    onEvent?: (event: LLMResilienceEvent) => void;
+}
+/**
+ * Events emitted during resilience handling.
+ */
+export type LLMResilienceEvent = {
+    type: 'empty_response';
+    attempt: number;
+    maxAttempts: number;
+} | {
+    type: 'empty_response_recovered';
+    attempt: number;
+} | {
+    type: 'empty_response_failed';
+    attempts: number;
+} | {
+    type: 'max_tokens_truncated';
+    continuation: number;
+    maxContinuations: number;
+} | {
+    type: 'max_tokens_continued';
+    continuation: number;
+    totalContent: number;
+} | {
+    type: 'max_tokens_completed';
+    continuations: number;
+    totalContent: number;
+} | {
+    type: 'max_tokens_limit_reached';
+    continuations: number;
+} | {
+    type: 'response_validated';
+    contentLength: number;
+    hasToolCalls: boolean;
+};
+/**
+ * Result of resilient LLM call.
+ */
+export interface ResilientLLMResult {
+    /** The validated response */
+    response: ChatResponse;
+    /** Number of empty response retries used */
+    emptyRetries: number;
+    /** Number of max_tokens continuations used */
+    continuations: number;
+    /** Whether response was modified by resilience layer */
+    wasRecovered: boolean;
+}
+/**
+ * Function type for making LLM calls.
+ */
+export type LLMCallFn = (messages: Message[]) => Promise<ChatResponse>;
+/**
+ * Wrap an LLM call with semantic resilience.
+ *
+ * Handles:
+ * 1. Empty responses - retries with slight prompt modification
+ * 2. max_tokens truncation - auto-continues to get complete response
+ * 3. Response validation - ensures response meets minimum quality bar
+ *
+ * @example
+ * ```typescript
+ * const result = await resilientLLMCall(
+ *   messages,
+ *   (msgs) => provider.chat(msgs, options),
+ *   { onEvent: (e) => console.log('Resilience:', e) }
+ * );
+ * ```
+ */
+export declare function resilientLLMCall(messages: Message[], callFn: LLMCallFn, config?: LLMResilienceConfig): Promise<ResilientLLMResult>;
+/**
+ * Error thrown when LLM resilience cannot recover.
+ */
+export declare class LLMResilienceError extends Error {
+    readonly details: {
+        emptyRetries: number;
+        continuations: number;
+    };
+    constructor(message: string, details: {
+        emptyRetries: number;
+        continuations: number;
+    });
+}
+/**
+ * Check if an error is an LLM resilience error.
+ */
+export declare function isLLMResilienceError(error: unknown): error is LLMResilienceError;
+/**
+ * Validate that a response meets minimum quality criteria.
+ */
+export declare function validateResponse(response: ChatResponse, options?: {
+    minContentLength?: number;
+}): {
+    valid: boolean;
+    issues: string[];
+};
+/**
+ * Create a response summary for logging/debugging.
+ */
+export declare function summarizeResponse(response: ChatResponse): string;
+//# sourceMappingURL=llm-resilience.d.ts.map

package/dist/src/providers/llm-resilience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-resilience.d.ts","sourceRoot":"","sources":["../../../src/providers/llm-resilience.ts"],"names":[],"mappings":"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"}