@poolzin/pool-bot 2026.2.20 → 2026.2.21

package/dist/agents/provider/session-binding.js

@@ -0,0 +1,376 @@
+/**
+ * Session Manager
+ *
+ * Manages sticky session bindings between conversation sessions and API tokens.
+ * Ensures conversation continuity by routing requests to the same key when possible.
+ *
+ * @module provider/session-binding
+ */
+import { createSubsystemLogger } from "../../logging/subsystem.js";
+export var SessionManager;
+(function (SessionManager) {
+    const log = createSubsystemLogger("provider/session-binding");
+    // ============================================================================
+    // Internal State
+    // ============================================================================
+    /** Session bindings: sessionID:providerID -> Binding */
+    const bindings = new Map();
+    /** Configuration */
+    let config = {
+        defaultTTLMs: 60_000, // 60 seconds
+        maxBindings: 10_000,
+        extendOnAccess: true,
+    };
+    /** Cleanup interval handle */
+    let cleanupInterval = null;
+    // ============================================================================
+    // Helper Functions
+    // ============================================================================
+    /**
+     * Creates a composite key for the bindings map.
+     */
+    function getBindingKey(sessionID, providerID) {
+        return `${sessionID}:${providerID}`;
+    }
+    /**
+     * Checks if a binding is expired.
+     */
+    function isExpired(binding) {
+        return Date.now() > binding.expiresAt;
+    }
+    /**
+     * Evicts oldest bindings if over capacity.
+     */
+    function evictIfNeeded() {
+        if (bindings.size <= config.maxBindings)
+            return;
+        // Sort by last accessed time and remove oldest
+        const sorted = Array.from(bindings.entries()).sort((a, b) => a[1].lastAccessedAt - b[1].lastAccessedAt);
+        const toRemove = sorted.slice(0, bindings.size - config.maxBindings);
+        for (const [key] of toRemove) {
+            bindings.delete(key);
+        }
+        log.info("evicted", { count: toRemove.length });
+    }
+    // ============================================================================
+    // Public API
+    // ============================================================================
+    /**
+     * Configures the session manager.
+     *
+     * @param newConfig - Partial configuration to merge
+     *
+     * @example
+     * ```typescript
+     * SessionManager.configure({
+     *   defaultTTLMs: 120_000, // 2 minutes
+     *   extendOnAccess: true
+     * })
+     * ```
+     */
+    function configure(newConfig) {
+        config = { ...config, ...newConfig };
+        log.info("configured", { ...config });
+    }
+    SessionManager.configure = configure;
+    /**
+     * Gets the current configuration.
+     */
+    function getConfig() {
+        return { ...config };
+    }
+    SessionManager.getConfig = getConfig;
+    /**
+     * Creates or updates a session binding.
+     *
+     * @param sessionID - Session identifier
+     * @param providerID - Provider identifier
+     * @param tokenID - Token identifier to bind to
+     * @param ttlMs - Custom TTL (uses default if not specified)
+     *
+     * @example
+     * ```typescript
+     * SessionManager.bind("session-123", "anthropic", "key-1")
+     * ```
+     */
+    function bind(sessionID, providerID, tokenID, ttlMs) {
+        const key = getBindingKey(sessionID, providerID);
+        const now = Date.now();
+        const ttl = ttlMs ?? config.defaultTTLMs;
+        const existing = bindings.get(key);
+        if (existing && existing.tokenID === tokenID) {
+            // Update existing binding
+            existing.lastAccessedAt = now;
+            existing.expiresAt = now + ttl;
+            existing.requestCount++;
+            return existing;
+        }
+        // Create new binding
+        const binding = {
+            sessionID,
+            providerID,
+            tokenID,
+            createdAt: now,
+            lastAccessedAt: now,
+            expiresAt: now + ttl,
+            requestCount: 1,
+        };
+        bindings.set(key, binding);
+        evictIfNeeded();
+        log.info("bound", { sessionID, providerID, tokenID, ttlMs: ttl });
+        return binding;
+    }
+    SessionManager.bind = bind;
+    /**
+     * Looks up a session binding.
+     *
+     * @param sessionID - Session identifier
+     * @param providerID - Provider identifier
+     * @returns Lookup result with binding if found and valid
+     *
+     * @example
+     * ```typescript
+     * const result = SessionManager.lookup("session-123", "anthropic")
+     * if (result.found && !result.expired) {
+     *   console.log("Using token:", result.binding.tokenID)
+     * }
+     * ```
+     */
+    function lookup(sessionID, providerID) {
+        const key = getBindingKey(sessionID, providerID);
+        const binding = bindings.get(key);
+        if (!binding) {
+            return { found: false, expired: false };
+        }
+        if (isExpired(binding)) {
+            bindings.delete(key);
+            return { found: true, expired: true };
+        }
+        // Extend TTL on access if configured
+        if (config.extendOnAccess) {
+            binding.lastAccessedAt = Date.now();
+            binding.expiresAt = binding.lastAccessedAt + config.defaultTTLMs;
+        }
+        return { binding, found: true, expired: false };
+    }
+    SessionManager.lookup = lookup;
+    /**
+     * Gets the bound token ID for a session, if any.
+     *
+     * @param sessionID - Session identifier
+     * @param providerID - Provider identifier
+     * @returns Token ID or undefined if not bound
+     */
+    function getBoundToken(sessionID, providerID) {
+        const result = lookup(sessionID, providerID);
+        return result.binding?.tokenID;
+    }
+    SessionManager.getBoundToken = getBoundToken;
+    /**
+     * Removes a session binding.
+     *
+     * @param sessionID - Session identifier
+     * @param providerID - Provider identifier
+     * @returns Whether a binding was found and removed
+     */
+    function unbind(sessionID, providerID) {
+        const key = getBindingKey(sessionID, providerID);
+        const removed = bindings.delete(key);
+        if (removed) {
+            log.info("unbound", { sessionID, providerID });
+        }
+        return removed;
+    }
+    SessionManager.unbind = unbind;
+    /**
+     * Removes all bindings for a session.
+     *
+     * @param sessionID - Session identifier
+     * @returns Number of bindings removed
+     */
+    function unbindSession(sessionID) {
+        let count = 0;
+        const prefix = `${sessionID}:`;
+        for (const key of bindings.keys()) {
+            if (key.startsWith(prefix)) {
+                bindings.delete(key);
+                count++;
+            }
+        }
+        if (count > 0) {
+            log.info("session-unbound", { sessionID, count });
+        }
+        return count;
+    }
+    SessionManager.unbindSession = unbindSession;
+    /**
+     * Removes all bindings for a provider.
+     *
+     * @param providerID - Provider identifier
+     * @returns Number of bindings removed
+     */
+    function unbindProvider(providerID) {
+        let count = 0;
+        const suffix = `:${providerID}`;
+        for (const key of bindings.keys()) {
+            if (key.endsWith(suffix)) {
+                bindings.delete(key);
+                count++;
+            }
+        }
+        if (count > 0) {
+            log.info("provider-unbound", { providerID, count });
+        }
+        return count;
+    }
+    SessionManager.unbindProvider = unbindProvider;
+    /**
+     * Removes all bindings for a specific token.
+     *
+     * @param providerID - Provider identifier
+     * @param tokenID - Token identifier
+     * @returns Number of bindings removed
+     */
+    function unbindToken(providerID, tokenID) {
+        let count = 0;
+        for (const [key, binding] of bindings.entries()) {
+            if (binding.providerID === providerID && binding.tokenID === tokenID) {
+                bindings.delete(key);
+                count++;
+            }
+        }
+        if (count > 0) {
+            log.info("token-unbound", { providerID, tokenID, count });
+        }
+        return count;
+    }
+    SessionManager.unbindToken = unbindToken;
+    /**
+     * Gets all bindings for a session.
+     *
+     * @param sessionID - Session identifier
+     * @returns Array of bindings
+     */
+    function getSessionBindings(sessionID) {
+        const result = [];
+        const now = Date.now();
+        const prefix = `${sessionID}:`;
+        for (const [key, binding] of bindings.entries()) {
+            if (key.startsWith(prefix) && binding.expiresAt > now) {
+                result.push({ ...binding });
+            }
+        }
+        return result;
+    }
+    SessionManager.getSessionBindings = getSessionBindings;
+    /**
+     * Gets all bindings for a provider.
+     *
+     * @param providerID - Provider identifier
+     * @returns Array of bindings
+     */
+    function getProviderBindings(providerID) {
+        const result = [];
+        const now = Date.now();
+        for (const binding of bindings.values()) {
+            if (binding.providerID === providerID && binding.expiresAt > now) {
+                result.push({ ...binding });
+            }
+        }
+        return result;
+    }
+    SessionManager.getProviderBindings = getProviderBindings;
+    /**
+     * Gets summary statistics for session bindings.
+     */
+    function getSummary() {
+        const now = Date.now();
+        let activeCount = 0;
+        let expiredCount = 0;
+        let totalRequests = 0;
+        let totalAge = 0;
+        const byProvider = {};
+        for (const binding of bindings.values()) {
+            if (binding.expiresAt > now) {
+                activeCount++;
+                totalRequests += binding.requestCount;
+                totalAge += now - binding.createdAt;
+                byProvider[binding.providerID] = (byProvider[binding.providerID] ?? 0) + 1;
+            }
+            else {
+                expiredCount++;
+            }
+        }
+        return {
+            totalBindings: bindings.size,
+            activeBindings: activeCount,
+            expiredBindings: expiredCount,
+            byProvider,
+            avgRequestsPerBinding: activeCount > 0 ? totalRequests / activeCount : 0,
+            avgAgeMs: activeCount > 0 ? totalAge / activeCount : 0,
+        };
+    }
+    SessionManager.getSummary = getSummary;
+    /**
+     * Removes expired bindings.
+     *
+     * @returns Number of bindings removed
+     */
+    function cleanupExpired() {
+        const now = Date.now();
+        let removed = 0;
+        for (const [key, binding] of bindings.entries()) {
+            if (binding.expiresAt <= now) {
+                bindings.delete(key);
+                removed++;
+            }
+        }
+        if (removed > 0) {
+            log.info("cleanup", { removed });
+        }
+        return removed;
+    }
+    SessionManager.cleanupExpired = cleanupExpired;
+    /**
+     * Clears all bindings.
+     */
+    function clear() {
+        const count = bindings.size;
+        bindings.clear();
+        if (count > 0) {
+            log.info("cleared", { count });
+        }
+    }
+    SessionManager.clear = clear;
+    /**
+     * Starts the automatic cleanup interval.
+     *
+     * @param intervalMs - Cleanup interval in milliseconds (default: 30000)
+     */
+    function startCleanup(intervalMs = 30_000) {
+        if (cleanupInterval)
+            return;
+        cleanupInterval = setInterval(() => {
+            cleanupExpired();
+        }, intervalMs);
+        // Don't keep the process alive just for cleanup
+        if (typeof cleanupInterval.unref === "function") {
+            cleanupInterval.unref();
+        }
+        log.debug("cleanup-started", { intervalMs });
+    }
+    SessionManager.startCleanup = startCleanup;
+    /**
+     * Stops the automatic cleanup interval.
+     */
+    function stopCleanup() {
+        if (cleanupInterval) {
+            clearInterval(cleanupInterval);
+            cleanupInterval = null;
+            log.info("cleanup-stopped");
+        }
+    }
+    SessionManager.stopCleanup = stopCleanup;
+    // Start cleanup on module load
+    startCleanup();
+})(SessionManager || (SessionManager = {}));