tlc-claude-code 1.4.1 → 1.4.2

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

@@ -0,0 +1,303 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  AgentHooks,
+  getAgentHooks,
+  resetHooks,
+  HOOK_TYPES,
+} from './agent-hooks.js';
+
+describe('AgentHooks', () => {
+  let hooks;
+
+  beforeEach(() => {
+    resetHooks();
+    hooks = new AgentHooks();
+  });
+
+  describe('registerHook', () => {
+    it('adds handler to hook type', () => {
+      const handler = vi.fn();
+
+      hooks.registerHook('onStart', handler);
+
+      const handlers = hooks.getHandlers('onStart');
+      expect(handlers).toHaveLength(1);
+      expect(handlers[0]).toBe(handler);
+    });
+
+    it('validates hook type', () => {
+      const handler = vi.fn();
+
+      expect(() => hooks.registerHook('invalidHook', handler)).toThrow();
+    });
+
+    it('returns unregister function', () => {
+      const handler = vi.fn();
+
+      const unregister = hooks.registerHook('onStart', handler);
+
+      expect(typeof unregister).toBe('function');
+    });
+
+    it('allows multiple handlers per hook', () => {
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+      const handler3 = vi.fn();
+
+      hooks.registerHook('onComplete', handler1);
+      hooks.registerHook('onComplete', handler2);
+      hooks.registerHook('onComplete', handler3);
+
+      const handlers = hooks.getHandlers('onComplete');
+      expect(handlers).toHaveLength(3);
+    });
+  });
+
+  describe('triggerHook', () => {
+    it('calls all handlers for hook type', async () => {
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+
+      hooks.registerHook('onStart', handler1);
+      hooks.registerHook('onStart', handler2);
+
+      await hooks.triggerHook('onStart', {});
+
+      expect(handler1).toHaveBeenCalledTimes(1);
+      expect(handler2).toHaveBeenCalledTimes(1);
+    });
+
+    it('passes agent context to handlers', async () => {
+      const handler = vi.fn();
+      const context = {
+        agentId: 'agent-123',
+        taskId: 'task-456',
+        phase: 'build',
+      };
+
+      hooks.registerHook('onStart', handler);
+
+      await hooks.triggerHook('onStart', context);
+
+      expect(handler).toHaveBeenCalledWith(context);
+    });
+
+    it('awaits async handlers', async () => {
+      const order = [];
+      const asyncHandler = vi.fn(async () => {
+        await new Promise(resolve => setTimeout(resolve, 10));
+        order.push('async');
+      });
+      const syncHandler = vi.fn(() => {
+        order.push('sync');
+      });
+
+      hooks.registerHook('onComplete', asyncHandler);
+      hooks.registerHook('onComplete', syncHandler);
+
+      await hooks.triggerHook('onComplete', {});
+
+      expect(asyncHandler).toHaveBeenCalled();
+      expect(syncHandler).toHaveBeenCalled();
+      // Both should complete before triggerHook returns
+      expect(order).toContain('async');
+      expect(order).toContain('sync');
+    });
+
+    it('continues on handler error', async () => {
+      const errorHandler = vi.fn(() => {
+        throw new Error('Handler failed');
+      });
+      const successHandler = vi.fn();
+
+      hooks.registerHook('onError', errorHandler);
+      hooks.registerHook('onError', successHandler);
+
+      // Should not throw
+      await expect(hooks.triggerHook('onError', {})).resolves.not.toThrow();
+
+      // Both should have been called
+      expect(errorHandler).toHaveBeenCalled();
+      expect(successHandler).toHaveBeenCalled();
+    });
+
+    it('returns results from all handlers', async () => {
+      const handler1 = vi.fn(() => 'result1');
+      const handler2 = vi.fn(() => 'result2');
+
+      hooks.registerHook('onComplete', handler1);
+      hooks.registerHook('onComplete', handler2);
+
+      const results = await hooks.triggerHook('onComplete', {});
+
+      expect(results).toHaveLength(2);
+      expect(results).toContain('result1');
+      expect(results).toContain('result2');
+    });
+
+    it('returns empty array for no handlers', async () => {
+      const results = await hooks.triggerHook('onStart', {});
+
+      expect(results).toEqual([]);
+    });
+  });
+
+  describe('removeHook', () => {
+    it('removes specific handler', () => {
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+
+      hooks.registerHook('onStart', handler1);
+      const unregister = hooks.registerHook('onStart', handler2);
+
+      unregister();
+
+      const handlers = hooks.getHandlers('onStart');
+      expect(handlers).toHaveLength(1);
+      expect(handlers[0]).toBe(handler1);
+    });
+
+    it('does not affect other handlers', async () => {
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+      const handler3 = vi.fn();
+
+      hooks.registerHook('onComplete', handler1);
+      const unregister = hooks.registerHook('onComplete', handler2);
+      hooks.registerHook('onComplete', handler3);
+
+      unregister();
+
+      await hooks.triggerHook('onComplete', {});
+
+      expect(handler1).toHaveBeenCalled();
+      expect(handler2).not.toHaveBeenCalled();
+      expect(handler3).toHaveBeenCalled();
+    });
+  });
+
+  describe('clearHooks', () => {
+    it('removes all handlers for a hook type', () => {
+      hooks.registerHook('onStart', vi.fn());
+      hooks.registerHook('onStart', vi.fn());
+      hooks.registerHook('onStart', vi.fn());
+
+      hooks.clearHooks('onStart');
+
+      expect(hooks.getHandlers('onStart')).toHaveLength(0);
+    });
+
+    it('removes all handlers when no type specified', () => {
+      hooks.registerHook('onStart', vi.fn());
+      hooks.registerHook('onComplete', vi.fn());
+      hooks.registerHook('onError', vi.fn());
+      hooks.registerHook('onCancel', vi.fn());
+
+      hooks.clearHooks();
+
+      expect(hooks.getHandlers('onStart')).toHaveLength(0);
+      expect(hooks.getHandlers('onComplete')).toHaveLength(0);
+      expect(hooks.getHandlers('onError')).toHaveLength(0);
+      expect(hooks.getHandlers('onCancel')).toHaveLength(0);
+    });
+  });
+
+  describe('hooks execute in registration order', () => {
+    it('calls handlers in order registered', async () => {
+      const order = [];
+
+      hooks.registerHook('onStart', () => order.push(1));
+      hooks.registerHook('onStart', () => order.push(2));
+      hooks.registerHook('onStart', () => order.push(3));
+
+      await hooks.triggerHook('onStart', {});
+
+      expect(order).toEqual([1, 2, 3]);
+    });
+
+    it('maintains order with async handlers', async () => {
+      const order = [];
+
+      hooks.registerHook('onComplete', async () => {
+        await new Promise(resolve => setTimeout(resolve, 5));
+        order.push(1);
+      });
+      hooks.registerHook('onComplete', () => order.push(2));
+      hooks.registerHook('onComplete', async () => {
+        await new Promise(resolve => setTimeout(resolve, 1));
+        order.push(3);
+      });
+
+      await hooks.triggerHook('onComplete', {});
+
+      // Each handler completes in sequence
+      expect(order).toEqual([1, 2, 3]);
+    });
+  });
+
+  describe('onStart receives task config', () => {
+    it('passes full task config to onStart handlers', async () => {
+      const handler = vi.fn();
+      const taskConfig = {
+        agentId: 'agent-001',
+        taskId: 'task-001',
+        phase: 'build',
+        plan: '01-setup',
+        taskNumber: 1,
+        taskName: 'Initialize project',
+        workingDir: '/project',
+        timeout: 30000,
+      };
+
+      hooks.registerHook('onStart', handler);
+
+      await hooks.triggerHook('onStart', taskConfig);
+
+      expect(handler).toHaveBeenCalledWith(taskConfig);
+      const passedConfig = handler.mock.calls[0][0];
+      expect(passedConfig.agentId).toBe('agent-001');
+      expect(passedConfig.taskName).toBe('Initialize project');
+      expect(passedConfig.timeout).toBe(30000);
+    });
+  });
+
+  describe('HOOK_TYPES constant', () => {
+    it('exports valid hook types', () => {
+      expect(HOOK_TYPES).toContain('onStart');
+      expect(HOOK_TYPES).toContain('onComplete');
+      expect(HOOK_TYPES).toContain('onError');
+      expect(HOOK_TYPES).toContain('onCancel');
+    });
+  });
+
+  describe('singleton pattern', () => {
+    it('returns same instance across calls', () => {
+      const instance1 = getAgentHooks();
+      const instance2 = getAgentHooks();
+
+      expect(instance1).toBe(instance2);
+    });
+
+    it('shares state across imports', () => {
+      const instance1 = getAgentHooks();
+      const handler = vi.fn();
+      instance1.registerHook('onStart', handler);
+
+      const instance2 = getAgentHooks();
+      const handlers = instance2.getHandlers('onStart');
+
+      expect(handlers).toHaveLength(1);
+      expect(handlers[0]).toBe(handler);
+    });
+
+    it('resetHooks clears singleton', () => {
+      const instance1 = getAgentHooks();
+      instance1.registerHook('onStart', vi.fn());
+
+      resetHooks();
+
+      const instance2 = getAgentHooks();
+      expect(instance2.getHandlers('onStart')).toHaveLength(0);
+    });
+  });
+});

