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

package/dist/src/types/index.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Type definitions for Rate Limit Fallback Plugin
+ */
+import type { LogConfig } from '../../logger.js';
+import type { TextPartInput, FilePartInput } from "@opencode-ai/sdk";
+/**
+ * Represents a fallback model configuration
+ */
+export interface FallbackModel {
+    providerID: string;
+    modelID: string;
+}
+/**
+ * Fallback mode when all models are exhausted:
+ * - "cycle": Reset and retry from the first model (default)
+ * - "stop": Stop and show error message
+ * - "retry-last": Try the last model once, then reset to first on next prompt
+ */
+export type FallbackMode = "cycle" | "stop" | "retry-last";
+/**
+ * Metrics output configuration
+ */
+export interface MetricsOutputConfig {
+    console: boolean;
+    file?: string;
+    format: "pretty" | "json" | "csv";
+}
+/**
+ * Metrics configuration
+ */
+export interface MetricsConfig {
+    enabled: boolean;
+    output: MetricsOutputConfig;
+    resetInterval: "hourly" | "daily" | "weekly";
+}
+/**
+ * Plugin configuration
+ */
+export interface PluginConfig {
+    fallbackModels: FallbackModel[];
+    cooldownMs: number;
+    enabled: boolean;
+    fallbackMode: FallbackMode;
+    maxSubagentDepth?: number;
+    enableSubagentFallback?: boolean;
+    log?: LogConfig;
+    metrics?: MetricsConfig;
+}
+/**
+ * Fallback state for tracking progress
+ */
+export type FallbackState = "none" | "in_progress" | "completed";
+/**
+ * Subagent session information
+ */
+export interface SubagentSession {
+    sessionID: string;
+    parentSessionID: string;
+    depth: number;
+    fallbackState: FallbackState;
+    createdAt: number;
+    lastActivity: number;
+}
+/**
+ * Session hierarchy for managing subagents
+ */
+export interface SessionHierarchy {
+    rootSessionID: string;
+    subagents: Map<string, SubagentSession>;
+    sharedFallbackState: FallbackState;
+    sharedConfig: PluginConfig;
+    createdAt: number;
+    lastActivity: number;
+}
+/**
+ * Session error event properties
+ */
+export interface SessionErrorEventProperties {
+    sessionID: string;
+    error: unknown;
+}
+/**
+ * Message updated event info
+ */
+export interface MessageUpdatedEventInfo {
+    sessionID: string;
+    providerID?: string;
+    modelID?: string;
+    error?: unknown;
+    id?: string;
+    status?: string;
+    role?: string;
+    [key: string]: unknown;
+}
+/**
+ * Message updated event properties
+ */
+export interface MessageUpdatedEventProperties {
+    info: MessageUpdatedEventInfo;
+    [key: string]: unknown;
+}
+/**
+ * Session retry status
+ */
+export interface SessionRetryStatus {
+    type: string;
+    message: string;
+    [key: string]: unknown;
+}
+/**
+ * Session status event properties
+ */
+export interface SessionStatusEventProperties {
+    sessionID: string;
+    status?: SessionRetryStatus;
+    [key: string]: unknown;
+}
+/**
+ * Rate limit metrics for a model
+ */
+export interface RateLimitMetrics {
+    count: number;
+    lastOccurrence: number;
+    firstOccurrence: number;
+    averageInterval?: number;
+}
+/**
+ * Fallback target metrics
+ */
+export interface FallbackTargetMetrics {
+    usedAsFallback: number;
+    successful: number;
+    failed: number;
+}
+/**
+ * Model performance metrics
+ */
+export interface ModelPerformanceMetrics {
+    requests: number;
+    successes: number;
+    failures: number;
+    averageResponseTime?: number;
+}
+/**
+ * Complete metrics data
+ */
+export interface MetricsData {
+    rateLimits: Map<string, RateLimitMetrics>;
+    fallbacks: {
+        total: number;
+        successful: number;
+        failed: number;
+        averageDuration: number;
+        byTargetModel: Map<string, FallbackTargetMetrics>;
+    };
+    modelPerformance: Map<string, ModelPerformanceMetrics>;
+    startedAt: number;
+    generatedAt: number;
+}
+/**
+ * Text message part
+ */
+export type TextPart = {
+    type: "text";
+    text: string;
+};
+/**
+ * File message part
+ */
+export type FilePart = {
+    type: "file";
+    path: string;
+    mediaType: string;
+};
+/**
+ * Message part (text or file)
+ */
+export type MessagePart = TextPart | FilePart;
+/**
+ * SDK-compatible message part input
+ */
+export type SDKMessagePartInput = TextPartInput | FilePartInput;
+/**
+ * OpenCode client interface
+ */
+export type OpenCodeClient = {
+    session: {
+        abort: (args: {
+            path: {
+                id: string;
+            };
+        }) => Promise<unknown>;
+        messages: (args: {
+            path: {
+                id: string;
+            };
+        }) => Promise<{
+            data?: Array<{
+                info: {
+                    id: string;
+                    role: string;
+                };
+                parts: unknown[];
+            }>;
+        }>;
+        prompt: (args: {
+            path: {
+                id: string;
+            };
+            body: {
+                parts: SDKMessagePartInput[];
+                model: {
+                    providerID: string;
+                    modelID: string;
+                };
+            };
+        }) => Promise<unknown>;
+    };
+    tui?: {
+        showToast: (toast: any) => Promise<any>;
+    };
+};
+/**
+ * Plugin context
+ */
+export type PluginContext = {
+    client: OpenCodeClient;
+    directory: string;
+};
+/**
+ * Default fallback models
+ */
+export declare const DEFAULT_FALLBACK_MODELS: FallbackModel[];
+/**
+ * Valid fallback modes
+ */
+export declare const VALID_FALLBACK_MODES: FallbackMode[];
+/**
+ * Valid reset intervals
+ */
+export declare const VALID_RESET_INTERVALS: readonly ["hourly", "daily", "weekly"];
+export type ResetInterval = typeof VALID_RESET_INTERVALS[number];
+/**
+ * Reset interval values in milliseconds
+ */
+export declare const RESET_INTERVAL_MS: Record<ResetInterval, number>;
+/**
+ * Deduplication window for fallback processing
+ */
+export declare const DEDUP_WINDOW_MS = 5000;
+/**
+ * State timeout for retry state
+ */
+export declare const STATE_TIMEOUT_MS = 30000;
+/**
+ * Cleanup interval for stale entries
+ */
+export declare const CLEANUP_INTERVAL_MS = 300000;
+/**
+ * TTL for session entries
+ */
+export declare const SESSION_ENTRY_TTL_MS = 3600000;

