agent-tank 0.9.0

package/bin/agent-tank.js

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+/* eslint-disable complexity */
+
+const { parseArgs } = require('node:util');
+const { AgentTank } = require('../src/index.js');
+
+const options = {
+  claude: { type: 'boolean', default: false },
+  gemini: { type: 'boolean', default: false },
+  codex: { type: 'boolean', default: false },
+  'claude-api': { type: 'boolean', default: false },
+  port: { type: 'string', default: '3456' },
+  host: { type: 'string' },
+  'auth-user': { type: 'string' },
+  'auth-pass': { type: 'string' },
+  'auth-token': { type: 'string' },
+  'fresh-process': { type: 'boolean', default: false },
+  config: { type: 'string', short: 'c' },
+  help: { type: 'boolean', short: 'h', default: false },
+  'auto-discover': { type: 'boolean', default: true },
+  'auto-refresh': { type: 'boolean', default: true },
+  'auto-refresh-interval': { type: 'string', default: '60' },
+  'auto-refresh-mode': { type: 'string', default: 'activity' },
+  'activity-debounce': { type: 'string', default: '5000' },
+  'history-retention-days': { type: 'string', default: '14' },
+  'keepalive': { type: 'boolean', default: true },
+  'keepalive-interval': { type: 'string', default: '300' },
+  once: { type: 'boolean', default: false },
+  json: { type: 'boolean', default: false },
+};
+
+const { values } = parseArgs({ options, allowPositionals: false, allowNegative: true });
+
+function exitWithCode(code, message, stream = process.stderr) {
+  if (message) {
+    stream.write(`${message}\n`);
+  }
+  process.exitCode = code;
+}
+
+function printHelp() {
+  process.stdout.write(`
+agent-tank - Monitor LLM CLI usage limits
+
+Usage: agent-tank [options]
+
+Options:
+  --claude              Enable Claude monitoring
+  --gemini              Enable Gemini monitoring
+  --codex               Enable Codex monitoring
+  --claude-api          Use direct Anthropic API for Claude usage (faster, 60s refresh)
+  --port <port>         HTTP server port (default: 3456)
+  --host <host>         Bind address (default: 127.0.0.1)
+  --auth-user <user>    HTTP Basic Auth username
+  --auth-pass <pass>    HTTP Basic Auth password
+  --auth-token <token>  API key for Bearer token auth
+  --fresh-process       Spawn a new process per refresh (default: false)
+  --config, -c          Path to config file (JSON)
+  --auto-discover       Auto-discover available agents (default: true)
+  --auto-refresh        Enable/disable background auto-refresh (default: true)
+  --auto-refresh-mode <mode>         Refresh mode: none, interval, activity (default: activity)
+  --auto-refresh-interval <seconds>  Auto-refresh interval in seconds (default: 60, 0 = disabled)
+  --activity-debounce <ms>           Activity debounce interval in milliseconds (default: 5000)
+  --keepalive           Enable/disable session keepalive (default: true)
+  --keepalive-interval <seconds>     Session keepalive interval in seconds (default: 300, 0 = disabled)
+  --history-retention-days <days>    Days to retain usage history (default: 14)
+  --once                Fetch usage once and exit (no HTTP server)
+  --json                Output pure JSON (suppress logging, use with --once)
+  --help, -h            Show this help message
+
+Auto-Refresh Modes:
+  none      - No automatic refresh (manual refresh only via POST /refresh)
+  interval  - Traditional interval-based polling (refreshes at fixed intervals)
+  activity  - Activity-based polling (default) - monitors log directories and
+              refreshes when CLI activity is detected, saving resources during idle
+
+Environment variables:
+  AGENT_TANK_USER       Basic auth username (overrides --auth-user)
+  AGENT_TANK_PASS       Basic auth password (overrides --auth-pass)
+  AGENT_TANK_TOKEN      API key (overrides --auth-token)
+  AGENT_TANK_HOST       Bind address (overrides --host)
+  AGENT_TANK_FRESH_PROCESS  Use fresh process per refresh ("1" or "true")
+  AGENT_TANK_CLAUDE_API Use direct Anthropic API for Claude usage ("1" or "true")
+  AGENT_TANK_AUTO_REFRESH   Enable/disable background auto-refresh ("1" or "true" / "0" or "false")
+  AGENT_TANK_AUTO_REFRESH_MODE      Refresh mode: none, interval, activity
+  AGENT_TANK_AUTO_REFRESH_INTERVAL  Auto-refresh interval in seconds
+  AGENT_TANK_ACTIVITY_DEBOUNCE      Activity debounce interval in milliseconds
+  AGENT_TANK_KEEPALIVE      Enable/disable session keepalive ("1" or "true" / "0" or "false")
+  AGENT_TANK_KEEPALIVE_INTERVAL  Session keepalive interval in seconds
+  AGENT_TANK_HISTORY_RETENTION_DAYS  Days to retain usage history
+
+Examples:
+  agent-tank                          # Auto-discover and monitor all available
+  agent-tank --claude --gemini        # Monitor specific agents
+  agent-tank --port 8080              # Use custom port
+  agent-tank --host 0.0.0.0           # Expose on all interfaces
+  agent-tank --auth-user admin --auth-pass secret  # Enable basic auth
+  agent-tank --auth-token mykey       # Enable API key auth
+  agent-tank -c ./config.json         # Use config file
+  agent-tank --auto-refresh-mode interval  # Use traditional interval polling
+  agent-tank --auto-refresh-mode activity  # Use activity-based polling (default)
+  agent-tank --activity-debounce 10000     # Wait 10 seconds after activity before refresh
+  agent-tank --auto-refresh-interval 30  # Refresh every 30 seconds
+  agent-tank --no-auto-refresh        # Disable background auto-refresh
+  agent-tank --keepalive-interval 600 # Send keepalive every 10 minutes
+  agent-tank --no-keepalive           # Disable session keepalive
+  agent-tank --history-retention-days 7  # Keep only 7 days of history
+  agent-tank --once                   # Fetch usage once and exit
+  agent-tank --once --json            # Output pure JSON for scripting
+
+HTTP Endpoints:
+  GET /              Status page (HTML)
+  GET /status        All agent statuses (JSON)
+  GET /status/:agent Status for specific agent (JSON)
+  GET /config        Auto-refresh and history configuration (JSON)
+  GET /history       Usage history statistics (JSON)
+  GET /history/:agent Usage history for specific agent (JSON)
+  POST /refresh      Trigger refresh for all agents
+  POST /refresh/:agent Trigger refresh for specific agent
+`);
+}
+
+async function main() {
+  if (values.help) {
+    printHelp();
+    process.exitCode = 0;
+    return;
+  }
+
+  // Load config file if specified
+  let config = {};
+  if (values.config) {
+    try {
+      config = require(require('path').resolve(values.config));
+    } catch (err) {
+      exitWithCode(1, `Failed to load config file: ${err.message}`);
+      return;
+    }
+  }
+
+  // Merge CLI options with config (env vars > CLI flags > config file)
+  const agents = [];
+  if (values.claude || config.claude) agents.push('claude');
+  if (values.gemini || config.gemini) agents.push('gemini');
+  if (values.codex || config.codex) agents.push('codex');
+
+  const auth = {
+    user: process.env.AGENT_TANK_USER || values['auth-user'] || config.auth?.user,
+    pass: process.env.AGENT_TANK_PASS || values['auth-pass'] || config.auth?.pass,
+    token: process.env.AGENT_TANK_TOKEN || values['auth-token'] || config.auth?.token,
+  };
+
+  const host = process.env.AGENT_TANK_HOST || values.host || config.host;
+
+  const freshProcessEnv = process.env.AGENT_TANK_FRESH_PROCESS;
+  const freshProcess = values['fresh-process'] ||
+    config.freshProcess ||
+    freshProcessEnv === '1' || freshProcessEnv === 'true';
+
+  // Claude API configuration (env > CLI > config file)
+  const claudeApiEnv = process.env.AGENT_TANK_CLAUDE_API;
+  const claudeApi = values['claude-api'] ||
+    config.claudeApi ||
+    claudeApiEnv === '1' || claudeApiEnv === 'true';
+
+  // Auto-refresh configuration (env > CLI > config file)
+  const autoRefreshEnv = process.env.AGENT_TANK_AUTO_REFRESH;
+  let autoRefreshEnabled = values['auto-refresh'];
+  if (autoRefreshEnv !== undefined) {
+    autoRefreshEnabled = autoRefreshEnv === '1' || autoRefreshEnv === 'true';
+  } else if (config.autoRefresh?.enabled !== undefined) {
+    autoRefreshEnabled = config.autoRefresh.enabled;
+  }
+
+  const autoRefreshIntervalEnv = process.env.AGENT_TANK_AUTO_REFRESH_INTERVAL;
+  let autoRefreshInterval = parseInt(values['auto-refresh-interval'], 10);
+  if (autoRefreshIntervalEnv !== undefined) {
+    autoRefreshInterval = parseInt(autoRefreshIntervalEnv, 10);
+  } else if (config.autoRefresh?.interval !== undefined) {
+    autoRefreshInterval = config.autoRefresh.interval;
+  }
+
+  // Auto-refresh mode configuration (env > CLI > config file)
+  const autoRefreshModeEnv = process.env.AGENT_TANK_AUTO_REFRESH_MODE;
+  let autoRefreshMode = values['auto-refresh-mode'];
+  if (autoRefreshModeEnv !== undefined) {
+    autoRefreshMode = autoRefreshModeEnv;
+  } else if (config.autoRefresh?.mode !== undefined) {
+    autoRefreshMode = config.autoRefresh.mode;
+  }
+
+  // Activity debounce configuration (env > CLI > config file)
+  const activityDebounceEnv = process.env.AGENT_TANK_ACTIVITY_DEBOUNCE;
+  let activityDebounce = parseInt(values['activity-debounce'], 10);
+  if (activityDebounceEnv !== undefined) {
+    activityDebounce = parseInt(activityDebounceEnv, 10);
+  } else if (config.autoRefresh?.activityDebounce !== undefined) {
+    activityDebounce = config.autoRefresh.activityDebounce;
+  }
+
+  // History retention configuration (env > CLI > config file > default)
+  const historyRetentionEnv = process.env.AGENT_TANK_HISTORY_RETENTION_DAYS;
+  let historyRetentionDays = parseInt(values['history-retention-days'], 10);
+  if (historyRetentionEnv !== undefined) {
+    historyRetentionDays = parseInt(historyRetentionEnv, 10);
+  } else if (config.history?.retentionDays !== undefined) {
+    historyRetentionDays = config.history.retentionDays;
+  }
+
+  // Keepalive configuration (env > CLI > config file)
+  const keepaliveEnv = process.env.AGENT_TANK_KEEPALIVE;
+  let keepaliveEnabled = values['keepalive'];
+  if (keepaliveEnv !== undefined) {
+    keepaliveEnabled = keepaliveEnv === '1' || keepaliveEnv === 'true';
+  } else if (config.keepalive?.enabled !== undefined) {
+    keepaliveEnabled = config.keepalive.enabled;
+  }
+
+  const keepaliveIntervalEnv = process.env.AGENT_TANK_KEEPALIVE_INTERVAL;
+  let keepaliveInterval = parseInt(values['keepalive-interval'], 10);
+  if (keepaliveIntervalEnv !== undefined) {
+    keepaliveInterval = parseInt(keepaliveIntervalEnv, 10);
+  } else if (config.keepalive?.interval !== undefined) {
+    keepaliveInterval = config.keepalive.interval;
+  }
+
+  // One-shot and JSON mode flags
+  const onceMode = values.once;
+  const jsonMode = values.json;
+
+  // Suppress console output in JSON mode
+  const originalLog = console.log;
+  if (jsonMode) {
+    console.log = () => {};
+    console.error = () => {};
+    console.warn = () => {};
+  }
+
+  const watcher = new AgentTank({
+    agents: agents.length > 0 ? agents : null, // null = auto-discover
+    autoDiscover: values['auto-discover'] && agents.length === 0,
+    port: parseInt(values.port || config.port || '3456', 10),
+    host,
+    auth,
+    freshProcess,
+    claudeApi,
+    autoRefreshEnabled: onceMode ? false : autoRefreshEnabled, // Disable auto-refresh in one-shot mode
+    autoRefreshInterval,
+    autoRefreshMode: onceMode ? 'none' : autoRefreshMode, // Disable auto-refresh in one-shot mode
+    activityDebounce,
+    keepaliveEnabled: onceMode ? false : keepaliveEnabled, // Disable keepalive in one-shot mode
+    keepaliveInterval,
+    historyRetentionDays,
+    skipServer: onceMode, // Don't start HTTP server in one-shot mode
+  });
+
+  // Graceful shutdown
+  const shutdown = () => {
+    if (!jsonMode) {
+      originalLog('\nShutting down...');
+    }
+    watcher.stop();
+    process.exitCode = 0;
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  try {
+    if (onceMode) {
+      await watcher.start();
+      const status = watcher.getStatus();
+      if (jsonMode) {
+        // Restore console.log for JSON output
+        console.log = originalLog;
+        console.log(JSON.stringify(status, null, 2));
+        // Suppress console.log again before stopping to avoid extra shutdown output
+        console.log = () => {};
+      } else {
+        for (const [name, agentStatus] of Object.entries(status)) {
+          originalLog(`\n=== ${name.toUpperCase()} ===`);
+          originalLog(JSON.stringify(agentStatus, null, 2));
+        }
+      }
+      watcher.stop();
+      process.exitCode = 0;
+      return;
+    }
+
+    await watcher.start();
+  } catch (err) {
+    if (jsonMode) {
+      console.log = originalLog;
+      console.log(JSON.stringify({ error: err.message }, null, 2));
+    } else {
+      exitWithCode(1, `Failed to start: ${err.message}`);
+    }
+    process.exitCode = 1;
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "agent-tank",
+  "version": "0.9.0",
+  "description": "Monitor and query usage limits for LLM CLI tools (Claude, Gemini, Codex) via HTTP API",
+  "main": "src/index.js",
+  "bin": {
+    "agent-tank": "bin/agent-tank.js"
+  },
+  "scripts": {
+    "start": "node bin/agent-tank.js",
+    "dev": "node bin/agent-tank.js",
+    "lint": "eslint src/ bin/",
+    "test": "jest",
+    "test:unit": "jest --testPathPattern=test/unit",
+    "test:e2e": "jest --testPathPattern=test/e2e",
+    "install": "node scripts/install.js || true",
+    "rebuild": "PYTHON=$(which python3.11 || which python3.10 || which python3.9 || which python3.8 || which python3) npm rebuild node-pty"
+  },
+  "keywords": [
+    "llm",
+    "claude",
+    "gemini",
+    "codex",
+    "openai",
+    "anthropic",
+    "google",
+    "usage",
+    "limits",
+    "rate-limit",
+    "monitor",
+    "cli",
+    "api"
+  ],
+  "author": "Rinalds Uzkalns (https://propr.dev)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/integry/agent-tank.git"
+  },
+  "bugs": {
+    "url": "https://github.com/integry/agent-tank/issues"
+  },
+  "homepage": "https://agenttank.io",
+  "dependencies": {
+    "node-pty": "^1.0.0",
+    "source-map-support": "^0.5.21"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "eslint": "^9.39.4",
+    "globals": "^15.15.0",
+    "jest": "^29.7.0",
+    "supertest": "^7.2.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "media/",
+    "LICENSE",
+    "README.md"
+  ]
+}

package/src/activity-monitor.js

@@ -0,0 +1,312 @@
+/**
+ * ActivityMonitor - Monitors local log directories for LLM CLI activity
+ *
+ * Watches known log directories for Claude, Codex, and Gemini using fs.watch.
+ * When activity is detected (new log entries), it triggers usage refresh callbacks
+ * with configurable debouncing to prevent excessive polling.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+/**
+ * Default log directories for each agent.
+ * These are the typical locations where CLI tools store their logs/session data.
+ */
+const DEFAULT_LOG_DIRECTORIES = {
+  claude: [
+    path.join(os.homedir(), '.config', 'claude', 'projects'),
+    path.join(os.homedir(), '.claude'),
+  ],
+  codex: [
+    path.join(os.homedir(), '.codex', 'sessions'),
+    path.join(os.homedir(), '.codex'),
+  ],
+  gemini: [
+    path.join(os.homedir(), '.config', 'gemini'),
+    path.join(os.homedir(), '.gemini'),
+  ],
+};
+
+function normalizeFilename(filename) {
+  return String(filename || '').replace(/\\/g, '/');
+}
+
+function isIgnoredActivityFile(filename) {
+  const normalized = normalizeFilename(filename);
+  if (!normalized) return false;
+
+  return normalized.endsWith('.lock') ||
+    normalized.includes('/.git/') ||
+    normalized.startsWith('.git/') ||
+    normalized.startsWith('plugins/marketplaces/') ||
+    normalized.includes('/plugins/marketplaces/') ||
+    normalized === 'plugins/known_marketplaces.json' ||
+    normalized.endsWith('/plugins/known_marketplaces.json');
+}
+
+class ActivityMonitor {
+  /**
+   * Create an ActivityMonitor instance.
+   *
+   * @param {Object} options - Configuration options
+   * @param {number} [options.debounceInterval=5000] - Debounce interval in milliseconds (default: 5 seconds)
+   * @param {Function} [options.onActivity] - Callback function when activity is detected
+   * @param {Object} [options.logDirectories] - Custom log directories per agent (overrides defaults)
+   * @param {string[]} [options.agents] - List of agents to monitor (default: all known agents)
+   */
+  constructor(options = {}) {
+    this.debounceInterval = options.debounceInterval ?? 5000; // Default: 5 seconds
+    this.onActivity = options.onActivity || (() => {});
+    this.logDirectories = options.logDirectories || DEFAULT_LOG_DIRECTORIES;
+    this.agents = options.agents || Object.keys(DEFAULT_LOG_DIRECTORIES);
+
+    this.watchers = new Map(); // Map<agentName, FSWatcher[]>
+    this.debounceTimers = new Map(); // Map<agentName, timeoutId>
+    this.lastActivityAt = new Map(); // Map<agentName, ISO timestamp>
+    this.suppressedUntil = new Map(); // Map<agentName, unix timestamp in ms>
+    this.isMonitoring = false;
+    this.activityCount = 0; // Total activity events detected
+  }
+
+  /**
+   * Start monitoring log directories for activity.
+   * Sets up fs.watch on each agent's log directories.
+   *
+   * @returns {Object} Status object with monitoring details
+   */
+  start() {
+    if (this.isMonitoring) {
+      console.log('[ActivityMonitor] Already monitoring');
+      return this.getStatus();
+    }
+
+    const monitoredDirs = [];
+    const missingDirs = [];
+
+    for (const agent of this.agents) {
+      const dirs = this.logDirectories[agent] || DEFAULT_LOG_DIRECTORIES[agent] || [];
+      const agentWatchers = [];
+
+      for (const dir of dirs) {
+        if (fs.existsSync(dir)) {
+          try {
+            const watcher = fs.watch(dir, { recursive: true }, (eventType, filename) => {
+              this._handleFileChange(agent, eventType, filename);
+            });
+
+            watcher.on('error', (err) => {
+              console.error(`[ActivityMonitor] Watcher error for ${agent} (${dir}): ${err.message}`);
+            });
+
+            agentWatchers.push(watcher);
+            monitoredDirs.push({ agent, dir });
+            console.log(`[ActivityMonitor] Watching ${agent}: ${dir}`);
+          } catch (err) {
+            console.error(`[ActivityMonitor] Failed to watch ${dir}: ${err.message}`);
+          }
+        } else {
+          missingDirs.push({ agent, dir });
+        }
+      }
+
+      if (agentWatchers.length > 0) {
+        this.watchers.set(agent, agentWatchers);
+      }
+    }
+
+    this.isMonitoring = true;
+
+    if (missingDirs.length > 0) {
+      console.log(`[ActivityMonitor] Some directories not found: ${missingDirs.map(d => d.dir).join(', ')}`);
+    }
+
+    console.log(`[ActivityMonitor] Started monitoring ${monitoredDirs.length} directories for ${this.watchers.size} agent(s)`);
+
+    return {
+      isMonitoring: this.isMonitoring,
+      monitoredDirs,
+      missingDirs,
+      agentCount: this.watchers.size,
+    };
+  }
+
+  /**
+   * Stop monitoring all directories.
+   */
+  stop() {
+    for (const [agent, agentWatchers] of this.watchers) {
+      for (const watcher of agentWatchers) {
+        try {
+          watcher.close();
+        } catch (err) {
+          console.error(`[ActivityMonitor] Error closing watcher for ${agent}: ${err.message}`);
+        }
+      }
+    }
+    this.watchers.clear();
+
+    // Clear any pending debounce timers
+    for (const timer of this.debounceTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.debounceTimers.clear();
+
+    this.isMonitoring = false;
+    console.log('[ActivityMonitor] Stopped');
+  }
+
+  /**
+   * Handle a file change event from fs.watch.
+   * Debounces activity detection per agent.
+   *
+   * @param {string} agent - Agent name
+   * @param {string} eventType - Event type ('rename' or 'change')
+   * @param {string} filename - Changed filename
+   * @private
+   */
+  _handleFileChange(agent, eventType, filename) {
+    if (isIgnoredActivityFile(filename) || this._isSuppressed(agent)) {
+      return;
+    }
+
+    // Clear existing debounce timer for this agent
+    if (this.debounceTimers.has(agent)) {
+      clearTimeout(this.debounceTimers.get(agent));
+    }
+
+    // Set up new debounce timer
+    const timer = setTimeout(() => {
+      this._triggerActivity(agent, eventType, filename);
+      this.debounceTimers.delete(agent);
+    }, this.debounceInterval);
+
+    this.debounceTimers.set(agent, timer);
+  }
+
+  _isSuppressed(agent) {
+    const suppressedUntil = this.suppressedUntil.get(agent);
+    if (!suppressedUntil) {
+      return false;
+    }
+
+    if (Date.now() >= suppressedUntil) {
+      this.suppressedUntil.delete(agent);
+      return false;
+    }
+
+    return true;
+  }
+
+  suppressAgent(agent, durationMs) {
+    this.suppressedUntil.set(agent, Date.now() + durationMs);
+  }
+
+  suppressAll(durationMs) {
+    for (const agent of this.agents) {
+      this.suppressAgent(agent, durationMs);
+    }
+  }
+
+  /**
+   * Trigger the activity callback after debounce period.
+   *
+   * @param {string} agent - Agent name
+   * @param {string} eventType - Event type that triggered this
+   * @param {string} filename - Changed filename
+   * @private
+   */
+  _triggerActivity(agent, eventType, filename) {
+    const now = new Date().toISOString();
+    this.lastActivityAt.set(agent, now);
+    this.activityCount++;
+
+    console.log(`[ActivityMonitor] Activity detected for ${agent}: ${eventType} ${filename || '(unknown file)'}`);
+
+    try {
+      this.onActivity({
+        agent,
+        eventType,
+        filename,
+        timestamp: now,
+        activityCount: this.activityCount,
+      });
+    } catch (err) {
+      console.error(`[ActivityMonitor] Error in onActivity callback: ${err.message}`);
+    }
+  }
+
+  /**
+   * Check if there is pending activity (debounce timer active).
+   *
+   * @param {string} [agent] - Optional agent name to check (checks all if not specified)
+   * @returns {boolean} True if there is pending activity
+   */
+  hasPendingActivity(agent = null) {
+    if (agent) {
+      return this.debounceTimers.has(agent);
+    }
+    return this.debounceTimers.size > 0;
+  }
+
+  /**
+   * Get the time since last activity for an agent.
+   *
+   * @param {string} agent - Agent name
+   * @returns {number|null} Milliseconds since last activity, or null if never active
+   */
+  getTimeSinceActivity(agent) {
+    const lastActivity = this.lastActivityAt.get(agent);
+    if (!lastActivity) {
+      return null;
+    }
+    return Date.now() - new Date(lastActivity).getTime();
+  }
+
+  /**
+   * Set the debounce interval dynamically.
+   *
+   * @param {number} interval - Debounce interval in milliseconds
+   */
+  setDebounceInterval(interval) {
+    this.debounceInterval = interval;
+    console.log(`[ActivityMonitor] Debounce interval set to ${interval}ms`);
+  }
+
+  /**
+   * Get the current status of the activity monitor.
+   *
+   * @returns {Object} Status information
+   */
+  getStatus() {
+    const monitoredAgents = Array.from(this.watchers.keys());
+    const lastActivityByAgent = {};
+    for (const [agent, timestamp] of this.lastActivityAt) {
+      lastActivityByAgent[agent] = timestamp;
+    }
+
+    return {
+      isMonitoring: this.isMonitoring,
+      debounceInterval: this.debounceInterval,
+      monitoredAgents,
+      agentCount: monitoredAgents.length,
+      activityCount: this.activityCount,
+      lastActivityAt: lastActivityByAgent,
+      hasPendingActivity: this.hasPendingActivity(),
+      pendingAgents: Array.from(this.debounceTimers.keys()),
+    };
+  }
+
+  /**
+   * Manually trigger an activity check for an agent.
+   * Useful for testing or forcing a refresh.
+   *
+   * @param {string} agent - Agent name
+   */
+  triggerManual(agent) {
+    this._triggerActivity(agent, 'manual', 'manual-trigger');
+  }
+}
+
+module.exports = { ActivityMonitor, DEFAULT_LOG_DIRECTORIES };