@memberjunction/ai-prompts 5.41.0 → 5.43.0

package/dist/AIPromptRunner.js

@@ -1,12 +1,11 @@
 import { BaseLLM, ChatParams, ChatMessageRole, GetAIAPIKey, ErrorAnalyzer, ResolveFileInputStrategy } from '@memberjunction/ai';
 import { AIModelRunner } from './AIModelRunner.js';
 import { AIModelSelectionInfo } from '@memberjunction/ai-core-plus';
-import { LogErrorEx, LogStatus, LogStatusEx, IsVerboseLoggingEnabled, Metadata } from '@memberjunction/core';
+import { BaseEntitySaveQueue, LogErrorEx, LogStatus, LogStatusEx, IsVerboseLoggingEnabled, Metadata } from '@memberjunction/core';
 import { CleanJSON, MJGlobal, JSONValidator, ValidationResult, ValidationErrorInfo, ValidationErrorType, UUIDsEqual, NormalizeUUID } from '@memberjunction/global';
 import { CredentialEngine } from '@memberjunction/credentials';
 import { TemplateEngineServer } from '@memberjunction/templates';
 import { ExecutionPlanner } from './ExecutionPlanner.js';
-import { ParallelExecutionCoordinator } from './ParallelExecutionCoordinator.js';
 import { AIEngine } from '@memberjunction/aiengine';
 import { AIEngineBase } from '@memberjunction/ai-engine-base';
 import { SystemPlaceholderManager } from '@memberjunction/ai-core-plus';
