@memberjunction/ai-agents 5.10.1 → 5.12.0

package/dist/base-agent.js

@@ -19,7 +19,7 @@ import { ActionEngineServer } from '@memberjunction/actions';
 import { AIAgentPermissionHelper } from '@memberjunction/ai-engine-base';
 import { AgentContextInjector } from './agent-context-injector.js';
 import { RerankerService } from '@memberjunction/ai-reranker';
-import { AIPromptParams, ChildPromptParam, ConversationUtility } from '@memberjunction/ai-core-plus';
+import { AIPromptParams, ChildPromptParam, ConversationUtility, parseAssignmentStrategy } from '@memberjunction/ai-core-plus';
 import { AgentRunner } from './AgentRunner.js';
 import { PayloadManager } from './PayloadManager.js';
 import { AgentDataPreloader } from './AgentDataPreloader.js';
@@ -104,6 +104,13 @@ export class BaseAgent {
          * @private
          */
         this._agentRun = null;
+        /**
+         * Stores the ID of an AIAgentRequest created when a Chat step fires.
+         * Populated by executeChatStep(), returned in ExecuteAgentResult.feedbackRequestId.
+         * Only set for root agents (depth 0), not sub-agents.
+         * @private
+         */
+        this._feedbackRequestId = null;
         /**
          * Agent hierarchy for display purposes (e.g., ["Marketing Agent", "Copywriter Agent"]).
          * Tracked separately as it's display-only and doesn't need persistence.
@@ -192,6 +199,22 @@ export class BaseAgent {
          * Storage for injected notes and examples to include in result
          */
         this._injectedMemory = { notes: [], examples: [] };
+        /**
+         * Walks up the agent's category hierarchy looking for an AssignmentStrategy.
+         * Loads categories via RunView and caches them for the duration of this run.
+         * @private
+         */
+        this._categoryCache = null;
+        /**
+         * Determines the request type ID based on the Chat step's context.
+         * - If the responseForm has only approve/reject-style buttons, uses "Approval"
+         * - If there's a responseForm with fields, uses "Information"
+         * - Otherwise defaults to "Information"
+         *
+         * Caches the request type lookup for the duration of this agent execution.
+         * @private
+         */
+        this._requestTypeCache = null;
     }
     /**
      * Maximum allowed validation retries before forcing failure.
@@ -4402,6 +4425,13 @@ The context is now within limits. Please retry your request with the recovered c
             await this.finalizeStepEntity(stepEntity, promptResult.success, promptResult.success ? undefined : promptResult.errorMessage, outputData);
             // Return based on next step
             if (updatedNextStep.step === 'Chat') {
+                // For root agents, create a persistent AIAgentRequest so the request is
+                // tracked in the dashboard and can be responded to outside a conversation.
+                // This is done here because Chat decisions from executePromptStep terminate
+                // immediately and never reach executeChatStep in the main loop.
+                if (this._depth === 0) {
+                    await this.createFeedbackRequest(params, stepEntity, updatedNextStep);
+                }
                 return { ...updatedNextStep, terminate: true };
             }
             else if (updatedNextStep.step === 'Success' || updatedNextStep.step === 'Failed') {
@@ -5505,6 +5535,20 @@ The context is now within limits. Please retry your request with the recovered c
                     content: resultsMessage,
                     metadata: metadata
                 });
+                // Surface substantive action result messages as a separate instruction message.
+                // When action messages contain multi-line directives (e.g., "YOUR NEXT ACTION — pick one"),
+                // they get buried inside the JSON results structure above. LLMs treat JSON-wrapped text as
+                // data to acknowledge, not instructions to follow. By re-surfacing these messages as a
+                // standalone user message, the LLM reads them as explicit instructions.
+                const substantiveMessages = actionSummaries
+                    .filter(a => a.success && a.message && a.message.includes('\n'))
+                    .map(a => a.message);
+                if (substantiveMessages.length > 0) {
+                    params.conversationMessages.push({
+                        role: 'user',
+                        content: `IMPORTANT — Follow these instructions from the action results:\n\n${substantiveMessages.join('\n\n')}`
+                    });
+                }
             }
             // Call agent type's post-processing for actions
             let finalPayload = currentPayload;
@@ -5567,12 +5611,22 @@ The context is now within limits. Please retry your request with the recovered c
      * Executes a chat step - these should bubble up to the user for interaction.
      * Chat steps are terminal and indicate the agent needs user input.
      *
+     * For root agents (depth 0), this also creates a persistent AIAgentRequest row
+     * so the request is tracked even when the agent isn't running in a conversation.
+     * The feedbackRequestId is returned in ExecuteAgentResult for callers to use
+     * (e.g., sending notifications, syncing conversation responses).
+     *
      * @private
      */
     async executeChatStep(params, previousDecision) {
         const stepEntity = await this.createStepEntity({ stepType: 'Chat', stepName: 'User Interaction', contextUser: params.contextUser });
         // Chat steps are successful - they indicate a need for user interaction
         await this.finalizeStepEntity(stepEntity, true);
+        // For root agents, create a persistent AIAgentRequest so the request is
+        // tracked in the dashboard and can be responded to outside a conversation.
+        if (this._depth === 0) {
+            await this.createFeedbackRequest(params, stepEntity, previousDecision);
+        }
         return {
             step: 'Chat',
             terminate: true,
@@ -5587,6 +5641,214 @@ The context is now within limits. Please retry your request with the recovered c
             automaticCommands: previousDecision.automaticCommands
         };
     }
