@gotza02/seq-thinking 1.1.0

package/src/__tests__/utils.test.ts

@@ -0,0 +1,322 @@
+/**
+ * Utils Test Suite
+ * Tests for utility functions including ID generation, similarity calculations,
+ * statistical functions, formatting, and validation
+ */
+import { test, describe } from 'node:test';
+import assert from 'node:assert';
+import {
+  generateId,
+  clamp,
+  calculateSimilarity,
+  calculateMean,
+  formatDuration,
+} from '../utils/index.js';
+
+describe('generateId', () => {
+  test('should generate unique IDs', () => {
+    const id1 = generateId();
+    const id2 = generateId();
+    assert.notStrictEqual(id1, id2);
+  });
+
+  test('should generate string IDs', () => {
+    const id = generateId();
+    assert.strictEqual(typeof id, 'string');
+  });
+
+  test('should generate non-empty IDs', () => {
+    const id = generateId();
+    assert.ok(id.length > 0);
+  });
+
+  test('should generate IDs with consistent length', () => {
+    const ids = Array.from({ length: 100 }, generateId);
+    const lengths = new Set(ids.map(id => id.length));
+    assert.strictEqual(lengths.size, 1, 'All IDs should have the same length');
+  });
+
+  test('should generate IDs containing only valid characters', () => {
+    const id = generateId();
+    assert.ok(/^[a-zA-Z0-9_-]+$/.test(id), 'ID should contain only alphanumeric, underscore, and hyphen characters');
+  });
+
+  test('should generate many unique IDs without collision', () => {
+    const ids = new Set(Array.from({ length: 1000 }, generateId));
+    assert.strictEqual(ids.size, 1000, 'All 1000 IDs should be unique');
+  });
+});
+
+describe('clamp', () => {
+  test('should return value when within range', () => {
+    assert.strictEqual(clamp(5, 0, 10), 5);
+    assert.strictEqual(clamp(0, 0, 10), 0);
+    assert.strictEqual(clamp(10, 0, 10), 10);
+  });
+
+  test('should clamp to min when below range', () => {
+    assert.strictEqual(clamp(-5, 0, 10), 0);
+    assert.strictEqual(clamp(-100, 0, 10), 0);
+    assert.strictEqual(clamp(-0.1, 0, 10), 0);
+  });
+
+  test('should clamp to max when above range', () => {
+    assert.strictEqual(clamp(15, 0, 10), 10);
+    assert.strictEqual(clamp(100, 0, 10), 10);
+    assert.strictEqual(clamp(10.1, 0, 10), 10);
+  });
+
+  test('should handle negative ranges', () => {
+    assert.strictEqual(clamp(-5, -10, -1), -5);
+    assert.strictEqual(clamp(-15, -10, -1), -10);
+    assert.strictEqual(clamp(0, -10, -1), -1);
+  });
+
+  test('should handle decimal ranges', () => {
+    assert.strictEqual(clamp(0.5, 0, 1), 0.5);
+    assert.strictEqual(clamp(-0.5, 0, 1), 0);
+    assert.strictEqual(clamp(1.5, 0, 1), 1);
+  });
+
+  test('should handle zero range (min equals max)', () => {
+    assert.strictEqual(clamp(5, 5, 5), 5);
+    assert.strictEqual(clamp(0, 5, 5), 5);
+    assert.strictEqual(clamp(10, 5, 5), 5);
+  });
+
+  test('should handle very large numbers', () => {
+    assert.strictEqual(clamp(1e20, 0, 1e18), 1e18);
+    assert.strictEqual(clamp(-1e20, -1e18, 0), -1e18);
+  });
+
+  test('should handle very small numbers', () => {
+    assert.strictEqual(clamp(1e-20, 1e-18, 1), 1e-18);
+    assert.strictEqual(clamp(-1e-20, -1, -1e-18), -1e-18);
+  });
+});
+
+describe('calculateSimilarity', () => {
+  test('should return 1 for identical strings', () => {
+    assert.strictEqual(calculateSimilarity('hello', 'hello'), 1);
+    assert.strictEqual(calculateSimilarity('', ''), 1);
+    assert.strictEqual(calculateSimilarity('The quick brown fox', 'The quick brown fox'), 1);
+  });
+
+  test('should return 0 for completely different strings', () => {
+    assert.strictEqual(calculateSimilarity('abc', 'xyz'), 0);
+    assert.strictEqual(calculateSimilarity('abc', 'def'), 0);
+  });
+
+  test('should return value between 0 and 1 for similar strings', () => {
+    const similarity = calculateSimilarity('hello', 'hallo');
+    assert.ok(similarity > 0 && similarity < 1);
+  });
+
+  test('should be case sensitive', () => {
+    const similarity = calculateSimilarity('Hello', 'hello');
+    assert.ok(similarity < 1, 'Case-sensitive comparison should not return 1');
+  });
+
+  test('should handle empty strings', () => {
+    assert.strictEqual(calculateSimilarity('', ''), 1);
+    assert.strictEqual(calculateSimilarity('', 'hello'), 0);
+    assert.strictEqual(calculateSimilarity('hello', ''), 0);
+  });
+
+  test('should handle whitespace differences', () => {
+    const similarity1 = calculateSimilarity('hello world', 'hello  world');
+    const similarity2 = calculateSimilarity('hello world', 'helloworld');
+    assert.ok(similarity1 > similarity2, 'Extra space should be more similar than no space');
+  });
+
+  test('should handle substring relationships', () => {
+    const similarity = calculateSimilarity('hello world', 'hello');
+    assert.ok(similarity > 0 && similarity < 1);
+  });
+
+  test('should be symmetric', () => {
+    const sim1 = calculateSimilarity('kitten', 'sitting');
+    const sim2 = calculateSimilarity('sitting', 'kitten');
+    assert.strictEqual(sim1, sim2);
+  });
+
+  test('should handle special characters', () => {
+    assert.ok(calculateSimilarity('hello!', 'hello') > 0);
+    assert.ok(calculateSimilarity('hello@#$', 'hello') > 0);
+  });
+
+  test('should handle unicode characters', () => {
+    assert.strictEqual(calculateSimilarity('héllo', 'héllo'), 1);
+    assert.ok(calculateSimilarity('héllo', 'hello') >= 0);
+  });
+
+  test('should handle very long strings', () => {
+    const long1 = 'a'.repeat(10000);
+    const long2 = 'a'.repeat(9999) + 'b';
+    const similarity = calculateSimilarity(long1, long2);
+    assert.ok(similarity > 0.99, 'Very similar long strings should have high similarity');
+  });
+
+  test('should handle common typos', () => {
+    const similarity = calculateSimilarity('accommodation', 'accomodation');
+    assert.ok(similarity > 0.9, 'Common typos should have high similarity');
+  });
+});
+
+describe('calculateMean', () => {
+  test('should calculate mean of positive numbers', () => {
+    assert.strictEqual(calculateMean([1, 2, 3, 4, 5]), 3);
+    assert.strictEqual(calculateMean([10, 20, 30]), 20);
+  });
+
+  test('should calculate mean of negative numbers', () => {
+    assert.strictEqual(calculateMean([-1, -2, -3, -4, -5]), -3);
+    assert.strictEqual(calculateMean([-10, -20, -30]), -20);
+  });
+
+  test('should calculate mean of mixed numbers', () => {
+    assert.strictEqual(calculateMean([-5, 0, 5]), 0);
+    assert.strictEqual(calculateMean([-10, 10]), 0);
+  });
+
+  test('should handle single element array', () => {
+    assert.strictEqual(calculateMean([42]), 42);
+    assert.strictEqual(calculateMean([0]), 0);
+  });
+
+  test('should handle decimal numbers', () => {
+    assert.strictEqual(calculateMean([1.5, 2.5, 3.5]), 2.5);
+    assert.ok(Math.abs(calculateMean([0.1, 0.2, 0.3]) - 0.2) < 0.0001);
+  });
+
+  test('should handle empty array', () => {
+    assert.ok(Number.isNaN(calculateMean([])));
+  });
+
+  test('should handle array with zeros', () => {
+    assert.strictEqual(calculateMean([0, 0, 0]), 0);
+    assert.strictEqual(calculateMean([0, 10, 0]), 10 / 3);
+  });
+
+  test('should handle very large numbers', () => {
+    const result = calculateMean([1e10, 2e10, 3e10]);
+    assert.strictEqual(result, 2e10);
+  });
+
+  test('should handle very small numbers', () => {
+    const result = calculateMean([1e-10, 2e-10, 3e-10]);
+    assert.strictEqual(result, 2e-10);
+  });
+
+  test('should handle large arrays', () => {
+    const largeArray = Array.from({ length: 10000 }, (_, i) => i + 1);
+    const result = calculateMean(largeArray);
+    assert.strictEqual(result, 5000.5);
+  });
+
+  test('should be precise with floating point', () => {
+    // Test for floating point precision issues
+    const result = calculateMean([0.1, 0.2]);
+    assert.ok(Math.abs(result - 0.15) < 0.0001);
+  });
+});
+
+describe('formatDuration', () => {
+  test('should format milliseconds', () => {
+    assert.strictEqual(formatDuration(500), '500ms');
+    assert.strictEqual(formatDuration(0), '0ms');
+    assert.strictEqual(formatDuration(999), '999ms');
+  });
+
+  test('should format seconds', () => {
+    assert.strictEqual(formatDuration(1000), '1s');
+    assert.strictEqual(formatDuration(5000), '5s');
+    assert.strictEqual(formatDuration(59000), '59s');
+  });
+
+  test('should format minutes', () => {
+    assert.strictEqual(formatDuration(60000), '1m');
+    assert.strictEqual(formatDuration(120000), '2m');
+    assert.strictEqual(formatDuration(3540000), '59m');
+  });
+
+  test('should format hours', () => {
+    assert.strictEqual(formatDuration(3600000), '1h');
+    assert.strictEqual(formatDuration(7200000), '2h');
+    assert.strictEqual(formatDuration(86400000), '24h');
+  });
+
+  test('should format days', () => {
+    assert.strictEqual(formatDuration(86400000), '24h');
+    assert.strictEqual(formatDuration(172800000), '48h');
+  });
+
+  test('should handle negative durations', () => {
+    assert.strictEqual(formatDuration(-500), '-500ms');
+    assert.strictEqual(formatDuration(-1000), '-1s');
+  });
+
+  test('should handle decimal milliseconds', () => {
+    assert.strictEqual(formatDuration(500.5), '500ms');
+    assert.strictEqual(formatDuration(1000.9), '1s');
+  });
+
+  test('should handle very large durations', () => {
+    assert.strictEqual(formatDuration(31536000000), '8760h'); // 1 year in hours
+  });
+
+  test('should handle boundary values', () => {
+    assert.strictEqual(formatDuration(59999), '59s');
+    assert.strictEqual(formatDuration(60000), '1m');
+    assert.strictEqual(formatDuration(59999.9), '59s');
+  });
+});
+
+describe('Utility Functions Integration', () => {
+  test('clamp and calculateMean work together', () => {
+    const values = [5, 15, 25, 35, 45];
+    const mean = calculateMean(values);
+    const clampedMean = clamp(mean, 10, 30);
+    assert.ok(clampedMean >= 10 && clampedMean <= 30);
+  });
+
+  test('generateId and calculateSimilarity work together', () => {
+    const id1 = generateId();
+    const id2 = generateId();
+    const similarity = calculateSimilarity(id1, id2);
+    assert.ok(similarity >= 0 && similarity <= 1);
+  });
+
+  test('formatDuration handles processing time from TaskResult', () => {
+    const processingTimes = [100, 500, 1000, 5000, 60000];
+    processingTimes.forEach(time => {
+      const formatted = formatDuration(time);
+      assert.ok(formatted.length > 0);
+      assert.ok(/\d+(ms|s|m|h)/.test(formatted));
+    });
+  });
+});
+
+describe('Edge Cases and Error Conditions', () => {
+  test('clamp with Infinity values', () => {
+    assert.strictEqual(clamp(5, -Infinity, Infinity), 5);
+    assert.strictEqual(clamp(Infinity, 0, 10), 10);
+    assert.strictEqual(clamp(-Infinity, 0, 10), 0);
+  });
+
+  test('calculateMean with Infinity values', () => {
+    assert.strictEqual(calculateMean([1, 2, Infinity]), Infinity);
+    assert.strictEqual(calculateMean([-Infinity, 0, 1]), -Infinity);
+  });
+
+  test('calculateSimilarity with null/undefined should handle gracefully', () => {
+    // These should not throw errors
+    assert.doesNotThrow(() => calculateSimilarity('', ''));
+    assert.doesNotThrow(() => calculateSimilarity('test', 'test'));
+  });
+
+  test('formatDuration with very small values', () => {
+    assert.strictEqual(formatDuration(0.1), '0ms');
+    assert.strictEqual(formatDuration(0.9), '0ms');
+  });
+});

