tlc-claude-code 1.4.1 → 1.4.4

package/server/index.js

@@ -471,6 +471,184 @@ app.post('/api/test', (req, res) => {
   res.json({ success: true });
 });
 
+// ============================================
+// Agent Registry API (Phase 32)
+// ============================================
+const { getAgentRegistry } = require('./lib/agent-registry');
+const { createAgentState } = require('./lib/agent-state');
+const { createMetadata } = require('./lib/agent-metadata');
+
+// Helper to format agent for API response
+function formatAgent(agent) {
+  return {
+    id: agent.id,
+    name: agent.name,
+    state: {
+      current: agent.stateMachine ? agent.stateMachine.getState() : 'pending',
+      history: agent.stateMachine ? agent.stateMachine.getHistory() : [],
+    },
+    metadata: {
+      model: agent.model,
+      taskType: agent.taskType || 'unknown',
+      tokens: agent.metadataObj ? {
+        input: agent.metadataObj.inputTokens,
+        output: agent.metadataObj.outputTokens,
+        total: agent.metadataObj.totalTokens,
+      } : { input: 0, output: 0, total: 0 },
+    },
+    createdAt: agent.createdAt || agent.registeredAt,
+  };
+}
+
+// List agents
+app.get('/api/agents', (req, res) => {
+  try {
+    const registry = getAgentRegistry();
+    let agents = registry.listAgents();
+
+    // Filter by status (state.current)
+    if (req.query.status) {
+      agents = agents.filter(a =>
+        a.stateMachine ? a.stateMachine.getState() === req.query.status : false
+      );
+    }
+    // Filter by model
+    if (req.query.model) {
+      agents = agents.filter(a => a.model === req.query.model);
+    }
+    // Filter by type
+    if (req.query.type) {
+      agents = agents.filter(a => a.taskType === req.query.type);
+    }
+
+    res.json({ success: true, agents: agents.map(formatAgent) });
+  } catch (err) {
+    res.status(500).json({ success: false, error: err.message });
+  }
+});
+
+// Get single agent
+app.get('/api/agents/:id', (req, res) => {
+  try {
+    const registry = getAgentRegistry();
+    const agent = registry.getAgent(req.params.id);
+    if (!agent) {
+      return res.status(404).json({ success: false, error: 'Agent not found' });
+    }
+    res.json({ success: true, agent: formatAgent(agent) });
+  } catch (err) {
+    res.status(500).json({ success: false, error: err.message });
+  }
+});
+
+// Register new agent
+app.post('/api/agents', (req, res) => {
+  try {
+    const registry = getAgentRegistry();
+    const { id, name, model, taskType } = req.body;
+
+    if (!name) {
+      return res.status(400).json({ success: false, error: 'name is required' });
+    }
+
+    // Create state machine and metadata
+    const stateMachine = createAgentState({ agentId: id });
+    const metadataObj = createMetadata({
+      model: model || 'unknown',
+      taskType: taskType || 'default',
+    });
+
+    // Register with all components
+    const agentId = registry.registerAgent({
+      id,
+      name,
+      model: model || 'unknown',
+      taskType: taskType || 'default',
+      stateMachine,
+      metadataObj,
+      createdAt: Date.now(),
+    });
+
+    const agent = registry.getAgent(agentId);
+    res.status(201).json({ success: true, agent: formatAgent(agent) });
+  } catch (err) {
+    res.status(500).json({ success: false, error: err.message });
+  }
+});
+
+// Update agent (state transitions, token updates)
+app.patch('/api/agents/:id', (req, res) => {
+  try {
+    const registry = getAgentRegistry();
+    const agent = registry.getAgent(req.params.id);
+    if (!agent) {
+      return res.status(404).json({ success: false, error: 'Agent not found' });
+    }
+
+    // Handle state transition
+    if (req.body.state) {
+      if (!agent.stateMachine) {
+        return res.status(400).json({ success: false, error: 'Agent has no state machine' });
+      }
+      const result = agent.stateMachine.transition(req.body.state, { reason: req.body.reason });
+      if (!result.success) {
+        return res.status(400).json({ success: false, error: result.error });
+      }
+    }
+
+    // Handle token updates
+    if (req.body.tokens && agent.metadataObj) {
+      agent.metadataObj.updateTokens({
+        input: req.body.tokens.input || 0,
+        output: req.body.tokens.output || 0,
+      });
+    }
+
+    res.json({ success: true, agent: formatAgent(agent) });
+  } catch (err) {
+    res.status(500).json({ success: false, error: err.message });
+  }
+});
+
+// Delete agent
+app.delete('/api/agents/:id', (req, res) => {
+  try {
+    const registry = getAgentRegistry();
+    const removed = registry.removeAgent(req.params.id);
+    if (!removed) {
+      return res.status(404).json({ success: false, error: 'Agent not found' });
+    }
+    res.json({ success: true });
+  } catch (err) {
+    res.status(500).json({ success: false, error: err.message });
+  }
+});
+
+// Get registry stats
+app.get('/api/agents-stats', (req, res) => {
+  try {
+    const registry = getAgentRegistry();
+    const agents = registry.listAgents();
+
+    const stats = {
+      total: agents.length,
+      byStatus: {},
+      byModel: {}
+    };
+
+    agents.forEach(agent => {
+      const status = agent.stateMachine ? agent.stateMachine.getState() : 'pending';
+      const model = agent.model || 'unknown';
+      stats.byStatus[status] = (stats.byStatus[status] || 0) + 1;
+      stats.byModel[model] = (stats.byModel[model] || 0) + 1;
+    });
+
+    res.json({ success: true, stats });
+  } catch (err) {
+    res.status(500).json({ success: false, error: err.message });
+  }
+});
+
 app.post('/api/restart', (req, res) => {
   addLog('app', '--- Restarting app ---', 'warn');
   broadcast('app-restart', {});

package/server/lib/agent-cleanup.js

@@ -0,0 +1,177 @@
+/**
+ * Agent Cleanup - Handles timeouts and orphaned agents
+ *
+ * Detects stuck agents (running state but no activity for timeout period)
+ * and transitions them to cancelled state.
+ * Supports periodic cleanup via setInterval with configurable interval.
+ */
+
+import { getAgentRegistry } from './agent-registry.js';
+import { getAgentHooks } from './agent-hooks.js';
+import { STATES } from './agent-state.js';
+
+/**
+ * Default timeout for detecting orphaned agents (30 minutes)
+ */
+const DEFAULT_TIMEOUT = 30 * 60 * 1000;
+
+/**
+ * Default interval for periodic cleanup (5 minutes)
+ */
+const DEFAULT_INTERVAL = 5 * 60 * 1000;
+
+/**
+ * Internal state for cleanup scheduling and stats
+ */
+let cleanupIntervalId = null;
+let cleanupStats = {
+  totalCleaned: 0,
+  cleanupRuns: 0,
+  lastCleanupAt: null,
+};
+
+/**
+ * Find agents that are orphaned (stuck in running state without activity)
+ * @param {Object} [options] - Options
+ * @param {number} [options.timeout] - Timeout in ms (default: 30 minutes)
+ * @returns {Array} Array of orphaned agent objects
+ */
+function findOrphanedAgents(options = {}) {
+  const timeout = options.timeout || DEFAULT_TIMEOUT;
+  const registry = getAgentRegistry();
+  const now = Date.now();
+
+  // Get all running agents
+  const runningAgents = registry.listAgents({ status: STATES.RUNNING });
+
+  // Filter to those with no activity for longer than timeout
+  const orphans = runningAgents.filter(agent => {
+    const lastActivity = agent.lastActivity || agent.registeredAt;
+    const inactiveTime = now - lastActivity;
+
+    // Check if agent has a custom grace period
+    if (agent.gracePeriod) {
+      return inactiveTime > agent.gracePeriod;
+    }
+
+    return inactiveTime > timeout;
+  });
+
+  return orphans;
+}
+
+/**
+ * Clean up orphaned agents by transitioning them to cancelled state
+ * @param {Object} [options] - Options
+ * @param {number} [options.timeout] - Timeout for finding orphans (default: 30 minutes)
+ * @returns {Promise<Object>} Result with cleaned agents and any errors
+ */
+async function cleanupOrphans(options = {}) {
+  const orphans = findOrphanedAgents(options);
+  const registry = getAgentRegistry();
+  const hooks = getAgentHooks();
+
+  const cleaned = [];
+  const errors = [];
+
+  for (const agent of orphans) {
+    try {
+      // Update agent status to cancelled
+      registry.updateAgent(agent.id, {
+        status: STATES.CANCELLED,
+        cancelledAt: Date.now(),
+        cancelReason: 'orphaned',
+      });
+
+      // Trigger onCancel hook
+      try {
+        await hooks.triggerHook('onCancel', {
+          agentId: agent.id,
+          agent: agent,
+          reason: 'orphaned',
+          timeout: options.timeout || DEFAULT_TIMEOUT,
+        });
+      } catch (hookError) {
+        // Hook errors are logged but don't stop cleanup
+        errors.push({ agentId: agent.id, error: hookError.message, type: 'hook' });
+      }
+
+      cleaned.push(agent);
+
+      // Log cleanup action
+      console.log(`[agent-cleanup] Cleaned orphaned agent: ${agent.id} (${agent.name})`);
+    } catch (err) {
+      errors.push({ agentId: agent.id, error: err.message, type: 'cleanup' });
+    }
+  }
+
+  // Update stats
+  cleanupStats.totalCleaned += cleaned.length;
+  cleanupStats.cleanupRuns += 1;
+  cleanupStats.lastCleanupAt = Date.now();
+
+  return { cleaned, errors };
+}
+
+/**
+ * Schedule periodic cleanup
+ * @param {Object} [options] - Options
+ * @param {number} [options.interval] - Interval in ms (default: 5 minutes)
+ * @param {number} [options.timeout] - Timeout for finding orphans (default: 30 minutes)
+ */
+function scheduleCleanup(options = {}) {
+  const interval = options.interval || DEFAULT_INTERVAL;
+
+  // Stop any existing schedule
+  stopCleanup();
+
+  // Schedule periodic cleanup
+  cleanupIntervalId = setInterval(async () => {
+    try {
+      await cleanupOrphans(options);
+    } catch (err) {
+      console.error('[agent-cleanup] Error during scheduled cleanup:', err);
+    }
+  }, interval);
+}
+
+/**
+ * Stop the scheduled cleanup
+ */
+function stopCleanup() {
+  if (cleanupIntervalId) {
+    clearInterval(cleanupIntervalId);
+    cleanupIntervalId = null;
+  }
+}
+
+/**
+ * Get cleanup statistics
+ * @returns {Object} Stats including totalCleaned, cleanupRuns, lastCleanupAt
+ */
+function getCleanupStats() {
+  return { ...cleanupStats };
+}
+
+/**
+ * Reset cleanup state (for testing)
+ */
+function resetCleanup() {
+  stopCleanup();
+  cleanupStats = {
+    totalCleaned: 0,
+    cleanupRuns: 0,
+    lastCleanupAt: null,
+  };
+}
+
+export {
+  findOrphanedAgents,
+  cleanupOrphans,
+  scheduleCleanup,
+  stopCleanup,
+  getCleanupStats,
+  resetCleanup,
+  DEFAULT_TIMEOUT,
+  DEFAULT_INTERVAL,
+};

package/server/lib/agent-cleanup.test.js

@@ -0,0 +1,359 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  findOrphanedAgents,
+  cleanupOrphans,
+  scheduleCleanup,
+  stopCleanup,
+  getCleanupStats,
+  DEFAULT_TIMEOUT,
+  DEFAULT_INTERVAL,
+  resetCleanup,
+} from './agent-cleanup.js';
+import { getAgentRegistry, resetRegistry } from './agent-registry.js';
+import { getAgentHooks, resetHooks } from './agent-hooks.js';
+import { STATES } from './agent-state.js';
+
+describe('agent-cleanup', () => {
+  let registry;
+  let hooks;
+  const BASE_TIME = new Date('2025-01-01T12:00:00Z').getTime();
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(BASE_TIME);
+    resetRegistry();
+    resetHooks();
+    resetCleanup();
+    registry = getAgentRegistry();
+    hooks = getAgentHooks();
+  });
+
+  afterEach(() => {
+    stopCleanup();
+    vi.useRealTimers();
+  });
+
+  describe('findOrphanedAgents', () => {
+    it('detects stuck agents', () => {
+      // Register agent and set it as running with old lastActivity
+      const id = registry.registerAgent({
+        name: 'stuck-agent',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.RUNNING,
+        lastActivity: Date.now() - 35 * 60 * 1000, // 35 minutes ago
+      });
+
+      const orphans = findOrphanedAgents();
+
+      expect(orphans).toHaveLength(1);
+      expect(orphans[0].id).toBe(id);
+    });
+
+    it('uses configurable timeout', () => {
+      // Register agent running for 10 minutes
+      const id = registry.registerAgent({
+        name: 'agent',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.RUNNING,
+        lastActivity: Date.now() - 10 * 60 * 1000, // 10 minutes ago
+      });
+
+      // With default 30 minute timeout, should not be orphaned
+      expect(findOrphanedAgents()).toHaveLength(0);
+
+      // With 5 minute timeout, should be orphaned
+      const orphans = findOrphanedAgents({ timeout: 5 * 60 * 1000 });
+      expect(orphans).toHaveLength(1);
+      expect(orphans[0].id).toBe(id);
+    });
+
+    it('does not flag recently active agents', () => {
+      registry.registerAgent({
+        name: 'active-agent',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.RUNNING,
+        lastActivity: Date.now() - 5 * 60 * 1000, // 5 minutes ago - recent
+      });
+
+      const orphans = findOrphanedAgents();
+
+      expect(orphans).toHaveLength(0);
+    });
+
+    it('only flags running agents', () => {
+      // Pending agent with old activity - should not be orphaned
+      registry.registerAgent({
+        name: 'pending-agent',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.PENDING,
+        lastActivity: Date.now() - 35 * 60 * 1000,
+      });
+
+      // Completed agent with old activity - should not be orphaned
+      registry.registerAgent({
+        name: 'completed-agent',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.COMPLETED,
+        lastActivity: Date.now() - 35 * 60 * 1000,
+      });
+
+      const orphans = findOrphanedAgents();
+
+      expect(orphans).toHaveLength(0);
+    });
+  });
+
+  describe('cleanupOrphans', () => {
+    it('transitions to cancelled', async () => {
+      const id = registry.registerAgent({
+        name: 'stuck-agent',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.RUNNING,
+        lastActivity: Date.now() - 35 * 60 * 1000,
+      });
+
+      const result = await cleanupOrphans();
+
+      expect(result.cleaned).toHaveLength(1);
+      expect(result.cleaned[0].id).toBe(id);
+
+      const agent = registry.getAgent(id);
+      expect(agent.status).toBe(STATES.CANCELLED);
+    });
+
+    it('triggers hooks', async () => {
+      const onCancelHandler = vi.fn();
+      hooks.registerHook('onCancel', onCancelHandler);
+
+      registry.registerAgent({
+        name: 'stuck-agent',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.RUNNING,
+        lastActivity: Date.now() - 35 * 60 * 1000,
+      });
+
+      await cleanupOrphans();
+
+      expect(onCancelHandler).toHaveBeenCalled();
+      expect(onCancelHandler).toHaveBeenCalledWith(
+        expect.objectContaining({
+          reason: 'orphaned',
+        })
+      );
+    });
+
+    it('handles cleanup errors gracefully', async () => {
+      // Register an agent that will cause error during hook execution
+      registry.registerAgent({
+        name: 'error-agent',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.RUNNING,
+        lastActivity: Date.now() - 35 * 60 * 1000,
+      });
+
+      // Register a hook that throws
+      hooks.registerHook('onCancel', () => {
+        throw new Error('Hook error');
+      });
+
+      // Should not throw, should handle gracefully
+      const result = await cleanupOrphans();
+
+      expect(result.errors).toBeDefined();
+      expect(result.errors.length).toBeGreaterThanOrEqual(0);
+    });
+
+    it('respects agent grace period', async () => {
+      // Agent with gracePeriod that hasn't expired
+      registry.registerAgent({
+        name: 'grace-agent',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.RUNNING,
+        lastActivity: Date.now() - 35 * 60 * 1000,
+        gracePeriod: 60 * 60 * 1000, // 1 hour grace period
+      });
+
+      // Agent without grace period - should be cleaned
+      const id2 = registry.registerAgent({
+        name: 'no-grace-agent',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.RUNNING,
+        lastActivity: Date.now() - 35 * 60 * 1000,
+      });
+
+      const result = await cleanupOrphans();
+
+      expect(result.cleaned).toHaveLength(1);
+      expect(result.cleaned[0].id).toBe(id2);
+    });
+
+    it('logs cleanup actions', async () => {
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+      registry.registerAgent({
+        name: 'stuck-agent',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.RUNNING,
+        lastActivity: Date.now() - 35 * 60 * 1000,
+      });
+
+      await cleanupOrphans();
+
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining('cleanup')
+      );
+
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe('scheduleCleanup', () => {
+    it('runs periodically', async () => {
+      // Set up an orphan
+      registry.registerAgent({
+        name: 'stuck-agent',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.RUNNING,
+        lastActivity: Date.now() - 35 * 60 * 1000,
+      });
+
+      scheduleCleanup({ interval: 1000 }); // Every 1 second for testing
+
+      // Initially no cleanup yet
+      let stats = getCleanupStats();
+      expect(stats.totalCleaned).toBe(0);
+
+      // Advance time by 1 second
+      await vi.advanceTimersByTimeAsync(1000);
+
+      stats = getCleanupStats();
+      expect(stats.totalCleaned).toBe(1);
+    });
+
+    it('uses configurable interval', async () => {
+      const customInterval = 5 * 60 * 1000; // 5 minutes
+
+      scheduleCleanup({ interval: customInterval });
+
+      // Add an orphan after scheduling
+      registry.registerAgent({
+        name: 'stuck-agent',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.RUNNING,
+        lastActivity: Date.now() - 35 * 60 * 1000,
+      });
+
+      // Advance 1 minute - no cleanup yet
+      await vi.advanceTimersByTimeAsync(60 * 1000);
+      expect(getCleanupStats().totalCleaned).toBe(0);
+
+      // Advance to 5 minutes - cleanup should run
+      await vi.advanceTimersByTimeAsync(4 * 60 * 1000);
+      expect(getCleanupStats().totalCleaned).toBe(1);
+    });
+  });
+
+  describe('stopCleanup', () => {
+    it('cancels schedule', () => {
+      scheduleCleanup({ interval: 1000 });
+
+      registry.registerAgent({
+        name: 'stuck-agent',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.RUNNING,
+        lastActivity: Date.now() - 35 * 60 * 1000,
+      });
+
+      stopCleanup();
+
+      // Advance time - cleanup should not run since stopped
+      vi.advanceTimersByTime(5000);
+
+      expect(getCleanupStats().totalCleaned).toBe(0);
+    });
+
+    it('is safe to call multiple times', () => {
+      stopCleanup();
+      stopCleanup();
+      stopCleanup();
+
+      // Should not throw
+      expect(true).toBe(true);
+    });
+  });
+
+  describe('getCleanupStats', () => {
+    it('returns counts', async () => {
+      const id = registry.registerAgent({
+        name: 'stuck-agent',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.RUNNING,
+        lastActivity: Date.now() - 35 * 60 * 1000,
+      });
+
+      const statsBefore = getCleanupStats();
+      expect(statsBefore.totalCleaned).toBe(0);
+      expect(statsBefore.lastCleanupAt).toBeNull();
+
+      await cleanupOrphans();
+
+      const statsAfter = getCleanupStats();
+      expect(statsAfter.totalCleaned).toBe(1);
+      expect(statsAfter.lastCleanupAt).toBeDefined();
+      expect(statsAfter.cleanupRuns).toBe(1);
+    });
+
+    it('accumulates across multiple cleanup runs', async () => {
+      // First orphan
+      registry.registerAgent({
+        name: 'stuck-agent-1',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.RUNNING,
+        lastActivity: Date.now() - 35 * 60 * 1000,
+      });
+
+      await cleanupOrphans();
+
+      // Second orphan (new one)
+      registry.registerAgent({
+        name: 'stuck-agent-2',
+        model: 'claude-3',
+        type: 'worker',
+        status: STATES.RUNNING,
+        lastActivity: Date.now() - 35 * 60 * 1000,
+      });
+
+      await cleanupOrphans();
+
+      const stats = getCleanupStats();
+      expect(stats.totalCleaned).toBe(2);
+      expect(stats.cleanupRuns).toBe(2);
+    });
+  });
+
+  describe('defaults', () => {
+    it('DEFAULT_TIMEOUT is 30 minutes', () => {
+      expect(DEFAULT_TIMEOUT).toBe(30 * 60 * 1000);
+    });
+
+    it('DEFAULT_INTERVAL is 5 minutes', () => {
+      expect(DEFAULT_INTERVAL).toBe(5 * 60 * 1000);
+    });
+  });
+});