@itssimplereally/opencode-kimicode-auth 0.1.0

package/dist/src/plugin/refresh-queue.js

@@ -0,0 +1,248 @@
+/**
+ * Proactive Token Refresh Queue
+ *
+ * Ported from LLM-API-Key-Proxy's BackgroundRefresher.
+ *
+ * This module provides background token refresh to ensure OAuth tokens
+ * remain valid without blocking user requests. It periodically checks
+ * all accounts and refreshes tokens that are approaching expiry.
+ *
+ * Features:
+ * - Non-blocking background refresh (doesn't block requests)
+ * - Configurable refresh buffer (default: 30 minutes before expiry)
+ * - Configurable check interval (default: 5 minutes)
+ * - Serialized refresh to prevent concurrent refresh storms
+ * - Integrates with existing AccountManager and token refresh logic
+ * - Silent operation: no console output, uses structured logger
+ */
+import { refreshAccessToken } from "./token";
+import { createLogger } from "./logger";
+const log = createLogger("refresh-queue");
+export const DEFAULT_PROACTIVE_REFRESH_CONFIG = {
+    enabled: true,
+    bufferSeconds: 1800, // 30 minutes
+    checkIntervalSeconds: 300, // 5 minutes
+};
+/**
+ * Proactive Token Refresh Queue
+ *
+ * Runs in the background and proactively refreshes tokens before they expire.
+ * This ensures that user requests never block on token refresh.
+ *
+ * All logging is silent by default - uses structured logger that only outputs
+ * when OPENCODE_KIMICODE_CONSOLE_LOG=1 is set or TUI logging is available.
+ */
+export class ProactiveRefreshQueue {
+    config;
+    client;
+    providerId;
+    accountManager = null;
+    state = {
+        isRunning: false,
+        intervalHandle: null,
+        isRefreshing: false,
+        lastCheckTime: 0,
+        lastRefreshTime: 0,
+        refreshCount: 0,
+        errorCount: 0,
+    };
+    constructor(client, providerId, config) {
+        this.client = client;
+        this.providerId = providerId;
+        this.config = {
+            ...DEFAULT_PROACTIVE_REFRESH_CONFIG,
+            ...config,
+        };
+    }
+    /**
+     * Set the account manager to use for refresh operations.
+     * Must be called before start().
+     */
+    setAccountManager(manager) {
+        this.accountManager = manager;
+    }
+    /**
+     * Check if a token needs proactive refresh.
+     * Returns true if the token expires within the buffer period.
+     */
+    needsRefresh(account) {
+        if (!account.expires) {
+            // No expiry set - assume it's fine
+            return false;
+        }
+        const now = Date.now();
+        const bufferMs = this.config.bufferSeconds * 1000;
+        const refreshThreshold = now + bufferMs;
+        return account.expires <= refreshThreshold;
+    }
+    /**
+     * Check if a token is already expired.
+     */
+    isExpired(account) {
+        if (!account.expires) {
+            return false;
+        }
+        return account.expires <= Date.now();
+    }
+    /**
+     * Get all accounts that need proactive refresh.
+     */
+    getAccountsNeedingRefresh() {
+        if (!this.accountManager) {
+            return [];
+        }
+        return this.accountManager.getAccounts().filter((account) => {
+            // Skip disabled accounts - they shouldn't receive proactive refresh
+            if (account.enabled === false) {
+                return false;
+            }
+            // Only refresh if not already expired (let the main flow handle expired tokens)
+            if (this.isExpired(account)) {
+                return false;
+            }
+            return this.needsRefresh(account);
+        });
+    }
+    /**
+     * Perform a single refresh check iteration.
+     * This is called periodically by the background interval.
+     */
+    async runRefreshCheck() {
+        if (this.state.isRefreshing) {
+            // Already refreshing - skip this iteration
+            return;
+        }
+        if (!this.accountManager) {
+            return;
+        }
+        this.state.isRefreshing = true;
+        this.state.lastCheckTime = Date.now();
+        try {
+            const accountsToRefresh = this.getAccountsNeedingRefresh();
+            if (accountsToRefresh.length === 0) {
+                return;
+            }
+            log.debug("Found accounts needing refresh", { count: accountsToRefresh.length });
+            // Refresh accounts serially to avoid concurrent refresh storms
+            for (const account of accountsToRefresh) {
+                if (!this.state.isRunning) {
+                    // Queue was stopped - abort
+                    break;
+                }
+                try {
+                    const auth = this.accountManager.toAuthDetails(account);
+                    const refreshed = await this.refreshToken(auth, account);
+                    if (refreshed) {
+                        this.accountManager.updateFromAuth(account, refreshed);
+                        this.state.refreshCount++;
+                        this.state.lastRefreshTime = Date.now();
+                        // Persist the refreshed token
+                        try {
+                            await this.accountManager.saveToDisk();
+                        }
+                        catch {
+                            // Non-fatal - token is refreshed in memory
+                        }
+                    }
+                }
+                catch (error) {
+                    this.state.errorCount++;
+                    // Log but don't throw - continue with other accounts
+                    log.warn("Failed to refresh account", {
+                        accountIndex: account.index,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        }
+        finally {
+            this.state.isRefreshing = false;
+        }
+    }
+    /**
+     * Refresh a single token.
+     */
+    async refreshToken(auth, account) {
+        const minutesUntilExpiry = account.expires
+            ? Math.round((account.expires - Date.now()) / 60000)
+            : "unknown";
+        log.debug("Proactively refreshing token", {
+            accountIndex: account.index,
+            email: account.email ?? "unknown",
+            minutesUntilExpiry,
+        });
+        return refreshAccessToken(auth, this.client, this.providerId);
+    }
+    /**
+     * Start the background refresh queue.
+     */
+    start() {
+        if (this.state.isRunning) {
+            return;
+        }
+        if (!this.config.enabled) {
+            log.debug("Proactive refresh disabled by config");
+            return;
+        }
+        this.state.isRunning = true;
+        const intervalMs = this.config.checkIntervalSeconds * 1000;
+        log.debug("Started proactive refresh queue", {
+            checkIntervalSeconds: this.config.checkIntervalSeconds,
+            bufferSeconds: this.config.bufferSeconds,
+        });
+        // Run initial check after a short delay (let things settle)
+        setTimeout(() => {
+            if (this.state.isRunning) {
+                this.runRefreshCheck().catch((error) => {
+                    log.error("Initial check failed", {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                });
+            }
+        }, 5000);
+        // Set up periodic checks
+        this.state.intervalHandle = setInterval(() => {
+            this.runRefreshCheck().catch((error) => {
+                log.error("Check failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+        }, intervalMs);
+    }
+    /**
+     * Stop the background refresh queue.
+     */
+    stop() {
+        if (!this.state.isRunning) {
+            return;
+        }
+        this.state.isRunning = false;
+        if (this.state.intervalHandle) {
+            clearInterval(this.state.intervalHandle);
+            this.state.intervalHandle = null;
+        }
+        log.debug("Stopped proactive refresh queue", {
+            refreshCount: this.state.refreshCount,
+            errorCount: this.state.errorCount,
+        });
+    }
+    /**
+     * Get current queue statistics.
+     */
+    getStats() {
+        return { ...this.state };
+    }
+    /**
+     * Check if the queue is currently running.
+     */
+    isRunning() {
+        return this.state.isRunning;
+    }
+}
+/**
+ * Create a proactive refresh queue instance.
+ */
+export function createProactiveRefreshQueue(client, providerId, config) {
+    return new ProactiveRefreshQueue(client, providerId, config);
+}
+//# sourceMappingURL=refresh-queue.js.map

package/dist/src/plugin/refresh-queue.js.map

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

package/dist/src/plugin/rotation.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Account Rotation System
+ *
+ * Implements advanced account selection algorithms:
+ * - Health Score: Track account wellness based on success/failure
+ * - LRU Selection: Prefer accounts with longest rest periods
+ * - Jitter: Add random variance to break predictable patterns
+ *
+ * Used by 'hybrid' strategy for improved ban prevention and load distribution.
+ */
+export interface HealthScoreConfig {
+    /** Initial score for new accounts (default: 70) */
+    initial: number;
+    /** Points added on successful request (default: 1) */
+    successReward: number;
+    /** Points removed on rate limit (default: -10) */
+    rateLimitPenalty: number;
+    /** Points removed on failure (auth, network, etc.) (default: -20) */
+    failurePenalty: number;
+    /** Points recovered per hour of rest (default: 2) */
+    recoveryRatePerHour: number;
+    /** Minimum score to be considered usable (default: 50) */
+    minUsable: number;
+    /** Maximum score cap (default: 100) */
+    maxScore: number;
+}
+export declare const DEFAULT_HEALTH_SCORE_CONFIG: HealthScoreConfig;
+/**
+ * Tracks health scores for accounts.
+ * Higher score = healthier account = preferred for selection.
+ */
+export declare class HealthScoreTracker {
+    private readonly scores;
+    private readonly config;
+    constructor(config?: Partial<HealthScoreConfig>);
+    /**
+     * Get current health score for an account, applying time-based recovery.
+     */
+    getScore(accountIndex: number): number;
+    /**
+     * Record a successful request - improves health score.
+     */
+    recordSuccess(accountIndex: number): void;
+    /**
+     * Record a rate limit hit - moderate penalty.
+     */
+    recordRateLimit(accountIndex: number): void;
+    /**
+     * Record a failure (auth, network, etc.) - larger penalty.
+     */
+    recordFailure(accountIndex: number): void;
+    /**
+     * Check if account is healthy enough to use.
+     */
+    isUsable(accountIndex: number): boolean;
+    /**
+     * Get consecutive failure count for an account.
+     */
+    getConsecutiveFailures(accountIndex: number): number;
+    /**
+     * Reset health state for an account (e.g., after removal).
+     */
+    reset(accountIndex: number): void;
+    /**
+     * Get all scores for debugging/logging.
+     */
+    getSnapshot(): Map<number, {
+        score: number;
+        consecutiveFailures: number;
+    }>;
+}
+/**
+ * Add random jitter to a delay value.
+ * Helps break predictable timing patterns.
+ *
+ * @param baseMs - Base delay in milliseconds
+ * @param jitterFactor - Fraction of base to vary (default: 0.3 = ±30%)
+ * @returns Jittered delay in milliseconds
+ */
+export declare function addJitter(baseMs: number, jitterFactor?: number): number;
+/**
+ * Generate a random delay within a range.
+ *
+ * @param minMs - Minimum delay in milliseconds
+ * @param maxMs - Maximum delay in milliseconds
+ * @returns Random delay between min and max
+ */
+export declare function randomDelay(minMs: number, maxMs: number): number;
+export interface AccountWithMetrics {
+    index: number;
+    lastUsed: number;
+    healthScore: number;
+    isRateLimited: boolean;
+    isCoolingDown: boolean;
+}
+/**
+ * Sort accounts by LRU (least recently used first) with health score tiebreaker.
+ *
+ * Priority:
+ * 1. Filter out rate-limited and cooling-down accounts
+ * 2. Filter out unhealthy accounts (score < minUsable)
+ * 3. Sort by lastUsed ascending (oldest first = most rested)
+ * 4. Tiebreaker: higher health score wins
+ */
+export declare function sortByLruWithHealth(accounts: AccountWithMetrics[], minHealthScore?: number): AccountWithMetrics[];
+/**
+ * Select account using hybrid strategy with stickiness:
+ * 1. Filter available accounts (not rate-limited, not cooling down, healthy, has tokens)
+ * 2. Calculate priority score: health (2x) + tokens (5x) + freshness (0.1x)
+ * 3. Apply stickiness bonus to current account
+ * 4. Only switch if another account beats current by SWITCH_THRESHOLD
+ *
+ * @param accounts - All accounts with their metrics
+ * @param tokenTracker - Token bucket tracker for token balances
+ * @param currentAccountIndex - Currently active account index (for stickiness)
+ * @param minHealthScore - Minimum health score to be considered
+ * @returns Best account index, or null if none available
+ */
+export declare function selectHybridAccount(accounts: AccountWithMetrics[], tokenTracker: TokenBucketTracker, currentAccountIndex?: number | null, minHealthScore?: number): number | null;
+export interface TokenBucketConfig {
+    /** Maximum tokens per account (default: 50) */
+    maxTokens: number;
+    /** Tokens regenerated per minute (default: 6) */
+    regenerationRatePerMinute: number;
+    /** Initial tokens for new accounts (default: 50) */
+    initialTokens: number;
+}
+export declare const DEFAULT_TOKEN_BUCKET_CONFIG: TokenBucketConfig;
+/**
+ * Client-side rate limiting using Token Bucket algorithm.
+ * Helps prevent hitting server 429s by tracking "cost" of requests.
+ */
+export declare class TokenBucketTracker {
+    private readonly buckets;
+    private readonly config;
+    constructor(config?: Partial<TokenBucketConfig>);
+    /**
+     * Get current token balance for an account, applying regeneration.
+     */
+    getTokens(accountIndex: number): number;
+    /**
+     * Check if account has enough tokens for a request.
+     * @param cost Cost of the request (default: 1)
+     */
+    hasTokens(accountIndex: number, cost?: number): boolean;
+    /**
+     * Consume tokens for a request.
+     * @returns true if tokens were consumed, false if insufficient
+     */
+    consume(accountIndex: number, cost?: number): boolean;
+    /**
+     * Refund tokens (e.g., if request wasn't actually sent).
+     */
+    refund(accountIndex: number, amount?: number): void;
+    getMaxTokens(): number;
+}
+export declare function getTokenTracker(): TokenBucketTracker;
+export declare function initTokenTracker(config: Partial<TokenBucketConfig>): TokenBucketTracker;
+/**
+ * Get the global health score tracker instance.
+ * Creates one with default config if not initialized.
+ */
+export declare function getHealthTracker(): HealthScoreTracker;
+/**
+ * Initialize the global health tracker with custom config.
+ * Call this at plugin startup if custom config is needed.
+ */
+export declare function initHealthTracker(config: Partial<HealthScoreConfig>): HealthScoreTracker;
+//# sourceMappingURL=rotation.d.ts.map

package/dist/src/plugin/rotation.d.ts.map

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