package/src/agents/base-agent.ts

@@ -0,0 +1,285 @@
+/**
+ * Base Agent Class
+ * @module agents/base-agent
+ * @version 1.0.0
+ */
+
+import {
+  AgentType,
+  AgentStatus,
+  type AgentConfig,
+  type AgentCapability,
+  type Task,
+  type TaskResult,
+  type SwarmMessage
+} from '../types/index.js';
+
+/**
+ * Abstract base class for all agents
+ */
+export abstract class BaseAgent {
+  /** Agent ID */
+  readonly id: string;
+  
+  /** Agent configuration */
+  config: AgentConfig;
+  
+  /** Current status */
+  protected status: AgentStatus = AgentStatus.IDLE;
+  
+  /** Current task IDs */
+  protected currentTasks: Set<string> = new Set();
+  
+  /** Performance history */
+  protected performanceHistory: Array<{
+    taskId: string;
+    quality: number;
+    timeMs: number;
+    timestamp: Date;
+  }> = [];
+  
+  /** Message handlers */
+  protected messageHandlers: Array<(message: SwarmMessage) => void | Promise<void>> = [];
+
+  /**
+   * Create a new base agent
+   * @param config - Agent configuration
+   */
+  constructor(config: Partial<AgentConfig> & { name: string }) {
+    this.id = config.id || `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    this.config = {
+      id: this.id,
+      name: config.name,
+      type: config.type || AgentType.UTILITY,
+      subtype: config.subtype,
+      capabilities: config.capabilities || [],
+      maxConcurrentTasks: config.maxConcurrentTasks || 3,
+      confidenceThreshold: config.confidenceThreshold || 0.7,
+      metadata: {
+        createdAt: new Date(),
+        version: '1.0.0',
+        config: config.metadata?.config || {}
+      }
+    };
+  }
+
+  /**
+   * Execute a task
+   * @param task - Task to execute
+   * @returns Task result
+   */
+  async execute(task: Task): Promise<TaskResult> {
+    const startTime = Date.now();
+    this.status = AgentStatus.BUSY;
+    this.currentTasks.add(task.id);
+
+    try {
+      const result = await this.process(task);
+      const processingTime = Date.now() - startTime;
+
+      this.performanceHistory.push({
+        taskId: task.id,
+        quality: result.confidence,
+        timeMs: processingTime,
+        timestamp: new Date()
+      });
+
+      this.currentTasks.delete(task.id);
+      this.status = this.currentTasks.size === 0 ? AgentStatus.IDLE : AgentStatus.BUSY;
+
+      return result;
+    } catch (error) {
+      this.currentTasks.delete(task.id);
+      this.status = this.currentTasks.size === 0 ? AgentStatus.IDLE : AgentStatus.BUSY;
+
+      return {
+        taskId: task.id,
+        agentId: this.id,
+        success: false,
+        output: null,
+        confidence: 0,
+        processingTimeMs: Date.now() - startTime,
+        metadata: {
+          tokensUsed: 0,
+          reasoningSteps: 0,
+          intermediateResults: [],
+          error: error instanceof Error ? error.message : String(error)
+        }
+      };
+    }
+  }
+
+  /**
+   * Process a task (implemented by subclasses)
+   * @param task - Task to process
+   * @returns Task result
+   */
+  abstract process(task: Task): Promise<TaskResult>;
+
+  /**
+   * Register a message handler
+   * @param handler - Message handler function
+   * @returns Unsubscribe function
+   */
+  onMessage(handler: (message: SwarmMessage) => void | Promise<void>): () => void {
+    this.messageHandlers.push(handler);
+    
+    return () => {
+      const index = this.messageHandlers.indexOf(handler);
+      if (index > -1) {
+        this.messageHandlers.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Receive a message
+   * @param message - Message to receive
+   */
+  receiveMessage(message: SwarmMessage): void {
+    for (const handler of this.messageHandlers) {
+      try {
+        const result = handler(message);
+        if (result instanceof Promise) {
+          result.catch(error => {
+            console.error(`Error in message handler for agent ${this.id}:`, error);
+          });
+        }
+      } catch (error) {
+        console.error(`Error in message handler for agent ${this.id}:`, error);
+      }
+    }
+  }
+
+  /**
+   * Get agent status
+   * @returns Current status
+   */
+  getStatus(): AgentStatus {
+    return this.status;
+  }
+
+  /**
+   * Set agent status
+   * @param status - New status
+   */
+  setStatus(status: AgentStatus): void {
+    this.status = status;
+  }
+
+  /**
+   * Get current task IDs
+   * @returns Array of task IDs
+   */
+  getCurrentTasks(): string[] {
+    return Array.from(this.currentTasks);
+  }
+
+  /**
+   * Get performance metrics
+   * @returns Performance metrics
+   */
+  getPerformanceMetrics(): {
+    tasksCompleted: number;
+    averageQuality: number;
+    averageTimeMs: number;
+    successRate: number;
+  } {
+    if (this.performanceHistory.length === 0) {
+      return {
+        tasksCompleted: 0,
+        averageQuality: 0,
+        averageTimeMs: 0,
+        successRate: 0
+      };
+    }
+
+    const completed = this.performanceHistory.length;
+    const avgQuality = this.performanceHistory.reduce((sum, p) => sum + p.quality, 0) / completed;
+    const avgTime = this.performanceHistory.reduce((sum, p) => sum + p.timeMs, 0) / completed;
+    const successRate = this.performanceHistory.filter(p => p.quality > 0.5).length / completed;
+
+    return {
+      tasksCompleted: completed,
+      averageQuality: avgQuality,
+      averageTimeMs: avgTime,
+      successRate
+    };
+  }
+
+  /**
+   * Check if agent has a capability
+   * @param capabilityName - Capability name
+   * @returns True if agent has capability
+   */
+  hasCapability(capabilityName: string): boolean {
+    return this.getCapabilities().some(c => c.name === capabilityName);
+  }
+
+  /**
+   * Get capability confidence
+   * @param capabilityName - Capability name
+   * @returns Confidence level (0-1)
+   */
+  getCapabilityConfidence(capabilityName: string): number {
+    const cap = this.getCapabilities().find(c => c.name === capabilityName);
+    return cap?.confidence || 0;
+  }
+
+  /**
+   * Check if agent can handle a task
+   * @param task - Task to check
+   * @returns True if agent can handle task
+   */
+  canHandleTask(task: Task): boolean {
+    const requiredCaps = task.requirements.requiredCapabilities;
+    return requiredCaps.every(cap => this.hasCapability(cap));
+  }
+
+  /**
+   * Create a task result
+   * @param taskId - Task ID
+   * @param output - Output data
+   * @param confidence - Confidence level
+   * @param processingTimeMs - Processing time in ms
+   * @param metadata - Additional metadata
+   * @returns Task result
+   */
+  protected createTaskResult(
+    taskId: string,
+    output: unknown,
+    confidence: number,
+    processingTimeMs: number,
+    metadata: {
+      tokensUsed?: number;
+      reasoningSteps?: number;
+      intermediateResults?: unknown[];
+    } = {}
+  ): TaskResult {
+    return {
+      taskId,
+      agentId: this.id,
+      success: confidence > 0.5,
+      output,
+      confidence,
+      processingTimeMs,
+      metadata: {
+        tokensUsed: metadata.tokensUsed || 0,
+        reasoningSteps: metadata.reasoningSteps || 1,
+        intermediateResults: metadata.intermediateResults || []
+      }
+    };
+  }
+
+  /**
+   * Get agent type
+   * @returns Agent type
+   */
+  abstract getType(): string;
+
+  /**
+   * Get agent capabilities
+   * @returns Array of capabilities
+   */
+  abstract getCapabilities(): AgentCapability[];
+}