@memberjunction/ai-agents 3.4.0 → 4.0.0

package/dist/agent-types/flow-agent-type.js

@@ -1,41 +1,104 @@
-"use strict";
+/**
+ * @fileoverview Implementation of the Flow Agent Type for deterministic workflow execution.
+ *
+ * The FlowAgentType enables agents to execute predefined workflows using a directed graph
+ * of steps and conditional paths. Unlike LoopAgentType which makes decisions based on
+ * LLM output, FlowAgentType follows a deterministic execution path based on boolean
+ * expressions evaluated against the current payload and step results.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ * @since 2.76.0
+ */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LoadFlowAgentType = exports.FlowAgentType = exports.FlowExecutionState = void 0;
-const global_1 = require("@memberjunction/global");
-const base_agent_type_1 = require("./base-agent-type");
-const core_1 = require("@memberjunction/core");
-const aiengine_1 = require("@memberjunction/aiengine");
-const actions_1 = require("@memberjunction/actions");
-const PayloadManager_1 = require("../PayloadManager");
-const ConversationMessageResolver_1 = require("../utils/ConversationMessageResolver");
-class FlowExecutionState {
+import { RegisterClass, SafeExpressionEvaluator } from '@memberjunction/global';
+import { BaseAgentType } from './base-agent-type.js';
+import { LogError, LogStatus, LogStatusEx, IsVerboseLoggingEnabled } from '@memberjunction/core';
+import { AIEngine } from '@memberjunction/aiengine';
+import { ActionEngineServer } from '@memberjunction/actions';
+import { PayloadManager } from '../PayloadManager.js';
+import { ConversationMessageResolver } from '../utils/ConversationMessageResolver.js';
+/**
+ * Flow execution state that tracks the progress through the workflow.
+ * This is maintained by the Flow Agent Type during execution.
+ *
+ * Note: Loop iteration tracking is now handled by BaseAgent._iterationContext.
+ * FlowExecutionState only tracks flow-specific navigation state.
+ */
+export class FlowExecutionState {
     constructor(agentId) {
+        /** Set of completed step IDs */
         this.completedStepIds = new Set();
+        /** Map of step results by step ID */
         this.stepResults = new Map();
+        /** Ordered list of step IDs in execution order */
         this.executionPath = [];
         this.agentId = agentId;
     }
 }
-exports.FlowExecutionState = FlowExecutionState;
-let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType {
+/**
+ * Implementation of the Flow Agent Type pattern.
+ *
+ * This agent type enables deterministic workflow execution where agents follow
+ * predefined paths through a graph of steps. Key features:
+ * - Graph-based workflow definition
+ * - Conditional path evaluation using safe boolean expressions
+ * - Support for Actions, Sub-Agents, and Prompts as step types
+ * - Deterministic execution with optional AI-driven decision points
+ *
+ * @class FlowAgentType
+ * @extends BaseAgentType
+ *
+ * @example
+ * ```typescript
+ * // Flow agents execute steps based on graph structure
+ * const flowAgent = new FlowAgentType();
+ * const nextStep = await flowAgent.DetermineNextStep(promptResult, payload);
+ *
+ * // Steps are determined by evaluating path conditions
+ * // Path: "payload.status == 'approved' && payload.amount < 1000"
+ * // Leads to: "Auto-Approve" step
+ * ```
+ */
+let FlowAgentType = class FlowAgentType extends BaseAgentType {
     constructor() {
         super(...arguments);
-        this._evaluator = new global_1.SafeExpressionEvaluator();
-        this._payloadManager = new PayloadManager_1.PayloadManager();
+        this._evaluator = new SafeExpressionEvaluator();
+        this._payloadManager = new PayloadManager();
     }
+    /**
+     * Handles the initialization of the flow agent state that is specialized, additional state information
+     * specific to the Flow Agent Type
+     * @param params
+     * @returns
+     */
     async InitializeAgentTypeState(params) {
         const flowState = new FlowExecutionState(params.agent.ID);
         return flowState;
     }
+    /**
+     * Determines the next step based on the flow graph structure.
+     *
+     * For Flow agents, the next step is determined by:
+     * 1. Finding the current position in the graph
+     * 2. Evaluating conditions on outgoing paths
+     * 3. Following the highest priority valid path
+     * 4. Using prompt results only when current step type is 'Prompt'
+     *
+     * @param {AIPromptRunResult | null} promptResult - Result from prompt execution (null for non-prompt steps)
+     * @param {ExecuteAgentParams} params - The full execution parameters
+     *
+     * @returns {Promise<BaseAgentNextStep<P>>} The next step to execute
+     */
     async DetermineNextStep(promptResult, params, payload, agentTypeState) {
         try {
             const flowState = agentTypeState;
+            // If no current step, this should have been handled by DetermineInitialStep
             if (!flowState.currentStepId) {
                 const startingSteps = await this.getStartingSteps(params.agent.ID);
                 if (startingSteps.length === 0) {
@@ -43,26 +106,41 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                         errorMessage: 'No starting steps defined for flow agent'
                     });
                 }
+                // For now, execute the first starting step
+                // Future enhancement: support parallel starting steps
                 return await this.createStepForFlowNode(params, startingSteps[0], payload, flowState);
             }
+            // Get current step to check if it was a Prompt step
             const currentStep = await this.getStepById(flowState.currentStepId);
+            // If current step was a Prompt, update payload with the prompt result
             if (currentStep?.StepType === 'Prompt' && promptResult) {
+                // Parse the prompt result as JSON
                 const promptResponse = this.parseJSONResponse(promptResult);
                 if (promptResponse) {
+                    // Check if the prompt response contains a Chat step request
+                    // This handles the case where a Prompt step wants to return a message to the user
                     if (promptResponse.nextStep?.type === 'Chat' ||
                         (promptResponse.taskComplete && promptResponse.message)) {
+                        // Return a Chat step to bubble the message back to the user
                         return this.createNextStep('Chat', {
                             message: promptResponse.message || 'Response from flow prompt step',
                             reasoning: promptResponse.reasoning,
                             confidence: promptResponse.confidence,
-                            terminate: true,
+                            terminate: true, // Always terminate for chat responses
                             newPayload: payload,
                             previousPayload: payload
                         });
                     }
+                    // Deep merge the prompt response into the current payload
+                    // This preserves existing nested properties while adding/updating from the prompt
+                    // Example: If payload has {decision: {Y: 4, Z: 2}} and prompt returns {decision: {x: "string"}},
+                    // the result will be {decision: {x: "string", Y: 4, Z: 2}} instead of losing Y and Z
                     const mergedPayload = this._payloadManager.deepMerge(payload, promptResponse);
+                    // Copy merged result back to payload reference (modifying in place for consistency)
                     Object.assign(payload, mergedPayload);
                 }
+                // Store the prompt step result so path conditions can access it
+                // Create a result object with Success: true (prompt executed successfully)
                 const promptStepResult = {
                     Success: true,
                     step: 'Success',
@@ -70,30 +148,39 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                     rawResult: promptResult
                 };
                 flowState.stepResults.set(flowState.currentStepId, promptStepResult);
+                // Add to execution path if not already present
                 if (!flowState.executionPath.includes(flowState.currentStepId)) {
                     flowState.executionPath.push(flowState.currentStepId);
                 }
+                // Mark step as completed
                 flowState.completedStepIds.add(flowState.currentStepId);
             }
+            // Find valid paths from current step
+            // Pass params to enable data/context access in path conditions (Phase 1)
             const paths = await this.getValidPaths(flowState.currentStepId, payload, flowState, params);
             if (paths.length === 0) {
+                // No valid paths - flow is complete
                 return this.createSuccessStep({
                     message: 'Flow completed - no more paths to follow'
                 });
             }
+            // Get the destination step for the highest priority path
             const nextStep = await this.getStepById(paths[0].DestinationStepID);
             if (!nextStep) {
                 return this.createNextStep('Failed', {
                     errorMessage: `Destination step not found: ${paths[0].DestinationStepID}`
                 });
             }
+            // Check if the step is active
             if (nextStep.Status !== 'Active') {
+                // Step is disabled or pending - find next valid path
                 for (let i = 1; i < paths.length; i++) {
                     const alternateStep = await this.getStepById(paths[i].DestinationStepID);
                     if (alternateStep && alternateStep.Status === 'Active') {
                         return await this.createStepForFlowNode(params, alternateStep, payload, flowState);
                     }
                 }
+                // No active steps found in any path
                 return this.createNextStep('Failed', {
                     errorMessage: `No active steps found. Step '${nextStep.Name}' has status: ${nextStep.Status}`
                 });
@@ -101,12 +188,19 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
             return await this.createStepForFlowNode(params, nextStep, payload, flowState);
         }
         catch (error) {
-            (0, core_1.LogError)(`Error in FlowAgentType.DetermineNextStep: ${error.message}`);
+            LogError(`Error in FlowAgentType.DetermineNextStep: ${error.message}`);
             return this.createNextStep('Failed', {
                 errorMessage: `Flow execution error: ${error.message}`
             });
         }
     }
+    /**
+     * Injects flow-specific context into the prompt parameters.
+     *
+     * @param {P} payload - The payload to inject
+     * @param {AIPromptParams} prompt - The prompt parameters to update
+     * @param {object} agentInfo - Agent identification info
+     */
     async InjectPayload(payload, agentState, prompt, agentInfo) {
         if (!prompt) {
             throw new Error('Prompt parameters are required for payload injection');
@@ -114,7 +208,9 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
         if (!prompt.data) {
             prompt.data = {};
         }
-        prompt.data[base_agent_type_1.BaseAgentType.CURRENT_PAYLOAD_PLACEHOLDER] = payload || {};
+        // Inject standard payload
+        prompt.data[BaseAgentType.CURRENT_PAYLOAD_PLACEHOLDER] = payload || {};
+        // Add flow-specific context from our state tracking
         if (agentInfo.agentRunId) {
             const flowState = agentState;
             if (agentState) {
@@ -127,28 +223,66 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
             }
         }
     }
+    /**
+     * Gets all starting steps for an agent
+     *
+     * @private
+     */
     async getStartingSteps(agentId) {
-        const steps = aiengine_1.AIEngine.Instance.GetAgentSteps(agentId, 'Active');
+        const steps = AIEngine.Instance.GetAgentSteps(agentId, 'Active');
         return steps.filter(step => step.StartingStep).sort((a, b) => a.Name.localeCompare(b.Name));
     }
+    /**
+     * Gets a step by ID
+     *
+     * @private
+     */
     async getStepById(stepId) {
-        return aiengine_1.AIEngine.Instance.GetAgentStepByID(stepId);
+        return AIEngine.Instance.GetAgentStepByID(stepId);
     }
+    /**
+     * Gets a step by name within an agent
+     *
+     * @private
+     */
     async getStepByName(agentId, stepName) {
-        const steps = aiengine_1.AIEngine.Instance.GetAgentSteps(agentId);
+        const steps = AIEngine.Instance.GetAgentSteps(agentId);
         return steps.find(step => step.Name === stepName) || null;
     }
+    /**
+     * Gets all paths from a step and evaluates their conditions.
+     *
+     * The evaluation context includes:
+     * - payload: The current agent payload (persistent state)
+     * - stepResult: Result from the last executed step
+     * - flowContext: Flow execution metadata (current step, completed steps, path)
+     * - data: Transient template data from ExecuteAgentParams (NEW in Phase 1)
+     * - context: Runtime context from ExecuteAgentParams (NEW in Phase 1)
+     *
+     * This allows path conditions to access runtime parameters like:
+     * - `data.userApproval === true`
+     * - `context.environment === 'production'`
+     * - `data.retryCount < 3 && payload.status === 'pending'`
+     *
+     * @private
+     */
     async getValidPaths(stepId, payload, flowState, params) {
-        const allPaths = aiengine_1.AIEngine.Instance.GetPathsFromStep(stepId)
+        // Load all paths from this step
+        const allPaths = AIEngine.Instance.GetPathsFromStep(stepId)
             .sort((a, b) => b.Priority - a.Priority);
         const validPaths = [];
+        // Evaluate each path's condition
         for (const path of allPaths) {
+            // If no condition, path is always valid
             if (!path.Condition) {
                 validPaths.push(path);
                 continue;
             }
             try {
+                // Create enhanced evaluation context
+                // Phase 1: Read-only access to data and context for path conditions
                 const context = {
+                    // Existing context properties
                     payload,
                     stepResult: this.getLastStepResult(flowState),
                     flowContext: {
@@ -157,6 +291,9 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                         executionPath: flowState.executionPath,
                         stepCount: flowState.completedStepIds.size
                     },
+                    // NEW: Map params.data and params.context directly
+                    // These enable deterministic routing based on runtime state
+                    // without polluting the persistent payload
                     data: params.data || {},
                     context: params.context || {}
                 };
@@ -165,41 +302,69 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                     validPaths.push(path);
                 }
                 else if (!evalResult.success) {
-                    (0, core_1.LogError)(`Path condition failed: ${path.Condition}\n${evalResult.error}`);
+                    // Only log errors when evaluation failed, not when condition is simply false
+                    LogError(`Path condition failed: ${path.Condition}\n${evalResult.error}`);
                 }
             }
             catch (error) {
-                (0, core_1.LogError)(`Failed to evaluate path condition: ${error.message}`);
+                LogError(`Failed to evaluate path condition: ${error.message}`);
             }
         }
+        // If no valid paths with conditions, include paths with priority <= 0 (defaults)
         if (validPaths.length === 0) {
             return allPaths.filter(p => p.Priority <= 0 && !p.Condition);
         }
+        // Sort by priority (already sorted by query, but re-sort valid subset)
         return validPaths.sort((a, b) => b.Priority - a.Priority);
     }
+    /**
+     * Gets the last step result from the flow context
+     *
+     * @private
+     */
     getLastStepResult(flowState) {
         if (flowState.executionPath.length === 0)
             return null;
         const lastStepId = flowState.executionPath[flowState.executionPath.length - 1];
         return flowState.stepResults.get(lastStepId) || null;
     }
+    /**
+     * Helper to set a value on a target object, supporting array append syntax.
+     * If key ends with '[]', the value is pushed to an array (auto-initialized if needed).
+     *
+     * @private
+     */
     setMappedValue(target, key, value) {
         const isArrayAppend = key.endsWith('[]');
         const actualKey = isArrayAppend ? key.slice(0, -2) : key;
         if (isArrayAppend) {
+            // Initialize array if it doesn't exist
             if (!(actualKey in target)) {
                 target[actualKey] = [];
             }
+            // Validate it's actually an array
             if (!Array.isArray(target[actualKey])) {
                 throw new Error(`Cannot append to '${actualKey}': target is not an array. ` +
                     `Use '${actualKey}' without [] suffix for property update.`);
             }
+            // Append the value
             target[actualKey].push(value);
         }
         else {
+            // Standard property assignment
             target[actualKey] = value;
         }
     }
+    /**
+     * Applies action output mapping to update the payload and extract special fields.
+     *
+     * Special fields ($message, $reasoning, $confidence) are prefixed with $ and are not
+     * added to the payload. Instead, they are stored separately in FlowExecutionState
+     * for use in the final response.
+     *
+     * @private
+     * @returns Object with payloadChange and specialFields
+     */
     applyActionOutputMapping(actionResult, _payload, mappingConfig) {
         try {
             const mapping = JSON.parse(mappingConfig);
@@ -211,10 +376,12 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                     value = actionResult;
                 }
                 else if (outputParam.includes('.')) {
+                    // Support dot notation for nested property access (e.g., "AgentSpec.ID")
                     const parts = outputParam.split('.');
                     value = actionResult;
                     for (const part of parts) {
                         if (value && typeof value === 'object' && !Array.isArray(value)) {
+                            // Case-insensitive lookup at each level
                             const actualKey = Object.keys(value).find(key => key.toLowerCase() === part.toLowerCase());
                             value = actualKey ? value[actualKey] : undefined;
                         }
@@ -225,12 +392,15 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                     }
                 }
                 else {
+                    // Simple case-insensitive lookup for non-dotted output parameters
                     const actualKey = Object.keys(actionResult).find(key => key.toLowerCase() === outputParam.toLowerCase());
                     value = actualKey ? actionResult[actualKey] : undefined;
                 }
                 if (value !== undefined) {
+                    // Check if this is a special field mapping (starts with $)
                     if (payloadPath.startsWith('$')) {
                         const fieldName = payloadPath.substring(1).toLowerCase();
+                        // Store in special fields instead of payload
                         if (fieldName === 'message' && typeof value === 'string') {
                             specialFields.message = value;
                         }
@@ -240,21 +410,26 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                         else if (fieldName === 'confidence' && typeof value === 'number') {
                             specialFields.confidence = value;
                         }
+                        // Ignore unknown special fields with warning
                         else {
-                            (0, core_1.LogError)(`Unknown special field in ActionOutputMapping: ${payloadPath}. Valid special fields are: $message, $reasoning, $confidence`);
+                            LogError(`Unknown special field in ActionOutputMapping: ${payloadPath}. Valid special fields are: $message, $reasoning, $confidence`);
                         }
                     }
                     else {
+                        // Regular payload mapping
+                        // Parse the path and build nested object
                         const pathParts = payloadPath.split('.');
                         let current = updateObj;
                         for (let i = 0; i < pathParts.length - 1; i++) {
                             const part = pathParts[i];
+                            // Remove [] suffix for intermediate path parts
                             const cleanPart = part.endsWith('[]') ? part.slice(0, -2) : part;
                             if (!(cleanPart in current)) {
                                 current[cleanPart] = {};
                             }
                             current = current[cleanPart];
                         }
+                        // Use helper to support array append on final path part
                         this.setMappedValue(current, pathParts[pathParts.length - 1], value);
                     }
                 }
@@ -268,26 +443,41 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
             };
         }
         catch (error) {
-            (0, core_1.LogError)(`Failed to parse ActionOutputMapping: ${error.message}`);
+            LogError(`Failed to parse ActionOutputMapping: ${error.message}`);
             return { payloadChange: null };
         }
     }
