@memberjunction/ai-agents 5.23.0 → 5.25.0

package/README.md

@@ -332,6 +332,38 @@ New code should import these directly from `@memberjunction/ai-reranker`.
 - `@memberjunction/aiengine` -- AIEngine for metadata and vector search
 - `@memberjunction/ai-core-plus` -- Shared types (ExecuteAgentParams, ExecuteAgentResult)
 - `@memberjunction/ai-engine-base` -- Base metadata cache and permissions
+## Storage Account Resolution
+
+When agents create file-based artifacts (PDF, Excel, Word), the system resolves which `FileStorageAccount` to use via a hierarchical chain. The first non-null value wins:
+
+| Priority | Source | Field |
+|----------|--------|-------|
+| 1 (highest) | Runtime | `ExecuteAgentParams.override.storageAccountId` |
+| 2 | Agent | `AIAgent.DefaultStorageAccountID` |
+| 3 | Category tree | `AIAgentCategory.DefaultStorageAccountID` (walks up `ParentID`) |
+| 4 (lowest) | Agent Type | `AIAgentType.DefaultStorageAccountID` |
+| Fallback | System | Single active account (if only one exists) |
+
+### How it works
+
+- `BaseAgent.getStorageAccountID(params)` implements the resolution logic. It is `protected` so subclasses can override it for custom routing.
+- The resolved ID is stored in `ExecuteAgentResult.resolvedStorageAccountId` and passed to `AgentRunner.ProcessFileArtifacts()` for upload routing.
+- `AgentRunner.uploadBase64ToStorage()` uses `FileStorageEngine.Instance.GetAccountWithProvider()` to get the account + provider, then `initializeDriverWithAccountCredentials()` for proper OAuth credential handling.
+
+### Startup validation
+
+`AIEngine.validateStorageAccountDefaults()` runs at server startup. If 2+ active storage accounts exist but agent types lack a `DefaultStorageAccountID`, it auto-assigns the highest-priority account and logs a prominent warning.
+
+### Configuration
+
+Set `DefaultStorageAccountID` at any level via the admin UI or metadata sync:
+- **Agent Type** -- broadest default (e.g., all Loop agents → Dropbox)
+- **Agent Category** -- business-domain default (e.g., Marketing → Box, Finance → SharePoint)
+- **Agent** -- per-agent override
+- **Runtime** -- `ExecuteAgentParams.override.storageAccountId` for programmatic callers
+
+## Dependencies
+
 - `@memberjunction/ai` -- Core AI abstractions
 - `@memberjunction/ai-reranker` -- Two-stage retrieval reranking
 - `@memberjunction/actions` -- Server-side action execution

package/dist/AgentRunner.d.ts

@@ -10,7 +10,7 @@
  * @since 2.49.0
  */
 import { UserInfo, IMetadataProvider } from '@memberjunction/core';
-import { ExecuteAgentResult, ExecuteAgentParams, MediaOutput } from '@memberjunction/ai-core-plus';
+import { ExecuteAgentResult, ExecuteAgentParams, MediaOutput, FileOutputRef } from '@memberjunction/ai-core-plus';
 /**
  * AgentRunner provides a thin wrapper for executing AI agents.
  *
@@ -123,7 +123,7 @@ export declare class AgentRunner {
      * const newVersionNumber = maxVersion + 1;
      * ```
      */
-    GetMaxVersionForArtifact(artifactId: string, contextUser: UserInfo): Promise<number>;
+    GetMaxVersionForArtifact(artifactId: string, contextUser: UserInfo, provider?: IMetadataProvider): Promise<number>;
     /**
      * Checks whether the serialized content for a new artifact version is identical to the
      * latest existing version of the same artifact, using SHA-256 content hashing.
@@ -139,7 +139,7 @@ export declare class AgentRunner {
      * @param contextUser - User context for the RunView query
      * @returns The existing version's ID if content is identical, or `null` if a new version should be created
      */
-    protected CheckForDuplicateVersion(artifactId: string, candidateContent: string, latestVersionNumber: number, contextUser: UserInfo): Promise<string | null>;
+    protected CheckForDuplicateVersion(artifactId: string, candidateContent: string, latestVersionNumber: number, contextUser: UserInfo, provider?: IMetadataProvider): Promise<string | null>;
     /**
      * Creates a `ConversationDetailArtifact` junction record linking an artifact version
      * to a conversation detail, then returns the standard artifact result tuple.
@@ -280,6 +280,61 @@ export declare class AgentRunner {
      * ```
      */
     CreateConversationMediaAttachments(conversationDetailId: string, mediaOutputs: MediaOutput[], agentRunMediaIds: string[], contextUser: UserInfo, provider?: IMetadataProvider): Promise<string[]>;
