agent-tank 0.9.0

package/src/keepalive-manager.js

@@ -0,0 +1,163 @@
+/**
+ * KeepaliveManager - Manages periodic session keepalive for registered agents
+ *
+ * Prevents session expiration by scheduling lightweight ping/keepalive operations
+ * on registered agents at a configurable interval.
+ */
+
+class KeepaliveManager {
+  /**
+   * Create a KeepaliveManager instance.
+   *
+   * @param {Object} options - Configuration options
+   * @param {number} [options.interval=300] - Keepalive interval in seconds (default: 5 minutes)
+   * @param {boolean} [options.enabled=true] - Whether keepalive is enabled
+   */
+  constructor(options = {}) {
+    this.interval = options.interval ?? 300; // Default: 5 minutes
+    this.enabled = options.enabled !== false; // Default: true
+    this.agents = new Map();
+    this.timer = null;
+    this.lastKeepaliveAt = null;
+    this.isRunning = false;
+  }
+
+  /**
+   * Register an agent with the keepalive manager.
+   *
+   * @param {string} name - Agent name
+   * @param {Object} agent - Agent instance (must have a keepalive() method)
+   */
+  register(name, agent) {
+    if (!agent) {
+      console.warn(`[KeepaliveManager] Cannot register null agent: ${name}`);
+      return;
+    }
+
+    if (typeof agent.keepalive !== 'function') {
+      console.warn(`[KeepaliveManager] Agent ${name} does not implement keepalive() method`);
+      return;
+    }
+
+    this.agents.set(name, agent);
+    console.log(`[KeepaliveManager] Registered agent: ${name}`);
+  }
+
+  /**
+   * Unregister an agent from the keepalive manager.
+   *
+   * @param {string} name - Agent name to unregister
+   */
+  unregister(name) {
+    if (this.agents.has(name)) {
+      this.agents.delete(name);
+      console.log(`[KeepaliveManager] Unregistered agent: ${name}`);
+    }
+  }
+
+  /**
+   * Start the keepalive scheduler.
+   * Runs keepalive immediately on start, then at the configured interval.
+   */
+  start() {
+    if (this.isRunning) {
+      console.log('[KeepaliveManager] Already running');
+      return;
+    }
+
+    if (!this.enabled) {
+      console.log('[KeepaliveManager] Keepalive disabled');
+      return;
+    }
+
+    if (this.interval <= 0) {
+      console.log('[KeepaliveManager] Keepalive interval is 0, disabled');
+      return;
+    }
+
+    if (this.agents.size === 0) {
+      console.log('[KeepaliveManager] No agents registered, not starting');
+      return;
+    }
+
+    this.isRunning = true;
+    const intervalMs = this.interval * 1000;
+
+    console.log(`[KeepaliveManager] Starting with ${this.interval}s interval for ${this.agents.size} agent(s)`);
+
+    // Start the periodic timer
+    this.timer = setInterval(() => {
+      this._runKeepalive();
+    }, intervalMs);
+  }
+
+  /**
+   * Stop the keepalive scheduler.
+   */
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.isRunning = false;
+    console.log('[KeepaliveManager] Stopped');
+  }
+
+  /**
+   * Run keepalive on all registered agents.
+   * Errors in individual agents do not affect others.
+   *
+   * @returns {Promise<Object>} Results keyed by agent name
+   */
+  async _runKeepalive() {
+    if (this.agents.size === 0) {
+      return {};
+    }
+
+    console.log(`[KeepaliveManager] Running keepalive for ${this.agents.size} agent(s)...`);
+    const results = {};
+
+    const promises = Array.from(this.agents.entries()).map(async ([name, agent]) => {
+      try {
+        await agent.keepalive();
+        results[name] = { success: true };
+        console.log(`[KeepaliveManager] Keepalive successful: ${name}`);
+      } catch (err) {
+        // Log error but don't crash - keepalive errors should not affect the server
+        results[name] = { success: false, error: err.message };
+        console.error(`[KeepaliveManager] Keepalive failed for ${name}: ${err.message}`);
+      }
+    });
+
+    await Promise.all(promises);
+    this.lastKeepaliveAt = new Date().toISOString();
+
+    return results;
+  }
+
+  /**
+   * Manually trigger a keepalive run.
+   *
+   * @returns {Promise<Object>} Results keyed by agent name
+   */
+  async runNow() {
+    return this._runKeepalive();
+  }
+
+  /**
+   * Get the current status of the keepalive manager.
+   *
+   * @returns {Object} Status information
+   */
+  getStatus() {
+    return {
+      enabled: this.enabled,
+      interval: this.interval,
+      isRunning: this.isRunning,
+      registeredAgents: Array.from(this.agents.keys()),
+      lastKeepaliveAt: this.lastKeepaliveAt,
+    };
+  }
+}
+
+module.exports = { KeepaliveManager };

package/src/logger.js

