@sparkleideas/swarm 3.0.0-alpha.7

package/src/domain/entities/agent.ts

@@ -0,0 +1,370 @@
+/**
+ * Agent Entity - Domain Layer
+ *
+ * Core domain entity representing an AI agent in the swarm.
+ * Implements DDD aggregate root pattern with encapsulated business logic.
+ *
+ * @module v3/swarm/domain/entities
+ */
+
+import { randomUUID } from 'crypto';
+
+/**
+ * Agent status types
+ */
+export type AgentStatus = 'idle' | 'active' | 'busy' | 'paused' | 'terminated' | 'error';
+
+/**
+ * Agent role types - following 15-agent hierarchy
+ */
+export type AgentRole =
+  | 'queen-coordinator'
+  | 'security-architect'
+  | 'security-auditor'
+  | 'memory-specialist'
+  | 'swarm-specialist'
+  | 'integration-architect'
+  | 'performance-engineer'
+  | 'core-architect'
+  | 'test-architect'
+  | 'project-coordinator'
+  | 'coder'
+  | 'reviewer'
+  | 'tester'
+  | 'planner'
+  | 'researcher'
+  | 'custom';
+
+/**
+ * Agent properties
+ */
+export interface AgentProps {
+  id?: string;
+  name: string;
+  role: AgentRole;
+  domain: string;
+  capabilities: string[];
+  status?: AgentStatus;
+  parentId?: string;
+  metadata?: Record<string, unknown>;
+  maxConcurrentTasks?: number;
+  currentTaskIds?: string[];
+  completedTaskCount?: number;
+  createdAt?: Date;
+  updatedAt?: Date;
+  lastActiveAt?: Date;
+}
+
+/**
+ * Agent - Aggregate Root
+ *
+ * Represents an individual agent with lifecycle management,
+ * task tracking, and hierarchical relationships.
+ */
+export class Agent {
+  private _id: string;
+  private _name: string;
+  private _role: AgentRole;
+  private _domain: string;
+  private _capabilities: Set<string>;
+  private _status: AgentStatus;
+  private _parentId?: string;
+  private _metadata: Record<string, unknown>;
+  private _maxConcurrentTasks: number;
+  private _currentTaskIds: Set<string>;
+  private _completedTaskCount: number;
+  private _createdAt: Date;
+  private _updatedAt: Date;
+  private _lastActiveAt: Date;
+
+  private constructor(props: AgentProps) {
+    const now = new Date();
+    this._id = props.id ?? randomUUID();
+    this._name = props.name;
+    this._role = props.role;
+    this._domain = props.domain;
+    this._capabilities = new Set(props.capabilities);
+    this._status = props.status ?? 'idle';
+    this._parentId = props.parentId;
+    this._metadata = props.metadata ?? {};
+    this._maxConcurrentTasks = props.maxConcurrentTasks ?? 3;
+    this._currentTaskIds = new Set(props.currentTaskIds ?? []);
+    this._completedTaskCount = props.completedTaskCount ?? 0;
+    this._createdAt = props.createdAt ?? now;
+    this._updatedAt = props.updatedAt ?? now;
+    this._lastActiveAt = props.lastActiveAt ?? now;
+  }
+
+  /**
+   * Factory method - Create new agent
+   */
+  static create(props: AgentProps): Agent {
+    return new Agent(props);
+  }
+
+  /**
+   * Factory method - Reconstruct from persistence
+   */
+  static fromPersistence(props: AgentProps): Agent {
+    return new Agent(props);
+  }
+
+  // Getters
+  get id(): string {
+    return this._id;
+  }
+
+  get name(): string {
+    return this._name;
+  }
+
+  get role(): AgentRole {
+    return this._role;
+  }
+
+  get domain(): string {
+    return this._domain;
+  }
+
+  get capabilities(): string[] {
+    return Array.from(this._capabilities);
+  }
+
+  get status(): AgentStatus {
+    return this._status;
+  }
+
+  get parentId(): string | undefined {
+    return this._parentId;
+  }
+
+  get metadata(): Record<string, unknown> {
+    return { ...this._metadata };
+  }
+
+  get maxConcurrentTasks(): number {
+    return this._maxConcurrentTasks;
+  }
+
+  get currentTaskIds(): string[] {
+    return Array.from(this._currentTaskIds);
+  }
+
+  get currentTaskCount(): number {
+    return this._currentTaskIds.size;
+  }
+
+  get completedTaskCount(): number {
+    return this._completedTaskCount;
+  }
+
+  get createdAt(): Date {
+    return new Date(this._createdAt);
+  }
+
+  get updatedAt(): Date {
+    return new Date(this._updatedAt);
+  }
+
+  get lastActiveAt(): Date {
+    return new Date(this._lastActiveAt);
+  }
+
+  // ============================================================================
+  // Business Logic Methods
+  // ============================================================================
+
+  /**
+   * Start the agent (transition to active)
+   */
+  start(): void {
+    if (this._status === 'terminated') {
+      throw new Error('Cannot start terminated agent');
+    }
+    this._status = 'active';
+    this._lastActiveAt = new Date();
+    this._updatedAt = new Date();
+  }
+
+  /**
+   * Pause the agent
+   */
+  pause(): void {
+    if (this._status !== 'active' && this._status !== 'busy') {
+      throw new Error('Can only pause active or busy agent');
+    }
+    this._status = 'paused';
+    this._updatedAt = new Date();
+  }
+
+  /**
+   * Resume paused agent
+   */
+  resume(): void {
+    if (this._status !== 'paused') {
+      throw new Error('Can only resume paused agent');
+    }
+    this._status = this._currentTaskIds.size > 0 ? 'busy' : 'active';
+    this._lastActiveAt = new Date();
+    this._updatedAt = new Date();
+  }
+
+  /**
+   * Terminate the agent
+   */
+  terminate(): void {
+    this._status = 'terminated';
+    this._currentTaskIds.clear();
+    this._updatedAt = new Date();
+  }
+
+  /**
+   * Mark agent as having an error
+   */
+  setError(errorMessage?: string): void {
+    this._status = 'error';
+    if (errorMessage) {
+      this._metadata['lastError'] = errorMessage;
+      this._metadata['lastErrorAt'] = new Date().toISOString();
+    }
+    this._updatedAt = new Date();
+  }
+
+  /**
+   * Recover from error state
+   */
+  recover(): void {
+    if (this._status !== 'error') {
+      throw new Error('Can only recover from error state');
+    }
+    this._status = 'idle';
+    delete this._metadata['lastError'];
+    this._updatedAt = new Date();
+  }
+
+  /**
+   * Assign a task to this agent
+   */
+  assignTask(taskId: string): void {
+    if (this._status === 'terminated') {
+      throw new Error('Cannot assign task to terminated agent');
+    }
+    if (this._currentTaskIds.size >= this._maxConcurrentTasks) {
+      throw new Error('Agent at maximum concurrent task capacity');
+    }
+
+    this._currentTaskIds.add(taskId);
+    this._status = 'busy';
+    this._lastActiveAt = new Date();
+    this._updatedAt = new Date();
+  }
+
+  /**
+   * Complete a task
+   */
+  completeTask(taskId: string): void {
+    if (!this._currentTaskIds.has(taskId)) {
+      throw new Error(`Task ${taskId} not assigned to this agent`);
+    }
+
+    this._currentTaskIds.delete(taskId);
+    this._completedTaskCount++;
+
+    if (this._currentTaskIds.size === 0) {
+      this._status = 'active';
+    }
+
+    this._lastActiveAt = new Date();
+    this._updatedAt = new Date();
+  }
+
+  /**
+   * Check if agent can accept more tasks
+   */
+  canAcceptTask(): boolean {
+    return (
+      this._status !== 'terminated' &&
+      this._status !== 'error' &&
+      this._status !== 'paused' &&
+      this._currentTaskIds.size < this._maxConcurrentTasks
+    );
+  }
+
+  /**
+   * Check if agent has a specific capability
+   */
+  hasCapability(capability: string): boolean {
+    return this._capabilities.has(capability);
+  }
+
+  /**
+   * Add a capability
+   */
+  addCapability(capability: string): void {
+    this._capabilities.add(capability);
+    this._updatedAt = new Date();
+  }
+
+  /**
+   * Remove a capability
+   */
+  removeCapability(capability: string): void {
+    this._capabilities.delete(capability);
+    this._updatedAt = new Date();
+  }
+
+  /**
+   * Update metadata
+   */
+  setMetadata(key: string, value: unknown): void {
+    this._metadata[key] = value;
+    this._updatedAt = new Date();
+  }
+
+  /**
+   * Check if agent is a child of given parent
+   */
+  isChildOf(parentId: string): boolean {
+    return this._parentId === parentId;
+  }
+
+  /**
+   * Calculate agent utilization (0-1)
+   */
+  getUtilization(): number {
+    return this._currentTaskIds.size / this._maxConcurrentTasks;
+  }
+
+  /**
+   * Check if agent is available for work
+   */
+  isAvailable(): boolean {
+    return this._status === 'idle' || (this._status === 'active' && this.canAcceptTask());
+  }
+
+  /**
+   * Convert to plain object for persistence
+   */
+  toPersistence(): Record<string, unknown> {
+    return {
+      id: this._id,
+      name: this._name,
+      role: this._role,
+      domain: this._domain,
+      capabilities: Array.from(this._capabilities),
+      status: this._status,
+      parentId: this._parentId,
+      metadata: this._metadata,
+      maxConcurrentTasks: this._maxConcurrentTasks,
+      currentTaskIds: Array.from(this._currentTaskIds),
+      completedTaskCount: this._completedTaskCount,
+      createdAt: this._createdAt.toISOString(),
+      updatedAt: this._updatedAt.toISOString(),
+      lastActiveAt: this._lastActiveAt.toISOString(),
+    };
+  }
+
+  toJSON(): Record<string, unknown> {
+    return this.toPersistence();
+  }
+}

