claude-flow-novice 1.6.1 → 1.6.2

package/.claude-flow-novice/dist/src/coordination/v2/sdk/multi-level-control.js

@@ -0,0 +1,545 @@
+/**
+ * Phase 5 - Sprint 5.2: Multi-Level Agent Control
+ *
+ * Implements pause/inject/resume from Level 0 to any child level:
+ * - Parent can pause any descendant at any level
+ * - Inject commands to paused agents (modify state, update tasks)
+ * - Resume agents from Level 0 supervisor
+ * - Propagate control commands down hierarchy with <100ms latency
+ *
+ * @module coordination/v2/sdk/multi-level-control
+ */ import { EventEmitter } from 'node:events';
+import { Logger } from '../../../core/logger.js';
+import { generateId } from '../../../utils/helpers.js';
+// ============================================================================
+// Types and Interfaces
+// ============================================================================
+/**
+ * Command types that can be injected into paused agents
+ */ export var InjectedCommandType = /*#__PURE__*/ function(InjectedCommandType) {
+    /** Modify agent internal state */ InjectedCommandType["STATE_UPDATE"] = "state_update";
+    /** Assign new task to agent */ InjectedCommandType["TASK_UPDATE"] = "task_update";
+    /** Update agent priority */ InjectedCommandType["PRIORITY_UPDATE"] = "priority_update";
+    /** Modify agent metadata */ InjectedCommandType["METADATA_UPDATE"] = "metadata_update";
+    /** Custom command with arbitrary payload */ InjectedCommandType["CUSTOM"] = "custom";
+    return InjectedCommandType;
+}({});
+// ============================================================================
+// Multi-Level Control Integration Layer
+// ============================================================================
+/**
+ * MultiLevelController - Enables Level 0 to control any descendant
+ *
+ * Integrates QueryController (pause/resume) with HierarchicalCoordinator
+ * (hierarchy management) to provide:
+ * - Pause any agent at any level from Level 0
+ * - Inject commands into paused agents
+ * - Resume agents with injected commands applied
+ * - <100ms latency for control operations
+ */ export class MultiLevelController extends EventEmitter {
+    logger;
+    config;
+    queryController;
+    hierarchicalCoordinator;
+    /** Command injection queue per agent */ commandQueues;
+    /** Agent level cache for fast lookups */ agentLevelCache;
+    /** Control operation metrics */ metrics;
+    constructor(queryController, config = {}){
+        super();
+        this.logger = new Logger({
+            level: 'info',
+            format: 'text',
+            destination: 'console'
+        });
+        this.config = {
+            maxControlLatencyMs: 100,
+            enableCommandQueue: true,
+            maxQueuedCommands: 50,
+            enableLogging: config.enableLogging ?? true,
+            ...config
+        };
+        this.queryController = queryController;
+        this.commandQueues = new Map();
+        this.agentLevelCache = new Map();
+        this.metrics = this.initializeMetrics();
+        this.logger.info('MultiLevelController initialized', {
+            maxControlLatencyMs: this.config.maxControlLatencyMs,
+            enableCommandQueue: this.config.enableCommandQueue
+        });
+    }
+    /**
+   * Register hierarchical coordinator for level tracking
+   */ registerHierarchicalCoordinator(coordinator) {
+        this.hierarchicalCoordinator = coordinator;
+        // Build agent level cache from hierarchy
+        if (coordinator && typeof coordinator.getHierarchyStructure === 'function') {
+            const hierarchy = coordinator.getHierarchyStructure();
+            for (const agent of hierarchy.agents){
+                this.agentLevelCache.set(agent.id, agent.level);
+            }
+            this.logger.info('Hierarchical coordinator registered', {
+                totalAgents: hierarchy.agents.length,
+                hierarchyDepth: hierarchy.depth
+            });
+        }
+    }
+    /**
+   * Update agent level cache when hierarchy changes
+   */ updateAgentLevel(agentId, level) {
+        this.agentLevelCache.set(agentId, level);
+    }
+    /**
+   * Get agent hierarchy level (cached)
+   */ getAgentLevel(agentId) {
+        // Try cache first
+        const cachedLevel = this.agentLevelCache.get(agentId);
+        if (cachedLevel !== undefined) {
+            return cachedLevel;
+        }
+        // Fallback to hierarchical coordinator lookup
+        if (this.hierarchicalCoordinator) {
+            const agentStatus = this.hierarchicalCoordinator.getAgentStatus(agentId);
+            if (agentStatus) {
+                this.agentLevelCache.set(agentId, agentStatus.level);
+                return agentStatus.level;
+            }
+        }
+        // Default to Level 0 if not found
+        return 0;
+    }
+    // ============================================================================
+    // Multi-Level Control Operations (Level 0 → Level N)
+    // ============================================================================
+    /**
+   * Pause agent at any level from Level 0 parent
+   *
+   * @param parentAgentId - Parent issuing the pause (Level 0 supervisor)
+   * @param targetAgentId - Child agent to pause (any level)
+   * @param reason - Reason for pause
+   * @returns Control operation result
+   */ async pauseChildAgent(parentAgentId, targetAgentId, reason) {
+        const startTime = Date.now();
+        try {
+            const targetLevel = this.getAgentLevel(targetAgentId);
+            // Use QueryController to pause agent
+            await this.queryController.pauseAgent(targetAgentId, reason ?? `Paused by parent ${parentAgentId}`);
+            const latencyMs = Date.now() - startTime;
+            // Update metrics
+            this.updateControlMetrics(latencyMs);
+            this.metrics.totalPauses++;
+            const result = {
+                operation: 'pause',
+                success: true,
+                agentId: targetAgentId,
+                level: targetLevel,
+                latencyMs,
+                data: {
+                    parentAgentId,
+                    reason
+                }
+            };
+            if (this.config.enableLogging) {
+                this.logger.info('Agent paused from parent', {
+                    parentAgentId,
+                    targetAgentId,
+                    level: targetLevel,
+                    latencyMs
+                });
+            }
+            this.emit('agent:paused', result);
+            return result;
+        } catch (error) {
+            const latencyMs = Date.now() - startTime;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.error('Failed to pause child agent', {
+                parentAgentId,
+                targetAgentId,
+                error: errorMessage
+            });
+            return {
+                operation: 'pause',
+                success: false,
+                agentId: targetAgentId,
+                level: this.getAgentLevel(targetAgentId),
+                latencyMs,
+                error: errorMessage
+            };
+        }
+    }
+    /**
+   * Inject command into paused agent at any level
+   *
+   * Commands are queued and applied when agent resumes.
+   * This allows parents to modify child state, assign tasks, update priorities.
+   *
+   * @param parentAgentId - Parent issuing the command
+   * @param targetAgentId - Child agent to receive command
+   * @param commandType - Type of command to inject
+   * @param payload - Command payload
+   * @param immediate - Execute immediately vs queue for resume
+   * @returns Injection result
+   */ async injectCommand(parentAgentId, targetAgentId, commandType, payload, immediate = false) {
+        const startTime = Date.now();
+        try {
+            const targetLevel = this.getAgentLevel(targetAgentId);
+            // Verify agent is paused
+            const session = await this.queryController.getAgentSession(targetAgentId);
+            if (!session.isPaused && !immediate) {
+                throw new Error(`Agent ${targetAgentId} must be paused before command injection`);
+            }
+            // Create injected command
+            const command = {
+                id: generateId('cmd'),
+                type: commandType,
+                payload,
+                issuedBy: parentAgentId,
+                targetAgentId,
+                targetLevel,
+                timestamp: new Date(),
+                immediate
+            };
+            // Queue command for agent
+            if (this.config.enableCommandQueue) {
+                this.queueCommand(targetAgentId, command);
+            }
+            // Apply command to agent session metadata
+            await this.applyCommandToSession(session, command);
+            const latencyMs = Date.now() - startTime;
+            // Update metrics
+            this.updateControlMetrics(latencyMs);
+            this.metrics.totalInjections++;
+            const result = {
+                success: true,
+                commandId: command.id,
+                agentId: targetAgentId,
+                level: targetLevel,
+                latencyMs
+            };
+            if (this.config.enableLogging) {
+                this.logger.info('Command injected', {
+                    commandId: command.id,
+                    commandType,
+                    parentAgentId,
+                    targetAgentId,
+                    level: targetLevel,
+                    latencyMs,
+                    immediate
+                });
+            }
+            this.emit('command:injected', {
+                command,
+                result
+            });
+            return result;
+        } catch (error) {
+            const latencyMs = Date.now() - startTime;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.error('Failed to inject command', {
+                parentAgentId,
+                targetAgentId,
+                commandType,
+                error: errorMessage
+            });
+            return {
+                success: false,
+                commandId: '',
+                agentId: targetAgentId,
+                level: this.getAgentLevel(targetAgentId),
+                latencyMs,
+                error: errorMessage
+            };
+        }
+    }
+    /**
+   * Resume agent from Level 0 parent
+   *
+   * Applies all queued commands and resumes agent execution.
+   *
+   * @param parentAgentId - Parent issuing the resume
+   * @param targetAgentId - Child agent to resume
+   * @param checkpointId - Optional checkpoint to resume from
+   * @returns Control operation result
+   */ async resumeChildAgent(parentAgentId, targetAgentId, checkpointId) {
+        const startTime = Date.now();
+        try {
+            const targetLevel = this.getAgentLevel(targetAgentId);
+            // Apply queued commands before resume
+            const queuedCommands = this.getQueuedCommands(targetAgentId);
+            if (queuedCommands.length > 0) {
+                const session = await this.queryController.getAgentSession(targetAgentId);
+                for (const command of queuedCommands){
+                    await this.applyCommandToSession(session, command);
+                }
+                // Clear command queue
+                this.clearCommandQueue(targetAgentId);
+                if (this.config.enableLogging) {
+                    this.logger.debug('Applied queued commands before resume', {
+                        agentId: targetAgentId,
+                        commandCount: queuedCommands.length
+                    });
+                }
+            }
+            // Resume agent via QueryController
+            await this.queryController.resumeAgent(targetAgentId, checkpointId);
+            const latencyMs = Date.now() - startTime;
+            // Update metrics
+            this.updateControlMetrics(latencyMs);
+            this.metrics.totalResumes++;
+            const result = {
+                operation: 'resume',
+                success: true,
+                agentId: targetAgentId,
+                level: targetLevel,
+                latencyMs,
+                data: {
+                    parentAgentId,
+                    checkpointId,
+                    appliedCommands: queuedCommands.length
+                }
+            };
+            if (this.config.enableLogging) {
+                this.logger.info('Agent resumed from parent', {
+                    parentAgentId,
+                    targetAgentId,
+                    level: targetLevel,
+                    latencyMs,
+                    appliedCommands: queuedCommands.length
+                });
+            }
+            this.emit('agent:resumed', result);
+            return result;
+        } catch (error) {
+            const latencyMs = Date.now() - startTime;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.error('Failed to resume child agent', {
+                parentAgentId,
+                targetAgentId,
+                error: errorMessage
+            });
+            return {
+                operation: 'resume',
+                success: false,
+                agentId: targetAgentId,
+                level: this.getAgentLevel(targetAgentId),
+                latencyMs,
+                error: errorMessage
+            };
+        }
+    }
+    /**
+   * Cascade control operation to all descendants
+   *
+   * Propagates pause/resume down the hierarchy tree.
+   *
+   * @param parentAgentId - Root parent issuing cascade
+   * @param operation - Operation to cascade
+   * @returns Array of control operation results
+   */ async cascadeControlOperation(parentAgentId, operation) {
+        const results = [];
+        if (!this.hierarchicalCoordinator) {
+            this.logger.warn('Cannot cascade without hierarchical coordinator');
+            return results;
+        }
+        const parentAgent = this.hierarchicalCoordinator.getAgentStatus(parentAgentId);
+        if (!parentAgent) {
+            this.logger.warn('Parent agent not found in hierarchy', {
+                parentAgentId
+            });
+            return results;
+        }
+        // Get all descendants (DFS traversal)
+        const descendants = await this.getAllDescendants(parentAgentId);
+        if (this.config.enableLogging) {
+            this.logger.info('Cascading control operation', {
+                parentAgentId,
+                operation,
+                descendantCount: descendants.length
+            });
+        }
+        // Apply operation to all descendants in parallel
+        const operations = descendants.map(async (descendantId)=>{
+            if (operation === 'pause') {
+                return await this.pauseChildAgent(parentAgentId, descendantId, `Cascaded from ${parentAgentId}`);
+            } else {
+                return await this.resumeChildAgent(parentAgentId, descendantId);
+            }
+        });
+        results.push(...await Promise.all(operations));
+        this.emit('control:cascaded', {
+            parentAgentId,
+            operation,
+            results
+        });
+        return results;
+    }
+    // ============================================================================
+    // Command Queue Management
+    // ============================================================================
+    /**
+   * Queue command for paused agent
+   */ queueCommand(agentId, command) {
+        let queue = this.commandQueues.get(agentId);
+        if (!queue) {
+            queue = [];
+            this.commandQueues.set(agentId, queue);
+        }
+        // Enforce max queue size
+        if (queue.length >= this.config.maxQueuedCommands) {
+            this.logger.warn('Command queue full, removing oldest command', {
+                agentId,
+                maxQueueSize: this.config.maxQueuedCommands
+            });
+            queue.shift();
+        }
+        queue.push(command);
+    }
+    /**
+   * Get queued commands for agent
+   */ getQueuedCommands(agentId) {
+        return this.commandQueues.get(agentId) ?? [];
+    }
+    /**
+   * Clear command queue for agent
+   */ clearCommandQueue(agentId) {
+        this.commandQueues.delete(agentId);
+    }
+    /**
+   * Apply command to agent session
+   */ async applyCommandToSession(session, command) {
+        // Store command in session metadata for agent to process
+        if (!session.metadata.injectedCommands) {
+            session.metadata.injectedCommands = [];
+        }
+        session.metadata.injectedCommands.push({
+            commandId: command.id,
+            type: command.type,
+            payload: command.payload,
+            issuedBy: command.issuedBy,
+            timestamp: command.timestamp
+        });
+        // Apply command effects based on type
+        switch(command.type){
+            case "state_update":
+                if (command.payload.state) {
+                    session.state = command.payload.state;
+                }
+                break;
+            case "priority_update":
+                if (command.payload.priority !== undefined) {
+                    session.priority = command.payload.priority;
+                }
+                break;
+            case "metadata_update":
+                if (command.payload.metadata) {
+                    session.metadata = {
+                        ...session.metadata,
+                        ...command.payload.metadata
+                    };
+                }
+                break;
+            case "task_update":
+            case "custom":
+                break;
+            default:
+                this.logger.warn('Unknown command type', {
+                    type: command.type
+                });
+        }
+    }
+    // ============================================================================
+    // Hierarchy Traversal Helpers
+    // ============================================================================
+    /**
+   * Get all descendants of an agent (DFS)
+   */ async getAllDescendants(agentId) {
+        const descendants = [];
+        if (!this.hierarchicalCoordinator) {
+            return descendants;
+        }
+        const agent = this.hierarchicalCoordinator.getAgentStatus(agentId);
+        if (!agent) {
+            return descendants;
+        }
+        // DFS traversal
+        const stack = [
+            ...agent.childIds
+        ];
+        while(stack.length > 0){
+            const childId = stack.pop();
+            descendants.push(childId);
+            const child = this.hierarchicalCoordinator.getAgentStatus(childId);
+            if (child && child.childIds.length > 0) {
+                stack.push(...child.childIds);
+            }
+        }
+        return descendants;
+    }
+    // ============================================================================
+    // Metrics and Monitoring
+    // ============================================================================
+    /**
+   * Update control operation metrics
+   */ updateControlMetrics(latencyMs) {
+        const totalOps = this.metrics.totalPauses + this.metrics.totalInjections + this.metrics.totalResumes;
+        this.metrics.averageControlLatencyMs = (this.metrics.averageControlLatencyMs * totalOps + latencyMs) / (totalOps + 1);
+        this.metrics.maxControlLatencyMs = Math.max(this.metrics.maxControlLatencyMs, latencyMs);
+        // Warn if exceeding latency target
+        if (latencyMs > this.config.maxControlLatencyMs) {
+            this.logger.warn('Control operation exceeded latency target', {
+                latencyMs,
+                targetMs: this.config.maxControlLatencyMs
+            });
+        }
+    }
+    /**
+   * Get control operation metrics
+   */ getMetrics() {
+        return {
+            ...this.metrics,
+            latencyTargetMs: this.config.maxControlLatencyMs,
+            withinTarget: this.metrics.averageControlLatencyMs <= this.config.maxControlLatencyMs
+        };
+    }
+    /**
+   * Get queued commands count for agent
+   */ getQueuedCommandsCount(agentId) {
+        return this.commandQueues.get(agentId)?.length ?? 0;
+    }
+    /**
+   * Cleanup - clear all queues and caches
+   */ async cleanup() {
+        this.commandQueues.clear();
+        this.agentLevelCache.clear();
+        this.removeAllListeners();
+        this.logger.info('MultiLevelController cleaned up');
+    }
+    // ============================================================================
+    // Private Helpers
+    // ============================================================================
+    initializeMetrics() {
+        return {
+            totalPauses: 0,
+            totalInjections: 0,
+            totalResumes: 0,
+            averageControlLatencyMs: 0,
+            maxControlLatencyMs: 0
+        };
+    }
+}
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * Create multi-level controller with QueryController
+ */ export function createMultiLevelController(queryController, config) {
+    return new MultiLevelController(queryController, config);
+}
+/**
+ * Create multi-level controller with hierarchical coordinator integration
+ */ export function createMultiLevelControllerWithHierarchy(queryController, hierarchicalCoordinator, config) {
+    const controller = new MultiLevelController(queryController, config);
+    controller.registerHierarchicalCoordinator(hierarchicalCoordinator);
+    return controller;
+} // Types are already exported inline above - no duplicate export needed
+
+//# sourceMappingURL=multi-level-control.js.map

