tlc-claude-code 1.4.0 → 1.4.2

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

@@ -0,0 +1,383 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  AgentMetadata,
+  createMetadata,
+  MODEL_PRICING,
+} from './agent-metadata.js';
+
+describe('AgentMetadata', () => {
+  let metadata;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-02-02T12:00:00Z'));
+  });
+
+  describe('createMetadata', () => {
+    it('initializes with model and task', () => {
+      metadata = createMetadata({
+        model: 'claude-3-opus',
+        taskType: 'code-review',
+        parameters: { files: ['test.js'] },
+      });
+
+      expect(metadata.model).toBe('claude-3-opus');
+      expect(metadata.taskType).toBe('code-review');
+      expect(metadata.parameters).toEqual({ files: ['test.js'] });
+    });
+
+    it('sets initial token counts to zero', () => {
+      metadata = createMetadata({
+        model: 'claude-3-opus',
+        taskType: 'analysis',
+      });
+
+      expect(metadata.inputTokens).toBe(0);
+      expect(metadata.outputTokens).toBe(0);
+      expect(metadata.totalTokens).toBe(0);
+    });
+
+    it('records start timestamp', () => {
+      metadata = createMetadata({
+        model: 'claude-3-opus',
+        taskType: 'generation',
+      });
+
+      expect(metadata.startedAt).toBe(new Date('2026-02-02T12:00:00Z').getTime());
+    });
+
+    it('initializes cost to zero', () => {
+      metadata = createMetadata({
+        model: 'claude-3-opus',
+        taskType: 'analysis',
+      });
+
+      expect(metadata.cost).toBe(0);
+    });
+
+    it('sets frozen to false initially', () => {
+      metadata = createMetadata({
+        model: 'claude-3-opus',
+        taskType: 'generation',
+      });
+
+      expect(metadata.frozen).toBe(false);
+    });
+  });
+
+  describe('updateTokens', () => {
+    beforeEach(() => {
+      metadata = createMetadata({
+        model: 'claude-3-opus',
+        taskType: 'analysis',
+      });
+    });
+
+    it('adds input tokens', () => {
+      metadata.updateTokens({ input: 100 });
+
+      expect(metadata.inputTokens).toBe(100);
+    });
+
+    it('adds output tokens', () => {
+      metadata.updateTokens({ output: 50 });
+
+      expect(metadata.outputTokens).toBe(50);
+    });
+
+    it('calculates total tokens', () => {
+      metadata.updateTokens({ input: 100, output: 50 });
+
+      expect(metadata.totalTokens).toBe(150);
+    });
+
+    it('accumulates across multiple updates', () => {
+      metadata.updateTokens({ input: 100, output: 50 });
+      metadata.updateTokens({ input: 200, output: 75 });
+
+      expect(metadata.inputTokens).toBe(300);
+      expect(metadata.outputTokens).toBe(125);
+      expect(metadata.totalTokens).toBe(425);
+    });
+
+    it('returns self for chaining', () => {
+      const result = metadata.updateTokens({ input: 100 });
+
+      expect(result).toBe(metadata);
+    });
+  });
+
+  describe('calculateCost', () => {
+    it('uses model pricing for claude-3-opus', () => {
+      metadata = createMetadata({
+        model: 'claude-3-opus',
+        taskType: 'analysis',
+      });
+      metadata.updateTokens({ input: 1000, output: 500 });
+
+      const cost = metadata.calculateCost();
+
+      // claude-3-opus: $15/1M input, $75/1M output
+      const expectedCost = (1000 * 15 / 1_000_000) + (500 * 75 / 1_000_000);
+      expect(cost).toBeCloseTo(expectedCost, 6);
+      expect(metadata.cost).toBeCloseTo(expectedCost, 6);
+    });
+
+    it('uses model pricing for claude-3-sonnet', () => {
+      metadata = createMetadata({
+        model: 'claude-3-sonnet',
+        taskType: 'analysis',
+      });
+      metadata.updateTokens({ input: 1000, output: 500 });
+
+      const cost = metadata.calculateCost();
+
+      // claude-3-sonnet: $3/1M input, $15/1M output
+      const expectedCost = (1000 * 3 / 1_000_000) + (500 * 15 / 1_000_000);
+      expect(cost).toBeCloseTo(expectedCost, 6);
+    });
+
+    it('uses model pricing for claude-3-haiku', () => {
+      metadata = createMetadata({
+        model: 'claude-3-haiku',
+        taskType: 'analysis',
+      });
+      metadata.updateTokens({ input: 1000, output: 500 });
+
+      const cost = metadata.calculateCost();
+
+      // claude-3-haiku: $0.25/1M input, $1.25/1M output
+      const expectedCost = (1000 * 0.25 / 1_000_000) + (500 * 1.25 / 1_000_000);
+      expect(cost).toBeCloseTo(expectedCost, 6);
+    });
+
+    it('handles unknown models with default pricing', () => {
+      metadata = createMetadata({
+        model: 'unknown-model',
+        taskType: 'analysis',
+      });
+      metadata.updateTokens({ input: 1000, output: 500 });
+
+      const cost = metadata.calculateCost();
+
+      // default: $1/1M input, $3/1M output
+      const expectedCost = (1000 * 1 / 1_000_000) + (500 * 3 / 1_000_000);
+      expect(cost).toBeCloseTo(expectedCost, 6);
+    });
+
+    it('returns zero cost when no tokens', () => {
+      metadata = createMetadata({
+        model: 'claude-3-opus',
+        taskType: 'analysis',
+      });
+
+      const cost = metadata.calculateCost();
+
+      expect(cost).toBe(0);
+    });
+  });
+
+  describe('setDuration', () => {
+    beforeEach(() => {
+      metadata = createMetadata({
+        model: 'claude-3-opus',
+        taskType: 'analysis',
+      });
+    });
+
+    it('records elapsed time in milliseconds', () => {
+      // Advance time by 5 seconds
+      vi.advanceTimersByTime(5000);
+
+      metadata.setDuration();
+
+      expect(metadata.duration).toBe(5000);
+    });
+
+    it('records completion timestamp', () => {
+      vi.advanceTimersByTime(5000);
+
+      metadata.setDuration();
+
+      expect(metadata.completedAt).toBe(new Date('2026-02-02T12:00:05Z').getTime());
+    });
+
+    it('returns self for chaining', () => {
+      const result = metadata.setDuration();
+
+      expect(result).toBe(metadata);
+    });
+  });
+
+  describe('freeze', () => {
+    beforeEach(() => {
+      metadata = createMetadata({
+        model: 'claude-3-opus',
+        taskType: 'analysis',
+      });
+      metadata.updateTokens({ input: 100, output: 50 });
+    });
+
+    it('prevents further token updates', () => {
+      metadata.freeze();
+
+      expect(() => metadata.updateTokens({ input: 100 })).toThrow();
+      expect(metadata.inputTokens).toBe(100);
+    });
+
+    it('prevents setting duration again', () => {
+      metadata.setDuration();
+      metadata.freeze();
+
+      expect(() => metadata.setDuration()).toThrow();
+    });
+
+    it('sets frozen flag to true', () => {
+      metadata.freeze();
+
+      expect(metadata.frozen).toBe(true);
+    });
+
+    it('automatically calculates final cost', () => {
+      metadata.freeze();
+
+      expect(metadata.cost).toBeGreaterThan(0);
+    });
+
+    it('returns self for chaining', () => {
+      const result = metadata.freeze();
+
+      expect(result).toBe(metadata);
+    });
+  });
+
+  describe('toJSON', () => {
+    it('serializes all fields', () => {
+      metadata = createMetadata({
+        model: 'claude-3-opus',
+        taskType: 'code-review',
+        parameters: { files: ['test.js'] },
+      });
+      metadata.updateTokens({ input: 1000, output: 500 });
+      vi.advanceTimersByTime(5000);
+      metadata.setDuration();
+      metadata.freeze();
+
+      const json = metadata.toJSON();
+
+      expect(json).toMatchObject({
+        model: 'claude-3-opus',
+        taskType: 'code-review',
+        parameters: { files: ['test.js'] },
+        inputTokens: 1000,
+        outputTokens: 500,
+        totalTokens: 1500,
+        duration: 5000,
+        frozen: true,
+      });
+      expect(json.startedAt).toBeDefined();
+      expect(json.completedAt).toBeDefined();
+      expect(json.cost).toBeGreaterThan(0);
+    });
+
+    it('returns plain object, not instance', () => {
+      metadata = createMetadata({
+        model: 'claude-3-opus',
+        taskType: 'analysis',
+      });
+
+      const json = metadata.toJSON();
+
+      expect(json).not.toBeInstanceOf(AgentMetadata);
+      expect(typeof json.updateTokens).toBe('undefined');
+    });
+  });
+
+  describe('fromJSON', () => {
+    it('deserializes correctly', () => {
+      const original = createMetadata({
+        model: 'claude-3-opus',
+        taskType: 'code-review',
+        parameters: { files: ['test.js'] },
+      });
+      original.updateTokens({ input: 1000, output: 500 });
+      vi.advanceTimersByTime(5000);
+      original.setDuration();
+      original.freeze();
+
+      const json = original.toJSON();
+      const restored = AgentMetadata.fromJSON(json);
+
+      expect(restored.model).toBe('claude-3-opus');
+      expect(restored.taskType).toBe('code-review');
+      expect(restored.parameters).toEqual({ files: ['test.js'] });
+      expect(restored.inputTokens).toBe(1000);
+      expect(restored.outputTokens).toBe(500);
+      expect(restored.totalTokens).toBe(1500);
+      expect(restored.duration).toBe(5000);
+      expect(restored.frozen).toBe(true);
+    });
+
+    it('restored metadata is immutable if original was frozen', () => {
+      const original = createMetadata({
+        model: 'claude-3-opus',
+        taskType: 'analysis',
+      });
+      original.freeze();
+
+      const restored = AgentMetadata.fromJSON(original.toJSON());
+
+      expect(() => restored.updateTokens({ input: 100 })).toThrow();
+    });
+
+    it('restored metadata is mutable if original was not frozen', () => {
+      const original = createMetadata({
+        model: 'claude-3-opus',
+        taskType: 'analysis',
+      });
+
+      const restored = AgentMetadata.fromJSON(original.toJSON());
+      restored.updateTokens({ input: 100 });
+
+      expect(restored.inputTokens).toBe(100);
+    });
+  });
+
+  describe('validates required fields', () => {
+    it('throws if model is missing', () => {
+      expect(() => createMetadata({
+        taskType: 'analysis',
+      })).toThrow('model is required');
+    });
+
+    it('throws if taskType is missing', () => {
+      expect(() => createMetadata({
+        model: 'claude-3-opus',
+      })).toThrow('taskType is required');
+    });
+
+    it('accepts valid minimal config', () => {
+      expect(() => createMetadata({
+        model: 'claude-3-opus',
+        taskType: 'analysis',
+      })).not.toThrow();
+    });
+  });
+
+  describe('MODEL_PRICING', () => {
+    it('exports pricing constants', () => {
+      expect(MODEL_PRICING).toBeDefined();
+      expect(MODEL_PRICING['claude-3-opus']).toBeDefined();
+      expect(MODEL_PRICING['claude-3-sonnet']).toBeDefined();
+      expect(MODEL_PRICING['claude-3-haiku']).toBeDefined();
+      expect(MODEL_PRICING['default']).toBeDefined();
+    });
+
+    it('has input and output rates for each model', () => {
+      for (const model of Object.keys(MODEL_PRICING)) {
+        expect(MODEL_PRICING[model].input).toBeTypeOf('number');
+        expect(MODEL_PRICING[model].output).toBeTypeOf('number');
+      }
+    });
+  });
+});

