@memberjunction/ai-agents 3.4.0 → 4.0.0

package/dist/agent-types/loop-agent-type.d.ts

@@ -1,23 +1,160 @@
-import { BaseAgentType } from './base-agent-type';
+/**
+ * @fileoverview Implementation of the Loop Agent Type for iterative task execution.
+ *
+ * The LoopAgentType enables agents to operate in a continuous loop, making decisions
+ * about task completion and next steps based on the current state. It parses structured
+ * JSON responses from the AI model and translates them into BaseAgentNextStep directives.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ * @since 2.49.0
+ */
+import { BaseAgentType } from './base-agent-type.js';
 import { AIPromptRunResult, BaseAgentNextStep, AIPromptParams, ExecuteAgentParams, AgentConfiguration, AgentAction } from '@memberjunction/ai-core-plus';
 import { AIPromptEntityExtended } from '@memberjunction/ai-core-plus';
+/**
+ * Implementation of the Loop Agent Type pattern.
+ *
+ * This agent type enables iterative execution where the agent continues
+ * processing until a task is marked complete. It supports:
+ * - Task completion detection
+ * - Sub-agent delegation
+ * - Action execution
+ * - Progress tracking
+ * - Error handling
+ * - Result accumulation across iterations
+ *
+ * @class LoopAgentType
+ * @extends BaseAgentType
+ *
+ * @example
+ * ```typescript
+ * // The agent will execute in a loop until taskComplete is true
+ * const loopAgent = new LoopAgentType();
+ * const nextStep = await loopAgent.DetermineNextStep(promptResult);
+ *
+ * switch (nextStep.step) {
+ *   case 'success':
+ *     console.log('Task completed:', nextStep.payload);
+ *     break;
+ *   case 'sub-agent':
+ *     console.log('Delegating to:', nextStep.subAgentName);
+ *     break;
+ *   case 'action':
+ *     console.log('Executing action:', nextStep.actionName);
+ *     break;
+ * }
+ * ```
+ */
 export declare class LoopAgentType extends BaseAgentType {
     private _evaluator;
     InitializeAgentTypeState<ATS = any, P = any>(params: ExecuteAgentParams<any, P>): Promise<ATS>;
+    /**
+     * Determines the next step based on the structured response from the AI model.
+     *
+     * This method parses the JSON response from the loop agent prompt and translates
+     * it into appropriate BaseAgentNextStep directives. It handles task completion,
+     * sub-agent delegation, action execution, and error conditions.
+     *
+     * @param {AIPromptRunResult} promptResult - The result from executing the agent's prompt
+     * @returns {Promise<BaseAgentNextStep>} The next step to take in the agent execution
+     *
+     * @throws {Error} Implicitly through failed parsing, but returns failed step instead
+     */
     DetermineNextStep<P = any, ATS = any>(promptResult: AIPromptRunResult | null, params: ExecuteAgentParams<any, P>, payload: P, agentTypeState: ATS): Promise<BaseAgentNextStep<P>>;
+    /**
+     * Validates that the response conforms to the expected LoopAgentResponse structure.
+     *
+     * @param {any} response - The response to validate
+     * @returns {boolean} True if the response is valid, false otherwise
+     *
+     * @protected
+     */
     protected isValidLoopResponse(simpleResponse: unknown): {
         success: boolean;
         message?: string;
     };
+    /**
+     * Injects a payload into the prompt parameters.
+     * For LoopAgentType, this could be used to inject previous loop results or context.
+     *
+     * @param {T} payload - The payload to inject
+     * @param {AIPromptParams} prompt - The prompt parameters to update
+     * @param {object} agentInfo - Agent identification info (unused by LoopAgentType)
+     */
     InjectPayload<T = any, ATS = any>(payload: T, agentTypeState: ATS, prompt: AIPromptParams, agentInfo: {
         agentId: string;
         agentRunId?: string;
     }): Promise<void>;
+    /**
+     * Determines the initial step for loop agent types.
+     *
+     * Loop agents always start with a prompt execution to determine the initial actions.
+     *
+     * @param {ExecuteAgentParams} params - The full execution parameters
+     * @returns {Promise<BaseAgentNextStep<P> | null>} Always returns null to use default behavior
+     *
+     * @override
+     * @since 2.76.0
+     */
     DetermineInitialStep<P = any>(params: ExecuteAgentParams<P>): Promise<BaseAgentNextStep<P> | null>;
+    /**
+     * Pre-processes steps for loop agent types.
+     *
+     * Loop agents use the default next step behavior which executes the prompt again.
+     *
+     * @param {ExecuteAgentParams} params - The full execution parameters
+     * @param {BaseAgentNextStep} step - The step that needs to be preprocessed
+     * @returns {Promise<BaseAgentNextStep<P> | null>} Always returns null to use default behavior
+     *
+     * @override
+     * @since 2.76.0
+     */
     PreProcessNextStep<P = any, ATS = any>(params: ExecuteAgentParams<P>, step: BaseAgentNextStep<P>, payload: P, agentTypeState: ATS): Promise<BaseAgentNextStep<P> | null>;
+    /**
+     * Gets the prompt to use for a specific step.
+     * Loop agents always use the default prompt from configuration.
+     *
+     * @param {ExecuteAgentParams} params - The execution parameters (unused)
+     * @param {AgentConfiguration} config - The loaded agent configuration
+     * @param {BaseAgentNextStep | null} previousDecision - The previous step decision (unused)
+     * @returns {Promise<AIPromptEntityExtended | null>} Returns config.childPrompt
+     *
+     * @override
+     * @since 2.76.0
+     */
     GetPromptForStep<P = any, ATS = any>(params: ExecuteAgentParams, config: AgentConfiguration, payload: P, agentTypeState: ATS, previousDecision?: BaseAgentNextStep<P> | null): Promise<AIPromptEntityExtended | null>;
+    /**
+     * Pre-processes action parameters to resolve conversation references.
+     *
+     * Loop agents get action parameters directly from the LLM's JSON response.
+     * This method resolves any "conversation.*" references in those parameters
+     * before the actions are executed.
+     *
+     * @param {AgentAction[]} actions - The actions that will be executed (modified in place)
+     * @param {P} currentPayload - The current payload
+     * @param {ATS} agentTypeState - The agent type state
+     * @param {BaseAgentNextStep<P>} currentStep - The current step being executed
+     * @param {ExecuteAgentParams<P>} params - The execution parameters with conversation messages
+     *
+     * @returns {Promise<void>} Actions are modified in place
+     *
+     * @override
+     * @since 2.120.0
+     */
     PreProcessActionStep<P = any, ATS = any>(actions: AgentAction[], currentPayload: P, agentTypeState: ATS, currentStep: BaseAgentNextStep<P>, params?: ExecuteAgentParams<P>): Promise<void>;
+    /**
+     * Recursively resolves conversation references in action parameters.
+     *
+     * Handles nested objects and arrays, resolving any string values that start
+     * with "conversation." using the ConversationMessageResolver.
+     *
+     * @param {unknown} value - The value to resolve (can be object, array, string, or primitive)
+     * @param {ExecuteAgentParams} params - The execution parameters with conversation messages
+     * @returns {unknown} The resolved value
+     *
+     * @private
+     */
     private resolveConversationReferences;
 }