+    /**
+     * Creates a BaseAgentNextStep for a flow node.
+     *
+     * If the node is in agentTypeParams.skipSteps, the step is marked as skipped
+     * and we immediately evaluate paths to find the next step.
+     *
+     * @private
+     */
     async createStepForFlowNode(params, node, payload, flowState) {
+        // Check if this step should be skipped
         const flowParams = params.agentTypeParams;
         if (flowParams?.skipSteps && flowParams.skipSteps.some(s => s.ID === node.ID)) {
-            (0, core_1.LogStatus)(`Flow Agent: Skipping step '${node.Name}' (via agentTypeParams.skipSteps)`);
+            LogStatus(`Flow Agent: Skipping step '${node.Name}' (via agentTypeParams.skipSteps)`);
+            // Update flow state to mark this as current step (for path evaluation)
             flowState.currentStepId = node.ID;
+            // Mark the step as completed (skipped)
             flowState.completedStepIds.add(node.ID);
             flowState.executionPath.push(node.ID);
+            // Store a skip marker as the step result
             flowState.stepResults.set(node.ID, { skipped: true, stepName: node.Name });
+            // Find the next step by evaluating paths from this skipped step
             const paths = await this.getValidPaths(node.ID, payload, flowState, params);
             if (paths.length === 0) {
+                // No more paths - flow is complete
                 return this.createSuccessStep({
                     message: `Flow completed after skipping step '${node.Name}' - no more paths to follow`,
                     newPayload: payload,
                     previousPayload: payload
                 });
             }
+            // Get the destination step for the highest priority path
             const nextStep = await this.getStepById(paths[0].DestinationStepID);
             if (!nextStep) {
                 return this.createNextStep('Failed', {
@@ -296,8 +486,10 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                     previousPayload: payload
                 });
             }
+            // Recursively create the step for the next node (which may also be skipped)
             return await this.createStepForFlowNode(params, nextStep, payload, flowState);
         }
+        // Update flow state to mark this as current step
         flowState.currentStepId = node.ID;
         switch (node.StepType) {
             case 'Action':
@@ -308,6 +500,7 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                         previousPayload: payload
                     });
                 }