+    /**
+     * Creates a persistent AIAgentRequest row when a Chat step fires.
+     * Resolves the target user via the assignment chain:
+     *   1. contextUser (explicit caller)
+     *   2. AgentRun.UserID (run initiator)
+     *   3. Conversation.UserID (conversation fallback)
+     *   4. Agent.OwnerUserID (agent owner)
+     *   5. null (system-level, visible to admins)
+     *
+     * @private
+     */
+    async createFeedbackRequest(params, stepEntity, previousDecision) {
+        try {
+            const requestTypeId = await this.resolveRequestTypeId(previousDecision, params.contextUser);
+            const resolvedStrategy = await this.resolveAssignmentStrategy(params, requestTypeId);
+            const requestForUserId = this.resolveUserFromStrategy(resolvedStrategy, params);
+            const priority = resolvedStrategy?.priority ?? 50;
+            const expirationMinutes = resolvedStrategy?.expirationMinutes;
+            const request = await this._metadata.GetEntityObject('MJ: AI Agent Requests', params.contextUser);
+            request.NewRecord();
+            request.AgentID = params.agent.ID;
+            request.RequestedAt = new Date();
+            request.RequestForUserID = requestForUserId;
+            request.Status = 'Requested';
+            request.Request = previousDecision.message || 'Agent needs user input';
+            request.RequestTypeID = requestTypeId;
+            request.ResponseSchema = previousDecision.responseForm
+                ? JSON.stringify(previousDecision.responseForm)
+                : null;
+            request.Priority = priority;
+            request.OriginatingAgentRunID = this._agentRun?.ID || null;
+            request.OriginatingAgentRunStepID = stepEntity.ID;
+            if (expirationMinutes != null && expirationMinutes > 0) {
+                request.ExpiresAt = new Date(Date.now() + expirationMinutes * 60_000);
+            }
+            const saved = await request.Save();
+            if (saved) {
+                this._feedbackRequestId = request.ID;
+                this.logStatus(`📋 Created feedback request ${request.ID} for user ${requestForUserId || '(system)'}`, true, params);
+            }
+            else {
+                LogError(`Failed to save AIAgentRequest for agent ${params.agent.Name}`);
+            }
+        }
+        catch (error) {
+            // Don't let request creation failure break the agent execution
+            LogError(`Error creating feedback request: ${error.message}`);
+        }
+    }
+    /**
+     * Walks the assignment strategy resolution chain (bottom-up, first-non-null wins):
+     * 1. ExecuteAgentParams.assignmentStrategy (per-invocation)
+     * 2. Agent Type's AssignmentStrategy
+     * 3. Agent's Category AssignmentStrategy (walks up ParentID tree)
+     * 4. Request Type's DefaultAssignmentStrategy
+     * 5. Fallback: null (caller uses contextUser + warning)
+     * @private
+     */
+    async resolveAssignmentStrategy(params, requestTypeId) {
+        // 1. Per-invocation override (highest precedence)
+        if (params.assignmentStrategy) {
+            return params.assignmentStrategy;
+        }
+        // 2. Agent Type's AssignmentStrategy
+        const agentType = AIEngine.Instance.AgentTypes.find(at => UUIDsEqual(at.ID, params.agent.TypeID));
+        const typeStrategy = parseAssignmentStrategy(agentType?.AssignmentStrategy ?? null);
+        if (typeStrategy) {
+            return typeStrategy;
+        }
+        // 3. Agent's Category AssignmentStrategy (walk up ParentID tree)
+        const categoryStrategy = await this.resolveCategoryAssignmentStrategy(params);
+        if (categoryStrategy) {
+            return categoryStrategy;
+        }
+        // 4. Request Type's DefaultAssignmentStrategy
+        if (requestTypeId && this._requestTypeCache) {
+            const requestType = this._requestTypeCache.find(t => UUIDsEqual(t.ID, requestTypeId));
+            if (requestType) {
+                const rtStrategy = parseAssignmentStrategy(requestType.DefaultAssignmentStrategy);
+                if (rtStrategy) {
+                    return rtStrategy;
+                }
+            }
+        }
+        return null;
+    }
+    async resolveCategoryAssignmentStrategy(params) {
+        const categoryId = params.agent.CategoryID;
+        if (!categoryId)
+            return null;
+        try {
+            // Load all categories if not cached
+            if (!this._categoryCache) {
+                const rv = new RunView();
+                const result = await rv.RunView({
+                    EntityName: 'MJ: AI Agent Categories',
+                    Fields: ['ID', 'ParentID', 'AssignmentStrategy'],
+                    ResultType: 'simple'
+                }, params.contextUser);
+                this._categoryCache = result.Success ? result.Results : [];
+            }
+            // Walk up the tree from the agent's category to the root
+            let currentId = categoryId;
+            const visited = new Set(); // prevent infinite loops
+            while (currentId && !visited.has(currentId)) {
+                visited.add(currentId);
+                const cat = this._categoryCache.find(c => UUIDsEqual(c.ID, currentId));
+                if (!cat)
+                    break;
+                const strategy = parseAssignmentStrategy(cat.AssignmentStrategy);
+                if (strategy)
+                    return strategy;
+                currentId = cat.ParentID;
+            }
+        }
+        catch (error) {
+            LogError(`Error resolving category assignment strategy: ${error.message}`);
+        }
+        return null;
+    }
+    /**
+     * Resolves the target user ID from a resolved assignment strategy.
+     * For simple strategies (RunUser, AgentOwner, SpecificUser), resolves immediately.
+     * For List/SharedInbox strategies, delegates to list-based resolution.
+     * Falls back to contextUser with a warning if no strategy is provided.
+     * @private
+     */
+    resolveUserFromStrategy(strategy, params) {
+        if (!strategy) {
+            // No strategy resolved anywhere — fall back to contextUser + warning
+            if (params.contextUser?.ID) {
+                LogStatus(`⚠️ No assignment strategy configured for agent ${params.agent.Name}; defaulting to context user`);
+                return params.contextUser.ID;
+            }
+            LogStatus(`⚠️ No assignment strategy and no context user for agent ${params.agent.Name}; request will be unassigned`);
+            return null;
+        }
+        switch (strategy.type) {
+            case 'RunUser':
+                return params.contextUser?.ID
+                    ?? this._agentRun?.UserID
+                    ?? null;
+            case 'AgentOwner':
+                return params.agent.OwnerUserID ?? null;
+            case 'SpecificUser':
+                return strategy.userID ?? null;
+            case 'List':
+                // List-based resolution (RoundRobin, LeastBusy, Random) requires async DB lookups.
+                // For now, fall back to contextUser. Full list resolution is a future enhancement
+                // that will query ListDetail records and track assignment state.
+                LogStatus(`ℹ️ List-based assignment strategy configured but not yet implemented; defaulting to context user`);
+                return params.contextUser?.ID ?? null;
+            case 'SharedInbox':
+                // SharedInbox means "unassigned — anyone in the list can claim it"
+                return null;
+            default:
+                return params.contextUser?.ID ?? null;
+        }
+    }
+    async resolveRequestTypeId(previousDecision, contextUser) {
+        try {
+            // Load request types if not cached
+            if (!this._requestTypeCache) {
+                const rv = new RunView();
+                const result = await rv.RunView({
+                    EntityName: 'MJ: AI Agent Request Types',
+                    ResultType: 'entity_object'
+                }, contextUser);
+                this._requestTypeCache = result.Success ? result.Results : [];
+            }
+            // Determine type name based on responseForm content
+            let typeName = 'Information'; // default
+            if (previousDecision.responseForm) {
+                typeName = this.detectRequestTypeName(previousDecision.responseForm);
+            }
+            const matchedType = this._requestTypeCache.find(t => t.Name === typeName);
+            return matchedType?.ID || null;
+        }
+        catch (error) {
+            LogError(`Error resolving request type: ${error.message}`);
+            return null;
+        }
+    }
+    /**
+     * Inspects an AgentResponseForm to determine the best request type name.
+     * Returns "Approval" if the form is a simple two-option approve/reject pattern,
+     * otherwise returns "Information".
+     * @private
+     */
+    detectRequestTypeName(form) {
+        const q = form.questions?.[0];
+        if (!q || form.questions.length !== 1) {
+            return 'Information';
+        }
+        const qType = q.type;
+        if ((qType.type === 'buttongroup' || qType.type === 'radio') && 'options' in qType) {
+            const opts = qType.options;
+            if (opts.length === 2) {
+                const labels = opts.map(o => o.label.toLowerCase());
+                const hasPositive = labels.some(l => l.includes('approv') || l.includes('yes') || l.includes('accept'));
+                const hasNegative = labels.some(l => l.includes('reject') || l.includes('no') || l.includes('deny'));
+                if (hasPositive && hasNegative) {
+                    return 'Approval';
+                }
+            }
+        }
+        return 'Information';
+    }
     /**
      * Executes a ForEach loop with actual for loop
      * @private
@@ -6178,6 +6440,10 @@ The context is now within limits. Please retry your request with the recovered c
                 // set status to Failed
                 this._agentRun.Status = 'Failed';
             }
+            else if (finalStep.step === 'Chat') {
+                // Chat steps mean the agent is waiting for human input
+                this._agentRun.Status = 'AwaitingFeedback';
+            }
             else {
                 this._agentRun.Status = 'Completed';
             }
@@ -6216,7 +6482,8 @@ The context is now within limits. Please retry your request with the recovered c
             memoryContext: this._injectedMemory.notes.length > 0 || this._injectedMemory.examples.length > 0
                 ? this._injectedMemory
                 : undefined,
-            mediaOutputs: this._mediaOutputs.length > 0 ? this._mediaOutputs : undefined
+            mediaOutputs: this._mediaOutputs.length > 0 ? this._mediaOutputs : undefined,
+            feedbackRequestId: this._feedbackRequestId || undefined
         };
     }
     /**