@memberjunction/ai-agents 5.23.0 → 5.24.0

package/dist/base-agent.js

@@ -832,13 +832,36 @@ export class BaseAgent {
         this._activeProvider = params.provider || Metadata.Provider;
         try {
             this.logStatus(`🤖 Starting execution of agent '${params.agent.Name}'`, true, params);
-            // Check permissions - user must have run permission or be the owner
-            const canRun = await AIAgentPermissionHelper.HasPermission(params.agent.ID, params.contextUser, 'run');
-            if (!canRun) {
-                const errorMessage = `User ${params.contextUser.Email} does not have permission to run agent '${params.agent.Name}' (ID: ${params.agent.ID})`;
-                this.logStatus(`🚫 ${errorMessage}`, false, params);
-                throw new Error(errorMessage);
-            }
+            // =====================================================================================
+            // LATENCY OPTIMIZATION (Opt #4): Parallelized initialization sequence.
+            //
+            // The agent initialization pipeline was originally fully sequential: each operation
+            // awaited before the next began, even when there were no data dependencies between
+            // them. This added ~150-200ms of unnecessary serial wait time.
+            //
+            // The restructured pipeline uses 4 phases:
+            //
+            //   PRE-WORK (sync/fast): Parameter wrapping, markup conversion, payload init,
+            //     cancellation check, payload validation (may exit early).
+            //
+            //   PHASE 1 (parallel): Permission check + Engine init + AgentRun creation.
+            //     These three are mutually independent. If permission fails, we mark the
+            //     already-created AgentRun as failed and terminate — the wasted run record
+            //     is a negligible cost vs. the ~150ms saved by not serializing these.
+            //
+            //   PHASE 2 (parallel): Config load + Data preload + Context memory injection.
+            //     All three depend on Phase 1 completing (engines loaded, agentRun exists)
+            //     but NOT on each other. Config load reads from AIEngine's in-memory cache.
+            //     Data preload fetches agent data sources. Context memory loads notes/examples
+            //     and injects them into the conversation messages.
+            //
+            //   PHASE 3 (sequential): Agent type initialization — must wait for config from
+            //     Phase 2 because it needs the resolved agent type and prompt configuration.
+            //
+            // Original total init time: ~sum of all operations (~400-500ms)
+            // Optimized: ~max(Phase1) + max(Phase2) + Phase3 (~200-300ms)
+            // =====================================================================================
+            // --- PRE-WORK: Fast synchronous setup and early-exit checks ---
             // Wrap the progress callback to capture all events
             const wrappedParams = {
                 ...params,
@@ -850,12 +873,20 @@ export class BaseAgent {
             }
             // Reset scratchpad for each new execution (ephemeral per run)
             this._scratchpadManager.Clear();
+            // Initialize starting payload — must complete before AgentRun creation since the
+            // run record stores the starting payload snapshot.
             await this.initializeStartingPayload(wrappedParams);
             // Check for cancellation at start
             if (params.cancellationToken?.aborted) {
                 this.logStatus(`⚠️ Agent '${params.agent.Name}' execution cancelled before start`, true, params);
                 return await this.createCancelledResult('Cancelled before execution started', params.contextUser);
             }
+            // Handle starting payload validation if configured — may return early with a
+            // validation failure result, so we run this before launching expensive parallel work.
+            const startingValidationResult = await this.handleStartingPayloadValidation(wrappedParams);
+            if (startingValidationResult) {
+                return startingValidationResult;
+            }
             // Report initialization progress
             wrappedParams.onProgress?.({
                 step: 'initialization',
@@ -865,31 +896,44 @@ export class BaseAgent {
                     hierarchicalStep: this.buildHierarchicalStep(0, this._parentStepCounts)
                 }
             });
-            // Initialize execution tracking
-            await this.initializeAgentRun(wrappedParams);
-            // Reset validation retry counters for this run
+            // --- PHASE 1: Permission check + Engine init + AgentRun creation (parallel) ---
+            // These three operations have zero data dependencies on each other:
+            // - Permission check queries the AIAgentPermission entity
+            // - Engine init calls AIEngine.Instance.Config() and ActionEngineServer.Instance.Config()
+            // - AgentRun creation inserts a new AIAgentRun record
+            //
+            // If permission check fails, we mark the AgentRun as failed. This is acceptable:
+            // an orphaned "failed" run record is harmless and far cheaper than serializing these
+            // three operations (~150ms savings).
+            const [canRun] = await Promise.all([
+                AIAgentPermissionHelper.HasPermission(params.agent.ID, params.contextUser, 'run'),
+                this.initializeEngines(params.contextUser),
+                this.initializeAgentRun(wrappedParams)
+            ]);
+            if (!canRun) {
+                // Permission denied — mark the already-created AgentRun as failed so it doesn't
+                // appear as a phantom "running" record in the UI.
+                const errorMessage = `User ${params.contextUser.Email} does not have permission to run agent '${params.agent.Name}' (ID: ${params.agent.ID})`;
+                this.logStatus(`🚫 ${errorMessage}`, false, params);
+                if (this._agentRun) {
+                    this._agentRun.Status = 'Failed';
+                    this._agentRun.ErrorMessage = errorMessage;
+                    await this._agentRun.Save();
+                }
+                throw new Error(errorMessage);
+            }
+            // Reset per-run state (sync, instant — no parallelization needed)
             this._validationRetryCount = 0;
             this._generalValidationRetryCount = 0;
             this._contextRecoveryAttempts = 0;
-            // Reset effective actions and dynamic limits for this run
             this._effectiveActions = [];
             this._dynamicActionLimits = {};
-            // Reset media outputs accumulator for this run
-            // (unified array now includes both promoted media and intercepted binary with refIds)
             this._mediaOutputs = [];
-            // Store message lifecycle callback if provided
             this._messageLifecycleCallback = params.onMessageLifecycle;
-            // Initialize engines
-            await this.initializeEngines(params.contextUser);
-            // Check for cancellation after initialization
+            // Check for cancellation after Phase 1
             if (params.cancellationToken?.aborted) {
                 return await this.createCancelledResult('Cancelled during initialization', params.contextUser);
             }
-            // Handle starting payload validation if configured
-            const startingValidationResult = await this.handleStartingPayloadValidation(wrappedParams);
-            if (startingValidationResult) {
-                return startingValidationResult;
-            }
             // Report validation progress
             wrappedParams.onProgress?.({
                 step: 'validation',
@@ -899,34 +943,26 @@ export class BaseAgent {
                     hierarchicalStep: this.buildHierarchicalStep(0, this._parentStepCounts)
                 }
             });
-            // Create and track validation step
+            // Validate agent — may return early with a failure result. Runs after engines are
+            // initialized (Phase 1) since validation may inspect AIEngine metadata.
             const validationResult = await this.validateAgentWithTracking(params.agent, params.contextUser);
             if (validationResult)
                 return validationResult;
-            // Load agent configuration
+            // --- PHASE 2: Config load + Data preload + Context memory injection (parallel) ---
+            // All three depend on Phase 1 completing (engines initialized, agentRun exists) but
+            // have no dependencies on each other:
+            // - Config load reads agent type, prompts, and agent prompts from AIEngine's in-memory
+            //   cache — typically < 5ms but async due to potential Config() refresh.
+            // - Data preload fetches agent data sources and creates a tracking step entity.
+            // - Context memory resolves scope configuration (pure computation), then loads notes
+            //   and examples from the DB and injects them into conversation messages.
             this.logStatus(`📋 Loading configuration for agent '${params.agent.Name}'`, true, params);
-            const config = await this.loadAgentConfiguration(params.agent);
-            if (!config.success) {
-                this.logError(`Failed to load agent configuration: ${config.errorMessage}`, {
-                    agent: params.agent,
-                    category: 'AgentConfiguration'
-                });
-                return await this.createFailureResult(config.errorMessage || 'Failed to load agent configuration', params.contextUser);
-            }
-            // Preload agent data sources unless disabled
-            await this.preloadAgentData(wrappedParams);
-            // now initialize the agent type which gets us the instance setup in our class plus also gets the agent type to initialize
-            // its state
-            await this.initializeAgentType(wrappedParams, config);
-            // Inject context memory (notes and examples) before execution
+            // Pre-compute scope configuration for context memory injection (pure computation,
+            // no I/O — safe to do before launching the parallel phase).
             const userId = params.userId || params.contextUser?.ID;
             const companyId = params.companyId;
-            // Extract input text from conversation messages (last user message)
-            const lastUserMessage = params.conversationMessages
-                .filter(m => m.role === 'user')
-                .pop();
+            const lastUserMessage = params.conversationMessages.filter(m => m.role === 'user').pop();
             const inputText = lastUserMessage?.content || '';
-            // Parse agent-level scope config for note/example filtering
             const scopeConfigJson = params.agent.ScopeConfig;
             let scopeConfig = null;
             if (scopeConfigJson) {
@@ -935,11 +971,9 @@ export class BaseAgent {
                 }
                 catch { /* ignore bad JSON */ }
             }
-            // Resolve scope params from top-level params or data fallback (for GraphQL callers)
             const primaryScopeEntityName = params.PrimaryScopeEntityName ?? params.data?.PrimaryScopeEntityName;
             const primaryScopeRecordId = params.PrimaryScopeRecordID ?? params.data?.PrimaryScopeRecordID;
             const secondaryScopes = params.SecondaryScopes ?? params.data?.SecondaryScopes;
-            // Resolve entity name to entity ID for scope filtering
             let primaryScopeEntityId;
             if (primaryScopeEntityName) {
                 const primaryEntity = this._metadata.Entities.find(e => e.Name === primaryScopeEntityName);
@@ -947,8 +981,22 @@ export class BaseAgent {
                     primaryScopeEntityId = primaryEntity.ID;
                 }
             }
-            // Inject context memory (notes and examples) into conversation messages
-            await this.InjectContextMemory(typeof inputText === 'string' ? inputText : '', params.agent, userId, companyId, params.contextUser, wrappedParams.conversationMessages, primaryScopeEntityId, primaryScopeRecordId, secondaryScopes, scopeConfig);
+            const [config] = await Promise.all([
+                this.loadAgentConfiguration(params.agent),
+                this.preloadAgentData(wrappedParams),
+                this.InjectContextMemory(typeof inputText === 'string' ? inputText : '', params.agent, userId, companyId, params.contextUser, wrappedParams.conversationMessages, primaryScopeEntityId, primaryScopeRecordId, secondaryScopes, scopeConfig)
+            ]);
+            if (!config.success) {
+                this.logError(`Failed to load agent configuration: ${config.errorMessage}`, {
+                    agent: params.agent,
+                    category: 'AgentConfiguration'
+                });
+                return await this.createFailureResult(config.errorMessage || 'Failed to load agent configuration', params.contextUser);
+            }
+            // --- PHASE 3: Agent type initialization (sequential) ---
+            // Must wait for config from Phase 2 because it needs the resolved agent type and
+            // prompt configuration to initialize the type-specific state machine.
+            await this.initializeAgentType(wrappedParams, config);
             // Execute the agent's internal logic with wrapped parameters
             this.logStatus(`🚀 Executing agent '${params.agent.Name}' internal logic`, true, params);
             const executionResult = await this.executeAgentInternal(wrappedParams, config);
@@ -3618,6 +3666,18 @@ The context is now within limits. Please retry your request with the recovered c
             lines.push('');
             lines.push(`**User:** ${user.Name}${user.Roles?.length ? ` (Roles: ${user.Roles.join(', ')})` : ''}`);
         }
+        // Additional context reported by the active view/component
+        const dashboardCtx = ctx['AdditionalContext'];
+        if (dashboardCtx && Object.keys(dashboardCtx).length > 0) {
+            lines.push('');
+            lines.push('**Dashboard state:**');
+            for (const [key, value] of Object.entries(dashboardCtx)) {
+                if (value === null || value === undefined)
+                    continue;
+                const displayValue = typeof value === 'object' ? JSON.stringify(value) : String(value);
+                lines.push(`- ${key}: ${displayValue}`);
+            }
+        }
         return lines.join('\n');
     }
     /**