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

package/dist/src/metrics/MetricsManager.js

@@ -0,0 +1,377 @@
+/**
+ * Metrics Manager - Handles metrics collection, aggregation, and reporting
+ */
+import { RESET_INTERVAL_MS } from './types.js';
+import { getModelKey } from '../utils/helpers.js';
+/**
+ * Metrics Manager class for collecting and reporting metrics
+ */
+export class MetricsManager {
+    metrics;
+    config;
+    logger;
+    resetTimer = null;
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+        this.metrics = {
+            rateLimits: new Map(),
+            fallbacks: {
+                total: 0,
+                successful: 0,
+                failed: 0,
+                averageDuration: 0,
+                byTargetModel: new Map(),
+            },
+            modelPerformance: new Map(),
+            startedAt: Date.now(),
+            generatedAt: Date.now(),
+        };
+        if (this.config.enabled) {
+            this.startResetTimer();
+        }
+    }
+    /**
+     * Start the automatic reset timer
+     */
+    startResetTimer() {
+        if (this.resetTimer) {
+            clearInterval(this.resetTimer);
+        }
+        const intervalMs = RESET_INTERVAL_MS[this.config.resetInterval];
+        this.resetTimer = setInterval(() => {
+            this.reset();
+        }, intervalMs);
+    }
+    /**
+     * Reset all metrics data
+     */
+    reset() {
+        this.metrics = {
+            rateLimits: new Map(),
+            fallbacks: {
+                total: 0,
+                successful: 0,
+                failed: 0,
+                averageDuration: 0,
+                byTargetModel: new Map(),
+            },
+            modelPerformance: new Map(),
+            startedAt: Date.now(),
+            generatedAt: Date.now(),
+        };
+        this.logger.debug("Metrics reset");
+    }
+    /**
+     * Record a rate limit event
+     */
+    recordRateLimit(providerID, modelID) {
+        if (!this.config.enabled)
+            return;
+        const key = getModelKey(providerID, modelID);
+        const now = Date.now();
+        const existing = this.metrics.rateLimits.get(key);
+        if (existing) {
+            const intervalMs = now - existing.lastOccurrence;
+            existing.count++;
+            existing.lastOccurrence = now;
+            existing.averageInterval = existing.averageInterval
+                ? (existing.averageInterval + intervalMs) / 2
+                : intervalMs;
+            this.metrics.rateLimits.set(key, existing);
+        }
+        else {
+            this.metrics.rateLimits.set(key, {
+                count: 1,
+                firstOccurrence: now,
+                lastOccurrence: now,
+            });
+        }
+    }
+    /**
+     * Record the start of a fallback operation
+     * @returns timestamp for tracking duration
+     */
+    recordFallbackStart() {
+        if (!this.config.enabled)
+            return 0;
+        return Date.now();
+    }
+    /**
+     * Record a successful fallback operation
+     */
+    recordFallbackSuccess(targetProviderID, targetModelID, startTime) {
+        if (!this.config.enabled)
+            return;
+        const duration = Date.now() - startTime;
+        const key = getModelKey(targetProviderID, targetModelID);
+        this.metrics.fallbacks.total++;
+        this.metrics.fallbacks.successful++;
+        // Update average duration
+        const totalDuration = this.metrics.fallbacks.averageDuration * (this.metrics.fallbacks.successful - 1);
+        this.metrics.fallbacks.averageDuration = (totalDuration + duration) / this.metrics.fallbacks.successful;
+        // Update target model metrics
+        const targetMetrics = this.metrics.fallbacks.byTargetModel.get(key) || {
+            usedAsFallback: 0,
+            successful: 0,
+            failed: 0,
+        };
+        targetMetrics.usedAsFallback++;
+        targetMetrics.successful++;
+        this.metrics.fallbacks.byTargetModel.set(key, targetMetrics);
+    }
+    /**
+     * Record a failed fallback operation
+     */
+    recordFallbackFailure() {
+        if (!this.config.enabled)
+            return;
+        this.metrics.fallbacks.total++;
+        this.metrics.fallbacks.failed++;
+    }
+    /**
+     * Record a model request
+     */
+    recordModelRequest(providerID, modelID) {
+        if (!this.config.enabled)
+            return;
+        const key = getModelKey(providerID, modelID);
+        const existing = this.metrics.modelPerformance.get(key) || {
+            requests: 0,
+            successes: 0,
+            failures: 0,
+        };
+        existing.requests++;
+        this.metrics.modelPerformance.set(key, existing);
+    }
+    /**
+     * Record a successful model request
+     */
+    recordModelSuccess(providerID, modelID, responseTime) {
+        if (!this.config.enabled)
+            return;
+        const key = getModelKey(providerID, modelID);
+        const existing = this.metrics.modelPerformance.get(key) || {
+            requests: 0,
+            successes: 0,
+            failures: 0,
+        };
+        existing.successes++;
+        // Update average response time
+        const totalTime = (existing.averageResponseTime || 0) * (existing.successes - 1);
+        existing.averageResponseTime = (totalTime + responseTime) / existing.successes;
+        this.metrics.modelPerformance.set(key, existing);
+    }
+    /**
+     * Record a failed model request
+     */
+    recordModelFailure(providerID, modelID) {
+        if (!this.config.enabled)
+            return;
+        const key = getModelKey(providerID, modelID);
+        const existing = this.metrics.modelPerformance.get(key) || {
+            requests: 0,
+            successes: 0,
+            failures: 0,
+        };
+        existing.failures++;
+        this.metrics.modelPerformance.set(key, existing);
+    }
+    /**
+     * Get a copy of the current metrics
+     */
+    getMetrics() {
+        this.metrics.generatedAt = Date.now();
+        return { ...this.metrics };
+    }
+    /**
+     * Export metrics in the specified format
+     */
+    export(format = "json") {
+        const metrics = this.getMetrics();
+        switch (format) {
+            case "pretty":
+                return this.exportPretty(metrics);
+            case "csv":
+                return this.exportCSV(metrics);
+            case "json":
+            default:
+                return JSON.stringify(this.toPlainObject(metrics), null, 2);
+        }
+    }
+    /**
+     * Convert metrics to a plain object (converts Maps to Objects)
+     */
+    toPlainObject(metrics) {
+        return {
+            rateLimits: Object.fromEntries(Array.from(metrics.rateLimits.entries()).map(([k, v]) => [k, v])),
+            fallbacks: {
+                ...metrics.fallbacks,
+                byTargetModel: Object.fromEntries(Array.from(metrics.fallbacks.byTargetModel.entries()).map(([k, v]) => [k, v])),
+            },
+            modelPerformance: Object.fromEntries(Array.from(metrics.modelPerformance.entries()).map(([k, v]) => [k, v])),
+            startedAt: metrics.startedAt,
+            generatedAt: metrics.generatedAt,
+        };
+    }
+    /**
+     * Export metrics in pretty-printed text format
+     */
+    exportPretty(metrics) {
+        const lines = [];
+        lines.push("=".repeat(60));
+        lines.push("Rate Limit Fallback Metrics");
+        lines.push("=".repeat(60));
+        lines.push(`Started: ${new Date(metrics.startedAt).toISOString()}`);
+        lines.push(`Generated: ${new Date(metrics.generatedAt).toISOString()}`);
+        lines.push("");
+        // Rate Limits
+        lines.push("Rate Limits:");
+        lines.push("-".repeat(40));
+        if (metrics.rateLimits.size === 0) {
+            lines.push("  No rate limits recorded");
+        }
+        else {
+            for (const [model, data] of metrics.rateLimits.entries()) {
+                lines.push(`  ${model}:`);
+                lines.push(`    Count: ${data.count}`);
+                lines.push(`    First: ${new Date(data.firstOccurrence).toISOString()}`);
+                lines.push(`    Last: ${new Date(data.lastOccurrence).toISOString()}`);
+                if (data.averageInterval) {
+                    lines.push(`    Avg Interval: ${(data.averageInterval / 1000).toFixed(2)}s`);
+                }
+            }
+        }
+        lines.push("");
+        // Fallbacks
+        lines.push("Fallbacks:");
+        lines.push("-".repeat(40));
+        lines.push(`  Total: ${metrics.fallbacks.total}`);
+        lines.push(`  Successful: ${metrics.fallbacks.successful}`);
+        lines.push(`  Failed: ${metrics.fallbacks.failed}`);
+        if (metrics.fallbacks.averageDuration > 0) {
+            lines.push(`  Avg Duration: ${(metrics.fallbacks.averageDuration / 1000).toFixed(2)}s`);
+        }
+        if (metrics.fallbacks.byTargetModel.size > 0) {
+            lines.push("");
+            lines.push("  By Target Model:");
+            for (const [model, data] of metrics.fallbacks.byTargetModel.entries()) {
+                lines.push(`    ${model}:`);
+                lines.push(`      Used: ${data.usedAsFallback}`);
+                lines.push(`      Success: ${data.successful}`);
+                lines.push(`      Failed: ${data.failed}`);
+            }
+        }
+        lines.push("");
+        // Model Performance
+        lines.push("Model Performance:");
+        lines.push("-".repeat(40));
+        if (metrics.modelPerformance.size === 0) {
+            lines.push("  No performance data recorded");
+        }
+        else {
+            for (const [model, data] of metrics.modelPerformance.entries()) {
+                lines.push(`  ${model}:`);
+                lines.push(`    Requests: ${data.requests}`);
+                lines.push(`    Successes: ${data.successes}`);
+                lines.push(`    Failures: ${data.failures}`);
+                if (data.averageResponseTime) {
+                    lines.push(`    Avg Response: ${(data.averageResponseTime / 1000).toFixed(2)}s`);
+                }
+                if (data.requests > 0) {
+                    const successRate = ((data.successes / data.requests) * 100).toFixed(1);
+                    lines.push(`    Success Rate: ${successRate}%`);
+                }
+            }
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Export metrics in CSV format
+     */
+    exportCSV(metrics) {
+        const lines = [];
+        // Rate Limits CSV
+        lines.push("=== RATE_LIMITS ===");
+        lines.push("model,count,first_occurrence,last_occurrence,avg_interval_ms");
+        for (const [model, data] of metrics.rateLimits.entries()) {
+            lines.push([
+                model,
+                data.count,
+                data.firstOccurrence,
+                data.lastOccurrence,
+                data.averageInterval || 0,
+            ].join(","));
+        }
+        lines.push("");
+        // Fallbacks Summary CSV
+        lines.push("=== FALLBACKS_SUMMARY ===");
+        lines.push(`total,successful,failed,avg_duration_ms`);
+        lines.push([
+            metrics.fallbacks.total,
+            metrics.fallbacks.successful,
+            metrics.fallbacks.failed,
+            metrics.fallbacks.averageDuration || 0,
+        ].join(","));
+        lines.push("");
+        // Fallbacks by Model CSV
+        lines.push("=== FALLBACKS_BY_MODEL ===");
+        lines.push("model,used_as_fallback,successful,failed");
+        for (const [model, data] of metrics.fallbacks.byTargetModel.entries()) {
+            lines.push([
+                model,
+                data.usedAsFallback,
+                data.successful,
+                data.failed,
+            ].join(","));
+        }
+        lines.push("");
+        // Model Performance CSV
+        lines.push("=== MODEL_PERFORMANCE ===");
+        lines.push("model,requests,successes,failures,avg_response_time_ms,success_rate");
+        for (const [model, data] of metrics.modelPerformance.entries()) {
+            const successRate = data.requests > 0 ? ((data.successes / data.requests) * 100).toFixed(1) : "0";
+            lines.push([
+                model,
+                data.requests,
+                data.successes,
+                data.failures,
+                data.averageResponseTime || 0,
+                successRate,
+            ].join(","));
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Report metrics to configured outputs
+     */
+    async report() {
+        if (!this.config.enabled)
+            return;
+        const output = this.export(this.config.output.format);
+        // Console output
+        if (this.config.output.console) {
+            console.log(output);
+        }
+        // File output
+        if (this.config.output.file) {
+            try {
+                const { writeFileSync } = await import('fs');
+                writeFileSync(this.config.output.file, output, "utf-8");
+                this.logger.debug(`Metrics exported to ${this.config.output.file}`);
+            }
+            catch (error) {
+                this.logger.warn(`Failed to write metrics to file: ${this.config.output.file}`, { error });
+            }
+        }
+    }
+    /**
+     * Clean up resources
+     */
+    destroy() {
+        if (this.resetTimer) {
+            clearInterval(this.resetTimer);
+            this.resetTimer = null;
+        }
+    }
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Metrics-specific types for the MetricsManager
+ */
+/**
+ * Reset interval options for metrics
+ */
+export type ResetInterval = "hourly" | "daily" | "weekly";
+/**
+ * Reset interval values in milliseconds
+ */
+export declare const RESET_INTERVAL_MS: Record<ResetInterval, number>;

package/dist/src/metrics/types.js

@@ -0,0 +1,11 @@
+/**
+ * Metrics-specific types for the MetricsManager
+ */
+/**
+ * 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,
+};

package/dist/src/session/SubagentTracker.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Subagent hierarchy and fallback propagation management
+ */
+import type { SessionHierarchy, PluginConfig } from '../types/index.js';
+/**
+ * Initialize subagent tracker with config
+ */
+export declare function initSubagentTracker(config: PluginConfig): void;
+/**
+ * Register a new subagent in the hierarchy
+ */
+export declare function registerSubagent(sessionID: string, parentSessionID: string, config: PluginConfig): boolean;
+/**
+ * Get root session ID for a session
+ */
+export declare function getRootSession(sessionID: string): string | null;
+/**
+ * Get hierarchy for a session
+ */
+export declare function getHierarchy(sessionID: string): SessionHierarchy | null;
+/**
+ * Get all session hierarchies (for cleanup)
+ */
+export declare function getAllHierarchies(): Map<string, SessionHierarchy>;
+/**
+ * Get session to root map (for cleanup)
+ */
+export declare function getSessionToRootMap(): Map<string, string>;
+/**
+ * Clean up stale hierarchies
+ */
+export declare function cleanupStaleEntries(): void;
+/**
+ * Clean up all hierarchies
+ */
+export declare function clearAll(): void;

package/dist/src/session/SubagentTracker.js

@@ -0,0 +1,114 @@
+/**
+ * Subagent hierarchy and fallback propagation management
+ */
+import { SESSION_ENTRY_TTL_MS } from '../types/index.js';
+/**
+ * Session Hierarchy storage
+ */
+const sessionHierarchies = new Map();
+const sessionToRootMap = new Map();
+let maxSubagentDepth = 10;
+/**
+ * Initialize subagent tracker with config
+ */
+export function initSubagentTracker(config) {
+    maxSubagentDepth = config.maxSubagentDepth ?? 10;
+}
+/**
+ * Register a new subagent in the hierarchy
+ */
+export function registerSubagent(sessionID, parentSessionID, config) {
+    // Validate parent session exists
+    // Parent session must either be registered in sessionToRootMap or be a new root session
+    const parentRootSessionID = sessionToRootMap.get(parentSessionID);
+    // Determine root session - if parent doesn't exist, treat it as a new root
+    const rootSessionID = parentRootSessionID || parentSessionID;
+    // If parent is not a subagent but we're treating it as a root, create a hierarchy for it
+    // This allows sessions to become roots when their first subagent is registered
+    const hierarchy = getOrCreateHierarchy(rootSessionID, config);
+    const parentSubagent = hierarchy.subagents.get(parentSessionID);
+    const depth = parentSubagent ? parentSubagent.depth + 1 : 1;
+    // Enforce max depth
+    if (depth > maxSubagentDepth) {
+        return false;
+    }
+    const subagent = {
+        sessionID,
+        parentSessionID,
+        depth,
+        fallbackState: "none",
+        createdAt: Date.now(),
+        lastActivity: Date.now(),
+    };
+    hierarchy.subagents.set(sessionID, subagent);
+    sessionToRootMap.set(sessionID, rootSessionID);
+    hierarchy.lastActivity = Date.now();
+    return true;
+}
+/**
+ * Get or create hierarchy for a root session
+ */
+function getOrCreateHierarchy(rootSessionID, config) {
+    let hierarchy = sessionHierarchies.get(rootSessionID);
+    if (!hierarchy) {
+        hierarchy = {
+            rootSessionID,
+            subagents: new Map(),
+            sharedFallbackState: "none",
+            sharedConfig: config,
+            createdAt: Date.now(),
+            lastActivity: Date.now(),
+        };
+        sessionHierarchies.set(rootSessionID, hierarchy);
+        sessionToRootMap.set(rootSessionID, rootSessionID);
+    }
+    return hierarchy;
+}
+/**
+ * Get root session ID for a session
+ */
+export function getRootSession(sessionID) {
+    return sessionToRootMap.get(sessionID) || null;
+}
+/**
+ * Get hierarchy for a session
+ */
+export function getHierarchy(sessionID) {
+    const rootSessionID = getRootSession(sessionID);
+    return rootSessionID ? sessionHierarchies.get(rootSessionID) || null : null;
+}
+/**
+ * Get all session hierarchies (for cleanup)
+ */
+export function getAllHierarchies() {
+    return sessionHierarchies;
+}
+/**
+ * Get session to root map (for cleanup)
+ */
+export function getSessionToRootMap() {
+    return sessionToRootMap;
+}
+/**
+ * Clean up stale hierarchies
+ */
+export function cleanupStaleEntries() {
+    const now = Date.now();
+    for (const [rootSessionID, hierarchy] of sessionHierarchies.entries()) {
+        if (now - hierarchy.lastActivity > SESSION_ENTRY_TTL_MS) {
+            // Clean up all subagents in this hierarchy
+            for (const subagentID of hierarchy.subagents.keys()) {
+                sessionToRootMap.delete(subagentID);
+            }
+            sessionHierarchies.delete(rootSessionID);
+            sessionToRootMap.delete(rootSessionID);
+        }
+    }
+}
+/**
+ * Clean up all hierarchies
+ */
+export function clearAll() {
+    sessionHierarchies.clear();
+    sessionToRootMap.clear();
+}