+    /**
+     * Creates MJ: Artifact records for file outputs collected during agent execution.
+     * Reads directly from `ExecuteAgentResult.fileOutputs` — no DB query needed.
+     *
+     * Called automatically by RunAgentInConversation after the agent completes.
+     *
+     * @param fileOutputs - File outputs collected by BaseAgent during action execution
+     * @param conversationDetailId - The conversation detail to link artifacts to
+     * @param contextUser - User context for DB operations
+     * @param resolvedStorageAccountId - Pre-resolved FileStorageAccount ID from the agent's
+     *   hierarchical resolution chain (Runtime → Agent → Category → Type → fallback).
+     *   When provided, uploads use this specific account instead of picking the first active one.
+     */
+    ProcessFileArtifacts(fileOutputs: FileOutputRef[], conversationDetailId: string, contextUser: UserInfo, resolvedStorageAccountId?: string, provider?: IMetadataProvider): Promise<void>;
+    /**
+     * Re-processes file artifacts from a historical agent run by querying its persisted
+     * action step OutputData. Use this to recover artifacts for runs that completed before
+     * ProcessFileArtifacts was introduced, or for debugging.
+     *
+     * @param agentRunId - The agent run whose action steps to inspect
+     * @param conversationDetailId - The conversation detail to link artifacts to
+     * @param contextUser - User context for DB operations
+     */
+    ReprocessRunFileArtifacts(agentRunId: string, conversationDetailId: string, contextUser: UserInfo, provider?: IMetadataProvider): Promise<void>;
+    /** Loads all completed action steps for a given agent run (read-only, narrow fields). */
+    private loadActionStepsForRun;
+    /**
+     * Parses persisted OutputData JSON from an action step and extracts file output metadata.
+     * Detection is shape-based (looks for objects with fileName + mimeType + fileData/fileId),
+     * not name-based — works regardless of what the action named its output parameter.
+     *
+     * Used only by the historical reprocessing path — live runs use BaseAgent's detectFileOutputs.
+     */
+    private parseStepFileOutputs;
+    /** Uploads or resolves a single file output and creates the artifact records.
+     *  Falls back to inline base64 artifact if storage is unavailable or upload fails. */
+    private processFileOutput;
+    /**
+     * Uploads base64-encoded file content to MJStorage and creates an MJ: Files record.
+     * Returns the new MJ: Files record ID.
+     *
+     * @param resolvedStorageAccountId - Pre-resolved account from the agent's storage resolution chain.
+     *   When provided, uploads to this specific account. Otherwise falls back to the first active account.
+     */
+    private uploadBase64ToStorage;
+    /**
+     * Shared logic for creating an artifact + version + conversation detail link in a single
+     * transaction. The caller provides a callback to set the version-specific fields (file-backed
+     * vs. inline content).
+     */
+    private createArtifactWithVersion;
+    /** Creates a file-backed artifact (version references a FileID in MJStorage). */
+    private createFileArtifact;
+    /** Creates an inline artifact (version stores base64 data URL directly, no MJStorage). */
+    private createInlineFileArtifact;
     /**
      * Gets file extension from MIME type
      * @private

package/dist/AgentRunner.d.ts.map

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

package/dist/AgentRunner.js

@@ -10,10 +10,13 @@
  * @since 2.49.0
  */
 import { createHash } from 'crypto';
-import { LogError, LogStatusEx, IsVerboseLoggingEnabled, LogStatus, Metadata, RunView } from '@memberjunction/core';
+import { LogError, LogStatusEx, IsVerboseLoggingEnabled, LogStatus, Metadata, RunView, ProviderType } from '@memberjunction/core';
 import { MJGlobal, UUIDsEqual } from '@memberjunction/global';
 import { AIEngine } from '@memberjunction/aiengine';
+import { ParseFileOutputRef } from '@memberjunction/ai-core-plus';
 import { BaseAgent } from './base-agent.js';