-export declare function LoadLoopAgentType(): void;
 //# sourceMappingURL=loop-agent-type.d.ts.map

package/dist/agent-types/loop-agent-type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop-agent-type.d.ts","sourceRoot":"","sources":["../../src/agent-types/loop-agent-type.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEzJ,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAsCtE,qBACa,aAAc,SAAQ,aAAa;IAC5C,OAAO,CAAC,UAAU,CAAiC;IAEtC,wBAAwB,CAAC,GAAG,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,kBAAkB,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC;IAkB9F,iBAAiB,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,EAC7C,YAAY,EAAE,iBAAiB,GAAG,IAAI,EACtC,MAAM,EAAE,kBAAkB,CAAC,GAAG,EAAE,CAAC,CAAC,EAClC,OAAO,EAAE,CAAC,EACV,cAAc,EAAE,GAAG,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAkJhC,SAAS,CAAC,mBAAmB,CAAC,cAAc,EAAE,OAAO,GAAG;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC;IA2I/E,aAAa,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,EACzC,OAAO,EAAE,CAAC,EACV,cAAc,EAAE,GAAG,EACnB,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GACpD,OAAO,CAAC,IAAI,CAAC;IAoBH,oBAAoB,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAiBlG,kBAAkB,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,EAC9C,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC7B,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC1B,OAAO,EAAE,CAAC,EACV,cAAc,EAAE,GAAG,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAiB1B,gBAAgB,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,EAC5C,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,CAAC,EACV,cAAc,EAAE,GAAG,EACnB,gBAAgB,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,GAC/C,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAuB5B,oBAAoB,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,EAChD,OAAO,EAAE,WAAW,EAAE,EACtB,cAAc,EAAE,CAAC,EACjB,cAAc,EAAE,GAAG,EACnB,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC,EACjC,MAAM,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC/B,OAAO,CAAC,IAAI,CAAC;IAqBhB,OAAO,CAAC,6BAA6B;CAyBxC;AAKD,wBAAgB,iBAAiB,SAEhC"}
+{"version":3,"file":"loop-agent-type.d.ts","sourceRoot":"","sources":["../../src/agent-types/loop-agent-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEzJ,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAItE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBACa,aAAc,SAAQ,aAAa;IAC5C,OAAO,CAAC,UAAU,CAAiC;IAEtC,wBAAwB,CAAC,GAAG,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,kBAAkB,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC;IAM3G;;;;;;;;;;;OAWG;IACU,iBAAiB,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,EAC7C,YAAY,EAAE,iBAAiB,GAAG,IAAI,EACtC,MAAM,EAAE,kBAAkB,CAAC,GAAG,EAAE,CAAC,CAAC,EAClC,OAAO,EAAE,CAAC,EACV,cAAc,EAAE,GAAG,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;IA0IhC;;;;;;;OAOG;IACH,SAAS,CAAC,mBAAmB,CAAC,cAAc,EAAE,OAAO,GAAG;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC;IAmI5F;;;;;;;OAOG;IACU,aAAa,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,EACzC,OAAO,EAAE,CAAC,EACV,cAAc,EAAE,GAAG,EACnB,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GACpD,OAAO,CAAC,IAAI,CAAC;IAShB;;;;;;;;;;OAUG;IACU,oBAAoB,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAK/G;;;;;;;;;;;OAWG;IACU,kBAAkB,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,EAC9C,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC7B,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC1B,OAAO,EAAE,CAAC,EACV,cAAc,EAAE,GAAG,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAKvC;;;;;;;;;;;OAWG;IACU,gBAAgB,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,EAC5C,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,CAAC,EACV,cAAc,EAAE,GAAG,EACnB,gBAAgB,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,GAC/C,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAKzC;;;;;;;;;;;;;;;;;OAiBG;IACU,oBAAoB,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,EAChD,OAAO,EAAE,WAAW,EAAE,EACtB,cAAc,EAAE,CAAC,EACjB,cAAc,EAAE,GAAG,EACnB,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC,EACjC,MAAM,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC/B,OAAO,CAAC,IAAI,CAAC;IAShB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,6BAA6B;CAyBxC"}

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

@@ -1,50 +1,111 @@
-"use strict";
+/**
+ * @fileoverview Implementation of the Loop Agent Type for iterative task execution.
+ *
+ * The LoopAgentType enables agents to operate in a continuous loop, making decisions
+ * about task completion and next steps based on the current state. It parses structured
+ * JSON responses from the AI model and translates them into BaseAgentNextStep directives.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ * @since 2.49.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.LoadLoopAgentType = exports.LoopAgentType = void 0;
-const global_1 = require("@memberjunction/global");
-const base_agent_type_1 = require("./base-agent-type");
-const core_1 = require("@memberjunction/core");
-const ConversationMessageResolver_1 = require("../utils/ConversationMessageResolver");
-let LoopAgentType = class LoopAgentType extends base_agent_type_1.BaseAgentType {
+import { RegisterClass, SafeExpressionEvaluator } from '@memberjunction/global';
+import { BaseAgentType } from './base-agent-type.js';
+import { LogError, LogStatusEx } from '@memberjunction/core';
+import { ConversationMessageResolver } from '../utils/ConversationMessageResolver.js';
+/**
+ * Implementation of the Loop Agent Type pattern.
+ *
+ * This agent type enables iterative execution where the agent continues
+ * processing until a task is marked complete. It supports:
+ * - Task completion detection
+ * - Sub-agent delegation
+ * - Action execution
+ * - Progress tracking
+ * - Error handling
+ * - Result accumulation across iterations
+ *
+ * @class LoopAgentType
+ * @extends BaseAgentType
+ *
+ * @example
+ * ```typescript
+ * // The agent will execute in a loop until taskComplete is true
+ * const loopAgent = new LoopAgentType();
+ * const nextStep = await loopAgent.DetermineNextStep(promptResult);
+ *
+ * switch (nextStep.step) {
+ *   case 'success':
+ *     console.log('Task completed:', nextStep.payload);
+ *     break;
+ *   case 'sub-agent':
+ *     console.log('Delegating to:', nextStep.subAgentName);
+ *     break;
+ *   case 'action':
+ *     console.log('Executing action:', nextStep.actionName);
+ *     break;
+ * }
+ * ```
+ */
+let LoopAgentType = class LoopAgentType extends BaseAgentType {
     constructor() {
         super(...arguments);
-        this._evaluator = new global_1.SafeExpressionEvaluator();
+        this._evaluator = new SafeExpressionEvaluator();
     }
     async InitializeAgentTypeState(params) {
-        return {};
+        // Loop agents do not require agent-type specific state initialization
+        // but can be extended in the future if needed
+        return {}; // Return an empty object for now
     }
+    /**
+     * Determines the next step based on the structured response from the AI model.
+     *
+     * This method parses the JSON response from the loop agent prompt and translates
+     * it into appropriate BaseAgentNextStep directives. It handles task completion,
+     * sub-agent delegation, action execution, and error conditions.
+     *
+     * @param {AIPromptRunResult} promptResult - The result from executing the agent's prompt
+     * @returns {Promise<BaseAgentNextStep>} The next step to take in the agent execution
+     *
+     * @throws {Error} Implicitly through failed parsing, but returns failed step instead
+     */
     async DetermineNextStep(promptResult, params, payload, agentTypeState) {
         try {
+            // Ensure we have a successful result
             if (!promptResult.success || !promptResult.result) {
                 return this.createNextStep('Failed', {
                     errorMessage: promptResult.errorMessage || 'Prompt execution failed'
                 });
             }
+            // Parse the response using the base class utility
             const response = this.parseJSONResponse(promptResult);
             if (!response) {
                 return this.createRetryStep('Failed to parse JSON response');
             }
+            // Validate the response structure
             const validationResult = this.isValidLoopResponse(response);
             if (!validationResult.success) {
                 return this.createRetryStep(validationResult.message);
             }
+            // Check for Chat nextStep BEFORE checking taskComplete
+            // This allows agents to ask for user clarification even when taskComplete=true
             if (response.nextStep?.type === 'Chat') {
                 if (!response.message) {
                     return this.createRetryStep('Chat type specified but no user message provided');
                 }
-                (0, core_1.LogStatusEx)({
+                LogStatusEx({
                     message: '💬 Loop Agent: Requesting user interaction. Message: ' + response.message,
                     verboseOnly: true
                 });
                 return this.createNextStep('Chat', {
                     message: response.message,
-                    terminate: true,
+                    terminate: true, // Chat always terminates to return to user
                     payloadChangeRequest: response.payloadChangeRequest,
                     responseForm: response.responseForm,
                     actionableCommands: response.actionableCommands,
@@ -53,8 +114,9 @@ let LoopAgentType = class LoopAgentType extends base_agent_type_1.BaseAgentType
                     confidence: response.confidence
                 });
             }
+            // Check if task is complete
             if (response.taskComplete) {
-                (0, core_1.LogStatusEx)({
+                LogStatusEx({
                     message: '✅ Loop Agent: Task completed successfully. Message: ' + response.message,
                     verboseOnly: true
                 });
@@ -68,9 +130,11 @@ let LoopAgentType = class LoopAgentType extends base_agent_type_1.BaseAgentType
                     automaticCommands: response.automaticCommands
                 });
             }
+            // Handle when nextStep is not provided but task is not complete
             if (!response.nextStep) {
                 return this.createRetryStep('Task not complete but no next step provided');
             }
+            // Determine next step based on type
             const retVal = {
                 payloadChangeRequest: response.payloadChangeRequest,
                 terminate: response.taskComplete,
@@ -115,6 +179,7 @@ let LoopAgentType = class LoopAgentType extends base_agent_type_1.BaseAgentType
                         retVal.errorMessage = 'ForEach type specified but forEach details missing';
                     }
                     else {
+                        // Return ForEach decision for BaseAgent to execute in next iteration
                         retVal.step = 'ForEach';
                         retVal.forEach = response.nextStep.forEach;
                     }
@@ -125,6 +190,7 @@ let LoopAgentType = class LoopAgentType extends base_agent_type_1.BaseAgentType
                         retVal.errorMessage = 'While type specified but while details missing';
                     }
                     else {
+                        // Return While decision for BaseAgent to execute in next iteration
                         retVal.step = 'While';
                         retVal.while = response.nextStep.while;
                     }
@@ -137,41 +203,63 @@ let LoopAgentType = class LoopAgentType extends base_agent_type_1.BaseAgentType
             return retVal;
         }
         catch (error) {
-            (0, core_1.LogError)(`Error in LoopAgentType.DetermineNextStep: ${error.message}`);
+            LogError(`Error in LoopAgentType.DetermineNextStep: ${error.message}`);
             return this.createRetryStep(`Failed to parse loop agent response: ${error.message}`);
         }
     }
+    /**
+     * Validates that the response conforms to the expected LoopAgentResponse structure.
+     *
+     * @param {any} response - The response to validate
+     * @returns {boolean} True if the response is valid, false otherwise
+     *
+     * @protected
+     */
     isValidLoopResponse(simpleResponse) {
+        // Check required fields, first cast the simpleResponse to LoopAgentResponse
+        // so we get the benefit of TypeScript's type checking below in this method
         const response = simpleResponse;
         if (typeof response !== 'object' || response === null) {
             return { success: false, message: 'Invalid response format' };
         }
         if (!response.taskComplete) {
+            // if not provided, default to false to make processing work
             response.taskComplete = false;
         }
         if (typeof response.taskComplete !== 'boolean') {
-            (0, core_1.LogError)('LoopAgentResponse missing required field: taskComplete');
+            LogError('LoopAgentResponse missing required field: taskComplete');
             return { success: false, message: 'Missing required field: taskComplete' };
         }
+        // nextStep is optional when taskComplete is true
         if (!response.taskComplete && !response.nextStep) {
             if (response.message?.trim().length > 0 ||
                 (typeof response.reasoning === 'string' &&
                     response.reasoning?.trim().length > 0)) {
+                // in this situation we have a message or reasoning coming back but a malformed response
+                // so we can consider it a chat response becuase it is trying to communicate
+                // something back, better to provide that back than discarding it entirely
+                // possibly we will make this configurable in the future
                 response.nextStep = {
                     type: 'Chat'
                 };
                 if (response.message?.trim().length === 0) {
+                    // this means reasoning was provided but no message, copy reasoning to message 
+                    // as you shouldn't ever have that but we can handle it gracefully
                     response.message = response.reasoning;
                 }
             }
             else if (response.payloadChangeRequest?.newElements ||
                 response.payloadChangeRequest?.updateElements ||
                 response.payloadChangeRequest?.removeElements) {
+                // the AI forgot to mark taskComplete as true but provided a payloadChangeRequest
+                // with changes to the elements, so we can consider this a valid response
+                // and we can consider it attempting to have a taskComplete = true
+                // and validation will catch if it didn't actually complete and drive a retry
                 response.message = 'taskComplete set to true automatically due to payloadChangeRequest and no nextStep provided by AI';
                 response.taskComplete = true;
             }
             else {
-                (0, core_1.LogError)('LoopAgentResponse requires nextStep when taskComplete is false');
+                LogError('LoopAgentResponse requires nextStep when taskComplete is false');
                 return {
                     success: false,
                     message: `Missing nextStep is a required field when taskComplete is false
@@ -184,98 +272,184 @@ let LoopAgentType = class LoopAgentType extends base_agent_type_1.BaseAgentType
                 };
             }
         }
+        // Validate nextStep structure if present
         if (response.nextStep) {
             const validStepTypes = ['actions', 'sub-agent', 'chat', 'foreach', 'while'];
             let lcaseType = response.nextStep.type?.toLowerCase().trim();
+            // allow the AI to mess up the case, but we need to validate it
+            // be smart/lenient about missing types. if type is missing but we have a nextStep.subAgent, default to sub-agent and if type is missing and we have nextStep.actions, default to actions
             if (!lcaseType && response.nextStep.subAgent) {
-                response.nextStep.type = 'Sub-Agent';
+                response.nextStep.type = 'Sub-Agent'; // update the data structure to have the correct type
                 lcaseType = 'sub-agent';
             }
             else if (!lcaseType && response.nextStep.actions && response.nextStep.actions.length > 0) {
-                response.nextStep.type = 'Actions';
+                response.nextStep.type = 'Actions'; // update the data structure to have the correct type
                 lcaseType = 'actions';
             }
             else if (!lcaseType && response.nextStep.forEach) {
-                response.nextStep.type = 'ForEach';
+                response.nextStep.type = 'ForEach'; // update the data structure to have the correct type
                 lcaseType = 'foreach';
             }
             else if (!lcaseType && response.nextStep.while) {
-                response.nextStep.type = 'While';
+                response.nextStep.type = 'While'; // update the data structure to have the correct type
                 lcaseType = 'while';
             }
             if (!validStepTypes.includes(lcaseType)) {
                 const message = `LoopAgentResponse has invalid nextStep.type: ${response.nextStep.type}`;
-                (0, core_1.LogError)(message);
+                LogError(message);
                 return { success: false, message };
             }
+            // Validate specific fields based on type
             if (lcaseType === 'actions' && !response.nextStep.actions) {
                 const message = 'LoopAgentResponse requires actions array for action type';
-                (0, core_1.LogError)(message);
+                LogError(message);
                 return { success: false, message };
             }
             if (lcaseType === 'sub-agent' && !response.nextStep.subAgent) {
                 const message = 'LoopAgentResponse requires subAgent object for sub-agent type';
-                (0, core_1.LogError)(message);
+                LogError(message);
                 return { success: false, message };
             }
             if (lcaseType === 'chat' && !response.message) {
+                // check to see if we have reasoning, if so, use that, otherwise we have to fail
                 if (!response.reasoning || response.reasoning.trim().length === 0) {
                     const message = 'LoopAgentResponse requires message for chat type';
-                    (0, core_1.LogError)(message);
+                    LogError(message);
                     return { success: false, message };
                 }
                 else {
+                    // if we have reasoning, use that as the message
                     response.message = response.reasoning;
                 }
             }
             if (lcaseType === 'foreach' && !response.nextStep.forEach) {
                 const message = 'LoopAgentResponse requires forEach object for ForEach type';
-                (0, core_1.LogError)(message);
+                LogError(message);
                 return { success: false, message };
             }
             if (lcaseType === 'while' && !response.nextStep.while) {
                 const message = 'LoopAgentResponse requires while object for While type';
-                (0, core_1.LogError)(message);
+                LogError(message);
                 return { success: false, message };
             }
         }
         return { success: true };
     }
+    /**
+     * Injects a payload into the prompt parameters.
+     * For LoopAgentType, this could be used to inject previous loop results or context.
+     *
+     * @param {T} payload - The payload to inject
+     * @param {AIPromptParams} prompt - The prompt parameters to update
+     * @param {object} agentInfo - Agent identification info (unused by LoopAgentType)
+     */
     async InjectPayload(payload, agentTypeState, prompt, agentInfo) {
         if (!prompt)
             throw new Error('Prompt parameters are required for payload injection');
         if (!prompt.data)
             prompt.data = {};
-        prompt.data[base_agent_type_1.BaseAgentType.CURRENT_PAYLOAD_PLACEHOLDER] = payload || {};
+        prompt.data[BaseAgentType.CURRENT_PAYLOAD_PLACEHOLDER] = payload || {};
     }
+    /**
+     * Determines the initial step for loop agent types.
+     *
+     * Loop agents always start with a prompt execution to determine the initial actions.
+     *
+     * @param {ExecuteAgentParams} params - The full execution parameters
+     * @returns {Promise<BaseAgentNextStep<P> | null>} Always returns null to use default behavior
+     *
+     * @override
+     * @since 2.76.0
+     */
     async DetermineInitialStep(params) {
+        // Loop agents always start with a prompt execution
         return null;
     }
+    /**
+     * Pre-processes steps for loop agent types.
+     *
+     * Loop agents use the default next step behavior which executes the prompt again.
+     *
+     * @param {ExecuteAgentParams} params - The full execution parameters
+     * @param {BaseAgentNextStep} step - The step that needs to be preprocessed
+     * @returns {Promise<BaseAgentNextStep<P> | null>} Always returns null to use default behavior
+     *
+     * @override
+     * @since 2.76.0
+     */
     async PreProcessNextStep(params, step, payload, agentTypeState) {
+        // Loop agents use default next step behavior (execute prompt)
         return null;
     }
+    /**
+     * Gets the prompt to use for a specific step.
+     * Loop agents always use the default prompt from configuration.
+     *
+     * @param {ExecuteAgentParams} params - The execution parameters (unused)
+     * @param {AgentConfiguration} config - The loaded agent configuration
+     * @param {BaseAgentNextStep | null} previousDecision - The previous step decision (unused)
+     * @returns {Promise<AIPromptEntityExtended | null>} Returns config.childPrompt
+     *
+     * @override
+     * @since 2.76.0
+     */
     async GetPromptForStep(params, config, payload, agentTypeState, previousDecision) {
+        // Loop agents always use the default prompt from configuration
         return config.childPrompt || null;
     }
+    /**
+     * Pre-processes action parameters to resolve conversation references.
+     *
+     * Loop agents get action parameters directly from the LLM's JSON response.
+     * This method resolves any "conversation.*" references in those parameters
+     * before the actions are executed.
+     *
+     * @param {AgentAction[]} actions - The actions that will be executed (modified in place)
+     * @param {P} currentPayload - The current payload
+     * @param {ATS} agentTypeState - The agent type state
+     * @param {BaseAgentNextStep<P>} currentStep - The current step being executed
+     * @param {ExecuteAgentParams<P>} params - The execution parameters with conversation messages
+     *
+     * @returns {Promise<void>} Actions are modified in place
+     *
+     * @override
+     * @since 2.120.0
+     */
     async PreProcessActionStep(actions, currentPayload, agentTypeState, currentStep, params) {
+        // Resolve conversation references in action parameters
         for (const action of actions) {
             if (action.params) {
                 action.params = this.resolveConversationReferences(action.params, params);
             }
         }
     }
+    /**
+     * Recursively resolves conversation references in action parameters.
+     *
+     * Handles nested objects and arrays, resolving any string values that start
+     * with "conversation." using the ConversationMessageResolver.
+     *
+     * @param {unknown} value - The value to resolve (can be object, array, string, or primitive)
+     * @param {ExecuteAgentParams} params - The execution parameters with conversation messages
+     * @returns {unknown} The resolved value
+     *
+     * @private
+     */
     resolveConversationReferences(value, params) {
         if (typeof value === 'string') {
+            // Check if this is a conversation reference
             const trimmedValue = value.trim();
-            if (ConversationMessageResolver_1.ConversationMessageResolver.isConversationReference(trimmedValue) && params?.conversationMessages) {
-                return ConversationMessageResolver_1.ConversationMessageResolver.resolve(trimmedValue, params.conversationMessages);
+            if (ConversationMessageResolver.isConversationReference(trimmedValue) && params?.conversationMessages) {
+                return ConversationMessageResolver.resolve(trimmedValue, params.conversationMessages);
             }
             return value;
         }
         else if (Array.isArray(value)) {
+            // Recursively resolve array elements
             return value.map(item => this.resolveConversationReferences(item, params));
         }
         else if (value && typeof value === 'object') {
+            // Recursively resolve object properties
             const resolvedObj = {};
             for (const [key, val] of Object.entries(value)) {
                 resolvedObj[key] = this.resolveConversationReferences(val, params);
@@ -283,15 +457,13 @@ let LoopAgentType = class LoopAgentType extends base_agent_type_1.BaseAgentType
             return resolvedObj;
         }
         else {
+            // Primitives (numbers, booleans, null, undefined) pass through
             return value;
         }
     }
 };
-exports.LoopAgentType = LoopAgentType;
-exports.LoopAgentType = LoopAgentType = __decorate([
-    (0, global_1.RegisterClass)(base_agent_type_1.BaseAgentType, "LoopAgentType")
+LoopAgentType = __decorate([
+    RegisterClass(BaseAgentType, "LoopAgentType")
 ], LoopAgentType);
-function LoadLoopAgentType() {
-}
-exports.LoadLoopAgentType = LoadLoopAgentType;
+export { LoopAgentType };
 //# sourceMappingURL=loop-agent-type.js.map