@azumag/opencode-rate-limit-fallback 1.21.0 → 1.21.1

package/dist/src/fallback/FallbackHandler.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Fallback orchestration logic
+ */
+import type { Logger } from '../../logger.js';
+import type { FallbackModel, PluginConfig, OpenCodeClient, MessagePart, SessionHierarchy } from '../types/index.js';
+import { MetricsManager } from '../metrics/MetricsManager.js';
+/**
+ * Hierarchy resolver functions
+ */
+export type HierarchyResolver = {
+    getRootSession: (sessionID: string) => string | null;
+    getHierarchy: (sessionID: string) => SessionHierarchy | null;
+};
+/**
+ * Fallback Handler class for orchestrating the fallback retry flow
+ */
+export declare class FallbackHandler {
+    private config;
+    private client;
+    private logger;
+    private modelSelector;
+    private currentSessionModel;
+    private modelRequestStartTimes;
+    private retryState;
+    private fallbackInProgress;
+    private fallbackMessages;
+    private metricsManager;
+    private hierarchyResolver;
+    constructor(config: PluginConfig, client: OpenCodeClient, logger: Logger, metricsManager: MetricsManager, hierarchyResolver: HierarchyResolver);
+    /**
+     * Check and mark fallback in progress for deduplication
+     */
+    private checkAndMarkFallbackInProgress;
+    /**
+     * Get or create retry state for a specific message
+     */
+    private getOrCreateRetryState;
+    /**
+     * Get current model for a session
+     */
+    getSessionModel(sessionID: string): {
+        providerID: string;
+        modelID: string;
+    } | null;
+    /**
+     * Abort current session with error handling
+     */
+    private abortSession;
+    /**
+     * Retry the prompt with a different model
+     */
+    retryWithModel(targetSessionID: string, model: FallbackModel, parts: MessagePart[], hierarchy: SessionHierarchy | null): Promise<void>;
+    /**
+     * Handle the rate limit fallback process
+     */
+    handleRateLimitFallback(sessionID: string, currentProviderID: string, currentModelID: string): Promise<void>;
+    /**
+     * Handle message updated events for metrics recording
+     */
+    handleMessageUpdated(sessionID: string, messageID: string, hasError: boolean, isError: boolean): void;
+    /**
+     * Set model for a session
+     */
+    setSessionModel(sessionID: string, providerID: string, modelID: string): void;
+    /**
+     * Clean up stale entries
+     */
+    cleanupStaleEntries(): void;
+    /**
+     * Clean up all resources
+     */
+    destroy(): void;
+}

package/dist/src/fallback/FallbackHandler.js

