tlc-claude-code 1.4.0 → 1.4.2

package/server/lib/agent-registry-command.js

@@ -0,0 +1,340 @@
+/**
+ * Agent Registry Command
+ * CLI for agent registry operations
+ */
+
+import registry from './agent-registry.js';
+import { transitionTo, STATES } from './agent-state.js';
+import { cleanupOrphans, getCleanupStats } from './agent-cleanup.js';
+import { triggerHook } from './agent-hooks.js';
+
+/**
+ * Parse command line arguments
+ * @param {string[]} args - Command line arguments
+ * @returns {Object} Parsed arguments
+ */
+export function parseArgs(args) {
+  if (!args || args.length === 0) {
+    return { command: 'help', args: [], flags: {} };
+  }
+
+  const command = args[0];
+  const flags = {};
+  const positionalArgs = [];
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      const flagName = arg.slice(2);
+      // Check if next arg is a value or another flag
+      if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+        flags[flagName] = args[i + 1];
+        i++;
+      } else {
+        flags[flagName] = true;
+      }
+    } else {
+      positionalArgs.push(arg);
+    }
+  }
+
+  return { command, args: positionalArgs, flags };
+}
+
+/**
+ * Execute a registry command
+ * @param {string[]} args - Command arguments
+ * @returns {Promise<Object>} Command result
+ */
+export async function execute(args) {
+  const parsed = parseArgs(args);
+
+  switch (parsed.command) {
+    case 'list':
+      return executeList(parsed);
+    case 'get':
+      return executeGet(parsed);
+    case 'cancel':
+      return executeCancel(parsed);
+    case 'cleanup':
+      return executeCleanup(parsed);
+    case 'help':
+      return executeHelp();
+    default:
+      return {
+        success: false,
+        error: `Unknown command: ${parsed.command}. Use 'help' to see available commands.`,
+      };
+  }
+}
+
+/**
+ * Execute list command
+ */
+function executeList(parsed) {
+  const filters = {};
+
+  if (parsed.flags.status) {
+    filters.status = parsed.flags.status;
+  }
+  if (parsed.flags.model) {
+    filters.model = parsed.flags.model;
+  }
+
+  const agents = registry.listAgents(Object.keys(filters).length > 0 ? filters : undefined);
+
+  return {
+    success: true,
+    data: agents,
+    formatted: formatAgentList(agents),
+  };
+}
+
+/**
+ * Execute get command
+ */
+function executeGet(parsed) {
+  const agentId = parsed.args[0];
+
+  if (!agentId) {
+    return {
+      success: false,
+      error: 'Agent ID required. Usage: tlc agents get <id>',
+    };
+  }
+
+  const agent = registry.getAgent(agentId);
+
+  if (!agent) {
+    return {
+      success: false,
+      error: `Agent '${agentId}' not found`,
+    };
+  }
+
+  return {
+    success: true,
+    data: agent,
+    formatted: formatAgentDetails(agent),
+  };
+}
+
+/**
+ * Execute cancel command
+ */
+async function executeCancel(parsed) {
+  const agentId = parsed.args[0];
+
+  if (!agentId) {
+    return {
+      success: false,
+      error: 'Agent ID required. Usage: tlc agents cancel <id>',
+    };
+  }
+
+  const agent = registry.getAgent(agentId);
+
+  if (!agent) {
+    return {
+      success: false,
+      error: `Agent '${agentId}' not found`,
+    };
+  }
+
+  // Check if agent can be cancelled
+  const cancellableStates = [STATES.PENDING, STATES.RUNNING];
+  if (!cancellableStates.includes(agent.state.current)) {
+    return {
+      success: false,
+      error: `Cannot cancel agent in '${agent.state.current}' state. Only pending or running agents can be cancelled.`,
+    };
+  }
+
+  // Transition to cancelled
+  transitionTo(agent.state, STATES.CANCELLED, { reason: 'User requested cancellation' });
+
+  // Trigger cancel hook
+  await triggerHook('onCancel', agent);
+
+  return {
+    success: true,
+    message: `Agent '${agentId}' cancelled successfully`,
+    data: agent,
+  };
+}
+
+/**
+ * Execute cleanup command
+ */
+async function executeCleanup(parsed) {
+  const result = await cleanupOrphans();
+  const stats = getCleanupStats();
+
+  return {
+    success: true,
+    data: {
+      cleaned: result.cleaned,
+      errors: result.errors,
+      stats,
+    },
+    formatted: formatCleanupResult(result, stats),
+  };
+}
+
+/**
+ * Execute help command
+ */
+function executeHelp() {
+  const message = `
+Usage: tlc agents <command> [options]
+
+Commands:
+  list                  List all agents
+    --status <status>   Filter by status (pending, running, completed, failed, cancelled)
+    --model <model>     Filter by model
+    --json              Output as JSON
+
+  get <id>              Show agent details
+    --json              Output as JSON
+
+  cancel <id>           Cancel a running agent
+
+  cleanup               Run cleanup for orphaned agents
+
+  help                  Show this help message
+
+Examples:
+  tlc agents list
+  tlc agents list --status running
+  tlc agents list --model claude --status completed
+  tlc agents get agent-abc123
+  tlc agents cancel agent-abc123
+  tlc agents cleanup
+`.trim();
+
+  return {
+    success: true,
+    message,
+  };
+}
+
+/**
+ * Format agent list as table
+ * @param {Object[]} agents - List of agents
+ * @returns {string} Formatted table
+ */
+export function formatAgentList(agents) {
+  if (!agents || agents.length === 0) {
+    return 'No agents found.';
+  }
+
+  const header = '| ID | Name | Status | Model | Created |';
+  const separator = '|------|------|--------|-------|---------|';
+
+  const rows = agents.map(agent => {
+    const id = truncate(agent.id, 15);
+    const name = truncate(agent.name || '-', 20);
+    const status = agent.state?.current || '-';
+    const model = agent.metadata?.model || '-';
+    const created = agent.createdAt ? formatDate(agent.createdAt) : '-';
+
+    return `| ${id} | ${name} | ${status} | ${model} | ${created} |`;
+  });
+
+  return [header, separator, ...rows].join('\n');
+}
+
+/**
+ * Format agent details
+ * @param {Object} agent - Agent object
+ * @returns {string} Formatted details
+ */
+export function formatAgentDetails(agent) {
+  const lines = [
+    `Agent: ${agent.id}`,
+    `Name: ${agent.name || '-'}`,
+    `Status: ${agent.state?.current || '-'}`,
+    `Model: ${agent.metadata?.model || '-'}`,
+    `Created: ${agent.createdAt || '-'}`,
+    '',
+  ];
+
+  // Add token info if available
+  if (agent.metadata?.tokens) {
+    lines.push('Tokens:');
+    lines.push(`  Input: ${agent.metadata.tokens.input || 0}`);
+    lines.push(`  Output: ${agent.metadata.tokens.output || 0}`);
+    lines.push(`  Total: ${(agent.metadata.tokens.input || 0) + (agent.metadata.tokens.output || 0)}`);
+    lines.push('');
+  }
+
+  // Add cost if available
+  if (agent.metadata?.cost !== undefined) {
+    lines.push(`Cost: $${agent.metadata.cost.toFixed(4)}`);
+    lines.push('');
+  }
+
+  // Add state history if available
+  if (agent.state?.history && agent.state.history.length > 0) {
+    lines.push('State History:');
+    agent.state.history.forEach(entry => {
+      const time = entry.timestamp ? formatDate(entry.timestamp) : '-';
+      lines.push(`  ${time}: ${entry.state}`);
+    });
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format cleanup result
+ */
+function formatCleanupResult(result, stats) {
+  const lines = [
+    'Cleanup Results:',
+    `  Cleaned this run: ${result.cleaned.length}`,
+    `  Errors: ${result.errors.length}`,
+    '',
+    'Overall Stats:',
+    `  Total cleaned: ${stats.totalCleaned}`,
+    `  Cleanup runs: ${stats.cleanupRuns}`,
+    `  Last cleanup: ${stats.lastCleanupAt ? formatDate(stats.lastCleanupAt) : 'Never'}`,
+  ];
+
+  if (result.cleaned.length > 0) {
+    lines.push('');
+    lines.push('Cleaned agents:');
+    result.cleaned.forEach(id => lines.push(`  - ${id}`));
+  }
+
+  if (result.errors.length > 0) {
+    lines.push('');
+    lines.push('Errors:');
+    result.errors.forEach(err => lines.push(`  - ${err.id}: ${err.error}`));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Truncate string to max length
+ */
+function truncate(str, maxLength) {
+  if (!str) return '-';
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength - 3) + '...';
+}
+
+/**
+ * Format date for display
+ */
+function formatDate(dateStr) {
+  try {
+    const date = new Date(dateStr);
+    return date.toISOString().replace('T', ' ').slice(0, 19);
+  } catch {
+    return dateStr;
+  }
+}
+
+export default { execute, parseArgs, formatAgentList, formatAgentDetails };

package/server/lib/agent-registry-command.test.js

@@ -0,0 +1,334 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// Mock dependencies
+vi.mock('./agent-registry.js', () => ({
+  default: {
+    listAgents: vi.fn(),
+    getAgent: vi.fn(),
+    removeAgent: vi.fn(),
+  },
+}));
+
+vi.mock('./agent-state.js', () => ({
+  transitionTo: vi.fn(),
+  STATES: {
+    PENDING: 'pending',
+    RUNNING: 'running',
+    COMPLETED: 'completed',
+    FAILED: 'failed',
+    CANCELLED: 'cancelled',
+  },
+}));
+
+vi.mock('./agent-cleanup.js', () => ({
+  cleanupOrphans: vi.fn(),
+  getCleanupStats: vi.fn(),
+}));
+
+vi.mock('./agent-hooks.js', () => ({
+  triggerHook: vi.fn(),
+}));
+
+import {
+  execute,
+  formatAgentList,
+  formatAgentDetails,
+  parseArgs,
+} from './agent-registry-command.js';
+import registry from './agent-registry.js';
+import { transitionTo, STATES } from './agent-state.js';
+import { cleanupOrphans, getCleanupStats } from './agent-cleanup.js';
+import { triggerHook } from './agent-hooks.js';
+
+describe('agent-registry-command', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('execute list', () => {
+    it('shows all agents', async () => {
+      const agents = [
+        { id: 'agent-1', name: 'test-1', state: { current: 'running' }, metadata: { model: 'claude' } },
+        { id: 'agent-2', name: 'test-2', state: { current: 'completed' }, metadata: { model: 'gpt-4' } },
+      ];
+      registry.listAgents.mockReturnValue(agents);
+
+      const result = await execute(['list']);
+
+      expect(registry.listAgents).toHaveBeenCalled();
+      expect(result.success).toBe(true);
+      expect(result.data).toEqual(agents);
+    });
+
+    it('filters by status', async () => {
+      const agents = [
+        { id: 'agent-1', name: 'test-1', state: { current: 'running' }, metadata: { model: 'claude' } },
+      ];
+      registry.listAgents.mockReturnValue(agents);
+
+      const result = await execute(['list', '--status', 'running']);
+
+      expect(registry.listAgents).toHaveBeenCalledWith({ status: 'running' });
+      expect(result.success).toBe(true);
+    });
+
+    it('filters by model', async () => {
+      const agents = [
+        { id: 'agent-1', name: 'test-1', state: { current: 'running' }, metadata: { model: 'claude' } },
+      ];
+      registry.listAgents.mockReturnValue(agents);
+
+      const result = await execute(['list', '--model', 'claude']);
+
+      expect(registry.listAgents).toHaveBeenCalledWith({ model: 'claude' });
+      expect(result.success).toBe(true);
+    });
+
+    it('combines filters', async () => {
+      registry.listAgents.mockReturnValue([]);
+
+      const result = await execute(['list', '--status', 'running', '--model', 'claude']);
+
+      expect(registry.listAgents).toHaveBeenCalledWith({ status: 'running', model: 'claude' });
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('execute get', () => {
+    it('shows agent details', async () => {
+      const agent = {
+        id: 'agent-123',
+        name: 'test-agent',
+        state: { current: 'running', history: [] },
+        metadata: { model: 'claude', tokens: { input: 100, output: 50 } },
+        createdAt: new Date().toISOString(),
+      };
+      registry.getAgent.mockReturnValue(agent);
+
+      const result = await execute(['get', 'agent-123']);
+
+      expect(registry.getAgent).toHaveBeenCalledWith('agent-123');
+      expect(result.success).toBe(true);
+      expect(result.data).toEqual(agent);
+    });
+
+    it('shows error for missing agent', async () => {
+      registry.getAgent.mockReturnValue(null);
+
+      const result = await execute(['get', 'unknown-id']);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('not found');
+    });
+
+    it('requires agent ID', async () => {
+      const result = await execute(['get']);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Agent ID required');
+    });
+  });
+
+  describe('execute cancel', () => {
+    it('cancels running agent', async () => {
+      const agent = {
+        id: 'agent-123',
+        name: 'test-agent',
+        state: { current: 'running' },
+      };
+      registry.getAgent.mockReturnValue(agent);
+      transitionTo.mockReturnValue({ current: 'cancelled' });
+
+      const result = await execute(['cancel', 'agent-123']);
+
+      expect(registry.getAgent).toHaveBeenCalledWith('agent-123');
+      expect(transitionTo).toHaveBeenCalledWith(agent.state, STATES.CANCELLED, expect.any(Object));
+      expect(triggerHook).toHaveBeenCalledWith('onCancel', agent);
+      expect(result.success).toBe(true);
+      expect(result.message).toContain('cancelled');
+    });
+
+    it('shows error for missing agent', async () => {
+      registry.getAgent.mockReturnValue(null);
+
+      const result = await execute(['cancel', 'unknown-id']);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('not found');
+    });
+
+    it('shows error for already completed agent', async () => {
+      const agent = {
+        id: 'agent-123',
+        state: { current: 'completed' },
+      };
+      registry.getAgent.mockReturnValue(agent);
+
+      const result = await execute(['cancel', 'agent-123']);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Cannot cancel');
+    });
+
+    it('requires agent ID', async () => {
+      const result = await execute(['cancel']);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Agent ID required');
+    });
+  });
+
+  describe('execute cleanup', () => {
+    it('runs cleanup and shows stats', async () => {
+      cleanupOrphans.mockResolvedValue({ cleaned: ['agent-1', 'agent-2'], errors: [] });
+      getCleanupStats.mockReturnValue({ totalCleaned: 5, cleanupRuns: 3, lastCleanupAt: new Date() });
+
+      const result = await execute(['cleanup']);
+
+      expect(cleanupOrphans).toHaveBeenCalled();
+      expect(getCleanupStats).toHaveBeenCalled();
+      expect(result.success).toBe(true);
+      expect(result.data.cleaned).toHaveLength(2);
+      expect(result.data.stats.totalCleaned).toBe(5);
+    });
+
+    it('reports cleanup errors', async () => {
+      cleanupOrphans.mockResolvedValue({ cleaned: [], errors: [{ id: 'agent-1', error: 'failed' }] });
+      getCleanupStats.mockReturnValue({ totalCleaned: 0, cleanupRuns: 1 });
+
+      const result = await execute(['cleanup']);
+
+      expect(result.success).toBe(true);
+      expect(result.data.errors).toHaveLength(1);
+    });
+  });
+
+  describe('formatAgentList', () => {
+    it('creates readable table', () => {
+      const agents = [
+        { id: 'agent-123', name: 'task-1', state: { current: 'running' }, metadata: { model: 'claude' }, createdAt: '2025-01-01T00:00:00Z' },
+        { id: 'agent-456', name: 'task-2', state: { current: 'completed' }, metadata: { model: 'gpt-4' }, createdAt: '2025-01-01T00:01:00Z' },
+      ];
+
+      const output = formatAgentList(agents);
+
+      expect(output).toContain('agent-123');
+      expect(output).toContain('running');
+      expect(output).toContain('claude');
+      expect(output).toContain('agent-456');
+      expect(output).toContain('completed');
+    });
+
+    it('handles empty list', () => {
+      const output = formatAgentList([]);
+
+      expect(output).toContain('No agents');
+    });
+
+    it('truncates long names', () => {
+      const agents = [
+        { id: 'agent-123', name: 'this-is-a-very-long-agent-name-that-should-be-truncated', state: { current: 'running' }, metadata: { model: 'claude' } },
+      ];
+
+      const output = formatAgentList(agents);
+
+      expect(output.length).toBeLessThan(agents[0].name.length + 200);
+    });
+  });
+
+  describe('formatAgentDetails', () => {
+    it('shows all agent fields', () => {
+      const agent = {
+        id: 'agent-123',
+        name: 'test-agent',
+        state: { current: 'running', history: [{ state: 'pending', timestamp: '2025-01-01T00:00:00Z' }] },
+        metadata: { model: 'claude', tokens: { input: 100, output: 50 }, cost: 0.0015 },
+        createdAt: '2025-01-01T00:00:00Z',
+      };
+
+      const output = formatAgentDetails(agent);
+
+      expect(output).toContain('agent-123');
+      expect(output).toContain('test-agent');
+      expect(output).toContain('running');
+      expect(output).toContain('claude');
+      expect(output).toContain('100');
+      expect(output).toContain('50');
+    });
+
+    it('shows state history', () => {
+      const agent = {
+        id: 'agent-123',
+        name: 'test',
+        state: {
+          current: 'completed',
+          history: [
+            { state: 'pending', timestamp: '2025-01-01T00:00:00Z' },
+            { state: 'running', timestamp: '2025-01-01T00:00:01Z' },
+            { state: 'completed', timestamp: '2025-01-01T00:00:10Z' },
+          ],
+        },
+        metadata: { model: 'claude' },
+      };
+
+      const output = formatAgentDetails(agent);
+
+      expect(output).toContain('pending');
+      expect(output).toContain('running');
+      expect(output).toContain('completed');
+    });
+  });
+
+  describe('parseArgs', () => {
+    it('parses command', () => {
+      const parsed = parseArgs(['list']);
+      expect(parsed.command).toBe('list');
+    });
+
+    it('parses command with flags', () => {
+      const parsed = parseArgs(['list', '--status', 'running']);
+      expect(parsed.command).toBe('list');
+      expect(parsed.flags.status).toBe('running');
+    });
+
+    it('parses command with positional arg', () => {
+      const parsed = parseArgs(['get', 'agent-123']);
+      expect(parsed.command).toBe('get');
+      expect(parsed.args).toContain('agent-123');
+    });
+
+    it('handles multiple flags', () => {
+      const parsed = parseArgs(['list', '--status', 'running', '--model', 'claude', '--json']);
+      expect(parsed.flags.status).toBe('running');
+      expect(parsed.flags.model).toBe('claude');
+      expect(parsed.flags.json).toBe(true);
+    });
+
+    it('returns help for empty args', () => {
+      const parsed = parseArgs([]);
+      expect(parsed.command).toBe('help');
+    });
+  });
+
+  describe('unknown command', () => {
+    it('shows error for unknown command', async () => {
+      const result = await execute(['unknown']);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Unknown command');
+    });
+  });
+
+  describe('help command', () => {
+    it('shows usage information', async () => {
+      const result = await execute(['help']);
+
+      expect(result.success).toBe(true);
+      expect(result.message).toContain('Usage');
+      expect(result.message).toContain('list');
+      expect(result.message).toContain('get');
+      expect(result.message).toContain('cancel');
+      expect(result.message).toContain('cleanup');
+    });
+  });
+});