@sparkleideas/swarm 3.0.0-alpha.7

package/src/domain/repositories/agent-repository.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-repository.interface.js","sourceRoot":"","sources":["agent-repository.interface.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/src/domain/repositories/agent-repository.interface.ts

@@ -0,0 +1,69 @@
+/**
+ * Agent Repository Interface - Domain Layer
+ *
+ * Defines the contract for agent persistence.
+ *
+ * @module v3/swarm/domain/repositories
+ */
+
+import { Agent, AgentStatus, AgentRole } from '../entities/agent.js';
+
+/**
+ * Agent query options
+ */
+export interface AgentQueryOptions {
+  status?: AgentStatus;
+  role?: AgentRole;
+  domain?: string;
+  parentId?: string;
+  capability?: string;
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * Agent statistics
+ */
+export interface AgentStatistics {
+  total: number;
+  byStatus: Record<AgentStatus, number>;
+  byRole: Record<string, number>;
+  byDomain: Record<string, number>;
+  totalTasksCompleted: number;
+  averageUtilization: number;
+}
+
+/**
+ * Agent Repository Interface
+ */
+export interface IAgentRepository {
+  // CRUD
+  save(agent: Agent): Promise<void>;
+  findById(id: string): Promise<Agent | null>;
+  findByName(name: string): Promise<Agent | null>;
+  delete(id: string): Promise<boolean>;
+  exists(id: string): Promise<boolean>;
+
+  // Bulk operations
+  saveMany(agents: Agent[]): Promise<void>;
+  findByIds(ids: string[]): Promise<Agent[]>;
+  deleteMany(ids: string[]): Promise<number>;
+
+  // Query operations
+  findAll(options?: AgentQueryOptions): Promise<Agent[]>;
+  findByStatus(status: AgentStatus): Promise<Agent[]>;
+  findByRole(role: AgentRole): Promise<Agent[]>;
+  findByDomain(domain: string): Promise<Agent[]>;
+  findByParent(parentId: string): Promise<Agent[]>;
+  findByCapability(capability: string): Promise<Agent[]>;
+  findAvailable(): Promise<Agent[]>;
+
+  // Statistics
+  getStatistics(): Promise<AgentStatistics>;
+  count(options?: AgentQueryOptions): Promise<number>;
+
+  // Lifecycle
+  initialize(): Promise<void>;
+  shutdown(): Promise<void>;
+  clear(): Promise<void>;
+}

package/src/domain/repositories/task-repository.interface.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Task Repository Interface - Domain Layer
+ *
+ * Defines the contract for task persistence.
+ *
+ * @module v3/swarm/domain/repositories
+ */
+import { Task, TaskStatus, TaskPriority } from '../entities/task.js';
+/**
+ * Task query options
+ */
+export interface TaskQueryOptions {
+    status?: TaskStatus;
+    priority?: TaskPriority;
+    type?: string;
+    assignedAgentId?: string;
+    limit?: number;
+    offset?: number;
+    orderBy?: 'createdAt' | 'priority' | 'startedAt';
+    orderDirection?: 'asc' | 'desc';
+}
+/**
+ * Task statistics
+ */
+export interface TaskStatistics {
+    total: number;
+    byStatus: Record<TaskStatus, number>;
+    byPriority: Record<TaskPriority, number>;
+    byType: Record<string, number>;
+    averageExecutionTime: number;
+    successRate: number;
+    retryRate: number;
+}
+/**
+ * Task Repository Interface
+ */
+export interface ITaskRepository {
+    save(task: Task): Promise<void>;
+    findById(id: string): Promise<Task | null>;
+    delete(id: string): Promise<boolean>;
+    exists(id: string): Promise<boolean>;
+    saveMany(tasks: Task[]): Promise<void>;
+    findByIds(ids: string[]): Promise<Task[]>;
+    deleteMany(ids: string[]): Promise<number>;
+    findAll(options?: TaskQueryOptions): Promise<Task[]>;
+    findByStatus(status: TaskStatus): Promise<Task[]>;
+    findByPriority(priority: TaskPriority): Promise<Task[]>;
+    findByAgent(agentId: string): Promise<Task[]>;
+    findPending(): Promise<Task[]>;
+    findQueued(): Promise<Task[]>;
+    findRunning(): Promise<Task[]>;
+    findTimedOut(): Promise<Task[]>;
+    getNextTask(agentCapabilities?: string[]): Promise<Task | null>;
+    getTaskQueue(limit?: number): Promise<Task[]>;
+    getStatistics(): Promise<TaskStatistics>;
+    count(options?: TaskQueryOptions): Promise<number>;
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=task-repository.interface.d.ts.map

package/src/domain/repositories/task-repository.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-repository.interface.d.ts","sourceRoot":"","sources":["task-repository.interface.ts"],"names":[],"mappings":"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"}

package/src/domain/repositories/task-repository.interface.js

@@ -0,0 +1,9 @@
+/**
+ * Task Repository Interface - Domain Layer
+ *
+ * Defines the contract for task persistence.
+ *
+ * @module v3/swarm/domain/repositories
+ */
+export {};
+//# sourceMappingURL=task-repository.interface.js.map

package/src/domain/repositories/task-repository.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-repository.interface.js","sourceRoot":"","sources":["task-repository.interface.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/src/domain/repositories/task-repository.interface.ts

@@ -0,0 +1,75 @@
+/**
+ * Task Repository Interface - Domain Layer
+ *
+ * Defines the contract for task persistence.
+ *
+ * @module v3/swarm/domain/repositories
+ */
+
+import { Task, TaskStatus, TaskPriority } from '../entities/task.js';
+
+/**
+ * Task query options
+ */
+export interface TaskQueryOptions {
+  status?: TaskStatus;
+  priority?: TaskPriority;
+  type?: string;
+  assignedAgentId?: string;
+  limit?: number;
+  offset?: number;
+  orderBy?: 'createdAt' | 'priority' | 'startedAt';
+  orderDirection?: 'asc' | 'desc';
+}
+
+/**
+ * Task statistics
+ */
+export interface TaskStatistics {
+  total: number;
+  byStatus: Record<TaskStatus, number>;
+  byPriority: Record<TaskPriority, number>;
+  byType: Record<string, number>;
+  averageExecutionTime: number;
+  successRate: number;
+  retryRate: number;
+}
+
+/**
+ * Task Repository Interface
+ */
+export interface ITaskRepository {
+  // CRUD
+  save(task: Task): Promise<void>;
+  findById(id: string): Promise<Task | null>;
+  delete(id: string): Promise<boolean>;
+  exists(id: string): Promise<boolean>;
+
+  // Bulk operations
+  saveMany(tasks: Task[]): Promise<void>;
+  findByIds(ids: string[]): Promise<Task[]>;
+  deleteMany(ids: string[]): Promise<number>;
+
+  // Query operations
+  findAll(options?: TaskQueryOptions): Promise<Task[]>;
+  findByStatus(status: TaskStatus): Promise<Task[]>;
+  findByPriority(priority: TaskPriority): Promise<Task[]>;
+  findByAgent(agentId: string): Promise<Task[]>;
+  findPending(): Promise<Task[]>;
+  findQueued(): Promise<Task[]>;
+  findRunning(): Promise<Task[]>;
+  findTimedOut(): Promise<Task[]>;
+
+  // Queue operations
+  getNextTask(agentCapabilities?: string[]): Promise<Task | null>;
+  getTaskQueue(limit?: number): Promise<Task[]>;
+
+  // Statistics
+  getStatistics(): Promise<TaskStatistics>;
+  count(options?: TaskQueryOptions): Promise<number>;
+
+  // Lifecycle
+  initialize(): Promise<void>;
+  shutdown(): Promise<void>;
+  clear(): Promise<void>;
+}

package/src/domain/services/coordination-service.ts

@@ -0,0 +1,320 @@
+/**
+ * Coordination Domain Service - Domain Layer
+ *
+ * Contains coordination logic that spans multiple entities.
+ * Handles task assignment, load balancing, and swarm orchestration.
+ *
+ * @module v3/swarm/domain/services
+ */
+
+import { Agent, AgentRole } from '../entities/agent.js';
+import { Task, TaskPriority } from '../entities/task.js';
+import { IAgentRepository } from '../repositories/agent-repository.interface.js';
+import { ITaskRepository } from '../repositories/task-repository.interface.js';
+
+/**
+ * Load balancing strategy
+ */
+export type LoadBalancingStrategy = 'round-robin' | 'least-loaded' | 'capability-match' | 'random';
+
+/**
+ * Task assignment result
+ */
+export interface TaskAssignmentResult {
+  success: boolean;
+  taskId: string;
+  agentId?: string;
+  reason?: string;
+}
+
+/**
+ * Swarm health status
+ */
+export interface SwarmHealth {
+  healthy: boolean;
+  totalAgents: number;
+  activeAgents: number;
+  errorAgents: number;
+  pendingTasks: number;
+  runningTasks: number;
+  queueDepth: number;
+  averageUtilization: number;
+  issues: string[];
+}
+
+/**
+ * Coordination Domain Service
+ *
+ * Provides domain-level coordination operations.
+ */
+export class CoordinationService {
+  constructor(
+    private readonly agentRepository: IAgentRepository,
+    private readonly taskRepository: ITaskRepository
+  ) {}
+
+  /**
+   * Assign a task to the best available agent
+   */
+  async assignTask(
+    taskId: string,
+    strategy: LoadBalancingStrategy = 'capability-match'
+  ): Promise<TaskAssignmentResult> {
+    const task = await this.taskRepository.findById(taskId);
+    if (!task) {
+      return { success: false, taskId, reason: 'Task not found' };
+    }
+
+    // Check dependencies
+    const completedTasks = await this.taskRepository.findByStatus('completed');
+    const completedIds = new Set(completedTasks.map((t) => t.id));
+
+    if (!task.areDependenciesSatisfied(completedIds)) {
+      return { success: false, taskId, reason: 'Dependencies not satisfied' };
+    }
+
+    // Find best agent
+    const agent = await this.findBestAgent(task, strategy);
+    if (!agent) {
+      return { success: false, taskId, reason: 'No available agents' };
+    }
+
+    // Assign task
+    task.assign(agent.id);
+    agent.assignTask(taskId);
+
+    await this.taskRepository.save(task);
+    await this.agentRepository.save(agent);
+
+    return { success: true, taskId, agentId: agent.id };
+  }
+
+  /**
+   * Find the best agent for a task based on strategy
+   */
+  private async findBestAgent(
+    task: Task,
+    strategy: LoadBalancingStrategy
+  ): Promise<Agent | null> {
+    const availableAgents = await this.agentRepository.findAvailable();
+
+    if (availableAgents.length === 0) return null;
+
+    switch (strategy) {
+      case 'round-robin':
+        return this.roundRobinSelection(availableAgents);
+
+      case 'least-loaded':
+        return this.leastLoadedSelection(availableAgents);
+
+      case 'capability-match':
+        return this.capabilityMatchSelection(availableAgents, task);
+
+      case 'random':
+        return availableAgents[Math.floor(Math.random() * availableAgents.length)];
+
+      default:
+        return availableAgents[0];
+    }
+  }
+
+  private roundRobinSelection(agents: Agent[]): Agent {
+    // Sort by last active time and pick least recently used
+    return [...agents].sort(
+      (a, b) => a.lastActiveAt.getTime() - b.lastActiveAt.getTime()
+    )[0];
+  }
+
+  private leastLoadedSelection(agents: Agent[]): Agent {
+    return [...agents].sort((a, b) => a.getUtilization() - b.getUtilization())[0];
+  }
+
+  private capabilityMatchSelection(agents: Agent[], task: Task): Agent | null {
+    // Extract required capabilities from task type and metadata
+    const requiredCapabilities = this.extractRequiredCapabilities(task);
+
+    // Score agents by capability match
+    const scored = agents.map((agent) => {
+      let score = 0;
+      for (const cap of requiredCapabilities) {
+        if (agent.hasCapability(cap)) score++;
+      }
+      // Factor in utilization (prefer less loaded)
+      score -= agent.getUtilization() * 0.5;
+      return { agent, score };
+    });
+
+    scored.sort((a, b) => b.score - a.score);
+
+    // Return best match if any capabilities matched
+    if (scored.length > 0 && scored[0].score > 0) {
+      return scored[0].agent;
+    }
+
+    // Fallback to least loaded
+    return this.leastLoadedSelection(agents);
+  }
+
+  private extractRequiredCapabilities(task: Task): string[] {
+    const capabilities: string[] = [task.type];
+
+    // Map task types to required capabilities
+    const capabilityMap: Record<string, string[]> = {
+      implementation: ['coding', 'testing'],
+      review: ['review', 'analysis'],
+      testing: ['testing', 'qa'],
+      documentation: ['documentation', 'writing'],
+      security: ['security', 'audit'],
+      performance: ['performance', 'optimization'],
+    };
+
+    if (capabilityMap[task.type]) {
+      capabilities.push(...capabilityMap[task.type]);
+    }
+
+    return capabilities;
+  }
+
+  /**
+   * Process completed tasks and release agents
+   */
+  async processTaskCompletion(taskId: string, output?: unknown): Promise<void> {
+    const task = await this.taskRepository.findById(taskId);
+    if (!task || !task.assignedAgentId) return;
+
+    const agent = await this.agentRepository.findById(task.assignedAgentId);
+
+    task.complete(output);
+    await this.taskRepository.save(task);
+
+    if (agent) {
+      agent.completeTask(taskId);
+      await this.agentRepository.save(agent);
+    }
+
+    // Check for dependent tasks that can now be queued
+    await this.queueDependentTasks(taskId);
+  }
+
+  /**
+   * Queue tasks whose dependencies are now satisfied
+   */
+  private async queueDependentTasks(completedTaskId: string): Promise<void> {
+    const pendingTasks = await this.taskRepository.findPending();
+    const completedTasks = await this.taskRepository.findByStatus('completed');
+    const completedIds = new Set(completedTasks.map((t) => t.id));
+
+    for (const task of pendingTasks) {
+      if (
+        task.dependencies.includes(completedTaskId) &&
+        task.areDependenciesSatisfied(completedIds)
+      ) {
+        task.queue();
+        await this.taskRepository.save(task);
+      }
+    }
+  }
+
+  /**
+   * Handle task failure with retry logic
+   */
+  async processTaskFailure(taskId: string, error: string): Promise<boolean> {
+    const task = await this.taskRepository.findById(taskId);
+    if (!task) return false;
+
+    const agentId = task.assignedAgentId;
+
+    task.fail(error);
+    await this.taskRepository.save(task);
+
+    if (agentId) {
+      const agent = await this.agentRepository.findById(agentId);
+      if (agent) {
+        agent.completeTask(taskId);
+        await this.agentRepository.save(agent);
+      }
+    }
+
+    // Return true if task was requeued for retry
+    return task.status === 'queued';
+  }
+
+  /**
+   * Get overall swarm health
+   */
+  async getSwarmHealth(): Promise<SwarmHealth> {
+    const agentStats = await this.agentRepository.getStatistics();
+    const taskStats = await this.taskRepository.getStatistics();
+    const queuedTasks = await this.taskRepository.findQueued();
+
+    const issues: string[] = [];
+
+    // Check for issues
+    if (agentStats.byStatus.error > 0) {
+      issues.push(`${agentStats.byStatus.error} agents in error state`);
+    }
+    if (queuedTasks.length > agentStats.byStatus.active * 10) {
+      issues.push('Task queue backlog detected');
+    }
+    if (agentStats.averageUtilization > 0.9) {
+      issues.push('High agent utilization');
+    }
+
+    const timedOutTasks = await this.taskRepository.findTimedOut();
+    if (timedOutTasks.length > 0) {
+      issues.push(`${timedOutTasks.length} timed out tasks`);
+    }
+
+    return {
+      healthy: issues.length === 0,
+      totalAgents: agentStats.total,
+      activeAgents: agentStats.byStatus.active + agentStats.byStatus.busy,
+      errorAgents: agentStats.byStatus.error,
+      pendingTasks: taskStats.byStatus.pending,
+      runningTasks: taskStats.byStatus.running,
+      queueDepth: queuedTasks.length,
+      averageUtilization: agentStats.averageUtilization,
+      issues,
+    };
+  }
+
+  /**
+   * Scale agents based on workload
+   */
+  async calculateScalingRecommendation(): Promise<{
+    action: 'scale-up' | 'scale-down' | 'none';
+    count: number;
+    reason: string;
+  }> {
+    const health = await this.getSwarmHealth();
+    const queuedTasks = await this.taskRepository.findQueued();
+
+    // Scale up if queue is deep and agents are highly utilized
+    if (queuedTasks.length > 10 && health.averageUtilization > 0.8) {
+      const additionalAgents = Math.ceil(queuedTasks.length / 5);
+      return {
+        action: 'scale-up',
+        count: additionalAgents,
+        reason: 'High queue depth with high agent utilization',
+      };
+    }
+
+    // Scale down if queue is empty and many agents are idle
+    if (queuedTasks.length === 0 && health.averageUtilization < 0.2) {
+      const excessAgents = Math.floor(health.totalAgents * 0.3);
+      if (excessAgents > 0) {
+        return {
+          action: 'scale-down',
+          count: excessAgents,
+          reason: 'Low utilization with empty queue',
+        };
+      }
+    }
+
+    return {
+      action: 'none',
+      count: 0,
+      reason: 'Current scaling is appropriate',
+    };
+  }
+}