@poolzin/pool-bot 2026.2.20 → 2026.2.21

package/dist/agents/provider/request-monitor.js

@@ -0,0 +1,449 @@
+/**
+ * Request Monitor
+ *
+ * Provides observability into API requests for debugging, cost analysis, and analytics.
+ * Implements a ring buffer for memory-efficient storage with optional persistence.
+ *
+ * @module provider/request-monitor
+ */
+import { createSubsystemLogger } from "../../logging/subsystem.js";
+export var RequestMonitor;
+(function (RequestMonitor) {
+    const log = createSubsystemLogger("provider/request-monitor");
+    // ============================================================================
+    // Internal State
+    // ============================================================================
+    /** Ring buffer for request logs */
+    const logs = [];
+    /** Per-provider statistics */
+    const providerStats = new Map();
+    /** Overall statistics */
+    let globalStats = createEmptyStats();
+    /** Event listeners */
+    const listeners = new Set();
+    /** Monitor configuration */
+    let config = {
+        enabled: true,
+        maxLogs: 1000,
+        calculateCosts: true,
+        emitEvents: true,
+    };
+    /** Rolling window for RPM/TPM calculations (last 60 seconds) */
+    const rollingWindow = [];
+    // ============================================================================
+    // Helper Functions
+    // ============================================================================
+    /**
+     * Creates an empty stats object.
+     */
+    function createEmptyStats() {
+        return {
+            totalRequests: 0,
+            successCount: 0,
+            errorCount: 0,
+            rateLimitCount: 0,
+            totalInputTokens: 0,
+            totalOutputTokens: 0,
+            totalCacheReadTokens: 0,
+            totalCacheWriteTokens: 0,
+            avgLatencyMs: 0,
+            minLatencyMs: Infinity,
+            maxLatencyMs: 0,
+            p50LatencyMs: 0,
+            p95LatencyMs: 0,
+            p99LatencyMs: 0,
+            totalCostUSD: 0,
+            requestsPerMinute: 0,
+            tokensPerMinute: 0,
+        };
+    }
+    /**
+     * Generates a unique request ID.
+     */
+    function generateID() {
+        const timestamp = Date.now().toString(36);
+        const random = Math.random().toString(36).substring(2, 8);
+        return `req_${timestamp}_${random}`;
+    }
+    /**
+     * Updates statistics with a new request log.
+     */
+    function updateStats(stats, entry) {
+        stats.totalRequests++;
+        if (entry.status >= 200 && entry.status < 400) {
+            stats.successCount++;
+        }
+        else {
+            stats.errorCount++;
+        }
+        if (entry.status === 429) {
+            stats.rateLimitCount++;
+        }
+        stats.totalInputTokens += entry.inputTokens ?? 0;
+        stats.totalOutputTokens += entry.outputTokens ?? 0;
+        stats.totalCacheReadTokens += entry.cacheReadTokens ?? 0;
+        stats.totalCacheWriteTokens += entry.cacheWriteTokens ?? 0;
+        stats.totalCostUSD += entry.costUSD ?? 0;
+        // Update latency stats
+        stats.minLatencyMs = Math.min(stats.minLatencyMs, entry.latencyMs);
+        stats.maxLatencyMs = Math.max(stats.maxLatencyMs, entry.latencyMs);
+        // Rolling average for avgLatencyMs
+        stats.avgLatencyMs =
+            (stats.avgLatencyMs * (stats.totalRequests - 1) + entry.latencyMs) / stats.totalRequests;
+        // Update first/last timestamps
+        if (!stats.firstRequestAt) {
+            stats.firstRequestAt = entry.timestamp;
+        }
+        stats.lastRequestAt = entry.timestamp;
+    }
+    /**
+     * Calculates percentile latencies from the log buffer.
+     */
+    function calculatePercentiles(stats) {
+        if (logs.length === 0)
+            return;
+        const latencies = logs.map((l) => l.latencyMs).sort((a, b) => a - b);
+        const len = latencies.length;
+        stats.p50LatencyMs = latencies[Math.floor(len * 0.5)] ?? 0;
+        stats.p95LatencyMs = latencies[Math.floor(len * 0.95)] ?? 0;
+        stats.p99LatencyMs = latencies[Math.floor(len * 0.99)] ?? 0;
+    }
+    /**
+     * Updates rolling window metrics (RPM, TPM).
+     */
+    function updateRollingMetrics() {
+        const now = Date.now();
+        const oneMinuteAgo = now - 60_000;
+        // Remove old entries
+        while (rollingWindow.length > 0 && rollingWindow[0].timestamp < oneMinuteAgo) {
+            rollingWindow.shift();
+        }
+        // Calculate RPM and TPM
+        globalStats.requestsPerMinute = rollingWindow.length;
+        globalStats.tokensPerMinute = rollingWindow.reduce((sum, entry) => sum + entry.tokens, 0);
+        // Update per-provider stats
+        for (const [providerID, stats] of providerStats.entries()) {
+            const providerLogs = logs.filter((l) => l.providerID === providerID && l.timestamp >= oneMinuteAgo);
+            stats.requestsPerMinute = providerLogs.length;
+            stats.tokensPerMinute = providerLogs.reduce((sum, l) => sum + (l.inputTokens ?? 0) + (l.outputTokens ?? 0), 0);
+        }
+    }
+    // ============================================================================
+    // Public API
+    // ============================================================================
+    /**
+     * Configures the request monitor.
+     *
+     * @param newConfig - Partial configuration to merge
+     *
+     * @example
+     * ```typescript
+     * RequestMonitor.configure({
+     *   maxLogs: 500,
+     *   calculateCosts: false
+     * })
+     * ```
+     */
+    function configure(newConfig) {
+        config = { ...config, ...newConfig };
+        log.info("configured", { ...config });
+        // Trim logs if max reduced
+        while (logs.length > config.maxLogs) {
+            logs.shift();
+        }
+    }
+    RequestMonitor.configure = configure;
+    /**
+     * Gets the current configuration.
+     */
+    function getConfig() {
+        return { ...config };
+    }
+    RequestMonitor.getConfig = getConfig;
+    /**
+     * Logs a new API request.
+     *
+     * @param entry - Partial request log entry (id and timestamp auto-generated if missing)
+     * @returns The complete log entry
+     *
+     * @example
+     * ```typescript
+     * const entry = RequestMonitor.logRequest({
+     *   providerID: "anthropic",
+     *   modelID: "claude-sonnet-4-20250514",
+     *   method: "chat",
+     *   status: 200,
+     *   latencyMs: 1234,
+     *   inputTokens: 500,
+     *   outputTokens: 200,
+     *   streaming: true
+     * })
+     * ```
+     */
+    function logRequest(entry) {
+        if (!config.enabled) {
+            return {
+                ...entry,
+                id: entry.id ?? generateID(),
+                timestamp: entry.timestamp ?? Date.now(),
+            };
+        }
+        const requestLog = {
+            ...entry,
+            id: entry.id ?? generateID(),
+            timestamp: entry.timestamp ?? Date.now(),
+        };
+        // Add to ring buffer (remove oldest if at capacity)
+        if (logs.length >= config.maxLogs) {
+            logs.shift();
+        }
+        logs.push(requestLog);
+        // Update stats
+        updateStats(globalStats, requestLog);
+        if (!providerStats.has(requestLog.providerID)) {
+            providerStats.set(requestLog.providerID, createEmptyStats());
+        }
+        updateStats(providerStats.get(requestLog.providerID), requestLog);
+        // Update rolling window
+        const totalTokens = (requestLog.inputTokens ?? 0) + (requestLog.outputTokens ?? 0);
+        rollingWindow.push({ timestamp: requestLog.timestamp, tokens: totalTokens });
+        updateRollingMetrics();
+        // Emit event
+        if (config.emitEvents) {
+            const event = { type: "request", log: requestLog };
+            for (const listener of listeners) {
+                try {
+                    listener(event);
+                }
+                catch (e) {
+                    log.error("event-listener-error", { error: String(e) });
+                }
+            }
+        }
+        log.debug("logged", {
+            id: requestLog.id,
+            provider: requestLog.providerID,
+            model: requestLog.modelID,
+            status: requestLog.status,
+            latency: requestLog.latencyMs,
+        });
+        return requestLog;
+    }
+    RequestMonitor.logRequest = logRequest;
+    /**
+     * Gets recent request logs.
+     *
+     * @param options - Filter options
+     * @returns Array of request logs (newest first)
+     *
+     * @example
+     * ```typescript
+     * // Get last 10 logs
+     * const recent = RequestMonitor.getRecentLogs({ limit: 10 })
+     *
+     * // Get logs for a specific provider
+     * const anthropicLogs = RequestMonitor.getRecentLogs({
+     *   providerID: "anthropic",
+     *   limit: 50
+     * })
+     * ```
+     */
+    function getRecentLogs(options = {}) {
+        let result = [...logs];
+        // Apply filters
+        if (options.providerID) {
+            result = result.filter((l) => l.providerID === options.providerID);
+        }
+        if (options.modelID) {
+            result = result.filter((l) => l.modelID === options.modelID);
+        }
+        if (options.sessionID) {
+            result = result.filter((l) => l.sessionID === options.sessionID);
+        }
+        if (options.minStatus !== undefined) {
+            result = result.filter((l) => l.status >= options.minStatus);
+        }
+        if (options.maxStatus !== undefined) {
+            result = result.filter((l) => l.status <= options.maxStatus);
+        }
+        if (options.since !== undefined) {
+            result = result.filter((l) => l.timestamp >= options.since);
+        }
+        if (options.until !== undefined) {
+            result = result.filter((l) => l.timestamp <= options.until);
+        }
+        // Sort newest first and apply limit
+        result.reverse();
+        if (options.limit) {
+            result = result.slice(0, options.limit);
+        }
+        return result;
+    }
+    RequestMonitor.getRecentLogs = getRecentLogs;
+    /**
+     * Gets a specific request log by ID.
+     *
+     * @param id - Request ID
+     * @returns The log entry or undefined if not found
+     */
+    function getLog(id) {
+        return logs.find((l) => l.id === id);
+    }
+    RequestMonitor.getLog = getLog;
+    /**
+     * Gets statistics for a provider or overall.
+     *
+     * @param providerID - Optional provider ID (undefined for global stats)
+     * @returns Statistics object
+     *
+     * @example
+     * ```typescript
+     * // Get global stats
+     * const global = RequestMonitor.getStats()
+     *
+     * // Get provider-specific stats
+     * const anthropic = RequestMonitor.getStats("anthropic")
+     * ```
+     */
+    function getStats(providerID) {
+        // Calculate percentiles on demand
+        calculatePercentiles(globalStats);
+        for (const stats of providerStats.values()) {
+            calculatePercentiles(stats);
+        }
+        updateRollingMetrics();
+        if (providerID) {
+            return providerStats.get(providerID) ?? createEmptyStats();
+        }
+        return { ...globalStats };
+    }
+    RequestMonitor.getStats = getStats;
+    /**
+     * Gets statistics for all providers.
+     *
+     * @returns Map of provider ID to statistics
+     */
+    function getAllStats() {
+        updateRollingMetrics();
+        calculatePercentiles(globalStats);
+        const result = {};
+        for (const [providerID, stats] of providerStats.entries()) {
+            calculatePercentiles(stats);
+            result[providerID] = { ...stats };
+        }
+        return result;
+    }
+    RequestMonitor.getAllStats = getAllStats;
+    /**
+     * Gets a summary of all monitoring data.
+     *
+     * @returns Summary object suitable for API responses
+     */
+    function getSummary() {
+        return {
+            enabled: config.enabled,
+            logCount: logs.length,
+            global: getStats(),
+            providers: getAllStats(),
+            recentErrors: getRecentLogs({ minStatus: 400, limit: 10 }),
+        };
+    }
+    RequestMonitor.getSummary = getSummary;
+    /**
+     * Adds an event listener.
+     *
+     * @param listener - Callback function
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = RequestMonitor.addListener((event) => {
+     *   console.log("Request:", event.log.id)
+     * })
+     *
+     * // Later...
+     * unsubscribe()
+     * ```
+     */
+    function addListener(listener) {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+    }
+    RequestMonitor.addListener = addListener;
+    /**
+     * Exports logs to JSON format.
+     *
+     * @param options - Export options
+     * @returns JSON string
+     */
+    function exportJSON(options = {}) {
+        const data = {
+            exportedAt: new Date().toISOString(),
+            global: getStats(),
+            providers: getAllStats(),
+            logs: getRecentLogs({
+                providerID: options.providerID,
+                since: options.since,
+                until: options.until,
+            }),
+        };
+        return JSON.stringify(data, null, options.pretty ? 2 : 0);
+    }
+    RequestMonitor.exportJSON = exportJSON;
+    /**
+     * Clears all logs and resets statistics.
+     */
+    function clear() {
+        logs.length = 0;
+        providerStats.clear();
+        globalStats = createEmptyStats();
+        rollingWindow.length = 0;
+        log.info("cleared");
+    }
+    RequestMonitor.clear = clear;
+    /**
+     * Clears logs and stats for a specific provider.
+     *
+     * @param providerID - Provider ID to clear
+     */
+    function clearProvider(providerID) {
+        // Remove logs for this provider
+        for (let i = logs.length - 1; i >= 0; i--) {
+            if (logs[i].providerID === providerID) {
+                logs.splice(i, 1);
+            }
+        }
+        // Remove provider stats
+        providerStats.delete(providerID);
+        // Recalculate global stats
+        globalStats = createEmptyStats();
+        for (const l of logs) {
+            updateStats(globalStats, l);
+        }
+        log.info("cleared-provider", { providerID });
+    }
+    RequestMonitor.clearProvider = clearProvider;
+    /**
+     * Enables monitoring.
+     */
+    function enable() {
+        config.enabled = true;
+        log.info("enabled");
+    }
+    RequestMonitor.enable = enable;
+    /**
+     * Disables monitoring.
+     */
+    function disable() {
+        config.enabled = false;
+        log.info("disabled");
+    }
+    RequestMonitor.disable = disable;
+    /**
+     * Checks if monitoring is enabled.
+     */
+    function isEnabled() {
+        return config.enabled;
+    }
+    RequestMonitor.isEnabled = isEnabled;
+})(RequestMonitor || (RequestMonitor = {}));