@@ -55,22 +54,48 @@ export class AIPromptRunner {
     constructor() {
         this._provider = null;
         /**
-         * Instance-keyed chain of in-flight AIPromptRun saves. Mirrors the BaseAgent step-save pattern:
-         * prompt-run persistence is fire-and-forget so the execution path never blocks on a DB
-         * round-trip, but saves for the SAME entity are sequenced — the initial 'Running' INSERT always
-         * completes before the finalize UPDATE, so a slow INSERT can never clobber the finalized row.
-         * Keyed by the entity INSTANCE (stable), not its ID. See {@link queuePromptRunSave}.
+         * Fire-and-forget AIPromptRun persistence. Prompt-run logging never blocks the execution path on a
+         * DB round-trip; the shared {@link BaseEntitySaveQueue} sequences saves for the SAME entity (the
+         * initial 'Running' INSERT always completes before the finalize UPDATE, and the finalize mutation
+         * runs INSIDE the post-INSERT task so a slow INSERT can never clobber the finalized row). Failures
+         * stay in this runner's structured log stream via the queue's `onError` hook.
          */
-        this._promptRunSaveChains = new Map();
-        /** All queued prompt-run save promises, for optional flushing via {@link WaitForPendingPromptRunSaves}. */
-        this._pendingPromptRunSaves = [];
+        this._promptRunQueue = new BaseEntitySaveQueue({
+            onError: (message) => this.logError(message, { category: 'PromptRunSave' }),
+        });
         this._metadata = this._provider ?? new Metadata();
         this._templateEngine = TemplateEngineServer.Instance;
         this._executionPlanner = new ExecutionPlanner();
-        this._parallelCoordinator = new ParallelExecutionCoordinator();
         this._jsonValidator = new JSONValidator();
         this._modelRunner = new AIModelRunner();
     }
+    /** ClassFactory key the parallel coordinator self-registers under (see {@link ParallelCoordinator}). */
+    static { this.PARALLEL_COORDINATOR_KEY = 'ParallelExecutionCoordinator'; }
+    /**
+     * Lazily resolves the parallel execution coordinator.
+     *
+     * The coordinator is a SUBCLASS of AIPromptRunner — it inherits {@link executeModel} and the rest
+     * of the battle-tested execution path so there is a single source of truth for credential / driver
+     * / ChatParams / streaming resolution. That subclass relationship means the base cannot statically
+     * `new` it without a hard circular import, so we resolve it through the ClassFactory instead (the
+     * coordinator self-registers via `@RegisterClass(AIPromptRunner, PARALLEL_COORDINATOR_KEY)`).
+     * Created once per runner and reused; the runner's Provider override is propagated. Throws a clear
+     * error if the coordinator class was never loaded/registered — otherwise ClassFactory would silently
+     * fall back to a plain AIPromptRunner that lacks the parallel methods.
+     */
+    get ParallelCoordinator() {
+        if (!this._parallelCoordinator) {
+            const instance = MJGlobal.Instance.ClassFactory.CreateInstance(AIPromptRunner, AIPromptRunner.PARALLEL_COORDINATOR_KEY);
+            if (!instance || typeof instance.executeTasksInParallel !== 'function') {
+                throw new Error(`ParallelExecutionCoordinator is not registered with the ClassFactory. Ensure ` +
+                    `'@memberjunction/ai-prompts' is fully loaded (it is exported from the package index and ` +
+                    `picked up by the class-registration manifest).`);
+            }
+            instance.Provider = this.Provider;
+            this._parallelCoordinator = instance;
+        }
+        return this._parallelCoordinator;
+    }
     /**
      * Access the underlying AIModelRunner for embedding and other non-LLM model calls.
      * Use this when you need tracked embedding execution with AIPromptRun record creation.
@@ -457,25 +482,20 @@ export class AIPromptRunner {
             let renderedPromptText = '';
             // For hierarchical prompts, we need to create the parent prompt run first to get its ID
             let parentPromptRun;
-            let selectedModel;
             let childTemplateRenderingResult;
-            let modelSelectionInfo;
+            let selection;
             // Handle different prompt execution modes
             if (params.childPrompts && params.childPrompts.length > 0) {
                 // Hierarchical template composition mode - render child templates first, then compose
-                //this.logStatus(`🌳 Composing prompt with ${params.childPrompts.length} child templates in hierarchical mode`, true, params);
                 // Determine which prompt to use for model selection
                 let modelSelectionPrompt = prompt;
                 if (params.modelSelectionPrompt) {
                     modelSelectionPrompt = params.modelSelectionPrompt;
-                    //this.logStatus(`🎯 Using prompt "${modelSelectionPrompt.Name}" for model selection instead of parent prompt`, true, params);
                 }
-                // Select model using the appropriate prompt
-                const modelResult = await this.selectModel(modelSelectionPrompt, params.override?.modelId, params.contextUser, params.configurationId, params.override?.vendorId, params);
-                selectedModel = modelResult.model;
-                modelSelectionInfo = modelResult.selectionInfo;
-                if (!selectedModel) {
-                    throw new Error(this.buildNoModelFoundMessage(modelSelectionPrompt.Name, modelSelectionInfo));
+                // Select model using the appropriate prompt — capture the FULL result
+                selection = await this.selectModel(modelSelectionPrompt, params.override?.modelId, params.contextUser, params.configurationId, params.override?.vendorId, params);
+                if (!selection.model) {
+                    throw new Error(this.buildNoModelFoundMessage(modelSelectionPrompt.Name, selection.selectionInfo));
                 }
                 // Check if we have a system prompt override
                 if (params.systemPromptOverride) {
@@ -490,7 +510,7 @@ export class AIPromptRunner {
                     renderedPromptText = await this.renderPromptWithChildTemplates(prompt, params, childTemplateRenderingResult.renderedTemplates);
                 }
                 // Create parent prompt run for the final composed prompt execution
-                parentPromptRun = await this.createPromptRun(prompt, selectedModel, params, renderedPromptText, startTime, params.override?.vendorId, modelSelectionInfo);
+                parentPromptRun = await this.createPromptRun(prompt, selection.model, params, renderedPromptText, startTime, params.override?.vendorId, selection.selectionInfo);
             }
             else if (prompt.TemplateID && (!params.conversationMessages || params.templateMessageRole !== 'none')) {
                 // Check if we have a system prompt override
@@ -520,30 +540,28 @@ export class AIPromptRunner {
             if (params.cancellationToken?.aborted) {
                 throw new Error('Prompt execution was cancelled during template rendering');
             }
-            // If no model was selected yet (no template case), select one now
-            if (!selectedModel) {
+            // If no model was selected yet (non-hierarchical case), select one now — capture the FULL result
+            if (!selection?.model) {
                 let modelSelectionPrompt = prompt;
                 if (params.modelSelectionPrompt) {
                     modelSelectionPrompt = params.modelSelectionPrompt;
                     this.logStatus(`🎯 Using prompt "${modelSelectionPrompt.Name}" for model selection instead of main prompt`, true, params);
                 }
-                const modelResult = await this.selectModel(modelSelectionPrompt, params.override?.modelId, params.contextUser, params.configurationId, params.override?.vendorId, params);
-                selectedModel = modelResult.model;
-                modelSelectionInfo = modelResult.selectionInfo;
-                if (!selectedModel) {
-                    throw new Error(this.buildNoModelFoundMessage(modelSelectionPrompt.Name, modelSelectionInfo));
+                selection = await this.selectModel(modelSelectionPrompt, params.override?.modelId, params.contextUser, params.configurationId, params.override?.vendorId, params);
+                if (!selection.model) {
+                    throw new Error(this.buildNoModelFoundMessage(modelSelectionPrompt.Name, selection.selectionInfo));
                 }
             }
             // Check if we need parallel execution based on ParallelizationMode
             const shouldUseParallelExecution = prompt.ParallelizationMode && prompt.ParallelizationMode !== 'None';
             let result;
             if (shouldUseParallelExecution) {
-                // Use parallel execution path
-                result = await this.executePromptInParallel(prompt, renderedPromptText, params, startTime, parentPromptRun, selectedModel, modelSelectionInfo);
+                // Use parallel execution path — pass full selection through
+                result = await this.executePromptInParallel(prompt, renderedPromptText, params, startTime, parentPromptRun, selection);
             }
             else {
-                // Use traditional single execution path
-                result = await this.executeSinglePrompt(prompt, renderedPromptText, params, startTime, parentPromptRun, selectedModel, modelSelectionInfo);
+                // Use traditional single execution path — pass full selection through
+                result = await this.executeSinglePrompt(prompt, renderedPromptText, params, startTime, parentPromptRun, selection);
             }
             // Note: With template composition, we only execute once so no rollup calculations needed
             // The final composed prompt is executed as a single operation
@@ -613,33 +631,22 @@ export class AIPromptRunner {
      * @param startTime - Execution start time
      * @returns Promise<AIPromptRunResult<T>> - The execution result
      */
-    async executeSinglePrompt(prompt, renderedPromptText, params, startTime, existingPromptRun, existingModel, existingModelSelectionInfo) {
+    async executeSinglePrompt(prompt, renderedPromptText, params, startTime, existingPromptRun, existingSelection) {
         // Check for cancellation before model selection
         if (params.cancellationToken?.aborted) {
             throw new Error('Prompt execution was cancelled before model selection');
         }
-        // Use existing model if provided (hierarchical case) or select one
-        let selectedModel = existingModel;
-        let modelSelectionInfo = existingModelSelectionInfo;
-        let vendorDriverClass;
-        let vendorApiName;
-        let vendorSupportsEffortLevel;
-        let modelEffortLevel;
-        let allCandidates = [];
-        if (modelSelectionInfo) {
-            // we received model selection info, need to lookup vendor driver class and api name from there
-            const vendorID = modelSelectionInfo.vendorSelected?.ID;
-            const modelID = modelSelectionInfo.modelSelected.ID;
-            const modelVendor = AIEngine.Instance.ModelVendorsByModelID.get(NormalizeUUID(modelID))
-                ?.find(mv => UUIDsEqual(mv.VendorID, vendorID));
-            if (modelVendor) {
-                vendorDriverClass = modelVendor.DriverClass;
-                vendorApiName = modelVendor.APIName;
-                vendorSupportsEffortLevel = modelVendor.SupportsEffortLevel;
-            }
-            // Extract valid candidates from selection info for retry logic
-            allCandidates = this.buildCandidatesFromSelectionInfo(modelSelectionInfo);
-        }
+        // Use existing selection if provided (hierarchical case) or select now
+        let selectedModel = existingSelection?.model ?? undefined;
+        let modelSelectionInfo = existingSelection?.selectionInfo;
+        let vendorDriverClass = existingSelection?.vendorDriverClass;
+        let vendorApiName = existingSelection?.vendorApiName;
+        let vendorSupportsEffortLevel = existingSelection?.vendorSupportsEffortLevel;
+        let modelEffortLevel = existingSelection?.modelEffortLevel;
+        let allCandidates = existingSelection?.allCandidates ?? [];
+        // Credential probes already done during selection — reused by failover so it doesn't
+        // recompute hasCredentialsAvailable for the prefix it walks before the selected candidate.
+        let credentialAvailability = existingSelection?.credentialAvailability;
         if (!selectedModel) {
             // Determine which prompt to use for model selection
             let modelSelectionPrompt = prompt;
@@ -655,6 +662,7 @@ export class AIPromptRunner {
             modelEffortLevel = modelResult.modelEffortLevel;
             modelSelectionInfo = modelResult.selectionInfo;
             allCandidates = modelResult.allCandidates || [];
+            credentialAvailability = modelResult.credentialAvailability;
             if (!selectedModel) {
                 throw new Error(this.buildNoModelFoundMessage(modelSelectionPrompt.Name, modelSelectionInfo));
             }
@@ -670,7 +678,8 @@ export class AIPromptRunner {
             throw new Error('Prompt execution was cancelled before model execution');
         }
         // Execute with retry logic for validation failures
-        const { modelResult, parsedResult, validationAttempts, cumulativeTokens } = await this.executeWithValidationRetries(selectedModel, renderedPromptText, prompt, params, promptRun, allCandidates, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel // Pass model-specific effort level
+        const { modelResult, parsedResult, validationAttempts, cumulativeTokens } = await this.executeWithValidationRetries(selectedModel, renderedPromptText, prompt, params, promptRun, allCandidates, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel, // Pass model-specific effort level
+        credentialAvailability // Reuse credential probes from selection
         );
         // Calculate execution metrics
         const endTime = new Date();
@@ -730,7 +739,7 @@ export class AIPromptRunner {
      * @param startTime - Execution start time
      * @returns Promise<AIPromptRunResult<T>> - The aggregated execution result
      */
-    async executePromptInParallel(prompt, renderedPromptText, params, startTime, existingPromptRun, existingModel, existingModelSelectionInfo) {
+    async executePromptInParallel(prompt, renderedPromptText, params, startTime, existingPromptRun, existingSelection) {
         // Check for cancellation before starting parallel execution
         if (params.cancellationToken?.aborted) {
             throw new Error('Parallel execution was cancelled before starting');
@@ -738,21 +747,21 @@ export class AIPromptRunner {
         // Load AI Engine to get models and prompt models
         await AIEngine.Instance.Config(false, params.contextUser);
         let executionTasks;
-        // If a model is already selected (from hierarchical template composition), 
+        // If a model is already selected (from hierarchical template composition),
         // create a single task with that model instead of using the planner
-        if (existingModel) {
+        if (existingSelection?.model) {
             // Create a single execution task with the pre-selected model
             executionTasks = [{
                     taskId: 'pre-selected',
-                    model: existingModel,
-                    vendorDriverClass: undefined, // Would need to look up vendor entity for this
-                    vendorApiName: existingModel.Vendor, // Vendor is already the name string
+                    model: existingSelection.model,
+                    vendorDriverClass: existingSelection.vendorDriverClass,
+                    vendorApiName: existingSelection.vendorApiName,
                     messages: params.conversationMessages || [],
                     promptText: renderedPromptText,
                     templateMessageRole: params.templateMessageRole || 'system',
                     contextUser: params.contextUser
                 }];
-            this.logStatus(`   Using pre-selected model "${existingModel.Name}" for parallel execution`, true, params);
+            this.logStatus(`   Using pre-selected model "${existingSelection.model.Name}" for parallel execution`, true, params);
         }
         else {
             // Normal parallel execution path - let the planner decide
@@ -777,7 +786,7 @@ export class AIPromptRunner {
             throw new Error('Parallel execution was cancelled before task execution');
         }
         // Execute tasks in parallel
-        const parallelResult = await this._parallelCoordinator.executeTasksInParallel(params, executionTasks, undefined, undefined, params.cancellationToken, undefined, params.agentRunId);
+        const parallelResult = await this.ParallelCoordinator.executeTasksInParallel(params, executionTasks, undefined, undefined, params.cancellationToken, undefined, params.agentRunId);
         if (!parallelResult.success) {
             throw new Error(`Parallel execution failed: ${parallelResult.errors.join(', ')}`);
         }
@@ -793,7 +802,7 @@ export class AIPromptRunner {
                 method: 'PromptSelector',
                 selectorPromptId: prompt.ResultSelectorPromptID,
             };
-            const aiSelectedResult = await this._parallelCoordinator.selectBestResult(successfulResults, selectionConfig, undefined, params.cancellationToken);
+            const aiSelectedResult = await this.ParallelCoordinator.selectBestResult(successfulResults, selectionConfig, undefined, params.cancellationToken);
             if (aiSelectedResult) {
                 selectedResult = aiSelectedResult;
             }
@@ -822,7 +831,7 @@ export class AIPromptRunner {
         }
         // Use existing prompt run if provided (hierarchical case) or create new one
         // Use the model selection info if provided (from hierarchical execution)
-        const consolidatedPromptRun = existingPromptRun || await this.createPromptRun(prompt, selectedResult.task.model, params, renderedPromptText, startTime, params.override?.vendorId, existingModelSelectionInfo);
+        const consolidatedPromptRun = existingPromptRun || await this.createPromptRun(prompt, selectedResult.task.model, params, renderedPromptText, startTime, params.override?.vendorId, existingSelection?.selectionInfo);
         // Update with parallel execution metadata
         const endTime = new Date();
         consolidatedPromptRun.CompletedAt = endTime;
@@ -875,8 +884,10 @@ export class AIPromptRunner {
         // Set Status and WasSelectedResult for parallel execution
         consolidatedPromptRun.Status = parallelResult.successCount > 0 ? 'Completed' : 'Failed';
         consolidatedPromptRun.WasSelectedResult = true; // This is the consolidated result chosen by judge
-        // Persist the consolidated run fire-and-forget; chains after its INSERT via the save queue.
-        this.queuePromptRunSave(consolidatedPromptRun);
+        // Persist the consolidated run fire-and-forget; the finalize UPDATE chains after its INSERT via
+        // the save queue. These fields are set after all the awaited parallel work, so the INSERT has long
+        // landed — a plain Update (no post-INSERT callback) is race-safe here.
+        this._promptRunQueue.Update(consolidatedPromptRun);
         // Create additional results from all other successful results (excluding the best one)
         const additionalResults = [];
         // Sort successful results by ranking (if available) or keep original order
@@ -944,11 +955,11 @@ export class AIPromptRunner {
             modelInfo: {
                 modelId: selectedResult.task.model.ID,
                 modelName: selectedResult.task.model.Name,
-                vendorId: existingModelSelectionInfo?.vendorSelected?.ID, // VendorID not directly available on AIModel
+                vendorId: existingSelection?.selectionInfo?.vendorSelected?.ID, // VendorID not directly available on AIModel
                 vendorName: selectedResult.task.model.Vendor,
             },
             judgeMetadata: selectedResult.judgeMetadata,
-            modelSelectionInfo: existingModelSelectionInfo, // Include model selection info if provided
+            modelSelectionInfo: existingSelection?.selectionInfo, // Include model selection info if provided
         };
     }
     /**
@@ -1275,7 +1286,7 @@ export class AIPromptRunner {
             //   });
             // }
             // Select the first candidate with available credentials and track all attempts
-            const { selected, consideredModels } = await this.selectModelWithAPIKeyTracked(candidates, prompt.ID, params);
+            const { selected, consideredModels, credentialAvailability } = await this.selectModelWithAPIKeyTracked(candidates, prompt.ID, params);
             // Merge considered models into our tracking
             modelsConsidered.push(...consideredModels);
             if (!selected) {
@@ -1287,6 +1298,7 @@ export class AIPromptRunner {
                     vendorSupportsEffortLevel: undefined,
                     modelEffortLevel: undefined,
                     allCandidates: candidates,
+                    credentialAvailability,
                     selectionInfo: this.createSelectionInfo({
                         aiConfiguration: configuration,
                         modelsConsidered,
@@ -1331,6 +1343,7 @@ export class AIPromptRunner {
                 vendorSupportsEffortLevel: selected.supportsEffortLevel,
                 modelEffortLevel: selected.effortLevel, // Pass through model-specific effort level
                 allCandidates: candidates,
+                credentialAvailability,
                 selectionInfo: this.createSelectionInfo({
                     aiConfiguration: configuration,
                     modelsConsidered,
@@ -1879,33 +1892,6 @@ export class AIPromptRunner {
         Object.assign(info, data);
         return info;
     }
-    /**
-     * Converts model selection info into ModelVendorCandidate array for retry logic.
-     * Extracts only the valid candidates (those with available API keys) from the selection info.
-     *
-     * @param selectionInfo - Model selection information containing considered models
-     * @returns Array of valid model-vendor candidates sorted by priority
-     */
-    buildCandidatesFromSelectionInfo(selectionInfo) {
-        const validModels = selectionInfo.extractValidCandidates();
-        return validModels.map(considered => {
-            // Find matching model vendor for driver and API info
-            const modelVendor = considered.vendor
-                ? considered.model.ModelVendors.find(mv => UUIDsEqual(mv.VendorID, considered.vendor.ID))
-                : undefined;
-            return {
-                model: considered.model,
-                vendorId: considered.vendor?.ID,
-                vendorName: considered.vendor?.Name,
-                driverClass: modelVendor?.DriverClass || considered.model.DriverClass,
-                apiName: modelVendor?.APIName || considered.model.APIName,
-                supportsEffortLevel: modelVendor?.SupportsEffortLevel ?? considered.model.SupportsEffortLevel ?? false,
-                isPreferredVendor: false, // Can't determine from selection info alone
-                priority: considered.priority,
-                source: (selectionInfo.selectionStrategy === 'ByPower' ? 'power-rank' : 'model-type')
-            };
-        }).sort((a, b) => b.priority - a.priority); // Sort by priority descending
-    }
     /**
      * Enhanced version of selectModelWithAPIKey that tracks all considered models
      * for model selection reporting. Uses the hierarchical credential resolution
@@ -1997,7 +1983,7 @@ export class AIPromptRunner {
                 maxErrorLength: params?.maxErrorLength
             });
         }
-        return { selected: selectedCandidate, consideredModels };
+        return { selected: selectedCandidate, consideredModels, credentialAvailability: credentialCache };
     }
     /**
      * Builds a descriptive error message when no model could be selected for a prompt.
@@ -2049,51 +2035,12 @@ export class AIPromptRunner {
         };
     }
     /**
-     * Queues a fire-and-forget `Save()` for a prompt-run entity. Saves for the same instance are
-     * chained (via {@link _promptRunSaveChains}) so the initial INSERT always completes before any
-     * finalize UPDATE — guaranteeing a slow INSERT can't overwrite the finalized row. The whole
-     * chain runs independently of the execution flow (callers do NOT await it), so the model call
-     * is never delayed by a DB write.
-     *
-     * Save failures are logged (non-fatal): the AIPromptRun record is observability, not part of the
-     * prompt's success contract, so a rare persistence failure must not fail the prompt. The chained
-     * promise is tracked in {@link _pendingPromptRunSaves} so {@link WaitForPendingPromptRunSaves}
-     * can flush them when determinism is required (e.g. tests, or a caller that needs the rows
-     * durably written). Returns that promise.
-     */
-    queuePromptRunSave(promptRun) {
-        const previous = this._promptRunSaveChains.get(promptRun) ?? Promise.resolve(true);
-        const current = previous
-            .then(async () => {
-            const ok = await promptRun.Save();
-            if (!ok) {
-                this.logError(`Failed to save AIPromptRun ${promptRun.ID || '(unsaved)'}: ${promptRun.LatestResult?.CompleteMessage || 'Unknown error'}`, {
-                    category: 'PromptRunSave',
-                    metadata: { promptRunId: promptRun.ID }
-                });
-            }
-            return ok;
-        })
-            .catch((err) => {
-            // Infrastructure-level throw (network, etc.) — log and swallow so the fire-and-forget
-            // promise never surfaces as an unhandled rejection.
-            this.logError(err instanceof Error ? err : new Error(String(err)), {
-                category: 'PromptRunSave',
-                metadata: { promptRunId: promptRun.ID }
-            });
-            return false;
-        });
-        this._promptRunSaveChains.set(promptRun, current);
-        this._pendingPromptRunSaves.push(current);
-        return current;
-    }
-    /**
-     * Awaits all in-flight prompt-run saves queued by this runner instance. The normal execution
-     * path does NOT call this — prompt-run persistence is intentionally fire-and-forget. Exposed for
-     * tests and for callers that need the AIPromptRun rows durably written before proceeding.
+     * Awaits all in-flight prompt-run saves queued by this runner instance. The normal execution path
+     * does NOT call this — prompt-run persistence is intentionally fire-and-forget. Exposed for tests
+     * and for callers that need the AIPromptRun rows durably written before proceeding.
      */
     async WaitForPendingPromptRunSaves() {
-        await Promise.allSettled(this._pendingPromptRunSaves);
+        await this._promptRunQueue.Flush();
     }
     async createPromptRun(prompt, model, params, systemPromptText, startTime, vendorId, modelSelectionInfo) {
         const provider = params.provider ?? Metadata.Provider;
@@ -2110,7 +2057,7 @@ export class AIPromptRunner {
             promptRun.Status = 'Running';
             promptRun.Cancelled = false;
             promptRun.CacheHit = false;
-            promptRun.StreamingEnabled = false;
+            promptRun.StreamingEnabled = !!params.onStreaming;
             promptRun.WasSelectedResult = false;
             // Set model selection tracking fields
             if (modelSelectionInfo) {
@@ -2261,7 +2208,7 @@ export class AIPromptRunner {
             // NewRecord() above, so callers (and the onPromptRunCreated callback) have it immediately —
             // we don't block the model call on the INSERT. The finalize UPDATE chains after this INSERT
             // via the instance-keyed save queue, so ordering is guaranteed.
-            this.queuePromptRunSave(promptRun);
+            this._promptRunQueue.Insert(promptRun);
             // Invoke callback if provided. The ID is available without awaiting the save (client-generated
             // by NewRecord()), so agent-run/step linking that depends on it works immediately.
             if (params.onPromptRunCreated) {
@@ -2353,7 +2300,7 @@ export class AIPromptRunner {
      * - updatePromptRunWithFailoverFailure: Records failed failover metadata
      * - createFailoverErrorResult: Creates standardized error response
      */
-    async executeModelWithFailover(model, renderedPrompt, prompt, params, vendorId, conversationMessages, templateMessageRole = 'system', cancellationToken, allCandidates, promptRun, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel) {
+    async executeModelWithFailover(model, renderedPrompt, prompt, params, vendorId, conversationMessages, templateMessageRole = 'system', cancellationToken, allCandidates, promptRun, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel, credentialAvailability) {
         // Get failover configuration (used for errorScope filtering)
         const failoverConfig = this.getFailoverConfiguration(prompt);
         // If no candidates provided or failover disabled, execute normally with first model
@@ -2363,10 +2310,45 @@ export class AIPromptRunner {
         // Track failover attempts
         const failoverAttempts = [];
         let lastError = null;
+        // Cache credential availability per driver:model:vendor for the duration of this failover
+        // scan so we don't repeat env-var / binding lookups while walking the candidate list.
+        //
+        // PERF: seed it with the probes model SELECTION already performed (same key format). Selection
+        // walks the priority list until it finds the first credentialed candidate, so this map holds
+        // the prefix it rejected (known false) PLUS the selected candidate (known true) — which is
+        // exactly the segment failover re-walks on the happy path. Reusing those results means the
+        // common case (and any caller looping failover) does ZERO redundant hasCredentialsAvailable
+        // calls. The not-evaluated tail is intentionally absent, so failover still lazily probes it
+        // only if a real failure forces it to walk down there.
+        const failoverCredentialCache = credentialAvailability
+            ? new Map(credentialAvailability)
+            : new Map();
+        const candidateHasCredentials = (c) => {
+            const key = `${c.driverClass}:${c.model.ID}:${c.vendorId || 'default'}`;
+            let has = failoverCredentialCache.get(key);
+            if (has === undefined) {
+                has = this.hasCredentialsAvailable(c.driverClass, prompt.ID, c.model.ID, c.vendorId, params);
+                failoverCredentialCache.set(key, has);
+            }
+            return has;
+        };
+        let skippedForCredentials = 0;
         // Iterate through all candidates in priority order with instant failover
         for (let i = 0; i < allCandidates.length; i++) {
             const candidate = allCandidates[i];
             const attemptStartTime = Date.now();
+            // Skip candidates with no credentials configured. `allCandidates` is intentionally the
+            // FULL priority-ordered list (see the DECISION note in selectModelWithAPIKeyTracked),
+            // so it can include vendors that have no API key in this environment. Firing a live
+            // request at one of those produces a misleading "401 invalid API key" — and because an
+            // Authentication error is treated as fatal, it would halt failover before any
+            // credentialed candidate is ever reached. Skipping here makes failover land on the
+            // first candidate that can actually authenticate (mirroring model selection's own
+            // highest-priority-with-credentials rule).
+            if (!candidateHasCredentials(candidate)) {
+                skippedForCredentials++;
+                continue;
+            }
             try {
                 // Log the attempt if not the first one
                 if (i > 0) {
@@ -2435,6 +2417,11 @@ export class AIPromptRunner {
         if (promptRun && failoverAttempts.length > 0) {
             this.updatePromptRunWithFailoverFailure(promptRun, failoverAttempts);
         }
+        // If every candidate was skipped for missing credentials we never attempted a call and
+        // have no underlying error to report — surface an actionable message instead of null.
+        if (!lastError && failoverAttempts.length === 0 && skippedForCredentials > 0) {
+            lastError = new Error(`No API credentials configured for any of the ${skippedForCredentials} candidate model-vendor combination(s) for prompt "${prompt.Name}".`);
+        }
         return this.createFailoverErrorResult(lastError, failoverAttempts);
     }
     /**
@@ -2570,7 +2557,11 @@ export class AIPromptRunner {
         };
     }
     /**
-     * Executes the AI model with the rendered prompt
+     * Executes the AI model with the rendered prompt.
+     *
+     * `protected` so the parallel coordinator subclass reuses this exact code path — credential
+     * resolution, driver selection, ChatParams construction, prefill, media handling, and streaming
+     * all live here ONCE. Do not duplicate this logic elsewhere.
      */
     async executeModel(model, renderedPrompt, prompt, params, vendorId, conversationMessages, templateMessageRole = 'system', cancellationToken, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel) {
         // define these variables here to ensure they're available in the catch block
@@ -2712,6 +2703,17 @@ export class AIPromptRunner {
             this.stripUnsupportedMediaBlocks(llm, chatParams, model, verbose, params);
             // Apply assistant prefill (native or fallback) based on prompt config and provider support
             this.applyAssistantPrefill(chatParams, prompt, model, vendorId, llm);
+            // Streaming: wire the prompt-level onStreaming callback into the LLM call. This is the SINGLE
+            // place streaming is configured for prompt execution, so the single-model path and the parallel
+            // path (which bridges its per-task callbacks into params.onStreaming) stream through identical
+            // code — no second streaming implementation that can drift.
+            if (params.onStreaming) {
+                const onStreaming = params.onStreaming;
+                chatParams.streaming = true;
+                chatParams.streamingCallbacks = {
+                    OnContent: (chunk, isComplete) => onStreaming({ content: chunk, isComplete, modelName: model.Name }),
+                };
+            }
             // Execute the model with cancellation support
             if (cancellationToken) {
                 // If cancellation token is provided, wrap the execution to handle cancellation
@@ -3091,7 +3093,7 @@ export class AIPromptRunner {
     /**
      * Executes the model with retry logic for validation failures
      */
-    async executeWithValidationRetries(selectedModel, renderedPromptText, prompt, params, promptRun, allCandidates, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel) {
+    async executeWithValidationRetries(selectedModel, renderedPromptText, prompt, params, promptRun, allCandidates, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel, credentialAvailability) {
         const validationAttempts = [];
         const maxRetries = Math.max(0, prompt.MaxRetries || 0);
         let lastError = null;
@@ -3111,7 +3113,8 @@ export class AIPromptRunner {
                 }
                 // Execute the AI model with failover support
                 const modelResult = await this.executeModelWithFailover(selectedModel, renderedPromptText, prompt, params, promptRun.VendorID, params.conversationMessages, params.templateMessageRole || 'system', params.cancellationToken, allCandidates, // Pass the candidates from initial selection
-                promptRun, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel);
+                promptRun, vendorDriverClass, vendorApiName, vendorSupportsEffortLevel, modelEffortLevel, credentialAvailability // Reuse credential probes from selection
+                );
                 // Check for fatal errors - don't attempt validation/retry on these
                 // Fatal errors (like ContextLengthExceeded when all models exhausted) cannot be resolved by retrying
                 if (!modelResult.success && modelResult.errorInfo?.severity === 'Fatal') {
@@ -3982,6 +3985,18 @@ export class AIPromptRunner {
      * Updates the AIPromptRun entity with execution results
      */
     async updatePromptRun(promptRun, prompt, modelResult, parsedResult, endTime, executionTimeMS, validationAttempts, cumulativeTokens) {
+        // Fire-and-forget finalize UPDATE. The field mutations run INSIDE the post-INSERT task (after the
+        // 'Running' INSERT + its finalizeSave reload land), so the reload can never revert them and the
+        // chained UPDATE persists the finalized state — the "stuck at Running" race is structurally
+        // impossible. The execution flow does NOT await the save.
+        this._promptRunQueue.Update(promptRun, () => this.applyFinalizedPromptRunFields(promptRun, prompt, modelResult, parsedResult, endTime, executionTimeMS, validationAttempts, cumulativeTokens));
+    }
+    /**
+     * Populates a prompt-run's finalized fields (result, tokens, cost, timing, rollups) from the model
+     * result. Runs INSIDE the post-INSERT save task — see {@link updatePromptRun}. Errors here are
+     * logged (non-fatal): the AIPromptRun is observability, not part of the prompt's success contract.
+     */
+    applyFinalizedPromptRunFields(promptRun, prompt, modelResult, parsedResult, endTime, executionTimeMS, validationAttempts, cumulativeTokens) {
         try {
             promptRun.CompletedAt = endTime;
             promptRun.ExecutionTimeMS = executionTimeMS;
@@ -4168,10 +4183,6 @@ export class AIPromptRunner {
             if (promptRun.Cost !== undefined) {
                 promptRun.TotalCost = promptRun.Cost;
             }
-            // Finalize fire-and-forget. Chains after the initial INSERT (same entity instance) so the
-            // 'Running' INSERT can never overwrite this finalized 'Completed'/'Failed' state. The
-            // execution flow does NOT await this — see queuePromptRunSave / WaitForPendingPromptRunSaves.
-            this.queuePromptRunSave(promptRun);
         }
         catch (error) {
             this.logError(error, {