+                // Need to get the action name
                 const actionName = await this.getActionName(node.ActionID);
                 if (!actionName) {
                     return this.createNextStep('Failed', {
@@ -316,15 +509,18 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                         previousPayload: payload
                     });
                 }
+                // Check if we have output mapping configured
                 const baseStep = this.createNextStep('Actions', {
                     actions: [{
                             name: actionName,
-                            params: {}
+                            params: {} // Future: support parameter mapping
                         }],
                     terminate: false,
                     newPayload: payload,
                     previousPayload: payload
                 });
+                // Store the mapping config in a special property for later use
+                // Always set stepId for action steps so PreProcessActionStep can access step entity
                 baseStep.stepId = node.ID;
                 if (node.ActionOutputMapping) {
                     baseStep.actionOutputMapping = node.ActionOutputMapping;
@@ -338,6 +534,7 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                         previousPayload: payload
                     });
                 }
+                // Need to get the sub-agent name
                 const subAgentName = await this.getAgentName(node.SubAgentID);
                 if (!subAgentName) {
                     return this.createNextStep('Failed', {
@@ -346,18 +543,25 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                         previousPayload: payload
                     });
                 }
+                // Use node description to define the sub-agent's task
+                // The full conversation history is preserved in params.conversationMessages
+                // and will be available to the sub-agent through BaseAgent.ExecuteSubAgent()
+                // Propagate context to sub-agent so it has access to runtime configuration,
+                // API keys, environment settings, etc. from the parent agent
                 return this.createNextStep('Sub-Agent', {
                     subAgent: {
                         name: subAgentName,
                         message: node.Description || '',
                         terminateAfter: false,
-                        context: params.context
+                        context: params.context // Propagate runtime context to sub-agent
                     },
                     terminate: false,
                     newPayload: payload,
                     previousPayload: payload
                 });
             case 'Prompt':