package/server/lib/agent-persistence.js

@@ -0,0 +1,191 @@
+/**
+ * Agent Persistence - Save and restore agent state across sessions
+ *
+ * Provides file-based persistence for agent data in the .tlc/agents/ directory.
+ * Uses atomic writes (write to temp file, then rename) to prevent corruption.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Default directory for storing agent files
+ */
+const AGENTS_DIR = '.tlc/agents';
+
+/**
+ * Default max age for cleanup (7 days in milliseconds)
+ */
+const DEFAULT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Get the storage path for an agent
+ * @param {string|null} projectRoot - Project root directory (uses TLC_PROJECT_ROOT env if null)
+ * @param {string} [agentId] - Optional agent ID for specific file path
+ * @returns {string} Full path to agent file or agents directory
+ */
+function getStoragePath(projectRoot, agentId) {
+  const root = projectRoot || process.env.TLC_PROJECT_ROOT || process.cwd();
+  const agentsDir = path.join(root, AGENTS_DIR);
+
+  if (agentId) {
+    return path.join(agentsDir, `${agentId}.json`);
+  }
+
+  return agentsDir;
+}
+
+/**
+ * Ensure the agents directory exists
+ * @param {string} projectRoot - Project root directory
+ */
+function ensureAgentsDir(projectRoot) {
+  const agentsDir = getStoragePath(projectRoot);
+  if (!fs.existsSync(agentsDir)) {
+    fs.mkdirSync(agentsDir, { recursive: true });
+  }
+}
+
+/**
+ * Save agent data to file using atomic write
+ * @param {string} projectRoot - Project root directory
+ * @param {Object} agentData - Agent data to save
+ * @param {string} agentData.id - Agent ID (required)
+ * @param {string} agentData.state - Agent state
+ * @param {Object} agentData.metadata - Agent metadata
+ * @param {number} agentData.createdAt - Creation timestamp
+ * @param {number} agentData.updatedAt - Last update timestamp
+ * @returns {Promise<void>}
+ * @throws {Error} If agent ID is missing
+ */
+async function saveAgent(projectRoot, agentData) {
+  if (!agentData || !agentData.id) {
+    throw new Error('Agent ID is required');
+  }
+
+  ensureAgentsDir(projectRoot);
+
+  const filePath = getStoragePath(projectRoot, agentData.id);
+  const tempPath = `${filePath}.tmp`;
+
+  // Write to temp file first
+  const jsonData = JSON.stringify(agentData, null, 2);
+  fs.writeFileSync(tempPath, jsonData, 'utf8');
+
+  // Atomic rename
+  fs.renameSync(tempPath, filePath);
+}
+
+/**
+ * Load agent data from file
+ * @param {string} projectRoot - Project root directory
+ * @param {string} agentId - Agent ID to load
+ * @returns {Promise<Object|null>} Agent data or null if not found/corrupted
+ */
+async function loadAgent(projectRoot, agentId) {
+  const filePath = getStoragePath(projectRoot, agentId);
+
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    if (!content || content.trim() === '') {
+      return null;
+    }
+    return JSON.parse(content);
+  } catch (err) {
+    // Handle corrupted files gracefully
+    return null;
+  }
+}
+
+/**
+ * Load all saved agents
+ * @param {string} projectRoot - Project root directory
+ * @returns {Promise<Array>} Array of agent data objects
+ */
+async function loadAllAgents(projectRoot) {
+  const agentsDir = getStoragePath(projectRoot);
+
+  if (!fs.existsSync(agentsDir)) {
+    return [];
+  }
+
+  const files = fs.readdirSync(agentsDir);
+  const agents = [];
+
+  for (const file of files) {
+    if (!file.endsWith('.json')) {
+      continue;
+    }
+
+    const agentId = path.basename(file, '.json');
+    const agent = await loadAgent(projectRoot, agentId);
+
+    if (agent) {
+      agents.push(agent);
+    }
+  }
+
+  return agents;
+}
+
+/**
+ * Delete an agent file
+ * @param {string} projectRoot - Project root directory
+ * @param {string} agentId - Agent ID to delete
+ * @returns {Promise<boolean>} True if deleted, false if not found
+ */
+async function deleteAgent(projectRoot, agentId) {
+  const filePath = getStoragePath(projectRoot, agentId);
+
+  if (!fs.existsSync(filePath)) {
+    return false;
+  }
+
+  fs.unlinkSync(filePath);
+  return true;
+}
+
+/**
+ * Clean up old agent files
+ * @param {string} projectRoot - Project root directory
+ * @param {number} [maxAgeMs] - Maximum age in milliseconds (default: 7 days)
+ * @returns {Promise<number>} Number of agents cleaned up
+ */
+async function cleanupOldAgents(projectRoot, maxAgeMs = DEFAULT_MAX_AGE_MS) {
+  const agents = await loadAllAgents(projectRoot);
+  const now = Date.now();
+  let cleaned = 0;
+
+  for (const agent of agents) {
+    // Skip running agents - they might still be active
+    if (agent.state === 'running' || agent.state === 'pending') {
+      continue;
+    }
+
+    // Check age based on updatedAt (or createdAt if updatedAt is missing)
+    const agentTime = agent.updatedAt || agent.createdAt;
+    const age = now - agentTime;
+
+    if (age > maxAgeMs) {
+      await deleteAgent(projectRoot, agent.id);
+      cleaned++;
+    }
+  }
+
+  return cleaned;
+}
+
+module.exports = {
+  saveAgent,
+  loadAgent,
+  loadAllAgents,
+  deleteAgent,
+  getStoragePath,
+  cleanupOldAgents,
+  AGENTS_DIR,
+  DEFAULT_MAX_AGE_MS,
+};