@@ -0,0 +1,213 @@
+/**
+ * Custom ANSI Logger Utility
+ *
+ * A lightweight, dependency-free ANSI logger providing color-coded output,
+ * agent-specific styles, and highlighted URLs.
+ */
+
+// ANSI escape codes for styling
+const ANSI = {
+  // Reset
+  reset: '\x1b[0m',
+
+  // Text styles
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  underline: '\x1b[4m',
+
+  // Foreground colors
+  black: '\x1b[30m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+
+  // Bright foreground colors
+  brightBlack: '\x1b[90m',
+  brightRed: '\x1b[91m',
+  brightGreen: '\x1b[92m',
+  brightYellow: '\x1b[93m',
+  brightBlue: '\x1b[94m',
+  brightMagenta: '\x1b[95m',
+  brightCyan: '\x1b[96m',
+  brightWhite: '\x1b[97m',
+};
+
+// Agent color mapping
+const AGENT_COLORS = {
+  claude: ANSI.magenta,
+  gemini: ANSI.cyan,
+  codex: ANSI.green,
+};
+
+// URL regex pattern for highlighting
+const URL_PATTERN = /https?:\/\/[^\s<>"{}|\\^`[\]]+/g;
+
+/**
+ * Highlights URLs in a string with underline and bright white color
+ * (bright white provides better readability on dark terminal backgrounds)
+ * @param {string} text - The text to process
+ * @returns {string} - Text with highlighted URLs
+ */
+function highlightUrls(text) {
+  if (typeof text !== 'string') {
+    return text;
+  }
+  return text.replace(URL_PATTERN, (url) => {
+    return `${ANSI.brightWhite}${ANSI.underline}${url}${ANSI.reset}`;
+  });
+}
+
+/**
+ * Formats arguments into a single string, handling objects and arrays
+ * @param {...any} args - Arguments to format
+ * @returns {string} - Formatted string
+ */
+function formatArgs(...args) {
+  return args.map(arg => {
+    if (typeof arg === 'object' && arg !== null) {
+      try {
+        return JSON.stringify(arg);
+      } catch {
+        return String(arg);
+      }
+    }
+    return String(arg);
+  }).join(' ');
+}
+
+/**
+ * Colorizes text with the specified ANSI color
+ * @param {string} color - ANSI color code
+ * @param {string} text - Text to colorize
+ * @returns {string} - Colorized text
+ */
+function colorize(color, text) {
+  return `${color}${text}${ANSI.reset}`;
+}
+
+/**
+ * Creates a prefixed log message
+ * @param {string} prefix - The prefix (e.g., "INFO", "ERROR")
+ * @param {string} color - ANSI color for the prefix
+ * @param {...any} args - Message arguments
+ * @returns {string} - Formatted message
+ */
+function createPrefixedMessage(prefix, color, ...args) {
+  const formattedMessage = highlightUrls(formatArgs(...args));
+  return `${colorize(color, `[${prefix}]`)} ${formattedMessage}`;
+}
+
+/**
+ * Logger object with formatting methods
+ */
+const logger = {
+  /**
+   * Log an informational message (blue prefix)
+   * @param {...any} args - Message arguments
+   */
+  info(...args) {
+    console.log(createPrefixedMessage('INFO', ANSI.blue, ...args));
+  },
+
+  /**
+   * Log a success message (green prefix)
+   * @param {...any} args - Message arguments
+   */
+  success(...args) {
+    console.log(createPrefixedMessage('SUCCESS', ANSI.green, ...args));
+  },
+
+  /**
+   * Log a warning message (yellow prefix)
+   * @param {...any} args - Message arguments
+   */
+  warn(...args) {
+    console.warn(createPrefixedMessage('WARN', ANSI.yellow, ...args));
+  },
+
+  /**
+   * Log an error message (red prefix)
+   * @param {...any} args - Message arguments
+   */
+  error(...args) {
+    console.error(createPrefixedMessage('ERROR', ANSI.red, ...args));
+  },
+
+  /**
+   * Log an agent-specific message with mapped color
+   * @param {string} agentName - Name of the agent (claude, gemini, codex)
+   * @param {...any} args - Message arguments
+   */
+  agent(agentName, ...args) {
+    const normalizedName = agentName.toLowerCase();
+    const color = AGENT_COLORS[normalizedName] || ANSI.white;
+    const formattedMessage = highlightUrls(formatArgs(...args));
+    console.log(`${colorize(color, `[${agentName}]`)} ${formattedMessage}`);
+  },
+
+  /**
+   * Log a server-related message (cyan prefix with "SERVER" label)
+   * @param {...any} args - Message arguments
+   */
+  server(...args) {
+    console.log(createPrefixedMessage('SERVER', ANSI.cyan, ...args));
+  },
+
+  /**
+   * Format text with dim styling (for verbose/secondary output)
+   * @param {string} text - Text to dim
+   * @returns {string} - Dimmed text
+   */
+  dim(text) {
+    return `${ANSI.dim}${text}${ANSI.reset}`;
+  },
+
+  /**
+   * Format and dim JSON data (for large data payloads)
+   * @param {any} data - Data to format as JSON
+   * @param {boolean} [pretty=false] - Whether to pretty-print the JSON
+   * @returns {string} - Dimmed JSON string
+   */
+  json(data, pretty = false) {
+    let jsonStr;
+    try {
+      jsonStr = pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+    } catch {
+      jsonStr = String(data);
+    }
+    return `${ANSI.dim}${jsonStr}${ANSI.reset}`;
+  },
+
+  /**
+   * Get the color code for a specific agent
+   * @param {string} agentName - Name of the agent
+   * @returns {string} - ANSI color code
+   */
+  getAgentColor(agentName) {
+    const normalizedName = agentName.toLowerCase();
+    return AGENT_COLORS[normalizedName] || ANSI.white;
+  },
+
+  /**
+   * Highlight URLs in text (exposed for external use)
+   * @param {string} text - Text to process
+   * @returns {string} - Text with highlighted URLs
+   */
+  highlightUrls,
+
+  /**
+   * Raw ANSI codes for custom formatting
+   */
+  ANSI,
+
+  /**
+   * Agent color mapping for custom formatting
+   */
+  AGENT_COLORS,
+};
+
+module.exports = logger;

package/src/pace-attachment.js

@@ -0,0 +1,104 @@
+/**
+ * Pace evaluation attachment utilities.
+ *
+ * Attaches pace evaluation data to agent usage metrics.
+ */
+
+const { evaluatePace } = require('./pace-evaluator.js');
+const { CYCLE_DURATIONS } = require('./usage-formatters.js');
+
+/**
+ * Attach pace evaluation to a usage data object if it has required fields.
+ * @param {Object} data - Usage data object with percentUsed and resetsInSeconds
+ * @param {string} percentField - Field name for percent value
+ * @param {string} cycle - Cycle type for duration lookup
+ */
+function attachPaceToData(data, percentField, cycle) {
+  if (!data) return;
+  const percent = data[percentField];
+  if (typeof percent !== 'number' || typeof data.resetsInSeconds !== 'number') return;
+
+  const paceEval = evaluatePace({
+    usagePercent: percent,
+    resetsInSeconds: data.resetsInSeconds,
+    cycleDurationSeconds: CYCLE_DURATIONS[cycle]
+  });
+  if (paceEval) {
+    data.paceEval = paceEval;
+  }
+}
+
+/**
+ * Attach pace evaluation to Claude usage metrics.
+ * @param {Object} usage - Claude usage data
+ */
+function attachClaudePace(usage) {
+  const sections = [
+    { data: usage.session, cycle: 'session' },
+    { data: usage.weeklyAll, cycle: 'weekly' },
+    { data: usage.weeklySonnet, cycle: 'weekly' },
+    { data: usage.weekly, cycle: 'weekly' },
+    { data: usage.extraUsage, cycle: 'weekly' }
+  ];
+
+  for (const { data, cycle } of sections) {
+    attachPaceToData(data, 'percent', cycle);
+  }
+}
+
+/**
+ * Attach pace evaluation to Gemini usage metrics.
+ * @param {Object} usage - Gemini usage data
+ */
+function attachGeminiPace(usage) {
+  if (!usage.models || !Array.isArray(usage.models)) return;
+
+  for (const model of usage.models) {
+    attachPaceToData(model, 'percentUsed', 'sessionGemini');
+  }
+}
+
+/**
+ * Attach pace evaluation to Codex usage metrics.
+ * @param {Object} usage - Codex usage data
+ */
+function attachCodexPace(usage) {
+  // Main limits
+  attachPaceToData(usage.fiveHour, 'percentUsed', 'fiveHour');
+  attachPaceToData(usage.weekly, 'percentUsed', 'weekly');
+
+  // Per-model limits
+  if (usage.modelLimits && Array.isArray(usage.modelLimits)) {
+    for (const ml of usage.modelLimits) {
+      attachPaceToData(ml.fiveHour, 'percentUsed', 'fiveHour');
+      attachPaceToData(ml.weekly, 'percentUsed', 'weekly');
+    }
+  }
+}
+
+/**
+ * Attach pace evaluation data to usage metrics based on agent type.
+ * @param {string} agentName - Name of the agent
+ * @param {Object} usage - Usage data object
+ */
+function attachPaceEvaluation(agentName, usage) {
+  switch (agentName) {
+    case 'claude':
+      attachClaudePace(usage);
+      break;
+    case 'gemini':
+      attachGeminiPace(usage);
+      break;
+    case 'codex':
+      attachCodexPace(usage);
+      break;
+  }
+}
+
+module.exports = {
+  attachPaceEvaluation,
+  attachClaudePace,
+  attachGeminiPace,
+  attachCodexPace,
+  attachPaceToData
+};