@memberjunction/ai-agents 3.4.0 → 4.0.0

package/dist/AgentRunner.js

@@ -1,66 +1,119 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentRunner = void 0;
-const core_1 = require("@memberjunction/core");
-const global_1 = require("@memberjunction/global");
-const aiengine_1 = require("@memberjunction/aiengine");
-const base_agent_1 = require("./base-agent");
-class AgentRunner {
+/**
+ * @fileoverview AgentRunner provides a thin wrapper for executing AI agents
+ * using the MemberJunction AI Agent framework.
+ *
+ * This module handles agent instantiation using the ClassFactory pattern to ensure
+ * the correct agent subclass is used based on the agent type's DriverClass property.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ * @since 2.49.0
+ */
+import { LogError, LogStatusEx, IsVerboseLoggingEnabled, LogStatus, Metadata, RunView } from '@memberjunction/core';
+import { MJGlobal } from '@memberjunction/global';
+import { AIEngine } from '@memberjunction/aiengine';
+import { BaseAgent } from './base-agent.js';
+/**
+ * AgentRunner provides a thin wrapper for executing AI agents.
+ *
+ * This class handles:
+ * - Loading agent type metadata to get the DriverClass
+ * - Instantiating the correct agent class using ClassFactory
+ * - Passing through to the agent's Execute method
+ *
+ * @class AgentRunner
+ * @example
+ * ```typescript
+ * const runner = new AgentRunner();
+ * const result = await runner.RunAgent({
+ *   agent: myAgent,
+ *   conversationMessages: messages,
+ *   contextUser: currentUser
+ * });
+ * ```
+ */
+export class AgentRunner {
+    /**
+     * Runs an AI agent with the specified parameters.
+     *
+     * This method acts as a thin pass-through that:
+     * 1. Loads the agent type to get the DriverClass
+     * 2. Uses ClassFactory to instantiate the correct agent class
+     * 3. Calls Execute on the agent instance and returns the result
+     *
+     * @param {ExecuteAgentParams} params - Parameters for agent execution (same as BaseAgent.Execute)
+     * @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<T>>} The execution result (same as BaseAgent.Execute)
+     *
+     * @throws {Error} Throws if agent type loading fails or agent instantiation fails
+     */
     async RunAgent(params) {
         try {
-            (0, core_1.LogStatusEx)({
+            LogStatusEx({
                 message: `AgentRunner: Starting execution for agent: ${params.agent.Name} (ID: ${params.agent.ID})`,
                 verboseOnly: true,
-                isVerboseEnabled: () => params.verbose === true || (0, core_1.IsVerboseLoggingEnabled)()
+                isVerboseEnabled: () => params.verbose === true || IsVerboseLoggingEnabled()
             });
-            await aiengine_1.AIEngine.Instance.Config(false, params.contextUser);
-            const agentType = aiengine_1.AIEngine.Instance.AgentTypes.find(at => at.ID === params.agent.TypeID);
+            // Ensure AIEngine is configured
+            await AIEngine.Instance.Config(false, params.contextUser);
+            // Find the agent type to get the DriverClass
+            const agentType = AIEngine.Instance.AgentTypes.find(at => at.ID === params.agent.TypeID);
             if (!agentType) {
                 throw new Error(`Agent type not found for ID: ${params.agent.TypeID}`);
             }
+            // Get the correct agent class using ClassFactory, prefer the agent's DriverClass if specified, otherwise fallback to Agent Type, otherwise we get BaseAgent from ClassFactory
             const driverClass = params.agent.DriverClass || agentType.DriverClass;
-            (0, core_1.LogStatusEx)({
+            LogStatusEx({
                 message: `AgentRunner: Using driver class: ${driverClass}`,
                 verboseOnly: true,
-                isVerboseEnabled: () => params.verbose === true || (0, core_1.IsVerboseLoggingEnabled)()
+                isVerboseEnabled: () => params.verbose === true || IsVerboseLoggingEnabled()
             });
-            const agentInstance = global_1.MJGlobal.Instance.ClassFactory.CreateInstance(base_agent_1.BaseAgent, driverClass);
+            const agentInstance = MJGlobal.Instance.ClassFactory.CreateInstance(BaseAgent, driverClass);
             if (!agentInstance) {
                 throw new Error(`Failed to create agent instance for driver class: ${driverClass}`);
             }
+            // Execute the agent and return the result directly
             return await agentInstance.Execute(params);
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
-            (0, core_1.LogError)(`AgentRunner execution failed: ${errorMessage}`, undefined, error);
+            LogError(`AgentRunner execution failed: ${errorMessage}`, undefined, error);
+            // Re-throw the error since we can't create a proper ExecuteAgentResult without an agent run
+            // BaseAgent.Execute will handle creating a proper error result with an agent run
             throw error;
         }
     }
+    /**
+     * Runs an AI agent within a conversation context, handling conversation and artifact management.
+     *
+     * This method provides a complete workflow for running agents in conversations:
+     * 1. Creates or uses existing conversation
+     * 2. Creates conversation detail record for the user message
+     * 3. Executes the agent
+     * 4. Creates artifacts from the agent's payload (if configured)
+     * 5. Links artifacts to the conversation detail
+     *
+     * @param params - Core agent execution parameters
+     * @param options - Conversation-specific options
+     * @returns Promise containing the agent execution result and conversation/artifact metadata
+     *
+     * @example
+     * ```typescript
+     * const runner = new AgentRunner();
+     * const result = await runner.RunAgentInConversation({
+     *   agent: myAgent,
+     *   conversationMessages: messages,
+     *   contextUser: currentUser
+     * }, {
+     *   conversationId: existingConvoId,  // Optional - creates new if not provided
+     *   userMessage: 'User query text',
+     *   createArtifacts: true
+     * });
+     * ```
+     */
     async RunAgentInConversation(params, options) {
-        const md = new core_1.Metadata();
+        const md = new Metadata();
         const contextUser = params.contextUser;
         if (!contextUser) {
             throw new Error('contextUser is required for RunAgentInConversation');
@@ -70,29 +123,40 @@ class AgentRunner {
             let userMessageDetailId;
             let agentResponseDetailId;
             let agentResponseDetail;
+            // If conversationDetailId is provided, use it (UI-created agent response detail)
             if (options.conversationDetailId) {
                 agentResponseDetailId = options.conversationDetailId;
+                // Load the conversation detail to get the conversation ID AND keep reference for final status update
+                // This ensures backend can update Status/Message even if frontend disconnects (browser refresh)
                 agentResponseDetail = await md.GetEntityObject('Conversation Details', contextUser);
                 if (await agentResponseDetail.Load(agentResponseDetailId)) {
                     conversationId = agentResponseDetail.ConversationID;
-                    (0, core_1.LogStatus)(`Using existing conversation ${conversationId} and agent response detail ${agentResponseDetailId}`);
-                    userMessageDetailId = agentResponseDetailId;
+                    LogStatus(`Using existing conversation ${conversationId} and agent response detail ${agentResponseDetailId}`);
+                    // Note: In this case, we don't know the user message detail ID
+                    userMessageDetailId = agentResponseDetailId; // For backward compatibility
                 }
                 else {
                     throw new Error(`Failed to load conversation detail ${agentResponseDetailId}`);
                 }
             }
             else {
+                // Server creates BOTH user message and agent response details
                 if (!options.userMessage) {
                     throw new Error('userMessage is required when conversationDetailId is not provided');
                 }
+                // Step 1: Get or create conversation
                 conversationId = options.conversationId || '';
                 if (!conversationId) {
-                    (0, core_1.LogStatus)('Creating new conversation');
+                    LogStatus('Creating new conversation');
                     const conversation = await md.GetEntityObject('Conversations', contextUser);
+                    // Smart conversation naming:
+                    // 1. Use provided name if given
+                    // 2. Otherwise, use AI prompt to generate a good name from user message
+                    // 3. Fallback to "Chat with [AgentName]"
                     let conversationName = options.conversationName;
                     let conversationDescription = null;
                     if (!conversationName && options.userMessage) {
+                        // Try to generate a name using the "Name Conversation" prompt (same as UI)
                         const nameResult = await this.GenerateConversationName(options.userMessage, contextUser);
                         if (nameResult) {
                             conversationName = nameResult.name;
@@ -103,10 +167,11 @@ class AgentRunner {
                         conversationName = `Chat with ${params.agent.Name}`;
                     }
                     conversation.Name = conversationName;
-                    conversation.Description = conversationDescription || '';
+                    conversation.Description = conversationDescription || ''; // Set description too (like UI does)
                     conversation.UserID = contextUser.ID;
                     conversation.Status = 'Available';
-                    conversation.DataContextID = null;
+                    conversation.DataContextID = null; // Can be set by caller if needed
+                    // Link to test run if provided (for test execution traceability)
                     if (options.testRunId) {
                         conversation.TestRunID = options.testRunId;
                     }
@@ -114,15 +179,17 @@ class AgentRunner {
                         throw new Error('Failed to create conversation');
                     }
                     conversationId = conversation.ID;
-                    (0, core_1.LogStatus)(`Created conversation ${conversationId}: ${conversationName}`);
+                    LogStatus(`Created conversation ${conversationId}: ${conversationName}`);
                 }
-                (0, core_1.LogStatus)('Creating conversation detail for user message');
+                // Step 2: Create conversation detail for user message
+                LogStatus('Creating conversation detail for user message');
                 const userMessageDetail = await md.GetEntityObject('Conversation Details', contextUser);
                 userMessageDetail.ConversationID = conversationId;
                 userMessageDetail.Message = options.userMessage;
                 userMessageDetail.Role = 'User';
                 userMessageDetail.UserID = contextUser.ID;
                 userMessageDetail.HiddenToUser = false;
+                // Link to test run if provided (for test execution traceability)
                 if (options.testRunId) {
                     userMessageDetail.TestRunID = options.testRunId;
                 }
@@ -130,8 +197,9 @@ class AgentRunner {
                     throw new Error('Failed to create user message conversation detail');
                 }
                 userMessageDetailId = userMessageDetail.ID;
-                (0, core_1.LogStatus)(`Created user message detail ${userMessageDetailId}`);
-                (0, core_1.LogStatus)('Creating conversation detail for agent response');
+                LogStatus(`Created user message detail ${userMessageDetailId}`);
+                // Step 3: Create conversation detail for agent response (like UI does)
+                LogStatus('Creating conversation detail for agent response');
                 agentResponseDetail = await md.GetEntityObject('Conversation Details', contextUser);
                 agentResponseDetail.ConversationID = conversationId;
                 agentResponseDetail.Message = '⏳ Starting...';
@@ -139,6 +207,7 @@ class AgentRunner {
                 agentResponseDetail.Status = 'In-Progress';
                 agentResponseDetail.HiddenToUser = false;
                 agentResponseDetail.AgentID = params.agent.ID;
+                // Link to test run if provided (for test execution traceability)
                 if (options.testRunId) {
                     agentResponseDetail.TestRunID = options.testRunId;
                 }
@@ -146,23 +215,32 @@ class AgentRunner {
                     throw new Error('Failed to create agent response conversation detail');
                 }
                 agentResponseDetailId = agentResponseDetail.ID;
-                (0, core_1.LogStatus)(`Created agent response detail ${agentResponseDetailId}`);
+                LogStatus(`Created agent response detail ${agentResponseDetailId}`);
             }
-            (0, core_1.LogStatus)(`Executing agent ${params.agent.Name} in conversation context`);
+            // Step 4: Execute the agent with conversation context
+            LogStatus(`Executing agent ${params.agent.Name} in conversation context`);
+            // Flag to prevent late progress callbacks from overwriting final status
+            // Progress callbacks fire async and may complete AFTER agent returns
             let agentExecutionCompleted = false;
+            // Wrap progress callback to update agent response detail
             const originalOnProgress = params.onProgress;
             const wrappedOnProgress = agentResponseDetail
                 ? async (progress) => {
+                    // Skip DB save if agent already completed - prevents race condition
+                    // where late progress overwrites final Status='Complete'
                     if (agentExecutionCompleted) {
+                        // Still call original callback for PubSub streaming
                         if (originalOnProgress) {
                             await originalOnProgress(progress);
                         }
                         return;
                     }
+                    // Update the agent response detail with progress message
                     if (agentResponseDetail && progress.message) {
                         agentResponseDetail.Message = progress.message;
                         await agentResponseDetail.Save();
                     }
+                    // Call original callback if provided
                     if (originalOnProgress) {
                         await originalOnProgress(progress);
                     }
@@ -170,19 +248,26 @@ class AgentRunner {
                 : originalOnProgress;
             const modifiedParams = {
                 ...params,
-                data: { ...params.data, conversationId },
+                data: { ...params.data, conversationId }, // ensure we pass along OUR conversationId
                 conversationDetailId: agentResponseDetailId,
                 onProgress: wrappedOnProgress
             };
             const agentResult = await this.RunAgent(modifiedParams);
+            // Mark execution as completed to stop progress saves
             agentExecutionCompleted = true;
+            // Step 5: Update agent response detail with final result
+            // ALWAYS update status - don't rely on frontend (browser may refresh during execution)
             if (agentResponseDetail && agentResponseDetailId) {
+                // Wait for any in-flight progress save to complete
+                // EnsureSaveComplete() resolves immediately if no save in progress
                 await agentResponseDetail.EnsureSaveComplete();
-                (0, core_1.LogStatus)('Updating agent response detail with final result');
+                LogStatus('Updating agent response detail with final result');
+                // Reload to get any updates from agent execution
                 await agentResponseDetail.Load(agentResponseDetailId);
                 agentResponseDetail.Message = agentResult.agentRun?.Message ||
                     (agentResult.success ? '✅ Completed' : '❌ Failed');
                 agentResponseDetail.Status = agentResult.success ? 'Complete' : 'Error';
+                // Set response form and command fields
                 if (agentResult.responseForm) {
                     agentResponseDetail.ResponseForm = JSON.stringify(agentResult.responseForm);
                 }
@@ -193,20 +278,28 @@ class AgentRunner {
                     agentResponseDetail.AutomaticCommands = JSON.stringify(agentResult.automaticCommands);
                 }
                 await agentResponseDetail.Save();
-                (0, core_1.LogStatus)(`Updated agent response detail ${agentResponseDetailId} with final status: ${agentResponseDetail.Status}`);
+                LogStatus(`Updated agent response detail ${agentResponseDetailId} with final status: ${agentResponseDetail.Status}`);
             }
+            // Step 6: Process artifacts if requested and agent succeeded
             let artifactInfo;
-            const shouldCreateArtifacts = options.createArtifacts !== false;
+            const shouldCreateArtifacts = options.createArtifacts !== false; // Default true
             if (shouldCreateArtifacts && agentResult.success && agentResult.payload) {
+                // Artifacts link to agent response detail ID
                 artifactInfo = await this.ProcessAgentArtifacts(agentResult, agentResponseDetailId, options.sourceArtifactId, contextUser);
             }
+            // Step 7: Save media outputs to AIAgentRunMedia and create conversation attachments
             let mediaIds = [];
             if (agentResult.mediaOutputs && agentResult.mediaOutputs.length > 0) {
+                // Filter to only media that should be persisted (persist !== false)
                 const mediaToSave = agentResult.mediaOutputs.filter(m => m.persist !== false);
-                (0, core_1.LogStatus)(`Processing ${mediaToSave.length} of ${agentResult.mediaOutputs.length} media outputs (filtered by persist flag)`);
-                mediaIds = await this.SaveAgentRunMedia(agentResult.agentRun.ID, mediaToSave, contextUser);
+                LogStatus(`Processing ${mediaToSave.length} of ${agentResult.mediaOutputs.length} media outputs (filtered by persist flag)`);
+                // Save to AIAgentRunMedia for permanent storage
+                mediaIds = await this.SaveAgentRunMedia(agentResult.agentRun.ID, mediaToSave, // Pass filtered array
+                contextUser);
+                // Create ConversationDetailAttachment records for UI display
                 if (agentResponseDetailId && mediaIds.length > 0) {
-                    await this.CreateConversationMediaAttachments(agentResponseDetailId, mediaToSave, mediaIds, contextUser);
+                    await this.CreateConversationMediaAttachments(agentResponseDetailId, mediaToSave, // Pass same filtered array to keep indices aligned
+                    mediaIds, contextUser);
                 }
             }
             return {
@@ -219,13 +312,28 @@ class AgentRunner {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
-            (0, core_1.LogError)(`RunAgentInConversation failed: ${errorMessage}`, undefined, error);
+            LogError(`RunAgentInConversation failed: ${errorMessage}`, undefined, error);
             throw error;
         }
     }
+    /**
+     * Gets the maximum version number for an artifact.
+     * Used when creating new versions of explicitly specified artifacts.
+     *
+     * @param artifactId - The artifact ID to query
+     * @param contextUser - The user context for the query
+     * @returns The maximum version number, or 0 if no versions exist
+     *
+     * @example
+     * ```typescript
+     * const runner = new AgentRunner();
+     * const maxVersion = await runner.GetMaxVersionForArtifact(artifactId, currentUser);
+     * const newVersionNumber = maxVersion + 1;
+     * ```
+     */
     async GetMaxVersionForArtifact(artifactId, contextUser) {
         try {
-            const rv = new core_1.RunView();
+            const rv = new RunView();
             const result = await rv.RunView({
                 EntityName: 'MJ: Artifact Versions',
                 ExtraFilter: `ArtifactID='${artifactId}'`,
@@ -239,13 +347,30 @@ class AgentRunner {
             return 0;
         }
         catch (error) {
-            (0, core_1.LogError)(`Error getting max version for artifact: ${error.message}`);
+            LogError(`Error getting max version for artifact: ${error.message}`);
             return 0;
         }
     }
+    /**
+     * Finds the most recent artifact for a conversation detail to determine versioning.
+     * Queries the junction table to locate artifacts linked to a specific conversation message.
+     *
+     * @param conversationDetailId - The conversation detail ID to query
+     * @param contextUser - The user context for the query
+     * @returns Artifact info if exists, null if this is the first artifact for this message
+     *
+     * @example
+     * ```typescript
+     * const runner = new AgentRunner();
+     * const previousArtifact = await runner.FindPreviousArtifactForMessage(detailId, currentUser);
+     * if (previousArtifact) {
+     *     console.log(`Found artifact ${previousArtifact.artifactId} at version ${previousArtifact.versionNumber}`);
+     * }
+     * ```
+     */
     async FindPreviousArtifactForMessage(conversationDetailId, contextUser) {
         try {
-            const rv = new core_1.RunView();
+            const rv = new RunView();
             const result = await rv.RunView({
                 EntityName: 'MJ: Conversation Detail Artifacts',
                 ExtraFilter: `ConversationDetailID='${conversationDetailId}' AND Direction='Output'`,
@@ -257,7 +382,7 @@ class AgentRunner {
                 return null;
             }
             const junction = result.Results[0];
-            const md = new core_1.Metadata();
+            const md = new Metadata();
             const version = await md.GetEntityObject('MJ: Artifact Versions', contextUser);
             if (!(await version.Load(junction.ArtifactVersionID))) {
                 return null;
@@ -268,56 +393,98 @@ class AgentRunner {
             };
         }
         catch (error) {
-            (0, core_1.LogError)(`Error finding previous artifact: ${error.message}`);
+            LogError(`Error finding previous artifact: ${error.message}`);
             return null;
         }
     }
+    /**
+     * Processes agent completion to create artifacts from the agent's payload.
+     * Handles artifact creation, versioning, and linking to conversation details.
+     *
+     * This method implements intelligent artifact versioning:
+     * 1. If sourceArtifactId is provided (explicit continuity), creates new version of that artifact
+     * 2. Otherwise, checks for previous artifacts on this conversation detail
+     * 3. If previous artifact exists, creates new version of it
+     * 4. If no previous artifact, creates entirely new artifact
+     *
+     * Respects the agent's ArtifactCreationMode configuration:
+     * - "Never": Skips artifact creation entirely
+     * - "System Only": Creates artifact with Visibility='System Only'
+     * - Other modes: Creates artifact with Visibility='Always'
+     *
+     * @param agentResult - The result from agent execution containing the payload
+     * @param conversationDetailId - The conversation detail to link the artifact to
+     * @param sourceArtifactId - Optional explicit artifact to version from (agent continuity)
+     * @param contextUser - The user context for the operation
+     * @returns Artifact metadata if created, undefined if skipped or failed
+     *
+     * @example
+     * ```typescript
+     * const runner = new AgentRunner();
+     * const artifactInfo = await runner.ProcessAgentArtifacts(
+     *     agentResult,
+     *     conversationDetailId,
+     *     sourceArtifactId, // Optional
+     *     currentUser
+     * );
+     * if (artifactInfo) {
+     *     console.log(`Created artifact ${artifactInfo.artifactId} version ${artifactInfo.versionNumber}`);
+     * }
+     * ```
+     */
     async ProcessAgentArtifacts(agentResult, conversationDetailId, sourceArtifactId, contextUser) {
         const payload = agentResult.payload;
         const agentRun = agentResult.agentRun;
         if (!payload || Object.keys(payload).length === 0) {
-            (0, core_1.LogStatus)('No payload to create artifact from');
+            LogStatus('No payload to create artifact from');
             return undefined;
         }
-        await aiengine_1.AIEngine.Instance.Config(false, contextUser);
-        const agent = aiengine_1.AIEngine.Instance.Agents.find(a => a.ID === agentRun.AgentID);
+        // Check agent's ArtifactCreationMode
+        await AIEngine.Instance.Config(false, contextUser);
+        const agent = AIEngine.Instance.Agents.find(a => a.ID === agentRun.AgentID);
         const creationMode = agent?.ArtifactCreationMode;
         if (creationMode === 'Never') {
-            (0, core_1.LogStatus)(`Skipping artifact creation - agent "${agent?.Name}" has ArtifactCreationMode='Never'`);
+            LogStatus(`Skipping artifact creation - agent "${agent?.Name}" has ArtifactCreationMode='Never'`);
             return undefined;
         }
         try {
-            const md = new core_1.Metadata();
+            const md = new Metadata();
             const JSON_ARTIFACT_TYPE_ID = 'ae674c7e-ea0d-49ea-89e4-0649f5eb20d4';
+            // Determine if creating new artifact or new version
             let artifactId;
             let newVersionNumber;
             let isNewArtifact = false;
+            // Priority 1: Use explicit source artifact if provided
             if (sourceArtifactId) {
                 const maxVersion = await this.GetMaxVersionForArtifact(sourceArtifactId, contextUser);
                 artifactId = sourceArtifactId;
                 newVersionNumber = maxVersion + 1;
-                (0, core_1.LogStatus)(`Creating version ${newVersionNumber} of source artifact ${artifactId}`);
+                LogStatus(`Creating version ${newVersionNumber} of source artifact ${artifactId}`);
             }
+            // Priority 2: Try to find previous artifact for this message
             else {
                 const previousArtifact = await this.FindPreviousArtifactForMessage(conversationDetailId, contextUser);
                 if (previousArtifact) {
                     artifactId = previousArtifact.artifactId;
                     newVersionNumber = previousArtifact.versionNumber + 1;
-                    (0, core_1.LogStatus)(`Creating version ${newVersionNumber} of existing artifact ${artifactId}`);
+                    LogStatus(`Creating version ${newVersionNumber} of existing artifact ${artifactId}`);
                 }
                 else {
+                    // Create new artifact header
                     const artifact = await md.GetEntityObject('MJ: Artifacts', contextUser);
                     const agentName = agent?.Name || 'Agent';
                     artifact.Name = `${agentName} Payload - ${new Date().toLocaleString()}`;
                     artifact.Description = `Payload returned by ${agentName}`;
+                    // Use agent's DefaultArtifactTypeID if available
                     const defaultArtifactTypeId = agent?.DefaultArtifactTypeID;
                     artifact.TypeID = defaultArtifactTypeId || JSON_ARTIFACT_TYPE_ID;
                     artifact.UserID = contextUser.ID;
                     artifact.EnvironmentID = contextUser.EnvironmentID ||
                         'F51358F3-9447-4176-B313-BF8025FD8D09';
+                    // Set visibility based on agent's ArtifactCreationMode
                     if (creationMode === 'System Only') {
                         artifact.Visibility = 'System Only';
-                        (0, core_1.LogStatus)(`Artifact marked as "System Only" per agent configuration`);
+                        LogStatus(`Artifact marked as "System Only" per agent configuration`);
                     }
                     else {
                         artifact.Visibility = 'Always';
@@ -328,9 +495,10 @@ class AgentRunner {
                     artifactId = artifact.ID;
                     newVersionNumber = 1;
                     isNewArtifact = true;
-                    (0, core_1.LogStatus)(`Created new artifact: ${artifact.Name} (${artifactId})`);
+                    LogStatus(`Created new artifact: ${artifact.Name} (${artifactId})`);
                 }
             }
+            // Create artifact version with content
             const version = await md.GetEntityObject('MJ: Artifact Versions', contextUser);
             version.ArtifactID = artifactId;
             version.VersionNumber = newVersionNumber;
@@ -339,7 +507,8 @@ class AgentRunner {
             if (!(await version.Save())) {
                 throw new Error('Failed to save artifact version');
             }
-            (0, core_1.LogStatus)(`Created artifact version ${newVersionNumber} (${version.ID})`);
+            LogStatus(`Created artifact version ${newVersionNumber} (${version.ID})`);
+            // If first version of new artifact, check for extracted Name attribute
             if (isNewArtifact && newVersionNumber === 1) {
                 const nameAttr = version.Attributes?.find((attr) => attr.StandardProperty === 'name' || attr.Name?.toLowerCase() === 'name');
                 let extractedName = nameAttr?.Value?.trim();
@@ -349,11 +518,12 @@ class AgentRunner {
                     if (await artifact.Load(artifactId)) {
                         artifact.Name = extractedName;
                         if (await artifact.Save()) {
-                            (0, core_1.LogStatus)(`Updated artifact name to: ${artifact.Name}`);
+                            LogStatus(`Updated artifact name to: ${artifact.Name}`);
                         }
                     }
                 }
             }
+            // Create junction record linking artifact to conversation detail
             const junction = await md.GetEntityObject('MJ: Conversation Detail Artifacts', contextUser);
             junction.ConversationDetailID = conversationDetailId;
             junction.ArtifactVersionID = version.ID;
@@ -361,7 +531,7 @@ class AgentRunner {
             if (!(await junction.Save())) {
                 throw new Error('Failed to create artifact-message association');
             }
-            (0, core_1.LogStatus)(`Linked artifact to conversation detail ${conversationDetailId}`);
+            LogStatus(`Linked artifact to conversation detail ${conversationDetailId}`);
             return {
                 artifactId,
                 versionId: version.ID,
@@ -369,21 +539,35 @@ class AgentRunner {
             };
         }
         catch (error) {
-            (0, core_1.LogError)(`Failed to process agent artifacts: ${error.message}`);
+            LogError(`Failed to process agent artifacts: ${error.message}`);
             return undefined;
         }
     }
+    /**
+     * Generates a conversation name and description using the "Name Conversation" AI prompt.
+     * Same approach as UI - uses AI to create a meaningful title and description from the first user message.
+     * Falls back to null if prompt not found or execution fails (caller will use fallback).
+     *
+     * @param userMessage - The first user message to base the name on
+     * @param contextUser - User context for prompt execution
+     * @returns Generated conversation name and description, or null if generation failed
+     * @private
+     */
     async GenerateConversationName(userMessage, contextUser) {
         try {
-            const { AIPromptRunner } = await Promise.resolve().then(() => __importStar(require('@memberjunction/ai-prompts')));
-            const { AIPromptParams } = await Promise.resolve().then(() => __importStar(require('@memberjunction/ai-core-plus')));
-            const { AIEngine } = await Promise.resolve().then(() => __importStar(require('@memberjunction/aiengine')));
+            // Import AIPromptRunner, AIPromptParams, and AIEngine
+            const { AIPromptRunner } = await import('@memberjunction/ai-prompts');
+            const { AIPromptParams } = await import('@memberjunction/ai-core-plus');
+            const { AIEngine } = await import('@memberjunction/aiengine');
+            // Ensure AIEngine is configured
             await AIEngine.Instance.Config(false, contextUser);
+            // Find the "Name Conversation" prompt (same as UI)
             const prompt = AIEngine.Instance.Prompts.find(p => p.Name === 'Name Conversation');
             if (!prompt) {
-                (0, core_1.LogStatus)('Name Conversation prompt not found - using fallback naming');
+                LogStatus('Name Conversation prompt not found - using fallback naming');
                 return null;
             }
+            // Execute the prompt using AIPromptRunner
             const promptParams = new AIPromptParams();
             promptParams.prompt = prompt;
             promptParams.contextUser = contextUser;
@@ -391,12 +575,13 @@ class AgentRunner {
             const runner = new AIPromptRunner();
             const result = await runner.ExecutePrompt(promptParams);
             if (result && result.success && result.result) {
+                // Try to parse the result as JSON to extract name and description
                 const parsed = typeof result.result === 'string'
                     ? JSON.parse(result.result)
                     : result.result;
                 const { name, description } = parsed;
                 if (name) {
-                    (0, core_1.LogStatus)(`Generated conversation name via AI: "${name}" with description: "${description || ''}"`);
+                    LogStatus(`Generated conversation name via AI: "${name}" with description: "${description || ''}"`);
                     return {
                         name,
                         description: description || ''
@@ -406,46 +591,77 @@ class AgentRunner {
             return null;
         }
         catch (error) {
-            (0, core_1.LogError)(`Error generating conversation name: ${error.message}`);
+            LogError(`Error generating conversation name: ${error.message}`);
             return null;
         }
     }
+    /**
+     * Saves media outputs to AIAgentRunMedia table for permanent storage.
+     * This creates records for each media output promoted during agent execution.
+     *
+     * Only media with `persist !== false` is saved. Media items with `persist: false`
+     * are typically intercepted binary content that was never used in the final output.
+     *
+     * @param agentRunId - The ID of the agent run
+     * @param mediaOutputs - Array of media outputs to save
+     * @param contextUser - User context for the operation
+     * @returns Array of saved AIAgentRunMedia IDs
+     * @since 3.1.0
+     *
+     * @example
+     * ```typescript
+     * const runner = new AgentRunner();
+     * const mediaIds = await runner.SaveAgentRunMedia(
+     *     agentResult.agentRun.ID,
+     *     agentResult.mediaOutputs,
+     *     currentUser
+     * );
+     * console.log(`Saved ${mediaIds.length} media outputs`);
+     * ```
+     */
     async SaveAgentRunMedia(agentRunId, mediaOutputs, contextUser) {
         if (!mediaOutputs || mediaOutputs.length === 0) {
             return [];
         }
+        // Filter to only persist media that should be saved
+        // persist=false means intercepted but unused binary content (e.g., images not used in response)
         const mediaToSave = mediaOutputs.filter(m => m.persist !== false);
         if (mediaToSave.length === 0) {
-            (0, core_1.LogStatus)(`All ${mediaOutputs.length} media outputs have persist=false, skipping save`);
+            LogStatus(`All ${mediaOutputs.length} media outputs have persist=false, skipping save`);
             return [];
         }
         if (mediaToSave.length < mediaOutputs.length) {
-            (0, core_1.LogStatus)(`Filtering: ${mediaToSave.length} of ${mediaOutputs.length} media outputs will be persisted`);
+            LogStatus(`Filtering: ${mediaToSave.length} of ${mediaOutputs.length} media outputs will be persisted`);
         }
         const savedIds = [];
-        const md = new core_1.Metadata();
+        const md = new Metadata();
         try {
-            const aiEngine = aiengine_1.AIEngine.Instance;
+            // Use AIEngine's cached modalities instead of a fresh DB call
+            const aiEngine = AIEngine.Instance;
             for (let i = 0; i < mediaToSave.length; i++) {
                 const mediaOutput = mediaToSave[i];
                 try {
                     const mediaEntity = await md.GetEntityObject('MJ: AI Agent Run Medias', contextUser);
                     mediaEntity.AgentRunID = agentRunId;
+                    // Link to source prompt run media if this was promoted
                     if (mediaOutput.promptRunMediaId) {
                         mediaEntity.SourcePromptRunMediaID = mediaOutput.promptRunMediaId;
                     }
+                    // Get modality ID from cached engine data
                     const modality = aiEngine.GetModalityByName(mediaOutput.modality);
                     if (modality) {
                         mediaEntity.ModalityID = modality.ID;
                     }
                     else {
-                        (0, core_1.LogError)(`Unknown modality: ${mediaOutput.modality}`);
+                        LogError(`Unknown modality: ${mediaOutput.modality}`);
                         continue;
                     }
                     mediaEntity.MimeType = mediaOutput.mimeType;
+                    // Only store inline data if NOT from prompt run media
                     if (!mediaOutput.promptRunMediaId && mediaOutput.data) {
                         mediaEntity.InlineData = mediaOutput.data;
                     }
+                    // Set dimensions if available
                     if (mediaOutput.width) {
                         mediaEntity.Width = mediaOutput.width;
                     }
@@ -455,12 +671,14 @@ class AgentRunner {
                     if (mediaOutput.durationSeconds) {
                         mediaEntity.DurationSeconds = mediaOutput.durationSeconds;
                     }
+                    // Set label and metadata
                     if (mediaOutput.label) {
                         mediaEntity.Label = mediaOutput.label;
                     }
                     if (mediaOutput.metadata) {
                         mediaEntity.Metadata = JSON.stringify(mediaOutput.metadata);
                     }
+                    // Set description if available
                     if (mediaOutput.description) {
                         mediaEntity.Description = mediaOutput.description;
                     }
@@ -468,37 +686,60 @@ class AgentRunner {
                     const saved = await mediaEntity.Save();
                     if (saved) {
                         savedIds.push(mediaEntity.ID);
-                        (0, core_1.LogStatus)(`Saved AIAgentRunMedia: ${mediaEntity.ID} (${mediaOutput.modality})`);
+                        LogStatus(`Saved AIAgentRunMedia: ${mediaEntity.ID} (${mediaOutput.modality})`);
                     }
                     else {
-                        (0, core_1.LogError)(`Failed to save AIAgentRunMedia: ${mediaEntity.LatestResult?.Message}`);
+                        LogError(`Failed to save AIAgentRunMedia: ${mediaEntity.LatestResult?.Message}`);
                     }
                 }
                 catch (mediaError) {
-                    (0, core_1.LogError)(`Error saving media output ${i}: ${mediaError.message}`);
+                    LogError(`Error saving media output ${i}: ${mediaError.message}`);
                 }
             }
-            (0, core_1.LogStatus)(`Saved ${savedIds.length} of ${mediaToSave.length} media outputs for agent run ${agentRunId}`);
+            LogStatus(`Saved ${savedIds.length} of ${mediaToSave.length} media outputs for agent run ${agentRunId}`);
             return savedIds;
         }
         catch (error) {
-            (0, core_1.LogError)(`Error in SaveAgentRunMedia: ${error.message}`);
+            LogError(`Error in SaveAgentRunMedia: ${error.message}`);
             return savedIds;
         }
     }
+    /**
+     * Creates ConversationDetailAttachment records for media outputs.
+     * This enables media to be displayed in the conversation UI.
+     *
+     * @param conversationDetailId - The conversation detail to attach media to
+     * @param mediaOutputs - Array of media outputs
+     * @param agentRunMediaIds - Corresponding AIAgentRunMedia IDs
+     * @param contextUser - User context for the operation
+     * @returns Array of created attachment IDs
+     * @since 3.1.0
+     *
+     * @example
+     * ```typescript
+     * const runner = new AgentRunner();
+     * const attachmentIds = await runner.CreateConversationMediaAttachments(
+     *     conversationDetailId,
+     *     mediaOutputs,
+     *     agentRunMediaIds,
+     *     currentUser
+     * );
+     * ```
+     */
     async CreateConversationMediaAttachments(conversationDetailId, mediaOutputs, agentRunMediaIds, contextUser) {
         if (!mediaOutputs || mediaOutputs.length === 0) {
             return [];
         }
         const attachmentIds = [];
-        const md = new core_1.Metadata();
+        const md = new Metadata();
         try {
-            const aiEngine = aiengine_1.AIEngine.Instance;
+            // Use AIEngine's cached modalities instead of a fresh DB call
+            const aiEngine = AIEngine.Instance;
             for (let i = 0; i < mediaOutputs.length; i++) {
                 const mediaOutput = mediaOutputs[i];
                 const agentRunMediaId = agentRunMediaIds[i];
                 if (!agentRunMediaId) {
-                    (0, core_1.LogError)(`No AIAgentRunMedia ID for media output ${i}`);
+                    LogError(`No AIAgentRunMedia ID for media output ${i}`);
                     continue;
                 }
                 try {
@@ -506,20 +747,26 @@ class AgentRunner {
                     attachment.ConversationDetailID = conversationDetailId;
                     attachment.MimeType = mediaOutput.mimeType;
                     attachment.DisplayOrder = i;
+                    // Get modality ID from cached engine data
                     const modality = aiEngine.GetModalityByName(mediaOutput.modality);
                     if (modality) {
                         attachment.ModalityID = modality.ID;
                     }
                     else {
-                        (0, core_1.LogError)(`Unknown modality: ${mediaOutput.modality}`);
+                        LogError(`Unknown modality: ${mediaOutput.modality}`);
                         continue;
                     }
+                    // Generate a filename if none provided
                     const extension = this.getMimeTypeExtension(mediaOutput.mimeType);
                     attachment.FileName = mediaOutput.label || `${mediaOutput.modality.toLowerCase()}_${i + 1}.${extension}`;
+                    // Store inline data for small media
+                    // In the future, consider MJStorage for large files
                     if (mediaOutput.data) {
                         attachment.InlineData = mediaOutput.data;
+                        // Estimate file size from base64 length (base64 is ~33% larger than binary)
                         attachment.FileSizeBytes = Math.ceil(mediaOutput.data.length * 0.75);
                     }
+                    // Set dimensions if available
                     if (mediaOutput.width) {
                         attachment.Width = mediaOutput.width;
                     }
@@ -529,30 +776,35 @@ class AgentRunner {
                     if (mediaOutput.durationSeconds) {
                         attachment.DurationSeconds = Math.ceil(mediaOutput.durationSeconds);
                     }
+                    // Set description if available
                     if (mediaOutput.description) {
                         attachment.Description = mediaOutput.description;
                     }
                     const saved = await attachment.Save();
                     if (saved) {
                         attachmentIds.push(attachment.ID);
-                        (0, core_1.LogStatus)(`Created ConversationDetailAttachment: ${attachment.ID} (${mediaOutput.modality})`);
+                        LogStatus(`Created ConversationDetailAttachment: ${attachment.ID} (${mediaOutput.modality})`);
                     }
                     else {
-                        (0, core_1.LogError)(`Failed to create attachment: ${attachment.LatestResult?.Message}`);
+                        LogError(`Failed to create attachment: ${attachment.LatestResult?.Message}`);
                     }
                 }
                 catch (attachError) {
-                    (0, core_1.LogError)(`Error creating attachment ${i}: ${attachError.message}`);
+                    LogError(`Error creating attachment ${i}: ${attachError.message}`);
                 }
             }
-            (0, core_1.LogStatus)(`Created ${attachmentIds.length} conversation attachments for detail ${conversationDetailId}`);
+            LogStatus(`Created ${attachmentIds.length} conversation attachments for detail ${conversationDetailId}`);
             return attachmentIds;
         }
         catch (error) {
-            (0, core_1.LogError)(`Error in CreateConversationMediaAttachments: ${error.message}`);
+            LogError(`Error in CreateConversationMediaAttachments: ${error.message}`);
             return attachmentIds;
         }
     }
+    /**
+     * Gets file extension from MIME type
+     * @private
+     */
     getMimeTypeExtension(mimeType) {
         const mimeToExt = {
             'image/png': 'png',
@@ -571,5 +823,4 @@ class AgentRunner {
         return mimeToExt[mimeType.toLowerCase()] || 'bin';
     }
 }
-exports.AgentRunner = AgentRunner;
 //# sourceMappingURL=AgentRunner.js.map