@azumag/opencode-rate-limit-fallback 1.31.0 → 1.36.0

package/dist/src/diagnostics/Reporter.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Diagnostic Reporter
+ * Generates and reports diagnostic information about the plugin
+ */
+import { Logger } from '../../logger.js';
+import type { PluginConfig, ModelHealth } from '../types/index.js';
+import type { HealthTracker } from '../health/HealthTracker.js';
+import type { CircuitBreaker } from '../circuitbreaker/index.js';
+import { ErrorPatternRegistry } from '../errors/PatternRegistry.js';
+/**
+ * Active fallback information
+ */
+export interface ActiveFallbackInfo {
+    sessionID: string;
+    currentProviderID: string;
+    currentModelID: string;
+    targetProviderID: string;
+    targetModelID: string;
+    startTime: number;
+}
+/**
+ * Circuit breaker status for a model
+ */
+export interface CircuitBreakerStatus {
+    modelKey: string;
+    providerID: string;
+    modelID: string;
+    state: 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+    failureCount: number;
+    successCount: number;
+    lastFailureTime?: number;
+    lastSuccessTime?: number;
+}
+/**
+ * Complete diagnostic report
+ */
+export interface DiagnosticReport {
+    timestamp: number;
+    config: {
+        source: string;
+        data: PluginConfig;
+    };
+    health: {
+        enabled: boolean;
+        stats: {
+            totalTracked: number;
+            totalRequests: number;
+            totalSuccesses: number;
+            totalFailures: number;
+            avgHealthScore: number;
+            modelsWithReliableData: number;
+        };
+        models: ModelHealth[];
+    };
+    errorPatterns: {
+        stats: {
+            total: number;
+            byProvider: Record<string, number>;
+            byPriority: Record<string, number>;
+        };
+    };
+    circuitBreaker: {
+        enabled: boolean;
+        models: CircuitBreakerStatus[];
+    };
+    activeFallbacks: ActiveFallbackInfo[];
+}
+/**
+ * Report format type
+ */
+export type ReportFormat = 'text' | 'json';
+/**
+ * Diagnostic Reporter class
+ */
+export declare class DiagnosticReporter {
+    private config;
+    private configSource;
+    private healthTracker?;
+    private circuitBreaker?;
+    private errorPatternRegistry;
+    private activeFallbacks;
+    private logger;
+    constructor(config: PluginConfig, configSource: string, healthTracker?: HealthTracker, circuitBreaker?: CircuitBreaker, errorPatternRegistry?: ErrorPatternRegistry, logger?: Logger);
+    /**
+     * Generate a complete diagnostic report
+     */
+    generateReport(): DiagnosticReport;
+    /**
+     * Generate health tracking report
+     */
+    private generateHealthReport;
+    /**
+     * Generate error pattern registry report
+     */
+    private generateErrorPatternsReport;
+    /**
+     * Generate circuit breaker report
+     */
+    private generateCircuitBreakerReport;
+    /**
+     * Get circuit breaker statuses for all tracked models
+     */
+    private getCircuitBreakerStatuses;
+    /**
+     * Format a report as text or JSON
+     */
+    formatReport(report: DiagnosticReport, format?: ReportFormat): string;
+    /**
+     * Format report as human-readable text
+     */
+    private formatReportAsText;
+    /**
+     * Log current configuration to console
+     */
+    logCurrentConfig(): void;
+    /**
+     * Register an active fallback
+     */
+    registerActiveFallback(info: ActiveFallbackInfo): void;
+    /**
+     * Unregister an active fallback
+     */
+    unregisterActiveFallback(sessionID: string): void;
+    /**
+     * Get active fallbacks count
+     */
+    getActiveFallbacksCount(): number;
+}

package/dist/src/diagnostics/Reporter.js