package/dist/src/types/index.js

@@ -0,0 +1,46 @@
+/**
+ * Type definitions for Rate Limit Fallback Plugin
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Default fallback models
+ */
+export const DEFAULT_FALLBACK_MODELS = [
+    { providerID: "anthropic", modelID: "claude-3-5-sonnet-20250514" },
+    { providerID: "google", modelID: "gemini-2.5-pro" },
+    { providerID: "google", modelID: "gemini-2.5-flash" },
+];
+/**
+ * Valid fallback modes
+ */
+export const VALID_FALLBACK_MODES = ["cycle", "stop", "retry-last"];
+/**
+ * Valid reset intervals
+ */
+export const VALID_RESET_INTERVALS = ["hourly", "daily", "weekly"];
+/**
+ * Reset interval values in milliseconds
+ */
+export const RESET_INTERVAL_MS = {
+    hourly: 60 * 60 * 1000,
+    daily: 24 * 60 * 60 * 1000,
+    weekly: 7 * 24 * 60 * 60 * 1000,
+};
+/**
+ * Deduplication window for fallback processing
+ */
+export const DEDUP_WINDOW_MS = 5000;
+/**
+ * State timeout for retry state
+ */
+export const STATE_TIMEOUT_MS = 30000;
+/**
+ * Cleanup interval for stale entries
+ */
+export const CLEANUP_INTERVAL_MS = 300000; // 5 minutes
+/**
+ * TTL for session entries
+ */
+export const SESSION_ENTRY_TTL_MS = 3600000; // 1 hour

package/dist/src/utils/config.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Configuration loading and validation
+ */
+import type { PluginConfig } from '../types/index.js';
+/**
+ * Default plugin configuration
+ */
+export declare const DEFAULT_CONFIG: PluginConfig;
+/**
+ * Validate configuration values
+ */
+export declare function validateConfig(config: any): PluginConfig;
+/**
+ * Load and validate config from file paths
+ */
+export declare function loadConfig(directory: string): PluginConfig;

package/dist/src/utils/config.js

