@sparkleideas/shared 3.0.0-alpha.7

package/src/types/swarm.types.ts

@@ -0,0 +1,255 @@
+/**
+ * V3 Swarm Types
+ * Modernized type system for swarm coordination
+ */
+
+import type { ISwarmConfig, ISwarmState, SwarmTopology, CoordinationStatus } from '../core/interfaces/coordinator.interface.js';
+import type { IAgent } from '../core/interfaces/agent.interface.js';
+
+/**
+ * Swarm initialization options
+ */
+export interface SwarmInitOptions extends ISwarmConfig {
+  name?: string;
+  description?: string;
+  initialAgents?: string[];
+  warmup?: boolean;
+  warmupTasks?: number;
+}
+
+/**
+ * Swarm initialization result
+ */
+export interface SwarmInitResult {
+  state: ISwarmState;
+  agents: IAgent[];
+  startupTime: number;
+  ready: boolean;
+}
+
+/**
+ * Swarm scaling options
+ */
+export interface SwarmScaleOptions {
+  targetSize: number;
+  agentType?: string;
+  timeout?: number;
+  graceful?: boolean;
+}
+
+/**
+ * Swarm scaling result
+ */
+export interface SwarmScaleResult {
+  previousSize: number;
+  currentSize: number;
+  agentsAdded: string[];
+  agentsRemoved: string[];
+  duration: number;
+  success: boolean;
+}
+
+/**
+ * Swarm coordination message
+ */
+export interface SwarmMessage<T = unknown> {
+  id: string;
+  type: string;
+  source: string;
+  target?: string | 'broadcast';
+  payload: T;
+  timestamp: Date;
+  correlationId?: string;
+  replyTo?: string;
+  ttl?: number;
+}
+
+/**
+ * Swarm consensus request
+ */
+export interface ConsensusRequest<T = unknown> {
+  topic: string;
+  options: T[];
+  requiredVotes: number | 'majority' | 'all';
+  timeout: number;
+  voters?: string[];
+}
+
+/**
+ * Swarm consensus response
+ */
+export interface ConsensusResponse<T = unknown> {
+  topic: string;
+  decision: T | null;
+  votes: Map<string, T>;
+  consensus: boolean;
+  votingDuration: number;
+  participatingAgents: string[];
+}
+
+/**
+ * Distributed lock state
+ */
+export interface DistributedLock {
+  resourceId: string;
+  holderId: string;
+  acquiredAt: Date;
+  expiresAt: Date;
+  renewCount: number;
+}
+
+/**
+ * Lock acquisition result
+ */
+export interface LockAcquisitionResult {
+  acquired: boolean;
+  lock?: DistributedLock;
+  waitTime?: number;
+  error?: Error;
+}
+
+/**
+ * Deadlock detection result
+ */
+export interface DeadlockDetectionResult {
+  detected: boolean;
+  agents: string[];
+  resources: string[];
+  cycle?: string[][];
+  suggestedResolution?: string;
+}
+
+/**
+ * Swarm metrics
+ */
+export interface SwarmMetrics {
+  topology: SwarmTopology;
+  status: CoordinationStatus;
+  agentCount: number;
+  activeAgentCount: number;
+  taskCount: number;
+  completedTasks: number;
+  failedTasks: number;
+  throughput: number;
+  avgLatencyMs: number;
+  p95LatencyMs: number;
+  p99LatencyMs: number;
+  successRate: number;
+  resourceUtilization: number;
+  messagesSent: number;
+  messagesReceived: number;
+  consensusRounds: number;
+  locksAcquired: number;
+  deadlocksDetected: number;
+  uptime: number;
+  timestamp: Date;
+}
+
+/**
+ * Swarm event payloads
+ */
+export interface SwarmEventPayloads {
+  'swarm:initialized': {
+    state: ISwarmState;
+    config: ISwarmConfig;
+  };
+  'swarm:scaled': {
+    result: SwarmScaleResult;
+  };
+  'swarm:topology:changed': {
+    previousTopology: SwarmTopology;
+    currentTopology: SwarmTopology;
+  };
+  'swarm:status:changed': {
+    previousStatus: CoordinationStatus;
+    currentStatus: CoordinationStatus;
+  };
+  'swarm:message:sent': {
+    message: SwarmMessage;
+  };
+  'swarm:message:received': {
+    message: SwarmMessage;
+  };
+  'swarm:consensus:started': {
+    request: ConsensusRequest;
+  };
+  'swarm:consensus:completed': {
+    response: ConsensusResponse;
+  };
+  'swarm:lock:acquired': {
+    lock: DistributedLock;
+  };
+  'swarm:lock:released': {
+    resourceId: string;
+    holderId: string;
+    duration: number;
+  };
+  'swarm:deadlock:detected': {
+    result: DeadlockDetectionResult;
+  };
+  'swarm:shutdown': {
+    reason: string;
+    graceful: boolean;
+  };
+}
+
+/**
+ * Topology configuration presets
+ */
+export const TopologyPresets: Record<SwarmTopology, Partial<ISwarmConfig>> = {
+  hierarchical: {
+    topology: 'hierarchical',
+    coordination: {
+      consensusRequired: false,
+      timeoutMs: 5000,
+      retryPolicy: { maxRetries: 3, backoffMs: 1000 }
+    }
+  },
+  mesh: {
+    topology: 'mesh',
+    coordination: {
+      consensusRequired: true,
+      timeoutMs: 10000,
+      retryPolicy: { maxRetries: 5, backoffMs: 500 }
+    }
+  },
+  ring: {
+    topology: 'ring',
+    coordination: {
+      consensusRequired: true,
+      timeoutMs: 8000,
+      retryPolicy: { maxRetries: 4, backoffMs: 750 }
+    }
+  },
+  star: {
+    topology: 'star',
+    coordination: {
+      consensusRequired: false,
+      timeoutMs: 3000,
+      retryPolicy: { maxRetries: 2, backoffMs: 500 }
+    }
+  },
+  adaptive: {
+    topology: 'adaptive',
+    autoScale: {
+      enabled: true,
+      minAgents: 1,
+      maxAgents: 20,
+      scaleUpThreshold: 0.8,
+      scaleDownThreshold: 0.3
+    },
+    coordination: {
+      consensusRequired: true,
+      timeoutMs: 10000,
+      retryPolicy: { maxRetries: 5, backoffMs: 500 }
+    }
+  },
+  'hierarchical-mesh': {
+    topology: 'hierarchical-mesh',
+    coordination: {
+      consensusRequired: true,
+      timeoutMs: 8000,
+      retryPolicy: { maxRetries: 4, backoffMs: 750 }
+    }
+  }
+};