@@ -0,0 +1,285 @@
+/**
+ * Diagnostic Reporter
+ * Generates and reports diagnostic information about the plugin
+ */
+import { ErrorPatternRegistry } from '../errors/PatternRegistry.js';
+/**
+ * Diagnostic Reporter class
+ */
+export class DiagnosticReporter {
+    config;
+    configSource;
+    healthTracker;
+    circuitBreaker;
+    errorPatternRegistry;
+    activeFallbacks;
+    logger;
+    constructor(config, configSource, healthTracker, circuitBreaker, errorPatternRegistry, logger) {
+        this.config = config;
+        this.configSource = configSource;
+        this.healthTracker = healthTracker;
+        this.circuitBreaker = circuitBreaker;
+        this.errorPatternRegistry = errorPatternRegistry || new ErrorPatternRegistry();
+        this.activeFallbacks = new Map();
+        // Initialize logger
+        this.logger = logger || {
+            debug: () => { },
+            info: () => { },
+            warn: () => { },
+            error: () => { },
+        };
+    }
+    /**
+     * Generate a complete diagnostic report
+     */
+    generateReport() {
+        return {
+            timestamp: Date.now(),
+            config: {
+                source: this.configSource,
+                data: this.config,
+            },
+            health: this.generateHealthReport(),
+            errorPatterns: this.generateErrorPatternsReport(),
+            circuitBreaker: this.generateCircuitBreakerReport(),
+            activeFallbacks: Array.from(this.activeFallbacks.values()),
+        };
+    }
+    /**
+     * Generate health tracking report
+     */
+    generateHealthReport() {
+        if (!this.healthTracker) {
+            return {
+                enabled: false,
+                stats: {
+                    totalTracked: 0,
+                    totalRequests: 0,
+                    totalSuccesses: 0,
+                    totalFailures: 0,
+                    avgHealthScore: 100,
+                    modelsWithReliableData: 0,
+                },
+                models: [],
+            };
+        }
+        const stats = this.healthTracker.getStats();
+        return {
+            enabled: this.healthTracker.isEnabled(),
+            stats,
+            models: this.healthTracker.getAllHealthData(),
+        };
+    }
+    /**
+     * Generate error pattern registry report
+     */
+    generateErrorPatternsReport() {
+        return {
+            stats: this.errorPatternRegistry.getStats(),
+        };
+    }
+    /**
+     * Generate circuit breaker report
+     */
+    generateCircuitBreakerReport() {
+        if (!this.circuitBreaker) {
+            return {
+                enabled: false,
+                models: [],
+            };
+        }
+        return {
+            enabled: this.config.circuitBreaker?.enabled || false,
+            models: this.getCircuitBreakerStatuses(),
+        };
+    }
+    /**
+     * Get circuit breaker statuses for all tracked models
+     */
+    getCircuitBreakerStatuses() {
+        if (!this.circuitBreaker) {
+            return [];
+        }
+        const allStates = this.circuitBreaker.getAllStates();
+        return allStates.map(({ modelKey, state }) => {
+            const [providerID, modelID] = modelKey.split('/');
+            return {
+                modelKey,
+                providerID,
+                modelID,
+                state: state.state,
+                failureCount: state.failureCount,
+                successCount: state.successCount,
+                lastFailureTime: state.lastFailureTime || undefined,
+                lastSuccessTime: state.lastSuccessTime || undefined,
+            };
+        });
+    }
+    /**
+     * Format a report as text or JSON
+     */
+    formatReport(report, format = 'text') {
+        if (format === 'json') {
+            return JSON.stringify(report, null, 2);
+        }
+        return this.formatReportAsText(report);
+    }
+    /**
+     * Format report as human-readable text
+     */
+    formatReportAsText(report) {
+        const lines = [];
+        lines.push('='.repeat(70));
+        lines.push('Rate Limit Fallback - Diagnostic Report');
+        lines.push('='.repeat(70));
+        lines.push(`Generated: ${new Date(report.timestamp).toISOString()}`);
+        lines.push('');
+        // Configuration section
+        lines.push('-'.repeat(70));
+        lines.push('CONFIGURATION');
+        lines.push('-'.repeat(70));
+        lines.push(`Source: ${report.config.source || 'Default (no file found)'}`);
+        lines.push(`Enabled: ${report.config.data.enabled}`);
+        lines.push(`Fallback Mode: ${report.config.data.fallbackMode}`);
+        lines.push(`Cooldown: ${report.config.data.cooldownMs}ms`);
+        lines.push(`Health-Based Selection: ${report.config.data.enableHealthBasedSelection ?? false}`);
+        lines.push(`Verbose Mode: ${report.config.data.verbose ?? false}`);
+        lines.push('');
+        lines.push('Fallback Models:');
+        for (const model of report.config.data.fallbackModels) {
+            lines.push(`  - ${model.providerID}/${model.modelID}`);
+        }
+        lines.push('');
+        // Retry policy
+        if (report.config.data.retryPolicy) {
+            lines.push('Retry Policy:');
+            lines.push(`  Max Retries: ${report.config.data.retryPolicy.maxRetries}`);
+            lines.push(`  Strategy: ${report.config.data.retryPolicy.strategy}`);
+            lines.push(`  Base Delay: ${report.config.data.retryPolicy.baseDelayMs}ms`);
+            lines.push(`  Max Delay: ${report.config.data.retryPolicy.maxDelayMs}ms`);
+            lines.push(`  Jitter: ${report.config.data.retryPolicy.jitterEnabled ? 'enabled' : 'disabled'}`);
+            lines.push('');
+        }
+        // Circuit breaker
+        if (report.config.data.circuitBreaker) {
+            lines.push('Circuit Breaker:');
+            lines.push(`  Enabled: ${report.config.data.circuitBreaker.enabled}`);
+            if (report.config.data.circuitBreaker.enabled) {
+                lines.push(`  Failure Threshold: ${report.config.data.circuitBreaker.failureThreshold}`);
+                lines.push(`  Recovery Timeout: ${report.config.data.circuitBreaker.recoveryTimeoutMs}ms`);
+                lines.push(`  Success Threshold: ${report.config.data.circuitBreaker.successThreshold}`);
+            }
+            lines.push('');
+        }
+        // Health tracking section
+        lines.push('-'.repeat(70));
+        lines.push('HEALTH TRACKING');
+        lines.push('-'.repeat(70));
+        lines.push(`Enabled: ${report.health.enabled}`);
+        if (report.health.enabled) {
+            const stats = report.health.stats;
+            lines.push(`Total Models Tracked: ${stats.totalTracked}`);
+            lines.push(`Total Requests: ${stats.totalRequests}`);
+            lines.push(`Total Successes: ${stats.totalSuccesses}`);
+            lines.push(`Total Failures: ${stats.totalFailures}`);
+            lines.push(`Average Health Score: ${stats.avgHealthScore}/100`);
+            lines.push(`Models with Reliable Data: ${stats.modelsWithReliableData}/${stats.totalTracked}`);
+            lines.push('');
+            if (report.health.models.length > 0) {
+                lines.push('Model Health Details:');
+                for (const health of report.health.models.sort((a, b) => b.healthScore - a.healthScore)) {
+                    const successRate = health.totalRequests > 0
+                        ? Math.round((health.successfulRequests / health.totalRequests) * 100)
+                        : 0;
+                    lines.push(`  ${health.providerID}/${health.modelID}:`);
+                    lines.push(`    Score: ${health.healthScore}/100`);
+                    lines.push(`    Requests: ${health.totalRequests} (${successRate}% success)`);
+                    lines.push(`    Avg Response: ${health.avgResponseTime}ms`);
+                    lines.push(`    Consecutive Failures: ${health.consecutiveFailures}`);
+                    lines.push(`    Last Used: ${new Date(health.lastUsed).toISOString()}`);
+                }
+                lines.push('');
+            }
+        }
+        lines.push('');
+        // Error patterns section
+        lines.push('-'.repeat(70));
+        lines.push('ERROR PATTERN REGISTRY');
+        lines.push('-'.repeat(70));
+        const patternStats = report.errorPatterns.stats;
+        lines.push(`Total Patterns: ${patternStats.total}`);
+        lines.push('');
+        if (Object.keys(patternStats.byProvider).length > 0) {
+            lines.push('By Provider:');
+            for (const [provider, count] of Object.entries(patternStats.byProvider).sort((a, b) => b[1] - a[1])) {
+                lines.push(`  ${provider}: ${count} patterns`);
+            }
+            lines.push('');
+        }
+        if (Object.keys(patternStats.byPriority).length > 0) {
+            lines.push('By Priority:');
+            for (const [priority, count] of Object.entries(patternStats.byPriority).sort((a, b) => b[1] - a[1])) {
+                lines.push(`  ${priority}: ${count} patterns`);
+            }
+            lines.push('');
+        }
+        // Circuit breaker section
+        lines.push('-'.repeat(70));
+        lines.push('CIRCUIT BREAKER');
+        lines.push('-'.repeat(70));
+        lines.push(`Enabled: ${report.circuitBreaker.enabled}`);
+        if (report.circuitBreaker.enabled && report.circuitBreaker.models.length > 0) {
+            for (const status of report.circuitBreaker.models) {
+                lines.push(`  ${status.providerID}/${status.modelID}:`);
+                lines.push(`    State: ${status.state}`);
+                lines.push(`    Failures: ${status.failureCount}, Successes: ${status.successCount}`);
+            }
+        }
+        lines.push('');
+        // Active fallbacks section
+        lines.push('-'.repeat(70));
+        lines.push('ACTIVE FALLBACKS');
+        lines.push('-'.repeat(70));
+        lines.push(`Count: ${report.activeFallbacks.length}`);
+        if (report.activeFallbacks.length > 0) {
+            for (const fallback of report.activeFallbacks) {
+                const duration = Date.now() - fallback.startTime;
+                lines.push(`  Session ${fallback.sessionID}:`);
+                lines.push(`    From: ${fallback.currentProviderID}/${fallback.currentModelID}`);
+                lines.push(`    To: ${fallback.targetProviderID}/${fallback.targetModelID}`);
+                lines.push(`    Duration: ${duration}ms`);
+            }
+        }
+        lines.push('');
+        lines.push('='.repeat(70));
+        lines.push('End of Report');
+        lines.push('='.repeat(70));
+        return lines.join('\n');
+    }
+    /**
+     * Log current configuration to console
+     */
+    logCurrentConfig() {
+        const report = this.generateReport();
+        const formatted = this.formatReport(report, 'text');
+        this.logger.info(formatted);
+    }
+    /**
+     * Register an active fallback
+     */
+    registerActiveFallback(info) {
+        this.activeFallbacks.set(info.sessionID, info);
+    }
+    /**
+     * Unregister an active fallback
+     */
+    unregisterActiveFallback(sessionID) {
+        this.activeFallbacks.delete(sessionID);
+    }
+    /**
+     * Get active fallbacks count
+     */
+    getActiveFallbacksCount() {
+        return this.activeFallbacks.size;
+    }
+}

