@memberjunction/ai-agents 5.34.1 → 5.35.0

package/dist/base-agent.js

@@ -991,8 +991,12 @@ export class BaseAgent {
             // Reset scratchpad and artifact tools for each new execution (ephemeral per run)
             this._scratchpadManager.Clear();
             this._artifactToolManager.Clear();
-            // Initialize artifact tools with any input artifacts from the conversation
-            const inputArtifacts = wrappedParams.data?.__inputArtifacts;
+            // Initialize artifact tools with any input artifacts attached to the run.
+            // Artifacts arrive as a typed first-class field on ExecuteAgentParams —
+            // they are NOT routed through `data` because prompt-template rendering
+            // would otherwise serialize artifact bodies into the LLM payload. Only
+            // the manifest (injected via _ARTIFACT_MANIFEST below) reaches the LLM.
+            const inputArtifacts = wrappedParams.inputArtifacts;
             if (inputArtifacts?.length) {
                 this._artifactToolManager.Initialize(inputArtifacts);
                 this.logStatus(`[ArtifactTools] Initialized with ${inputArtifacts.length} artifact(s): ${inputArtifacts.map(a => `${a.typeName}:"${a.name}"`).join(', ')}`, true, params);
@@ -1802,12 +1806,15 @@ export class BaseAgent {
                 promptParams.data['_SCRATCHPAD_TASKS'] = this._scratchpadManager.ToPromptString();
                 promptParams.data['_SCRATCHPAD_TASK_SUMMARY'] = this._scratchpadManager.GetTaskSummary();
             }
-            // Inject artifact tools template variables if enabled and artifacts are present
+            // Inject artifact tools template variables if enabled and artifacts are present.
+            // Note: prior tool results are NO LONGER injected via a per-turn template var.
+            // They are pushed into conversationMessages as a one-shot 'tool-result'
+            // message at execution time (see injectArtifactToolResultsMessage) and decay
+            // via pruneAndCompactExpiredMessages — same lifecycle as action results.
             const artifactToolsEnabled = agentTypePromptParams?.includeArtifactToolsDocs !== false;
             if (artifactToolsEnabled && this._artifactToolManager.HasArtifacts()) {
                 promptParams.data['_ARTIFACT_MANIFEST'] = this._artifactToolManager.ToManifestString();
                 promptParams.data['_ARTIFACT_TOOLS'] = this._artifactToolManager.GetToolDocumentation();
-                promptParams.data['_ARTIFACT_TOOL_RESULTS'] = this._artifactToolManager.GetPendingResults();
                 promptParams.data['_ARTIFACT_TOOL_SUMMARY'] = this._artifactToolManager.GetSummary();
                 this.logStatus(`[ArtifactTools] Injected manifest into prompt: ${this._artifactToolManager.GetSummary()}`, true, params);
             }
@@ -2875,7 +2882,7 @@ export class BaseAgent {
         return payload ? JSON.stringify(payload) : null;
     }
     /**
-     * Recovery Strategy 1: Remove oldest action-result messages.
+     * Recovery Strategy 1: Remove oldest tool-result messages.
      * Targets messages older than minAge turns for removal.
      *
      * @param params - Agent execution parameters
@@ -2885,10 +2892,10 @@ export class BaseAgent {
      * @returns Result with tokens saved and strategy description
      * @protected
      */
-    recoveryStrategy_RemoveOldestActionResults(params, tokensToSave, currentStepCount, minAge = 5) {
+    recoveryStrategy_RemoveOldestToolResults(params, tokensToSave, currentStepCount, minAge = 5) {
         let tokensSaved = 0;
         const removedIndices = [];
-        // Find action-result messages older than minAge turns
+        // Find tool-result messages older than minAge turns
         const candidates = params.conversationMessages
             .map((msg, index) => ({
             message: msg,
@@ -2907,7 +2914,7 @@ export class BaseAgent {
                 break;
             removedIndices.push(candidate.index);
             tokensSaved += candidate.tokens;
-            this.logStatus(`Removing action-result from ${candidate.age} turns ago (${candidate.tokens} tokens)`, true, params);
+            this.logStatus(`Removing tool-result from ${candidate.age} turns ago (${candidate.tokens} tokens)`, true, params);
         }
         // Remove in reverse order to maintain indices
         removedIndices.sort((a, b) => b - a).forEach(index => {
@@ -2918,17 +2925,17 @@ export class BaseAgent {
                 turn: currentStepCount,
                 messageIndex: index,
                 message: removed,
-                reason: 'Context recovery - oldest action results',
+                reason: 'Context recovery - oldest tool results',
                 tokensSaved: this.estimateTokens(removed.content)
             });
         });
         return {
             tokensSaved,
-            strategyName: `Removed ${removedIndices.length} old action-results (${minAge}+ turns)`
+            strategyName: `Removed ${removedIndices.length} old tool-results (${minAge}+ turns)`
         };
     }
     /**
-     * Recovery Strategy 2: Compact old action-result messages.
+     * Recovery Strategy 2: Compact old tool-result messages.
      * Uses smart trimming to reduce size while preserving some content.
      *
      * @param params - Agent execution parameters
@@ -2938,10 +2945,10 @@ export class BaseAgent {
      * @returns Result with tokens saved and strategy description
      * @protected
      */
-    async recoveryStrategy_CompactOldActionResults(params, tokensToSave, currentStepCount, minAge = 3) {
+    async recoveryStrategy_CompactOldToolResults(params, tokensToSave, currentStepCount, minAge = 3) {
         let tokensSaved = 0;
         let compactedCount = 0;
-        // Find action-result messages to compact
+        // Find tool-result messages to compact
         const candidates = params.conversationMessages
             .map((msg, index) => ({
             message: msg,
@@ -2986,16 +2993,16 @@ export class BaseAgent {
                 };
                 tokensSaved += saved;
                 compactedCount++;
-                this.logStatus(`Compacted action-result from ${candidate.age} turns ago (saved ${saved} tokens)`, true, params);
+                this.logStatus(`Compacted tool-result from ${candidate.age} turns ago (saved ${saved} tokens)`, true, params);
             }
         }
         return {
             tokensSaved,
-            strategyName: `Compacted ${compactedCount} old action-results (${minAge}+ turns)`
+            strategyName: `Compacted ${compactedCount} old tool-results (${minAge}+ turns)`
         };
     }
     /**
-     * Recovery Strategy 3: Aggressively compact ALL action-result messages.
+     * Recovery Strategy 3: Aggressively compact ALL tool-result messages.
      * Used when gentler strategies haven't freed enough space.
      *
      * @param params - Agent execution parameters
@@ -3003,10 +3010,10 @@ export class BaseAgent {
      * @returns Result with tokens saved and strategy description
      * @protected
      */
-    async recoveryStrategy_CompactAllActionResults(params, tokensToSave) {
+    async recoveryStrategy_CompactAllToolResults(params, tokensToSave) {
         let tokensSaved = 0;
         let compactedCount = 0;
-        // Find ALL action-result messages that aren't already compacted
+        // Find ALL tool-result messages that aren't already compacted
         const candidates = params.conversationMessages
             .map((msg, index) => ({
             message: msg,
@@ -3052,7 +3059,7 @@ export class BaseAgent {
         }
         return {
             tokensSaved,
-            strategyName: `Aggressively compacted ${compactedCount} action-results`
+            strategyName: `Aggressively compacted ${compactedCount} tool-results`
         };
     }
     /**
@@ -3111,7 +3118,7 @@ export class BaseAgent {
     /**
      * Attempts to recover from a context length exceeded error using multiple strategies.
      * Uses escalating strategies: remove old results → compact old results → compact all → trim user message.
-     * This approach preserves the user's original request while removing stale action results.
+     * This approach preserves the user's original request while removing stale tool results.
      *
      * @param params - Agent execution parameters (conversationMessages will be modified)
      * @param payload - Current payload to carry forward
@@ -3143,10 +3150,10 @@ export class BaseAgent {
         const currentPromptTurn = this._promptTurnCount;
         // Try multiple recovery strategies in order
         const strategies = [
-            () => this.recoveryStrategy_RemoveOldestActionResults(params, tokensToSave, currentPromptTurn, 5),
-            () => this.recoveryStrategy_CompactOldActionResults(params, tokensToSave, currentPromptTurn, 3),
-            () => this.recoveryStrategy_RemoveOldestActionResults(params, tokensToSave, currentPromptTurn, 2),
-            () => this.recoveryStrategy_CompactAllActionResults(params, tokensToSave),
+            () => this.recoveryStrategy_RemoveOldestToolResults(params, tokensToSave, currentPromptTurn, 5),
+            () => this.recoveryStrategy_CompactOldToolResults(params, tokensToSave, currentPromptTurn, 3),
+            () => this.recoveryStrategy_RemoveOldestToolResults(params, tokensToSave, currentPromptTurn, 2),
+            () => this.recoveryStrategy_CompactAllToolResults(params, tokensToSave),
             () => Promise.resolve(this.recoveryStrategy_TrimLastUserMessage(params, tokensToSave))
         ];
         let tokensSaved = 0;
@@ -3215,30 +3222,88 @@ The context is now within limits. Please retry your request with the recovered c
         return guardrailCheckedStep;
     }
     /**
-     * Creates a chat message containing action execution results.
+     * Executes a batch of artifact tool calls, recording each as its own
+     * `Tool` AIAgentRunStep (a sibling of the Prompt step that requested them)
+     * with full inputs/outputs captured in InputData/OutputData. Returns the
+     * stored results so the caller can render them into a single recall-friendly
+     * message for the next prompt turn.
+     *
+     * Step naming convention: `Artifact Tool: {toolName}` for log/UI clarity.
      *
-     * @param {AgentAction[]} actions - The actions that were executed
-     * @param {any[]} results - The results from action execution
-     * @returns {ChatMessage} A formatted message with action results
      * @protected
      */
-    createActionResultMessage(actions, results) {
-        const actionSummaries = actions.map((action, index) => {
-            const result = results[index];
-            const outputParams = result.Params?.filter(p => p.Type === 'Output' || p.Type === 'Both') || [];
-            return {
-                actionName: action.name,
-                success: result.Success,
-                params: outputParams,
-                resultCode: result.Result?.ResultCode || 'N/A',
-                message: result.Message || '(no message)',
-                aiDirectives: result.AIDirectives,
-            };
-        });
-        return {
+    async executeArtifactToolCallsAsSteps(calls, params) {
+        // No parentId: artifact tool steps are siblings of the prompt step that
+        // requested them, matching how action steps render. ParentID is reserved
+        // for genuine control-flow nesting (ForEach/While loops, sub-agents), which
+        // artifact tools are never dispatched from.
+        const results = await Promise.all(calls.map(async (call) => {
+            const toolStep = await this.createStepEntity({
+                stepType: 'Tool',
+                stepName: `Artifact Tool: ${call.tool}`,
+                contextUser: params.contextUser,
+                inputData: {
+                    artifactId: call.artifactId,
+                    tool: call.tool,
+                    input: call.input,
+                },
+            });
+            const stored = await this._artifactToolManager.ExecuteSingleToolCall(call);
+            await this.finalizeStepEntity(toolStep, stored.result.success, stored.result.success ? undefined : stored.result.errorMessage, {
+                artifactId: stored.artifactId,
+                tool: stored.tool,
+                input: stored.input,
+                result: stored.result,
+                durationMs: stored.durationMs,
+            });
+            return stored;
+        }));
+        return results;
+    }
+    /**
+     * Pushes a single user-role message containing rendered artifact-tool
+     * results into the conversation. This mirrors the action-result
+     * "inject once, then expire" pattern — the LLM sees the results on its
+     * next turn, and older messages are pruned/compacted by
+     * `pruneAndCompactExpiredMessages` instead of being re-rendered into
+     * every system-prompt turn.
+     *
+     * @protected
+     */
+    injectArtifactToolResultsMessage(params, toolResults) {
+        if (toolResults.length === 0)
+            return;
+        const header = toolResults.length === 1
+            ? 'Artifact tool result:'
+            : `Artifact tool results (${toolResults.length} calls):`;
+        const body = toolResults.map((r, i) => {
+            const heading = `### ${i + 1}. ${r.artifactId}.${r.tool}(${JSON.stringify(r.input)})`;
+            if (r.result.success) {
+                const data = typeof r.result.data === 'string'
+                    ? r.result.data
+                    : JSON.stringify(r.result.data, null, 2);
+                return `${heading}\n\`\`\`json\n${data}\n\`\`\``;
+            }
+            return `${heading}\n**Error:** ${r.result.errorMessage}`;
+        }).join('\n\n');
+        const message = {
             role: 'user',
-            content: `Action results:\n${this.formatActionResultsAsMarkdown(actionSummaries)}`
+            content: `${header}\n${body}`,
+            metadata: {
+                turnAdded: this._promptTurnCount,
+                messageType: 'tool-result',
+                // Default: keep results visible for a few turns then compact to a
+                // first-N-chars preview. The LLM is taught (via the loop-agent
+                // system prompt) that older tool results are summarised and that
+                // it can re-call the tool if it needs the full result back.
+                expirationTurns: 3,
+                expirationMode: 'Compact',
+                compactMode: 'First N Chars',
+                compactLength: 500,
+                compactPromptId: '',
+            },
         };
+        params.conversationMessages.push(message);
     }
     /**
      * Creates a chat message containing sub-agent execution results.
@@ -4685,8 +4750,8 @@ The context is now within limits. Please retry your request with the recovered c
                 return await this.processSubAgentStep(params, previousDecision, undefined, undefined, stepCount);
             case 'Actions':
                 return await this.executeActionsStep(params, previousDecision, undefined, true, stepCount);
-            // Type assertion required because 'ClientTools' is not yet in the DB StepType value list.
-            // The LoopAgentType.DetermineNextStep() emits this value when the LLM chooses client tools.
+            // Type assertion required because 'ClientTools' is not part of the BaseAgentNextStep
+            // step union — LoopAgentType.DetermineNextStep() emits it when the LLM chooses client tools.
             case 'ClientTools':
                 return await this.executeClientToolsStep(params, config, previousDecision, stepCount);
             case 'Chat':
@@ -5001,7 +5066,16 @@ The context is now within limits. Please retry your request with the recovered c
             const artifactToolsExecutedThisTurn = !!(artifactToolCalls?.length);
             if (artifactToolsExecutedThisTurn) {
                 this.logStatus(`[ArtifactTools] LLM requested ${artifactToolCalls.length} tool call(s): ${artifactToolCalls.map(c => `${c.artifactId}.${c.tool}`).join(', ')}`, true, params);
-                await this._artifactToolManager.ExecuteToolCalls(artifactToolCalls);
+                // Per-call observability: wrap each invocation in its own AIAgentRunStep
+                // (StepType='Tool') so the run tree shows the calls + their inputs/outputs
+                // at full fidelity instead of a summary buried inside the parent Prompt
+                // step's OutputData. Step naming convention is "Artifact Tool: {tool}".
+                // The result is also surfaced to the agent on the NEXT turn via a
+                // one-shot ChatMessage push (see injectArtifactToolResultsMessage below),
+                // mirroring the action-result inject-once-then-expire pattern instead of
+                // the previous re-render-every-turn `_ARTIFACT_TOOL_RESULTS` template var.
+                const toolResults = await this.executeArtifactToolCallsAsSteps(artifactToolCalls, params);
+                this.injectArtifactToolResultsMessage(params, toolResults);
             }
             else if (this._artifactToolManager.HasArtifacts()) {
                 this.logStatus(`[ArtifactTools] LLM did not use artifact tools this turn (artifacts available but not accessed)`, true, params);
@@ -6362,12 +6436,7 @@ The context is now within limits. Please retry your request with the recovered c
         // Execute tools sequentially (client may not support parallel UI operations)
         for (const tool of clientTools) {
             const stepEntity = await this.createStepEntity({
-                // INTENTIONAL: We use 'Actions' as the DB step type because the MJ: AI Agent Run Steps
-                // entity's StepType value list does not yet include 'ClientTools'. A future database
-                // migration will add 'ClientTools' to the allowed values in the StepType CHECK constraint
-                // and CodeGen will regenerate the types. Until then, client tool steps are recorded under
-                // 'Actions' in the run history. The step name ("Client Tool: {name}") distinguishes them.
-                stepType: 'Actions',
+                stepType: 'Tool',
                 stepName: `Client Tool: ${tool.Name}`,
                 inputData: { toolName: tool.Name, params: tool.Params },
                 contextUser: params.contextUser,
@@ -7860,7 +7929,9 @@ The context is now within limits. Please retry your request with the recovered c
      */
     IsToolResultMessage(msg) {
         const messageType = msg.metadata?.messageType;
-        return messageType === 'action-result' || messageType === 'client-tool-result';
+        return messageType === 'action-result'
+            || messageType === 'client-tool-result'
+            || messageType === 'tool-result';
     }
     estimateTokens(content, modelName) {
         const text = typeof content === 'string'