package/.claude-flow-novice/dist/src/coordination/v2/sdk/multi-level-control.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../src/coordination/v2/sdk/multi-level-control.ts"],"names":["EventEmitter","Logger","generateId","InjectedCommandType","MultiLevelController","logger","config","queryController","hierarchicalCoordinator","commandQueues","agentLevelCache","metrics","level","format","destination","maxControlLatencyMs","enableCommandQueue","maxQueuedCommands","enableLogging","Map","initializeMetrics","info","registerHierarchicalCoordinator","coordinator","getHierarchyStructure","hierarchy","agent","agents","set","id","totalAgents","length","hierarchyDepth","depth","updateAgentLevel","agentId","getAgentLevel","cachedLevel","get","undefined","agentStatus","getAgentStatus","pauseChildAgent","parentAgentId","targetAgentId","reason","startTime","Date","now","targetLevel","pauseAgent","latencyMs","updateControlMetrics","totalPauses","result","operation","success","data","emit","error","errorMessage","Error","message","String","injectCommand","commandType","payload","immediate","session","getAgentSession","isPaused","command","type","issuedBy","timestamp","queueCommand","applyCommandToSession","totalInjections","commandId","resumeChildAgent","checkpointId","queuedCommands","getQueuedCommands","clearCommandQueue","debug","commandCount","resumeAgent","totalResumes","appliedCommands","cascadeControlOperation","results","warn","parentAgent","descendants","getAllDescendants","descendantCount","operations","map","descendantId","push","Promise","all","queue","maxQueueSize","shift","delete","metadata","injectedCommands","state","priority","stack","childIds","childId","pop","child","totalOps","averageControlLatencyMs","Math","max","targetMs","getMetrics","latencyTargetMs","withinTarget","getQueuedCommandsCount","cleanup","clear","removeAllListeners","createMultiLevelController","createMultiLevelControllerWithHierarchy","controller"],"mappings":"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"}

