agent-tank 0.9.0

package/src/pace-evaluator.js

@@ -0,0 +1,269 @@
+/**
+ * Pace Evaluator Module
+ *
+ * Calculates whether usage is out-pacing the time window.
+ * Warns users if they are burning through rate limits faster than time is elapsing.
+ * Provides extrapolation of ETA until 100% usage is reached.
+ */
+
+/**
+ * Calculate the pace of usage relative to time elapsed in a cycle.
+ *
+ * @param {Object} options - The pace calculation options
+ * @param {number} options.usagePercent - Current usage percentage (0-100)
+ * @param {number} options.resetsInSeconds - Seconds until the cycle resets
+ * @param {number} options.cycleDurationSeconds - Total duration of the cycle in seconds
+ * @param {number} [options.warningThreshold=1.2] - Pace ratio threshold to trigger warning (default: 20% faster than time)
+ * @returns {Object|null} Pace data or null if calculation not possible
+ *   - paceRatio: Usage rate vs time rate (>1 means out-pacing)
+ *   - elapsedPercent: Percentage of time elapsed in the cycle
+ *   - isWarning: Whether usage is significantly out-pacing time
+ *   - warningMessage: Human-readable warning message (if warning triggered)
+ */
+function calculatePace(options) {
+  const {
+    usagePercent,
+    resetsInSeconds,
+    cycleDurationSeconds,
+    warningThreshold = 1.2
+  } = options;
+
+  // Validate inputs
+  if (
+    typeof usagePercent !== 'number' ||
+    typeof resetsInSeconds !== 'number' ||
+    typeof cycleDurationSeconds !== 'number' ||
+    cycleDurationSeconds <= 0
+  ) {
+    return null;
+  }
+
+  // Calculate elapsed time in the cycle
+  const elapsedSeconds = cycleDurationSeconds - resetsInSeconds;
+
+  // Handle edge case: no time elapsed yet
+  if (elapsedSeconds <= 0) {
+    return {
+      paceRatio: usagePercent > 0 ? Infinity : 0,
+      elapsedPercent: 0,
+      isWarning: usagePercent > 0,
+      warningMessage: usagePercent > 0 ? 'Usage started before time window opened' : null
+    };
+  }
+
+  const elapsedPercent = (elapsedSeconds / cycleDurationSeconds) * 100;
+
+  // Handle edge case: no usage
+  if (usagePercent === 0) {
+    return {
+      paceRatio: 0,
+      elapsedPercent,
+      isWarning: false,
+      warningMessage: null
+    };
+  }
+
+  // Calculate pace ratio: usage rate vs time rate
+  // paceRatio > 1 means using faster than time is passing
+  // paceRatio = 2 means using at 2x the sustainable rate
+  const paceRatio = usagePercent / elapsedPercent;
+
+  // Determine if warning should be triggered
+  const isWarning = paceRatio >= warningThreshold;
+
+  // Generate warning message if applicable
+  let warningMessage = null;
+  if (isWarning) {
+    const paceMultiplier = paceRatio.toFixed(1);
+    warningMessage = `Using ${paceMultiplier}x faster than sustainable`;
+  }
+
+  return {
+    paceRatio: Math.round(paceRatio * 100) / 100, // Round to 2 decimal places
+    elapsedPercent: Math.round(elapsedPercent * 100) / 100,
+    isWarning,
+    warningMessage
+  };
+}
+
+/**
+ * Evaluate usage pace and extrapolate when user will hit 100%.
+ *
+ * This function calculates the expected linear usage based on elapsed time,
+ * determines if the user is burning faster than expected, and if so,
+ * extrapolates the ETA in seconds until they hit 100%.
+ *
+ * @param {Object} options - The evaluation options
+ * @param {number} options.usagePercent - Current usage percentage (0-100)
+ * @param {number} options.resetsInSeconds - Seconds until the cycle resets
+ * @param {number} options.cycleDurationSeconds - Total duration of the cycle in seconds
+ * @param {number} [options.warningThreshold=1.2] - Pace ratio threshold to trigger warning
+ * @returns {Object|null} Pace evaluation result or null if calculation not possible
+ *   - expectedPercent: Expected usage percentage based on linear pace
+ *   - isBurningFast: Whether actual usage exceeds expected usage
+ *   - etaSeconds: Seconds until 100% usage (only if isBurningFast is true, null otherwise)
+ *   - paceRatio: Usage rate vs time rate (>1 means out-pacing)
+ *   - elapsedPercent: Percentage of time elapsed in the cycle
+ *   - deltaPercent: Difference between actual and expected usage (positive = ahead)
+ */
+function evaluatePace(options) {
+  const {
+    usagePercent,
+    resetsInSeconds,
+    cycleDurationSeconds,
+    warningThreshold = 1.2
+  } = options;
+
+  // Validate inputs
+  if (
+    typeof usagePercent !== 'number' ||
+    typeof resetsInSeconds !== 'number' ||
+    typeof cycleDurationSeconds !== 'number' ||
+    cycleDurationSeconds <= 0
+  ) {
+    return null;
+  }
+
+  // Calculate elapsed time in the cycle
+  const elapsedSeconds = cycleDurationSeconds - resetsInSeconds;
+
+  // Handle edge case: no time elapsed yet
+  if (elapsedSeconds <= 0) {
+    return {
+      expectedPercent: 0,
+      isBurningFast: usagePercent > 0,
+      etaSeconds: usagePercent > 0 ? 0 : null, // Already burning if any usage at start
+      paceRatio: usagePercent > 0 ? Infinity : 0,
+      elapsedPercent: 0,
+      deltaPercent: usagePercent
+    };
+  }
+
+  // Calculate expected usage based on linear pace
+  // If 50% of time has elapsed, expected usage should be 50%
+  const elapsedPercent = (elapsedSeconds / cycleDurationSeconds) * 100;
+  const expectedPercent = elapsedPercent;
+
+  // Calculate delta (positive = ahead of pace, negative = behind)
+  const deltaPercent = usagePercent - expectedPercent;
+
+  // Determine if burning fast (usage exceeds expected by threshold)
+  // Using threshold ratio: if usage/expected >= threshold, burning fast
+  const paceRatio = usagePercent > 0 && elapsedPercent > 0
+    ? usagePercent / elapsedPercent
+    : (usagePercent > 0 ? Infinity : 0);
+
+  const isBurningFast = paceRatio >= warningThreshold;
+
+  // Calculate ETA to 100% if burning fast
+  let etaSeconds = null;
+  if (isBurningFast && usagePercent < 100 && usagePercent > 0) {
+    // Current burn rate: usagePercent per elapsedSeconds
+    const burnRatePerSecond = usagePercent / elapsedSeconds;
+
+    // Remaining usage to reach 100%
+    const remainingPercent = 100 - usagePercent;
+
+    // Time to reach 100% at current burn rate
+    etaSeconds = Math.round(remainingPercent / burnRatePerSecond);
+  } else if (usagePercent >= 100) {
+    etaSeconds = 0; // Already at or past 100%
+  }
+
+  return {
+    expectedPercent: Math.round(expectedPercent * 100) / 100,
+    isBurningFast,
+    etaSeconds,
+    paceRatio: paceRatio === Infinity ? Infinity : Math.round(paceRatio * 100) / 100,
+    elapsedPercent: Math.round(elapsedPercent * 100) / 100,
+    deltaPercent: Math.round(deltaPercent * 100) / 100
+  };
+}
+
+/**
+ * Format a pace warning as HTML for display in the UI.
+ * Includes ETA countdown when burning fast.
+ *
+ * @param {Object|null} paceData - Result from evaluatePace() or calculatePace()
+ * @returns {string} HTML string for the pace warning (empty string if no warning)
+ */
+function formatPaceWarning(paceData) {
+  if (!paceData) {
+    return '';
+  }
+
+  // Determine if we should show warning based on isWarning or isBurningFast
+  const shouldShowWarning = paceData.isWarning || paceData.isBurningFast;
+  if (!shouldShowWarning) {
+    return '';
+  }
+
+  const paceDisplay = paceData.paceRatio.toFixed(1);
+  // Add critical class for 2x or higher pace
+  const criticalClass = paceData.paceRatio >= 2 ? ' pace-critical' : '';
+
+  // Build tooltip message
+  let tooltip = paceData.warningMessage || `Using ${paceDisplay}x faster than sustainable`;
+
+  // Generate ETA section if available
+  let etaHtml = '';
+  if (paceData.etaSeconds != null && paceData.etaSeconds >= 0 && paceData.isBurningFast) {
+    const etaString = formatEtaString(paceData.etaSeconds);
+    if (etaString) {
+      etaHtml = `<span class="pace-eta">runs out in ${etaString}</span>`;
+      tooltip += ` • Runs out in ${etaString}`;
+    }
+  }
+
+  return `<div class="pace-warning${criticalClass}" title="${tooltip}">
+    <span class="pace-icon">&#9888;</span>
+    <span class="pace-text">${paceDisplay}x pace</span>${etaHtml}
+  </div>`;
+}
+
+/**
+ * Format ETA seconds into a human-readable string.
+ *
+ * @param {number|null} etaSeconds - Seconds until 100% usage
+ * @returns {string} Formatted ETA string (e.g., "2h 15m", "45m", "~30s")
+ */
+function formatEtaString(etaSeconds) {
+  if (etaSeconds == null || etaSeconds < 0) {
+    return '';
+  }
+
+  if (etaSeconds === 0) {
+    return 'now';
+  }
+
+  const days = Math.floor(etaSeconds / (24 * 60 * 60));
+  const hours = Math.floor((etaSeconds % (24 * 60 * 60)) / (60 * 60));
+  const minutes = Math.floor((etaSeconds % (60 * 60)) / 60);
+
+  const parts = [];
+
+  if (days > 0) {
+    parts.push(`${days}d`);
+  }
+  if (hours > 0) {
+    parts.push(`${hours}h`);
+  }
+  if (minutes > 0 && days === 0) {
+    // Only show minutes if no days (for readability)
+    parts.push(`${minutes}m`);
+  }
+
+  // If less than a minute, show "< 1m"
+  if (parts.length === 0) {
+    return '< 1m';
+  }
+
+  return parts.join(' ');
+}
+
+module.exports = {
+  calculatePace,
+  formatPaceWarning,
+  evaluatePace,
+  formatEtaString
+};

