@memberjunction/ai-agents 3.4.0 → 4.1.0

package/dist/base-agent.d.ts

@@ -1,48 +1,345 @@
+/**
+ * @fileoverview Base implementation of the MemberJunction AI Agent framework.
+ *
+ * This module provides the core BaseAgent class that handles agent execution
+ * using a hierarchical prompt system. Agents use their type's system prompt
+ * as a parent prompt and their own configured prompts as child prompts,
+ * enabling sophisticated agent behaviors through prompt composition.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ * @since 2.49.0
+ */
 import { AIAgentTypeEntity, TemplateParamEntity, AIAgentNoteEntity, AIAgentExampleEntity } from '@memberjunction/core-entities';
 import { AIAgentRunEntityExtended, AIAgentRunStepEntityExtended, AIPromptEntityExtended, AIAgentEntityExtended } from "@memberjunction/ai-core-plus";
 import { UserInfo } from '@memberjunction/core';
 import { ChatMessage, ChatMessageContent } from '@memberjunction/ai';
-import { BaseAgentType } from './agent-types/base-agent-type';
+import { BaseAgentType } from './agent-types/base-agent-type.js';
 import { AIPromptParams, AIPromptRunResult, ExecuteAgentParams, AgentConfiguration, ExecuteAgentResult, AgentAction, AgentSubAgentRequest, BaseAgentNextStep, MessageLifecycleEvent, AgentChatMessage, AIModelSelectionInfo, ActionChange, ActionChangeScope, MediaOutput } from '@memberjunction/ai-core-plus';
 import { ActionEntityExtended, ActionResult } from '@memberjunction/actions-base';