@@ -0,0 +1,78 @@
+/**
+ * Configuration loading and validation
+ */
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { DEFAULT_FALLBACK_MODELS, VALID_FALLBACK_MODES, VALID_RESET_INTERVALS, } from '../types/index.js';
+/**
+ * Default plugin configuration
+ */
+export const DEFAULT_CONFIG = {
+    fallbackModels: DEFAULT_FALLBACK_MODELS,
+    cooldownMs: 60 * 1000,
+    enabled: true,
+    fallbackMode: "cycle",
+    log: {
+        level: "warn",
+        format: "simple",
+        enableTimestamp: true,
+    },
+    metrics: {
+        enabled: false,
+        output: {
+            console: true,
+            format: "pretty",
+        },
+        resetInterval: "daily",
+    },
+};
+/**
+ * Validate configuration values
+ */
+export function validateConfig(config) {
+    const mode = config.fallbackMode;
+    const resetInterval = config.metrics?.resetInterval;
+    return {
+        ...DEFAULT_CONFIG,
+        ...config,
+        fallbackModels: config.fallbackModels || DEFAULT_CONFIG.fallbackModels,
+        fallbackMode: VALID_FALLBACK_MODES.includes(mode) ? mode : DEFAULT_CONFIG.fallbackMode,
+        log: config.log ? { ...DEFAULT_CONFIG.log, ...config.log } : DEFAULT_CONFIG.log,
+        metrics: config.metrics ? {
+            ...DEFAULT_CONFIG.metrics,
+            ...config.metrics,
+            output: config.metrics.output ? {
+                ...DEFAULT_CONFIG.metrics.output,
+                ...config.metrics.output,
+            } : DEFAULT_CONFIG.metrics.output,
+            resetInterval: VALID_RESET_INTERVALS.includes(resetInterval) ? resetInterval : DEFAULT_CONFIG.metrics.resetInterval,
+        } : DEFAULT_CONFIG.metrics,
+    };
+}
+/**
+ * Load and validate config from file paths
+ */
+export function loadConfig(directory) {
+    const homedir = process.env.HOME || "";
+    const configPaths = [
+        join(directory, ".opencode", "rate-limit-fallback.json"),
+        join(directory, "rate-limit-fallback.json"),
+        join(homedir, ".opencode", "rate-limit-fallback.json"),
+        join(homedir, ".config", "opencode", "rate-limit-fallback.json"),
+    ];
+    for (const configPath of configPaths) {
+        if (existsSync(configPath)) {
+            try {
+                const content = readFileSync(configPath, "utf-8");
+                const userConfig = JSON.parse(content);
+                return validateConfig(userConfig);
+            }
+            catch (error) {
+                // Log config errors to console immediately before logger is initialized
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.error(`[RateLimitFallback] Failed to load config from ${configPath}:`, errorMessage);
+            }
+        }
+    }
+    return DEFAULT_CONFIG;
+}

package/dist/src/utils/errorDetection.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Rate limit error detection
+ */
+/**
+ * Check if error is rate limit related
+ */
+export declare function isRateLimitError(error: unknown): boolean;

package/dist/src/utils/errorDetection.js

@@ -0,0 +1,34 @@
+/**
+ * Rate limit error detection
+ */
+/**
+ * Check if error is rate limit related
+ */
+export function isRateLimitError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    // More type-safe error object structure
+    const err = error;
+    // Check for 429 status code in APIError (strict check)
+    if (err.name === "APIError" && err.data?.statusCode === 429) {
+        return true;
+    }
+    // Type-safe access to error fields
+    const responseBody = String(err.data?.responseBody || "").toLowerCase();
+    const message = String(err.data?.message || err.message || "").toLowerCase();
+    // Strict rate limit indicators only - avoid false positives
+    const strictRateLimitIndicators = [
+        "rate limit",
+        "rate_limit",
+        "ratelimit",
+        "too many requests",
+        "quota exceeded",
+    ];
+    // Check for 429 in text (explicit HTTP status code)
+    if (responseBody.includes("429") || message.includes("429")) {
+        return true;
+    }
+    // Check for strict rate limit keywords
+    return strictRateLimitIndicators.some((indicator) => responseBody.includes(indicator) ||
+        message.includes(indicator));
+}

package/dist/src/utils/helpers.d.ts