package/src/domain/entities/task.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Task Entity - Domain Layer
+ *
+ * Core domain entity representing a task in the swarm.
+ * Tasks are units of work assigned to agents.
+ *
+ * @module v3/swarm/domain/entities
+ */
+/**
+ * Task status types
+ */
+export type TaskStatus = 'pending' | 'queued' | 'assigned' | 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Task priority levels
+ */
+export type TaskPriority = 'critical' | 'high' | 'normal' | 'low';
+/**
+ * Task properties
+ */
+export interface TaskProps {
+    id?: string;
+    title: string;
+    description: string;
+    type: string;
+    priority?: TaskPriority;
+    status?: TaskStatus;
+    assignedAgentId?: string;
+    dependencies?: string[];
+    metadata?: Record<string, unknown>;
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+    retryCount?: number;
+    maxRetries?: number;
+    timeout?: number;
+    createdAt?: Date;
+    startedAt?: Date;
+    completedAt?: Date;
+}
+/**
+ * Task - Entity
+ *
+ * Represents a unit of work with lifecycle management,
+ * dependency tracking, and result storage.
+ */
+export declare class Task {
+    private _id;
+    private _title;
+    private _description;
+    private _type;
+    private _priority;
+    private _status;
+    private _assignedAgentId?;
+    private _dependencies;
+    private _metadata;
+    private _input?;
+    private _output?;
+    private _error?;
+    private _retryCount;
+    private _maxRetries;
+    private _timeout;
+    private _createdAt;
+    private _startedAt?;
+    private _completedAt?;
+    private constructor();
+    static create(props: TaskProps): Task;
+    static fromPersistence(props: TaskProps): Task;
+    get id(): string;
+    get title(): string;
+    get description(): string;
+    get type(): string;
+    get priority(): TaskPriority;
+    get status(): TaskStatus;
+    get assignedAgentId(): string | undefined;
+    get dependencies(): string[];
+    get metadata(): Record<string, unknown>;
+    get input(): unknown;
+    get output(): unknown;
+    get error(): string | undefined;
+    get retryCount(): number;
+    get maxRetries(): number;
+    get timeout(): number;
+    get createdAt(): Date;
+    get startedAt(): Date | undefined;
+    get completedAt(): Date | undefined;
+    /**
+     * Queue the task for execution
+     */
+    queue(): void;
+    /**
+     * Assign task to an agent
+     */
+    assign(agentId: string): void;
+    /**
+     * Start task execution
+     */
+    start(): void;
+    /**
+     * Complete the task successfully
+     */
+    complete(output?: unknown): void;
+    /**
+     * Mark task as failed
+     */
+    fail(error: string): void;
+    /**
+     * Cancel the task
+     */
+    cancel(): void;
+    /**
+     * Check if all dependencies are satisfied
+     */
+    areDependenciesSatisfied(completedTaskIds: Set<string>): boolean;
+    /**
+     * Check if task can be retried
+     */
+    canRetry(): boolean;
+    /**
+     * Get execution duration in milliseconds
+     */
+    getExecutionDuration(): number | null;
+    /**
+     * Check if task is timed out
+     */
+    isTimedOut(): boolean;
+    /**
+     * Priority comparison (for sorting)
+     */
+    comparePriority(other: Task): number;
+    toPersistence(): Record<string, unknown>;
+    toJSON(): Record<string, unknown>;
+}
+//# sourceMappingURL=task.d.ts.map

package/src/domain/entities/task.d.ts.map

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