package/src/public-status.js

@@ -0,0 +1,276 @@
+/**
+ * Public Status API Polling Module
+ *
+ * Fetches status information from public API status pages for Anthropic, OpenAI,
+ * and Google Cloud. Uses Statuspage.io JSON API for Anthropic and OpenAI, and
+ * Google Cloud's incidents JSON for Google/Gemini.
+ */
+
+const https = require('node:https');
+
+// Status page configurations
+const STATUS_PAGES = {
+  claude: {
+    url: 'https://anthropic.statuspage.io/api/v2/status.json',
+    type: 'statuspage',
+    name: 'Anthropic',
+  },
+  codex: {
+    url: 'https://status.openai.com/api/v2/status.json',
+    type: 'statuspage',
+    name: 'OpenAI',
+  },
+  gemini: {
+    url: 'https://status.cloud.google.com/incidents.json',
+    type: 'google-cloud',
+    name: 'Google Cloud',
+    // Vertex AI Gemini product ID for filtering incidents
+    productId: 'Z0FZJAMvEB4j3NbCJs6B',
+  },
+};
+
+// Status indicator mapping (statuspage.io format)
+// Possible values: none, minor, major, critical
+const STATUS_INDICATOR_MAP = {
+  none: 'operational',
+  minor: 'degraded',
+  major: 'outage',
+  critical: 'outage',
+};
+
+// Request timeout in milliseconds
+const FETCH_TIMEOUT = 10000;
+
+/**
+ * Makes an HTTPS GET request and returns the response body as a string
+ * @param {string} url - The URL to fetch
+ * @returns {Promise<string>} - The response body
+ */
+function httpsGet(url) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, { timeout: FETCH_TIMEOUT }, (res) => {
+      if (res.statusCode !== 200) {
+        reject(new Error(`HTTP ${res.statusCode}`));
+        return;
+      }
+
+      let data = '';
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      res.on('end', () => {
+        resolve(data);
+      });
+    });
+
+    request.on('error', reject);
+    request.on('timeout', () => {
+      request.destroy();
+      reject(new Error('Request timeout'));
+    });
+  });
+}
+
+/**
+ * Parse Statuspage.io JSON response
+ * @param {string} json - Raw JSON response
+ * @returns {object} - Parsed status object
+ */
+function parseStatuspageResponse(json) {
+  const data = JSON.parse(json);
+  const indicator = data.status?.indicator || 'none';
+  const description = data.status?.description || 'Unknown';
+
+  return {
+    status: STATUS_INDICATOR_MAP[indicator] || 'unknown',
+    indicator,
+    description,
+    updatedAt: data.page?.updated_at || null,
+  };
+}
+
+/**
+ * Parse Google Cloud incidents JSON response
+ * Determines status based on recent active incidents affecting the specified product
+ * @param {string} json - Raw JSON response
+ * @param {string} productId - Product ID to filter incidents
+ * @returns {object} - Parsed status object
+ */
+function parseGoogleCloudResponse(json, productId) {
+  const incidents = JSON.parse(json);
+
+  // Find active incidents affecting the specified product (e.g., Vertex AI Gemini)
+  const now = new Date();
+  const activeIncidents = incidents.filter((incident) => {
+    // Check if incident is ongoing (no end date or recent)
+    if (incident.end) {
+      const endDate = new Date(incident.end);
+      // Consider incidents that ended less than 1 hour ago as potentially still affecting
+      if (now - endDate > 60 * 60 * 1000) {
+        return false;
+      }
+    }
+
+    // Check if incident affects the target product
+    if (productId && incident.affected_products) {
+      const affectsProduct = incident.affected_products.some(
+        (p) => p.id === productId || p.title?.toLowerCase().includes('gemini') ||
+               p.title?.toLowerCase().includes('vertex')
+      );
+      if (!affectsProduct) {
+        return false;
+      }
+    }
+
+    // Check status - include ongoing or recent disruptions
+    return incident.status === 'SERVICE_DISRUPTION' ||
+           incident.status === 'SERVICE_OUTAGE' ||
+           !incident.end;
+  });
+
+  // Determine overall status based on active incidents
+  if (activeIncidents.length === 0) {
+    return {
+      status: 'operational',
+      indicator: 'none',
+      description: 'All Systems Operational',
+      updatedAt: null,
+    };
+  }
+
+  // Find the most severe active incident
+  const hasOutage = activeIncidents.some((i) => i.status === 'SERVICE_OUTAGE');
+  const hasDisruption = activeIncidents.some((i) => i.status === 'SERVICE_DISRUPTION');
+
+  if (hasOutage) {
+    return {
+      status: 'outage',
+      indicator: 'major',
+      description: activeIncidents[0].external_desc || 'Service Outage',
+      updatedAt: activeIncidents[0].modified || null,
+    };
+  }
+
+  if (hasDisruption) {
+    return {
+      status: 'degraded',
+      indicator: 'minor',
+      description: activeIncidents[0].external_desc || 'Service Disruption',
+      updatedAt: activeIncidents[0].modified || null,
+    };
+  }
+
+  // Default to operational if incidents are resolved
+  return {
+    status: 'operational',
+    indicator: 'none',
+    description: 'All Systems Operational',
+    updatedAt: null,
+  };
+}
+
+/**
+ * Fetch public status for a single agent
+ * @param {string} agentName - Name of the agent (claude, gemini, codex)
+ * @returns {Promise<object>} - Status object with status, indicator, description
+ */
+async function fetchAgentPublicStatus(agentName) {
+  const config = STATUS_PAGES[agentName];
+
+  if (!config) {
+    return {
+      status: 'unknown',
+      indicator: 'unknown',
+      description: 'No status page configured',
+      error: null,
+    };
+  }
+
+  try {
+    const response = await httpsGet(config.url);
+
+    if (config.type === 'statuspage') {
+      return parseStatuspageResponse(response);
+    } else if (config.type === 'google-cloud') {
+      return parseGoogleCloudResponse(response, config.productId);
+    }
+
+    return {
+      status: 'unknown',
+      indicator: 'unknown',
+      description: 'Unknown status page type',
+      error: null,
+    };
+  } catch (err) {
+    console.error(`[PublicStatus] Error fetching ${agentName} status:`, err.message);
+    return {
+      status: 'unknown',
+      indicator: 'unknown',
+      description: 'Unable to fetch status',
+      error: err.message,
+    };
+  }
+}
+
+/**
+ * Fetch public status for all configured agents
+ * @param {string[]} agentNames - Array of agent names to fetch status for
+ * @returns {Promise<object>} - Object mapping agent names to their public status
+ */
+async function fetchPublicStatus(agentNames = Object.keys(STATUS_PAGES)) {
+  const results = {};
+
+  const promises = agentNames.map(async (name) => {
+    results[name] = await fetchAgentPublicStatus(name);
+  });
+
+  await Promise.all(promises);
+
+  return results;
+}
+
+/**
+ * Get the badge color class for a status
+ * @param {string} status - Status string (operational, degraded, outage, unknown)
+ * @returns {string} - CSS class name for the badge
+ */
+function getStatusBadgeClass(status) {
+  switch (status) {
+    case 'operational':
+      return 'status-badge-green';
+    case 'degraded':
+      return 'status-badge-yellow';
+    case 'outage':
+      return 'status-badge-red';
+    default:
+      return 'status-badge-grey';
+  }
+}
+
+/**
+ * Get the human-readable status text
+ * @param {string} status - Status string
+ * @returns {string} - Human-readable status
+ */
+function getStatusText(status) {
+  switch (status) {
+    case 'operational':
+      return 'Operational';
+    case 'degraded':
+      return 'Degraded';
+    case 'outage':
+      return 'Outage';
+    default:
+      return 'Unknown';
+  }
+}
+
+module.exports = {
+  fetchPublicStatus,
+  fetchAgentPublicStatus,
+  getStatusBadgeClass,
+  getStatusText,
+  parseStatuspageResponse,
+  parseGoogleCloudResponse,
+  STATUS_PAGES,
+};

