@memberjunction/ai-agent-manager 2.109.0 → 2.110.0

package/src/agents/architect-agent.ts

@@ -51,9 +51,8 @@ export class AgentArchitectAgent extends BaseAgent {
         // Apply payload changes to get the spec that would be sent forward
         const payloadWithChanges = this.applyPayloadChanges<P>(currentPayload, nextStep);
 
-        // Extract the agentSpec from the nested payload structure
-        // The payload has structure: { metadata, requirements, design, agentSpec }
-        const agentSpec = (payloadWithChanges as any).agentSpec as AgentSpec;
+        // The payload IS the AgentSpec
+        const agentSpec = payloadWithChanges as AgentSpec;
 
         console.log('🏗️ Architect Agent: Validating AgentSpec:', agentSpec ? `Name="${agentSpec.Name}"` : 'agentSpec is null/undefined');
 
@@ -74,13 +73,9 @@ export class AgentArchitectAgent extends BaseAgent {
         // If spec was auto-corrected, update the payload with corrected spec
         if (validation.correctedSpec) {
             console.log('✓ Architect Agent: Auto-corrected AgentSpec, updating payload');
-            const updatedPayload = {
-                ...(payloadWithChanges as any),
-                agentSpec: validation.correctedSpec
-            };
             return {
                 ...nextStep,
-                newPayload: updatedPayload as P
+                newPayload: validation.correctedSpec as P
             };
         }
 
@@ -140,7 +135,116 @@ export class AgentArchitectAgent extends BaseAgent {
             }
         }
 
-        // 4. Validate optional but important fields
+        // 4. Validate TypeID and Status
+        const specWithType = correctedSpec as any;
+        if (!specWithType.TypeID) {
+            errors.push('❌ TypeID is required - must be "@lookup:MJ: AI Agent Types.Name=Loop" or "@lookup:MJ: AI Agent Types.Name=Flow"');
+        }
+
+        if (!specWithType.Status) {
+            // Auto-correct: add default
+            specWithType.Status = 'Active';
+            corrected = true;
+            console.log('✓ Auto-corrected: Added default Status = "Active"');
+        } else if (!['Active', 'Inactive', 'Pending'].includes(specWithType.Status)) {
+            errors.push(`❌ Status must be "Active", "Inactive", or "Pending", got: "${specWithType.Status}"`);
+        }
+
+        // 5. Validate agent type-specific requirements
+        const isLoopAgent = specWithType.TypeID?.includes('Loop');
+        const isFlowAgent = specWithType.TypeID?.includes('Flow');
+
+        if (isLoopAgent) {
+            // Loop agents require at least one prompt
+            if (!correctedSpec.Prompts || correctedSpec.Prompts.length === 0) {
+                errors.push('❌ Loop agents require at least ONE prompt in the Prompts array');
+            }
+        }
+
+        if (isFlowAgent) {
+            // CRITICAL: Flow agents MUST have empty Prompts array (no agent-level prompts)
+            if (correctedSpec.Prompts && correctedSpec.Prompts.length > 0) {
+                errors.push('❌ Flow agents MUST have empty Prompts array. If LLM is needed, use a Prompt step OR a Loop sub-agent instead of agent-level prompts.');
+            }
+
+            // Flow agents require Steps and Paths
+            if (!correctedSpec.Steps || correctedSpec.Steps.length === 0) {
+                errors.push('❌ Flow agents require at least ONE step in the Steps array');
+            }
+            // Paths are technically optional (single-step flows), but validate if present
+            if (correctedSpec.Steps && correctedSpec.Steps.length > 1) {
+                if (!correctedSpec.Paths || correctedSpec.Paths.length === 0) {
+                    errors.push('❌ Flow agents with multiple steps require at least ONE path in the Paths array');
+                }
+            }
+
+            // Validate that at least one step is marked as StartingStep
+            if (correctedSpec.Steps && correctedSpec.Steps.length > 0) {
+                const hasStartingStep = correctedSpec.Steps.some(step => step.StartingStep === true);
+                if (!hasStartingStep) {
+                    errors.push('❌ Flow agents require at least ONE step with StartingStep: true');
+                }
+
+                // Validate each step based on its type
+                for (let i = 0; i < correctedSpec.Steps.length; i++) {
+                    const step = correctedSpec.Steps[i];
+
+                    // Validate Action steps
+                    if (step.StepType === 'Action') {
+                        if (!step.ActionID) {
+                            errors.push(`❌ Action step "${step.Name}" (index ${i}) must have ActionID field`);
+                        }
+
+                        // Validate ActionInputMapping if provided (supports both string and object)
+                        if (step.ActionInputMapping) {
+                            try {
+                                if (typeof step.ActionInputMapping === 'string') {
+                                    JSON.parse(step.ActionInputMapping);
+                                }
+                                // else it's already an object, which is valid and will be stringified later
+                            } catch (e: any) {
+                                errors.push(`❌ Step "${step.Name}" (index ${i}) has invalid ActionInputMapping JSON: ${e?.message || String(e)}`);
+                            }
+                        }
+
+                        // Validate ActionOutputMapping if provided (supports both string and object)
+                        if (step.ActionOutputMapping) {
+                            try {
+                                if (typeof step.ActionOutputMapping === 'string') {
+                                    JSON.parse(step.ActionOutputMapping);
+                                }
+                                // else it's already an object, which is valid and will be stringified later
+                            } catch (e: any) {
+                                errors.push(`❌ Step "${step.Name}" (index ${i}) has invalid ActionOutputMapping JSON: ${e?.message || String(e)}`);
+                            }
+                        }
+                    }
+
+                    // Validate Prompt steps
+                    if (step.StepType === 'Prompt') {
+                        // If PromptID is empty or not provided, PromptText is required for inline creation
+                        if (!step.PromptID || step.PromptID === '') {
+                            if (!step.PromptText || step.PromptText.trim() === '') {
+                                errors.push(`❌ Prompt step "${step.Name}" (index ${i}) has empty PromptID but missing PromptText. For inline prompt creation, PromptText is required.`);
+                            }
+                            // PromptName and PromptDescription are recommended but not required
+                            if (!step.PromptName) {
+                                console.log(`⚠️ Warning: Prompt step "${step.Name}" (index ${i}) is missing PromptName (will default to "[Step Name] Prompt")`);
+                            }
+                        }
+                        // If PromptID is provided (existing prompt), other fields are optional
+                    }
+
+                    // Validate Sub-Agent steps
+                    if (step.StepType === 'Sub-Agent') {
+                        // SubAgentID can be empty "" for new sub-agents (will be linked by name matching)
+                        // No validation needed here - linking happens in AgentSpecSync
+                    }
+                }
+            }
+        }
+
+        // 6. Validate optional but important fields
         if (correctedSpec.FinalPayloadValidationMode &&
             !['Fail', 'Retry', 'Warn'].includes(correctedSpec.FinalPayloadValidationMode)) {
             errors.push(`❌ FinalPayloadValidationMode must be "Fail", "Retry", or "Warn", got: "${correctedSpec.FinalPayloadValidationMode}"`);
@@ -216,7 +320,7 @@ export class AgentArchitectAgent extends BaseAgent {
     }
 
     /**
-     * Validates SubAgent structure
+     * Validates SubAgent structure recursively
      */
     protected validateSubAgents(
         subAgents: AgentSpec['SubAgents']
@@ -259,6 +363,34 @@ export class AgentArchitectAgent extends BaseAgent {
                 errors.push(`❌ SubAgent at index ${i} is missing SubAgent.Name`);
             }
 
+            // Validate TypeID for sub-agent
+            if (!subAgent.SubAgent.TypeID) {
+                errors.push(`❌ SubAgent[${i}] "${subAgent.SubAgent.Name}" is missing TypeID field`);
+            } else {
+                // Validate Loop/Flow specific requirements for sub-agents
+                const isLoopSubAgent = subAgent.SubAgent.TypeID.includes('Loop');
+                const isFlowSubAgent = subAgent.SubAgent.TypeID.includes('Flow');
+
+                if (isLoopSubAgent) {
+                    // Loop sub-agents require at least one prompt
+                    if (!subAgent.SubAgent.Prompts || subAgent.SubAgent.Prompts.length === 0) {
+                        errors.push(`❌ Loop SubAgent[${i}] "${subAgent.SubAgent.Name}" requires at least ONE prompt in Prompts array`);
+                    }
+                }
+
+                if (isFlowSubAgent) {
+                    // Flow sub-agents MUST have empty Prompts array
+                    if (subAgent.SubAgent.Prompts && subAgent.SubAgent.Prompts.length > 0) {
+                        errors.push(`❌ Flow SubAgent[${i}] "${subAgent.SubAgent.Name}" MUST have empty Prompts array. Use Prompt steps or Loop sub-agents for LLM functionality.`);
+                    }
+
+                    // Flow sub-agents require Steps
+                    if (!subAgent.SubAgent.Steps || subAgent.SubAgent.Steps.length === 0) {
+                        errors.push(`❌ Flow SubAgent[${i}] "${subAgent.SubAgent.Name}" requires at least ONE step in Steps array`);
+                    }
+                }
+            }
+
             // Auto-correct: Add default StartingPayloadValidationMode if missing
             if (!subAgent.SubAgent.StartingPayloadValidationMode) {
                 subAgent.SubAgent.StartingPayloadValidationMode = 'Fail';
@@ -266,11 +398,33 @@ export class AgentArchitectAgent extends BaseAgent {
                 console.log(`✓ Auto-corrected: Added SubAgent[${i}].SubAgent.StartingPayloadValidationMode = "Fail"`);
             }
 
+            // Auto-correct: Add default Status if missing
+            if (!subAgent.SubAgent.Status) {
+                subAgent.SubAgent.Status = 'Active';
+                corrected = true;
+                console.log(`✓ Auto-corrected: Added SubAgent[${i}].SubAgent.Status = "Active"`);
+            }
+
             // Validate related-specific fields
             if (subAgent.Type === 'related' && !subAgent.AgentRelationshipID) {
                 // AgentRelationshipID can be empty for new relationships, it will be created on save
                 // This is not an error
             }
+
+            // Recursively validate nested sub-agents
+            if (subAgent.SubAgent.SubAgents && subAgent.SubAgent.SubAgents.length > 0) {
+                const nestedValidation = this.validateSubAgents(subAgent.SubAgent.SubAgents);
+                if (nestedValidation.errors.length > 0) {
+                    // Prefix nested errors with parent context
+                    const prefixedErrors = nestedValidation.errors.map(
+                        err => `SubAgent[${i}] "${subAgent.SubAgent.Name}" -> ${err}`
+                    );
+                    errors.push(...prefixedErrors);
+                }
+                if (nestedValidation.corrected) {
+                    corrected = true;
+                }
+            }
         }
 
         return { errors, corrected };

package/src/agents/builder-agent.ts

@@ -1,7 +1,10 @@
 import { BaseAgent } from '@memberjunction/ai-agents';
 import { ExecuteAgentParams, AgentConfiguration, BaseAgentNextStep, AgentSpec } from '@memberjunction/ai-core-plus';
 import { RegisterClass } from '@memberjunction/global';
+import { Metadata } from '@memberjunction/core';
+import { AIAgentRunStepEntityExtended } from '@memberjunction/core-entities';
 import { AgentSpecSync } from '../agent-spec-sync';
+import { TemplateEngineServer } from '@memberjunction/templates';
 
 /**
  * Builder Agent - Persists validated AgentSpec to database via AgentSpecSync
@@ -15,6 +18,7 @@ import { AgentSpecSync } from '../agent-spec-sync';
  * - Receive validated AgentSpec from payload
  * - Create AgentSpecSync instance
  * - Persist to database
+ * - Track mutations in AI Agent Run Steps table
  * - Return success with created agent ID, or failure with error details
  *
  * This agent does NOT iterate - it runs once and returns Success or Failed.
@@ -23,8 +27,9 @@ import { AgentSpecSync } from '../agent-spec-sync';
 export class AgentBuilderAgent extends BaseAgent {
 
     /**
-     * Override executeAgentInternal to run code instead of chat loop
-     * This follows the Skip Code Generator pattern
+     * Override executeAgentInternal to run code instead of chat loop.
+     *
+     * Directly creates the AI Agent Run Step with mutations from AgentSpecSync.
      */
     protected override async executeAgentInternal<P = any>(
         params: ExecuteAgentParams<P>,
@@ -34,55 +39,112 @@ export class AgentBuilderAgent extends BaseAgent {
         console.log('🔨 Builder Agent: Starting agent persistence...');
 
         try {
-            // Extract AgentSpec from nested payload structure
-            // The payload has structure: { metadata, requirements, design, agentSpec }
-            const agentSpec = (params.payload as any).agentSpec as AgentSpec;
-
+            // Validate payload
+            const agentSpec = params.payload as AgentSpec;
             if (!agentSpec) {
-                throw new Error('No AgentSpec found in payload.agentSpec - ensure Architect Agent placed it there');
+                throw new Error('No AgentSpec found in payload - ensure Architect Agent provided valid AgentSpec');
             }
-
             if (!agentSpec.Name) {
                 throw new Error('AgentSpec is missing required Name field');
             }
 
             console.log(`🔨 Builder Agent: Creating agent "${agentSpec.Name}"...`);
 
-            // Create AgentSpecSync instance
+            // Create AgentSpecSync and save to database
             const specSync = new AgentSpecSync(agentSpec, params.contextUser);
-
-            // Mark as dirty to ensure it saves
             specSync.markDirty();
 
-            // Save to database
-            const agentId = await specSync.SaveToDatabase();
+            const result = await specSync.SaveToDatabase();
+
+            if (!result.success) {
+                throw new Error('AgentSpecSync.SaveToDatabase() returned success=false');
+            }
+
+            console.log(`✅ Builder Agent: Successfully created agent with ID: ${result.agentId}`);
+
+            // Refresh metadata and template caches
+            console.log('🔄 Builder Agent: Refreshing metadata and template caches...');
+            const md = new Metadata();
+            await md.Refresh();
+
+            const templateEngine = new TemplateEngineServer();
+            await templateEngine.Config(true, params.contextUser);
+            console.log('✅ Builder Agent: Metadata and template caches refreshed');
 
-            console.log(`✅ Builder Agent: Successfully created agent with ID: ${agentId}`);
+            // Create AI Agent Run Step record directly
+            const agentRunId = params.parentRun?.ID || 'unknown';
+            const stepEntity = await md.GetEntityObject<AIAgentRunStepEntityExtended>(
+                'MJ: AI Agent Run Steps',
+                params.contextUser
+            );
 
-            // Return success with the created agent ID
-            const updatedSpec = { ...agentSpec, ID: agentId };
+            stepEntity.AgentRunID = agentRunId;
+            stepEntity.StepNumber = 2; // Validation is step 1, this is step 2
+            stepEntity.StepType = 'Decision';
+            stepEntity.StepName = 'Sync Agent Spec';
+            stepEntity.Status = 'Completed';
+            stepEntity.Success = true;
+            stepEntity.StartedAt = new Date();
+            stepEntity.CompletedAt = new Date();
 
+            // InputData = Full AgentSpec
+            stepEntity.InputData = JSON.stringify(agentSpec, null, 2);
+            stepEntity.PayloadAtStart = JSON.stringify(params.payload);
+
+            // OutputData = Mutations array
+            stepEntity.OutputData = JSON.stringify(result.mutations, null, 2);
+            stepEntity.PayloadAtEnd = stepEntity.PayloadAtStart;
+
+            await stepEntity.Save();
+            console.log(`✅ Builder Agent: Created AI Agent Run Step with ID: ${stepEntity.ID}`);
+
+            // Return success
+            const updatedSpec = { ...agentSpec, ID: result.agentId };
             return {
                 finalStep: {
                     terminate: true,
                     step: 'Success',
-                    reasoning: `Successfully created agent "${agentSpec.Name}" with ID: ${agentId}`,
+                    reasoning: `Successfully created agent "${agentSpec.Name}" with ID: ${result.agentId}`,
                     newPayload: updatedSpec as P
                 },
-                stepCount: 1
+                stepCount: 2
             };
 
         } catch (error: any) {
             console.error('❌ Builder Agent: Failed to create agent:', error);
 
-            // Return failure with error details
+            // Create failed AI Agent Run Step
+            const agentRunId = params.parentRun?.ID || 'unknown';
+            const md = new Metadata();
+            const stepEntity = await md.GetEntityObject<AIAgentRunStepEntityExtended>(
+                'MJ: AI Agent Run Steps',
+                params.contextUser
+            );
+
+            stepEntity.AgentRunID = agentRunId;
+            stepEntity.StepNumber = 2;
+            stepEntity.StepType = 'Decision';
+            stepEntity.StepName = 'Sync Agent Spec';
+            stepEntity.Status = 'Failed';
+            stepEntity.Success = false;
+            stepEntity.StartedAt = new Date();
+            stepEntity.CompletedAt = new Date();
+            stepEntity.ErrorMessage = error?.message || String(error);
+
+            stepEntity.InputData = JSON.stringify(params.payload, null, 2);
+            stepEntity.PayloadAtStart = JSON.stringify(params.payload);
+            stepEntity.OutputData = JSON.stringify({ error: error?.message || String(error) });
+            stepEntity.PayloadAtEnd = stepEntity.PayloadAtStart;
+
+            await stepEntity.Save();
+
             return {
                 finalStep: {
                     terminate: true,
                     step: 'Failed',
                     reasoning: `Failed to create agent: ${error?.message || String(error)}`
                 },
-                stepCount: 1
+                stepCount: 2
             };
         }
     }

package/src/old/agent-definition.interface.ts

@@ -182,4 +182,63 @@ export interface AgentManagerPayload {
       issues: string[];
     }[];
   };
+
+  /**
+   * Agent Loader section - for modification workflow
+   * Contains the loaded agent when modifying an existing agent
+   */
+  loadedAgent?: {
+    /** Full AgentSpec loaded from database with all nested structure */
+    agentSpec: any; // AgentSpec type from CorePlus
+    /** Copy of original spec for comparison during modification */
+    originalSpec: any; // AgentSpec type from CorePlus
+    /** When the agent was last modified in database */
+    lastModified: string;
+    /** Agent's current status */
+    status: string;
+  };
+
+  /**
+   * Modification Planner section - for modification workflow
+   * Contains the detailed plan for modifying an existing agent
+   */
+  modificationPlan?: {
+    /** High-level summary of all changes to be made */
+    changeSummary: string;
+    /** Fields that will be updated (field name -> old/new values) */
+    fieldsToUpdate?: Record<string, { old: any; new: any }>;
+    /** Actions to add (with action IDs from Find Best Action) */
+    actionsToAdd?: Array<{ id: string; name: string; reason: string }>;
+    /** Action IDs to remove from the agent */
+    actionsToRemove?: string[];
+    /** Sub-agents modifications (add/remove/update) */
+    subAgentsToModify?: Array<{
+      operation: 'add' | 'remove' | 'update';
+      subAgentName?: string;
+      subAgentId?: string;
+      details?: any;
+    }>;
+    /** Prompts to update or add */
+    promptsToUpdate?: Array<{
+      operation: 'add' | 'update' | 'remove';
+      agentName: string;
+      promptText?: string;
+      promptRole?: string;
+      promptPosition?: string;
+    }>;
+    /** Steps modifications for Flow agents only */
+    stepsToModify?: Array<{
+      operation: 'add' | 'remove' | 'update';
+      stepName?: string;
+      stepType?: string;
+      details?: any;
+    }>;
+    /** Paths modifications for Flow agents only */
+    pathsToModify?: Array<{
+      operation: 'add' | 'remove' | 'update';
+      from?: string;
+      to?: string;
+      details?: any;
+    }>;
+  };
 }