package/src/types/task.types.ts

@@ -0,0 +1,205 @@
+/**
+ * V3 Task Types
+ * Modernized type system with strict TypeScript
+ */
+
+import type { ITask, ITaskResult, TaskStatus, TaskPriority } from '../core/interfaces/task.interface.js';
+
+/**
+ * Task creation input
+ */
+export interface TaskInput {
+  type: string;
+  description: string;
+  priority?: number | TaskPriority;
+  timeout?: number;
+  assignedAgent?: string;
+  input?: Record<string, unknown>;
+  metadata?: TaskMetadata;
+}
+
+/**
+ * Task metadata for additional context
+ */
+export interface TaskMetadata {
+  requiredCapabilities?: string[];
+  retryCount?: number;
+  maxRetries?: number;
+  critical?: boolean;
+  parentTaskId?: string;
+  childTaskIds?: string[];
+  tags?: string[];
+  deadline?: Date;
+  estimatedDuration?: number;
+  source?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Task execution context
+ */
+export interface TaskExecutionContext {
+  task: ITask;
+  agentId: string;
+  startTime: Date;
+  timeout: number;
+  attempt: number;
+  maxAttempts: number;
+}
+
+/**
+ * Task execution result - extended
+ */
+export interface TaskExecutionResult extends ITaskResult {
+  context: TaskExecutionContext;
+  logs?: string[];
+  artifacts?: TaskArtifact[];
+}
+
+/**
+ * Task artifact - file or data produced by task
+ */
+export interface TaskArtifact {
+  id: string;
+  name: string;
+  type: 'file' | 'data' | 'log' | 'metric';
+  path?: string;
+  data?: unknown;
+  size?: number;
+  createdAt: Date;
+}
+
+/**
+ * Task queue configuration
+ */
+export interface TaskQueueConfig {
+  maxSize: number;
+  priorityLevels: number;
+  defaultTimeout: number;
+  batchSize: number;
+  processingInterval: number;
+}
+
+/**
+ * Task assignment strategy configuration
+ */
+export interface TaskAssignmentConfig {
+  strategy: 'round-robin' | 'least-loaded' | 'capability-match' | 'priority-based' | 'custom';
+  loadBalancing: boolean;
+  stickyAssignment: boolean;
+  capabilityWeight: number;
+  loadWeight: number;
+  priorityWeight: number;
+}
+
+/**
+ * Task retry policy
+ */
+export interface TaskRetryPolicy {
+  maxRetries: number;
+  backoffMs: number;
+  backoffMultiplier: number;
+  maxBackoffMs: number;
+  retryableErrors?: string[];
+  nonRetryableErrors?: string[];
+}
+
+/**
+ * Task filter for queries
+ */
+export interface TaskFilter {
+  status?: TaskStatus | TaskStatus[];
+  type?: string | string[];
+  assignedAgent?: string;
+  priority?: number | { min?: number; max?: number };
+  createdAfter?: Date;
+  createdBefore?: Date;
+  tags?: string[];
+  hasParent?: boolean;
+  parentTaskId?: string;
+}
+
+/**
+ * Task sort options
+ */
+export interface TaskSortOptions {
+  field: 'priority' | 'createdAt' | 'startedAt' | 'completedAt' | 'status';
+  direction: 'asc' | 'desc';
+}
+
+/**
+ * Task query options
+ */
+export interface TaskQueryOptions {
+  filter?: TaskFilter;
+  sort?: TaskSortOptions;
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * Task event payloads
+ */
+export interface TaskEventPayloads {
+  'task:created': {
+    task: ITask;
+  };
+  'task:assigned': {
+    taskId: string;
+    agentId: string;
+  };
+  'task:started': {
+    taskId: string;
+    agentId: string;
+    startTime: Date;
+  };
+  'task:completed': {
+    taskId: string;
+    result: ITaskResult;
+  };
+  'task:failed': {
+    taskId: string;
+    error: Error;
+    retryable: boolean;
+  };
+  'task:cancelled': {
+    taskId: string;
+    reason: string;
+  };
+  'task:timeout': {
+    taskId: string;
+    timeoutMs: number;
+  };
+  'task:retry': {
+    taskId: string;
+    attempt: number;
+    maxAttempts: number;
+    error: Error;
+  };
+}
+
+/**
+ * Priority value conversion
+ */
+export function priorityToNumber(priority: number | TaskPriority): number {
+  if (typeof priority === 'number') {
+    return Math.max(0, Math.min(100, priority));
+  }
+  switch (priority) {
+    case 'critical': return 100;
+    case 'high': return 75;
+    case 'medium': return 50;
+    case 'low': return 25;
+    default: return 50;
+  }
+}
+
+/**
+ * Priority number to label
+ */
+export function numberToPriority(value: number): TaskPriority {
+  if (value >= 90) return 'critical';
+  if (value >= 70) return 'high';
+  if (value >= 40) return 'medium';
+  return 'low';
+}