package/server/lib/agent-metadata.js

@@ -0,0 +1,179 @@
+/**
+ * Agent Metadata - Tracks execution metadata for agent tasks
+ *
+ * Provides immutable tracking of:
+ * - Model used
+ * - Token counts (input/output)
+ * - Cost calculation
+ * - Duration
+ * - Task type and parameters
+ */
+
+/**
+ * Model pricing per million tokens (USD)
+ * Updated as of early 2026
+ */
+const MODEL_PRICING = {
+  'claude-3-opus': { input: 15, output: 75 },
+  'claude-3-sonnet': { input: 3, output: 15 },
+  'claude-3-haiku': { input: 0.25, output: 1.25 },
+  'claude-3.5-sonnet': { input: 3, output: 15 },
+  'claude-3.5-haiku': { input: 0.25, output: 1.25 },
+  'gpt-4': { input: 30, output: 60 },
+  'gpt-4-turbo': { input: 10, output: 30 },
+  'gpt-3.5-turbo': { input: 0.5, output: 1.5 },
+  'default': { input: 1, output: 3 },
+};
+
+/**
+ * AgentMetadata class - tracks metadata for a single agent task execution
+ */
+class AgentMetadata {
+  /**
+   * Create a new AgentMetadata instance
+   * @param {Object} config - Configuration
+   * @param {string} config.model - Model identifier
+   * @param {string} config.taskType - Type of task being executed
+   * @param {Object} [config.parameters] - Task parameters
+   */
+  constructor(config) {
+    if (!config.model) {
+      throw new Error('model is required');
+    }
+    if (!config.taskType) {
+      throw new Error('taskType is required');
+    }
+
+    this.model = config.model;
+    this.taskType = config.taskType;
+    this.parameters = config.parameters || {};
+    this.inputTokens = config.inputTokens || 0;
+    this.outputTokens = config.outputTokens || 0;
+    this.totalTokens = config.totalTokens || 0;
+    this.cost = config.cost || 0;
+    this.duration = config.duration || null;
+    this.startedAt = config.startedAt || Date.now();
+    this.completedAt = config.completedAt || null;
+    this.frozen = config.frozen || false;
+  }
+
+  /**
+   * Update token counts
+   * @param {Object} tokens - Token counts to add
+   * @param {number} [tokens.input=0] - Input tokens to add
+   * @param {number} [tokens.output=0] - Output tokens to add
+   * @returns {AgentMetadata} This instance for chaining
+   * @throws {Error} If metadata is frozen
+   */
+  updateTokens({ input = 0, output = 0 }) {
+    if (this.frozen) {
+      throw new Error('Cannot update frozen metadata');
+    }
+
+    this.inputTokens += input;
+    this.outputTokens += output;
+    this.totalTokens = this.inputTokens + this.outputTokens;
+
+    return this;
+  }
+
+  /**
+   * Calculate cost based on model pricing
+   * @returns {number} Total cost in USD
+   */
+  calculateCost() {
+    const pricing = MODEL_PRICING[this.model] || MODEL_PRICING['default'];
+
+    const inputCost = (this.inputTokens * pricing.input) / 1_000_000;
+    const outputCost = (this.outputTokens * pricing.output) / 1_000_000;
+
+    this.cost = inputCost + outputCost;
+    return this.cost;
+  }
+
+  /**
+   * Set duration based on elapsed time since start
+   * @returns {AgentMetadata} This instance for chaining
+   * @throws {Error} If metadata is frozen
+   */
+  setDuration() {
+    if (this.frozen) {
+      throw new Error('Cannot update frozen metadata');
+    }
+
+    this.completedAt = Date.now();
+    this.duration = this.completedAt - this.startedAt;
+
+    return this;
+  }
+
+  /**
+   * Freeze the metadata, preventing further updates
+   * Automatically calculates final cost
+   * @returns {AgentMetadata} This instance for chaining
+   */
+  freeze() {
+    this.calculateCost();
+    this.frozen = true;
+    return this;
+  }
+
+  /**
+   * Serialize to plain JSON object
+   * @returns {Object} Plain object representation
+   */
+  toJSON() {
+    return {
+      model: this.model,
+      taskType: this.taskType,
+      parameters: this.parameters,
+      inputTokens: this.inputTokens,
+      outputTokens: this.outputTokens,
+      totalTokens: this.totalTokens,
+      cost: this.cost,
+      duration: this.duration,
+      startedAt: this.startedAt,
+      completedAt: this.completedAt,
+      frozen: this.frozen,
+    };
+  }
+
+  /**
+   * Restore from JSON
+   * @param {Object} json - Serialized metadata
+   * @returns {AgentMetadata} Restored instance
+   */
+  static fromJSON(json) {
+    return new AgentMetadata({
+      model: json.model,
+      taskType: json.taskType,
+      parameters: json.parameters,
+      inputTokens: json.inputTokens,
+      outputTokens: json.outputTokens,
+      totalTokens: json.totalTokens,
+      cost: json.cost,
+      duration: json.duration,
+      startedAt: json.startedAt,
+      completedAt: json.completedAt,
+      frozen: json.frozen,
+    });
+  }
+}
+
+/**
+ * Create a new metadata instance
+ * @param {Object} config - Configuration
+ * @param {string} config.model - Model identifier
+ * @param {string} config.taskType - Type of task being executed
+ * @param {Object} [config.parameters] - Task parameters
+ * @returns {AgentMetadata} New metadata instance
+ */
+function createMetadata(config) {
+  return new AgentMetadata(config);
+}
+
+module.exports = {
+  AgentMetadata,
+  createMetadata,
+  MODEL_PRICING,
+};