package/.claude-flow-novice/dist/src/coordination/v2/sdk/query-controller.js

@@ -7,6 +7,8 @@
  */ import { EventEmitter } from 'node:events';
 import { Logger } from '../../../core/logger.js';
 import { generateId } from '../../../utils/helpers.js';
+import { HelpCoordinator } from '../help-system/help-coordinator.js';
+import { AgentState as AgentStateEnum } from '../core/agent-state.js';
 /**
  * QueryController - Manages agent lifecycle with zero-cost pause/resume
  *
@@ -27,6 +29,7 @@ import { generateId } from '../../../utils/helpers.js';
     coordinatorMetrics;
     ready;
     startTime;
+    /** Help coordinator for agent helper registration */ helpCoordinator;
     constructor(config = {}){
         super();
         this.logger = new Logger({
@@ -49,6 +52,8 @@ import { generateId } from '../../../utils/helpers.js';
         this.coordinatorMetrics = this.initializeCoordinatorMetrics();
         this.ready = false;
         this.startTime = Date.now();
+        // Initialize help coordinator for agent helper registration
+        this.helpCoordinator = new HelpCoordinator();
         this.logger.info('QueryController initialized', {
             maxConcurrentAgents: this.config.maxConcurrentAgents,
             enableDynamicAllocation: this.config.enableDynamicAllocation
@@ -363,12 +368,19 @@ import { generateId } from '../../../utils/helpers.js';
         }
     }
     /**
+   * Get help coordinator instance for external access
+   */ getHelpCoordinator() {
+        return this.helpCoordinator;
+    }
+    /**
    * Cleanup - terminate all sessions
    */ async cleanup() {
         this.logger.info('Cleaning up query controller', {
             totalSessions: this.sessions.size,
             pausedAgents: this.getPausedSessions().length
         });
+        // Clear help coordinator
+        this.helpCoordinator.clear();
         this.sessions.clear();
         this.checkpoints.clear();
         this.resourceAllocations.clear();
@@ -421,6 +433,23 @@ import { generateId } from '../../../utils/helpers.js';
         };
         // Store agent
         this.agents.set(agentId, agent);
+        // Register as helper if capabilities provided
+        if (config.metadata?.capabilities && Array.isArray(config.metadata.capabilities)) {
+            const agentProfile = {
+                agentId,
+                type: config.type,
+                state: agent.state,
+                capabilities: config.metadata.capabilities,
+                priority,
+                workload: 0.0,
+                metadata: config.metadata
+            };
+            this.helpCoordinator.registerAgent(agentProfile);
+            this.logger.debug('Agent registered as helper', {
+                agentId,
+                capabilities: config.metadata.capabilities.map((c)=>c.name)
+            });
+        }
         // Update coordinator metrics
         this.coordinatorMetrics.totalAgentsSpawned++;
         this.coordinatorMetrics.activeAgents++;
@@ -450,6 +479,8 @@ import { generateId } from '../../../utils/helpers.js';
         await this.interrupt(agent.sessionId, reason ?? 'Manual pause');
         // Update agent state
         agent.isPaused = true;
+        // Update help coordinator state
+        this.helpCoordinator.updateAgentState(agentId, AgentStateEnum.PAUSED);
         // Update coordinator metrics
         this.coordinatorMetrics.activeAgents--;
         this.coordinatorMetrics.pausedAgents++;
@@ -471,6 +502,8 @@ import { generateId } from '../../../utils/helpers.js';
         await this.resumeSessionAt(agent.sessionId, messageUUID, 'Resume from coordinator');
         // Update agent state
         agent.isPaused = false;
+        // Update help coordinator state (resumed agents go to IDLE or WORKING)
+        this.helpCoordinator.updateAgentState(agentId, agent.state);
         // Update coordinator metrics
         this.coordinatorMetrics.pausedAgents--;
         this.coordinatorMetrics.activeAgents++;
@@ -486,6 +519,11 @@ import { generateId } from '../../../utils/helpers.js';
         if (!agent.isPaused) {
             await this.createCheckpoint(agentId, `Termination: ${reason ?? 'Manual termination'}`);
         }
+        // Unregister helper if registered
+        this.helpCoordinator.unregisterAgent(agentId);
+        this.logger.debug('Agent unregistered from help coordinator', {
+            agentId
+        });
         // Remove agent
         this.agents.delete(agentId);
         // Remove session
@@ -661,6 +699,12 @@ import { generateId } from '../../../utils/helpers.js';
         this.updateTokenUsageInternal(agentId, tokensUsed);
         // Update coordinator metrics
         this.coordinatorMetrics.totalTokensUsed += tokensUsed;
+        // Update help coordinator workload (tokens used / budget)
+        const allocation = this.resourceAllocations.get(agentId);
+        if (allocation) {
+            const workload = Math.min(1.0, allocation.currentUsage / allocation.tokenBudget);
+            this.helpCoordinator.updateAgentWorkload(agentId, workload);
+        }
     }
     // ===========================
     // Private Helpers