@memberjunction/ai-agents 5.28.0 → 5.30.0

package/dist/base-agent.js

@@ -24,6 +24,7 @@ import { AIPromptParams, ChildPromptParam, ConversationUtility, ParseFileOutputR
 import { AgentRunner } from './AgentRunner.js';
 import { PayloadManager } from './PayloadManager.js';
 import { ScratchpadManager } from './ScratchpadManager.js';
+import { ArtifactToolManager } from './ArtifactToolManager.js';
 import { AgentDataPreloader } from './AgentDataPreloader.js';
 import { ClientToolRequestManager } from './ClientToolRequestManager.js';
 import { ConversationMessageResolver } from './utils/ConversationMessageResolver.js';
@@ -184,6 +185,11 @@ export class BaseAgent {
          * @since 2.46.0
          */
         this._scratchpadManager = new ScratchpadManager();
+        /**
+         * Manages artifact tools for the current agent run.
+         * Allows agents to explore input artifacts on demand.
+         */
+        this._artifactToolManager = new ArtifactToolManager();
         /**
          * Effective actions available to this agent after applying actionChanges.
          * Populated during gatherPromptTemplateData() and used for validation in executeActionsStep().
@@ -863,10 +869,59 @@ export class BaseAgent {
      * });
      * ```
      */
+    /**
+     * Engine-default wall-clock timeout applied to any agent run whose
+     * `ExecuteAgentParams.maxExecutionTimeMs` is not set. Sub-classes can
+     * override to globally change the default. Intentionally generous
+     * (2 hours) — tighten per-run for interactive scenarios.
+     */
+    get DefaultAgentTimeoutMS() {
+        return 2 * 60 * 60 * 1000;
+    }
     async Execute(params) {
         // Capture per-request provider for the duration of this execution so all entity
         // saves go through the isolated provider, never the global singleton's transaction.
         this._activeProvider = params.provider || Metadata.Provider;
+        // =====================================================================================
+        // UNIVERSAL WALL-CLOCK TIMEOUT
+        //
+        // We chain any caller-supplied `cancellationToken` with an internal
+        // AbortController that fires after `maxExecutionTimeMs` (falling back
+        // to `DefaultAgentTimeoutMS`). The chained signal replaces
+        // `params.cancellationToken` for the duration of the run, so every
+        // existing cancellation check in the body of Execute sees the merged
+        // abort condition — whether it came from the caller, the timeout, or
+        // both.
+        //
+        // Actions invoked from this agent carry their own AbortSignal on
+        // `RunActionParams.AbortSignal` (see ActionEngine.RunAction) and are
+        // unaffected by this wrapper — their timeout budget is independent.
+        // =====================================================================================
+        const agentTimeoutMS = params.maxExecutionTimeMs ?? this.DefaultAgentTimeoutMS;
+        const upstreamToken = params.cancellationToken;
+        const timeoutController = new AbortController();
+        const relayUpstreamAbort = () => {
+            if (!timeoutController.signal.aborted) {
+                timeoutController.abort(upstreamToken?.reason ?? 'upstream cancellation');
+            }
+        };
+        if (upstreamToken) {
+            if (upstreamToken.aborted) {
+                relayUpstreamAbort();
+            }
+            else {
+                upstreamToken.addEventListener('abort', relayUpstreamAbort, { once: true });
+            }
+        }
+        const timeoutId = setTimeout(() => {
+            if (!timeoutController.signal.aborted) {
+                timeoutController.abort(`Agent '${params.agent.Name}' exceeded maxExecutionTimeMs (${agentTimeoutMS}ms)`);
+            }
+        }, agentTimeoutMS);
+        // Route the merged signal back through `params` so the existing body of
+        // Execute (and downstream sub-agent invocations that propagate
+        // `cancellationToken`) observe it.
+        params.cancellationToken = timeoutController.signal;
         try {
             this.logStatus(`🤖 Starting execution of agent '${params.agent.Name}'`, true, params);
             // =====================================================================================
@@ -908,8 +963,18 @@ export class BaseAgent {
             if (params.convertUIMarkupToPlainText !== false) {
                 this.convertUIMarkupInMessages(wrappedParams.conversationMessages);
             }
-            // Reset scratchpad for each new execution (ephemeral per run)
+            // 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;
+            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);
+            }
+            else {
+                this.logStatus(`[ArtifactTools] No input artifacts found for this run`, true, params);
+            }
             // Initialize starting payload — must complete before AgentRun creation since the
             // run record stores the starting payload snapshot.
             await this.initializeStartingPayload(wrappedParams);
@@ -1065,8 +1130,11 @@ export class BaseAgent {
         catch (error) {
             // Check if error is due to cancellation
             if (params.cancellationToken?.aborted || error.message === 'Cancelled during execution') {
-                this.logStatus(`⚠️ Agent '${params.agent.Name}' execution cancelled: ${error.message}`, true, params);
-                return await this.createCancelledResult(error.message || 'Cancelled due to error during execution', params.contextUser);
+                const reason = typeof timeoutController.signal.reason === 'string'
+                    ? timeoutController.signal.reason
+                    : error.message;
+                this.logStatus(`⚠️ Agent '${params.agent.Name}' execution cancelled: ${reason}`, true, params);
+                return await this.createCancelledResult(reason || 'Cancelled due to error during execution', params.contextUser);
             }
             this.logError(error, {
                 agent: params.agent,
@@ -1075,6 +1143,18 @@ export class BaseAgent {
             });
             return await this.createFailureResult(error.message, params.contextUser);
         }
+        finally {
+            // Release timeout / upstream-abort listeners so we don't leak
+            // handles when the run completes (success, failure, or cancel).
+            clearTimeout(timeoutId);
+            if (upstreamToken) {
+                upstreamToken.removeEventListener('abort', relayUpstreamAbort);
+            }
+            // Restore the caller's original cancellationToken on `params` so
+            // consumers that re-read `params` after the call see what they
+            // passed in, not our chained signal.
+            params.cancellationToken = upstreamToken;
+        }
     }
     /**
      * Sub-classes can override this method to perform any specialized initialization
@@ -1636,6 +1716,26 @@ 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
+            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);
+            }
+            else if (this._artifactToolManager.HasArtifacts()) {
+                this.logStatus(`[ArtifactTools] Artifacts present but tools disabled by agent config (includeArtifactToolsDocs=false)`, true, params);
+            }
+            // Pass file artifacts as candidate native file inputs.
+            // The AIPromptRunner will check these against the resolved driver's
+            // FileCapabilities and attach qualifying files as native content blocks.
+            // When the driver doesn't support a file type, the runner falls back to
+            // the pre-extracted TextContent on each candidate.
+            if (this._artifactToolManager.HasArtifacts()) {
+                promptParams.nativeFileInputs = await this._artifactToolManager.GetNativeFileInputCandidates();
+            }
         }
         // Only set up child prompts if we have a system prompt
         if (systemPrompt) {
@@ -2403,14 +2503,36 @@ export class BaseAgent {
      * @protected
      */
     isConfigurationError(errorMessage, config) {
+        // Extract the property name from the error up front — used by the
+        // narrowed classifier below to decide whether this is a genuine config
+        // issue or a generic runtime exception that should bubble up normally.
+        const propertyMatch = errorMessage.match(/reading '(\w+)'/i);
+        const accessedProperty = propertyMatch ? propertyMatch[1].toLowerCase() : '';
+        // Only `.map/.x on undefined` errors that reference config-related
+        // properties are treated as configuration errors. Generic runtime
+        // errors (e.g. a tool handler crashing on `rows.map`) should not
+        // terminate the run as "unrecoverable config issue" — they should
+        // fail the step and let the agent try to recover.
+        const CONFIG_RELATED_PROPERTIES = new Set([
+            'prompt', 'childprompt', 'systemprompt', 'prompts',
+            'agent', 'agents', 'agenttype', 'agenttypes',
+            'model', 'models', 'vendor', 'vendors',
+            'template', 'templates',
+        ]);
+        const isConfigRelatedProperty = accessedProperty !== ''
+            && CONFIG_RELATED_PROPERTIES.has(accessedProperty);
         // Check for common configuration error patterns
         const configErrorPatterns = [
             {
-                pattern: /cannot read propert(y|ies) of (undefined|null)/i,
+                // Only match when the accessed property is config-related.
+                // Without this guard, any runtime `.map on undefined` (e.g.
+                // in an artifact tool handler) gets misclassified as a fatal
+                // configuration error and the agent run terminates.
+                pattern: isConfigRelatedProperty
+                    ? /cannot read propert(y|ies) of (undefined|null)/i
+                    : /__NEVER_MATCH_GENERIC_UNDEFINED_ACCESS__/,
                 getMessage: () => {
-                    // Try to extract what property was being accessed
-                    const propertyMatch = errorMessage.match(/reading '(\w+)'/i);
-                    const property = propertyMatch ? propertyMatch[1] : 'unknown property';
+                    const property = accessedProperty || 'unknown property';
                     let details = `Attempted to access property '${property}' on an undefined or null object.`;
                     // Provide specific guidance based on the property name
                     if (property.toLowerCase().includes('prompt')) {
@@ -3223,7 +3345,8 @@ The context is now within limits. Please retry your request with the recovered c
             { docsFlag: 'includeCommandDocs', responseTypeKey: 'commands' },
             { docsFlag: 'includeForEachDocs', responseTypeKey: 'forEach' },
             { docsFlag: 'includeWhileDocs', responseTypeKey: 'while' },
-            { docsFlag: 'includeScratchpadDocs', responseTypeKey: 'scratchpad' }
+            { docsFlag: 'includeScratchpadDocs', responseTypeKey: 'scratchpad' },
+            { docsFlag: 'includeArtifactToolsDocs', responseTypeKey: 'artifactToolCalls' }
         ];
         for (const { docsFlag, responseTypeKey } of alignmentMappings) {
             // Check if the user explicitly set this response type property
@@ -4080,7 +4203,8 @@ The context is now within limits. Please retry your request with the recovered c
         }
         this._agentRun.Status = 'Running';
         this._agentRun.StartedAt = new Date();
-        this._agentRun.UserID = params.contextUser?.ID || null;
+        this._agentRun.UserID = params.userId || params.contextUser?.ID || null;
+        this._agentRun.CompanyID = params.companyId || null;
         // Resolve and save the effort level used (same precedence hierarchy as prompts)
         if (params.effortLevel !== undefined && params.effortLevel !== null) {
             this._agentRun.EffortLevel = params.effortLevel;
@@ -4780,6 +4904,16 @@ The context is now within limits. Please retry your request with the recovered c
                     LogStatus(`Scratchpad: pruned ${pruned} completed tasks (limit: ${maxTasks})`);
                 }
             }
+            // Execute artifact tool calls if provided (zero turn cost — processed inline)
+            const artifactToolCalls = initialNextStep.artifactToolCalls;
+            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);
+            }
+            else if (this._artifactToolManager.HasArtifacts()) {
+                this.logStatus(`[ArtifactTools] LLM did not use artifact tools this turn (artifacts available but not accessed)`, true, params);
+            }
             // now that we have processed the payload, we can process the next step which does validation and changes the next step if
             // validation fails
             const updatedNextStep = await this.processNextStep(initialNextStep, params, config.agentType, promptResult, finalPayload, stepEntity);
@@ -4802,6 +4936,10 @@ The context is now within limits. Please retry your request with the recovered c
                 ...(this._scratchpadManager.HasContent() && {
                     scratchpad: this._scratchpadManager.ToJSON()
                 }),
+                // Include artifact tools snapshot for audit/training data
+                ...(this._artifactToolManager.HasArtifacts() && {
+                    artifactTools: this._artifactToolManager.ToJSON()
+                }),
                 // Include memory attribution for observability
                 // This tracks which notes/examples were injected and influenced this step
                 ...(this._injectedMemory && (this._injectedMemory.notes.length > 0 || this._injectedMemory.examples.length > 0) && {
@@ -4834,6 +4972,14 @@ 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') {
+                // If artifact tools were called THIS turn, don't terminate yet — the LLM
+                // needs one more turn to see the results and incorporate them into its response.
+                // Without this, the tool results are wasted because the run exits before
+                // the LLM ever sees them.
+                if (artifactToolsExecutedThisTurn && this._artifactToolManager.HasArtifacts()) {
+                    this.logStatus(`[ArtifactTools] Chat step included tool calls — forcing one more turn so LLM can use results`, true, params);
+                    return { ...updatedNextStep, terminate: false, step: 'Retry' };
+                }
                 // 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