package/dist/src/errors/PatternRegistry.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Error Pattern Registry for rate limit error detection
+ */
+import type { ErrorPattern } from '../types/index.js';
+import { Logger } from '../../logger.js';
+/**
+ * Error Pattern Registry class
+ * Manages and matches error patterns for rate limit detection
+ */
+export declare class ErrorPatternRegistry {
+    private patterns;
+    private logger;
+    constructor(logger?: Logger);
+    /**
+     * Register default rate limit error patterns
+     */
+    registerDefaultPatterns(): void;
+    /**
+     * Register a new error pattern
+     */
+    register(pattern: ErrorPattern): void;
+    /**
+     * Register multiple error patterns
+     */
+    registerMany(patterns: ErrorPattern[]): void;
+    /**
+     * Check if an error matches any registered rate limit pattern
+     */
+    isRateLimitError(error: unknown): boolean;
+    /**
+     * Get the matched pattern for an error, or null if no match
+     */
+    getMatchedPattern(error: unknown): ErrorPattern | null;
+    /**
+     * Get all registered patterns
+     */
+    getAllPatterns(): ErrorPattern[];
+    /**
+     * Get patterns for a specific provider
+     */
+    getPatternsForProvider(provider: string): ErrorPattern[];
+    /**
+     * Get patterns by name
+     */
+    getPatternByName(name: string): ErrorPattern | undefined;
+    /**
+     * Remove a pattern by name
+     */
+    removePattern(name: string): boolean;
+    /**
+     * Clear all patterns (including default ones)
+     */
+    clearAllPatterns(): void;
+    /**
+     * Reset to default patterns only
+     */
+    resetToDefaults(): void;
+    /**
+     * Learn a new pattern from an error (for future ML-based learning)
+     * Currently disabled - patterns must be manually registered
+     */
+    addLearnedPattern(_error: unknown): void;
+    /**
+     * Get statistics about registered patterns
+     */
+    getStats(): {
+        total: number;
+        byProvider: Record<string, number>;
+        byPriority: Record<string, number>;
+    };
+    /**
+     * Get a readable priority range string
+     */
+    private getPriorityRange;
+}