+import { ArtifactMetadataEngine } from '@memberjunction/core-entities';
+import { FileStorageEngine } from '@memberjunction/storage';
 /**
  * AgentRunner provides a thin wrapper for executing AI agents.
  *
@@ -131,18 +134,39 @@ export class AgentRunner {
             // If conversationDetailId is provided, use it (UI-created agent response detail)
             if (options.conversationDetailId) {
                 agentResponseDetailId = options.conversationDetailId;
-                // Load the conversation detail to get the conversation ID AND keep reference for final status update
-                // This ensures backend can update Status/Message even if frontend disconnects (browser refresh)
-                agentResponseDetail = await md.GetEntityObject('MJ: Conversation Details', contextUser);
-                if (await agentResponseDetail.Load(agentResponseDetailId)) {
-                    conversationId = agentResponseDetail.ConversationID;
-                    LogStatus(`Using existing conversation ${conversationId} and agent response detail ${agentResponseDetailId}`);
-                    // Note: In this case, we don't know the user message detail ID
-                    userMessageDetailId = agentResponseDetailId; // For backward compatibility
+                // LATENCY OPTIMIZATION (Opt #2): When conversationId is pre-resolved by the caller
+                // (e.g., the resolver already loaded the ConversationDetail to build history), we
+                // skip the redundant DB load that was ONLY needed to extract ConversationID.
+                //
+                // We still must load the ConversationDetail entity object because it serves double
+                // duty: (a) progress callback updates its Message field during execution, and
+                // (b) step 5 sets the final Status/Message/ResponseForm after the agent completes.
+                // What we save here is the serial dependency: previously we had to wait for the
+                // Load to complete before we even knew conversationId. Now we know conversationId
+                // immediately and can resolve the entity object's load in parallel with other setup.
+                if (options.conversationId) {
+                    conversationId = options.conversationId;
+                    LogStatus(`Using pre-resolved conversation ${conversationId} and agent response detail ${agentResponseDetailId}`);
                 }
                 else {
-                    throw new Error(`Failed to load conversation detail ${agentResponseDetailId}`);
+                    // Fallback for callers that don't provide conversationId (backward compatibility).
+                    // This path still works but incurs the extra DB round-trip to extract conversationId.
+                    const tempDetail = await md.GetEntityObject('MJ: Conversation Details', contextUser);
+                    if (await tempDetail.Load(agentResponseDetailId)) {
+                        conversationId = tempDetail.ConversationID;
+                        LogStatus(`Using existing conversation ${conversationId} and agent response detail ${agentResponseDetailId}`);
+                    }
+                    else {
+                        throw new Error(`Failed to load conversation detail ${agentResponseDetailId}`);
+                    }
+                }
+                // Load the entity object for progress updates and final status Save at step 5.
+                // This is needed regardless of whether conversationId was pre-resolved.
+                agentResponseDetail = await md.GetEntityObject('MJ: Conversation Details', contextUser);
+                if (!await agentResponseDetail.Load(agentResponseDetailId)) {
+                    throw new Error(`Failed to load conversation detail entity for status updates: ${agentResponseDetailId}`);
                 }
+                userMessageDetailId = agentResponseDetailId; // For backward compatibility
             }
             else {
                 // Server creates BOTH user message and agent response details
@@ -260,55 +284,90 @@ export class AgentRunner {
             const agentResult = await this.RunAgent(modifiedParams);
             // Mark execution as completed to stop progress saves
             agentExecutionCompleted = true;
-            // Step 5: Update agent response detail with final result
-            // ALWAYS update status - don't rely on frontend (browser may refresh during execution)
-            if (agentResponseDetail && agentResponseDetailId) {
-                // Wait for any in-flight progress save to complete
-                // EnsureSaveComplete() resolves immediately if no save in progress
-                await agentResponseDetail.EnsureSaveComplete();
-                LogStatus('Updating agent response detail with final result');
-                // Reload to get any updates from agent execution
-                await agentResponseDetail.Load(agentResponseDetailId);
-                agentResponseDetail.Message = agentResult.agentRun?.Message ||
-                    (agentResult.success
-                        ? '✅ Completed'
-                        : agentResult.agentRun?.ErrorMessage || '❌ Failed');
-                agentResponseDetail.Status = agentResult.success ? 'Complete' : 'Error';
-                // Set response form and command fields
-                if (agentResult.responseForm) {
-                    agentResponseDetail.ResponseForm = JSON.stringify(agentResult.responseForm);
+            // LATENCY OPTIMIZATION (Opt #5): Steps 5, 6, and 7 are now parallelized.
+            //
+            // Previously these ran sequentially: save final status → process artifacts → save media.
+            // This added their individual latencies together (~130ms for steps 6+7, plus ~80ms for
+            // step 5's EnsureSaveComplete + Load + Save cycle).
+            //
+            // These operations are safe to parallelize because:
+            // - Step 5 (status update) writes to the ConversationDetail record (Status, Message fields)
+            // - Step 6 (artifacts) creates new Artifact/ArtifactVersion records and a junction record
+            //   linking to the ConversationDetail — it only needs the agentResponseDetailId (string),
+            //   not the entity object, and doesn't read/write the same fields as step 5
+            // - Step 7 (media) creates new AIAgentRunMedia and ConversationDetailAttachment records —
+            //   entirely separate from steps 5 and 6
+            //
+            // IMPORTANT: All three MUST complete before the resolver publishes the 'complete' event,
+            // because the client reloads all conversation data from the DB when it receives that event.
+            // If any write hasn't flushed yet, the client would see stale data. Promise.all guarantees
+            // all three finish before we return.
+            // Step 5: Update agent response detail with final result (async)
+            const updateDetailPromise = (async () => {
+                if (agentResponseDetail && agentResponseDetailId) {
+                    // Wait for any in-flight progress save to complete
+                    // EnsureSaveComplete() resolves immediately if no save in progress
+                    await agentResponseDetail.EnsureSaveComplete();
+                    LogStatus('Updating agent response detail with final result');
+                    // Reload to get any updates from agent execution
+                    await agentResponseDetail.Load(agentResponseDetailId);
+                    agentResponseDetail.Message = agentResult.agentRun?.Message ||
+                        (agentResult.success
+                            ? '✅ Completed'
+                            : agentResult.agentRun?.ErrorMessage || '❌ Failed');
+                    agentResponseDetail.Status = agentResult.success ? 'Complete' : 'Error';
+                    // Set response form and command fields
+                    if (agentResult.responseForm) {
+                        agentResponseDetail.ResponseForm = JSON.stringify(agentResult.responseForm);
+                    }
+                    if (agentResult.actionableCommands && agentResult.actionableCommands.length > 0) {
+                        agentResponseDetail.ActionableCommands = JSON.stringify(agentResult.actionableCommands);
+                    }
+                    if (agentResult.automaticCommands && agentResult.automaticCommands.length > 0) {
+                        agentResponseDetail.AutomaticCommands = JSON.stringify(agentResult.automaticCommands);
+                    }
+                    await agentResponseDetail.Save();
+                    LogStatus(`Updated agent response detail ${agentResponseDetailId} with final status: ${agentResponseDetail.Status}`);
                 }
-                if (agentResult.actionableCommands && agentResult.actionableCommands.length > 0) {
-                    agentResponseDetail.ActionableCommands = JSON.stringify(agentResult.actionableCommands);
+            })();
+            // Step 6: Process artifacts if requested and agent succeeded (async)
+            const processArtifactsPromise = (async () => {
+                const shouldCreateArtifacts = options.createArtifacts !== false; // Default true
+                if (shouldCreateArtifacts && agentResult.success && agentResult.payload) {
+                    return this.ProcessAgentArtifacts(agentResult, agentResponseDetailId, options.sourceArtifactId, contextUser, md);
                 }
-                if (agentResult.automaticCommands && agentResult.automaticCommands.length > 0) {
-                    agentResponseDetail.AutomaticCommands = JSON.stringify(agentResult.automaticCommands);
+                return undefined;
+            })();
+            // Step 6b: Process file artifacts produced by file-generation actions (async)
+            const processFileArtifactsPromise = (async () => {
+                if (agentResult.success && agentResponseDetailId && agentResult.fileOutputs?.length) {
+                    await this.ProcessFileArtifacts(agentResult.fileOutputs, agentResponseDetailId, contextUser, agentResult.resolvedStorageAccountId, md);
                 }
-                await agentResponseDetail.Save();
-                LogStatus(`Updated agent response detail ${agentResponseDetailId} with final status: ${agentResponseDetail.Status}`);
-            }
-            // Step 6: Process artifacts if requested and agent succeeded
-            let artifactInfo;
-            const shouldCreateArtifacts = options.createArtifacts !== false; // Default true
-            if (shouldCreateArtifacts && agentResult.success && agentResult.payload) {
-                // Artifacts link to agent response detail ID
-                artifactInfo = await this.ProcessAgentArtifacts(agentResult, agentResponseDetailId, options.sourceArtifactId, contextUser, md);
-            }
-            // Step 7: Save media outputs to AIAgentRunMedia and create conversation attachments
-            let mediaIds = [];
-            if (agentResult.mediaOutputs && agentResult.mediaOutputs.length > 0) {
-                // Filter to only media that should be persisted (persist !== false)
-                const mediaToSave = agentResult.mediaOutputs.filter(m => m.persist !== false);
-                LogStatus(`Processing ${mediaToSave.length} of ${agentResult.mediaOutputs.length} media outputs (filtered by persist flag)`);
-                // Save to AIAgentRunMedia for permanent storage
-                mediaIds = await this.SaveAgentRunMedia(agentResult.agentRun.ID, mediaToSave, // Pass filtered array
-                contextUser, md);
-                // Create ConversationDetailAttachment records for UI display
-                if (agentResponseDetailId && mediaIds.length > 0) {
-                    await this.CreateConversationMediaAttachments(agentResponseDetailId, mediaToSave, // Pass same filtered array to keep indices aligned
-                    mediaIds, contextUser, md);
+            })();
+            // Step 7: Save media outputs to AIAgentRunMedia and create conversation attachments (async)
+            const saveMediaPromise = (async () => {
+                if (agentResult.mediaOutputs && agentResult.mediaOutputs.length > 0) {
+                    const mediaToSave = agentResult.mediaOutputs.filter(m => m.persist !== false);
+                    LogStatus(`Processing ${mediaToSave.length} of ${agentResult.mediaOutputs.length} media outputs (filtered by persist flag)`);
+                    // Save to AIAgentRunMedia for permanent storage
+                    const ids = await this.SaveAgentRunMedia(agentResult.agentRun.ID, mediaToSave, contextUser, md);
+                    // Create ConversationDetailAttachment records for UI display
+                    if (agentResponseDetailId && ids.length > 0) {
+                        await this.CreateConversationMediaAttachments(agentResponseDetailId, mediaToSave, ids, contextUser, md);
+                    }
+                    return ids;
                 }
-            }
+                return [];
+            })();
+            // Wait for all three post-execution operations to complete before returning.
+            // The resolver publishes the 'complete' event after this returns, so the client
+            // is guaranteed to see all DB writes when it reloads.
+            const [, artifactInfo] = await Promise.all([
+                updateDetailPromise,
+                processArtifactsPromise,
+                processFileArtifactsPromise,
+                saveMediaPromise
+            ]);
             return {
                 agentResult,
                 conversationId,
@@ -338,9 +397,9 @@ export class AgentRunner {
      * const newVersionNumber = maxVersion + 1;
      * ```
      */