@@ -0,0 +1,341 @@
+/**
+ * Fallback orchestration logic
+ */
+import { ModelSelector } from './ModelSelector.js';
+import { extractMessageParts, convertPartsToSDKFormat, safeShowToast, getStateKey, getModelKey, DEDUP_WINDOW_MS, STATE_TIMEOUT_MS } from '../utils/helpers.js';
+/**
+ * Fallback Handler class for orchestrating the fallback retry flow
+ */
+export class FallbackHandler {
+    config;
+    client;
+    logger;
+    modelSelector;
+    currentSessionModel;
+    modelRequestStartTimes;
+    retryState;
+    fallbackInProgress;
+    fallbackMessages;
+    // Metrics manager reference
+    metricsManager;
+    // Hierarchy resolver
+    hierarchyResolver;
+    constructor(config, client, logger, metricsManager, hierarchyResolver) {
+        this.config = config;
+        this.client = client;
+        this.logger = logger;
+        this.modelSelector = new ModelSelector(config, client);
+        this.metricsManager = metricsManager;
+        this.hierarchyResolver = hierarchyResolver;
+        this.currentSessionModel = new Map();
+        this.modelRequestStartTimes = new Map();
+        this.retryState = new Map();
+        this.fallbackInProgress = new Map();
+        this.fallbackMessages = new Map();
+    }
+    /**
+     * Check and mark fallback in progress for deduplication
+     */
+    checkAndMarkFallbackInProgress(sessionID, messageID) {
+        const key = getStateKey(sessionID, messageID);
+        const lastFallback = this.fallbackInProgress.get(key);
+        if (lastFallback && Date.now() - lastFallback < DEDUP_WINDOW_MS) {
+            return false; // Skip - already processing
+        }
+        this.fallbackInProgress.set(key, Date.now());
+        return true; // Continue processing
+    }
+    /**
+     * Get or create retry state for a specific message
+     */
+    getOrCreateRetryState(sessionID, messageID) {
+        const stateKey = getStateKey(sessionID, messageID);
+        let state = this.retryState.get(stateKey);
+        if (!state || Date.now() - state.lastAttemptTime > STATE_TIMEOUT_MS) {
+            state = { attemptedModels: new Set(), lastAttemptTime: Date.now() };
+            this.retryState.set(stateKey, state);
+        }
+        return state;
+    }
+    /**
+     * Get current model for a session
+     */
+    getSessionModel(sessionID) {
+        const tracked = this.currentSessionModel.get(sessionID);
+        return tracked ? { providerID: tracked.providerID, modelID: tracked.modelID } : null;
+    }
+    /**
+     * Abort current session with error handling
+     */
+    async abortSession(sessionID) {
+        try {
+            await this.client.session.abort({ path: { id: sessionID } });
+        }
+        catch (abortError) {
+            // Silently ignore abort errors and continue with fallback
+            this.logger.debug(`Failed to abort session ${sessionID}`, { error: abortError });
+        }
+    }
+    /**
+     * Retry the prompt with a different model
+     */
+    async retryWithModel(targetSessionID, model, parts, hierarchy) {
+        // Track the new model for this session
+        this.currentSessionModel.set(targetSessionID, {
+            providerID: model.providerID,
+            modelID: model.modelID,
+            lastUpdated: Date.now(),
+        });
+        // If this is a root session with subagents, propagate the model to all subagents
+        if (hierarchy) {
+            if (hierarchy.rootSessionID === targetSessionID) {
+                hierarchy.sharedFallbackState = "completed";
+                hierarchy.lastActivity = Date.now();
+                // Update model tracking for all subagents
+                for (const [subagentID, subagent] of hierarchy.subagents.entries()) {
+                    this.currentSessionModel.set(subagentID, {
+                        providerID: model.providerID,
+                        modelID: model.modelID,
+                        lastUpdated: Date.now(),
+                    });
+                    subagent.fallbackState = "completed";
+                    subagent.lastActivity = Date.now();
+                }
+            }
+        }
+        // Record model request for metrics
+        if (this.metricsManager) {
+            this.metricsManager.recordModelRequest(model.providerID, model.modelID);
+            const modelKey = getModelKey(model.providerID, model.modelID);
+            this.modelRequestStartTimes.set(modelKey, Date.now());
+        }
+        // Convert internal MessagePart to SDK-compatible format
+        const sdkParts = convertPartsToSDKFormat(parts);
+        await this.client.session.prompt({
+            path: { id: targetSessionID },
+            body: {
+                parts: sdkParts,
+                model: { providerID: model.providerID, modelID: model.modelID },
+            },
+        });
+        await safeShowToast(this.client, {
+            body: {
+                title: "Fallback Successful",
+                message: `Now using ${model.modelID}`,
+                variant: "success",
+                duration: 3000,
+            },
+        });
+    }
+    /**
+     * Handle the rate limit fallback process
+     */
+    async handleRateLimitFallback(sessionID, currentProviderID, currentModelID) {
+        try {
+            // Get root session and hierarchy using resolver
+            const rootSessionID = this.hierarchyResolver.getRootSession(sessionID);
+            const targetSessionID = rootSessionID || sessionID;
+            const hierarchy = this.hierarchyResolver.getHierarchy(sessionID);
+            // If no model info provided, try to get from tracked session model
+            if (!currentProviderID || !currentModelID) {
+                const tracked = this.currentSessionModel.get(targetSessionID);
+                if (tracked) {
+                    currentProviderID = tracked.providerID;
+                    currentModelID = tracked.modelID;
+                }
+            }
+            // Record rate limit metric
+            if (currentProviderID && currentModelID && this.metricsManager) {
+                this.metricsManager.recordRateLimit(currentProviderID, currentModelID);
+            }
+            // Abort current session with error handling
+            await this.abortSession(targetSessionID);
+            await safeShowToast(this.client, {
+                body: {
+                    title: "Rate Limit Detected",
+                    message: `Switching from ${currentModelID || 'current model'}...`,
+                    variant: "warning",
+                    duration: 3000,
+                },
+            });
+            // Get messages from the session
+            const messagesResult = await this.client.session.messages({ path: { id: targetSessionID } });
+            if (!messagesResult.data) {
+                return;
+            }
+            const messages = messagesResult.data;
+            const lastUserMessage = [...messages].reverse().find(m => m.info.role === "user");
+            if (!lastUserMessage) {
+                return;
+            }
+            // Check deduplication with message scope
+            const dedupSessionID = rootSessionID || sessionID;
+            if (!this.checkAndMarkFallbackInProgress(dedupSessionID, lastUserMessage.info.id)) {
+                return; // Skip - already processing
+            }
+            // Update hierarchy state if exists
+            if (hierarchy && rootSessionID) {
+                hierarchy.sharedFallbackState = "in_progress";
+                hierarchy.lastActivity = Date.now();
+                const subagent = hierarchy.subagents.get(sessionID);
+                if (subagent) {
+                    subagent.fallbackState = "in_progress";
+                    subagent.lastActivity = Date.now();
+                }
+            }
+            // Get or create retry state for this message
+            const state = this.getOrCreateRetryState(sessionID, lastUserMessage.info.id);
+            const stateKey = getStateKey(sessionID, lastUserMessage.info.id);
+            const fallbackKey = getStateKey(dedupSessionID, lastUserMessage.info.id);
+            // Select the next fallback model
+            const nextModel = await this.modelSelector.selectFallbackModel(currentProviderID, currentModelID, state.attemptedModels);
+            // Show error if no model is available
+            if (!nextModel) {
+                await safeShowToast(this.client, {
+                    body: {
+                        title: "No Fallback Available",
+                        message: this.config.fallbackMode === "stop"
+                            ? "All fallback models exhausted"
+                            : "All models are rate limited",
+                        variant: "error",
+                        duration: 5000,
+                    },
+                });
+                this.retryState.delete(stateKey);
+                this.fallbackInProgress.delete(fallbackKey);
+                return;
+            }
+            state.attemptedModels.add(getModelKey(nextModel.providerID, nextModel.modelID));
+            state.lastAttemptTime = Date.now();
+            // Extract message parts
+            const parts = extractMessageParts(lastUserMessage);
+            if (parts.length === 0) {
+                this.fallbackInProgress.delete(fallbackKey);
+                return;
+            }
+            await safeShowToast(this.client, {
+                body: {
+                    title: "Retrying",
+                    message: `Using ${nextModel.providerID}/${nextModel.modelID}`,
+                    variant: "info",
+                    duration: 3000,
+                },
+            });
+            // Record fallback start time
+            if (this.metricsManager) {
+                this.metricsManager.recordFallbackStart();
+            }
+            // Track this message as a fallback message for completion detection
+            this.fallbackMessages.set(fallbackKey, {
+                sessionID: dedupSessionID,
+                messageID: lastUserMessage.info.id,
+                timestamp: Date.now(),
+            });
+            // Retry with the selected model
+            await this.retryWithModel(dedupSessionID, nextModel, parts, hierarchy);
+            // Clean up state
+            this.retryState.delete(stateKey);
+        }
+        catch (err) {
+            // Log fallback errors at warn level for visibility
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            const errorName = err instanceof Error ? err.name : undefined;
+            this.logger.warn(`Fallback error for session ${sessionID}`, {
+                error: errorMessage,
+                name: errorName,
+            });
+        }
+    }
+    /**
+     * Handle message updated events for metrics recording
+     */
+    handleMessageUpdated(sessionID, messageID, hasError, isError) {
+        if (hasError && !isError) {
+            // Non-rate-limit error - record model failure metric
+            const tracked = this.currentSessionModel.get(sessionID);
+            if (tracked) {
+                if (this.metricsManager) {
+                    this.metricsManager.recordModelFailure(tracked.providerID, tracked.modelID);
+                    // Check if this was a fallback attempt and record failure
+                    const fallbackKey = getStateKey(sessionID, messageID);
+                    const fallbackInfo = this.fallbackMessages.get(fallbackKey);
+                    if (fallbackInfo) {
+                        this.metricsManager.recordFallbackFailure();
+                        this.fallbackInProgress.delete(fallbackKey);
+                        this.fallbackMessages.delete(fallbackKey);
+                    }
+                }
+            }
+        }
+        else if (!hasError) {
+            // Check if this message is a fallback message and clear its in-progress state
+            const fallbackKey = getStateKey(sessionID, messageID);
+            const fallbackInfo = this.fallbackMessages.get(fallbackKey);
+            if (fallbackInfo) {
+                // Clear fallback in progress for this message
+                this.fallbackInProgress.delete(fallbackKey);
+                this.fallbackMessages.delete(fallbackKey);
+                this.logger.debug(`Fallback completed for message ${messageID}`, { sessionID });
+                // Record fallback success metric
+                const tracked = this.currentSessionModel.get(sessionID);
+                if (tracked) {
+                    if (this.metricsManager) {
+                        this.metricsManager.recordFallbackSuccess(tracked.providerID, tracked.modelID, fallbackInfo.timestamp);
+                        // Record model performance metric
+                        const modelKey = getModelKey(tracked.providerID, tracked.modelID);
+                        const startTime = this.modelRequestStartTimes.get(modelKey);
+                        if (startTime) {
+                            const responseTime = Date.now() - startTime;
+                            this.metricsManager.recordModelSuccess(tracked.providerID, tracked.modelID, responseTime);
+                            this.modelRequestStartTimes.delete(modelKey);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Set model for a session
+     */
+    setSessionModel(sessionID, providerID, modelID) {
+        this.currentSessionModel.set(sessionID, {
+            providerID,
+            modelID,
+            lastUpdated: Date.now(),
+        });
+    }
+    /**
+     * Clean up stale entries
+     */
+    cleanupStaleEntries() {
+        const { STATE_TIMEOUT_MS, SESSION_ENTRY_TTL_MS } = require('../types/index.js');
+        const now = Date.now();
+        for (const [sessionID, entry] of this.currentSessionModel.entries()) {
+            if (now - entry.lastUpdated > SESSION_ENTRY_TTL_MS) {
+                this.currentSessionModel.delete(sessionID);
+            }
+        }
+        for (const [stateKey, state] of this.retryState.entries()) {
+            if (now - state.lastAttemptTime > STATE_TIMEOUT_MS) {
+                this.retryState.delete(stateKey);
+            }
+        }
+        for (const [fallbackKey, fallbackInfo] of this.fallbackMessages.entries()) {
+            if (now - fallbackInfo.timestamp > SESSION_ENTRY_TTL_MS) {
+                this.fallbackInProgress.delete(fallbackKey);
+                this.fallbackMessages.delete(fallbackKey);
+            }
+        }
+        this.modelSelector.cleanupStaleEntries();
+    }
+    /**
+     * Clean up all resources
+     */
+    destroy() {
+        this.currentSessionModel.clear();
+        this.modelRequestStartTimes.clear();
+        this.retryState.clear();
+        this.fallbackInProgress.clear();
+        this.fallbackMessages.clear();
+    }
+}

package/dist/src/fallback/ModelSelector.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Model selection logic based on fallback mode
+ */
+import type { FallbackModel, PluginConfig, OpenCodeClient } from '../types/index.js';
+/**
+ * Model Selector class for handling model selection strategies
+ */
+export declare class ModelSelector {
+    private rateLimitedModels;
+    private config;
+    private client;
+    constructor(config: PluginConfig, client: OpenCodeClient);
+    /**
+     * Check if a model is currently rate limited
+     */
+    private isModelRateLimited;
+    /**
+     * Mark a model as rate limited
+     */
+    markModelRateLimited(providerID: string, modelID: string): void;
+    /**
+     * Find the next available model that is not rate limited
+     */
+    private findNextAvailableModel;
+    /**
+     * Apply the fallback mode logic
+     */
+    private applyFallbackMode;
+    /**
+     * Select the next fallback model based on current state and fallback mode
+     */
+    selectFallbackModel(currentProviderID: string, currentModelID: string, attemptedModels: Set<string>): Promise<FallbackModel | null>;
+    /**
+     * Clean up stale rate-limited models
+     */
+    cleanupStaleEntries(): void;
+}

package/dist/src/fallback/ModelSelector.js

@@ -0,0 +1,134 @@
+/**
+ * Model selection logic based on fallback mode
+ */
+import { getModelKey } from '../utils/helpers.js';
+import { safeShowToast } from '../utils/helpers.js';
+/**
+ * Model Selector class for handling model selection strategies
+ */
+export class ModelSelector {
+    rateLimitedModels;
+    config;
+    client;
+    constructor(config, client) {
+        this.config = config;
+        this.client = client;
+        this.rateLimitedModels = new Map();
+    }
+    /**
+     * Check if a model is currently rate limited
+     */
+    isModelRateLimited(providerID, modelID) {
+        const key = getModelKey(providerID, modelID);
+        const limitedAt = this.rateLimitedModels.get(key);
+        if (!limitedAt)
+            return false;
+        if (Date.now() - limitedAt > this.config.cooldownMs) {
+            this.rateLimitedModels.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Mark a model as rate limited
+     */
+    markModelRateLimited(providerID, modelID) {
+        const key = getModelKey(providerID, modelID);
+        this.rateLimitedModels.set(key, Date.now());
+    }
+    /**
+     * Find the next available model that is not rate limited
+     */
+    findNextAvailableModel(currentProviderID, currentModelID, attemptedModels) {
+        const currentKey = getModelKey(currentProviderID, currentModelID);
+        const startIndex = this.config.fallbackModels.findIndex(m => getModelKey(m.providerID, m.modelID) === currentKey);
+        // If current model is not in the fallback list (startIndex is -1), start from 0
+        const searchStartIndex = Math.max(0, startIndex);
+        // Search forward from current position
+        for (let i = searchStartIndex + 1; i < this.config.fallbackModels.length; i++) {
+            const model = this.config.fallbackModels[i];
+            const key = getModelKey(model.providerID, model.modelID);
+            if (!attemptedModels.has(key) && !this.isModelRateLimited(model.providerID, model.modelID)) {
+                return model;
+            }
+        }
+        // Search from the beginning
+        for (let i = 0; i <= searchStartIndex && i < this.config.fallbackModels.length; i++) {
+            const model = this.config.fallbackModels[i];
+            const key = getModelKey(model.providerID, model.modelID);
+            if (!attemptedModels.has(key) && !this.isModelRateLimited(model.providerID, model.modelID)) {
+                return model;
+            }
+        }
+        return null;
+    }
+    /**
+     * Apply the fallback mode logic
+     */
+    applyFallbackMode(currentProviderID, currentModelID, attemptedModels) {
+        if (this.config.fallbackMode === "cycle") {
+            // Reset and retry from the first model
+            attemptedModels.clear();
+            if (currentProviderID && currentModelID) {
+                attemptedModels.add(getModelKey(currentProviderID, currentModelID));
+            }
+            return this.findNextAvailableModel("", "", attemptedModels);
+        }
+        else if (this.config.fallbackMode === "retry-last") {
+            // Try the last model in the list once, then reset on next prompt
+            const lastModel = this.config.fallbackModels[this.config.fallbackModels.length - 1];
+            if (lastModel) {
+                const isLastModelCurrent = currentProviderID === lastModel.providerID && currentModelID === lastModel.modelID;
+                if (!isLastModelCurrent && !this.isModelRateLimited(lastModel.providerID, lastModel.modelID)) {
+                    // Use the last model for one more try
+                    safeShowToast(this.client, {
+                        body: {
+                            title: "Last Resort",
+                            message: `Trying ${lastModel.modelID} one more time...`,
+                            variant: "warning",
+                            duration: 3000,
+                        },
+                    });
+                    return lastModel;
+                }
+                else {
+                    // Last model also failed, reset for next prompt
+                    attemptedModels.clear();
+                    if (currentProviderID && currentModelID) {
+                        attemptedModels.add(getModelKey(currentProviderID, currentModelID));
+                    }
+                    return this.findNextAvailableModel("", "", attemptedModels);
+                }
+            }
+        }
+        // "stop" mode: return null
+        return null;
+    }
+    /**
+     * Select the next fallback model based on current state and fallback mode
+     */
+    async selectFallbackModel(currentProviderID, currentModelID, attemptedModels) {
+        // Mark current model as rate limited and add to attempted
+        if (currentProviderID && currentModelID) {
+            this.markModelRateLimited(currentProviderID, currentModelID);
+            attemptedModels.add(getModelKey(currentProviderID, currentModelID));
+        }
+        let nextModel = this.findNextAvailableModel(currentProviderID || "", currentModelID || "", attemptedModels);
+        // Handle when no model is found based on fallbackMode
+        if (!nextModel && attemptedModels.size > 0) {
+            nextModel = this.applyFallbackMode(currentProviderID, currentModelID, attemptedModels);
+        }
+        return nextModel;
+    }
+    /**
+     * Clean up stale rate-limited models
+     */
+    cleanupStaleEntries() {
+        const now = Date.now();
+        for (const [key, limitedAt] of this.rateLimitedModels.entries()) {
+            if (now - limitedAt > this.config.cooldownMs) {
+                this.rateLimitedModels.delete(key);
+            }
+        }
+    }
+}

package/dist/src/metrics/MetricsManager.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Metrics Manager - Handles metrics collection, aggregation, and reporting
+ */
+import type { Logger } from '../../logger.js';
+import type { MetricsConfig, MetricsData, RateLimitMetrics, FallbackTargetMetrics, ModelPerformanceMetrics } from '../types/index.js';
+/**
+ * Metrics Manager class for collecting and reporting metrics
+ */
+export declare class MetricsManager {
+    private metrics;
+    private config;
+    private logger;
+    private resetTimer;
+    constructor(config: MetricsConfig, logger: Logger);
+    /**
+     * Start the automatic reset timer
+     */
+    private startResetTimer;
+    /**
+     * Reset all metrics data
+     */
+    reset(): void;
+    /**
+     * Record a rate limit event
+     */
+    recordRateLimit(providerID: string, modelID: string): void;
+    /**
+     * Record the start of a fallback operation
+     * @returns timestamp for tracking duration
+     */
+    recordFallbackStart(): number;
+    /**
+     * Record a successful fallback operation
+     */
+    recordFallbackSuccess(targetProviderID: string, targetModelID: string, startTime: number): void;
+    /**
+     * Record a failed fallback operation
+     */
+    recordFallbackFailure(): void;
+    /**
+     * Record a model request
+     */
+    recordModelRequest(providerID: string, modelID: string): void;
+    /**
+     * Record a successful model request
+     */
+    recordModelSuccess(providerID: string, modelID: string, responseTime: number): void;
+    /**
+     * Record a failed model request
+     */
+    recordModelFailure(providerID: string, modelID: string): void;
+    /**
+     * Get a copy of the current metrics
+     */
+    getMetrics(): MetricsData;
+    /**
+     * Export metrics in the specified format
+     */
+    export(format?: "pretty" | "json" | "csv"): string;
+    /**
+     * Convert metrics to a plain object (converts Maps to Objects)
+     */
+    private toPlainObject;
+    /**
+     * Export metrics in pretty-printed text format
+     */
+    private exportPretty;
+    /**
+     * Export metrics in CSV format
+     */
+    private exportCSV;
+    /**
+     * Report metrics to configured outputs
+     */
+    report(): Promise<void>;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}
+export type { MetricsConfig, MetricsData, RateLimitMetrics, FallbackTargetMetrics, ModelPerformanceMetrics };