@claude-flow/swarm 3.0.0-alpha.1

package/dist/domain/services/coordination-service.js

@@ -0,0 +1,231 @@
+/**
+ * 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
+ */
+/**
+ * Coordination Domain Service
+ *
+ * Provides domain-level coordination operations.
+ */
+export class CoordinationService {
+    agentRepository;
+    taskRepository;
+    constructor(agentRepository, taskRepository) {
+        this.agentRepository = agentRepository;
+        this.taskRepository = taskRepository;
+    }
+    /**
+     * Assign a task to the best available agent
+     */
+    async assignTask(taskId, strategy = 'capability-match') {
+        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
+     */
+    async findBestAgent(task, strategy) {
+        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];
+        }
+    }
+    roundRobinSelection(agents) {
+        // Sort by last active time and pick least recently used
+        return [...agents].sort((a, b) => a.lastActiveAt.getTime() - b.lastActiveAt.getTime())[0];
+    }
+    leastLoadedSelection(agents) {
+        return [...agents].sort((a, b) => a.getUtilization() - b.getUtilization())[0];
+    }
+    capabilityMatchSelection(agents, task) {
+        // 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);
+    }
+    extractRequiredCapabilities(task) {
+        const capabilities = [task.type];
+        // Map task types to required capabilities
+        const capabilityMap = {
+            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, output) {
+        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
+     */
+    async queueDependentTasks(completedTaskId) {
+        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, error) {
+        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() {
+        const agentStats = await this.agentRepository.getStatistics();
+        const taskStats = await this.taskRepository.getStatistics();
+        const queuedTasks = await this.taskRepository.findQueued();
+        const issues = [];
+        // 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() {
+        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',
+        };
+    }
+}
+//# sourceMappingURL=coordination-service.js.map

package/dist/domain/services/coordination-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordination-service.js","sourceRoot":"","sources":["../../../src/domain/services/coordination-service.ts"],"names":[],"mappings":"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"}

package/dist/federation-hub.d.ts

@@ -0,0 +1,284 @@
+/**
+ * Federation Hub - Ephemeral Agent Coordination
+ *
+ * Provides cross-swarm coordination and ephemeral agent management
+ * for distributed multi-swarm architectures.
+ *
+ * Features:
+ * - Ephemeral agent spawning (short-lived, task-specific)
+ * - Cross-swarm communication and coordination
+ * - Federation protocol for distributed consensus
+ * - Resource allocation and load balancing
+ * - Agent lifecycle management with auto-cleanup
+ *
+ * Performance Targets:
+ * - Agent spawn: <50ms
+ * - Cross-swarm message: <100ms
+ * - Federation sync: <500ms
+ * - Auto-cleanup: Background, non-blocking
+ *
+ * Implements ADR-001: agentic-flow@alpha compatibility
+ * Implements ADR-003: Unified coordination engine
+ *
+ * @module @claude-flow/swarm/federation-hub
+ * @version 3.0.0-alpha.1
+ */
+import { EventEmitter } from 'events';
+export type FederationId = string;
+export type SwarmId = string;
+export type EphemeralAgentId = string;
+export interface FederationConfig {
+    /** Federation identifier */
+    federationId?: FederationId;
+    /** Maximum ephemeral agents per swarm */
+    maxEphemeralAgents?: number;
+    /** Default TTL for ephemeral agents (ms) */
+    defaultTTL?: number;
+    /** Sync interval for federation state (ms) */
+    syncIntervalMs?: number;
+    /** Enable auto-cleanup of expired agents */
+    autoCleanup?: boolean;
+    /** Cleanup check interval (ms) */
+    cleanupIntervalMs?: number;
+    /** Cross-swarm communication timeout (ms) */
+    communicationTimeoutMs?: number;
+    /** Enable federation-wide consensus */
+    enableConsensus?: boolean;
+    /** Consensus quorum percentage */
+    consensusQuorum?: number;
+}
+export interface SwarmRegistration {
+    swarmId: SwarmId;
+    name: string;
+    endpoint?: string;
+    capabilities: string[];
+    maxAgents: number;
+    currentAgents: number;
+    status: 'active' | 'inactive' | 'degraded';
+    registeredAt: Date;
+    lastHeartbeat: Date;
+    metadata?: Record<string, unknown>;
+}
+export interface EphemeralAgent {
+    id: EphemeralAgentId;
+    swarmId: SwarmId;
+    type: string;
+    task: string;
+    status: 'spawning' | 'active' | 'completing' | 'terminated';
+    ttl: number;
+    createdAt: Date;
+    expiresAt: Date;
+    completedAt?: Date;
+    result?: unknown;
+    error?: Error;
+    metadata?: Record<string, unknown>;
+}
+export interface SpawnEphemeralOptions {
+    /** Target swarm (auto-select if not specified) */
+    swarmId?: SwarmId;
+    /** Agent type */
+    type: string;
+    /** Task description */
+    task: string;
+    /** Time-to-live in ms (default from config) */
+    ttl?: number;
+    /** Required capabilities */
+    capabilities?: string[];
+    /** Priority for swarm selection */
+    priority?: 'low' | 'normal' | 'high' | 'critical';
+    /** Wait for completion */
+    waitForCompletion?: boolean;
+    /** Completion timeout (ms) */
+    completionTimeout?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+export interface SpawnResult {
+    agentId: EphemeralAgentId;
+    swarmId: SwarmId;
+    status: 'spawned' | 'queued' | 'failed';
+    estimatedTTL: number;
+    result?: unknown;
+    error?: string;
+}
+export interface FederationMessage {
+    id: string;
+    type: 'broadcast' | 'direct' | 'consensus' | 'heartbeat';
+    sourceSwarmId: SwarmId;
+    targetSwarmId?: SwarmId;
+    payload: unknown;
+    timestamp: Date;
+    ttl?: number;
+}
+export interface ConsensusProposal {
+    id: string;
+    proposerId: SwarmId;
+    type: string;
+    value: unknown;
+    votes: Map<SwarmId, boolean>;
+    status: 'pending' | 'accepted' | 'rejected';
+    createdAt: Date;
+    expiresAt: Date;
+}
+export interface FederationStats {
+    federationId: FederationId;
+    totalSwarms: number;
+    activeSwarms: number;
+    totalEphemeralAgents: number;
+    activeEphemeralAgents: number;
+    completedAgents: number;
+    failedAgents: number;
+    avgAgentLifespanMs: number;
+    messagesExchanged: number;
+    consensusProposals: number;
+    uptime: number;
+}
+export interface FederationEvent {
+    type: FederationEventType;
+    federationId: FederationId;
+    swarmId?: SwarmId;
+    agentId?: EphemeralAgentId;
+    data?: unknown;
+    timestamp: Date;
+}
+export type FederationEventType = 'swarm_joined' | 'swarm_left' | 'swarm_degraded' | 'agent_spawned' | 'agent_completed' | 'agent_failed' | 'agent_expired' | 'message_sent' | 'message_received' | 'consensus_started' | 'consensus_completed' | 'federation_synced';
+export declare class FederationHub extends EventEmitter {
+    private config;
+    private swarms;
+    private ephemeralAgents;
+    private messages;
+    private proposals;
+    private syncInterval?;
+    private cleanupInterval?;
+    private startTime;
+    private stats;
+    /** Index: swarmId -> Set of agentIds */
+    private agentsBySwarm;
+    /** Index: status -> Set of agentIds */
+    private agentsByStatus;
+    constructor(config?: FederationConfig);
+    /**
+     * Add agent to indexes - O(1)
+     */
+    private addAgentToIndexes;
+    /**
+     * Remove agent from indexes - O(1)
+     */
+    private removeAgentFromIndexes;
+    /**
+     * Update agent status in index - O(1)
+     */
+    private updateAgentStatusIndex;
+    /**
+     * Get agents by swarm using index - O(k) where k is agents in swarm
+     */
+    private getAgentIdsBySwarm;
+    /**
+     * Get agents by status using index - O(k) where k is agents with status
+     */
+    private getAgentIdsByStatus;
+    /**
+     * Initialize the federation hub
+     */
+    initialize(): Promise<void>;
+    /**
+     * Shutdown the federation hub
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Register a swarm with the federation
+     */
+    registerSwarm(registration: Omit<SwarmRegistration, 'registeredAt' | 'lastHeartbeat'>): void;
+    /**
+     * Unregister a swarm from the federation
+     */
+    unregisterSwarm(swarmId: SwarmId): boolean;
+    /**
+     * Update swarm heartbeat
+     */
+    heartbeat(swarmId: SwarmId, currentAgents?: number): boolean;
+    /**
+     * Get all registered swarms
+     */
+    getSwarms(): SwarmRegistration[];
+    /**
+     * Get swarm by ID
+     */
+    getSwarm(swarmId: SwarmId): SwarmRegistration | undefined;
+    /**
+     * Spawn an ephemeral agent
+     */
+    spawnEphemeralAgent(options: SpawnEphemeralOptions): Promise<SpawnResult>;
+    /**
+     * Complete an ephemeral agent's task
+     */
+    completeAgent(agentId: EphemeralAgentId, result?: unknown): boolean;
+    /**
+     * Terminate an ephemeral agent
+     */
+    terminateAgent(agentId: EphemeralAgentId, error?: Error): Promise<boolean>;
+    /**
+     * Get ephemeral agent by ID
+     */
+    getAgent(agentId: EphemeralAgentId): EphemeralAgent | undefined;
+    /**
+     * Get all ephemeral agents
+     */
+    getAgents(swarmId?: SwarmId): EphemeralAgent[];
+    /**
+     * Get active ephemeral agents
+     */
+    getActiveAgents(swarmId?: SwarmId): EphemeralAgent[];
+    /**
+     * Send a message to another swarm
+     */
+    sendMessage(sourceSwarmId: SwarmId, targetSwarmId: SwarmId, payload: unknown): Promise<boolean>;
+    /**
+     * Broadcast a message to all swarms
+     */
+    broadcast(sourceSwarmId: SwarmId, payload: unknown): Promise<number>;
+    /**
+     * Get recent messages
+     */
+    getMessages(limit?: number): FederationMessage[];
+    /**
+     * Propose a value for federation-wide consensus
+     */
+    propose(proposerId: SwarmId, type: string, value: unknown, timeoutMs?: number): Promise<ConsensusProposal>;
+    /**
+     * Vote on a proposal
+     */
+    vote(swarmId: SwarmId, proposalId: string, approve: boolean): boolean;
+    /**
+     * Get proposal by ID
+     */
+    getProposal(proposalId: string): ConsensusProposal | undefined;
+    /**
+     * Get all pending proposals
+     */
+    getPendingProposals(): ConsensusProposal[];
+    /**
+     * Get federation statistics
+     */
+    getStats(): FederationStats;
+    private selectOptimalSwarm;
+    private getSwarmAgentCount;
+    private getActiveSwarmCount;
+    private waitForAgentCompletion;
+    private syncFederation;
+    private cleanupExpiredAgents;
+    private emitEvent;
+}
+/**
+ * Create a new Federation Hub instance
+ */
+export declare function createFederationHub(config?: FederationConfig): FederationHub;
+/**
+ * Get or create the default federation hub
+ */
+export declare function getDefaultFederationHub(): FederationHub;
+/**
+ * Reset the default federation hub
+ */
+export declare function resetDefaultFederationHub(): Promise<void>;
+//# sourceMappingURL=federation-hub.d.ts.map

package/dist/federation-hub.d.ts.map

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