-    async GetMaxVersionForArtifact(artifactId, contextUser) {
+    async GetMaxVersionForArtifact(artifactId, contextUser, provider) {
         try {
-            const rv = new RunView();
+            const rv = RunView.FromMetadataProvider(provider || this._provider);
             const result = await rv.RunView({
                 EntityName: 'MJ: Artifact Versions',
                 ExtraFilter: `ArtifactID='${artifactId}'`,
@@ -373,9 +432,9 @@ export class AgentRunner {
      * @param contextUser - User context for the RunView query
      * @returns The existing version's ID if content is identical, or `null` if a new version should be created
      */
-    async CheckForDuplicateVersion(artifactId, candidateContent, latestVersionNumber, contextUser) {
+    async CheckForDuplicateVersion(artifactId, candidateContent, latestVersionNumber, contextUser, provider) {
         const candidateHash = createHash('sha256').update(candidateContent, 'utf8').digest('hex');
-        const rv = new RunView();
+        const rv = RunView.FromMetadataProvider(provider || this._provider);
         const result = await rv.RunView({
             EntityName: 'MJ: Artifact Versions',
             ExtraFilter: `ArtifactID='${artifactId}' AND VersionNumber=${latestVersionNumber}`,
@@ -433,7 +492,7 @@ export class AgentRunner {
      */
     async FindPreviousArtifactForMessage(conversationDetailId, contextUser, provider) {
         try {
-            const rv = new RunView();
+            const rv = RunView.FromMetadataProvider(provider || this._provider);
             const result = await rv.RunView({
                 EntityName: 'MJ: Conversation Detail Artifacts',
                 ExtraFilter: `ConversationDetailID='${conversationDetailId}' AND Direction='Output'`,
@@ -519,7 +578,7 @@ export class AgentRunner {
             let isNewArtifact = false;
             // Priority 1: Use explicit source artifact if provided
             if (sourceArtifactId) {
-                const maxVersion = await this.GetMaxVersionForArtifact(sourceArtifactId, contextUser);
+                const maxVersion = await this.GetMaxVersionForArtifact(sourceArtifactId, contextUser, provider);
                 artifactId = sourceArtifactId;
                 newVersionNumber = maxVersion + 1;
                 LogStatus(`Creating version ${newVersionNumber} of source artifact ${artifactId}`);
@@ -565,7 +624,7 @@ export class AgentRunner {
             const serializedContent = JSON.stringify(payload, null, 2);
             // Skip version creation if content is identical to the latest version
             if (!isNewArtifact && newVersionNumber > 1) {
-                const existingVersionId = await this.CheckForDuplicateVersion(artifactId, serializedContent, newVersionNumber - 1, contextUser);
+                const existingVersionId = await this.CheckForDuplicateVersion(artifactId, serializedContent, newVersionNumber - 1, contextUser, provider);
                 if (existingVersionId) {
                     console.debug(`Skipping duplicate artifact version — content identical to version ${newVersionNumber - 1}`);
                     return undefined;
@@ -863,6 +922,233 @@ export class AgentRunner {
             return attachmentIds;
         }
     }
+    // ── File artifact processing ───────────────────────────────────────────────
+    /**
+     * Creates MJ: Artifact records for file outputs collected during agent execution.
+     * Reads directly from `ExecuteAgentResult.fileOutputs` — no DB query needed.
+     *
+     * Called automatically by RunAgentInConversation after the agent completes.
+     *
+     * @param fileOutputs - File outputs collected by BaseAgent during action execution
+     * @param conversationDetailId - The conversation detail to link artifacts to
+     * @param contextUser - User context for DB operations
+     * @param resolvedStorageAccountId - Pre-resolved FileStorageAccount ID from the agent's
+     *   hierarchical resolution chain (Runtime → Agent → Category → Type → fallback).
+     *   When provided, uploads use this specific account instead of picking the first active one.
+     */
+    async ProcessFileArtifacts(fileOutputs, conversationDetailId, contextUser, resolvedStorageAccountId, provider) {
+        if (fileOutputs.length === 0)
+            return;
+        const md = provider || this._provider;
+        // Hoist engine configs before parallel processing
+        await Promise.all([
+            ArtifactMetadataEngine.Instance.Config(false, contextUser),
+            FileStorageEngine.Instance.Config(false, contextUser),
+        ]);
+        await Promise.all(fileOutputs.map(fo => this.processFileOutput(fo, conversationDetailId, contextUser, resolvedStorageAccountId, md)));
+    }
+    /**
+     * Re-processes file artifacts from a historical agent run by querying its persisted
+     * action step OutputData. Use this to recover artifacts for runs that completed before
+     * ProcessFileArtifacts was introduced, or for debugging.
+     *
+     * @param agentRunId - The agent run whose action steps to inspect
+     * @param conversationDetailId - The conversation detail to link artifacts to
+     * @param contextUser - User context for DB operations
+     */
+    async ReprocessRunFileArtifacts(agentRunId, conversationDetailId, contextUser, provider) {
+        const md = provider || this._provider;
+        const steps = await this.loadActionStepsForRun(agentRunId, contextUser, md);
+        if (steps.length === 0)
+            return;
+        const fileOutputs = steps.flatMap(step => this.parseStepFileOutputs(step));
+        await this.ProcessFileArtifacts(fileOutputs, conversationDetailId, contextUser, undefined, md);
+    }
+    /** Loads all completed action steps for a given agent run (read-only, narrow fields). */
+    async loadActionStepsForRun(agentRunId, contextUser, provider) {
+        const rv = RunView.FromMetadataProvider(provider || this._provider);
+        const result = await rv.RunView({
+            EntityName: 'MJ: AI Agent Run Steps',
+            ExtraFilter: `AgentRunID='${agentRunId}' AND StepType='Actions' AND Status='Completed'`,
+            Fields: ['ID', 'OutputData'],
+            ResultType: 'simple'
+        }, contextUser);
+        return result.Success ? (result.Results ?? []) : [];
+    }
+    /**
+     * Parses persisted OutputData JSON from an action step and extracts file output metadata.
+     * Detection is shape-based (looks for objects with fileName + mimeType + fileData/fileId),
+     * not name-based — works regardless of what the action named its output parameter.
+     *
+     * Used only by the historical reprocessing path — live runs use BaseAgent's detectFileOutputs.
+     */
+    parseStepFileOutputs(step) {
+        if (!step.OutputData)
+            return [];
+        let outputData;
+        try {
+            outputData = JSON.parse(step.OutputData);
+        }
+        catch {
+            return [];
+        }
+        const params = outputData.actionResult?.parameters;
+        if (!params)
+            return [];
+        const results = [];
+        for (const param of params) {
+            if (param.Value == null)
+                continue;
+            const ref = ParseFileOutputRef(param.Value);
+            if (ref)
+                results.push(ref);
+        }
+        return results;
+    }
+    /** Uploads or resolves a single file output and creates the artifact records.
+     *  Falls back to inline base64 artifact if storage is unavailable or upload fails. */
+    async processFileOutput(fo, conversationDetailId, contextUser, resolvedStorageAccountId, provider) {
+        try {
+            if (fo.fileId) {
+                // File already in storage — create file-backed artifact
+                await this.createFileArtifact(fo.fileId, fo.mimeType, fo.fileName, fo.sizeBytes, conversationDetailId, contextUser, provider);
+                return;
+            }
+            // Check if any storage accounts are configured
+            const hasStorage = FileStorageEngine.Instance.HasStorageAccounts;
+            if (!hasStorage) {
+                // No storage configured — go straight to inline artifact
+                LogStatus(`ProcessFileArtifacts: no storage accounts configured for "${fo.fileName}", creating inline artifact`);
+                await this.createInlineFileArtifact(fo.fileData, fo.mimeType, fo.fileName, fo.sizeBytes, conversationDetailId, contextUser, provider);
+                return;
+            }
+            // Try to upload to storage
+            try {
+                const fileId = await this.uploadBase64ToStorage(fo.fileData, fo.fileName, fo.mimeType, contextUser, resolvedStorageAccountId, provider);
+                await this.createFileArtifact(fileId, fo.mimeType, fo.fileName, fo.sizeBytes, conversationDetailId, contextUser, provider);
+            }
+            catch (storageError) {
+                // Upload failed — fall back to inline artifact
+                LogStatus(`ProcessFileArtifacts: storage upload failed for "${fo.fileName}", creating inline artifact: ${storageError.message}`);
+                await this.createInlineFileArtifact(fo.fileData, fo.mimeType, fo.fileName, fo.sizeBytes, conversationDetailId, contextUser, provider);
+            }
+        }
+        catch (error) {
+            LogError(`ProcessFileArtifacts: failed for "${fo.fileName}": ${error.message}`);
+        }
+    }
+    /**
+     * Uploads base64-encoded file content to MJStorage and creates an MJ: Files record.
+     * Returns the new MJ: Files record ID.
+     *
+     * @param resolvedStorageAccountId - Pre-resolved account from the agent's storage resolution chain.
+     *   When provided, uploads to this specific account. Otherwise falls back to the first active account.
+     */
+    async uploadBase64ToStorage(base64Data, fileName, mimeType, contextUser, resolvedStorageAccountId, provider) {
+        const result = await FileStorageEngine.Instance.UploadFile({
+            content: Buffer.from(base64Data, 'base64'),
+            fileName,
+            mimeType,
+            contextUser,
+            storageAccountId: resolvedStorageAccountId,
+            provider
+        });
+        return result.FileID;
+    }
+    /**
+     * Shared logic for creating an artifact + version + conversation detail link in a single
+     * transaction. The caller provides a callback to set the version-specific fields (file-backed
+     * vs. inline content).
+     */
+    async createArtifactWithVersion(params) {
+        const { mimeType, fileName, sizeBytes, conversationDetailId, contextUser, provider, setVersionFields, label } = params;
+        // Resolve the artifact type by MIME type; fall back to the built-in JSON type
+        const JSON_ARTIFACT_TYPE_ID = 'ae674c7e-ea0d-49ea-89e4-0649f5eb20d4';
+        const artifactType = ArtifactMetadataEngine.Instance.GetArtifactTypeByMimeType(mimeType);
+        if (!artifactType) {
+            LogStatus(`ProcessFileArtifacts: no ArtifactType found for MIME ${mimeType}, using JSON fallback`);
+        }
+        const artifactTypeId = artifactType?.ID ?? JSON_ARTIFACT_TYPE_ID;
+        // Use direct provider transaction (BeginTransaction/CommitTransaction) instead of
+        // TransactionGroup. This ensures saves execute immediately within the SQL transaction,
+        // so server-side entity hooks (e.g. ArtifactVersion.ExtractAndSaveAttributes) can
+        // Load() parent records that were saved earlier in the same transaction.
+        const dbProvider = provider;
+        const useTransaction = dbProvider.ProviderType === ProviderType.Database;
+        if (useTransaction) {
+            await dbProvider.BeginTransaction();
+        }
+        try {
+            // Create the artifact header
+            const artifact = await provider.GetEntityObject('MJ: Artifacts', contextUser);
+            artifact.Name = fileName;
+            artifact.TypeID = artifactTypeId;
+            artifact.UserID = contextUser.ID;
+            artifact.Visibility = 'Always';
+            if (!(await artifact.Save())) {
+                throw new Error(`Failed to save artifact for ${label}: ${fileName}`);
+            }
+            // Create the artifact version — shared fields first, then caller-specific fields
+            const version = await provider.GetEntityObject('MJ: Artifact Versions', contextUser);
+            version.ArtifactID = artifact.ID;
+            version.VersionNumber = 1;
+            version.MimeType = mimeType;
+            version.FileName = fileName;
+            version.UserID = contextUser.ID;
+            if (sizeBytes !== undefined) {
+                version.ContentSizeBytes = sizeBytes;
+            }
+            setVersionFields(version);
+            if (!(await version.Save())) {
+                throw new Error(`Failed to save artifact version for ${label}: ${fileName}`);
+            }
+            // Link the artifact version to the conversation detail
+            const junction = await provider.GetEntityObject('MJ: Conversation Detail Artifacts', contextUser);
+            junction.ConversationDetailID = conversationDetailId;
+            junction.ArtifactVersionID = version.ID;
+            junction.Direction = 'Output';
+            if (!(await junction.Save())) {
+                throw new Error(`Failed to link ${label} artifact to conversation detail: ${conversationDetailId}`);
+            }
+            if (useTransaction) {
+                await dbProvider.CommitTransaction();
+            }
+            LogStatus(`Created ${label} artifact: ${fileName} (${mimeType}) → artifact ${artifact.ID}, version ${version.ID}`);
+        }
+        catch (error) {
+            if (useTransaction) {
+                try {
+                    await dbProvider.RollbackTransaction();
+                }
+                catch (rollbackError) {
+                    LogError(`Failed to rollback ${label} artifact transaction: ${rollbackError}`);
+                }
+            }
+            throw error;
+        }
+    }
+    /** Creates a file-backed artifact (version references a FileID in MJStorage). */
+    async createFileArtifact(fileId, mimeType, fileName, sizeBytes, conversationDetailId, contextUser, provider) {
+        await this.createArtifactWithVersion({
+            mimeType, fileName, sizeBytes, conversationDetailId, contextUser, provider,
+            label: 'file',
+            setVersionFields: (version) => {
+                version.ContentMode = 'File';
+                version.FileID = fileId;
+            }
+        });
+    }
+    /** Creates an inline artifact (version stores base64 data URL directly, no MJStorage). */
+    async createInlineFileArtifact(base64Data, mimeType, fileName, sizeBytes, conversationDetailId, contextUser, provider) {
+        await this.createArtifactWithVersion({
+            mimeType, fileName, sizeBytes, conversationDetailId, contextUser, provider,
+            label: 'inline file',
+            setVersionFields: (version) => {
+                version.ContentMode = 'Text';
+                version.Content = `data:${mimeType};base64,${base64Data}`;
+            }
+        });
+    }
     /**
      * Gets file extension from MIME type
      * @private