@memberjunction/ai-agent-manager 2.107.0 → 2.109.0

package/src/agents/architect-agent.ts

@@ -0,0 +1,293 @@
+import { BaseAgent, PayloadManager } from '@memberjunction/ai-agents';
+import { ExecuteAgentParams, BaseAgentNextStep, AgentSpec } from '@memberjunction/ai-core-plus';
+import { AIAgentRunEntityExtended, AIAgentRunStepEntityExtended, ActionEntity, AIPromptEntity } from '@memberjunction/core-entities';
+import { Metadata, RunView } from '@memberjunction/core';
+import { RegisterClass } from '@memberjunction/global';
+
+/**
+ * Architect Agent - Transforms technical design into validated AgentSpec JSON
+ *
+ * This agent creates AgentSpec objects from technical designs and validates them
+ * before passing to the Builder Agent for persistence. It overrides validateSuccessNextStep
+ * to ensure the generated AgentSpec is valid before proceeding.
+ *
+ * Key responsibilities:
+ * - Transform design documents into AgentSpec format
+ * - Validate required fields are present
+ * - Verify action IDs exist in database
+ * - Verify prompt IDs exist (if specified)
+ * - Validate SubAgent structure
+ * - Auto-correct minor issues (casing, missing optional fields)
+ * - Force retry with detailed errors if validation fails
+ */
+@RegisterClass(BaseAgent, 'AgentArchitectAgent')
+export class AgentArchitectAgent extends BaseAgent {
+
+    /**
+     * Applies payload changes if any are requested in the next step
+     */
+    protected applyPayloadChanges<P>(payload: P, nextStep: BaseAgentNextStep<P>): P {
+        if (nextStep.payloadChangeRequest) {
+            const pm = new PayloadManager();
+            const result = pm.applyAgentChangeRequest<P>(payload, nextStep.payloadChangeRequest);
+            return result.result || payload;
+        }
+        return payload;
+    }
+
+    protected override async validateSuccessNextStep<P>(
+        params: ExecuteAgentParams,
+        nextStep: BaseAgentNextStep<P>,
+        currentPayload: P,
+        agentRun: AIAgentRunEntityExtended,
+        currentStep: AIAgentRunStepEntityExtended
+    ): Promise<BaseAgentNextStep<P>> {
+        // First call base validation
+        const baseValidation = await super.validateSuccessNextStep(params, nextStep, currentPayload, agentRun, currentStep);
+        if (baseValidation.step === 'Retry') {
+            return baseValidation;
+        }
+
+        // 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;
+
+        console.log('🏗️ Architect Agent: Validating AgentSpec:', agentSpec ? `Name="${agentSpec.Name}"` : 'agentSpec is null/undefined');
+
+        // Validate the AgentSpec
+        const validation = await this.validateAgentSpec(agentSpec, params);
+
+        if (validation.errors.length > 0) {
+            console.log('❌ Architect Agent: Validation failed with errors:', validation.errors);
+            // Return retry with detailed error messages
+            return {
+                ...nextStep,
+                step: 'Retry',
+                retryInstructions: this.formatValidationErrors(validation.errors),
+                newPayload: nextStep.newPayload
+            };
+        }
+
+        // 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
+            };
+        }
+
+        console.log('✅ Architect Agent: AgentSpec validation passed');
+        return nextStep;
+    }
+
+    /**
+     * Validates an AgentSpec object
+     * Returns errors array and potentially a corrected spec
+     */
+    protected async validateAgentSpec(
+        spec: AgentSpec,
+        params: ExecuteAgentParams
+    ): Promise<{ errors: string[]; correctedSpec?: AgentSpec }> {
+        const errors: string[] = [];
+        let corrected = false;
+
+        // Check if spec exists
+        if (!spec) {
+            errors.push('❌ AgentSpec is null or undefined. Ensure you place the AgentSpec in payload.agentSpec (inside a payloadChangeRequest with newElements or replaceElements)');
+            return { errors };
+        }
+
+        const correctedSpec = { ...spec };
+
+        // 1. Validate required fields
+        if (!correctedSpec.Name || correctedSpec.Name.trim().length === 0) {
+            errors.push('❌ AgentSpec.Name is required and cannot be empty');
+        }
+
+        if (!correctedSpec.StartingPayloadValidationMode) {
+            // Auto-correct: add default
+            correctedSpec.StartingPayloadValidationMode = 'Fail';
+            corrected = true;
+            console.log('✓ Auto-corrected: Added default StartingPayloadValidationMode = "Fail"');
+        } else if (correctedSpec.StartingPayloadValidationMode !== 'Fail' && correctedSpec.StartingPayloadValidationMode !== 'Warn') {
+            errors.push(`❌ StartingPayloadValidationMode must be either "Fail" or "Warn", got: "${correctedSpec.StartingPayloadValidationMode}"`);
+        }
+
+        // 2. Validate Actions if specified
+        if (correctedSpec.Actions && correctedSpec.Actions.length > 0) {
+            const actionValidation = await this.validateActions(correctedSpec.Actions, params);
+            if (actionValidation.errors.length > 0) {
+                errors.push(...actionValidation.errors);
+            }
+        }
+
+        // 3. Validate SubAgents if specified
+        if (correctedSpec.SubAgents && correctedSpec.SubAgents.length > 0) {
+            const subAgentValidation = this.validateSubAgents(correctedSpec.SubAgents);
+            if (subAgentValidation.errors.length > 0) {
+                errors.push(...subAgentValidation.errors);
+            }
+            if (subAgentValidation.corrected) {
+                corrected = true;
+            }
+        }
+
+        // 4. 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}"`);
+        }
+
+        if (correctedSpec.InvocationMode &&
+            !['Any', 'Agent', 'User', 'Never'].includes(correctedSpec.InvocationMode)) {
+            errors.push(`❌ InvocationMode must be "Any", "Agent", "User", or "Never", got: "${correctedSpec.InvocationMode}"`);
+        }
+
+        return {
+            errors,
+            correctedSpec: corrected ? correctedSpec : undefined
+        };
+    }
+
+    /**
+     * Validates that action IDs exist in the database
+     */
+    protected async validateActions(
+        actions: AgentSpec['Actions'],
+        params: ExecuteAgentParams
+    ): Promise<{ errors: string[] }> {
+        const errors: string[] = [];
+
+        if (!actions || actions.length === 0) {
+            return { errors };
+        }
+
+        try {
+            const rv = new RunView();
+            const actionIds = actions
+                .map(a => a.ActionID)
+                .filter(id => id && id.trim().length > 0);
+
+            if (actionIds.length === 0) {
+                errors.push('❌ All actions must have an ActionID');
+                return { errors };
+            }
+
+            // Query database for these action IDs
+            const filter = actionIds.map(id => `ID='${id}'`).join(' OR ');
+            const result = await rv.RunView<ActionEntity>({
+                EntityName: 'Actions',
+                ExtraFilter: filter,
+                ResultType: 'entity_object'
+            }, params.contextUser);
+
+            if (!result.Success) {
+                errors.push(`❌ Failed to validate actions: ${result.ErrorMessage}`);
+                return { errors };
+            }
+
+            const foundIds = new Set(result.Results.map(a => a.ID));
+
+            // Check which actions weren't found
+            for (const action of actions) {
+                if (!action.ActionID) {
+                    errors.push('❌ Action is missing ActionID field');
+                    continue;
+                }
+
+                if (!foundIds.has(action.ActionID)) {
+                    errors.push(`❌ Action with ID "${action.ActionID}" not found in database. Please use "Find Best Action" or "List Actions" to get valid action IDs.`);
+                }
+            }
+
+        } catch (error: any) {
+            errors.push(`❌ Error validating actions: ${error?.message || String(error)}`);
+        }
+
+        return { errors };
+    }
+
+    /**
+     * Validates SubAgent structure
+     */
+    protected validateSubAgents(
+        subAgents: AgentSpec['SubAgents']
+    ): { errors: string[]; corrected: boolean } {
+        const errors: string[] = [];
+        let corrected = false;
+
+        if (!subAgents || subAgents.length === 0) {
+            return { errors, corrected };
+        }
+
+        for (let i = 0; i < subAgents.length; i++) {
+            const subAgent = subAgents[i];
+
+            // Validate Type field
+            if (!subAgent.Type) {
+                errors.push(`❌ SubAgent at index ${i} is missing required "Type" field (must be "child" or "related")`);
+                continue;
+            }
+
+            if (subAgent.Type !== 'child' && subAgent.Type !== 'related') {
+                errors.push(`❌ SubAgent at index ${i} has invalid Type "${subAgent.Type}" (must be "child" or "related")`);
+                continue;
+            }
+
+            // Validate SubAgent.SubAgent field
+            if (!subAgent.SubAgent) {
+                errors.push(`❌ SubAgent at index ${i} is missing required "SubAgent" field`);
+                continue;
+            }
+
+            // SubAgent.ID can be empty string "" for NEW sub-agents (Builder creates them recursively)
+            // Only validate that ID is not null/undefined
+            if (subAgent.SubAgent.ID === null || subAgent.SubAgent.ID === undefined) {
+                errors.push(`❌ SubAgent at index ${i} has null/undefined SubAgent.ID (use empty string "" for new sub-agents, or provide existing agent GUID)`);
+            }
+
+            // Validate SubAgent.SubAgent.Name
+            if (!subAgent.SubAgent.Name || subAgent.SubAgent.Name.trim().length === 0) {
+                errors.push(`❌ SubAgent at index ${i} is missing SubAgent.Name`);
+            }
+
+            // Auto-correct: Add default StartingPayloadValidationMode if missing
+            if (!subAgent.SubAgent.StartingPayloadValidationMode) {
+                subAgent.SubAgent.StartingPayloadValidationMode = 'Fail';
+                corrected = true;
+                console.log(`✓ Auto-corrected: Added SubAgent[${i}].SubAgent.StartingPayloadValidationMode = "Fail"`);
+            }
+
+            // 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
+            }
+        }
+
+        return { errors, corrected };
+    }
+
+    /**
+     * Formats validation errors into a clear, actionable message
+     */
+    protected formatValidationErrors(errors: string[]): string {
+        if (errors.length === 0) {
+            return '';
+        }
+
+        const header = '## AgentSpec Validation Errors\n\nThe generated AgentSpec has the following issues that must be fixed:\n\n';
+        const errorList = errors.map((err, idx) => `${idx + 1}. ${err}`).join('\n');
+        const footer = '\n\n**Please fix these issues and regenerate the AgentSpec.**';
+
+        return header + errorList + footer;
+    }
+}

