claude-flow-novice 1.6.1 → 1.6.3

package/.claude-flow-novice/dist/src/coordination/v2/deadlock/resource-manager.js

@@ -0,0 +1,669 @@
+/**
+ * Agent Coordination V2 - Resource Manager
+ *
+ * Manages resource allocation and deadlock prevention through:
+ * - Resource allocation tracking with <5% overhead
+ * - Circular wait detection (Wait-For-Graph)
+ * - Resource ordering enforcement
+ * - Timeout-based automatic resource release
+ * - Thread-safe concurrent access control
+ *
+ * Performance targets:
+ * - Allocation tracking overhead: <5%
+ * - Lock acquisition: <10ms (p95)
+ * - Deadlock detection: <500ms (p95)
+ *
+ * @module coordination/v2/deadlock/resource-manager
+ */ import { EventEmitter } from 'node:events';
+import { Logger } from '../../../core/logger.js';
+/**
+ * Resource types that can be allocated to agents
+ */ export var ResourceType = /*#__PURE__*/ function(ResourceType) {
+    /** Memory/token budget allocation */ ResourceType["MEMORY"] = "memory";
+    /** File access lock */ ResourceType["FILE"] = "file";
+    /** API rate limit quota */ ResourceType["API_QUOTA"] = "api_quota";
+    /** Database connection */ ResourceType["DATABASE"] = "database";
+    /** Network socket */ ResourceType["NETWORK"] = "network";
+    /** Compute/CPU allocation */ ResourceType["COMPUTE"] = "compute";
+    /** Generic custom resource */ ResourceType["CUSTOM"] = "custom";
+    return ResourceType;
+}({});
+/**
+ * Resource Manager
+ *
+ * Thread-safe resource allocation manager with deadlock prevention.
+ * Tracks resource ownership, detects circular waits, and enforces
+ * resource ordering to prevent deadlocks.
+ *
+ * @example
+ * ```typescript
+ * const manager = new ResourceManager(config);
+ * await manager.initialize();
+ *
+ * // Acquire resource
+ * await manager.acquire('agent-1', 'file:/path/to/file', 10);
+ *
+ * // Release resource
+ * await manager.release('agent-1', 'file:/path/to/file');
+ *
+ * // Check for deadlocks
+ * const cycles = manager.detectCircularWaits();
+ * if (cycles.length > 0) {
+ *   console.log('Deadlock detected:', cycles);
+ * }
+ * ```
+ */ export class ResourceManager extends EventEmitter {
+    logger;
+    config;
+    /** Active resource allocations: resourceId -> allocation */ allocations = new Map();
+    /** Resource wait queues: resourceId -> queue of requests */ waitQueues = new Map();
+    /** Agent resource holdings: agentId -> Set of resourceIds */ agentResources = new Map();
+    /** Wait-for graph edges for deadlock detection */ waitForGraph = new Map();
+    /** Resource ordering for deadlock prevention (resourceId -> order number) */ resourceOrder = new Map();
+    nextOrderNumber = 0;
+    /** Performance tracking */ overheadSamples = [];
+    MAX_SAMPLES = 1000;
+    /** Metrics */ metrics = {
+        totalAllocations: 0,
+        activeAllocations: 0,
+        totalRequests: 0,
+        pendingRequests: 0,
+        deadlocksDetected: 0,
+        timeoutReleases: 0,
+        averageOverheadMs: 0,
+        p95OverheadMs: 0,
+        allocationsByType: new Map()
+    };
+    /** Cleanup timers */ cleanupTimer;
+    deadlockCheckTimer;
+    /** Thread safety lock (using mutex pattern) */ operationLock = Promise.resolve();
+    constructor(config = {}){
+        super();
+        this.logger = new Logger({
+            level: 'info',
+            format: 'text',
+            destination: 'console'
+        }, {
+            namespace: 'ResourceManager'
+        });
+        this.config = {
+            defaultTimeoutMs: config.defaultTimeoutMs ?? 30000,
+            maxResourcesPerAgent: config.maxResourcesPerAgent ?? 100,
+            enableDeadlockDetection: config.enableDeadlockDetection ?? true,
+            deadlockCheckIntervalMs: config.deadlockCheckIntervalMs ?? 5000,
+            enableResourceOrdering: config.enableResourceOrdering ?? true,
+            cleanupIntervalMs: config.cleanupIntervalMs ?? 10000
+        };
+    }
+    /**
+   * Initialize the resource manager
+   */ async initialize() {
+        this.logger.info('Initializing ResourceManager', {
+            config: this.config
+        });
+        // Start cleanup timer
+        this.cleanupTimer = setInterval(()=>{
+            this.cleanup().catch((err)=>{
+                this.logger.error('Cleanup failed', err);
+            });
+        }, this.config.cleanupIntervalMs);
+        // Start deadlock detection timer
+        if (this.config.enableDeadlockDetection) {
+            this.deadlockCheckTimer = setInterval(()=>{
+                this.checkForDeadlocks().catch((err)=>{
+                    this.logger.error('Deadlock check failed', err);
+                });
+            }, this.config.deadlockCheckIntervalMs);
+        }
+        this.emit('initialized');
+    }
+    /**
+   * Shutdown the resource manager
+   */ async shutdown() {
+        this.logger.info('Shutting down ResourceManager');
+        // Clear timers
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+        if (this.deadlockCheckTimer) {
+            clearInterval(this.deadlockCheckTimer);
+            this.deadlockCheckTimer = undefined;
+        }
+        // Release all resources
+        await this.withLock(async ()=>{
+            const allAllocations = Array.from(this.allocations.entries());
+            for (const [resourceId, allocation] of allAllocations){
+                await this.releaseInternal(allocation.holderId, resourceId);
+            }
+            this.allocations.clear();
+            this.waitQueues.clear();
+            this.agentResources.clear();
+            this.waitForGraph.clear();
+        });
+        this.emit('shutdown');
+    }
+    /**
+   * Acquire a resource for an agent
+   *
+   * @param agentId - Agent requesting the resource
+   * @param resourceId - Resource to acquire
+   * @param priority - Request priority (higher = more urgent)
+   * @param timeoutMs - Acquisition timeout (optional, uses default if not specified)
+   * @returns Promise that resolves when resource is acquired
+   * @throws Error if acquisition times out or fails
+   */ async acquire(agentId, resourceId, priority = 0, timeoutMs) {
+        const startTime = performance.now();
+        const timeout = timeoutMs ?? this.config.defaultTimeoutMs;
+        const request = {
+            agentId,
+            resourceId,
+            priority,
+            timestamp: new Date(),
+            enqueuedAt: Date.now(),
+            timeoutMs: timeout
+        };
+        this.metrics.totalRequests++;
+        try {
+            await this.withLock(async ()=>{
+                // Check if agent already holds this resource
+                if (this.allocations.get(resourceId)?.holderId === agentId) {
+                    this.logger.debug('Agent already holds resource', {
+                        agentId,
+                        resourceId
+                    });
+                    return;
+                }
+                // Check resource limits
+                const agentResourceCount = this.agentResources.get(agentId)?.size ?? 0;
+                if (agentResourceCount >= this.config.maxResourcesPerAgent) {
+                    throw new Error(`Agent ${agentId} has reached maximum resource limit (${this.config.maxResourcesPerAgent})`);
+                }
+                // Check resource ordering if enabled
+                if (this.config.enableResourceOrdering) {
+                    this.enforceResourceOrdering(agentId, resourceId);
+                }
+                // Try to allocate immediately
+                if (!this.allocations.has(resourceId)) {
+                    await this.allocateResource(agentId, resourceId, priority);
+                    return;
+                }
+                // Resource is held, add to wait queue
+                await this.addToWaitQueue(request);
+            });
+            // Wait for resource to become available
+            await this.waitForResource(agentId, resourceId, timeout);
+            // Track overhead
+            const overhead = performance.now() - startTime;
+            this.trackOverhead(overhead);
+            this.logger.debug('Resource acquired', {
+                agentId,
+                resourceId,
+                overheadMs: overhead.toFixed(2)
+            });
+        } catch (error) {
+            this.logger.error('Resource acquisition failed', {
+                agentId,
+                resourceId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            throw error;
+        }
+    }
+    /**
+   * Release a resource held by an agent
+   *
+   * @param agentId - Agent releasing the resource
+   * @param resourceId - Resource to release
+   */ async release(agentId, resourceId) {
+        await this.withLock(async ()=>{
+            await this.releaseInternal(agentId, resourceId);
+        });
+    }
+    /**
+   * Release all resources held by an agent
+   *
+   * @param agentId - Agent ID
+   */ async releaseAll(agentId) {
+        await this.withLock(async ()=>{
+            const resources = this.agentResources.get(agentId);
+            if (!resources) {
+                return;
+            }
+            this.logger.info('Releasing all resources for agent', {
+                agentId,
+                resourceCount: resources.size
+            });
+            // Release all resources
+            const releases = Array.from(resources).map((resourceId)=>this.releaseInternal(agentId, resourceId));
+            await Promise.all(releases);
+        });
+    }
+    /**
+   * Get current resource allocations
+   *
+   * @returns Map of resourceId -> allocation
+   */ getAllocations() {
+        return new Map(this.allocations);
+    }
+    /**
+   * Get resources held by a specific agent
+   *
+   * @param agentId - Agent ID
+   * @returns Set of resource IDs held by the agent
+   */ getAgentResources(agentId) {
+        return new Set(this.agentResources.get(agentId) ?? []);
+    }
+    /**
+   * Detect circular waits in the wait-for graph
+   *
+   * @returns Array of detected circular wait cycles
+   */ detectCircularWaits() {
+        const cycles = [];
+        const visited = new Set();
+        const recursionStack = new Set();
+        const path = [];
+        // DFS-based cycle detection
+        const detectCycle = (agentId)=>{
+            visited.add(agentId);
+            recursionStack.add(agentId);
+            path.push(agentId);
+            const edges = this.waitForGraph.get(agentId) ?? [];
+            for (const edge of edges){
+                if (!visited.has(edge.holder)) {
+                    if (detectCycle(edge.holder)) {
+                        return true;
+                    }
+                } else if (recursionStack.has(edge.holder)) {
+                    // Cycle detected
+                    const cycleStartIndex = path.indexOf(edge.holder);
+                    const cycleAgents = path.slice(cycleStartIndex);
+                    const cycleResources = edges.filter((e)=>cycleAgents.includes(e.holder)).map((e)=>e.resourceId);
+                    cycles.push({
+                        agents: cycleAgents,
+                        resources: Array.from(new Set(cycleResources)),
+                        detectedAt: new Date(),
+                        path: [
+                            ...path,
+                            edge.holder
+                        ]
+                    });
+                    return true;
+                }
+            }
+            path.pop();
+            recursionStack.delete(agentId);
+            return false;
+        };
+        // Check all agents
+        const allAgents = Array.from(this.waitForGraph.keys());
+        for (const agentId of allAgents){
+            if (!visited.has(agentId)) {
+                detectCycle(agentId);
+            }
+        }
+        if (cycles.length > 0) {
+            this.metrics.deadlocksDetected += cycles.length;
+            this.logger.warn('Circular wait cycles detected', {
+                count: cycles.length,
+                cycles: cycles.map((c)=>({
+                        agents: c.agents,
+                        resources: c.resources
+                    }))
+            });
+            this.emit('deadlock-detected', {
+                cycles
+            });
+        }
+        return cycles;
+    }
+    /**
+   * Get current metrics
+   *
+   * @returns Current resource manager metrics
+   */ getMetrics() {
+        // Update current state
+        this.metrics.activeAllocations = this.allocations.size;
+        this.metrics.pendingRequests = Array.from(this.waitQueues.values()).reduce((sum, queue)=>sum + queue.length, 0);
+        // Calculate overhead percentiles
+        if (this.overheadSamples.length > 0) {
+            const sorted = [
+                ...this.overheadSamples
+            ].sort((a, b)=>a - b);
+            this.metrics.averageOverheadMs = sorted.reduce((sum, val)=>sum + val, 0) / sorted.length;
+            const p95Index = Math.floor(sorted.length * 0.95);
+            this.metrics.p95OverheadMs = sorted[p95Index] ?? 0;
+        }
+        return {
+            ...this.metrics
+        };
+    }
+    /**
+   * Get health status
+   */ async getHealthStatus() {
+        const metrics = this.getMetrics();
+        const cycles = this.detectCircularWaits();
+        return {
+            healthy: cycles.length === 0,
+            error: cycles.length > 0 ? `${cycles.length} deadlocks detected` : undefined,
+            metrics: {
+                activeAllocations: metrics.activeAllocations,
+                pendingRequests: metrics.pendingRequests,
+                deadlocksDetected: metrics.deadlocksDetected,
+                overheadPercentage: (metrics.averageOverheadMs / 100 * 100).toFixed(2)
+            }
+        };
+    }
+    // ==================== PRIVATE METHODS ====================
+    /**
+   * Thread-safe operation wrapper
+   */ async withLock(operation) {
+        // Chain operations to ensure serial execution
+        const currentLock = this.operationLock;
+        let resolveLock;
+        this.operationLock = new Promise((resolve)=>{
+            resolveLock = resolve;
+        });
+        try {
+            await currentLock;
+            return await operation();
+        } finally{
+            resolveLock();
+        }
+    }
+    /**
+   * Internal resource allocation (assumes lock is held)
+   */ async allocateResource(agentId, resourceId, priority) {
+        // Get or assign resource order
+        if (!this.resourceOrder.has(resourceId)) {
+            this.resourceOrder.set(resourceId, this.nextOrderNumber++);
+        }
+        // Determine resource type from ID
+        const type = this.getResourceType(resourceId);
+        // Create allocation
+        const allocation = {
+            resourceId,
+            type,
+            holderId: agentId,
+            allocatedAt: new Date(),
+            priority
+        };
+        this.allocations.set(resourceId, allocation);
+        // Track agent resources
+        if (!this.agentResources.has(agentId)) {
+            this.agentResources.set(agentId, new Set());
+        }
+        this.agentResources.get(agentId).add(resourceId);
+        // Update metrics
+        this.metrics.totalAllocations++;
+        const currentCount = this.metrics.allocationsByType.get(type) ?? 0;
+        this.metrics.allocationsByType.set(type, currentCount + 1);
+        // Remove from wait graph
+        this.removeFromWaitGraph(agentId, resourceId);
+        this.logger.debug('Resource allocated', {
+            agentId,
+            resourceId,
+            type,
+            priority
+        });
+        this.emit('resource-acquired', {
+            agentId,
+            resourceId,
+            allocation
+        });
+    }
+    /**
+   * Internal resource release (assumes lock is held)
+   */ async releaseInternal(agentId, resourceId) {
+        const allocation = this.allocations.get(resourceId);
+        if (!allocation) {
+            this.logger.debug('Resource not allocated', {
+                agentId,
+                resourceId
+            });
+            return;
+        }
+        if (allocation.holderId !== agentId) {
+            this.logger.warn('Agent does not hold resource', {
+                agentId,
+                resourceId,
+                actualHolder: allocation.holderId
+            });
+            return;
+        }
+        // Remove allocation
+        this.allocations.delete(resourceId);
+        this.agentResources.get(agentId)?.delete(resourceId);
+        // Update metrics
+        const type = allocation.type;
+        const currentCount = this.metrics.allocationsByType.get(type) ?? 0;
+        this.metrics.allocationsByType.set(type, Math.max(0, currentCount - 1));
+        this.logger.debug('Resource released', {
+            agentId,
+            resourceId
+        });
+        this.emit('resource-released', {
+            agentId,
+            resourceId
+        });
+        // Process wait queue
+        await this.processWaitQueue(resourceId);
+    }
+    /**
+   * Add request to wait queue
+   */ async addToWaitQueue(request) {
+        if (!this.waitQueues.has(request.resourceId)) {
+            this.waitQueues.set(request.resourceId, []);
+        }
+        const queue = this.waitQueues.get(request.resourceId);
+        queue.push(request);
+        // Sort by effective priority (base priority + age-based boost)
+        // This prevents starvation: low-priority agents eventually get highest priority
+        this.sortWaitQueue(queue);
+        // Update wait-for graph
+        const allocation = this.allocations.get(request.resourceId);
+        if (allocation) {
+            this.addToWaitGraph(request.agentId, allocation.holderId, request.resourceId);
+        }
+        this.logger.debug('Added to wait queue', {
+            agentId: request.agentId,
+            resourceId: request.resourceId,
+            queueLength: queue.length
+        });
+    }
+    /**
+   * Sort wait queue by effective priority with age-based boost
+   * Prevents starvation by increasing priority as requests age
+   */ sortWaitQueue(queue) {
+        const now = Date.now();
+        queue.sort((a, b)=>{
+            // Calculate age in seconds
+            const ageA = (now - a.enqueuedAt) / 1000;
+            const ageB = (now - b.enqueuedAt) / 1000;
+            // Effective priority = base priority + age boost
+            // Age boost: 1 priority point per second of waiting
+            // This ensures even low-priority agents eventually get served
+            const effectivePriorityA = a.priority + ageA;
+            const effectivePriorityB = b.priority + ageB;
+            return effectivePriorityB - effectivePriorityA;
+        });
+    }
+    /**
+   * Wait for resource to become available
+   */ async waitForResource(agentId, resourceId, timeoutMs) {
+        const startTime = Date.now();
+        return new Promise((resolve, reject)=>{
+            const checkInterval = setInterval(()=>{
+                const allocation = this.allocations.get(resourceId);
+                // Check if we now hold the resource
+                if (allocation?.holderId === agentId) {
+                    clearInterval(checkInterval);
+                    resolve();
+                    return;
+                }
+                // Check if we're still in the queue
+                const queue = this.waitQueues.get(resourceId);
+                const stillWaiting = queue?.some((req)=>req.agentId === agentId);
+                if (!stillWaiting) {
+                    clearInterval(checkInterval);
+                    reject(new Error('Request removed from wait queue'));
+                    return;
+                }
+                // Check timeout
+                if (Date.now() - startTime > timeoutMs) {
+                    clearInterval(checkInterval);
+                    // Remove from queue
+                    const index = queue?.findIndex((req)=>req.agentId === agentId) ?? -1;
+                    if (index !== -1) {
+                        queue?.splice(index, 1);
+                    }
+                    this.removeFromWaitGraph(agentId, resourceId);
+                    reject(new Error(`Resource acquisition timeout: ${resourceId}`));
+                }
+            }, 100);
+        });
+    }
+    /**
+   * Process wait queue for a resource
+   */ async processWaitQueue(resourceId) {
+        const queue = this.waitQueues.get(resourceId);
+        if (!queue || queue.length === 0) {
+            return;
+        }
+        // Re-sort queue to account for aging changes since last sort
+        // This ensures the most deserving agent (considering age) gets the resource
+        this.sortWaitQueue(queue);
+        // Allocate to next in queue (highest effective priority)
+        const nextRequest = queue.shift();
+        await this.allocateResource(nextRequest.agentId, resourceId, nextRequest.priority);
+        // Clean up empty queue
+        if (queue.length === 0) {
+            this.waitQueues.delete(resourceId);
+        }
+    }
+    /**
+   * Enforce resource ordering to prevent circular waits
+   */ enforceResourceOrdering(agentId, resourceId) {
+        const agentResources = this.agentResources.get(agentId);
+        if (!agentResources || agentResources.size === 0) {
+            return;
+        }
+        const requestedOrder = this.resourceOrder.get(resourceId) ?? this.nextOrderNumber;
+        // Check if agent holds any resource with higher order
+        const heldResources = Array.from(agentResources);
+        for (const heldResourceId of heldResources){
+            const heldOrder = this.resourceOrder.get(heldResourceId) ?? 0;
+            if (heldOrder > requestedOrder) {
+                throw new Error(`Resource ordering violation: agent ${agentId} holds ${heldResourceId} (order ${heldOrder}) but requests ${resourceId} (order ${requestedOrder})`);
+            }
+        }
+    }
+    /**
+   * Add edge to wait-for graph
+   */ addToWaitGraph(waiter, holder, resourceId) {
+        if (!this.waitForGraph.has(waiter)) {
+            this.waitForGraph.set(waiter, []);
+        }
+        const edges = this.waitForGraph.get(waiter);
+        const existing = edges.find((e)=>e.holder === holder && e.resourceId === resourceId);
+        if (!existing) {
+            edges.push({
+                waiter,
+                holder,
+                resourceId,
+                waitingSince: new Date()
+            });
+        }
+    }
+    /**
+   * Remove edge from wait-for graph
+   */ removeFromWaitGraph(waiter, resourceId) {
+        const edges = this.waitForGraph.get(waiter);
+        if (!edges) {
+            return;
+        }
+        const filtered = edges.filter((e)=>e.resourceId !== resourceId);
+        if (filtered.length === 0) {
+            this.waitForGraph.delete(waiter);
+        } else {
+            this.waitForGraph.set(waiter, filtered);
+        }
+    }
+    /**
+   * Cleanup expired requests and stale locks
+   */ async cleanup() {
+        await this.withLock(async ()=>{
+            const now = Date.now();
+            // Clean up expired wait queue requests
+            const allQueues = Array.from(this.waitQueues.entries());
+            for (const [resourceId, queue] of allQueues){
+                const filtered = queue.filter((req)=>{
+                    const age = now - req.timestamp.getTime();
+                    if (age > req.timeoutMs) {
+                        this.logger.warn('Removing expired wait request', {
+                            agentId: req.agentId,
+                            resourceId,
+                            ageMs: age
+                        });
+                        this.removeFromWaitGraph(req.agentId, resourceId);
+                        return false;
+                    }
+                    return true;
+                });
+                if (filtered.length === 0) {
+                    this.waitQueues.delete(resourceId);
+                } else {
+                    this.waitQueues.set(resourceId, filtered);
+                }
+            }
+            // Clean up stale locks (held longer than 2x default timeout)
+            const staleThreshold = this.config.defaultTimeoutMs * 2;
+            const allAllocations = Array.from(this.allocations.entries());
+            for (const [resourceId, allocation] of allAllocations){
+                const age = now - allocation.allocatedAt.getTime();
+                if (age > staleThreshold) {
+                    this.logger.warn('Force releasing stale lock', {
+                        resourceId,
+                        agentId: allocation.holderId,
+                        ageMs: age
+                    });
+                    this.metrics.timeoutReleases++;
+                    await this.releaseInternal(allocation.holderId, resourceId);
+                }
+            }
+        });
+    }
+    /**
+   * Periodic deadlock detection
+   */ async checkForDeadlocks() {
+        const cycles = this.detectCircularWaits();
+        if (cycles.length > 0) {
+            this.logger.error('Deadlocks detected during periodic check', {
+                count: cycles.length,
+                cycles
+            });
+        }
+    }
+    /**
+   * Determine resource type from resource ID
+   */ getResourceType(resourceId) {
+        if (resourceId.startsWith('file:')) return "file";
+        if (resourceId.startsWith('memory:')) return "memory";
+        if (resourceId.startsWith('api:')) return "api_quota";
+        if (resourceId.startsWith('db:')) return "database";
+        if (resourceId.startsWith('net:')) return "network";
+        if (resourceId.startsWith('cpu:')) return "compute";
+        return "custom";
+    }
+    /**
+   * Track overhead sample for metrics
+   */ trackOverhead(overheadMs) {
+        this.overheadSamples.push(overheadMs);
+        // Keep only last N samples
+        if (this.overheadSamples.length > this.MAX_SAMPLES) {
+            this.overheadSamples.shift();
+        }
+    }
+}
+
+//# sourceMappingURL=resource-manager.js.map