@poolzin/pool-bot 2026.2.20 → 2026.2.21

package/dist/agents/provider/token-pool.js

@@ -0,0 +1,541 @@
+/**
+ * Token Pool Manager
+ *
+ * Manages multiple API keys per provider with intelligent rotation,
+ * rate limit awareness, and scheduling strategies.
+ *
+ * @module provider/token-pool
+ */
+import { createSubsystemLogger } from "../../logging/subsystem.js";
+import { RateLimits } from "./rate-limits.js";
+export var TokenPool;
+(function (TokenPool) {
+    const log = createSubsystemLogger("provider/token-pool");
+    // ============================================================================
+    // Internal State
+    // ============================================================================
+    /** Pools per provider */
+    const pools = new Map();
+    /** Maximum number of provider pools to prevent unbounded growth */
+    const MAX_POOLS = 50;
+    /** Default pool configuration */
+    const DEFAULT_CONFIG = {
+        scheduling: "priority",
+        maxWaitMs: 5000,
+        autoDisable: true,
+        autoDisableThreshold: 5,
+    };
+    /** Tier priority (lower is higher priority) */
+    const TIER_PRIORITY = {
+        enterprise: 0,
+        paid: 1,
+        free: 2,
+    };
+    // ============================================================================
+    // Helper Functions
+    // ============================================================================
+    /**
+     * Gets or creates a pool for a provider.
+     * Enforces MAX_POOLS limit by evicting least recently used pools.
+     */
+    function getOrCreatePool(providerID) {
+        let pool = pools.get(providerID);
+        if (!pool) {
+            if (pools.size >= MAX_POOLS) {
+                evictLeastUsedPool();
+            }
+            pool = {
+                providerID,
+                config: { ...DEFAULT_CONFIG },
+                tokens: new Map(),
+                currentIndex: 0,
+                failureCounts: new Map(),
+            };
+            pools.set(providerID, pool);
+        }
+        return pool;
+    }
+    /**
+     * Evicts the pool with the fewest total requests (least used).
+     */
+    function evictLeastUsedPool() {
+        let leastUsedID;
+        let leastUsedRequests = Infinity;
+        for (const [providerID, pool] of pools.entries()) {
+            const totalRequests = Array.from(pool.tokens.values()).reduce((sum, t) => sum + t.usage.totalRequests, 0);
+            if (totalRequests < leastUsedRequests) {
+                leastUsedRequests = totalRequests;
+                leastUsedID = providerID;
+            }
+        }
+        if (leastUsedID) {
+            pools.delete(leastUsedID);
+            RateLimits.clearProvider(leastUsedID);
+            log.info("pool-evicted", { providerID: leastUsedID, reason: "max-pools-reached" });
+        }
+    }
+    /**
+     * Creates a default token entry.
+     */
+    function createTokenEntry(id, key, tier = "paid", label) {
+        return {
+            id,
+            key,
+            tier,
+            enabled: true,
+            label,
+            usage: {
+                totalRequests: 0,
+                totalInputTokens: 0,
+                totalOutputTokens: 0,
+                requestsToday: 0,
+            },
+            addedAt: Date.now(),
+        };
+    }
+    /**
+     * Gets available (enabled and not rate-limited) tokens from a pool.
+     */
+    function getAvailableTokens(pool) {
+        const available = [];
+        for (const token of pool.tokens.values()) {
+            if (!token.enabled)
+                continue;
+            const limitCheck = RateLimits.isLimited(pool.providerID, token.id);
+            if (!limitCheck.isLimited) {
+                available.push(token);
+            }
+        }
+        return available;
+    }
+    /**
+     * Sorts tokens by scheduling strategy.
+     */
+    function sortByStrategy(tokens, mode) {
+        switch (mode) {
+            case "priority":
+                return [...tokens].sort((a, b) => {
+                    // First by tier
+                    const tierDiff = TIER_PRIORITY[a.tier] - TIER_PRIORITY[b.tier];
+                    if (tierDiff !== 0)
+                        return tierDiff;
+                    // Then by least used
+                    return a.usage.totalRequests - b.usage.totalRequests;
+                });
+            case "least-used":
+                return [...tokens].sort((a, b) => a.usage.totalRequests - b.usage.totalRequests);
+            case "random":
+                return [...tokens].sort(() => Math.random() - 0.5);
+            case "round-robin":
+            default:
+                return tokens;
+        }
+    }
+    /**
+     * Gets the current date string (YYYY-MM-DD).
+     */
+    function getDateString() {
+        return new Date().toISOString().split("T")[0];
+    }
+    /**
+     * Resets daily counters if needed.
+     */
+    function resetDailyCountersIfNeeded(token) {
+        const today = getDateString();
+        if (token.usage.requestsDate !== today) {
+            token.usage.requestsToday = 0;
+            token.usage.requestsDate = today;
+        }
+    }
+    // ============================================================================
+    // Public API
+    // ============================================================================
+    /**
+     * Adds a token to a provider's pool.
+     *
+     * @param providerID - Provider identifier
+     * @param id - Unique token identifier
+     * @param key - The API key
+     * @param options - Additional options
+     *
+     * @example
+     * ```typescript
+     * TokenPool.addToken("anthropic", "personal", "sk-ant-...", {
+     *   tier: "paid",
+     *   label: "Personal API Key"
+     * })
+     * ```
+     */
+    function addToken(providerID, id, key, options = {}) {
+        const pool = getOrCreatePool(providerID);
+        const entry = createTokenEntry(id, key, options.tier ?? "paid", options.label);
+        if (options.enabled !== undefined) {
+            entry.enabled = options.enabled;
+        }
+        pool.tokens.set(id, entry);
+        log.info("token-added", { providerID, tokenID: id, tier: entry.tier });
+        return entry;
+    }
+    TokenPool.addToken = addToken;
+    /**
+     * Removes a token from a provider's pool.
+     *
+     * @param providerID - Provider identifier
+     * @param tokenID - Token identifier to remove
+     * @returns Whether the token was found and removed
+     */
+    function removeToken(providerID, tokenID) {
+        const pool = pools.get(providerID);
+        if (!pool)
+            return false;
+        const removed = pool.tokens.delete(tokenID);
+        if (removed) {
+            pool.failureCounts.delete(tokenID);
+            RateLimits.clear(providerID, tokenID);
+            log.info("token-removed", { providerID, tokenID });
+        }
+        return removed;
+    }
+    TokenPool.removeToken = removeToken;
+    /**
+     * Configures a provider's token pool.
+     *
+     * @param providerID - Provider identifier
+     * @param poolConfig - Partial configuration to merge
+     *
+     * @example
+     * ```typescript
+     * TokenPool.configure("anthropic", {
+     *   scheduling: "priority",
+     *   maxWaitMs: 10000
+     * })
+     * ```
+     */
+    function configure(providerID, poolConfig) {
+        const pool = getOrCreatePool(providerID);
+        pool.config = { ...pool.config, ...poolConfig };
+        log.info("configured", { providerID, config: { ...pool.config } });
+    }
+    TokenPool.configure = configure;
+    /**
+     * Gets the current configuration for a provider.
+     *
+     * @param providerID - Provider identifier
+     * @returns Configuration or default if no pool exists
+     */
+    function getConfig(providerID) {
+        const pool = pools.get(providerID);
+        return pool?.config ?? { ...DEFAULT_CONFIG };
+    }
+    TokenPool.getConfig = getConfig;
+    /**
+     * Gets a token from the pool using the configured scheduling strategy.
+     * Automatically skips rate-limited tokens.
+     *
+     * @param providerID - Provider identifier
+     * @param options - Selection options
+     * @returns Token result or undefined if no tokens available
+     *
+     * @example
+     * ```typescript
+     * const result = await TokenPool.getToken("anthropic")
+     * if (result) {
+     *   console.log("Using token:", result.token.id)
+     *   // Make API call with result.token.key
+     * }
+     * ```
+     */
+    async function getToken(providerID, options = {}) {
+        const pool = pools.get(providerID);
+        if (!pool || pool.tokens.size === 0) {
+            return undefined;
+        }
+        const maxWaitMs = options.maxWaitMs ?? pool.config.maxWaitMs;
+        // Check preferred token first (for sticky sessions)
+        if (options.preferredTokenID) {
+            const preferred = pool.tokens.get(options.preferredTokenID);
+            if (preferred?.enabled) {
+                const limitCheck = RateLimits.isLimited(providerID, preferred.id);
+                if (!limitCheck.isLimited) {
+                    return {
+                        token: preferred,
+                        waited: false,
+                        waitedMs: 0,
+                        onlyOption: pool.tokens.size === 1,
+                    };
+                }
+                // Wait for preferred if requested and wait time is acceptable
+                if (options.waitForPreferred && limitCheck.waitTimeMs <= maxWaitMs) {
+                    log.info("waiting-for-preferred", {
+                        providerID,
+                        tokenID: preferred.id,
+                        waitMs: limitCheck.waitTimeMs,
+                    });
+                    await sleep(limitCheck.waitTimeMs);
+                    return {
+                        token: preferred,
+                        waited: true,
+                        waitedMs: limitCheck.waitTimeMs,
+                        onlyOption: pool.tokens.size === 1,
+                    };
+                }
+            }
+        }
+        // Get available tokens
+        const available = getAvailableTokens(pool);
+        if (available.length > 0) {
+            // Sort by strategy
+            const sorted = sortByStrategy(available, pool.config.scheduling);
+            // For round-robin, use index
+            let selected;
+            if (pool.config.scheduling === "round-robin") {
+                pool.currentIndex = pool.currentIndex % sorted.length;
+                selected = sorted[pool.currentIndex];
+                pool.currentIndex++;
+            }
+            else {
+                selected = sorted[0];
+            }
+            return {
+                token: selected,
+                waited: false,
+                waitedMs: 0,
+                onlyOption: available.length === 1,
+            };
+        }
+        // All tokens are rate-limited, find the one that resets soonest
+        const allTokens = Array.from(pool.tokens.values()).filter((t) => t.enabled);
+        if (allTokens.length === 0) {
+            return undefined;
+        }
+        let soonestToken;
+        let soonestWaitMs = Infinity;
+        for (const token of allTokens) {
+            const limitCheck = RateLimits.isLimited(providerID, token.id);
+            if (limitCheck.waitTimeMs < soonestWaitMs) {
+                soonestWaitMs = limitCheck.waitTimeMs;
+                soonestToken = token;
+            }
+        }
+        if (!soonestToken) {
+            return undefined;
+        }
+        // Wait if within acceptable range
+        if (soonestWaitMs <= maxWaitMs) {
+            log.info("waiting-for-soonest", {
+                providerID,
+                tokenID: soonestToken.id,
+                waitMs: soonestWaitMs,
+            });
+            await sleep(soonestWaitMs);
+            return {
+                token: soonestToken,
+                waited: true,
+                waitedMs: soonestWaitMs,
+                onlyOption: allTokens.length === 1,
+            };
+        }
+        // Return soonest token anyway (caller can decide to wait or fail)
+        return {
+            token: soonestToken,
+            waited: false,
+            waitedMs: 0,
+            onlyOption: allTokens.length === 1,
+        };
+    }
+    TokenPool.getToken = getToken;
+    /**
+     * Records a successful request with a token.
+     *
+     * @param providerID - Provider identifier
+     * @param tokenID - Token identifier
+     * @param usage - Token usage from the request
+     */
+    function recordSuccess(providerID, tokenID, usage) {
+        const pool = pools.get(providerID);
+        const token = pool?.tokens.get(tokenID);
+        if (!pool || !token)
+            return;
+        // Reset failure count on success
+        pool.failureCounts.set(tokenID, 0);
+        // Update usage stats
+        resetDailyCountersIfNeeded(token);
+        token.usage.totalRequests++;
+        token.usage.requestsToday++;
+        token.usage.lastUsedAt = Date.now();
+        if (usage?.inputTokens) {
+            token.usage.totalInputTokens += usage.inputTokens;
+        }
+        if (usage?.outputTokens) {
+            token.usage.totalOutputTokens += usage.outputTokens;
+        }
+    }
+    TokenPool.recordSuccess = recordSuccess;
+    /**
+     * Records a failed request with a token.
+     * May auto-disable the token if threshold is reached.
+     *
+     * @param providerID - Provider identifier
+     * @param tokenID - Token identifier
+     * @param statusCode - HTTP status code
+     * @param headers - Response headers (for rate limit parsing)
+     */
+    function recordFailure(providerID, tokenID, statusCode, headers) {
+        const pool = pools.get(providerID);
+        const token = pool?.tokens.get(tokenID);
+        if (!pool || !token)
+            return;
+        // Track rate limits
+        if (statusCode === RateLimits.RATE_LIMIT_STATUS_CODES.TOO_MANY_REQUESTS ||
+            statusCode === RateLimits.RATE_LIMIT_STATUS_CODES.SERVICE_UNAVAILABLE ||
+            statusCode === RateLimits.RATE_LIMIT_STATUS_CODES.SITE_OVERLOADED) {
+            if (headers) {
+                RateLimits.markLimitedFromResponse(providerID, statusCode, headers, tokenID);
+            }
+            else {
+                RateLimits.markLimited(providerID, statusCode, `HTTP ${statusCode}`, {
+                    keyID: tokenID,
+                });
+            }
+        }
+        // Track consecutive failures
+        const failures = (pool.failureCounts.get(tokenID) ?? 0) + 1;
+        pool.failureCounts.set(tokenID, failures);
+        // Auto-disable if threshold reached
+        if (pool.config.autoDisable && failures >= pool.config.autoDisableThreshold) {
+            token.enabled = false;
+            log.warn("token-auto-disabled", {
+                providerID,
+                tokenID,
+                failures,
+                threshold: pool.config.autoDisableThreshold,
+            });
+        }
+    }
+    TokenPool.recordFailure = recordFailure;
+    /**
+     * Enables a previously disabled token.
+     *
+     * @param providerID - Provider identifier
+     * @param tokenID - Token identifier
+     */
+    function enableToken(providerID, tokenID) {
+        const pool = pools.get(providerID);
+        const token = pool?.tokens.get(tokenID);
+        if (!pool || !token)
+            return false;
+        token.enabled = true;
+        pool.failureCounts.set(tokenID, 0);
+        RateLimits.clear(providerID, tokenID);
+        log.info("token-enabled", { providerID, tokenID });
+        return true;
+    }
+    TokenPool.enableToken = enableToken;
+    /**
+     * Disables a token.
+     *
+     * @param providerID - Provider identifier
+     * @param tokenID - Token identifier
+     */
+    function disableToken(providerID, tokenID) {
+        const pool = pools.get(providerID);
+        const token = pool?.tokens.get(tokenID);
+        if (!token)
+            return false;
+        token.enabled = false;
+        log.info("token-disabled", { providerID, tokenID });
+        return true;
+    }
+    TokenPool.disableToken = disableToken;
+    /**
+     * Gets all tokens for a provider.
+     *
+     * @param providerID - Provider identifier
+     * @returns Array of token entries (without key values for security)
+     */
+    function getTokens(providerID) {
+        const pool = pools.get(providerID);
+        if (!pool)
+            return [];
+        return Array.from(pool.tokens.values()).map((t) => {
+            const { key: _key, ...rest } = t;
+            return rest;
+        });
+    }
+    TokenPool.getTokens = getTokens;
+    /**
+     * Gets a summary of a provider's pool.
+     *
+     * @param providerID - Provider identifier
+     */
+    function getPoolSummary(providerID) {
+        const pool = pools.get(providerID);
+        if (!pool)
+            return undefined;
+        const tokens = Array.from(pool.tokens.values());
+        const enabled = tokens.filter((t) => t.enabled);
+        const available = getAvailableTokens(pool);
+        const rateLimited = enabled.length - available.length;
+        return {
+            providerID,
+            config: pool.config,
+            totalTokens: tokens.length,
+            enabledTokens: enabled.length,
+            availableTokens: available.length,
+            rateLimitedTokens: rateLimited,
+            tokens: tokens.map((t) => {
+                const { key: _key, ...rest } = t;
+                return rest;
+            }),
+        };
+    }
+    TokenPool.getPoolSummary = getPoolSummary;
+    /**
+     * Gets summaries for all pools.
+     */
+    function getAllPoolSummaries() {
+        const result = {};
+        for (const providerID of pools.keys()) {
+            result[providerID] = getPoolSummary(providerID);
+        }
+        return result;
+    }
+    TokenPool.getAllPoolSummaries = getAllPoolSummaries;
+    /**
+     * Checks if a provider has a token pool configured.
+     *
+     * @param providerID - Provider identifier
+     */
+    function hasPool(providerID) {
+        const pool = pools.get(providerID);
+        return pool !== undefined && pool.tokens.size > 0;
+    }
+    TokenPool.hasPool = hasPool;
+    /**
+     * Clears all tokens from a provider's pool.
+     *
+     * @param providerID - Provider identifier
+     */
+    function clearPool(providerID) {
+        pools.delete(providerID);
+        RateLimits.clearProvider(providerID);
+        log.info("pool-cleared", { providerID });
+    }
+    TokenPool.clearPool = clearPool;
+    /**
+     * Clears all pools.
+     */
+    function clearAll() {
+        const count = pools.size;
+        pools.clear();
+        RateLimits.clearAll();
+        log.info("all-pools-cleared", { count });
+    }
+    TokenPool.clearAll = clearAll;
+    /**
+     * Simple sleep utility.
+     */
+    function sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+})(TokenPool || (TokenPool = {}));

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "version": "2026.2.20",
-  "commit": "d55929d079a2231e96e962d49e52c54efb661a80",
-  "builtAt": "2026-02-18T03:33:36.817Z"
+  "version": "2026.2.21",
+  "commit": "c1b8db5b38e189213061393716632d810d42bafd",
+  "builtAt": "2026-02-18T06:05:30.087Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolzin/pool-bot",
-  "version": "2026.2.20",
+  "version": "2026.2.21",
   "description": "🎱 Pool Bot - AI assistant with PLCODE integrations",
   "keywords": [],
   "license": "MIT",