package/src/agents/builder-agent.ts

@@ -0,0 +1,89 @@
+import { BaseAgent } from '@memberjunction/ai-agents';
+import { ExecuteAgentParams, AgentConfiguration, BaseAgentNextStep, AgentSpec } from '@memberjunction/ai-core-plus';
+import { RegisterClass } from '@memberjunction/global';
+import { AgentSpecSync } from '../agent-spec-sync';
+
+/**
+ * Builder Agent - Persists validated AgentSpec to database via AgentSpecSync
+ *
+ * This is a code-based agent that overrides executeAgentInternal to bypass
+ * the normal chat loop and directly execute persistence logic. It receives
+ * a validated AgentSpec from the Architect Agent and saves it to the database
+ * using AgentSpecSync.
+ *
+ * Key responsibilities:
+ * - Receive validated AgentSpec from payload
+ * - Create AgentSpecSync instance
+ * - Persist to database
+ * - Return success with created agent ID, or failure with error details
+ *
+ * This agent does NOT iterate - it runs once and returns Success or Failed.
+ */
+@RegisterClass(BaseAgent, 'AgentBuilderAgent')
+export class AgentBuilderAgent extends BaseAgent {
+
+    /**
+     * Override executeAgentInternal to run code instead of chat loop
+     * This follows the Skip Code Generator pattern
+     */
+    protected override async executeAgentInternal<P = any>(
+        params: ExecuteAgentParams<P>,
+        _config: AgentConfiguration
+    ): Promise<{ finalStep: BaseAgentNextStep<P>; stepCount: number }> {
+
+        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;
+
+            if (!agentSpec) {
+                throw new Error('No AgentSpec found in payload.agentSpec - ensure Architect Agent placed it there');
+            }
+
+            if (!agentSpec.Name) {
+                throw new Error('AgentSpec is missing required Name field');
+            }
+
+            console.log(`🔨 Builder Agent: Creating agent "${agentSpec.Name}"...`);
+
+            // Create AgentSpecSync instance
+            const specSync = new AgentSpecSync(agentSpec, params.contextUser);
+
+            // Mark as dirty to ensure it saves
+            specSync.markDirty();
+
+            // Save to database
+            const agentId = await specSync.SaveToDatabase();
+
+            console.log(`✅ Builder Agent: Successfully created agent with ID: ${agentId}`);
+
+            // Return success with the created agent ID
+            const updatedSpec = { ...agentSpec, ID: agentId };
+
+            return {
+                finalStep: {
+                    terminate: true,
+                    step: 'Success',
+                    reasoning: `Successfully created agent "${agentSpec.Name}" with ID: ${agentId}`,
+                    newPayload: updatedSpec as P
+                },
+                stepCount: 1
+            };
+
+        } catch (error: any) {
+            console.error('❌ Builder Agent: Failed to create agent:', error);
+
+            // Return failure with error details
+            return {
+                finalStep: {
+                    terminate: true,
+                    step: 'Failed',
+                    reasoning: `Failed to create agent: ${error?.message || String(error)}`
+                },
+                stepCount: 1
+            };
+        }
+    }
+}