+                // For prompt steps, we use Retry with a special marker
+                // The base agent will need to handle this case
                 if (!node.PromptID) {
                     return this.createNextStep('Failed', {
                         errorMessage: `Prompt step '${node.Name}' has no PromptID`,
@@ -369,6 +573,7 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                     step: 'Retry',
                     message: node.Description || 'Executing prompt step for flow decision',
                     terminate: false,
+                    // Special marker for flow prompt steps
                     flowPromptStepId: node.PromptID,
                     newPayload: payload,
                     previousPayload: payload
@@ -386,79 +591,137 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                 });
         }
     }
+    /**
+     * Gets action name by ID
+     *
+     * @private
+     */
     async getActionName(actionId) {
-        const action = actions_1.ActionEngineServer.Instance.Actions.find(a => a.ID === actionId);
+        const action = ActionEngineServer.Instance.Actions.find(a => a.ID === actionId);
         return action?.Name || null;
     }
+    /**
+     * Gets agent name by ID
+     *
+     * @private
+     */
     async getAgentName(agentId) {
-        const agent = aiengine_1.AIEngine.Instance.Agents.find(a => a.ID === agentId);
+        const agent = AIEngine.Instance.Agents.find(a => a.ID === agentId);
         return agent?.Name || null;
     }
+    /**
+     * Processes action results and applies output mapping if configured
+     * This should be called by BaseAgent after action execution
+     *
+     * @public
+     */
     processActionResult(actionResult, _stepId, outputMapping, currentPayload) {
         if (!outputMapping) {
             return null;
         }
         const result = this.applyActionOutputMapping(actionResult, currentPayload || {}, outputMapping);
+        // Note: Special fields are ignored in this legacy method
+        // Use PostProcessActionStep for full special field support
         return result.payloadChange;
     }
