@memberjunction/ai-agents 2.110.1 → 2.111.1

package/dist/base-agent.js

@@ -45,6 +45,7 @@ class BaseAgent {
         this._generalValidationRetryCount = 0;
         this._agentRun = null;
         this._agentHierarchy = [];
+        this._iterationContext = null;
         this._depth = 0;
         this._allProgressSteps = [];
         this._subAgentRuns = [];
@@ -548,9 +549,8 @@ class BaseAgent {
         return await this._promptRunner.ExecutePrompt(newParams);
     }
     async determineNextStep(params, agentType, promptResult, currentPayload) {
-        this.logStatus(`🤔 Processing next step for agent '${params.agent.Name}' with agent type '${agentType.Name}'`, true, params);
         this.logStatus(`🎯 Agent type '${agentType.Name}' determining next step`, true, params);
-        const nextStep = await this.AgentTypeInstance.DetermineNextStep(promptResult, params, currentPayload, this._agentTypeState);
+        const nextStep = await this.AgentTypeInstance.DetermineNextStep(promptResult, params, currentPayload, this.AgentTypeState);
         return nextStep;
     }
     async validateNextStep(params, nextStep, currentPayload, agentRun, currentStep) {
@@ -567,6 +567,10 @@ class BaseAgent {
                 return this.validateRetryNextStep(params, nextStep, currentPayload, agentRun, currentStep);
             case 'Failed':
                 return this.validateFailedNextStep(params, nextStep, currentPayload, agentRun, currentStep);
+            case 'ForEach':
+                return nextStep;
+            case 'While':
+                return nextStep;
             default:
                 this.logError(`Invalid next step '${nextStep.step}' for agent '${params.agent.Name}'`, {
                     agent: params.agent,
@@ -623,7 +627,23 @@ class BaseAgent {
     }
     async validateActionsNextStep(params, nextStep, currentPayload, agentRun, currentStep) {
         const curAgentActions = aiengine_1.AIEngine.Instance.AgentActions.filter(aa => aa.AgentID === params.agent.ID && aa.Status === 'Active');
-        const missingActions = nextStep.actions?.filter(action => !curAgentActions.some(aa => aa.Action.trim().toLowerCase() === action.name.trim().toLowerCase()));
+        const missingActions = nextStep.actions?.filter(action => {
+            const actionName = action.name.trim().toLowerCase();
+            const exactMatch = curAgentActions.find(aa => aa.Action.trim().toLowerCase() === actionName);
+            if (exactMatch)
+                return false;
+            const containsMatches = curAgentActions.filter(aa => aa.Action.trim().toLowerCase().includes(actionName));
+            if (containsMatches.length === 1) {
+                const correctedName = containsMatches[0].Action;
+                this.logStatus(`Action name fuzzy matched: '${action.name}' → '${correctedName}'`, true, params);
+                action.name = correctedName;
+                return false;
+            }
+            if (containsMatches.length > 1) {
+                this.logStatus(`Ambiguous action name '${action.name}' matches ${containsMatches.length} actions: ${containsMatches.map(a => a.Action).join(', ')}`, true, params);
+            }
+            return true;
+        });
         if (missingActions && missingActions.length > 0) {
             const missingActionNames = missingActions.map(a => a.name).join(', ');
             this.logError(`Actions '${missingActionNames}' not found or not active for agent '${params.agent.Name}'`, {
@@ -1465,11 +1485,11 @@ Please choose an alternative approach to complete your task.`
         try {
             const validationResult = await this.validateAgent(agent);
             if (validationResult) {
-                const stepEntity = await this.createStepEntity('Validation', 'Agent Validation', contextUser);
+                const stepEntity = await this.createStepEntity({ stepType: 'Validation', stepName: 'Agent Validation', contextUser });
                 await this.finalizeStepEntity(stepEntity, false, validationResult.agentRun?.ErrorMessage);
                 return await this.createFailureResult(validationResult.agentRun?.ErrorMessage || 'Validation failed', contextUser);
             }
-            const stepEntity = await this.createStepEntity('Validation', 'Agent Validation', contextUser);
+            const stepEntity = await this.createStepEntity({ stepType: 'Validation', stepName: 'Agent Validation', contextUser });
             await this.finalizeStepEntity(stepEntity, true);
             return null;
         }
@@ -1477,26 +1497,27 @@ Please choose an alternative approach to complete your task.`
             return await this.createFailureResult(`Validation error: ${error.message}`, contextUser);
         }
     }
-    async createStepEntity(stepType, stepName, contextUser, targetId, inputData, targetLogId, payloadAtStart, payloadAtEnd) {
-        const stepEntity = await this._metadata.GetEntityObject('MJ: AI Agent Run Steps', contextUser);
+    async createStepEntity(params) {
+        const stepEntity = await this._metadata.GetEntityObject('MJ: AI Agent Run Steps', params.contextUser);
         stepEntity.AgentRunID = this._agentRun.ID;
         stepEntity.StepNumber = (this._agentRun.Steps?.length || 0) + 1;
-        stepEntity.StepType = stepType;
-        stepEntity.StepName = this.formatHierarchicalMessage(stepName);
-        if (targetId && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(targetId)) {
-            console.warn(`Invalid target ID format: ${targetId}`);
+        stepEntity.StepType = params.stepType;
+        stepEntity.StepName = this.formatHierarchicalMessage(params.stepName);
+        if (params.targetId && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(params.targetId)) {
+            console.warn(`Invalid target ID format: ${params.targetId}`);
         }
         else {
-            stepEntity.TargetID = targetId || null;
+            stepEntity.TargetID = params.targetId || null;
         }
-        stepEntity.TargetLogID = targetLogId || null;
+        stepEntity.TargetLogID = params.targetLogId || null;
+        stepEntity.ParentID = params.parentId || null;
         stepEntity.Status = 'Running';
         stepEntity.StartedAt = new Date();
-        stepEntity.PayloadAtStart = payloadAtStart ? JSON.stringify(payloadAtStart) : null;
-        stepEntity.PayloadAtEnd = payloadAtEnd ? JSON.stringify(payloadAtEnd) : null;
-        if (inputData) {
+        stepEntity.PayloadAtStart = params.payloadAtStart ? JSON.stringify(params.payloadAtStart) : null;
+        stepEntity.PayloadAtEnd = params.payloadAtEnd ? JSON.stringify(params.payloadAtEnd) : null;
+        if (params.inputData) {
             stepEntity.InputData = JSON.stringify({
-                ...inputData,
+                ...params.inputData,
                 context: {
                     agentHierarchy: this._agentHierarchy,
                     depth: this._depth,
@@ -1562,6 +1583,66 @@ Please choose an alternative approach to complete your task.`
             console.error('Failed to update agent run step record');
         }
     }
+    getValueFromPath(obj, path) {
+        const parts = path.split('.');
+        let current = obj;
+        for (const part of parts) {
+            if (!part)
+                continue;
+            const arrayMatch = part.match(/^([^[]+)\[(\d+)\]$/);
+            if (arrayMatch) {
+                const arrayName = arrayMatch[1];
+                const index = parseInt(arrayMatch[2], 10);
+                if (current && typeof current === 'object' && arrayName in current) {
+                    current = current[arrayName];
+                    if (Array.isArray(current) && index >= 0 && index < current.length) {
+                        current = current[index];
+                    }
+                    else {
+                        return undefined;
+                    }
+                }
+                else {
+                    return undefined;
+                }
+            }
+            else {
+                if (current && typeof current === 'object' && part in current) {
+                    current = current[part];
+                }
+                else {
+                    return undefined;
+                }
+            }
+        }
+        return current;
+    }
+    resolveLoopParams(params, item, index, payload) {
+        const resolved = {};
+        for (const [key, value] of Object.entries(params)) {
+            if (typeof value === 'string') {
+                if (value.startsWith('item.')) {
+                    resolved[key] = this.getValueFromPath(item, value.substring(5));
+                }
+                else if (value.startsWith('payload.')) {
+                    resolved[key] = this.getValueFromPath(payload, value.substring(8));
+                }
+                else if (value === 'item') {
+                    resolved[key] = item;
+                }
+                else if (value === 'index') {
+                    resolved[key] = index;
+                }
+                else {
+                    resolved[key] = value;
+                }
+            }
+            else {
+                resolved[key] = value;
+            }
+        }
+        return resolved;
+    }
     formatHierarchicalMessage(baseMessage) {
         if (this._depth > 0) {
             const breadcrumb = this._agentHierarchy
@@ -1603,11 +1684,10 @@ Please choose an alternative approach to complete your task.`
             case 'Sub-Agent':
                 return await this.processSubAgentStep(params, previousDecision);
             case 'Actions':
-                return await this.executeActionsStep(params, config, previousDecision);
+                return await this.executeActionsStep(params, previousDecision, undefined);
             case 'Chat':
                 return await this.executeChatStep(params, previousDecision);
             case 'Success':
-                const pd = previousDecision;
                 if (previousDecision.terminate) {
                     return {
                         terminate: true,
@@ -1631,6 +1711,10 @@ Please choose an alternative approach to complete your task.`
                 else {
                     return await this.executePromptStep(params, config, previousDecision);
                 }
+            case 'ForEach':
+                return await this.executeForEachLoop(params, config, previousDecision);
+            case 'While':
+                return await this.executeWhileLoop(params, config, previousDecision);
             default:
                 throw new Error(`Unsupported next step: ${previousDecision.step}`);
         }
@@ -1650,7 +1734,7 @@ Please choose an alternative approach to complete your task.`
             conversationMessages: params.conversationMessages,
         };
         const payload = previousDecision?.newPayload || params.payload;
-        const stepEntity = await this.createStepEntity('Prompt', 'Execute Agent Prompt', params.contextUser, promptId, inputData, undefined, payload);
+        const stepEntity = await this.createStepEntity({ stepType: 'Prompt', stepName: 'Execute Agent Prompt', contextUser: params.contextUser, targetId: promptId, inputData, payloadAtStart: payload });
         try {
             const isRetry = !!previousDecision;
             const promptMessage = isRetry
@@ -1697,6 +1781,10 @@ Please choose an alternative approach to complete your task.`
                 await stepEntity.Save();
             };
             const promptResult = await this.executePrompt(promptParams);
+            const loopMsgIndex = params.conversationMessages.findIndex(m => m.metadata?._loopResults === true);
+            if (loopMsgIndex !== -1) {
+                params.conversationMessages.splice(loopMsgIndex, 1);
+            }
             if (promptResult.promptRun?.ID) {
                 stepEntity.TargetLogID = promptResult.promptRun.ID;
                 stepEntity.PromptRun = promptResult.promptRun;
@@ -1841,7 +1929,7 @@ Please choose an alternative approach to complete your task.`
         if (!subAgentEntity) {
             throw new Error(`Sub-agent '${subAgentRequest.name}' not found`);
         }
-        const stepEntity = await this.createStepEntity('Sub-Agent', `Execute Sub-Agent: ${subAgentRequest.name}`, params.contextUser, subAgentEntity.ID, inputData, undefined, previousDecision.newPayload);
+        const stepEntity = await this.createStepEntity({ stepType: 'Sub-Agent', stepName: `Execute Sub-Agent: ${subAgentRequest.name}`, contextUser: params.contextUser, targetId: subAgentEntity.ID, inputData, payloadAtStart: previousDecision.newPayload });
         this.incrementExecutionCount(subAgentEntity.ID);
         try {
             let downstreamPaths = ['*'];
@@ -2093,7 +2181,14 @@ Please choose an alternative approach to complete your task.`
             parentAgentHierarchy: this._agentHierarchy,
             relationshipType: 'related'
         };
-        const stepEntity = await this.createStepEntity('Sub-Agent', `Execute Related Sub-Agent: ${subAgentRequest.name}`, params.contextUser, subAgentEntity.ID, inputData, undefined, previousDecision.newPayload);
+        const stepEntity = await this.createStepEntity({
+            stepType: 'Sub-Agent',
+            stepName: `Execute Related Sub-Agent: ${subAgentRequest.name}`,
+            contextUser: params.contextUser,
+            targetId: subAgentEntity.ID,
+            inputData,
+            payloadAtStart: previousDecision.newPayload
+        });
         this.incrementExecutionCount(subAgentEntity.ID);
         try {
             stepEntity.PayloadAtStart = JSON.stringify(previousDecision.newPayload);
@@ -2307,41 +2402,7 @@ Please choose an alternative approach to complete your task.`
             content: `Parent Agent Context:\n\n${contextLines.join('\n\n')}`
         };
     }
-    getValueFromPath(obj, path) {
-        const parts = path.split('.');
-        let current = obj;
-        for (const part of parts) {
-            if (!part)
-                continue;
-            const arrayMatch = part.match(/^([^[]+)\[(\d+)\]$/);
-            if (arrayMatch) {
-                const arrayName = arrayMatch[1];
-                const index = parseInt(arrayMatch[2], 10);
-                if (current && typeof current === 'object' && arrayName in current) {
-                    current = current[arrayName];
-                    if (Array.isArray(current) && index >= 0 && index < current.length) {
-                        current = current[index];
-                    }
-                    else {
-                        return undefined;
-                    }
-                }
-                else {
-                    return undefined;
-                }
-            }
-            else {
-                if (current && typeof current === 'object' && part in current) {
-                    current = current[part];
-                }
-                else {
-                    return undefined;
-                }
-            }
-        }
-        return current;
-    }
-    async executeActionsStep(params, config, previousDecision) {
+    async executeActionsStep(params, previousDecision, parentStepId, addConversationMessage = true) {
         try {
             const currentPayload = previousDecision?.newPayload || previousDecision?.previousPayload || params.payload;
             const actions = previousDecision.actions || [];
@@ -2422,10 +2483,12 @@ Please choose an alternative approach to complete your task.`
                     return actionText;
                 }).join('\n\n');
             }
-            params.conversationMessages.push({
-                role: 'assistant',
-                content: actionMessage
-            });
+            if (addConversationMessage) {
+                params.conversationMessages.push({
+                    role: 'assistant',
+                    content: actionMessage
+                });
+            }
             const actionEngine = actions_1.ActionEngineServer.Instance;
             const agentActions = aiengine_1.AIEngine.Instance.AgentActions.filter(aa => aa.AgentID === params.agent.ID);
             try {
@@ -2447,7 +2510,7 @@ Please choose an alternative approach to complete your task.`
                     actionName: aa.name,
                     actionParams: aa.params
                 };
-                const stepEntity = await this.createStepEntity('Actions', `Execute Action: ${aa.name}`, params.contextUser, actionEntity.ID, actionInputData, undefined, currentPayload, currentPayload);
+                const stepEntity = await this.createStepEntity({ stepType: 'Actions', stepName: `Execute Action: ${aa.name}`, contextUser: params.contextUser, targetId: actionEntity.ID, inputData: actionInputData, payloadAtStart: currentPayload, payloadAtEnd: currentPayload, parentId: parentStepId });
                 lastStep = stepEntity;
                 stepEntity.StepNumber = baseStepNumber + numActionsProcessed++;
                 this.incrementExecutionCount(actionEntity.ID);
@@ -2524,11 +2587,13 @@ Please choose an alternative approach to complete your task.`
                     };
                 }
             }
-            params.conversationMessages.push({
-                role: 'user',
-                content: resultsMessage,
-                metadata: metadata
-            });
+            if (addConversationMessage) {
+                params.conversationMessages.push({
+                    role: 'user',
+                    content: resultsMessage,
+                    metadata: metadata
+                });
+            }
             let finalPayload = currentPayload;
             try {
                 const actionResultsOnly = actionResults.map(r => r.result).filter(r => r !== undefined);
@@ -2582,7 +2647,7 @@ Please choose an alternative approach to complete your task.`
         }
     }
     async executeChatStep(params, previousDecision) {
-        const stepEntity = await this.createStepEntity('Chat', 'User Interaction', params.contextUser);
+        const stepEntity = await this.createStepEntity({ stepType: 'Chat', stepName: 'User Interaction', contextUser: params.contextUser });
         await this.finalizeStepEntity(stepEntity, true);
         return {
             step: 'Chat',
@@ -2596,6 +2661,377 @@ Please choose an alternative approach to complete your task.`
             suggestedResponses: previousDecision.suggestedResponses
         };
     }
+    async executeForEachLoop(params, config, previousDecision) {
+        const forEach = previousDecision.forEach;
+        if (!forEach) {
+            return this.createFailedStep('ForEach configuration missing', previousDecision);
+        }
+        const validationMessage = this.validateForEachOperation(forEach);
+        if (validationMessage) {
+            return this.createFailedStep(`ForEach configuration invalid: ${validationMessage}`, previousDecision);
+        }
+        const currentPayload = previousDecision.newPayload || previousDecision.previousPayload;
+        const collection = this.getCollectionFromPayload(currentPayload, forEach.collectionPath);
+        if (!collection) {
+            return this.createFailedStep(`Collection path "${forEach.collectionPath}" not an array`, previousDecision);
+        }
+        const loopStepEntity = await this.createForEachLoopStep(forEach, collection, currentPayload, params);
+        const loopResults = await this.executeForEachIterations(forEach, collection, currentPayload, loopStepEntity.ID, params, config);
+        return this.completeForEachLoop(forEach, loopStepEntity, loopResults, previousDecision, params);
+    }
+    validateWhileOperation(whileOp) {
+        if (!whileOp.condition || whileOp.condition.trim() === '') {
+            return 'Condition is required';
+        }
+        if (!whileOp.itemVariable || whileOp.itemVariable.trim() === '') {
+            return 'Item variable is required';
+        }
+        if (whileOp.action) {
+            return this.validateActionInAgent(whileOp.action.name);
+        }
+        else if (whileOp.subAgent) {
+            return this.validateSubAgentInAgent(whileOp.subAgent.name);
+        }
+        return null;
+    }
+    validateForEachOperation(forEach) {
+        if (!forEach.itemVariable || forEach.itemVariable.trim() === '') {
+            return 'Item variable is required';
+        }
+        if (!forEach.collectionPath || forEach.collectionPath.trim() === '') {
+            return 'Collection path is required';
+        }
+        if (forEach.action) {
+            return this.validateActionInAgent(forEach.action.name);
+        }
+        else if (forEach.subAgent) {
+            return this.validateSubAgentInAgent(forEach.subAgent.name);
+        }
+        return null;
+    }
+    validateActionInAgent(actionName) {
+        const aa = aiengine_1.AIEngine.Instance.AgentActions.filter(aa => aa.AgentID === this._agentRun.AgentID);
+        let action = aa.filter(a => a.Agent?.trim().toLowerCase() === actionName.trim().toLowerCase());
+        if (!action) {
+            const partialAction = aa.filter(a => a.Agent?.trim().toLowerCase().includes(actionName.trim().toLowerCase() || ''));
+            if (partialAction.length > 1) {
+                return `Ambiguous action '${actionName}' specified`;
+            }
+            else if (partialAction.length === 0) {
+                return `No action '${actionName}' found`;
+            }
+        }
+        return null;
+    }
+    validateSubAgentInAgent(subAgentName) {
+        const relatedAgents = aiengine_1.AIEngine.Instance.AgentRelationships.filter(ar => ar.AgentID === this._agentRun.AgentID);
+        const childAgents = aiengine_1.AIEngine.Instance.Agents.filter(a => a.ParentID === this._agentRun.AgentID);
+        let subAgent = relatedAgents.filter(ra => ra.SubAgent?.trim().toLowerCase() === subAgentName.trim().toLowerCase());
+        if (subAgent.length === 0) {
+            subAgent = relatedAgents.filter(ra => ra.SubAgent?.trim().toLowerCase().includes(subAgentName.trim().toLowerCase() || ''));
+            if (subAgent.length > 1) {
+                return `Ambiguous sub-agent '${subAgentName}' specified`;
+            }
+            else if (subAgent.length === 0) {
+                let childAgent = childAgents.filter(ca => ca.Name?.trim().toLowerCase() === subAgentName.trim().toLowerCase());
+                if (childAgent.length === 0) {
+                    childAgent = childAgents.filter(ca => ca.Name?.trim().toLowerCase().includes(subAgentName.trim().toLowerCase() || ''));
+                    if (childAgent.length > 1) {
+                        return `Ambiguous child agent '${subAgentName}' specified`;
+                    }
+                    else if (childAgent.length === 0) {
+                        return `No child agent '${subAgentName}' found`;
+                    }
+                }
+                else {
+                }
+            }
+        }
+        return null;
+    }
+    getCollectionFromPayload(payload, path) {
+        const cleanPath = path.toLowerCase().startsWith('payload.')
+            ? path.substring(8)
+            : path;
+        const value = this.getValueFromPath(payload, cleanPath);
+        return Array.isArray(value) ? value : null;
+    }
+    async createForEachLoopStep(forEach, collection, payload, params) {
+        const stepEntity = await this.createStepEntity({
+            stepType: 'ForEach',
+            stepName: `ForEach: ${forEach.collectionPath} (${collection.length} items)`,
+            contextUser: params.contextUser,
+            inputData: { forEach, count: collection.length },
+            payloadAtStart: payload
+        });
+        return stepEntity;
+    }
+    async executeForEachIterations(forEach, collection, initialPayload, parentStepId, params, config) {
+        const executionMode = forEach.executionMode || 'sequential';
+        if (executionMode === 'parallel') {
+            return this.executeForEachIterationsParallel(forEach, collection, initialPayload, parentStepId, params, config);
+        }
+        else {
+            return this.executeForEachIterationsSequential(forEach, collection, initialPayload, parentStepId, params, config);
+        }
+    }
+    async executeForEachIterationsSequential(forEach, collection, initialPayload, parentStepId, params, config) {
+        let currentPayload = initialPayload;
+        const maxIterations = forEach.maxIterations ?? 1000;
+        const results = [];
+        const errors = [];
+        for (let i = 0; i < Math.min(collection.length, maxIterations); i++) {
+            if (i > 0 && forEach.delayBetweenIterationsMs) {
+                await new Promise(resolve => setTimeout(resolve, forEach.delayBetweenIterationsMs));
+            }
+            const iterResult = await this.executeSingleForEachIteration(forEach, collection[i], i, currentPayload, parentStepId, params, config);
+            if (iterResult.error) {
+                errors.push(iterResult.error);
+                if (!forEach.continueOnError)
+                    break;
+            }
+            else {
+                results.push(iterResult.result);
+                currentPayload = iterResult.payload;
+            }
+        }
+        return { results, errors, finalPayload: currentPayload };
+    }
+    async executeForEachIterationsParallel(forEach, collection, initialPayload, parentStepId, params, config) {
+        const maxIterations = forEach.maxIterations ?? 1000;
+        const maxConcurrency = forEach.maxConcurrency ?? 10;
+        const itemsToProcess = Math.min(collection.length, maxIterations);
+        const batches = this.createBatches(collection.slice(0, itemsToProcess), maxConcurrency);
+        const allResults = [];
+        for (let batchIndex = 0; batchIndex < batches.length; batchIndex++) {
+            const batch = batches[batchIndex];
+            const batchPromises = batch.map(({ item, index }) => this.executeSingleForEachIteration(forEach, item, index, initialPayload, parentStepId, params, config).then(iterResult => ({
+                index,
+                result: iterResult.result,
+                error: iterResult.error,
+                payload: iterResult.payload
+            })));
+            const batchResults = await Promise.all(batchPromises);
+            allResults.push(...batchResults);
+            if (forEach.delayBetweenIterationsMs && batchIndex < batches.length - 1) {
+                await new Promise(resolve => setTimeout(resolve, forEach.delayBetweenIterationsMs));
+            }
+            const hasFailure = batchResults.some(r => r.error);
+            if (hasFailure && !forEach.continueOnError) {
+                break;
+            }
+        }
+        allResults.sort((a, b) => a.index - b.index);
+        return this.applyForEachResultsSequentially(allResults, initialPayload, forEach.continueOnError || false);
+    }
+    createBatches(items, maxConcurrency) {
+        const batches = [];
+        for (let i = 0; i < items.length; i += maxConcurrency) {
+            const batch = items.slice(i, i + maxConcurrency).map((item, batchOffset) => ({
+                item,
+                index: i + batchOffset
+            }));
+            batches.push(batch);
+        }
+        return batches;
+    }
+    applyForEachResultsSequentially(sortedResults, initialPayload, continueOnError) {
+        let currentPayload = initialPayload;
+        const results = [];
+        const errors = [];
+        for (const { result, error, payload } of sortedResults) {
+            if (error) {
+                errors.push(error);
+                if (!continueOnError) {
+                    break;
+                }
+            }
+            else if (result) {
+                results.push(result);
+                currentPayload = payload || currentPayload;
+            }
+        }
+        return { results, errors, finalPayload: currentPayload };
+    }
+    async executeSingleForEachIteration(forEach, item, index, currentPayload, parentStepId, params, config) {
+        try {
+            const beforeHook = this.AgentTypeInstance.BeforeLoopIteration?.({ item, itemVariable: forEach.itemVariable, index, payload: currentPayload, loopType: 'ForEach', actionParams: forEach.action?.params || {} });
+            const resolvedParams = beforeHook?.actionParams || forEach.action?.params || {};
+            let result;
+            if (forEach.action) {
+                const matchedAction = this.findAgentActionForLoop(forEach.action.name, params.agent.ID, params.agent.Name, params);
+                const resolvedAction = {
+                    name: matchedAction.Action,
+                    params: resolvedParams
+                };
+                const actionStep = { step: 'Actions', actions: [resolvedAction], newPayload: currentPayload, previousPayload: currentPayload, terminate: false };
+                result = await this.executeActionsStep(params, actionStep, parentStepId, false);
+            }
+            else if (forEach.subAgent) {
+                const subAgentStep = { step: 'Sub-Agent', subAgent: forEach.subAgent, newPayload: currentPayload, previousPayload: currentPayload };
+                result = await this.processSubAgentStep(params, subAgentStep);
+            }
+            else {
+                throw new Error('ForEach missing action/subAgent');
+            }
+            const iterPayload = result.newPayload || currentPayload;
+            const afterHook = this.AgentTypeInstance.AfterLoopIteration?.({ currentPayload: iterPayload, item, itemVariable: forEach.itemVariable, index, loopContext: { actionOutputMapping: forEach.action?.outputMapping } });
+            return { payload: afterHook || iterPayload, result };
+        }
+        catch (error) {
+            return { error: { index, item, message: error.message } };
+        }
+    }
+    async completeForEachLoop(forEach, loopStepEntity, loopResults, previousDecision, params) {
+        loopStepEntity.PayloadAtEnd = JSON.stringify(loopResults.finalPayload);
+        await this.finalizeStepEntity(loopStepEntity, loopResults.errors.length === 0, loopResults.errors.join('\n\n'), loopResults);
+        if (this.AgentTypeInstance.InjectLoopResultsAsMessage) {
+            this.injectLoopResultsMessage('ForEach', forEach.collectionPath, loopResults.results, loopResults.errors, params);
+        }
+        return {
+            step: 'Retry',
+            retryInstructions: `Completed ForEach loop request using collection at '${forEach.collectionPath}'`,
+            terminate: false,
+            newPayload: loopResults.finalPayload,
+            previousPayload: previousDecision.previousPayload
+        };
+    }
+    injectLoopResultsMessage(loopType, collectionOrCondition, results, errors, params) {
+        const extractedResults = results.map(r => r.priorStepResult);
+        const label = loopType === 'ForEach' ? 'Collection' : 'Condition';
+        params.conversationMessages.push({
+            role: 'user',
+            content: `## Loop Completed\n**Type:** ${loopType}\n**${label}:** ${collectionOrCondition}\n` +
+                `**Processed:** ${results.length}, **Errors:** ${errors.length}\n\n` +
+                `**Results:**\n\`\`\`json\n${JSON.stringify(extractedResults, null, 2)}\n\`\`\``,
+            metadata: { _temporary: true, _loopResults: true }
+        });
+    }
+    findAgentActionForLoop(actionName, agentId, agentName, params) {
+        const agentActions = aiengine_1.AIEngine.Instance.AgentActions.filter(aa => aa.AgentID === agentId && aa.Status === 'Active');
+        let matched = agentActions.find(aa => aa.Action.trim().toLowerCase() === actionName.trim().toLowerCase());
+        if (!matched) {
+            const containsMatches = agentActions.filter(aa => aa.Action.trim().toLowerCase().includes(actionName.trim().toLowerCase()));
+            if (containsMatches.length === 1) {
+                matched = containsMatches[0];
+                this.logStatus(`Action fuzzy matched: '${actionName}' → '${matched.Action}'`, true, params);
+            }
+            else if (containsMatches.length > 1) {
+                throw new Error(`Ambiguous action '${actionName}'. Matches: ${containsMatches.map(a => a.Action).join(', ')}`);
+            }
+            else {
+                throw new Error(`Action '${actionName}' not found for agent '${agentName}'`);
+            }
+        }
+        return matched;
+    }
+    createFailedStep(errorMessage, previousDecision) {
+        return {
+            step: 'Failed',
+            terminate: false,
+            errorMessage,
+            previousPayload: previousDecision.previousPayload,
+            newPayload: previousDecision.newPayload || previousDecision.previousPayload
+        };
+    }
+    async executeWhileLoop(params, config, previousDecision) {
+        const whileOp = previousDecision.while;
+        if (!whileOp) {
+            return this.createFailedStep('While configuration missing', previousDecision);
+        }
+        const validationMessage = this.validateWhileOperation(whileOp);
+        if (validationMessage) {
+            return this.createFailedStep(`While configuration invalid: ${validationMessage}`, previousDecision);
+        }
+        const currentPayload = previousDecision.newPayload || previousDecision.previousPayload;
+        const loopStepEntity = await this.createWhileLoopStep(whileOp, currentPayload, params);
+        const loopResults = await this.executeWhileIterations(whileOp, currentPayload, loopStepEntity.ID, params, config);
+        return this.completeWhileLoop(whileOp, loopStepEntity, loopResults, previousDecision, params);
+    }
+    async createWhileLoopStep(whileOp, payload, params) {
+        const stepEntity = await this.createStepEntity({
+            stepType: 'While',
+            stepName: `While: ${whileOp.condition}`,
+            contextUser: params.contextUser,
+            inputData: { while: whileOp },
+            payloadAtStart: payload
+        });
+        return stepEntity;
+    }
+    async executeWhileIterations(whileOp, initialPayload, parentStepId, params, config) {
+        let currentPayload = initialPayload;
+        const maxIterations = whileOp.maxIterations ?? 100;
+        const results = [];
+        const errors = [];
+        let iterationCount = 0;
+        const { SafeExpressionEvaluator } = require('@memberjunction/global');
+        const evaluator = new SafeExpressionEvaluator();
+        while (iterationCount < maxIterations) {
+            if (iterationCount > 0 && whileOp.delayBetweenIterationsMs) {
+                await new Promise(resolve => setTimeout(resolve, whileOp.delayBetweenIterationsMs));
+            }
+            const evalResult = evaluator.evaluate(whileOp.condition, { payload: currentPayload, results, errors });
+            if (!evalResult.success || !evalResult.value) {
+                break;
+            }
+            const attemptContext = { attemptNumber: iterationCount + 1, totalAttempts: iterationCount };
+            const iterResult = await this.executeSingleWhileIteration(whileOp, attemptContext, iterationCount, currentPayload, parentStepId, params, config);
+            if (iterResult.error) {
+                errors.push(iterResult.error);
+                if (!whileOp.continueOnError)
+                    break;
+            }
+            else {
+                results.push(iterResult.result);
+                currentPayload = iterResult.payload;
+            }
+            iterationCount++;
+        }
+        return { results, errors, finalPayload: currentPayload, iterations: iterationCount };
+    }
+    async executeSingleWhileIteration(whileOp, attemptContext, index, currentPayload, parentStepId, params, config) {
+        try {
+            const beforeHook = this.AgentTypeInstance.BeforeLoopIteration?.({ item: attemptContext, index, itemVariable: whileOp.itemVariable, payload: currentPayload, loopType: 'While', actionParams: whileOp.action?.params || {} });
+            const resolvedParams = beforeHook?.actionParams || whileOp.action?.params || {};
+            let result;
+            if (whileOp.action) {
+                const matchedAction = this.findAgentActionForLoop(whileOp.action.name, params.agent.ID, params.agent.Name, params);
+                const resolvedAction = {
+                    name: matchedAction.Action,
+                    params: resolvedParams
+                };
+                const actionStep = { step: 'Actions', actions: [resolvedAction], newPayload: currentPayload, previousPayload: currentPayload, terminate: false };
+                result = await this.executeActionsStep(params, actionStep, parentStepId, false);
+            }
+            else if (whileOp.subAgent) {
+                const subAgentStep = { step: 'Sub-Agent', subAgent: whileOp.subAgent, newPayload: currentPayload, previousPayload: currentPayload };
+                result = await this.processSubAgentStep(params, subAgentStep);
+            }
+            else {
+                throw new Error('While missing action/subAgent');
+            }
+            const iterPayload = result.newPayload || currentPayload;
+            const afterHook = this.AgentTypeInstance.AfterLoopIteration?.({ currentPayload: iterPayload, item: attemptContext, itemVariable: whileOp.itemVariable, index, loopContext: { actionOutputMapping: whileOp.action?.outputMapping } });
+            return { payload: afterHook || iterPayload, result };
+        }
+        catch (error) {
+            return { error: { index, item: attemptContext, message: error.message } };
+        }
+    }
+    async completeWhileLoop(whileOp, loopStepEntity, loopResults, previousDecision, params) {
+        loopStepEntity.PayloadAtEnd = JSON.stringify(loopResults.finalPayload);
+        await this.finalizeStepEntity(loopStepEntity, loopResults.errors.length === 0, loopResults.errors.join('\n\n'), loopResults);
+        if (this.AgentTypeInstance.InjectLoopResultsAsMessage) {
+            this.injectLoopResultsMessage('While', whileOp.condition, loopResults.results, loopResults.errors, params);
+        }
+        return {
+            step: 'Retry',
+            retryInstructions: `Completed While loop request using condition '${whileOp.condition}' after ${loopResults.iterations} iteration(s)`,
+            terminate: false,
+            newPayload: loopResults.finalPayload,
+            previousPayload: previousDecision.previousPayload
+        };
+    }
     async createFailureResult(errorMessage, contextUser) {
         if (this._agentRun) {
             this._agentRun.Status = 'Failed';