package/src/index.ts

@@ -1,8 +1,29 @@
 /**
  * @module @memberjunction/agent-manager-core
- * 
+ *
  * Core interfaces and types for the MemberJunction Agent Manager system
  */
 
 // Export all interfaces
-export * from './interfaces/agent-definition.interface';
+export * from './old/agent-definition.interface';
+
+export * from './agent-spec-sync';
+
+// Export agent implementations
+export * from './agents/architect-agent';
+export * from './agents/builder-agent';
+
+/**
+ * Loads the Agent Manager Core module and ensures all agent classes are registered.
+ * This function prevents tree shaking from removing the agent class registrations.
+ *
+ * The function itself doesn't need to do anything - importing the module is enough
+ * to trigger the @RegisterClass decorators on AgentArchitectAgent and AgentBuilderAgent.
+ */
+export function LoadAgentManagerCore() {
+    // Forces module to load and decorators to execute
+    // Classes are already exported and decorators run on import
+}
+
+// Auto-load on import to ensure decorators execute
+LoadAgentManagerCore();

package/src/{interfaces → old}/agent-definition.interface.ts

@@ -10,6 +10,7 @@
 /**
  * Complete agent definition that supports n-levels of sub-agent hierarchy
  * All text fields support markdown formatting for rich documentation
+ * @deprecated
  */
 export interface AIAgentDefinition {
   // Basic Information

package/tsconfig.json

@@ -12,7 +12,9 @@
     "declaration": true,
     "declarationMap": true,
     "sourceMap": true,
-    "resolveJsonModule": true
+    "resolveJsonModule": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
   },
   "include": [
     "src/**/*"

package/dist/interfaces/agent-definition.interface.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"agent-definition.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/agent-definition.interface.ts"],"names":[],"mappings":"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"}

package/dist/interfaces/agent-definition.interface.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"agent-definition.interface.js","sourceRoot":"","sources":["../../src/interfaces/agent-definition.interface.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG"}