package/src/server.js

@@ -0,0 +1,144 @@
+/**
+ * HTTP Server module for Agent Tank
+ * Handles routing and request processing
+ */
+
+const http = require('node:http');
+const logger = require('./logger.js');
+const { statusPage } = require('./status-page.js');
+
+function createRequestHandler(tank) {
+  return async (req, res) => {
+    const url = new URL(req.url, `http://localhost:${tank.port}`);
+    const path = url.pathname;
+
+    // CORS headers
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    if (!tank.authenticate(req, url)) {
+      res.setHeader('WWW-Authenticate', 'Basic realm="LLM Limit Watcher"');
+      res.writeHead(401);
+      res.end(JSON.stringify({ error: 'Unauthorized' }));
+      return;
+    }
+
+    try {
+      // Routes
+      if (req.method === 'GET' && path === '/') {
+        res.setHeader('Content-Type', 'text/html');
+        res.writeHead(200);
+        res.end(statusPage(tank.getStatus()));
+        return;
+      }
+
+      if (req.method === 'GET' && path === '/status') {
+        const status = tank.getStatus();
+        logger.server(`GET /status - returning status for ${Object.keys(status).length} agents`);
+        res.setHeader('Content-Type', 'application/json');
+        res.writeHead(200);
+        res.end(JSON.stringify(status, null, 2));
+        return;
+      }
+
+      if (req.method === 'GET' && path === '/config') {
+        const config = {
+          autoRefresh: {
+            enabled: tank.autoRefresh.enabled && tank.autoRefresh.interval > 0,
+            interval: tank.autoRefresh.interval, // in seconds
+          },
+          lastRefreshedAt: tank.lastRefreshedAt,
+        };
+        res.setHeader('Content-Type', 'application/json');
+        res.writeHead(200);
+        res.end(JSON.stringify(config, null, 2));
+        return;
+      }
+
+      if (req.method === 'GET' && path.startsWith('/status/')) {
+        const agentName = path.slice(8);
+        const status = tank.getAgentStatus(agentName);
+        if (!status) {
+          res.writeHead(404);
+          res.end(JSON.stringify({ error: 'Agent not found' }));
+          return;
+        }
+        res.setHeader('Content-Type', 'application/json');
+        res.writeHead(200);
+        res.end(JSON.stringify(status, null, 2));
+        return;
+      }
+
+      if (req.method === 'POST' && path === '/refresh') {
+        await tank.refreshAll();
+        res.setHeader('Content-Type', 'application/json');
+        res.writeHead(200);
+        res.end(JSON.stringify({ success: true, status: tank.getStatus() }));
+        return;
+      }
+
+      if (req.method === 'POST' && path.startsWith('/refresh/')) {
+        const agentName = path.slice(9);
+        try {
+          await tank.refreshAgent(agentName);
+          res.setHeader('Content-Type', 'application/json');
+          res.writeHead(200);
+          res.end(JSON.stringify({ success: true, status: tank.getAgentStatus(agentName) }));
+        } catch (err) {
+          res.writeHead(404);
+          res.end(JSON.stringify({ error: err.message }));
+        }
+        return;
+      }
+
+      // 404
+      res.writeHead(404);
+      res.end(JSON.stringify({ error: 'Not found' }));
+
+    } catch (err) {
+      logger.error('Server error:', err);
+      res.writeHead(500);
+      res.end(JSON.stringify({ error: 'Internal server error' }));
+    }
+  };
+}
+
+/**
+ * Create and configure the HTTP server
+ * @param {Object} tank - AgentTank instance
+ * @returns {http.Server}
+ */
+function createServer(tank) {
+  return http.createServer(createRequestHandler(tank));
+}
+
+/**
+ * Display server startup banner
+ * @param {Object} tank - AgentTank instance
+ */
+function displayServerBanner(tank) {
+  const ANSI = logger.ANSI;
+  console.log('');
+  console.log(`${ANSI.cyan}${ANSI.bold}╔════════════════════════════════════════════╗${ANSI.reset}`);
+  console.log(`${ANSI.cyan}${ANSI.bold}║${ANSI.reset}  ${ANSI.brightCyan}🚀 Agent Tank Server${ANSI.reset}                      ${ANSI.cyan}${ANSI.bold}║${ANSI.reset}`);
+  console.log(`${ANSI.cyan}${ANSI.bold}╚════════════════════════════════════════════╝${ANSI.reset}`);
+  console.log('');
+  if (tank.auth.user && tank.auth.pass) {
+    logger.info(`🔐 Authentication: basic auth (user: ${tank.auth.user})`);
+  }
+  if (tank.auth.token) {
+    logger.info('🔑 Authentication: API key');
+  }
+  logger.server(`Listening on: ${tank.host}:${tank.port}`);
+  logger.server(`📄 Status page: http://${tank.host}:${tank.port}/`);
+  logger.server(`📡 JSON API:    http://${tank.host}:${tank.port}/status`);
+  console.log('');
+}
+
+module.exports = { createRequestHandler, createServer, displayServerBanner };