@@ -0,0 +1,34 @@
+/**
+ * General utility functions
+ */
+import type { MessagePart, SDKMessagePartInput } from '../types/index.js';
+export declare const DEDUP_WINDOW_MS = 5000;
+export declare const STATE_TIMEOUT_MS = 30000;
+/**
+ * Generate a model identifier key
+ */
+export declare function getModelKey(providerID: string, modelID: string): string;
+/**
+ * Generate a state identifier
+ */
+export declare function getStateKey(sessionID: string, messageID: string): string;
+/**
+ * Extract and validate message parts from a user message
+ */
+export declare function extractMessageParts(message: unknown): MessagePart[];
+/**
+ * Convert internal MessagePart to SDK-compatible format
+ */
+export declare function convertPartsToSDKFormat(parts: MessagePart[]): SDKMessagePartInput[];
+/**
+ * Extract toast message properties with fallback values
+ */
+export declare function getToastMessage(toast: any): {
+    title: string;
+    message: string;
+    variant: string;
+};
+/**
+ * Safely show toast, falling back to console logging if TUI is missing or fails
+ */
+export declare const safeShowToast: (client: any, toast: any) => Promise<void>;

package/dist/src/utils/helpers.js

@@ -0,0 +1,95 @@
+/**
+ * General utility functions
+ */
+import { DEDUP_WINDOW_MS as DEDUP_WINDOW_MS_TYPE, STATE_TIMEOUT_MS as STATE_TIMEOUT_MS_TYPE, } from '../types/index.js';
+// Re-export as constants
+export const DEDUP_WINDOW_MS = DEDUP_WINDOW_MS_TYPE;
+export const STATE_TIMEOUT_MS = STATE_TIMEOUT_MS_TYPE;
+/**
+ * Generate a model identifier key
+ */
+export function getModelKey(providerID, modelID) {
+    return `${providerID}/${modelID}`;
+}
+/**
+ * Generate a state identifier
+ */
+export function getStateKey(sessionID, messageID) {
+    return `${sessionID}:${messageID}`;
+}
+/**
+ * Extract and validate message parts from a user message
+ */
+export function extractMessageParts(message) {
+    const msg = message;
+    return msg.parts
+        .filter((p) => {
+        const part = p;
+        return part.type === "text" || part.type === "file";
+    })
+        .map((p) => {
+        const part = p;
+        if (part.type === "text")
+            return { type: "text", text: String(part.text) };
+        if (part.type === "file")
+            return { type: "file", path: String(part.path), mediaType: String(part.mediaType) };
+        return null;
+    })
+        .filter((p) => p !== null);
+}
+/**
+ * Convert internal MessagePart to SDK-compatible format
+ */
+export function convertPartsToSDKFormat(parts) {
+    return parts.map((part) => {
+        if (part.type === "text") {
+            return { type: "text", text: part.text };
+        }
+        // For file parts, we need to match the FilePartInput format
+        // Using path as url since we're dealing with local files
+        return {
+            type: "file",
+            url: part.path,
+            mime: part.mediaType || "application/octet-stream",
+        };
+    });
+}
+/**
+ * Extract toast message properties with fallback values
+ */
+export function getToastMessage(toast) {
+    const title = toast?.body?.title || toast?.title || "Toast";
+    const message = toast?.body?.message || toast?.message || "";
+    const variant = toast?.body?.variant || toast?.variant || "info";
+    return { title, message, variant };
+}
+/**
+ * Safely show toast, falling back to console logging if TUI is missing or fails
+ */
+export const safeShowToast = async (client, toast) => {
+    const { title, message, variant } = getToastMessage(toast);
+    const logToConsole = () => {
+        if (variant === "error") {
+            console.error(`[RateLimitFallback] ${title}: ${message}`);
+        }
+        else if (variant === "warning") {
+            console.warn(`[RateLimitFallback] ${title}: ${message}`);
+        }
+        else {
+            console.log(`[RateLimitFallback] ${title}: ${message}`);
+        }
+    };
+    try {
+        if (client.tui) {
+            await client.tui.showToast(toast);
+        }
+        else {
+            // TUI doesn't exist - log to console
+            logToConsole();
+        }
+    }
+    catch {
+        // TUI exists but failed to show toast - log to console
+        logToConsole();
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azumag/opencode-rate-limit-fallback",
-  "version": "1.21.0",
+  "version": "1.21.2",
   "description": "OpenCode plugin that automatically switches to fallback models when rate limited",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -32,10 +32,8 @@
     "test:coverage": "vitest run --coverage"
   },
   "files": [
-    "dist/index.js",
-    "dist/index.d.ts",
-    "dist/logger.js",
-    "dist/logger.d.ts",
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
     "README.md",
     "LICENSE"
   ],