@memberjunction/ai-agent-manager 2.108.0 → 2.110.0

package/dist/agent-spec-sync.js

@@ -75,6 +75,11 @@ class AgentSpecSync {
          * @private
          */
         this._isDirty = false;
+        /**
+         * Tracks all database mutations performed during save operations
+         * @private
+         */
+        this._mutations = [];
         if (spec) {
             this.spec = this.initializeSpec(spec);
             this._isDirty = true;
@@ -84,13 +89,39 @@ class AgentSpecSync {
             this.spec = {
                 ID: '', // Will be set on save if empty
                 Name: '',
-                StartingPayloadValidationMode: () => 'Fail',
+                StartingPayloadValidationMode: 'Fail',
                 Actions: [],
                 SubAgents: []
             };
         }
         this._contextUser = contextUser;
     }
+    // ===== MUTATION TRACKING METHODS =====
+    /**
+     * Track a database mutation performed during save operation
+     * @private
+     */
+    trackMutation(entity, operation, id, description) {
+        this._mutations.push({
+            Entity: entity,
+            Operation: operation,
+            ID: id,
+            Description: description
+        });
+    }
+    /**
+     * Get all mutations tracked during the last save operation
+     * @returns Array of mutations
+     */
+    getMutations() {
+        return [...this._mutations];
+    }
+    /**
+     * Clear all tracked mutations
+     */
+    clearMutations() {
+        this._mutations = [];
+    }
     // ===== STATIC FACTORY METHODS =====
     /**
      * Load an agent and its complete hierarchy from the database by ID.
@@ -208,7 +239,8 @@ class AgentSpecSync {
             throw new Error(`Agent with ID ${agentId} not found`);
         }
         // Step 2: Batch load related entities using RunViews for optimal performance
-        const [actionsResult, childAgentsResult, relatedAgentsResult] = await rv.RunViews([
+        // Note: Load paths separately after steps to avoid hardcoded view name in subquery
+        const [actionsResult, childAgentsResult, relatedAgentsResult, promptsResult, stepsResult] = await rv.RunViews([
             {
                 EntityName: 'AI Agent Actions',
                 ExtraFilter: `AgentID='${agentId}'`,
@@ -226,6 +258,18 @@ class AgentSpecSync {
                 ExtraFilter: `AgentID='${agentId}' AND Status='Active'`,
                 OrderBy: '__mj_CreatedAt',
                 ResultType: 'entity_object'
+            },
+            {
+                EntityName: 'MJ: AI Agent Prompts',
+                ExtraFilter: `AgentID='${agentId}'`,
+                OrderBy: 'ExecutionOrder',
+                ResultType: 'entity_object'
+            },
+            {
+                EntityName: 'MJ: AI Agent Steps',
+                ExtraFilter: `AgentID='${agentId}'`,
+                OrderBy: 'Name',
+                ResultType: 'entity_object'
             }
         ], this._contextUser);
         // Check for errors
@@ -238,13 +282,84 @@ class AgentSpecSync {
         if (!relatedAgentsResult.Success) {
             throw new Error(`Failed to load related agents: ${relatedAgentsResult.ErrorMessage}`);
         }
+        if (!promptsResult.Success) {
+            throw new Error(`Failed to load agent prompts: ${promptsResult.ErrorMessage}`);
+        }
+        if (!stepsResult.Success) {
+            throw new Error(`Failed to load agent steps: ${stepsResult.ErrorMessage}`);
+        }
+        // Step 2b: Load paths separately using step IDs to avoid hardcoded view name
+        let pathsResult;
+        const steps = stepsResult.Results || [];
+        if (steps.length > 0) {
+            const stepIds = steps.map((s) => `'${s.ID}'`).join(',');
+            pathsResult = await rv.RunView({
+                EntityName: 'MJ: AI Agent Step Paths',
+                ExtraFilter: `OriginStepID IN (${stepIds})`,
+                OrderBy: 'Priority DESC',
+                ResultType: 'entity_object'
+            }, this._contextUser);
+            if (!pathsResult.Success) {
+                throw new Error(`Failed to load step paths: ${pathsResult.ErrorMessage}`);
+            }
+        }
+        else {
+            // No steps, so no paths
+            pathsResult = {
+                Success: true,
+                Results: [],
+                RowCount: 0
+            };
+        }
+        // Step 2c: Load full AI Prompt records to get PromptText, PromptRole, PromptPosition
+        let fullPromptsResult;
+        const agentPrompts = promptsResult.Results || [];
+        if (agentPrompts.length > 0) {
+            const promptIds = agentPrompts.map((p) => `'${p.PromptID}'`).join(',');
+            fullPromptsResult = await rv.RunView({
+                EntityName: 'AI Prompts',
+                ExtraFilter: `ID IN (${promptIds})`,
+                OrderBy: 'Name',
+                ResultType: 'entity_object'
+            }, this._contextUser);
+            if (!fullPromptsResult.Success) {
+                throw new Error(`Failed to load AI prompts: ${fullPromptsResult.ErrorMessage}`);
+            }
+        }
+        else {
+            // No prompts
+            fullPromptsResult = {
+                Success: true,
+                Results: [],
+                RowCount: 0
+            };
+        }
         // Step 3: Map entities to raw spec format
-        this.spec = this.mapEntitiesToRawSpec(agentEntity, actionsResult.Results || [], childAgentsResult.Results || [], relatedAgentsResult.Results || []);
+        this.spec = this.mapEntitiesToRawSpec(agentEntity, actionsResult.Results || [], childAgentsResult.Results || [], relatedAgentsResult.Results || [], promptsResult.Results || [], fullPromptsResult.Results || [], stepsResult.Results || [], pathsResult.Results || []);
         // Step 4: Recursively load sub-agents if requested
         if (includeSubAgents && this.spec.SubAgents && this.spec.SubAgents.length > 0) {
-            // Note: We don't recursively populate the full spec here since SubAgentSpec
-            // only contains the ID and relationship metadata. To get full details,
-            // users can call LoadFromDatabase on the SubAgentID separately if needed.
+            // Recursively load complete specs for all sub-agents
+            for (const subAgentSpec of this.spec.SubAgents) {
+                if (subAgentSpec.SubAgent && subAgentSpec.SubAgent.ID) {
+                    try {
+                        // Load the complete sub-agent spec recursively
+                        const subAgentSync = await AgentSpecSync.LoadFromDatabase(subAgentSpec.SubAgent.ID, this._contextUser, true // Recursively load nested sub-agents too
+                        );
+                        // Replace the minimal SubAgent with the complete spec
+                        const fullSubAgentSpec = subAgentSync.toJSON();
+                        // Preserve the relationship metadata while adding full spec details
+                        subAgentSpec.SubAgent = {
+                            ...fullSubAgentSpec,
+                            // Ensure we preserve any relationship-specific overrides
+                            StartingPayloadValidationMode: subAgentSpec.SubAgent.StartingPayloadValidationMode || fullSubAgentSpec.StartingPayloadValidationMode
+                        };
+                    }
+                    catch (error) {
+                        (0, core_1.LogError)(`Failed to load sub-agent ${subAgentSpec.SubAgent.ID}: ${error instanceof Error ? error.message : String(error)}`);
+                        // Continue with partial data rather than failing completely
+                    }
+                }
+            }
         }
         this._isLoaded = true;
         this._isDirty = false;
@@ -260,14 +375,20 @@ class AgentSpecSync {
      * @param actions - Array of agent action entities
      * @param childAgents - Array of child agent entities (ParentID-based)
      * @param relatedAgents - Array of related agent relationship entities
+     * @param agentPrompts - Array of agent prompt junction entities
+     * @param fullPrompts - Array of full AI Prompt entities with PromptText, PromptRole, PromptPosition
+     * @param steps - Array of agent step entities (for Flow agents)
+     * @param paths - Array of step path entities (for Flow agents)
      * @returns Fully populated AgentSpec object
      */
-    mapEntitiesToRawSpec(agent, actions, childAgents, relatedAgents) {
+    mapEntitiesToRawSpec(agent, actions, childAgents, relatedAgents, agentPrompts, fullPrompts, steps, paths) {
         // Map all agent fields to spec
         const spec = {
             ID: agent.ID,
             Name: agent.Name || '',
             Description: agent.Description || undefined,
+            TypeID: agent.TypeID || undefined,
+            Status: agent.Status || undefined,
             IconClass: agent.IconClass || undefined,
             LogoURL: agent.LogoURL || undefined,
             ParentID: agent.ParentID || undefined,
@@ -299,13 +420,22 @@ class AgentSpecSync {
             DefaultArtifactTypeID: agent.DefaultArtifactTypeID || undefined,
             OwnerUserID: agent.OwnerUserID || undefined,
             InvocationMode: agent.InvocationMode,
+            // Requirements and design documentation
+            FunctionalRequirements: agent.FunctionalRequirements || null,
+            TechnicalDesign: agent.TechnicalDesign || null,
             // Map actions
             Actions: actions.map(action => this.mapActionEntityToSpec(action)),
             // Map sub-agents (both child and related)
             SubAgents: [
                 ...childAgents.map(child => this.mapChildAgentToSpec(child)),
                 ...relatedAgents.map(rel => this.mapRelatedAgentToSpec(rel))
-            ]
+            ],
+            // Map prompts (agent-level prompts for Loop agents)
+            Prompts: agentPrompts.map(agentPrompt => this.mapPromptEntityToSpec(agentPrompt, fullPrompts)),
+            // Map steps (for Flow agents)
+            Steps: steps.map(step => this.mapStepEntityToSpec(step)),
+            // Map paths (for Flow agents)
+            Paths: paths.map(path => this.mapPathEntityToSpec(path))
         };
         return spec;
     }
@@ -339,7 +469,11 @@ class AgentSpecSync {
     mapChildAgentToSpec(childAgent) {
         return {
             Type: 'child',
-            SubAgentID: childAgent.ID
+            SubAgent: {
+                ID: childAgent.ID,
+                Name: childAgent.Name || '',
+                StartingPayloadValidationMode: 'Fail'
+            }
         };
     }
     /**
@@ -352,13 +486,82 @@ class AgentSpecSync {
     mapRelatedAgentToSpec(relationship) {
         return {
             Type: 'related',
-            SubAgentID: relationship.SubAgentID,
+            SubAgent: {
+                ID: relationship.SubAgentID,
+                Name: relationship.SubAgent || '',
+                StartingPayloadValidationMode: 'Fail'
+            },
             AgentRelationshipID: relationship.ID,
             SubAgentInputMapping: this.parseJsonField(relationship.SubAgentInputMapping),
             SubAgentOutputMapping: this.parseJsonField(relationship.SubAgentOutputMapping),
             SubAgentContextPaths: this.parseJsonField(relationship.SubAgentContextPaths)
         };
     }
+    /**
+     * Map AIAgentPromptEntity junction to AgentPromptSpec format.
+     *
+     * @private
+     * @param agentPrompt - The agent prompt junction entity (has PromptID, ExecutionOrder)
+     * @param fullPrompts - Array of full AI Prompt entities
+     * @returns Mapped prompt spec
+     */
+    mapPromptEntityToSpec(agentPrompt, fullPrompts) {
+        // Find the full prompt data by matching PromptID
+        const fullPrompt = fullPrompts.find((p) => p.ID === agentPrompt.PromptID);
+        if (!fullPrompt) {
+            // Fallback if prompt not found
+            return {
+                PromptID: agentPrompt.PromptID || '',
+                PromptText: '',
+                PromptRole: 'System',
+                PromptPosition: 'First'
+            };
+        }
+        return {
+            PromptID: fullPrompt.ID || '',
+            PromptText: fullPrompt.TemplateText || '',
+            PromptRole: fullPrompt.PromptRole || 'System',
+            PromptPosition: fullPrompt.PromptPosition || 'First'
+        };
+    }
+    /**
+     * Map AIAgentStepEntity to AgentStep format.
+     *
+     * @private
+     * @param step - The agent step entity
+     * @returns Mapped step spec
+     */
+    mapStepEntityToSpec(step) {
+        return {
+            ID: step.ID,
+            Name: step.Name,
+            Description: step.Description || undefined,
+            StepType: step.StepType,
+            StartingStep: step.StartingStep,
+            ActionID: step.ActionID || undefined,
+            SubAgentID: step.SubAgentID || undefined,
+            PromptID: step.PromptID || undefined,
+            ActionInputMapping: this.parseJsonField(step.ActionInputMapping),
+            ActionOutputMapping: this.parseJsonField(step.ActionOutputMapping)
+        };
+    }
+    /**
+     * Map AIAgentStepPathEntity to AgentStepPath format.
+     *
+     * @private
+     * @param path - The agent step path entity
+     * @returns Mapped path spec
+     */
+    mapPathEntityToSpec(path) {
+        return {
+            ID: path.ID,
+            OriginStepID: path.OriginStepID,
+            DestinationStepID: path.DestinationStepID,
+            Condition: path.Condition || undefined,
+            Description: path.Description || undefined,
+            Priority: path.Priority
+        };
+    }
     // ===== SAVING METHODS =====
     /**
      * Save the current spec to the database.
@@ -370,7 +573,7 @@ class AgentSpecSync {
      * database schema are executed, and any failures will prevent the save.
      *
      * @param validate - Whether to validate before saving (default: true)
-     * @returns Promise resolving to the saved agent ID
+     * @returns Promise resolving to result with agent ID, success flag, and all mutations performed
      * @throws {Error} If validation fails or save operation fails
      *
      * @example
@@ -380,24 +583,51 @@ class AgentSpecSync {
      *     InvocationMode: 'Any'
      * }, contextUser);
      *
-     * const agentId = await spec.SaveToDatabase();
-     * console.log('Saved with ID:', agentId);
+     * const result = await spec.SaveToDatabase();
+     * console.log('Saved with ID:', result.agentId);
+     * console.log('Mutations:', result.mutations.length);
      * ```
      */
     async SaveToDatabase(validate = true) {
+        // Clear previous mutations
+        this.clearMutations();
         if (!this._isDirty && this._isLoaded) {
             // No changes to save
-            return this.spec.ID;
-        }
-        // Step 1: Save main agent entity
-        const agentId = await this.saveAgentEntity(validate);
-        // Step 2: Save actions
-        await this.saveActions(agentId);
-        // Step 3: Save sub-agents (both child and related)
-        await this.saveSubAgents(agentId);
-        this._isDirty = false;
-        this._isLoaded = true;
-        return agentId;
+            return {
+                agentId: this.spec.ID,
+                success: true,
+                mutations: []
+            };
+        }
+        try {
+            // Step 1: Save main agent entity
+            const agentId = await this.saveAgentEntity(validate);
+            // Step 2: Save actions
+            await this.saveActions(agentId);
+            // Step 3: Save sub-agents (both child and related)
+            await this.saveSubAgents(agentId);
+            // Step 4: Save prompts
+            await this.savePrompts(agentId);
+            // Step 5: Save steps (Flow agents only)
+            await this.saveSteps(agentId);
+            // Step 6: Save step paths (Flow agents only)
+            await this.saveStepPaths(agentId);
+            this._isDirty = false;
+            this._isLoaded = true;
+            return {
+                agentId,
+                success: true,
+                mutations: this.getMutations()
+            };
+        }
+        catch (error) {
+            // Return failure with whatever mutations were completed before error
+            return {
+                agentId: this.spec.ID || '',
+                success: false,
+                mutations: this.getMutations()
+            };
+        }
     }
     /**
      * Save the main AIAgent entity.
@@ -410,6 +640,8 @@ class AgentSpecSync {
     async saveAgentEntity(validate) {
         const md = new core_1.Metadata();
         const agentEntity = await md.GetEntityObject('AI Agents', this._contextUser);
+        // Track if this is an update or create
+        const isUpdate = !!this.spec.ID;
         // If ID exists, load existing record
         if (this.spec.ID) {
             const loaded = await agentEntity.Load(this.spec.ID);
@@ -425,6 +657,17 @@ class AgentSpecSync {
         agentEntity.ParentID = this.spec.ParentID || null;
         agentEntity.DriverClass = this.spec.DriverClass || null;
         agentEntity.ModelSelectionMode = this.spec.ModelSelectionMode || 'Agent Type';
+        // Handle TypeID - supports lookup references or direct GUID
+        if (this.spec.TypeID) {
+            agentEntity.TypeID = this.spec.TypeID;
+        }
+        // Handle Status - defaults to Active if not specified
+        if (this.spec.Status) {
+            agentEntity.Status = this.spec.Status;
+        }
+        else {
+            agentEntity.Status = 'Active';
+        }
         // Serialize JSON fields
         agentEntity.PayloadDownstreamPaths = JSON.stringify(this.spec.PayloadDownstreamPaths || ['*']);
         agentEntity.PayloadUpstreamPaths = JSON.stringify(this.spec.PayloadUpstreamPaths || ['*']);
@@ -440,7 +683,7 @@ class AgentSpecSync {
         agentEntity.FinalPayloadValidationMode = this.spec.FinalPayloadValidationMode || 'Retry';
         agentEntity.FinalPayloadValidationMaxRetries = this.spec.FinalPayloadValidationMaxRetries || 3;
         agentEntity.StartingPayloadValidation = this.spec.StartingPayloadValidation || null;
-        agentEntity.StartingPayloadValidationMode = this.spec.StartingPayloadValidationMode?.() || 'Fail';
+        agentEntity.StartingPayloadValidationMode = this.spec.StartingPayloadValidationMode || 'Fail';
         // Resource limits
         agentEntity.MaxCostPerRun = this.spec.MaxCostPerRun || null;
         agentEntity.MaxTokensPerRun = this.spec.MaxTokensPerRun || null;
@@ -457,6 +700,9 @@ class AgentSpecSync {
             agentEntity.OwnerUserID = this.spec.OwnerUserID;
         }
         agentEntity.InvocationMode = this.spec.InvocationMode || 'Any';
+        // Requirements and design documentation
+        agentEntity.FunctionalRequirements = this.spec.FunctionalRequirements || null;
+        agentEntity.TechnicalDesign = this.spec.TechnicalDesign || null;
         // Validate if requested
         if (validate) {
             const validation = agentEntity.Validate();
@@ -472,6 +718,8 @@ class AgentSpecSync {
         }
         // Update spec with saved ID
         this.spec.ID = agentEntity.ID;
+        // Track the mutation
+        this.trackMutation('AI Agents', isUpdate ? 'Update' : 'Create', agentEntity.ID, `${isUpdate ? 'Updated' : 'Created'} agent: ${this.spec.Name}`);
         return agentEntity.ID;
     }
     /**
@@ -492,6 +740,8 @@ class AgentSpecSync {
         const md = new core_1.Metadata();
         for (const actionSpec of this.spec.Actions) {
             const actionEntity = await md.GetEntityObject('AI Agent Actions', this._contextUser);
+            // Track if this is an update or create
+            const isUpdate = !!actionSpec.AgentActionID;
             // Load existing if ID provided
             if (actionSpec.AgentActionID) {
                 await actionEntity.Load(actionSpec.AgentActionID);
@@ -512,6 +762,8 @@ class AgentSpecSync {
             }
             // Update spec with saved ID
             actionSpec.AgentActionID = actionEntity.ID;
+            // Track the mutation
+            this.trackMutation('AI Agent Actions', isUpdate ? 'Update' : 'Create', actionEntity.ID, `${isUpdate ? 'Updated' : 'Created'} action junction for action ${actionSpec.ActionID}`);
         }
     }
     /**
@@ -542,33 +794,49 @@ class AgentSpecSync {
      * Save a child sub-agent (ParentID-based relationship).
      *
      * For child agents, the relationship is established by setting the ParentID field
-     * on the child agent entity. If the SubAgentID is empty, this indicates a new
-     * child agent that needs to be created.
+     * on the child agent entity. If the SubAgent.ID is empty, this creates a new
+     * child agent recursively using AgentSpecSync.
+     *
+     * This enables creating complete agent hierarchies in one call - sub-agents are
+     * created first (depth-first), then parent references them via ParentID.
      *
      * @private
      * @param parentId - The parent agent ID
      * @param SubAgentSpec - The sub-agent specification
-     * @throws {Error} If child agent doesn't exist or save fails
+     * @throws {Error} If child agent save fails
      */
     async saveChildSubAgent(parentId, SubAgentSpec) {
-        if (!SubAgentSpec.SubAgentID) {
-            throw new Error('Child sub-agent must have a SubAgentID');
-        }
-        // For child agents, we just need to ensure the ParentID is set correctly
-        // The sub-agent itself should already exist or be created separately
-        const md = new core_1.Metadata();
-        const childEntity = await md.GetEntityObject('AI Agents', this._contextUser);
-        const loaded = await childEntity.Load(SubAgentSpec.SubAgentID);
-        if (!loaded) {
-            throw new Error(`Child agent ${SubAgentSpec.SubAgentID} not found`);
+        console.log(`🔗 saveChildSubAgent: Processing child "${SubAgentSpec.SubAgent?.Name}", ID="${SubAgentSpec.SubAgent?.ID}"`);
+        // If SubAgent.ID is empty or missing, create the sub-agent recursively
+        if (!SubAgentSpec.SubAgent?.ID || SubAgentSpec.SubAgent.ID === '') {
+            console.log(`🔨 saveChildSubAgent: Creating new child sub-agent "${SubAgentSpec.SubAgent.Name}"...`);
+            // Set ParentID in the sub-agent spec before creating it
+            const childSpec = {
+                ...SubAgentSpec.SubAgent,
+                ParentID: parentId
+            };
+            // Recursively create the sub-agent using AgentSpecSync
+            const childSync = new AgentSpecSync(childSpec, this._contextUser);
+            childSync.markDirty();
+            const childResult = await childSync.SaveToDatabase();
+            // Update the SubAgentSpec with the created ID so parent can reference it
+            SubAgentSpec.SubAgent.ID = childResult.agentId;
+            console.log(`✅ saveChildSubAgent: Created child sub-agent with ID: ${childResult.agentId}`);
         }
-        // Update parent ID if needed
-        if (childEntity.ParentID !== parentId) {
-            childEntity.ParentID = parentId;
-            const saved = await childEntity.Save();
-            if (!saved) {
-                throw new Error(`Failed to update ParentID for child agent ${SubAgentSpec.SubAgentID}`);
-            }
+        else {
+            // SubAgent already exists - update it recursively to capture all field changes
+            console.log(`🔗 saveChildSubAgent: Updating existing child sub-agent "${SubAgentSpec.SubAgent.ID}"...`);
+            // Set ParentID in the sub-agent spec
+            const childSpec = {
+                ...SubAgentSpec.SubAgent,
+                ParentID: parentId
+            };
+            // Recursively update the sub-agent using AgentSpecSync
+            // This ensures all fields including FunctionalRequirements and TechnicalDesign are updated
+            const childSync = new AgentSpecSync(childSpec, this._contextUser);
+            childSync.markDirty();
+            await childSync.SaveToDatabase();
+            console.log(`✅ saveChildSubAgent: Updated existing child sub-agent`);
         }
     }
     /**
@@ -586,12 +854,13 @@ class AgentSpecSync {
         const md = new core_1.Metadata();
         const relationshipEntity = await md.GetEntityObject('MJ: AI Agent Relationships', this._contextUser);
         // Load existing if ID provided
-        if (SubAgentSpec.AgentRelationshipID) {
+        const isUpdate = !!SubAgentSpec.AgentRelationshipID;
+        if (isUpdate && SubAgentSpec.AgentRelationshipID) {
             await relationshipEntity.Load(SubAgentSpec.AgentRelationshipID);
         }
         // Map fields
         relationshipEntity.AgentID = agentId;
-        relationshipEntity.SubAgentID = SubAgentSpec.SubAgentID;
+        relationshipEntity.SubAgentID = SubAgentSpec.SubAgent.ID;
         relationshipEntity.Status = 'Active';
         // Serialize mapping fields
         if (SubAgentSpec.SubAgentInputMapping) {
@@ -614,11 +883,282 @@ class AgentSpecSync {
         }
         const saved = await relationshipEntity.Save();
         if (!saved) {
-            throw new Error(`Failed to save relationship for sub-agent ${SubAgentSpec.SubAgentID}`);
+            throw new Error(`Failed to save relationship for sub-agent ${SubAgentSpec.SubAgent.ID}`);
         }
+        // Track mutation
+        this.trackMutation('AI Agent Relationships', isUpdate ? 'Update' : 'Create', relationshipEntity.ID, `${isUpdate ? 'Updated' : 'Created'} agent relationship for sub-agent ${SubAgentSpec.SubAgent.ID}`);
         // Update spec with saved ID
         SubAgentSpec.AgentRelationshipID = relationshipEntity.ID;
     }
+    /**
+     * Save all prompts for this agent.
+     *
+     * Creates AIPrompt records (with template) and AIAgentPrompt junction records.
+     * Supports simplified prompt format from Architect Agent with just PromptText,
+     * PromptRole, and PromptPosition.
+     *
+     * @private
+     * @param agentId - The parent agent ID
+     * @throws {Error} If any prompt save fails
+     */
+    async savePrompts(agentId) {
+        console.log(`💬 savePrompts: Called with agentId=${agentId}, Prompts=${this.spec.Prompts ? this.spec.Prompts.length : 'undefined'}`);
+        if (!this.spec.Prompts || this.spec.Prompts.length === 0) {
+            console.log('💬 savePrompts: No prompts to save, returning early');
+            return;
+        }
+        console.log(`💬 savePrompts: Processing ${this.spec.Prompts.length} prompt(s)...`);
+        const md = new core_1.Metadata();
+        const rv = new core_1.RunView();
+        // Step 1: Create or update AIPrompt records
+        for (let i = 0; i < this.spec.Prompts.length; i++) {
+            const promptSpec = this.spec.Prompts[i];
+            // Check if this is an update (has PromptID) or create (no PromptID)
+            let promptEntity = await md.GetEntityObject('AI Prompts', this._contextUser);
+            let isUpdate = false;
+            if (promptSpec.PromptID && promptSpec.PromptID !== '') {
+                // Load existing prompt for update
+                const loaded = await promptEntity.Load(promptSpec.PromptID);
+                if (loaded) {
+                    isUpdate = true;
+                    console.log(`💬 savePrompts: Updating existing prompt ID: ${promptSpec.PromptID}`);
+                }
+                else {
+                    console.warn(`💬 savePrompts: PromptID specified but not found, creating new prompt`);
+                }
+            }
+            // Set all required fields (both create and update)
+            promptEntity.Name = `${this.spec.Name} - Prompt ${i + 1}`;
+            promptEntity.Description = `Agent prompt ${i + 1} for ${this.spec.Name}`;
+            promptEntity.TypeID = 'a6da423e-f36b-1410-8dac-00021f8b792e'; // Chat type
+            promptEntity.Status = 'Active';
+            promptEntity.ResponseFormat = 'JSON';
+            // Handle prompt text - supports both string and object formats
+            if (typeof promptSpec.PromptText === 'string') {
+                promptEntity.TemplateText = promptSpec.PromptText;
+            }
+            else if (typeof promptSpec.PromptText === 'object') {
+                // Architect may send PromptText as {text: "...", json: {...}}
+                const promptTextObj = promptSpec.PromptText;
+                let combinedText = promptTextObj.text || '';
+                if (promptTextObj.json) {
+                    combinedText += '\n\n```json\n' + JSON.stringify(promptTextObj.json, null, 2) + '\n```';
+                }
+                promptEntity.TemplateText = combinedText;
+            }
+            // Set prompt role and position if provided
+            if (promptSpec.PromptRole) {
+                promptEntity.PromptRole = promptSpec.PromptRole;
+            }
+            if (promptSpec.PromptPosition) {
+                promptEntity.PromptPosition = promptSpec.PromptPosition;
+            }
+            const saved = await promptEntity.Save();
+            if (!saved) {
+                throw new Error(`Failed to save prompt ${i + 1} for agent ${this.spec.Name}`);
+            }
+            // Track mutation
+            this.trackMutation('AI Prompts', isUpdate ? 'Update' : 'Create', promptEntity.ID, `${isUpdate ? 'Updated' : 'Created'} prompt: ${promptEntity.Name}`);
+            // Update the spec with the saved/updated ID
+            promptSpec.PromptID = promptEntity.ID;
+            console.log(`✅ savePrompts: ${isUpdate ? 'Updated' : 'Created'} AIPrompt with ID: ${promptEntity.ID}`);
+            // Step 2: Create or update AIAgentPrompt junction
+            // Query for existing junction by AgentID + PromptID
+            const existingJunctionResult = await rv.RunView({
+                EntityName: 'MJ: AI Agent Prompts',
+                ExtraFilter: `AgentID='${agentId}' AND PromptID='${promptEntity.ID}'`,
+                ResultType: 'entity_object'
+            }, this._contextUser);
+            let agentPromptEntity;
+            let isJunctionUpdate = false;
+            if (existingJunctionResult.Success && existingJunctionResult.Results && existingJunctionResult.Results.length > 0) {
+                // Junction exists - load it for update
+                agentPromptEntity = existingJunctionResult.Results[0];
+                isJunctionUpdate = true;
+                console.log(`💬 savePrompts: Updating existing junction for prompt ${i + 1}`);
+            }
+            else {
+                // Junction doesn't exist - create new one
+                agentPromptEntity = await md.GetEntityObject('MJ: AI Agent Prompts', this._contextUser);
+                agentPromptEntity.AgentID = agentId;
+                agentPromptEntity.PromptID = promptEntity.ID;
+                console.log(`💬 savePrompts: Creating new junction for prompt ${i + 1}`);
+            }
+            // Set/update common fields (ExecutionOrder might change)
+            agentPromptEntity.ExecutionOrder = i;
+            agentPromptEntity.Status = 'Active';
+            const junctionSaved = await agentPromptEntity.Save();
+            if (!junctionSaved) {
+                throw new Error(`Failed to save agent-prompt junction for prompt ${i + 1}`);
+            }
+            // Track mutation
+            this.trackMutation('AI Agent Prompts', isJunctionUpdate ? 'Update' : 'Create', agentPromptEntity.ID, `${isJunctionUpdate ? 'Updated' : 'Created'} agent-prompt junction for prompt ${promptEntity.ID}`);
+            console.log(`✅ savePrompts: ${isJunctionUpdate ? 'Updated' : 'Created'} AIAgentPrompt junction with ID: ${agentPromptEntity.ID}`);
+        }
+        console.log(`✅ savePrompts: Successfully saved all ${this.spec.Prompts.length} prompt(s)`);
+    }
+    /**
+     * Save all steps for this agent (Flow agents only).
+     *
+     * Creates AIAgentStep records for each step in the spec. Steps define the nodes
+     * in a Flow agent's execution graph.
+     *
+     * @private
+     * @param agentId - The parent agent ID
+     * @throws {Error} If any step save fails
+     */
+    async saveSteps(agentId) {
+        console.log(`🔷 saveSteps: Called with agentId=${agentId}, Steps=${this.spec.Steps ? this.spec.Steps.length : 'undefined'}`);
+        if (!this.spec.Steps || this.spec.Steps.length === 0) {
+            console.log('🔷 saveSteps: No steps to save, returning early');
+            return;
+        }
+        console.log(`🔷 saveSteps: Processing ${this.spec.Steps.length} step(s)...`);
+        const md = new core_1.Metadata();
+        for (const stepSpec of this.spec.Steps) {
+            const stepEntity = await md.GetEntityObject('MJ: AI Agent Steps', this._contextUser);
+            // Load existing if ID provided
+            const isUpdate = !!(stepSpec.ID && stepSpec.ID !== '');
+            if (isUpdate) {
+                await stepEntity.Load(stepSpec.ID);
+            }
+            // Map fields
+            stepEntity.AgentID = agentId;
+            stepEntity.Name = stepSpec.Name;
+            stepEntity.Description = stepSpec.Description || null;
+            stepEntity.StepType = stepSpec.StepType;
+            stepEntity.StartingStep = stepSpec.StartingStep;
+            stepEntity.ActionID = stepSpec.ActionID || null;
+            stepEntity.SubAgentID = stepSpec.SubAgentID || null;
+            stepEntity.Status = 'Active'; // Default to Active
+            // Handle inline prompt creation for Prompt-type steps
+            // If StepType is Prompt and PromptID is empty, create a new AIPrompt record
+            if (stepSpec.StepType === 'Prompt' && (!stepSpec.PromptID || stepSpec.PromptID === '')) {
+                if (stepSpec.PromptText) {
+                    console.log(`🔷 saveSteps: Creating inline prompt for step "${stepSpec.Name}"`);
+                    // Create AIPrompt entity (using any type for TemplateText dynamic property)
+                    const promptEntity = await md.GetEntityObject('AI Prompts', this._contextUser);
+                    // Set prompt fields
+                    promptEntity.Name = stepSpec.PromptName || `${stepSpec.Name} Prompt`;
+                    promptEntity.Description = stepSpec.PromptDescription || `Prompt for step: ${stepSpec.Name}`;
+                    promptEntity.TypeID = 'a6da423e-f36b-1410-8dac-00021f8b792e'; // Chat type
+                    promptEntity.Status = 'Active';
+                    promptEntity.ResponseFormat = 'JSON';
+                    promptEntity.TemplateText = stepSpec.PromptText; // TemplateText is a dynamic property
+                    const promptSaved = await promptEntity.Save();
+                    if (!promptSaved) {
+                        throw new Error(`Failed to save inline prompt for step "${stepSpec.Name}"`);
+                    }
+                    // Track mutation
+                    this.trackMutation('AI Prompts', 'Create', promptEntity.ID, `Created inline prompt: ${promptEntity.Name}`);
+                    console.log(`✅ saveSteps: Created inline AIPrompt with ID: ${promptEntity.ID}`);
+                    // Link the created prompt to this step
+                    stepEntity.PromptID = promptEntity.ID;
+                    stepSpec.PromptID = promptEntity.ID; // Update spec too
+                }
+                else {
+                    console.warn(`⚠️ saveSteps: Step "${stepSpec.Name}" is Prompt type with empty PromptID but no PromptText provided`);
+                    stepEntity.PromptID = null;
+                }
+            }
+            else {
+                stepEntity.PromptID = stepSpec.PromptID || null;
+            }
+            // Map Action I/O mappings for Flow agent action steps
+            // Handle ActionInputMapping - convert object to JSON string if needed
+            if (stepSpec.ActionInputMapping) {
+                stepEntity.ActionInputMapping = typeof stepSpec.ActionInputMapping === 'string'
+                    ? stepSpec.ActionInputMapping
+                    : JSON.stringify(stepSpec.ActionInputMapping);
+            }
+            else {
+                stepEntity.ActionInputMapping = null;
+            }
+            // Handle ActionOutputMapping - convert object to JSON string if needed
+            if (stepSpec.ActionOutputMapping) {
+                stepEntity.ActionOutputMapping = typeof stepSpec.ActionOutputMapping === 'string'
+                    ? stepSpec.ActionOutputMapping
+                    : JSON.stringify(stepSpec.ActionOutputMapping);
+            }
+            else {
+                stepEntity.ActionOutputMapping = null;
+            }
+            const saved = await stepEntity.Save();
+            if (!saved) {
+                throw new Error(`Failed to save step "${stepSpec.Name}" for agent ${this.spec.Name}`);
+            }
+            // Track mutation
+            this.trackMutation('AI Agent Steps', isUpdate ? 'Update' : 'Create', stepEntity.ID, `${isUpdate ? 'Updated' : 'Created'} step: ${stepSpec.Name}`);
+            // Update the spec with the saved ID so paths can reference it
+            stepSpec.ID = stepEntity.ID;
+            console.log(`✅ saveSteps: Created AIAgentStep with ID: ${stepEntity.ID}`);
+        }
+        console.log(`✅ saveSteps: Successfully saved all ${this.spec.Steps.length} step(s)`);
+    }
+    /**
+     * Save all step paths for this agent (Flow agents only).
+     *
+     * Creates AIAgentStepPath records that define the edges in a Flow agent's
+     * execution graph, including conditional branching logic.
+     *
+     * @private
+     * @param agentId - The parent agent ID
+     * @throws {Error} If any path save fails
+     */
+    async saveStepPaths(agentId) {
+        console.log(`🔶 saveStepPaths: Called with agentId=${agentId}, Paths=${this.spec.Paths ? this.spec.Paths.length : 'undefined'}`);
+        if (!this.spec.Paths || this.spec.Paths.length === 0) {
+            console.log('🔶 saveStepPaths: No paths to save, returning early');
+            return;
+        }
+        console.log(`🔶 saveStepPaths: Processing ${this.spec.Paths.length} path(s)...`);
+        const md = new core_1.Metadata();
+        // Create a map of step names to IDs for easy lookup
+        const stepNameToId = new Map();
+        if (this.spec.Steps) {
+            for (const step of this.spec.Steps) {
+                if (step.ID) {
+                    stepNameToId.set(step.Name, step.ID);
+                }
+            }
+        }
+        for (const pathSpec of this.spec.Paths) {
+            const pathEntity = await md.GetEntityObject('MJ: AI Agent Step Paths', this._contextUser);
+            // Load existing if ID provided
+            const isUpdate = !!(pathSpec.ID && pathSpec.ID !== '');
+            if (isUpdate) {
+                await pathEntity.Load(pathSpec.ID);
+            }
+            // Resolve step IDs from step names
+            // OriginStepID and DestinationStepID can be either step IDs or step names
+            // If they're names, look them up in our map
+            let originStepId = pathSpec.OriginStepID;
+            let destinationStepId = pathSpec.DestinationStepID;
+            // Try to resolve as step names first
+            if (stepNameToId.has(pathSpec.OriginStepID)) {
+                originStepId = stepNameToId.get(pathSpec.OriginStepID);
+            }
+            if (stepNameToId.has(pathSpec.DestinationStepID)) {
+                destinationStepId = stepNameToId.get(pathSpec.DestinationStepID);
+            }
+            // Map fields
+            pathEntity.OriginStepID = originStepId;
+            pathEntity.DestinationStepID = destinationStepId;
+            pathEntity.Condition = pathSpec.Condition || null;
+            pathEntity.Description = pathSpec.Description || null;
+            pathEntity.Priority = pathSpec.Priority;
+            const saved = await pathEntity.Save();
+            if (!saved) {
+                throw new Error(`Failed to save path from "${pathSpec.OriginStepID}" to "${pathSpec.DestinationStepID}"`);
+            }
+            // Track mutation
+            this.trackMutation('AI Agent Step Paths', isUpdate ? 'Update' : 'Create', pathEntity.ID, `${isUpdate ? 'Updated' : 'Created'} path from "${pathSpec.OriginStepID}" to "${pathSpec.DestinationStepID}"`);
+            // Update the spec with the saved ID
+            pathSpec.ID = pathEntity.ID;
+            console.log(`✅ saveStepPaths: Created AIAgentStepPath with ID: ${pathEntity.ID}`);
+        }
+        console.log(`✅ saveStepPaths: Successfully saved all ${this.spec.Paths.length} path(s)`);
+    }
     // ===== UTILITY METHODS =====
     /**
      * Parse a JSON string field, returning undefined if null/empty.
@@ -656,6 +1196,9 @@ class AgentSpecSync {
             ID: partial.ID || '',
             Name: partial.Name || '',
             Description: partial.Description,
+            // TypeID and Status are extended fields (not in base AgentSpec interface)
+            TypeID: partial.TypeID,
+            Status: partial.Status || 'Active',
             IconClass: partial.IconClass,
             LogoURL: partial.LogoURL,
             ParentID: partial.ParentID,
@@ -676,14 +1219,20 @@ class AgentSpecSync {
             MinExecutionsPerRun: partial.MinExecutionsPerRun,
             MaxExecutionsPerRun: partial.MaxExecutionsPerRun,
             StartingPayloadValidation: partial.StartingPayloadValidation,
-            StartingPayloadValidationMode: partial.StartingPayloadValidationMode || (() => 'Fail'),
+            StartingPayloadValidationMode: partial.StartingPayloadValidationMode || 'Fail',
             DefaultPromptEffortLevel: partial.DefaultPromptEffortLevel,
             ChatHandlingOption: partial.ChatHandlingOption,
             DefaultArtifactTypeID: partial.DefaultArtifactTypeID,
             OwnerUserID: partial.OwnerUserID,
             InvocationMode: partial.InvocationMode || 'Any',
+            FunctionalRequirements: partial.FunctionalRequirements,
+            TechnicalDesign: partial.TechnicalDesign,
             Actions: partial.Actions || [],
-            SubAgents: partial.SubAgents || []
+            SubAgents: partial.SubAgents || [],
+            Prompts: partial.Prompts || [],
+            // Flow agent fields - critical for Flow agent support
+            Steps: partial.Steps || [],
+            Paths: partial.Paths || []
         };
     }
     /**