+/**
+ * Base implementation for AI Agents in the MemberJunction framework.
+ *
+ * The BaseAgent class provides the core execution logic for AI agents using
+ * a hierarchical prompt system. It implements the following workflow:
+ *
+ * 1. Loads the agent's type to get the system prompt configuration
+ * 2. Validates that the agent type has a properly configured placeholder
+ * 3. Loads the agent's first active prompt (ordered by ExecutionOrder)
+ * 4. Gathers context data including sub-agents and available actions
+ * 5. Executes the prompts hierarchically (system prompt as parent, agent prompt as child)
+ * 6. Uses the agent type to determine the next step based on execution results
+ *
+ * @class BaseAgent
+ * @example
+ * ```typescript
+ * // Using with default context type (any)
+ * const agent = new BaseAgent();
+ * const result = await agent.Execute({
+ *   agent: myAgentEntity,
+ *   conversationMessages: messages,
+ *   contextUser: currentUser
+ * });
+ *
+ * // Using with typed context through ExecuteAgentParams
+ * interface MyContext {
+ *   apiKey: string;
+ *   environment: 'dev' | 'prod';
+ * }
+ *
+ * const agent = new BaseAgent();
+ * const params: ExecuteAgentParams<MyContext> = {
+ *   agent: myAgentEntity,
+ *   conversationMessages: messages,
+ *   contextUser: currentUser,
+ *   context: {
+ *     apiKey: 'abc123',
+ *     environment: 'prod'
+ *   }
+ * };
+ * const result = await agent.Execute(params);
+ * ```
+ */
 export declare class BaseAgent {
+    /**
+     * Maximum allowed validation retries before forcing failure.
+     * @private
+     */
     private static readonly MAX_VALIDATION_RETRIES;
+    /**
+     * Instance of AIPromptRunner used for executing hierarchical prompts.
+     * @private
+     */
     private _promptRunner;
+    /**
+     * Metadata instance for creating entity objects.
+     * @private
+     */
     private _metadata;
+    /**
+     * This is state information that is specific to the agent type. BaseAgent doesn't know what
+     * this contains or care, it is just responsible for keeping this, giving the Agent Type the
+     * opportunity to initialize its state when a run starts, and passing the object along each
+     * time the Agent Type is called to do something such as DetermineNextStep()
+     */
     private _agentTypeState;
+    /**
+     * Overridable accessor for the current agent instance's agent-type state
+     */
     protected get AgentTypeState(): any;
     private _agentTypeInstance;
+    /**
+     * Accessor for the agent's type instance
+     */
     get AgentTypeInstance(): BaseAgentType;
+    /**
+     * Map to track execution counts for actions and sub-agents.
+     * Key is the item ID (action ID or sub-agent ID), value is the count.
+     * @private
+     */
     private _executionCounts;
+    /**
+     * Callback for message lifecycle events (expiration, compaction, removal, expansion).
+     * @private
+     */
     private _messageLifecycleCallback;
+    /**
+     * Counter for validation-induced retries (when validation changes a step to Retry).
+     * This is separate from FinalPayloadValidation retries.
+     * @private
+     */
     private _generalValidationRetryCount;
+    /**
+     * Current agent run entity.
+     * @private
+     */
     private _agentRun;
+    /**
+     * Access the current run for the agent
+     */
     get AgentRun(): AIAgentRunEntityExtended | null;
+    /**
+     * Gets the available configuration presets for an agent.
+     * Returns semantic presets like "Fast", "Balanced", "High Quality" that users can choose from.
+     * These are actual presets stored in the database with specific AIConfiguration references.
+     *
+     * @param agentId - The ID of the agent to get presets for
+     * @returns Array of configuration presets sorted by Priority, or empty array if none configured
+     *
+     * @example
+     * ```typescript
+     * const agent = new ResearchAgent();
+     * const presets = agent.GetConfigurationPresets('agent-uuid-here');
+     * // Returns presets defined in database: [
+     * //   { Name: 'Fast', DisplayName: 'Quick Draft', AIConfigurationID: 'fast-config-uuid', IsDefault: true },
+     * //   { Name: 'HighQuality', DisplayName: 'Maximum Detail', AIConfigurationID: 'frontier-uuid', IsDefault: false }
+     * // ]
+     * // Note: If no presets configured, returns empty array - agent will use default behavior
+     * ```
+     */
     GetConfigurationPresets(agentId: string): import("@memberjunction/core-entities").AIAgentConfigurationEntity[];
+    /**
+     * Gets the default configuration preset for an agent.
+     *
+     * @param agentId - The ID of the agent to get the default preset for
+     * @returns The default preset, or undefined if none configured
+     */
     GetDefaultConfigurationPreset(agentId: string): import("@memberjunction/core-entities").AIAgentConfigurationEntity;
+    /**
+     * Promotes media outputs to the agent's final outputs.
+     * Call this method to add generated images, audio, or video to the agent's outputs.
+     * These will be saved to AIAgentRunMedia and flow to ConversationDetailAttachment.
+     *
+     * @param mediaOutputs - Array of media outputs to promote
+     * @since 3.1.0
+     *
+     * @example
+     * ```typescript
+     * // Promote images from action result
+     * this.promoteMediaOutputs([{
+     *   modality: 'Image',
+     *   mimeType: 'image/png',
+     *   data: base64Data,
+     *   label: 'Generated Product Image'
+     * }]);
+     *
+     * // Promote from prompt run media reference
+     * this.promoteMediaOutputs([{
+     *   promptRunMediaId: 'prompt-run-media-uuid',
+     *   modality: 'Image',
+     *   mimeType: 'image/png',
+     *   label: 'AI Generated Visualization'
+     * }]);
+     * ```
+     */
     promoteMediaOutputs(mediaOutputs: MediaOutput[]): void;
+    /**
+     * Gets the currently accumulated media outputs for this agent run.
+     * @returns Array of promoted media outputs
+     * @since 3.1.0
+     */
     get MediaOutputs(): MediaOutput[];
+    /**
+     * Minimum size in characters for binary content to be extracted as a media reference.
+     * Content smaller than this threshold is kept inline in action results.
+     * Default: 10000 (~7.5KB when decoded from base64)
+     * @private
+     */
     private static readonly LARGE_BINARY_THRESHOLD;
+    /**
+     * Intercepts large media content in action results and replaces with placeholder references.
+     * This prevents context overflow when action results contain large base64 data (images, audio, video).
+     *
+     * Uses generic ValueType=MediaOutput detection from action metadata to identify media output params.
+     * Intercepted media is stored in _mediaOutputs with refId and persist=false (not saved unless used).
+     *
+     * @param actionParams - The output parameters from an action result
+     * @param actionEntity - Optional action entity metadata for ValueType checking
+     * @returns Sanitized parameters with large media content replaced by ${media:ref-id} placeholders
+     * @private
+     * @since 3.1.0
+     */
     private interceptLargeBinaryContent;
+    /**
+     * Resolves media placeholders in a string.
+     * Replaces ${media:ref-id} with actual data URIs (data:mime;base64,...).
+     * Sets persist=true on resolved media so it will be saved to AIAgentRunMedia.
+     *
+     * @param text - The string that may contain media placeholders
+     * @returns String with placeholders resolved to actual data URIs
+     * @private
+     * @since 3.1.0
+     */
     private resolveMediaPlaceholdersInString;
+    /**
+     * Resolves media placeholders in a payload of any type.
+     * - For strings: resolves placeholders directly
+     * - For objects: recursively processes all string properties
+     * - For arrays: recursively processes all elements
+     *
+     * @param payload - The payload that may contain media placeholders in string values
+     * @returns Payload with all placeholders resolved to actual data URIs
+     * @private
+     * @since 3.1.0
+     */
     private resolveMediaPlaceholdersInPayload;
+    /**
+     * Recursively resolves media placeholders in any value.
+     * @private
+     */
     private resolveMediaPlaceholdersRecursive;
+    /**
+     * Processes media placeholders in agent messages for conversational agents.
+     *
+     * Unlike artifact-based agents (which embed images in HTML payload), conversational agents
+     * should display images via ConversationDetailAttachment. This method:
+     * 1. Detects ${media:xxx} placeholders in the message
+     * 2. Sets persist=true on referenced media (triggers save to AIAgentRunMedia)
+     * 3. Strips media HTML tags from the message (images display via attachment instead)
+     *
+     * @param message - The message that may contain media placeholders
+     * @returns Cleaned message with media tags stripped
+     * @private
+     * @since 3.1.0
+     */
     private processMessageMediaPlaceholders;
+    /**
+     * Agent hierarchy for display purposes (e.g., ["Marketing Agent", "Copywriter Agent"]).
+     * Tracked separately as it's display-only and doesn't need persistence.
+     * @private
+     */
     private _agentHierarchy;
+    /**
+     * Current iteration context for ForEach/While loops.
+     * Only one active loop per BaseAgent instance (nested loops handled by sub-agent instances).
+     * @private
+     */
     private _iterationContext;
+    /**
+     * Current depth in the agent hierarchy (0 = root agent, 1 = first sub-agent, etc.).
+     * @private
+     */
     private _depth;
+    /**
+     * Parent step counts from root to immediate parent.
+     * Example: [2, 1] means root agent is at step 2, parent agent is at step 1.
+     * Used to build hierarchical step display (e.g., "2.1.3" for nested agents).
+     * @private
+     */
     private _parentStepCounts;
+    /**
+     * All progress steps including intermediate ones for complete execution tracking.
+     * @private
+     */
     private _allProgressSteps;
+    /**
+     * Sub-agent execution results.
+     * @private
+     */
     private _subAgentRuns;
+    /**
+     * Accumulated media outputs that agents have explicitly promoted.
+     * These are collected during agent execution and returned in ExecuteAgentResult.mediaOutputs.
+     * Stored to AIAgentRunMedia when the agent completes.
+     * @private
+     * @since 3.1.0
+     */
     private _mediaOutputs;
+    /**
+     * Payload manager for handling payload access control.
+     * @private
+     */
     private _payloadManager;
+    /**
+     * Effective actions available to this agent after applying actionChanges.
+     * Populated during gatherPromptTemplateData() and used for validation in executeActionsStep().
+     * @private
+     * @since 2.123.0
+     */
     private _effectiveActions;
+    /**
+     * Execution limits for dynamically added actions.
+     * Maps action IDs to their MaxExecutionsPerRun limit.
+     * Populated during gatherPromptTemplateData() when actionChanges include actionLimits.
+     * @private
+     * @since 2.124.0
+     */
     private _dynamicActionLimits;
+    /**
+     * Counter for tracking validation retry attempts during FinalPayloadValidation.
+     * Reset at the start of each agent run.
+     * @private
+     */
     private _validationRetryCount;
+    /**
+     * Counter tracking the number of context recovery attempts made in this run.
+     * Context recovery removes/compacts old messages when context length is exceeded.
+     * Reset at the start of each agent run.
+     * @private
+     */
     private _contextRecoveryAttempts;
+    /**
+     * Maximum number of context recovery attempts allowed per agent run.
+     * @private
+     */
     private readonly MAX_RECOVERY_ATTEMPTS;
+    /**
+     * Gets the current validation retry count for the agent run.
+     * This count tracks how many times the agent has retried validation
+     * during the FinalPayloadValidation step.
+     * @readonly
+     */
     get ValidationRetryCount(): number;
+    /**
+     * Helper method for status logging with verbose control
+     * @param message The message to log
+     * @param verboseOnly Whether this is a verbose-only message
+     * @param params Optional agent execution parameters for custom verbose check
+     */
     protected logStatus(message: string, verboseOnly?: boolean, params?: ExecuteAgentParams): void;
+    /**
+     * Helper method for enhanced error logging with metadata
+     */
     protected logError(error: Error | string, options?: {
         category?: string;
         metadata?: Record<string, any>;
@@ -50,41 +347,316 @@ export declare class BaseAgent {
         agentType?: AIAgentTypeEntity;
         severity?: 'warning' | 'error' | 'critical';
     }): void;
+    /**
+     * Wrapper for progress callbacks that captures all progress events.
+     * @private
+     */
     private wrapProgressCallback;
+    /**
+     * This overridable method is responsible for setting up any necessary one-time initalization of the
+     * agent type. The base class sets up the AgentTypeInstance and also lets that agent type initialize
+     * its state.
+     * @param params
+     */
     protected initializeAgentType(params: ExecuteAgentParams, config: AgentConfiguration): Promise<void>;
+    /**
+     * Preloads data sources configured for the agent.
+     *
+     * This method loads data from RunView or RunQuery sources as configured in
+     * AIAgentDataSource metadata and merges it with caller-provided data, context, and payload.
+     * Data sources can target three destinations:
+     * - Data: For Nunjucks templates in prompts (visible to LLMs)
+     * - Context: For actions only (NOT visible to LLMs)
+     * - Payload: For agent state initialization
+     *
+     * Caller-provided values always take precedence over preloaded values.
+     *
+     * @param params - The execution parameters
+     * @private
+     */
     private preloadAgentData;
+    /**
+     * Executes an AI agent using hierarchical prompt composition.
+     *
+     * This method orchestrates the entire agent execution process, from loading
+     * configuration to executing prompts and determining next steps. It ensures
+     * all required metadata is present and handles errors gracefully.
+     *
+     * @param {ExecuteAgentParams} params - Parameters for agent execution
+     * @param {AIAgentEntityExtended} params.agent - The agent entity to execute
+     * @param {ChatMessage[]} params.conversationMessages - Conversation history
+     * @param {UserInfo} [params.contextUser] - Optional user context
+     * @param {any} [params.context] - Optional context object passed to sub-agents and actions
+     * @template C - The type of the agent's context as provided in the ExecuteAgentParams
+     * @template R - The type of the agent's result as returned in ExecuteAgentResult
+     *
+     * @returns {Promise<ExecuteAgentResult>} Result containing next step and any output
+     *
+     * @throws {Error} Throws if there are issues loading required entities
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.Execute({
+     *   agent: salesAgent,
+     *   conversationMessages: [{role: 'user', content: 'Help me find products'}],
+     *   contextUser: currentUser
+     * });
+     * ```
+     */
     Execute<C = any, R = any>(params: ExecuteAgentParams<C>): Promise<ExecuteAgentResult<R>>;
+    /**
+     * Sub-classes can override this method to perform any specialized initialization
+     * @param params
+     */
     protected initializeStartingPayload<P = any>(params: ExecuteAgentParams<any, P>): Promise<void>;
+    /**
+     * Executes the agent's internal logic.
+     *
+     * This method contains the core execution logic that drives agent behavior. By default,
+     * it implements a sequential execution loop, but subclasses can override this to
+     * implement different execution patterns such as:
+     * - Parallel execution of multiple steps
+     * - Event-driven or reactive execution
+     * - State machine implementations
+     * - Custom termination conditions
+     * - Alternative flow control mechanisms
+     *
+     * @template P - The type of the return value from agent execution
+     * @param {ExecuteAgentParams} params - The execution parameters with wrapped callbacks (includes wrapped onProgress and onStreaming)
+     * @param {AgentConfiguration} config - The loaded agent configuration
+     * @returns {Promise<{finalPayload: P, stepCount: number}>} The execution result with typed final payload and step count
+     * @protected
+     */
     protected executeAgentInternal<P = any>(params: ExecuteAgentParams, config: AgentConfiguration): Promise<{
         finalStep: BaseAgentNextStep<P>;
         stepCount: number;
     }>;
+    /**
+     * Initializes the AI and Action engines. Subclasses can override this to add any
+     * additional engine/metadata loading initialization they want to do and this method
+     * will be called at the right time in the agent execution process.
+     *
+     * @param {UserInfo} [contextUser] - Optional user context
+     * @protected
+     */
     protected initializeEngines(contextUser?: UserInfo): Promise<void>;
+    /**
+     * Storage for injected memory context to prepend to prompts
+     */
     private _memoryContext;
+    /**
+     * Storage for injected notes and examples to include in result
+     */
     private _injectedMemory;
+    /**
+     * Inject notes and examples into agent context memory.
+     * Called automatically before agent execution if injection is enabled on the agent.
+     * Injects memory context directly into conversation messages array.
+     *
+     * @param input - The user input text for semantic search
+     * @param agent - The agent configuration entity
+     * @param userId - Optional user ID for scoping
+     * @param companyId - Optional company ID for scoping
+     * @param contextUser - User context
+     * @param conversationMessages - The conversation messages array to inject into
+     * @returns Object containing injected notes and examples
+     */
     protected InjectContextMemory(input: string, agent: AIAgentEntityExtended, userId?: string, companyId?: string, contextUser?: UserInfo, conversationMessages?: ChatMessage[]): Promise<{
         notes: AIAgentNoteEntity[];
         examples: AIAgentExampleEntity[];
     }>;
+    /**
+     * Converts UI markup (@{...} syntax) in user messages to plain text.
+     * This prevents agents from being confused by UI-specific JSON syntax and reduces token usage.
+     *
+     * Modifies the messages in-place, converting:
+     * - Mentions: @{_mode:"mention",...} → "@Agent Name" or "@User Name"
+     * - Form responses: @{_mode:"form",...} → "Field1: Value1, Field2: Value2"
+     *
+     * @param messages - The conversation messages array to convert (modified in-place)
+     */
     protected convertUIMarkupInMessages(messages: ChatMessage[]): void;
+    /**
+     * Validates that there are no circular references in the run chain.
+     * Follows the LastRunID chain to ensure it doesn't loop back to the current run.
+     *
+     * @param {string} lastRunId - The ID of the last run to check
+     * @param {UserInfo} [contextUser] - Optional user context
+     * @private
+     */
     private validateRunChain;
+    /**
+     * Validates that the agent is active and ready for execution.
+     *
+     * @param {AIAgentEntityExtended} agent - The agent to validate
+     * @returns {ExecuteAgentResult | null} Error result if validation fails, null if valid
+     * @protected
+     */
     protected validateAgent(agent: AIAgentEntityExtended): Promise<ExecuteAgentResult | null>;
+    /**
+     * Handles validation of the starting payload if configured.
+     *
+     * This method validates the input payload against the agent's StartingPayloadValidation
+     * schema before execution begins. It respects the agent's PayloadScope if configured.
+     *
+     * @param {ExecuteAgentParams} params - The execution parameters
+     * @returns {Promise<ExecuteAgentResult | null>} Error result if validation fails and mode is 'Fail', null otherwise
+     * @protected
+     */
     protected handleStartingPayloadValidation<P = any>(params: ExecuteAgentParams<any, P>): Promise<ExecuteAgentResult | null>;
+    /**
+     * Handles starting payload validation failures based on the configured mode.
+     *
+     * @param {ExecuteAgentParams} params - The execution parameters
+     * @param {string[]} errorMessages - The validation error messages
+     * @returns {ExecuteAgentResult | null} Error result if mode is 'Fail', null if mode is 'Warn'
+     * @private
+     */
     private handleStartingValidationFailure;
+    /**
+     * Loads all required configuration for agent execution.
+     *
+     * @param {AIAgentEntityExtended} agent - The agent to load configuration for
+     * @returns {Promise<AgentConfiguration>} Configuration object with loaded entities
+     * @protected
+     */
     protected loadAgentConfiguration(agent: AIAgentEntityExtended): Promise<AgentConfiguration>;
+    /**
+     * Prepares prompt parameters for hierarchical execution.
+     *
+     * @param {AIAgentTypeEntity} agentType - The agent type
+     * @param {AIPromptEntityExtended} systemPrompt - The system prompt
+     * @param {AIPromptEntityExtended} childPrompt - The child prompt
+     * @param {ExecuteAgentParams} params - Original execution parameters
+     * @returns {Promise<AIPromptParams>} Configured prompt parameters
+     * @protected
+     */
     protected preparePromptParams<P>(config: AgentConfiguration, payload: P, params: ExecuteAgentParams): Promise<AIPromptParams>;
+    /**
+     * Executes the configured prompt. Always uses the attemptJSONRepair option to try to fix LLM
+     * JSON syntax issues if they arise.
+     *
+     * @param {AIPromptParams} promptParams - The prompt parameters
+     * @returns {Promise<AIPromptRunResult>} The prompt execution result
+     * @protected
+     */
     protected executePrompt(promptParams: AIPromptParams): Promise<AIPromptRunResult>;
+    /**
+     * Base class method that determines the next step by contacting the agent type class for the specified agent type and delegating
+     * that decision. Sub-classes can override this method to implement custom next step logic if needed.
+     * @param params
+     * @param agentType
+     * @param promptResult
+     * @returns
+     */
     protected determineNextStep<P>(params: ExecuteAgentParams, agentType: AIAgentTypeEntity, promptResult: AIPromptRunResult, currentPayload: P): Promise<BaseAgentNextStep<P>>;
+    /**
+     * Validates if the next step is valid, or not. If the next step is invalid, it returns a retry step with an error message
+     * that can be processed by the agent via a retry prompt to attempt to correct the issue. Alternatively, subclasses can
+     * handle this scenario differently as desired.
+     *
+     * The BaseAgent class implements checking for sub-agents and actions to ensure that the next step is valid in the
+     * context of the current agent. If the next step is a sub-agent, it checks if the sub-agent is active and available for execution.
+     * If the next step is actions, it checks if the actions are valid and available for execution.
+     * @param params
+     * @param nextStep
+     * @returns
+     */
     protected validateNextStep<P>(params: ExecuteAgentParams, nextStep: BaseAgentNextStep<P>, currentPayload: P, agentRun: AIAgentRunEntityExtended, currentStep: AIAgentRunStepEntityExtended): Promise<BaseAgentNextStep<P>>;
+    /**
+     * Validates that the sub-agent next step is valid and can be executed by the current agent. Subclasses can override
+     * this method to implement custom validation logic if needed.
+     * @param params
+     * @param nextStep
+     * @returns
+     */
     protected validateSubAgentNextStep<P>(params: ExecuteAgentParams, nextStep: BaseAgentNextStep<P>, currentPayload: P, agentRun: AIAgentRunEntityExtended, currentStep: AIAgentRunStepEntityExtended): Promise<BaseAgentNextStep<P>>;
+    /**
+     * Validates that the actions next step is valid and can be executed by the current agent. Subclasses can override
+     * this method to implement custom validation logic if needed.
+     * @param params
+     * @param nextStep
+     * @returns
+     */
     protected validateActionsNextStep<P>(params: ExecuteAgentParams, nextStep: BaseAgentNextStep<P>, currentPayload: P, agentRun: AIAgentRunEntityExtended, currentStep: AIAgentRunStepEntityExtended): Promise<BaseAgentNextStep<P>>;
+    /**
+     * Gets the effective actions for validation, using runtime changes if available.
+     * Falls back to database-configured actions if _effectiveActions is empty.
+     *
+     * @param agentId - The ID of the agent to get actions for
+     * @returns Array of effective actions available to the agent
+     * @protected
+     * @since 2.123.0
+     */
     protected getEffectiveActionsForValidation(agentId: string): ActionEntityExtended[];
+    /**
+     * Validates that the Success next step is valid and can be executed by the current agent. Subclasses can override
+     * this method to implement custom validation logic if needed.
+     * @param params
+     * @param nextStep
+     * @returns
+     */
     protected validateSuccessNextStep<P>(params: ExecuteAgentParams, nextStep: BaseAgentNextStep<P>, currentPayload: P, agentRun: AIAgentRunEntityExtended, currentStep: AIAgentRunStepEntityExtended): Promise<BaseAgentNextStep<P>>;
+    /**
+     * Handles final payload validation failures based on the configured mode.
+     *
+     * @param params - Execution parameters
+     * @param nextStep - The original success next step
+     * @param currentPayload - The current payload
+     * @param mode - The validation mode (Retry, Fail, Warn)
+     * @param errorMessages - The validation error messages
+     * @returns Modified next step based on validation mode
+     */
     protected handleFinalPayloadValidationFailure<P>(params: ExecuteAgentParams, nextStep: BaseAgentNextStep<P>, currentPayload: P, mode: string, errorMessages: string[], agentRun: AIAgentRunEntityExtended, currentStep: AIAgentRunStepEntityExtended): Promise<BaseAgentNextStep<P>>;
+    /**
+     * Validates that the Failed next step is valid and can be executed by the current agent. Subclasses can override
+     * this method to implement custom validation logic if needed.
+     * @param params
+     * @param nextStep
+     * @returns
+     */
     protected validateFailedNextStep<P>(params: ExecuteAgentParams, nextStep: BaseAgentNextStep<P>, currentPayload: P, agentRun: AIAgentRunEntityExtended, currentStep: AIAgentRunStepEntityExtended): Promise<BaseAgentNextStep<P>>;
+    /**
+     * Validates that the Retry next step is valid and can be executed by the current agent. Subclasses can override
+     * this method to implement custom validation logic if needed. The retry step is typically used to
+     * handle cases where the agent needs to re-attempt a step due to an error or invalid state.
+     * @param params
+     * @param nextStep
+     * @returns
+     */
     protected validateRetryNextStep<P>(params: ExecuteAgentParams, nextStep: BaseAgentNextStep<P>, currentPayload: P, agentRun: AIAgentRunEntityExtended, currentStep: AIAgentRunStepEntityExtended): Promise<BaseAgentNextStep<P>>;
+    /**
+     * Validates that the Chat next step is valid and can be executed by the current agent.
+     * Implements ChatHandlingOption remapping logic - if the agent has ChatHandlingOption set,
+     * the Chat step is remapped to the specified value (Success, Fail, or Retry).
+     * Subclasses can override this method to implement custom validation logic if needed.
+     * @param params
+     * @param nextStep
+     * @returns
+     */
     protected validateChatNextStep<P>(params: ExecuteAgentParams, nextStep: BaseAgentNextStep<P>, currentPayload: P, agentRun: AIAgentRunEntityExtended, currentStep: AIAgentRunStepEntityExtended): Promise<BaseAgentNextStep<P>>;
+    /**
+     * Checks execution guardrails and modifies next step if limits are exceeded.
+     * This method is called after validation but before execution of non-terminal steps.
+     *
+     * @param params - Execution parameters
+     * @param nextStep - The validated next step
+     * @param currentPayload - Current payload
+     * @param agentRun - Current agent run
+     * @param currentStep - Current execution step
+     * @returns Modified next step if guardrails exceeded, or original next step
+     * @protected
+     */
     protected checkExecutionGuardrails<P>(params: ExecuteAgentParams, nextStep: BaseAgentNextStep<P>, currentPayload: P, agentRun: AIAgentRunEntityExtended, currentStep: AIAgentRunStepEntityExtended): Promise<BaseAgentNextStep<P>>;
+    /**
+     * Checks if any agent run guardrails have been exceeded.
+     * Override this method to implement custom guardrail logic.
+     *
+     * @param params - Execution parameters
+     * @param agentRun - Current agent run
+     * @returns Object indicating if guardrails exceeded and details
+     * @protected
+     */
     protected hasExceededAgentRunGuardrails(params: ExecuteAgentParams, agentRun: AIAgentRunEntityExtended): Promise<{
         exceeded: boolean;
         type?: 'cost' | 'tokens' | 'iterations' | 'time';
@@ -92,135 +664,906 @@ export declare class BaseAgent {
         current?: number;
         reason?: string;
     }>;
+    /**
+     * Determines if a prompt execution error is fatal and should stop agent execution.
+     * Fatal errors are those that won't be resolved by retrying, such as context length
+     * exceeded (when no larger model is available), authentication failures, or invalid
+     * request format.
+     *
+     * @param promptResult - The result from prompt execution
+     * @returns true if the error is fatal and agent should terminate, false otherwise
+     * @protected
+     */
     protected isFatalPromptError(promptResult: AIPromptRunResult): boolean;
+    /**
+     * Determines if an error is a configuration error that cannot be resolved by retrying.
+     * Configuration errors indicate issues with agent setup that need manual intervention.
+     *
+     * This method provides detailed diagnostic information to help identify what configuration
+     * is missing or incorrect.
+     *
+     * @param {any} error - The error object or Error instance
+     * @param {string} errorMessage - The error message string
+     * @param {AgentConfiguration} [config] - Optional agent configuration to check for missing pieces
+     * @returns {{isConfigError: boolean, detailedMessage: string}} Object with determination and detailed diagnostic message
+     * @protected
+     */
     protected isConfigurationError(errorMessage: string, config?: AgentConfiguration): {
         isConfigError: boolean;
         detailedMessage: string;
     };
+    /**
+     * Converts ChatMessageContent to a string representation.
+     * Handles both simple strings and content block arrays.
+     *
+     * @param content - The message content to convert
+     * @returns String representation of the content
+     * @protected
+     */
     protected contentToString(content: ChatMessageContent): string;
+    /**
+     * Smart trimming of message content based on detected format.
+     * Attempts to preserve structure while reducing size.
+     *
+     * @param content - The message content to trim (must be string)
+     * @param maxLength - Maximum length for the trimmed content
+     * @returns Object with trimmed content and strategy used
+     * @protected
+     */
     protected smartTrimContent(content: string, maxLength?: number): {
         trimmed: string;
         strategy: string;
         originalLength: number;
     };
+    /**
+     * Serializes payload for logging to PayloadAtStart
+     * Override in subclasses to customize logging behavior (e.g., summarize large payloads)
+     *
+     * @param payload - The payload to serialize
+     * @returns Serialized string or null to skip logging
+     * @protected
+     */
     protected serializePayloadAtStart(payload: any): string | null;
+    /**
+     * Serializes payload for logging to PayloadAtEnd
+     * Override in subclasses to customize logging behavior (e.g., summarize large payloads)
+     *
+     * @param payload - The payload to serialize
+     * @returns Serialized string or null to skip logging
+     * @protected
+     */
     protected serializePayloadAtEnd(payload: any): string | null;
+    /**
+     * Recovery Strategy 1: Remove oldest action-result messages.
+     * Targets messages older than minAge turns for removal.
+     *
+     * @param params - Agent execution parameters
+     * @param tokensToSave - Target number of tokens to free
+     * @param currentStepCount - Current turn/step number
+     * @param minAge - Minimum age in turns for removal (default: 5)
+     * @returns Result with tokens saved and strategy description
+     * @protected
+     */
     protected recoveryStrategy_RemoveOldestActionResults(params: ExecuteAgentParams, tokensToSave: number, currentStepCount: number, minAge?: number): {
         tokensSaved: number;
         strategyName: string;
     };
+    /**
+     * Recovery Strategy 2: Compact old action-result messages.
+     * Uses smart trimming to reduce size while preserving some content.
+     *
+     * @param params - Agent execution parameters
+     * @param tokensToSave - Target number of tokens to free
+     * @param currentStepCount - Current turn/step number
+     * @param minAge - Minimum age in turns for compaction (default: 3)
+     * @returns Result with tokens saved and strategy description
+     * @protected
+     */
     protected recoveryStrategy_CompactOldActionResults(params: ExecuteAgentParams, tokensToSave: number, currentStepCount: number, minAge?: number): Promise<{
         tokensSaved: number;
         strategyName: string;
     }>;
+    /**
+     * Recovery Strategy 3: Aggressively compact ALL action-result messages.
+     * Used when gentler strategies haven't freed enough space.
+     *
+     * @param params - Agent execution parameters
+     * @param tokensToSave - Target number of tokens to free
+     * @returns Result with tokens saved and strategy description
+     * @protected
+     */
     protected recoveryStrategy_CompactAllActionResults(params: ExecuteAgentParams, tokensToSave: number): Promise<{
         tokensSaved: number;
         strategyName: string;
     }>;
+    /**
+     * Recovery Strategy 4: Preserve beginning of last user message (fallback).
+     * Keeps the first 200-300 tokens of the user's request (which usually contains the core ask)
+     * and adds a clear marker that content was trimmed due to context limits.
+     *
+     * @param params - Agent execution parameters
+     * @param tokensToSave - Target number of tokens to free
+     * @returns Result with tokens saved and strategy description
+     * @protected
+     */
     protected recoveryStrategy_TrimLastUserMessage(params: ExecuteAgentParams, tokensToSave: number): {
         tokensSaved: number;
         strategyName: string;
     };
+    /**
+     * Attempts to recover from a context length exceeded error using multiple strategies.
+     * Uses escalating strategies: remove old results → compact old results → compact all → trim user message.
+     * This approach preserves the user's original request while removing stale action results.
+     *
+     * @param params - Agent execution parameters (conversationMessages will be modified)
+     * @param payload - Current payload to carry forward
+     * @param errorMessage - The original error message from the failed prompt
+     * @param modelSelectionInfo - Model selection information containing the model and vendor used
+     * @returns A Retry step with reduced context or Failed if recovery unsuccessful
+     * @protected
+     */
     protected attemptContextRecovery<P>(params: ExecuteAgentParams, payload: P, errorMessage: string, modelSelectionInfo?: AIModelSelectionInfo): Promise<BaseAgentNextStep<P>>;
+    /**
+     * Processes the next step based on agent type determination.
+     *
+     * @param {ExecuteAgentParams} params - Original execution parameters
+     * @param {AIAgentTypeEntity} agentType - The agent type
+     * @param {AIPromptRunResult} promptResult - The prompt execution result
+     * @returns {Promise<ExecuteAgentResult>} The execution result
+     * @protected
+     */
     protected processNextStep<P>(nextStep: BaseAgentNextStep<P>, params: ExecuteAgentParams, agentType: AIAgentTypeEntity, promptResult: AIPromptRunResult, currentPayload: P, currentStep: AIAgentRunStepEntityExtended): Promise<BaseAgentNextStep<P>>;
+    /**
+     * Creates a chat message containing action execution results.
+     *
+     * @param {AgentAction[]} actions - The actions that were executed
+     * @param {any[]} results - The results from action execution
+     * @returns {ChatMessage} A formatted message with action results
+     * @protected
+     */
     protected createActionResultMessage(actions: AgentAction[], results: ActionResult[]): ChatMessage;
+    /**
+     * Creates a chat message containing sub-agent execution results.
+     *
+     * @param {AgentSubAgentRequest} subAgent - The sub-agent that was executed
+     * @param {any} result - The result from sub-agent execution
+     * @returns {ChatMessage} A formatted message with sub-agent results
+     * @protected
+     */
     protected createSubAgentResultMessage(subAgent: AgentSubAgentRequest, result: ExecuteAgentResult): ChatMessage;
+    /**
+     * Gathers context data about the agent for use in prompt templates.
+     *
+     * This method collects information about the agent's sub-agents and available
+     * actions, formatting them for injection into prompt templates. The data is
+     * structured to provide the LLM with comprehensive context about the agent's
+     * capabilities and hierarchical relationships.
+     *
+     * @param {AIAgentEntityExtended} agent - The agent to gather context for
+     * @param {UserInfo} [_contextUser] - Optional user context (reserved for future use)
+     * @param {any} [extraData] - Optional extra data to include in the context, if provided and keys conflict within the agent context data, the extraData will override the agent context data.
+     * @param {ActionChange[]} [actionChanges] - Optional runtime action modifications
+     *
+     * @returns {Promise<AgentContextData>} Structured context data for prompts
+     *
+     * @throws {Error} If there's an error accessing agent data
+     *
+     * @private
+     */
     private gatherPromptTemplateData;
+    /**
+     * Builds merged agent type prompt params from schema defaults,
+     * agent config, and runtime overrides.
+     *
+     * Merge precedence (lowest to highest):
+     * 1. Schema defaults (from AgentType.PromptParamsSchema)
+     * 2. Agent config (from AIAgent.AgentTypePromptParams)
+     * 3. Runtime overrides (from ExecuteAgentParams.data.__agentTypePromptParams)
+     *
+     * @param agentType - The agent type entity with schema definition
+     * @param agent - The agent entity with configured values
+     * @param runtimeOverrides - Optional runtime overrides from ExecuteAgentParams.data
+     * @returns Merged prompt params object
+     *
+     * @protected
+     * @since 2.131.0
+     */
     protected buildAgentTypePromptParams(agentType: AIAgentTypeEntity | undefined, agent: AIAgentEntityExtended, runtimeOverrides?: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Applies auto-alignment rules to includeResponseTypeDefinition based on other flags.
+     *
+     * When a documentation flag (e.g., includeForEachDocs) is explicitly set to false,
+     * the corresponding response type section (e.g., forEach) should also be excluded
+     * unless explicitly set otherwise.
+     *
+     * Auto-alignment mappings:
+     * - includePayloadInPrompt → includeResponseTypeDefinition.payload
+     * - includeResponseFormDocs → includeResponseTypeDefinition.responseForms
+     * - includeCommandDocs → includeResponseTypeDefinition.commands
+     * - includeForEachDocs → includeResponseTypeDefinition.forEach
+     * - includeWhileDocs → includeResponseTypeDefinition.while
+     *
+     * @param params - The merged params object to modify in place
+     * @param explicitResponseType - The explicitly set response type config from agent/runtime (not schema defaults)
+     * @protected
+     * @since 2.132.0
+     */
     protected applyResponseTypeAutoAlignment(params: Record<string, unknown>, explicitResponseType?: Record<string, unknown>): void;
+    /**
+     * Extracts default values from a JSON Schema definition.
+     *
+     * @param schemaJson - JSON string containing the schema
+     * @returns Object with property names and their default values
+     *
+     * @protected
+     * @since 2.131.0
+     */
     protected extractSchemaDefaults(schemaJson: string | null | undefined): Record<string, unknown>;
+    /**
+     * This method executes one action using the MemberJunction Actions framework.
+     * The full ActionResult objects are returned, allowing the caller to access result codes, output parameters,
+     * and other execution details.
+     *
+     * @param {ExecuteAgentParams} params - Parameters from agent execution for context passing
+     * @param {AgentAction} action - Action to execute
+     * @param {UserInfo} [contextUser] - Optional user context for permissions
+     *
+     * @returns {Promise<ActionResult>} ActionResult object from the action execution
+     *
+     * @throws {Error} If the action fails to execute
+     */
     ExecuteSingleAction(params: ExecuteAgentParams, action: AgentAction, actionEntity: ActionEntityExtended, contextUser?: UserInfo): Promise<ActionResult>;
+    /**
+     * Prepares conversation messages for sub-agent execution based on database-configured message mode.
+     *
+     * Message passing is controlled by MessageMode and MaxMessages fields stored in either:
+     * - AIAgentRelationship table (for related sub-agents via AgentRelationships)
+     * - AIAgent table (for child sub-agents via ParentID)
+     *
+     * **Message Modes:**
+     * - `'None'`: Fresh start - only context message and task message (default)
+     * - `'All'`: Pass complete parent conversation history
+     * - `'Latest'`: Pass most recent N messages (where N = MaxMessages)
+     * - `'Bookend'`: Pass first 2 messages + indicator + most recent (N-2) messages
+     *
+     * **Priority:** AIAgentRelationship.MessageMode takes precedence over AIAgent.MessageMode
+     * to allow different parent agents to pass messages differently to the same sub-agent.
+     *
+     * Subclasses can override this method to implement custom message preparation logic
+     * specific to their domain (e.g., Skip agents adding special context).
+     *
+     * @param {ExecuteAgentParams} params - Execution parameters with conversation history
+     * @param {AgentSubAgentRequest} subAgentRequest - Sub-agent request details
+     * @param {AIAgentEntityExtended} subAgent - The sub-agent entity
+     * @param {ChatMessage | undefined} contextMessage - Optional context from SubAgentContextPaths
+     * @returns {ChatMessage[]} Prepared message array for sub-agent execution
+     *
+     * @protected
+     */
     protected prepareSubAgentMessages(params: ExecuteAgentParams, subAgentRequest: AgentSubAgentRequest, subAgent: AIAgentEntityExtended, contextMessage?: ChatMessage): ChatMessage[];
+    /**
+     * Executes a sub-agent synchronously.
+     *
+     * This method creates a new instance of AgentRunner to execute a sub-agent.
+     * The sub-agent receives the provided message/context and runs to completion.
+     * If terminateAfter is true, the parent agent will not continue after the
+     * sub-agent completes.
+     *
+     * @param {AgentSubAgentRequest} subAgentRequest - Sub-agent execution details
+     * @param {ChatMessage[]} conversationMessages - Current conversation history
+     * @param {UserInfo} [contextUser] - Optional user context
+     *
+     * @returns {Promise<ExecuteAgentResult>} Result from the sub-agent execution
+     *
+     * @throws {Error} If sub-agent cannot be found or execution fails
+     *
+     * @example
+     * ```typescript
+     * const result = await this.ExecuteSubAgent({
+     *   id: 'agent123',
+     *   name: 'DataAnalysisAgent',
+     *   message: 'Analyze sales data for Q4',
+     *   terminateAfter: false
+     * }, messages);
+     * ```
+     */
     protected ExecuteSubAgent<SC = any, SR = any>(params: ExecuteAgentParams<SC>, subAgentRequest: AgentSubAgentRequest<SC>, subAgent: AIAgentEntityExtended, stepEntity: AIAgentRunStepEntityExtended, payload?: SR, contextMessage?: ChatMessage, stepCount?: number): Promise<ExecuteAgentResult<SR>>;
+    /**
+     * Formats sub-agent details for inclusion in prompt context.
+     *
+     * @param {AIAgentEntityExtended[]} subAgents - Array of sub-agent entities
+     * @returns {string} JSON formatted string with sub-agent details
+     * @private
+     */
     private formatSubAgentDetails;
+    /**
+     * Utility method to get agent prompt parameters for a given agent. This gets the
+     * highest priority prompt for the agent, and then gets the parameters for that
+     * prompt.
+     * @param agent
+     */
     protected getAgentPromptParameters(agent: AIAgentEntityExtended): Array<TemplateParamEntity>;
     protected getAgentPromptParametersJSON(agent: AIAgentEntityExtended): string;
+    /**
+     * Formats action details for inclusion in prompt context.
+     *
+     * @param {ActionEntityExtended[]} actions - Array of action entities
+     * @returns {string} JSON formatted string with comprehensive action details
+     * @private
+     */
     private formatActionDetails;
+    /**
+     * Formats a single action parameter for display.
+     *
+     * @param {any} param - The action parameter to format
+     * @returns {object} Formatted parameter object
+     * @private
+     */
     private formatActionParameter;
+    /**
+     * Formats a parameter value for display in action execution messages.
+     * Truncates long strings and formats objects/arrays for readability.
+     *
+     * @param {any} value - The parameter value to format
+     * @param {number} maxLength - Maximum length before truncation (default: 100)
+     * @returns {string} Formatted value suitable for message display
+     * @private
+     */
     private formatParamValueForMessage;
+    /**
+     * Gets the agent type name for a given type ID.
+     *
+     * @param {string} typeID - The agent type ID
+     * @returns {string} The agent type name or 'Unknown'
+     * @private
+     */
     private getAgentTypeName;
+    /**
+     * Determines if an action change scope applies to the current agent.
+     *
+     * @param {ActionChangeScope} scope - The scope of the action change
+     * @param {string} agentId - The ID of the current agent
+     * @param {boolean} isRoot - Whether this is the root agent
+     * @param {string[]} [agentIds] - Array of specific agent IDs (for 'specific' scope)
+     * @returns {boolean} True if the change applies to this agent
+     * @protected
+     * @since 2.123.0
+     */
     protected doesChangeScopeApply(scope: ActionChangeScope, agentId: string, isRoot: boolean, agentIds?: string[]): boolean;
+    /**
+     * Result type for applyActionChanges method.
+     * Contains both the modified actions and any dynamic execution limits.
+     * @since 2.123.0
+     */
     protected applyActionChanges(baseActions: ActionEntityExtended[], actionChanges: ActionChange[], agentId: string, isRoot: boolean): {
         actions: ActionEntityExtended[];
         dynamicLimits: Record<string, number>;
     };
+    /**
+     * Filters and transforms action changes for propagation to a sub-agent.
+     *
+     * This method applies the following propagation rules:
+     * - 'global': Propagated as-is to all sub-agents
+     * - 'root': Not propagated (only applies to root agent)
+     * - 'all-subagents': Propagated as 'global' (since sub-agent is now in scope)
+     * - 'specific': Propagated as-is (sub-agent checks if it's in agentIds)
+     *
+     * @param {ActionChange[] | undefined} actionChanges - The action changes to filter
+     * @returns {ActionChange[] | undefined} Filtered action changes for sub-agent, or undefined if empty
+     * @protected
+     * @since 2.123.0
+     */
     protected filterActionChangesForSubAgent(actionChanges: ActionChange[] | undefined): ActionChange[] | undefined;
+    /**
+     * Gets value list items for a parameter.
+     *
+     * @param {string} valueListID - The value list ID
+     * @returns {string[] | null} Array of allowed values or null
+     * @private
+     */
     private getValueListItems;
+    /**
+     * Gets the action category name for a given category ID.
+     *
+     * @param {string} categoryID - The action category ID
+     * @returns {string} The category name or 'Uncategorized'
+     * @private
+     */
     private getActionCategoryName;
+    /**
+     * Initializes the agent run tracking by creating AIAgentRunEntityExtended and setting up context.
+     *
+     * @private
+     * @param {ExecuteAgentParams} params - The execution parameters
+     */
     private initializeAgentRun;
+    /**
+     * Validates the agent with tracking.
+     *
+     * @private
+     * @param {AIAgentEntityExtended} agent - The agent to validate
+     * @returns {Promise<ExecuteAgentResult | null>} - Failure result if validation fails, null if successful
+     */
     private validateAgentWithTracking;
+    /**
+     * Creates a step entity for tracking.
+     *
+     * @private
+     * @param params - Step creation parameters
+     * @returns {Promise<AIAgentRunStepEntityExtended>} - The created step entity
+     */
     private createStepEntity;
+    /**
+     * Finalizes a step entity with completion status.
+     *
+     * @private
+     * @param {AIAgentRunStepEntityExtended} stepEntity - The step entity to finalize
+     * @param {boolean} success - Whether the step was successful
+     * @param {string} [errorMessage] - Optional error message
+     * @param {any} [outputData] - Optional output data to capture for this step
+     */
+    /**
+     * Builds a summary of payload change results for storage
+     * @param changeResult The result from PayloadManager operations
+     * @returns A serializable summary object
+     */
     private buildPayloadChangeResultSummary;
     private finalizeStepEntity;
+    /**
+     * Default parameter resolution for loop body parameters (used by Flow agents)
+     * Resolves item.field, payload.field, item, index, or static values
+     * @private
+     */
     private resolveLoopParams;
+    /**
+     * Formats a message with agent hierarchy for streaming/progress updates.
+     *
+     * @private
+     * @param {string} baseMessage - The base message to format
+     * @returns {string} - The formatted message with hierarchy breadcrumb
+     */
     private formatHierarchicalMessage;
+    /**
+     * Builds hierarchical step string from parent and current step counts.
+     *
+     * Examples:
+     * - Root agent step 2: buildHierarchicalStep(2, []) => "2"
+     * - Sub-agent step 1 under root step 2: buildHierarchicalStep(1, [2]) => "2.1"
+     * - Nested sub-agent step 3: buildHierarchicalStep(3, [2, 1]) => "2.1.3"
+     * - Deep nesting: buildHierarchicalStep(5, [1, 2, 3, 4]) => "1.2.3.4.5"
+     *
+     * @param currentStep - Current agent's step number (1-based)
+     * @param parentSteps - Array of parent step counts from root to immediate parent
+     * @returns Formatted hierarchical step string, or undefined if currentStep is undefined/null
+     * @private
+     */
     private buildHierarchicalStep;
+    /**
+     * Gets human-readable reasoning for the next step decision.
+     *
+     * @private
+     * @param {BaseAgentNextStep} nextStep - The next step decision
+     * @returns {string} Human-readable reasoning
+     */
     private getNextStepReasoning;
+    /**
+     * Executes the next step based on the current state.
+     *
+     * This method can be overridden by subclasses to customize step execution behavior.
+     * It handles the execution of different step types (prompt, actions, sub-agent, chat)
+     * based on the previous decision.
+     *
+     * @protected
+     * @param {ExecuteAgentParams} params - Original execution parameters
+     * @param {AgentConfiguration} config - Agent configuration
+     * @param {BaseAgentNextStep | null} previousDecision - Previous step decision
+     * @returns {Promise<BaseAgentNextStep<P>>}
+     */
     protected executeNextStep<P = any>(params: ExecuteAgentParams, config: AgentConfiguration, previousDecision: BaseAgentNextStep<P> | null, stepCount?: number): Promise<BaseAgentNextStep<P>>;
+    /**
+     * Returns the default payload self write paths for the agent. If not specified, it will return undefined
+     
+     */
     private getDefaultPayloadSelfWritePaths;
+    /**
+     * Executes a prompt step and tracks it.
+     *
+     * @private
+     */
     private executePromptStep;
+    /**
+     * Computes the upstream and downstream paths for a sub-agent based on the agent's payload paths.
+     * @param params
+     * @param subAgentEntity
+     * @param subAgentRequest
+     * @returns
+     */
     private computeUpstreamDownstreamPaths;
+    /**
+     * Computes the payload for a child sub-agent based on the agent's payload paths.
+     * @param params
+     * @param subAgentEntity
+     * @param downstreamPaths
+     * @param subAgentRequest
+     * @param previousDecision
+     * @returns
+     */
     private computeChildSubAgentPayload;
+    /**
+     * Executes a child sub-agent step (ParentID relationship) and tracks it.
+     * Child agents use direct payload inheritance with downstream/upstream paths.
+     *
+     * @private
+     * @param parentStepId - Optional ID of parent step (e.g., ForEach/While loop step) for proper UI hierarchy
+     * @param subAgentPayloadOverride - Optional payload override for sub-agent execution, if provided the normal payload computation is skipped
+     */
     private executeChildSubAgentStep;
+    /**
+     * Routes sub-agent execution to the appropriate handler based on relationship type.
+     * Child agents (ParentID) use direct payload coupling.
+     * Related agents (AgentRelationships) use message-based coupling with optional output mapping.
+     *
+     * @private
+     * @param parentStepId - Optional ID of parent step (e.g., ForEach/While loop step) for proper UI hierarchy
+     * @param subAgentPayloadOverride - Optional payload override for sub-agent execution, if provided the normal payload computation is skipped
+     */
     private processSubAgentStep;
+    /**
+     * Executes a related sub-agent step (AgentRelationships) and tracks it.
+     * Related agents use message-based communication with independent payloads.
+     * Optional output mapping can merge sub-agent results back to parent payload.
+     *
+     * @private
+     * @param parentStepId - Optional ID of parent step (e.g., ForEach/While loop step) for proper UI hierarchy
+     */
     private executeRelatedSubAgentStep;
+    /**
+     * Applies sub-agent output mapping to update the parent payload.
+     * Maps sub-agent result payload paths to parent payload paths.
+     * Mirrors the action output mapping pattern used by Flow agents.
+     *
+     * @private
+     */
     private applySubAgentOutputMapping;
+    /**
+     * Sets a value in a target object, supporting array append operations.
+     * If the key ends with [], the value is appended to an array instead of replacing.
+     *
+     * @param target - Target object to modify
+     * @param key - Property key, optionally ending with [] for array append
+     * @param value - Value to set or append
+     * @private
+     */
     private setMappedValue;
+    /**
+     * Applies sub-agent input mapping to prepare initial payload for related sub-agent.
+     * Maps parent payload paths to sub-agent initial payload paths.
+     * Enables structural data transfer from parent to related sub-agent.
+     *
+     * @param parentPayload - Parent agent's current payload
+     * @param mappingConfig - JSON mapping configuration string
+     * @returns Mapped payload object for sub-agent initialization, or null if mapping fails or produces empty result
+     * @private
+     */
     private applySubAgentInputMapping;
+    /**
+     * Prepares a context message containing parent payload data for related sub-agent.
+     * Extracts specified paths from parent payload or conversation messages and formats
+     * them as a user message to provide LLM context to the sub-agent.
+     *
+     * Supports both payload paths and conversation message paths:
+     * - Payload paths: "fieldName", "nested.field", etc.
+     * - Conversation paths: "conversation.all", "conversation.user.last", "conversation.all.last[5]", etc.
+     *
+     * @param parentPayload - Parent agent's current payload
+     * @param contextPaths - Array of paths to extract, or ["*"] for entire payload
+     * @param params - Execution parameters with conversation messages
+     * @returns ChatMessage with formatted context, or null if no paths specified or no data found
+     * @private
+     */
     private prepareRelatedSubAgentContextMessage;
+    /**
+     * Helper method to get a value from a nested object path.
+     * Supports both dot notation (obj.prop) and array indexing (arr[0]).
+     *
+
+    /**
+     * Executes actions step and tracks it.
+     *
+     * @private
+     */
     private executeActionsStep;
+    /**
+     * Executes a chat step - these should bubble up to the user for interaction.
+     * Chat steps are terminal and indicate the agent needs user input.
+     *
+     * @private
+     */
     private executeChatStep;
+    /**
+     * Executes a ForEach loop with actual for loop
+     * @private
+     */
     private executeForEachLoop;
     private validateWhileOperation;
     private validateForEachOperation;
     protected validateActionInAgent(actionName: string): string | null;
     protected validateSubAgentInAgent(subAgentName: string): string | null;
+    /**
+     * Helper: Validate and extract collection from payload
+     * Strips "payload." prefix if present (for LLM convenience)
+     */
     private getCollectionFromPayload;
+    /**
+     * Helper: Create parent ForEach loop step (not finalized until loop completes)
+     */
     private createForEachLoopStep;
+    /**
+     * Helper: Execute all iterations with actual for loop
+     */
     private executeForEachIterations;
+    /**
+     * Execute ForEach iterations sequentially (one at a time).
+     * This is the original implementation - safe for state accumulation and maintaining order.
+     */
     private executeForEachIterationsSequential;
+    /**
+     * Execute ForEach iterations in parallel batches.
+     * Processes multiple iterations concurrently for better performance when iterations are independent.
+     * Results are collected in parallel but applied to payload sequentially to maintain order.
+     */
     private executeForEachIterationsParallel;
+    /**
+     * Create batches of items for parallel processing.
+     * Each batch contains up to maxConcurrency items with their original indices.
+     */
     private createBatches;
+    /**
+     * Apply ForEach results sequentially to build final payload.
+     * This ensures payload changes are applied in order even when iterations ran in parallel.
+     */
     private applyForEachResultsSequentially;
+    /**
+     * Helper: Execute single ForEach iteration
+     */
     private executeSingleForEachIteration;
+    /**
+     * Helper: Complete ForEach and return result
+     */
     private completeForEachLoop;
+    /**
+     * Helper: Inject loop results as temporary message
+     */
     private injectLoopResultsMessage;
+    /**
+     * Helper: Find action with fuzzy matching for loops.
+     * Uses effective actions which includes both database-configured and dynamically added actions.
+     * Returns an object with the resolved action name for use in loop execution.
+     *
+     * @since 2.123.0 - Updated to use _effectiveActions for dynamic action support
+     */
     private findAgentActionForLoop;
+    /**
+     * Helper: Create failed step
+     */
     private createFailedStep;
+    /**
+     * Executes a While loop with actual while loop
+     * @private
+     */
     private executeWhileLoop;
+    /**
+     * Helper: Create parent While loop step
+     */
     private createWhileLoopStep;
+    /**
+     * Helper: Execute While iterations with actual while loop
+     */
     private executeWhileIterations;
+    /**
+     * Helper: Execute single While iteration
+     */
     private executeSingleWhileIteration;
+    /**
+     * Helper: Complete While and return result
+     */
     private completeWhileLoop;
+    /**
+     * Creates a failure result with proper tracking.
+     *
+     * @private
+     */
     private createFailureResult;
+    /**
+     * Creates a cancelled result.
+     *
+     * @private
+     * @param {string} message - The cancellation message
+     * @returns {Promise<ExecuteAgentResult>} The cancelled result
+     */
     private createCancelledResult;
+    /**
+     * Finalizes the agent run with success.
+     *
+     * @private
+     */
     private finalizeAgentRun;
+    /**
+     * Calculate total token statistics from the agent run's persisted steps.
+     *
+     * @returns Token statistics including totals and costs
+     * @private
+     */
     private calculateTokenStats;
+    /**
+     * Gets the count of how many times a specific action has been executed in this agent run.
+     *
+     * @param agentRunId - The agent run ID (not used anymore, kept for signature compatibility)
+     * @param actionId - The action ID to count
+     * @returns The number of times the action has been executed
+     */
     protected getActionExecutionCount(agentRunId: string, actionId: string): Promise<number>;
+    /**
+     * Gets the count of how many times a specific sub-agent has been executed in this agent run.
+     *
+     * @param agentRunId - The agent run ID (not used anymore, kept for signature compatibility)
+     * @param subAgentId - The sub-agent ID to count
+     * @returns The number of times the sub-agent has been executed
+     */
     protected getSubAgentExecutionCount(agentRunId: string, subAgentId: string): Promise<number>;
+    /**
+     * Increments the execution count for an item (action or sub-agent).
+     *
+     * @param itemId - The item ID to increment (action ID or sub-agent ID)
+     * @private
+     */
     private incrementExecutionCount;
+    /**
+     * Gets the execution count for an item (action or sub-agent).
+     *
+     * @param itemId - The item ID to get count for
+     * @returns The execution count (0 if never executed)
+     * @private
+     */
     private getExecutionCount;
+    /**
+     * Checks if all minimum execution requirements are met for actions and sub-agents.
+     *
+     * NOTE: This method intentionally uses only database-configured AgentActions, not _effectiveActions.
+     * MinExecutionsPerRun is a database-only concept - dynamically added actions via actionChanges
+     * do not have minimum execution requirements. If minimum requirements for dynamic actions are
+     * needed in the future, consider adding a `minActionLimits` property to the ActionChange interface.
+     *
+     * @param agent - The agent to check
+     * @param agentRun - The current agent run
+     * @returns Array of violation messages (empty if all requirements are met)
+     */
     protected checkMinimumExecutionRequirements(agent: AIAgentEntityExtended, agentRun: AIAgentRunEntityExtended): Promise<string[]>;
+    /**
+     * Prunes and compacts expired messages in the conversation based on configured expiration rules.
+     * Processes messages in three phases: identification, compaction, and removal.
+     *
+     * @param params - Agent execution parameters containing conversation messages
+     * @param currentTurn - Current turn number in the agent execution
+     * @protected
+     */
     protected pruneAndCompactExpiredMessages(params: ExecuteAgentParams, currentTurn: number): Promise<void>;
+    /**
+     * Creates an AIAgentRunStep for message compaction operations.
+     * Records the compaction attempt with context about the message being compacted.
+     *
+     * @param prompt - The AI prompt used for compaction
+     * @param message - The message being compacted
+     * @param params - Agent execution parameters
+     * @returns The created run step entity
+     * @protected
+     */
     protected createCompactionStep(prompt: AIPromptEntityExtended, message: AgentChatMessage, params: ExecuteAgentParams): Promise<AIAgentRunStepEntityExtended>;
+    /**
+     * Updates the compaction step with execution results and token usage.
+     *
+     * @param step - The run step to update
+     * @param result - The prompt execution result
+     * @param message - The message that was compacted
+     * @param params - Agent execution parameters
+     * @protected
+     */
     protected updateCompactionStep(step: AIAgentRunStepEntityExtended, result: AIPromptRunResult<{
         summary: string;
     }>, message: AgentChatMessage, params: ExecuteAgentParams): Promise<void>;
+    /**
+     * Compacts a message using configured compaction mode.
+     *
+     * @param message - The message to compact
+     * @param metadata - Compaction configuration
+     * @param params - Agent execution parameters for context
+     * @returns Compacted content string
+     * @protected
+     */
     protected compactMessage(message: AgentChatMessage, metadata: {
         compactMode: 'First N Chars' | 'AI Summary';
         compactLength: number;
         compactPromptId: string;
         originalLength: number;
     }, params: ExecuteAgentParams): Promise<string>;
+    /**
+     * Returns the system default prompt ID for message compaction.
+     * Looks up the "Compact Agent Message" prompt by name.
+     * @protected
+     */
     protected getSystemDefaultCompactPromptId(): string;
+    /**
+     * Estimates token count from content.
+     * Uses js-tiktoken for accurate counting when available and model info is provided,
+     * falls back to improved heuristic otherwise.
+     * @param content - The message content to estimate tokens for
+     * @param modelName - Optional model name for accurate tokenization
+     * @protected
+     */
     protected estimateTokens(content: ChatMessage['content'], modelName?: string): number;
+    /**
+     * Provides an improved heuristic token count when tokenizer is unavailable.
+     * @param text - The text to estimate tokens for
+     * @returns Estimated token count
+     * @private
+     */
     private heuristicTokenCount;
+    /**
+     * Gets the context limit for the current model.
+     * Uses model selection info from the prompt result to determine the actual model's MaxInputTokens.
+     * @param modelSelectionInfo - Model selection information from the prompt execution
+     * @returns The maximum input tokens for the model
+     * @protected
+     */
     protected getModelContextLimit(modelSelectionInfo?: AIModelSelectionInfo): number;
+    /**
+     * Estimates total token count across all conversation messages.
+     * @param messages - Message array to estimate
+     * @returns Total estimated tokens
+     * @protected
+     */
     protected estimateConversationTokens(messages: ChatMessage[]): number;
+    /**
+     * Emits message lifecycle event if callback is registered.
+     * @protected
+     */
     protected emitMessageLifecycleEvent(event: MessageLifecycleEvent): void;
+    /**
+     * Expands a previously compacted message to its original content.
+     *
+     * @param request - The expand message request
+     * @param params - Agent execution parameters
+     * @param currentTurn - Current turn number
+     * @protected
+     */
     protected executeExpandMessageStep(request: BaseAgentNextStep, params: ExecuteAgentParams, currentTurn: number): void;
+    /**
+     * Generic template resolver for loop iterations - extracts from LoopAgentType to make available to all agent types
+     * Resolves templates like {{item.field}}, {{index}}, etc. in action parameters and sub-agent payloads
+     */
     protected resolveTemplates(obj: Record<string, unknown>, context: Record<string, any>, itemVariable: string): Record<string, unknown>;
+    /**
+     * Resolves a value from context using variable references - extracts from LoopAgentType
+     *
+     * This method handles both scalar and complex object iterations in ForEach/While loops.
+     *
+     * Examples:
+     *
+     * Scalar array iteration:
+     *   candidateEntities = ["Users", "Companies", "Invoices"]
+     *   itemVariable = "entityName"
+     *   Template: "{{entityName}}" → resolves to "Users", then "Companies", then "Invoices"
+     *
+     * Object array iteration:
+     *   users = [{name: "Alice", age: 30}, {name: "Bob", age: 25}]
+     *   itemVariable = "user"
+     *   Template: "{{user.name}}" → resolves to "Alice", then "Bob"
+     *   Template: "{{user}}" → resolves to entire object {name: "Alice", age: 30}
+     */
     protected resolveValueFromContext(value: string, context: Record<string, any>, itemVariable: string): any;
+    /**
+     * Helper to get value from nested object path - extracts from LoopAgentType
+     */
     protected getValueFromPath(obj: any, path: string): unknown;
 }
 //# sourceMappingURL=base-agent.d.ts.map