+    /**
+     * Override of BaseAgentType's PreProcessActionStep to handle Flow-specific input mapping.
+     *
+     * This method checks if the current step has action input mapping configured
+     * and applies it to map payload values or static values to action input parameters.
+     *
+     * @override
+     * @param {AgentAction[]} actions - The actions that will be executed (modified in place)
+     * @param {P} currentPayload - The current payload
+     * @param {BaseAgentNextStep<P>} currentStep - The current step being executed
+     *
+     * @returns {Promise<void>} Actions are modified in place
+     *
+     * @since 2.76.0
+     */
     async PreProcessActionStep(actions, currentPayload, agentTypeState, currentStep, params) {
+        // Try to find the flow state and use its payload if available
         const stepMetadata = currentStep;
         const stepId = stepMetadata.stepId;
         if (!stepId || actions.length === 0) {
+            // No step ID or no actions to process
             return;
         }
-        const stepEntity = aiengine_1.AIEngine.Instance.GetAgentStepByID(stepId);
+        // Get the AIAgentStep from cached metadata
+        const stepEntity = AIEngine.Instance.GetAgentStepByID(stepId);
         if (!stepEntity) {
-            (0, core_1.LogError)(`Failed to find AIAgentStep for input mapping: ${stepId}`);
+            LogError(`Failed to find AIAgentStep for input mapping: ${stepId}`);
             return;
         }
         if (!stepEntity.ActionInputMapping) {
+            // No input mapping configured
             return;
         }
+        // For flow agents, we currently only support single action steps with input mapping
+        // Future enhancement: support mapping to multiple actions
         if (actions.length > 1) {
-            (0, core_1.LogError)('Flow agent action input mapping currently only supports single action steps');
+            LogError('Flow agent action input mapping currently only supports single action steps');
             return;
         }
         try {
+            // Parse the input mapping configuration
+            // Expected format: { "paramName": "payload.path.to.value" | "static:value" | 123 | true }
             let inputMapping;
             if (typeof stepEntity.ActionInputMapping === 'string') {
+                // ActionInputMapping is a JSON string - parse it
                 inputMapping = JSON.parse(stepEntity.ActionInputMapping);
             }
             else if (typeof stepEntity.ActionInputMapping === 'object' && stepEntity.ActionInputMapping !== null) {
+                // ActionInputMapping is already an object - use it directly
                 inputMapping = stepEntity.ActionInputMapping;
             }
             else {
-                (0, core_1.LogError)(`Invalid ActionInputMapping format for step ${stepEntity.Name}: ${stepEntity.ActionInputMapping}`);
+                // ActionInputMapping is null or invalid
+                LogError(`Invalid ActionInputMapping format for step ${stepEntity.Name}: ${stepEntity.ActionInputMapping}`);
                 return;
             }
             const action = actions[0];
+            // Initialize params if not present
             if (!action.params) {
                 action.params = {};
             }
+            // Apply each mapping
             for (const [paramName, mappingValue] of Object.entries(inputMapping)) {
+                // Use recursive resolution to handle nested objects, arrays, and primitive values
                 const resolvedValue = this.resolveNestedValue(mappingValue, currentPayload, params);
+                // Set the parameter value
                 action.params[paramName] = resolvedValue;
             }
-            if ((0, core_1.IsVerboseLoggingEnabled)()) {
+            if (IsVerboseLoggingEnabled()) {
                 console.log(`Applied action input mapping for step ${stepEntity.Name}:`, action.params);
             }
         }
         catch (error) {
-            (0, core_1.LogError)(`Failed to apply action input mapping: ${error.message}`);
+            LogError(`Failed to apply action input mapping: ${error.message}`);
         }
     }
+    /**
+     * Helper method to get a value from a nested object path
+     * Supports both dot notation (obj.prop) and array indexing (arr[0])
+     *
+     * @private
+     */
     getValueFromPath(obj, path) {
         const parts = path.split('.');
         let current = obj;
         for (const part of parts) {
             if (!part)
                 continue;
+            // Check if this part contains array indexing like "arrayName[0]"
             const arrayMatch = part.match(/^([^[]+)\[(\d+)\]$/);
             if (arrayMatch) {
+                // Extract array name and index
                 const arrayName = arrayMatch[1];
                 const index = parseInt(arrayMatch[2], 10);
+                // Navigate to the array
                 if (current && typeof current === 'object' && arrayName in current) {
                     current = current[arrayName];
+                    // Access the array element
                     if (Array.isArray(current) && index >= 0 && index < current.length) {
                         current = current[index];
                     }
@@ -471,6 +734,7 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                 }
             }
             else {
+                // Regular property access
                 if (current && typeof current === 'object' && part in current) {
                     current = current[part];
                 }
@@ -481,11 +745,25 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
         }
         return current;
     }
+    /**
+     * Recursively resolves payload, static, data, context, and conversation references in nested objects.
+     *
+     * Supported prefixes:
+     * - `payload.path.to.value` - reads from persistent payload
+     * - `static:value` - literal static value
+     * - `data.path.to.value` - reads from params.data (template data)
+     * - `context.path.to.value` - reads from params.context (runtime context, e.g., API keys, environment)
+     * - `conversation[N].content` - reads from conversation messages
+     *
+     * @private
+     */
     resolveNestedValue(value, currentPayload, params) {
         if (typeof value === 'string') {
+            // Handle string values with payload/static/data/context/conversation resolution (case-insensitive)
             const trimmedValue = value.trim();
-            if (ConversationMessageResolver_1.ConversationMessageResolver.isConversationReference(trimmedValue) && params?.conversationMessages) {
-                return ConversationMessageResolver_1.ConversationMessageResolver.resolve(trimmedValue, params.conversationMessages);
+            // Check for conversation message references
+            if (ConversationMessageResolver.isConversationReference(trimmedValue) && params?.conversationMessages) {
+                return ConversationMessageResolver.resolve(trimmedValue, params.conversationMessages);
             }
             else if (trimmedValue.toLowerCase().startsWith('static:')) {
                 return value.substring(value.indexOf(':') + 1);
@@ -501,6 +779,8 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                 return this.getValueFromPath(params.data, path);
             }
             else if (trimmedValue.toLowerCase().startsWith('context.') && params?.context) {
+                // NEW: Support context. prefix for accessing runtime context
+                // This allows action input mappings to reference API keys, environment settings, etc.
                 const pathStart = value.indexOf('.') + 1;
                 const path = value.substring(pathStart);
                 return this.getValueFromPath(params.context, path);
@@ -510,9 +790,11 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
             }
         }
         else if (Array.isArray(value)) {
+            // Handle arrays - recursively resolve each element
             return value.map(item => this.resolveNestedValue(item, currentPayload, params));
         }
         else if (value && typeof value === 'object') {
+            // Handle objects - recursively resolve each property
             const resolvedObj = {};
             for (const [key, val] of Object.entries(value)) {
                 resolvedObj[key] = this.resolveNestedValue(val, currentPayload, params);
@@ -520,22 +802,43 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
             return resolvedObj;
         }
         else {
+            // Handle primitives (numbers, booleans, null, undefined)
             return value;
         }
     }
+    /**
+     * Override of BaseAgentType's PostProcessActionStep to handle Flow-specific logic.
+     *
+     * This method checks if the current step has action output mapping configured
+     * and applies it to update the payload accordingly.
+     *
+     * @override
+     * @param {ActionResult[]} actionResults - The results from action execution
+     * @param {AgentAction[]} actions - The actions that were executed
+     * @param {P} currentPayload - The current payload
+     * @param {BaseAgentNextStep<P>} currentStep - The current step being executed
+     *
+     * @returns {Promise<AgentPayloadChangeRequest<P> | null>} Payload changes from output mapping
+     */
     async PostProcessActionStep(actionResults, actions, currentPayload, agentTypeState, currentStep) {
+        // Check if this step has action output mapping configured
         const stepMetadata = currentStep;
         const outputMapping = stepMetadata.actionOutputMapping;
         const stepId = stepMetadata.stepId;
         if (!outputMapping || !stepId || actionResults.length === 0) {
+            // No mapping configured or no results to process
             return null;
         }
+        // For flow agents, we currently only support single action steps with output mapping
+        // Future enhancement: support mapping from multiple actions
         if (actionResults.length > 1) {
-            (0, core_1.LogError)('Flow agent action output mapping currently only supports single action steps');
+            LogError('Flow agent action output mapping currently only supports single action steps');
             return null;
         }
+        // Extract output parameters from the action result
         const actionResult = actionResults[0];
         const outputParams = {};
+        // Filter for output parameters (Type === 'Output' or 'Both')
         if (actionResult.Params) {
             for (const param of actionResult.Params) {
                 if (param.Type === 'Output' || param.Type === 'Both') {
@@ -543,61 +846,114 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                 }
             }
         }
+        // Apply the mapping using our existing method
         const result = this.applyActionOutputMapping(outputParams, currentPayload, outputMapping);
         const payloadChange = result.payloadChange;
+        // Store special fields in flow state for later use
         const flowState = agentTypeState;
         if (result.specialFields) {
             if (!flowState.specialFields) {
                 flowState.specialFields = {};
             }
+            // Merge special fields (later values override earlier ones)
             Object.assign(flowState.specialFields, result.specialFields);
         }
+        // Update flow state with the modified payload
+        // This ensures the payload persists when DetermineNextStep is called again
         if (payloadChange && payloadChange.updateElements) {
             const existingPayload = currentPayload || {};
+            // Apply the payload change using PayloadManager's merge capabilities
             const mergeResult = this._payloadManager.applyAgentChangeRequest(existingPayload, payloadChange, {
                 logChanges: false,
-                verbose: (0, core_1.IsVerboseLoggingEnabled)()
+                verbose: IsVerboseLoggingEnabled()
             });
+            // Log any warnings if present
             if (mergeResult.warnings && mergeResult.warnings.length > 0) {
-                (0, core_1.LogError)(`Warnings during payload merge in flow state: ${mergeResult.warnings.join(', ')}`);
+                LogError(`Warnings during payload merge in flow state: ${mergeResult.warnings.join(', ')}`);
             }
         }
         return payloadChange;
     }
+    /**
+     * Determines the initial step for flow agent types.
+     *
+     * Flow agents look up their configured starting step instead of executing a prompt.
+     * If agentTypeParams.startAtStep is provided, the flow will begin at that step
+     * instead of the configured entry point.
+     *
+     * @param {ExecuteAgentParams} params - The full execution parameters
+     * @returns {Promise<BaseAgentNextStep<P> | null>} The initial step to execute, or null if flow context not ready
+     *
+     * @override
+     * @since 2.76.0
+     */
     async DetermineInitialStep(params, payload, agentTypeState) {
         const flowState = agentTypeState;
         const payloadToUse = payload || {};
+        // Check for startAtStep in agentTypeParams (FlowAgentExecuteParams)
         const flowParams = params.agentTypeParams;
         if (flowParams?.startAtStep) {
-            const agentSteps = aiengine_1.AIEngine.Instance.GetAgentSteps(flowState.agentId);
+            // Validate the step belongs to this agent
+            const agentSteps = AIEngine.Instance.GetAgentSteps(flowState.agentId);
             const validStep = agentSteps.find(s => s.ID === flowParams.startAtStep.ID);
             if (!validStep) {
                 return this.createNextStep('Failed', {
                     errorMessage: `startAtStep '${flowParams.startAtStep.Name}' (ID: ${flowParams.startAtStep.ID}) does not belong to agent '${params.agent.Name}'`
                 });
             }
-            (0, core_1.LogStatus)(`Flow Agent: Starting at step '${validStep.Name}' (override via agentTypeParams.startAtStep)`);
+            LogStatus(`Flow Agent: Starting at step '${validStep.Name}' (override via agentTypeParams.startAtStep)`);
             return await this.createStepForFlowNode(params, validStep, payloadToUse, flowState);
         }
+        // Default behavior: start at the configured entry point
         const startingSteps = await this.getStartingSteps(flowState.agentId);
         if (startingSteps.length === 0) {
             return this.createNextStep('Failed', {
                 errorMessage: 'No starting steps defined for flow agent'
             });
         }
+        // Execute the first starting step
+        // Future enhancement: support parallel starting steps
         return await this.createStepForFlowNode(params, startingSteps[0], payloadToUse, flowState);
     }
+    /**
+     * Pre-processes steps for flow agent types.
+     *
+     * For Flow agents, 'Retry' after actions means evaluate paths from the current step
+     * and continue the flow based on the updated payload. The only exception is when
+     * executing a Prompt step within the flow, which should execute normally.
+     *
+     * Also, 'Success' steps after sub-agents need to be evaluated in the same way as Retry after actions
+     *
+     * @param {ExecuteAgentParams} params - The full execution parameters
+     * @param {BaseAgentNextStep} step - The retry step that was returned
+     * @param {P} payload - The current payload
+     * @param {ATS} agentTypeState - The current agent type state
+     * @returns {Promise<BaseAgentNextStep<P> | null>} The next flow step, or null for prompt execution
+     *
+     * @override
+     * @since 2.76.0
+     */
     async PreProcessNextStep(params, step, payload, agentTypeState) {
+        // we only want to do special processing for retry, success, or failed steps
+        // Failed steps need to be evaluated for conditional failure paths
         if (step.step !== 'Retry' && step.step !== 'Success' && step.step !== 'Failed') {
+            // Not a retry, success, or failed step - use default processing
             return null;
         }
+        // Check if this is a special flow prompt step marker
         const flowStep = step;
         if (flowStep.flowPromptStepId) {
+            // This is a prompt step in the flow, let it execute normally
             return null;
         }
+        // Get the updated payload (after action execution)
         const payloadFromStep = payload || step.newPayload || params.payload || {};
         const flowState = agentTypeState;
+        // CRITICAL FIX: Don't overwrite the flow state's payload if it already has accumulated data
+        // The retry step only contains the action's output mapping result, not the full payload
+        // If flow state already has a payload with more data, keep it
         let currentPayload = payloadFromStep;
+        // We should have a current step ID from the flow state
         if (!flowState.currentStepId) {
             return this.createNextStep('Failed', {
                 errorMessage: 'No current step in flow state after action execution',
@@ -605,15 +961,23 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                 previousPayload: currentPayload
             });
         }
+        // Store the step result so path conditions can access it via stepResult
+        // The step parameter contains the result from the just-completed step (Sub-Agent, Action, or Prompt)
         flowState.stepResults.set(flowState.currentStepId, step);
+        // Add to execution path if not already present
         if (!flowState.executionPath.includes(flowState.currentStepId)) {
             flowState.executionPath.push(flowState.currentStepId);
         }
+        // Mark step as completed
         flowState.completedStepIds.add(flowState.currentStepId);
+        // Find valid paths from current step using updated payload
+        // Pass params to enable data/context access in path conditions (Phase 1)
         const paths = await this.getValidPaths(flowState.currentStepId, currentPayload, flowState, params);
         if (paths.length === 0) {
+            // No valid paths found
+            // If the previous step failed, propagate the failure with its error message
             if (step.step === 'Failed') {
-                (0, core_1.LogStatusEx)({
+                LogStatusEx({
                     message: `⚠️ Flow Agent: Step failed with no recovery path. Error: ${step.errorMessage || 'No error message'}`,
                     verboseOnly: false
                 });
@@ -624,10 +988,12 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                     terminate: true
                 });
             }
-            (0, core_1.LogStatusEx)({
+            // Otherwise, flow completed successfully
+            LogStatusEx({
                 message: '✅ Flow Agent: Flow completed successfully - no more paths to follow',
                 verboseOnly: true
             });
+            // Include special fields from action output mappings if available
             const successStep = this.createSuccessStep({
                 message: flowState.specialFields?.message || 'Flow completed - no more paths to follow',
                 reasoning: flowState.specialFields?.reasoning,
@@ -637,24 +1003,28 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
             });
             return successStep;
         }
+        // Get the destination step for the highest priority path
         const nextStep = await this.getStepById(paths[0].DestinationStepID);
         if (!nextStep) {
             return this.createNextStep('Failed', {
                 errorMessage: `Destination step not found: ${paths[0].DestinationStepID}`
             });
         }
+        // Log when we're navigating to a recovery path after a failure
         if (step.step === 'Failed') {
-            (0, core_1.LogStatusEx)({
+            LogStatusEx({
                 message: `🔄 Flow Agent: Failure detected, navigating to recovery path: '${nextStep.Name}'`,
                 verboseOnly: false
             });
         }
+        // Check if the step is active
         if (nextStep.Status !== 'Active') {
+            // Try alternate paths
             for (let i = 1; i < paths.length; i++) {
                 const alternateStep = await this.getStepById(paths[i].DestinationStepID);
                 if (alternateStep && alternateStep.Status === 'Active') {
                     if (step.step === 'Failed') {
-                        (0, core_1.LogStatusEx)({
+                        LogStatusEx({
                             message: `🔄 Flow Agent: Using alternate recovery path: '${alternateStep.Name}'`,
                             verboseOnly: false
                         });
@@ -668,23 +1038,44 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                 previousPayload: currentPayload
             });
         }
+        // Create the next step based on the flow node
         return await this.createStepForFlowNode(params, nextStep, currentPayload, flowState);
     }
+    /**
+     * Gets the prompt to use for a specific step.
+     * Flow agents may use different prompts for different steps in the flow.
+     *
+     * @param {ExecuteAgentParams} params - The execution parameters
+     * @param {AgentConfiguration} config - The loaded agent configuration
+     * @param {BaseAgentNextStep | null} previousDecision - The previous step decision that may contain flow prompt info
+     * @returns {Promise<AIPromptEntityExtended | null>} Custom prompt for flow steps, or default config.childPrompt
+     *
+     * @override
+     * @since 2.76.0
+     */
     async GetPromptForStep(params, config, payload, agentTypeState, previousDecision) {
+        // Check if this is a flow prompt step with a specific prompt ID
         const flowDecision = previousDecision;
         if (flowDecision?.flowPromptStepId) {
             const promptId = flowDecision.flowPromptStepId;
-            const promptEntity = aiengine_1.AIEngine.Instance.Prompts.find(p => p.ID === promptId);
+            // Get the specific prompt from AIEngine (avoids database hit)
+            const promptEntity = AIEngine.Instance.Prompts.find(p => p.ID === promptId);
             if (promptEntity) {
                 return promptEntity;
             }
             else {
-                (0, core_1.LogError)(`Failed to find flow prompt with ID: ${promptId} in AIEngine`);
+                LogError(`Failed to find flow prompt with ID: ${promptId} in AIEngine`);
+                // Fall back to default
                 return config.childPrompt || null;
             }
         }
+        // For non-flow-prompt steps, use the default prompt
         return config.childPrompt || null;
     }
+    /**
+     * Converts a Flow Agent ForEach step into universal ForEachOperation format
+     * that BaseAgent can execute
+     */
     async convertForEachStepToOperation(node, payload, flowState, params) {
         if (!node.Configuration) {
             return this.createNextStep('Failed', {
@@ -693,7 +1084,9 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                 previousPayload: payload
             });
         }
+        // Parse base configuration from AIAgentStep
         const baseConfig = JSON.parse(node.Configuration);
+        // Build universal ForEachOperation
         const forEach = {
             collectionPath: baseConfig.collectionPath,
             itemVariable: baseConfig.itemVariable,
@@ -704,8 +1097,9 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
             executionMode: baseConfig.executionMode,
             maxConcurrency: baseConfig.maxConcurrency
         };
+        // Add action or subAgent based on LoopBodyType (using cached engine data - no await needed)
         if (node.LoopBodyType === 'Action') {
-            const action = aiengine_1.AIEngine.Instance.Actions.find(a => a.ID === node.ActionID);
+            const action = AIEngine.Instance.Actions.find(a => a.ID === node.ActionID);
             if (!action) {
                 return this.createNextStep('Failed', {
                     errorMessage: `Action not found for loop body: ${node.ActionID}`,
@@ -720,7 +1114,7 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
             };
         }
         else if (node.LoopBodyType === 'Sub-Agent') {
-            const subAgent = aiengine_1.AIEngine.Instance.Agents.find(a => a.ID === node.SubAgentID);
+            const subAgent = AIEngine.Instance.Agents.find(a => a.ID === node.SubAgentID);
             if (!subAgent) {
                 return this.createNextStep('Failed', {
                     errorMessage: `Sub-Agent not found for loop body: ${node.SubAgentID}`,
@@ -732,7 +1126,7 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                 name: subAgent.Name,
                 message: node.Description || `Execute sub-agent: ${subAgent.Name}`,
                 templateParameters: {},
-                context: params.context
+                context: params.context // Propagate runtime context to sub-agent in loop
             };
         }
         else if (node.LoopBodyType === 'Prompt') {
@@ -742,16 +1136,22 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                 previousPayload: payload
             });
         }
+        // Store stepId in flow state for later (when loop completes, we need to navigate paths)
         flowState.currentStepId = node.ID;
+        // Return ForEach decision for BaseAgent to execute
         return {
             step: 'ForEach',
             forEach,
             terminate: false,
             newPayload: payload,
             previousPayload: payload,
-            agentTypeData: { stepId: node.ID }
+            agentTypeData: { stepId: node.ID } // Flow needs to remember which step this is
         };
     }
+    /**
+     * Converts a Flow Agent While step into universal WhileOperation format
+     * that BaseAgent can execute
+     */
     async convertWhileStepToOperation(node, payload, flowState, params) {
         if (!node.Configuration) {
             return this.createNextStep('Failed', {
@@ -760,7 +1160,9 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                 previousPayload: payload
             });
         }
+        // Parse base configuration
         const baseConfig = JSON.parse(node.Configuration);
+        // Build universal WhileOperation
         const whileOp = {
             condition: baseConfig.condition,
             itemVariable: baseConfig.itemVariable,
@@ -768,8 +1170,9 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
             continueOnError: baseConfig.continueOnError,
             delayBetweenIterationsMs: baseConfig.delayBetweenIterationsMs
         };
+        // Add action or subAgent based on LoopBodyType
         if (node.LoopBodyType === 'Action') {
-            const action = aiengine_1.AIEngine.Instance.Actions.find(a => a.ID === node.ActionID);
+            const action = AIEngine.Instance.Actions.find(a => a.ID === node.ActionID);
             if (!action) {
                 return this.createNextStep('Failed', {
                     errorMessage: `Action not found for loop body: ${node.ActionID}`,
@@ -784,7 +1187,7 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
             };
         }
         else if (node.LoopBodyType === 'Sub-Agent') {
-            const subAgent = aiengine_1.AIEngine.Instance.Agents.find(a => a.ID === node.SubAgentID);
+            const subAgent = AIEngine.Instance.Agents.find(a => a.ID === node.SubAgentID);
             if (!subAgent) {
                 return this.createNextStep('Failed', {
                     errorMessage: `Sub-Agent not found for loop body: ${node.SubAgentID}`,
@@ -796,7 +1199,7 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                 name: subAgent.Name,
                 message: node.Description || `Execute sub-agent: ${subAgent.Name}`,
                 templateParameters: {},
-                context: params.context
+                context: params.context // Propagate runtime context to sub-agent in loop
             };
         }
         else if (node.LoopBodyType === 'Prompt') {
@@ -806,7 +1209,9 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                 previousPayload: payload
             });
         }
+        // Store stepId for later path navigation
         flowState.currentStepId = node.ID;
+        // Return While decision for BaseAgent to execute
         return {
             step: 'While',
             while: whileOp,
@@ -816,31 +1221,63 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
             agentTypeData: { stepId: node.ID }
         };
     }
+    /**
+     * Flow agents don't need loop results injected as messages - they navigate paths
+     * @override
+     */
     get InjectLoopResultsAsMessage() {
         return false;
     }
+    /**
+     * Flow agents don't require agent-level prompts - they use step-level prompts exclusively
+     * @override
+     */
     get RequiresAgentLevelPrompts() {
         return false;
     }
+    /**
+     * Provides Flow-specific guidance for prompt configuration
+     * @override
+     */
     GetPromptConfigurationGuidance() {
         return `   - Flow agents use step-level prompts (StepType="Prompt" with PromptID)\n` +
             `   - Prompts should be configured in agent steps, not AI Agent Prompts relationship\n` +
             `   - Verify that prompts exist in AI Prompts table and are active`;
     }
+    /**
+     * Flow agents should NEVER fall back to prompt execution for Success/Failed steps.
+     * Flow agents are deterministic and driven by their graph structure (steps and paths).
+     * When a step completes (Success or Failed), the agent should terminate rather than
+     * retry with prompts.
+     *
+     * @override
+     * @since 2.113.0
+     */
     async HandleStepFallback(step, config, params, payload, agentTypeState) {
+        // Flow agents NEVER fall back to prompt execution
+        // They are driven entirely by their graph structure (steps and paths)
+        // Success/Failed steps should terminate, not retry prompts
         if (step.step === 'Success' || step.step === 'Failed') {
+            // Use spread to preserve all properties and just override terminate
             return {
                 ...step,
                 terminate: true
             };
         }
+        // For other step types, use default behavior (should not reach here)
         return null;
     }
+    /**
+     * Flow agents apply ActionOutputMapping after each iteration
+     * @override
+     */
     AfterLoopIteration(iterationResult) {
         const loopContext = iterationResult.loopContext;
+        // Only apply for actions with output mapping
         if (!iterationResult.actionResults || !loopContext.actionOutputMapping) {
             return null;
         }
+        // Extract output parameters
         const outputParams = {};
         if (iterationResult.actionResults[0]?.Params) {
             for (const param of iterationResult.actionResults[0].Params) {
@@ -849,22 +1286,25 @@ let FlowAgentType = class FlowAgentType extends base_agent_type_1.BaseAgentType
                 }
             }
         }
+        // Replace iteration variables in output mapping paths before applying
         let resolvedOutputMapping = loopContext.actionOutputMapping;
         const indexVar = loopContext.indexVariable || 'index';
         const itemVar = loopContext.itemVariable || 'item';
+        // Replace [index] with [0], [1], etc.
         resolvedOutputMapping = resolvedOutputMapping.replace(new RegExp(`\\[${indexVar}\\]`, 'g'), `[${iterationResult.index}]`);
+        // Apply output mapping with resolved paths
         const result = this.applyActionOutputMapping(outputParams, iterationResult.currentPayload, resolvedOutputMapping);
+        // Note: Special fields are not supported in loop iterations
+        // They only apply to final flow steps
         if (result.payloadChange?.updateElements) {
+            // Deep merge to preserve existing payload structure
             return this._payloadManager.deepMerge(iterationResult.currentPayload, result.payloadChange.updateElements);
         }
         return null;
     }
 };
-exports.FlowAgentType = FlowAgentType;
-exports.FlowAgentType = FlowAgentType = __decorate([
-    (0, global_1.RegisterClass)(base_agent_type_1.BaseAgentType, "FlowAgentType")
+FlowAgentType = __decorate([
+    RegisterClass(BaseAgentType, "FlowAgentType")
 ], FlowAgentType);
-function LoadFlowAgentType() {
-}
-exports.LoadFlowAgentType = LoadFlowAgentType;
+export { FlowAgentType };
 //# sourceMappingURL=flow-agent-type.js.map