@memberjunction/ai-prompts 5.40.2 → 5.42.0

package/dist/AIPromptRunner.js

@@ -6,7 +6,6 @@ import { CleanJSON, MJGlobal, JSONValidator, ValidationResult, ValidationErrorIn
 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';
@@ -26,6 +25,21 @@ function mimeFromBlockType(type) {
     }
 }
 export class AIPromptRunner {
+    /**
+     * Process-wide cache of parsed `OutputExample` JSON, keyed by the raw example string.
+     * A prompt's OutputExample is a static string reused across every run and every validation
+     * retry, so re-parsing it each time is pure waste. Keyed by content (not prompt ID) so two
+     * prompts sharing an identical example share one parsed entry and an edited example never
+     * serves a stale parse. Stores `{ parsed }` on success or `{ error }` on failure so we cache
+     * the failure too rather than re-throwing-and-reparsing bad JSON every attempt.
+     */
+    static { this._outputExampleCache = new Map(); }
+    /**
+     * Marker used in `AIModelSelectionInfo.modelsConsidered[].unavailableReason` for candidates
+     * that were intentionally NOT credential-checked because a higher-priority candidate had
+     * already been selected. See the DECISION note in {@link selectModelWithAPIKeyTracked}.
+     */
+    static { this.NOT_EVALUATED_REASON = 'Not evaluated (a higher-priority candidate was already selected; set AIPromptParams.forceFullModelEvaluation to probe all)'; }
     /**
      * Optional metadata provider override. Callers should set
      * `instance.Provider = providerToUse` before invoking run methods
@@ -39,13 +53,49 @@ 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}.
+         */
+        this._promptRunSaveChains = new Map();
+        /** All queued prompt-run save promises, for optional flushing via {@link WaitForPendingPromptRunSaves}. */
+        this._pendingPromptRunSaves = [];
         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.
@@ -116,19 +166,15 @@ export class AIPromptRunner {
         });
     }
     /**
-     * Checks if a model vendor is configured as an inference provider
+     * Checks if a model vendor is configured as an inference provider.
+     * Delegates to the memoized {@link AIEngine.IsInferenceProvider} helper so the
+     * "Inference Provider" vendor-type lookup happens once per engine load rather than on
+     * every candidate in every selection pass.
      * @param modelVendor The model vendor to check
      * @returns true if the vendor is an inference provider
      */
     isInferenceProvider(modelVendor) {
-        // Find the inference provider type from cached vendor type definitions
-        const inferenceProviderType = AIEngine.Instance.VendorTypeDefinitions.find(vt => vt.Name === 'Inference Provider');
-        if (!inferenceProviderType) {
-            // Fallback to checking if it's not a model developer (should rarely happen)
-            const modelDeveloperType = AIEngine.Instance.VendorTypeDefinitions.find(vt => vt.Name === 'Model Developer');
-            return !UUIDsEqual(modelVendor.TypeID, modelDeveloperType?.ID);
-        }
-        return UUIDsEqual(modelVendor.TypeID, inferenceProviderType.ID);
+        return AIEngine.Instance.IsInferenceProvider(modelVendor);
     }
     /**
      * Resolves credentials for AI model execution using a hierarchical resolution system.
@@ -171,7 +217,8 @@ export class AIPromptRunner {
         }
         // Priority 3: ModelVendor bindings - with failover
         if (modelId && vendorId) {
-            const modelVendor = AIEngine.Instance.ModelVendors.find(mv => UUIDsEqual(mv.ModelID, modelId) && UUIDsEqual(mv.VendorID, vendorId) && mv.Status === 'Active');
+            const modelVendor = AIEngine.Instance.ModelVendorsByModelID.get(NormalizeUUID(modelId))
+                ?.find(mv => UUIDsEqual(mv.VendorID, vendorId) && mv.Status === 'Active');
             if (modelVendor) {
                 const bindings = AIEngine.Instance.GetCredentialBindingsForTarget('ModelVendor', modelVendor.ID);
                 const result = await this.tryCredentialBindingsWithFailover(bindings, 'AICredentialBinding(ModelVendor)', params, verbose);
@@ -189,7 +236,7 @@ export class AIPromptRunner {
         // Priority 5: Type-based default credential
         // If the vendor declares a CredentialTypeID, try to find a default credential of that type
         if (vendorId) {
-            const vendor = AIEngine.Instance.Vendors.find(v => UUIDsEqual(v.ID, vendorId));
+            const vendor = AIEngine.Instance.VendorsByID.get(NormalizeUUID(vendorId));
             if (vendor?.CredentialTypeID) {
                 const defaultCredential = this.findDefaultCredentialByType(vendor.CredentialTypeID);
                 if (defaultCredential) {
@@ -348,7 +395,8 @@ export class AIPromptRunner {
         }
         // Priority 3: ModelVendor bindings
         if (modelId && vendorId) {
-            const modelVendor = AIEngine.Instance.ModelVendors.find(mv => UUIDsEqual(mv.ModelID, modelId) && UUIDsEqual(mv.VendorID, vendorId) && mv.Status === 'Active');
+            const modelVendor = AIEngine.Instance.ModelVendorsByModelID.get(NormalizeUUID(modelId))
+                ?.find(mv => UUIDsEqual(mv.VendorID, vendorId) && mv.Status === 'Active');
             if (modelVendor && AIEngine.Instance.HasCredentialBindings('ModelVendor', modelVendor.ID)) {
                 return true;
             }
@@ -361,7 +409,7 @@ export class AIPromptRunner {
         }
         // Priority 5: Type-based default credential
         if (vendorId) {
-            const vendor = AIEngine.Instance.Vendors.find(v => UUIDsEqual(v.ID, vendorId));
+            const vendor = AIEngine.Instance.VendorsByID.get(NormalizeUUID(vendorId));
             if (vendor?.CredentialTypeID) {
                 const defaultCredential = this.findDefaultCredentialByType(vendor.CredentialTypeID);
                 if (defaultCredential) {
@@ -434,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) {
@@ -467,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
@@ -497,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
@@ -590,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.ModelVendors.find(mv => UUIDsEqual(mv.VendorID, vendorID) &&
-                UUIDsEqual(mv.ModelID, modelID));
-            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;
@@ -632,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));
             }
@@ -647,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();
@@ -707,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');
@@ -715,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
@@ -754,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(', ')}`);
         }
@@ -770,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;
             }
@@ -799,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;
@@ -852,18 +884,8 @@ 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
-        const saveResult = await consolidatedPromptRun.Save();
-        if (!saveResult) {
-            this.logError(`Failed to save consolidated AIPromptRun: ${consolidatedPromptRun.LatestResult?.CompleteMessage || 'Unknown error'}`, {
-                category: 'ConsolidatedPromptRunSave',
-                metadata: {
-                    promptRunId: consolidatedPromptRun.ID,
-                    executionTasks: executionTasks.length,
-                    successfulResults: successfulResults.length
-                },
-                maxErrorLength: params.maxErrorLength
-            });
-        }
+        // Persist the consolidated run fire-and-forget; chains after its INSERT via the save queue.
+        this.queuePromptRunSave(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
@@ -931,11 +953,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
         };
     }
     /**
@@ -1225,7 +1247,7 @@ export class AIPromptRunner {
             }
             // Get configuration info if provided
             if (configurationId) {
-                configuration = AIEngine.Instance.Configurations.find(c => UUIDsEqual(c.ID, configurationId));
+                configuration = AIEngine.Instance.ConfigurationsByID.get(NormalizeUUID(configurationId));
                 configurationName = configuration?.Name;
             }
             // Build unified list of model-vendor candidates
@@ -1262,7 +1284,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) {
@@ -1274,6 +1296,7 @@ export class AIPromptRunner {
                     vendorSupportsEffortLevel: undefined,
                     modelEffortLevel: undefined,
                     allCandidates: candidates,
+                    credentialAvailability,
                     selectionInfo: this.createSelectionInfo({
                         aiConfiguration: configuration,
                         modelsConsidered,
@@ -1309,7 +1332,7 @@ export class AIPromptRunner {
             // Get selected vendor entity
             let selectedVendor;
             if (selected.vendorId) {
-                selectedVendor = AIEngine.Instance.Vendors.find(v => UUIDsEqual(v.ID, selected.vendorId));
+                selectedVendor = AIEngine.Instance.VendorsByID.get(NormalizeUUID(selected.vendorId));
             }
             return {
                 model: selected.model,
@@ -1318,6 +1341,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,
@@ -1385,7 +1409,7 @@ export class AIPromptRunner {
      * Returns candidates for the single model if it's active and compatible.
      */
     buildCandidatesForExplicitModel(explicitModelId, prompt, preferredVendorId) {
-        const model = AIEngine.Instance.Models.find(m => UUIDsEqual(m.ID, explicitModelId));
+        const model = AIEngine.Instance.ModelsByID.get(NormalizeUUID(explicitModelId));
         if (!model || !model.IsActive) {
             return [];
         }
@@ -1480,7 +1504,7 @@ export class AIPromptRunner {
             return 0;
         const modelsWithPower = promptModels
             .map(pm => {
-            const model = AIEngine.Instance.Models.find(m => UUIDsEqual(m.ID, pm.ModelID));
+            const model = AIEngine.Instance.ModelsByID.get(NormalizeUUID(pm.ModelID));
             return { powerRank: model?.PowerRank ?? 0, priority: pm.Priority || 1 };
         });
         const totalWeight = modelsWithPower.reduce((sum, m) => sum + m.priority, 0);
@@ -1510,7 +1534,7 @@ export class AIPromptRunner {
      */
     buildCandidatesForGeneralSelection(prompt, configurationId, preferredVendorId, verbose) {
         const preferredVendorName = preferredVendorId ?
-            AIEngine.Instance.Vendors.find(v => UUIDsEqual(v.ID, preferredVendorId))?.Name : undefined;
+            AIEngine.Instance.VendorsByID.get(NormalizeUUID(preferredVendorId))?.Name : undefined;
         // Get prompt models for configuration
         const promptModels = this.getPromptModelsForConfiguration(prompt, configurationId);
         const candidates = [];
@@ -1582,7 +1606,7 @@ export class AIPromptRunner {
             const pm = promptModels[i];
             // Compute priority as inverse of array position so highest-priority (first) gets the largest number
             const computedPriority = promptModels.length - i;
-            const model = AIEngine.Instance.Models.find(m => UUIDsEqual(m.ID, pm.ModelID));
+            const model = AIEngine.Instance.ModelsByID.get(NormalizeUUID(pm.ModelID));
             if (!model || !model.IsActive)
                 continue;
             if (pm.VendorID) {
@@ -1604,8 +1628,9 @@ export class AIPromptRunner {
      * Helper: Create candidate for specific vendor from AIPromptModel.
      */
     createCandidateForSpecificVendor(model, promptModel, computedPriority = 0) {
-        const modelVendor = AIEngine.Instance.ModelVendors.find(mv => UUIDsEqual(mv.ModelID, promptModel.ModelID) &&
-            UUIDsEqual(mv.VendorID, promptModel.VendorID) &&
+        // Use the model's precomputed ModelVendors (grouped at engine load) instead of scanning
+        // the global ModelVendors array — model.ID === promptModel.ModelID here.
+        const modelVendor = model.ModelVendors.find(mv => UUIDsEqual(mv.VendorID, promptModel.VendorID) &&
             mv.Status === 'Active' &&
             this.isInferenceProvider(mv));
         if (!modelVendor)
@@ -1627,9 +1652,8 @@ export class AIPromptRunner {
      * Helper: Create candidates for all vendors of a model, sorted by vendor priority.
      */
     createCandidatesForAllVendors(model, computedPriority = 0) {
-        const vendors = AIEngine.Instance.ModelVendors
-            .filter(mv => UUIDsEqual(mv.ModelID, model.ID) &&
-            mv.Status === 'Active' &&
+        const vendors = model.ModelVendors
+            .filter(mv => mv.Status === 'Active' &&
             this.isInferenceProvider(mv))
             .sort((a, b) => (b.Priority || 0) - (a.Priority || 0));
         const candidates = [];
@@ -1691,7 +1715,7 @@ export class AIPromptRunner {
      */
     addPromptSpecificCandidates(candidates, promptModels, preferredVendorId) {
         for (const pm of promptModels) {
-            const model = AIEngine.Instance.Models.find(m => UUIDsEqual(m.ID, pm.ModelID));
+            const model = AIEngine.Instance.ModelsByID.get(NormalizeUUID(pm.ModelID));
             if (model && model.IsActive) {
                 const modelCandidates = this.createCandidatesForModel(model, 5000, 'prompt-model', preferredVendorId, pm.Priority);
                 candidates.push(...modelCandidates);
@@ -1714,7 +1738,7 @@ export class AIPromptRunner {
                 LogStatus(`Adding ${parentModels.length} models from parent config "${parentConfig.Name}" as fallback`);
             }
             for (const pm of parentModels) {
-                const model = AIEngine.Instance.Models.find(m => UUIDsEqual(m.ID, pm.ModelID));
+                const model = AIEngine.Instance.ModelsByID.get(NormalizeUUID(pm.ModelID));
                 if (model && model.IsActive) {
                     // Decrease base priority for each level up the chain (3000, 2500, 2000, etc.)
                     const basePriority = 3000 - (i * 500);
@@ -1731,7 +1755,7 @@ export class AIPromptRunner {
             LogStatus(`Adding ${nullConfigModels.length} NULL configuration models as universal fallback`);
         }
         for (const pm of nullConfigModels) {
-            const model = AIEngine.Instance.Models.find(m => UUIDsEqual(m.ID, pm.ModelID));
+            const model = AIEngine.Instance.ModelsByID.get(NormalizeUUID(pm.ModelID));
             if (model && model.IsActive) {
                 const modelCandidates = this.createCandidatesForModel(model, 1000, // Lowest priority tier
                 'prompt-model', preferredVendorId, pm.Priority);
@@ -1759,8 +1783,7 @@ export class AIPromptRunner {
         return AIEngine.Instance.Models.filter(m => m.IsActive &&
             (!prompt.AIModelTypeID || UUIDsEqual(m.AIModelTypeID, prompt.AIModelTypeID)) &&
             (!preferredVendorName ||
-                AIEngine.Instance.ModelVendors.some(mv => UUIDsEqual(mv.ModelID, m.ID) &&
-                    mv.Status === 'Active' &&
+                m.ModelVendors.some(mv => mv.Status === 'Active' &&
                     mv.Vendor === preferredVendorName &&
                     this.isInferenceProvider(mv))));
     }
@@ -1801,9 +1824,11 @@ export class AIPromptRunner {
      */
     createCandidatesForModel(model, basePriority, source, preferredVendorId, promptModelPriority) {
         const modelCandidates = [];
-        // Get all vendors for this model - filter for inference providers only
-        const modelVendors = AIEngine.Instance.ModelVendors
-            .filter(mv => UUIDsEqual(mv.ModelID, model.ID) && mv.Status === 'Active' && this.isInferenceProvider(mv))
+        // Get all vendors for this model - filter for inference providers only.
+        // Uses the model's precomputed ModelVendors (grouped at engine load) rather than scanning
+        // the global ModelVendors array.
+        const modelVendors = model.ModelVendors
+            .filter(mv => mv.Status === 'Active' && this.isInferenceProvider(mv))
             .sort((a, b) => b.Priority - a.Priority);
         // First, add preferred vendor if it exists
         if (preferredVendorId) {
@@ -1865,34 +1890,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
-                ? AIEngine.Instance.ModelVendors.find(mv => UUIDsEqual(mv.ModelID, considered.model.ID) &&
-                    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
@@ -1908,8 +1905,33 @@ export class AIPromptRunner {
         // Key format: "driverClass:modelId:vendorId" to properly cache credential hierarchy
         const credentialCache = new Map();
         const consideredModels = [];
-        // Check ALL candidates to build complete list of valid and invalid options
+        // DECISION (performance): candidates are ordered by priority, and we only need the
+        // highest-priority candidate that has working credentials. So once we find that first
+        // hit, we STOP credential-probing the remaining candidates and record them as
+        // "not-evaluated" rather than running a `hasCredentialsAvailable` check (which does
+        // env-var lookups + binding scans) for every configured model on every prompt run.
+        // The remaining candidates are still kept in `consideredModels` (and in the returned
+        // `allCandidates` from selectModel, which is the FULL ordered list) so failover and the
+        // ordering are unaffected — only the per-candidate availability *telemetry* for the tail
+        // is skipped. Callers that need a complete availability report (e.g. an admin diagnostic)
+        // can set `AIPromptParams.forceFullModelEvaluation = true` to probe every candidate.
+        const forceFullEval = params?.forceFullModelEvaluation === true;
+        let selected;
         for (const candidate of candidates) {
+            const vendorEntity = candidate.vendorId
+                ? AIEngine.Instance.VendorsByID.get(NormalizeUUID(candidate.vendorId))
+                : undefined;
+            // Short-circuit: a usable candidate is already selected and full evaluation wasn't requested.
+            if (selected && !forceFullEval) {
+                consideredModels.push({
+                    model: candidate.model,
+                    vendor: vendorEntity,
+                    priority: candidate.priority,
+                    available: false,
+                    unavailableReason: AIPromptRunner.NOT_EVALUATED_REASON
+                });
+                continue;
+            }
             // Build cache key including model and vendor for proper credential resolution
             const cacheKey = `${candidate.driverClass}:${candidate.model.ID}:${candidate.vendorId || 'default'}`;
             // Check cache first
@@ -1922,22 +1944,20 @@ export class AIPromptRunner {
                 hasCredentials = this.hasCredentialsAvailable(candidate.driverClass, promptId, candidate.model.ID, candidate.vendorId, params);
                 credentialCache.set(cacheKey, hasCredentials);
             }
-            // Get vendor entity from AIEngine cache if vendorId is available
-            let vendorEntity;
-            if (candidate.vendorId) {
-                vendorEntity = AIEngine.Instance.Vendors.find(v => UUIDsEqual(v.ID, candidate.vendorId));
-            }
             // Track this model as considered with availability status
-            consideredModels.push({
+            const considered = {
                 model: candidate.model,
                 vendor: vendorEntity,
                 priority: candidate.priority,
                 available: hasCredentials,
                 unavailableReason: hasCredentials ? undefined : `No credentials configured for driver ${candidate.driverClass}`
-            });
+            };
+            consideredModels.push(considered);
+            // Record the first available candidate as the selection (highest priority with credentials)
+            if (hasCredentials && !selected) {
+                selected = considered;
+            }
         }
-        // Select the first available candidate (highest priority with API key)
-        const selected = consideredModels.find(m => m.available);
         const selectedCandidate = selected ? candidates.find(c => UUIDsEqual(c.model.ID, selected.model.ID) &&
             UUIDsEqual(c.vendorId, selected.vendor?.ID)) : null;
         if (selectedCandidate) {
@@ -1961,7 +1981,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.
@@ -1990,6 +2010,75 @@ export class AIPromptRunner {
     /**
      * Creates an AIPromptRun entity for execution tracking
      */
+    /**
+     * Resolves the scalar inference parameters for a run: each value is the per-request override
+     * from `additionalParameters` when supplied, otherwise the prompt's configured default. This
+     * is the single source of truth for parameter precedence so {@link executeModel} (ChatParams)
+     * and {@link createPromptRun} (the persisted record) stay in lockstep. Stop sequences and
+     * assistant prefill are intentionally excluded — their representations differ per target.
+     */
+    resolveScalarInferenceParams(prompt, additionalParameters) {
+        const pick = (override, promptDefault) => override !== undefined ? override : (promptDefault != null ? promptDefault : undefined);
+        const ap = additionalParameters;
+        return {
+            temperature: pick(ap?.temperature, prompt.Temperature),
+            topP: pick(ap?.topP, prompt.TopP),
+            topK: pick(ap?.topK, prompt.TopK),
+            minP: pick(ap?.minP, prompt.MinP),
+            frequencyPenalty: pick(ap?.frequencyPenalty, prompt.FrequencyPenalty),
+            presencePenalty: pick(ap?.presencePenalty, prompt.PresencePenalty),
+            seed: pick(ap?.seed, prompt.Seed),
+            includeLogProbs: pick(ap?.includeLogProbs, prompt.IncludeLogProbs),
+            topLogProbs: pick(ap?.topLogProbs, prompt.TopLogProbs),
+        };
+    }
+    /**
+     * 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.
+     */
+    async WaitForPendingPromptRunSaves() {
+        await Promise.allSettled(this._pendingPromptRunSaves);
+    }
     async createPromptRun(prompt, model, params, systemPromptText, startTime, vendorId, modelSelectionInfo) {
         const provider = params.provider ?? Metadata.Provider;
         const promptRun = await provider.GetEntityObject('MJ: AI Prompt Runs', params.contextUser);
@@ -2005,7 +2094,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) {
@@ -2058,8 +2147,8 @@ export class AIPromptRunner {
             }
             else {
                 // Fallback: grab the highest priority AI Model Vendor record for this model (inference providers only)
-                const modelVendors = AIEngine.Instance.ModelVendors
-                    .filter((mv) => UUIDsEqual(mv.ModelID, model.ID) && mv.Status === 'Active' && this.isInferenceProvider(mv))
+                const modelVendors = model.ModelVendors
+                    .filter((mv) => mv.Status === 'Active' && this.isInferenceProvider(mv))
                     .sort((a, b) => b.Priority - a.Priority);
                 if (modelVendors.length > 0) {
                     promptRun.VendorID = modelVendors[0].VendorID;
@@ -2091,62 +2180,35 @@ export class AIPromptRunner {
             if (prompt.ResponseFormat && prompt.ResponseFormat !== 'Any') {
                 promptRun.ResponseFormat = prompt.ResponseFormat;
             }
-            // Save the actual values that will be used (either from prompt defaults or additionalParameters)
-            // First, apply defaults from prompt entity 
-            if (prompt.Temperature != null)
-                promptRun.Temperature = prompt.Temperature;
-            if (prompt.TopP != null)
-                promptRun.TopP = prompt.TopP;
-            if (prompt.TopK != null)
-                promptRun.TopK = prompt.TopK;
-            if (prompt.MinP != null)
-                promptRun.MinP = prompt.MinP;
-            if (prompt.FrequencyPenalty != null)
-                promptRun.FrequencyPenalty = prompt.FrequencyPenalty;
-            if (prompt.PresencePenalty != null)
-                promptRun.PresencePenalty = prompt.PresencePenalty;
-            if (prompt.Seed != null)
-                promptRun.Seed = prompt.Seed;
+            // Save the actual values that will be used (prompt defaults overridden by additionalParameters).
+            // Uses the shared resolver so the persisted record matches what executeModel sends to the model.
+            const resolvedParams = this.resolveScalarInferenceParams(prompt, params.additionalParameters);
+            if (resolvedParams.temperature !== undefined)
+                promptRun.Temperature = resolvedParams.temperature;
+            if (resolvedParams.topP !== undefined)
+                promptRun.TopP = resolvedParams.topP;
+            if (resolvedParams.topK !== undefined)
+                promptRun.TopK = resolvedParams.topK;
+            if (resolvedParams.minP !== undefined)
+                promptRun.MinP = resolvedParams.minP;
+            if (resolvedParams.frequencyPenalty !== undefined)
+                promptRun.FrequencyPenalty = resolvedParams.frequencyPenalty;
+            if (resolvedParams.presencePenalty !== undefined)
+                promptRun.PresencePenalty = resolvedParams.presencePenalty;
+            if (resolvedParams.seed !== undefined)
+                promptRun.Seed = resolvedParams.seed;
+            if (resolvedParams.includeLogProbs !== undefined)
+                promptRun.LogProbs = resolvedParams.includeLogProbs;
+            if (resolvedParams.topLogProbs !== undefined)
+                promptRun.TopLogProbs = resolvedParams.topLogProbs;
+            // Stop sequences + assistant prefill: stored from the prompt, with the additionalParameters
+            // array (JSON-encoded) taking precedence when supplied.
             if (prompt.StopSequences)
                 promptRun.StopSequences = prompt.StopSequences;
             if (prompt.AssistantPrefill)
                 promptRun.AssistantPrefill = prompt.AssistantPrefill;
-            if (prompt.IncludeLogProbs != null)
-                promptRun.LogProbs = prompt.IncludeLogProbs;
-            if (prompt.TopLogProbs != null)
-                promptRun.TopLogProbs = prompt.TopLogProbs;
-            // Then override with additionalParameters if provided
-            if (params.additionalParameters) {
-                if (params.additionalParameters.temperature !== undefined) {
-                    promptRun.Temperature = params.additionalParameters.temperature;
-                }
-                if (params.additionalParameters.topP !== undefined) {
-                    promptRun.TopP = params.additionalParameters.topP;
-                }
-                if (params.additionalParameters.topK !== undefined) {
-                    promptRun.TopK = params.additionalParameters.topK;
-                }
-                if (params.additionalParameters.minP !== undefined) {
-                    promptRun.MinP = params.additionalParameters.minP;
-                }
-                if (params.additionalParameters.frequencyPenalty !== undefined) {
-                    promptRun.FrequencyPenalty = params.additionalParameters.frequencyPenalty;
-                }
-                if (params.additionalParameters.presencePenalty !== undefined) {
-                    promptRun.PresencePenalty = params.additionalParameters.presencePenalty;
-                }
-                if (params.additionalParameters.seed !== undefined) {
-                    promptRun.Seed = params.additionalParameters.seed;
-                }
-                if (params.additionalParameters.stopSequences !== undefined && params.additionalParameters.stopSequences.length > 0) {
-                    promptRun.StopSequences = JSON.stringify(params.additionalParameters.stopSequences);
-                }
-                if (params.additionalParameters.includeLogProbs !== undefined) {
-                    promptRun.LogProbs = params.additionalParameters.includeLogProbs;
-                }
-                if (params.additionalParameters.topLogProbs !== undefined) {
-                    promptRun.TopLogProbs = params.additionalParameters.topLogProbs;
-                }
+            if (params.additionalParameters?.stopSequences !== undefined && params.additionalParameters.stopSequences.length > 0) {
+                promptRun.StopSequences = JSON.stringify(params.additionalParameters.stopSequences);
             }
             // Store the input data/context as JSON in Messages field
             if (params.data || params.templateData || systemPromptText) {
@@ -2179,21 +2241,13 @@ export class AIPromptRunner {
             promptRun.ValidationAttemptCount = 0; // Will be updated during execution
             promptRun.SuccessfulValidationCount = 0;
             promptRun.FinalValidationPassed = false; // Will be updated after execution
-            const saveResult = await promptRun.Save();
-            if (!saveResult) {
-                const error = `Failed to save AIPromptRun: ${promptRun.LatestResult?.CompleteMessage || 'Unknown error'}`;
-                this.logError(error, {
-                    category: 'PromptRunCreation',
-                    metadata: {
-                        promptId: prompt.ID,
-                        modelId: model.ID,
-                        vendorId
-                    },
-                    maxErrorLength: params.maxErrorLength
-                });
-                throw new Error(error);
-            }
-            // Invoke callback if provided
+            // Persist the initial 'Running' record fire-and-forget. The ID was already assigned by
+            // 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);
+            // 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) {
                 try {
                     await params.onPromptRunCreated(promptRun.ID);
@@ -2283,7 +2337,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
@@ -2293,10 +2347,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) {
@@ -2365,6 +2454,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);
     }
     /**
@@ -2500,7 +2594,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
@@ -2530,7 +2628,7 @@ export class AIPromptRunner {
                 supportsEffortLevel = model.SupportsEffortLevel ?? false;
                 if (vendorId) {
                     // Find the AIModelVendor record for this specific vendor - must be an inference provider
-                    const modelVendor = AIEngine.Instance.ModelVendors.find((mv) => UUIDsEqual(mv.ModelID, model.ID) && UUIDsEqual(mv.VendorID, vendorId) && mv.Status === 'Active' && this.isInferenceProvider(mv));
+                    const modelVendor = model.ModelVendors.find((mv) => UUIDsEqual(mv.VendorID, vendorId) && mv.Status === 'Active' && this.isInferenceProvider(mv));
                     if (modelVendor) {
                         driverClass = modelVendor.DriverClass || driverClass;
                         apiName = modelVendor.APIName || apiName;
@@ -2554,63 +2652,34 @@ export class AIPromptRunner {
             }
             chatParams.model = apiName;
             chatParams.cancellationToken = cancellationToken;
-            // Apply defaults from prompt entity first (if they exist)
-            // These can be overridden by additionalParameters
-            if (prompt.Temperature != null)
-                chatParams.temperature = prompt.Temperature;
-            if (prompt.TopP != null)
-                chatParams.topP = prompt.TopP;
-            if (prompt.TopK != null)
-                chatParams.topK = prompt.TopK;
-            if (prompt.MinP != null)
-                chatParams.minP = prompt.MinP;
-            if (prompt.FrequencyPenalty != null)
-                chatParams.frequencyPenalty = prompt.FrequencyPenalty;
-            if (prompt.PresencePenalty != null)
-                chatParams.presencePenalty = prompt.PresencePenalty;
-            if (prompt.Seed != null)
-                chatParams.seed = prompt.Seed;
+            // Apply scalar inference params (prompt defaults overridden by additionalParameters) via the
+            // shared resolver so ChatParams and the persisted AIPromptRun never drift.
+            const resolvedParams = this.resolveScalarInferenceParams(prompt, params.additionalParameters);
+            if (resolvedParams.temperature !== undefined)
+                chatParams.temperature = resolvedParams.temperature;
+            if (resolvedParams.topP !== undefined)
+                chatParams.topP = resolvedParams.topP;
+            if (resolvedParams.topK !== undefined)
+                chatParams.topK = resolvedParams.topK;
+            if (resolvedParams.minP !== undefined)
+                chatParams.minP = resolvedParams.minP;
+            if (resolvedParams.frequencyPenalty !== undefined)
+                chatParams.frequencyPenalty = resolvedParams.frequencyPenalty;
+            if (resolvedParams.presencePenalty !== undefined)
+                chatParams.presencePenalty = resolvedParams.presencePenalty;
+            if (resolvedParams.seed !== undefined)
+                chatParams.seed = resolvedParams.seed;
+            if (resolvedParams.includeLogProbs !== undefined)
+                chatParams.includeLogProbs = resolvedParams.includeLogProbs;
+            if (resolvedParams.topLogProbs !== undefined)
+                chatParams.topLogProbs = resolvedParams.topLogProbs;
+            // Stop sequences are handled separately: the prompt value is comma-delimited and gated by
+            // driver support; additionalParameters supplies a ready-made array that overrides it.
             if (prompt.StopSequences && this.shouldApplyStopSequences(prompt, model, vendorId, llm)) {
-                // Parse comma-delimited stop sequences
                 chatParams.stopSequences = prompt.StopSequences.split(',').map((s) => s.replace(AIPromptRunner.STOP_SEQUENCE_TRIM_REGEX, '')).filter((s) => s.length > 0);
             }
-            if (prompt.IncludeLogProbs != null)
-                chatParams.includeLogProbs = prompt.IncludeLogProbs;
-            if (prompt.TopLogProbs != null)
-                chatParams.topLogProbs = prompt.TopLogProbs;
-            // Apply additional parameters if provided (these override prompt defaults)
-            if (params.additionalParameters) {
-                // Apply chat-specific parameters from additionalParameters
-                if (params.additionalParameters.temperature !== undefined) {
-                    chatParams.temperature = params.additionalParameters.temperature;
-                }
-                if (params.additionalParameters.topP !== undefined) {
-                    chatParams.topP = params.additionalParameters.topP;
-                }
-                if (params.additionalParameters.topK !== undefined) {
-                    chatParams.topK = params.additionalParameters.topK;
-                }
-                if (params.additionalParameters.minP !== undefined) {
-                    chatParams.minP = params.additionalParameters.minP;
-                }
-                if (params.additionalParameters.frequencyPenalty !== undefined) {
-                    chatParams.frequencyPenalty = params.additionalParameters.frequencyPenalty;
-                }
-                if (params.additionalParameters.presencePenalty !== undefined) {
-                    chatParams.presencePenalty = params.additionalParameters.presencePenalty;
-                }
-                if (params.additionalParameters.seed !== undefined) {
-                    chatParams.seed = params.additionalParameters.seed;
-                }
-                if (params.additionalParameters.stopSequences !== undefined) {
-                    chatParams.stopSequences = params.additionalParameters.stopSequences;
-                }
-                if (params.additionalParameters.includeLogProbs !== undefined) {
-                    chatParams.includeLogProbs = params.additionalParameters.includeLogProbs;
-                }
-                if (params.additionalParameters.topLogProbs !== undefined) {
-                    chatParams.topLogProbs = params.additionalParameters.topLogProbs;
-                }
+            if (params.additionalParameters?.stopSequences !== undefined) {
+                chatParams.stopSequences = params.additionalParameters.stopSequences;
             }
             // Apply effortLevel with precedence hierarchy
             // 1. params.effortLevel (runtime override - highest priority)
@@ -2671,6 +2740,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
@@ -2819,8 +2899,13 @@ export class AIPromptRunner {
         const lower = mimeType.toLowerCase();
         return caps.SupportedMimeTypes.some((pattern) => {
             const p = pattern.toLowerCase();
+            // Wildcard on EITHER side must match (the requested mime is often a modality
+            // probe like 'image/*' — e.g. an image_url block with no explicit mimeType —
+            // and must match a driver that declares any concrete 'image/<x>' type).
             if (p.endsWith('/*'))
                 return lower.startsWith(p.slice(0, -1));
+            if (lower.endsWith('/*'))
+                return p.startsWith(lower.slice(0, -1));
             return lower === p;
         });
     }
@@ -2976,7 +3061,7 @@ export class AIPromptRunner {
         }
         // Vendor-level override (null = inherit)
         if (vendorId) {
-            const modelVendor = AIEngine.Instance.ModelVendors.find(mv => UUIDsEqual(mv.ModelID, model.ID) && UUIDsEqual(mv.VendorID, vendorId) && mv.Status === 'Active');
+            const modelVendor = model.ModelVendors.find(mv => UUIDsEqual(mv.VendorID, vendorId) && mv.Status === 'Active');
             if (modelVendor?.SupportsPrefill != null) {
                 supportsPrefill = modelVendor.SupportsPrefill;
             }
@@ -2990,7 +3075,7 @@ export class AIPromptRunner {
      */
     resolvePrefillFallbackText(model, vendorId) {
         // Start with model type default
-        const modelType = AIEngine.Instance.ModelTypes.find(mt => UUIDsEqual(mt.ID, model.AIModelTypeID));
+        const modelType = AIEngine.Instance.ModelTypesByID.get(NormalizeUUID(model.AIModelTypeID));
         let fallbackText = modelType?.PrefillFallbackText ?? null;
         // Model-level override
         if (model.PrefillFallbackText != null) {
@@ -2998,7 +3083,7 @@ export class AIPromptRunner {
         }
         // Vendor-level override
         if (vendorId) {
-            const modelVendor = AIEngine.Instance.ModelVendors.find(mv => UUIDsEqual(mv.ModelID, model.ID) && UUIDsEqual(mv.VendorID, vendorId) && mv.Status === 'Active');
+            const modelVendor = model.ModelVendors.find(mv => UUIDsEqual(mv.VendorID, vendorId) && mv.Status === 'Active');
             if (modelVendor?.PrefillFallbackText != null) {
                 fallbackText = modelVendor.PrefillFallbackText;
             }
@@ -3045,7 +3130,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;
@@ -3065,7 +3150,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') {
@@ -3230,7 +3316,7 @@ export class AIPromptRunner {
         const filteredCandidates = allCandidates.filter(c => (c.vendorId || 'default') !== failedVendorId);
         const removedCount = beforeCount - filteredCandidates.length;
         if (removedCount > 0) {
-            const vendorName = AIEngine.Instance.Vendors.find(v => UUIDsEqual(v.ID, failedVendorId))?.Name || failedVendorId;
+            const vendorName = AIEngine.Instance.VendorsByID.get(NormalizeUUID(failedVendorId))?.Name || failedVendorId;
             const remainingCount = filteredCandidates.length;
             // Log appropriate message based on error type
             let reason;
@@ -3271,7 +3357,7 @@ export class AIPromptRunner {
         if (shouldRetry) {
             const modelName = currentModel.Name;
             const vendorName = currentVendorId
-                ? AIEngine.Instance.Vendors.find(v => UUIDsEqual(v.ID, currentVendorId))?.Name || 'default'
+                ? AIEngine.Instance.VendorsByID.get(NormalizeUUID(currentVendorId))?.Name || 'default'
                 : 'default';
             this.logStatus(`   ⏳ Rate limit hit - retrying ${modelName} (${vendorName}) with backoff (attempt ${rateLimitRetryCount}/${maxRetries})`, true);
             this.logFailoverAttempt(prompt.ID, failoverAttempt, true);
@@ -3746,28 +3832,28 @@ export class AIPromptRunner {
                 jsonToParse = CleanJSON(rawOutput);
             }
             catch (cleanError) {
-                if (params.verbose) {
-                    this.logError(cleanError, {
-                        category: 'JSONCleaningFailed',
-                        metadata: {
-                            originalError: originalError.message,
-                            rawOutput: rawOutput.substring(0, 500)
-                        },
-                        maxErrorLength: params.maxErrorLength
-                    });
-                }
+                this.logError(cleanError, {
+                    category: 'JSONCleaningFailed',
+                    metadata: {
+                        originalError: originalError.message,
+                        rawOutput: rawOutput.substring(0, 500)
+                    },
+                    maxErrorLength: params.maxErrorLength
+                });
             }
             const json5Result = JSON5.parse(jsonToParse);
-            if (params.verbose) {
-                this.logStatus('   ✅ JSON5 successfully parsed the malformed JSON', true, params);
-            }
+            this.logStatus('   ✅ JSON5 successfully parsed the malformed JSON', true, params);
+            currentPromptRun._jsonRepairInfo = {
+                repaired: true,
+                method: 'JSON5',
+                originalError: originalError.message,
+                rawOutputPrefix: rawOutput.substring(0, 200)
+            };
             return json5Result;
         }
         catch (json5Error) {
             // Step 2: Use AI to repair the JSON
-            if (params.verbose) {
-                this.logStatus('   🤖 JSON5 failed, attempting AI-based JSON repair...', true, params);
-            }
+            this.logStatus('   🤖 JSON5 failed, attempting AI-based JSON repair...', true, params);
             try {
                 // Find the "Repair JSON" prompt in the "MJ: System" category
                 const repairPrompt = AIEngine.Instance.Prompts.find(p => p.Name.trim().toLowerCase() === 'repair json' && p.Category.trim().toLowerCase() === 'mj: system');
@@ -3797,39 +3883,61 @@ export class AIPromptRunner {
                 }
                 // if we get here, we successfully repaired the JSON!!!
                 this.logStatus('   ✅ AI successfully repaired the JSON', true, params);
+                currentPromptRun._jsonRepairInfo = {
+                    repaired: true,
+                    method: 'AIRepair',
+                    originalError: originalError.message,
+                    rawOutputPrefix: rawOutput.substring(0, 200),
+                    repairPromptRunId: repairResult.promptRun?.ID
+                };
                 return repairedJSON;
             }
             catch (aiRepairError) {
-                // Both repair attempts failed
-                if (params.verbose) {
-                    this.logError(aiRepairError, {
-                        category: 'JSONRepairFailed',
-                        metadata: {
-                            originalError: originalError.message,
-                            json5Error: json5Error.message,
-                            aiError: aiRepairError.message,
-                            rawOutput: rawOutput.substring(0, 500)
-                        },
-                        maxErrorLength: params.maxErrorLength
-                    });
-                }
+                // Both repair attempts failed — always log, this is unexpected LLM behavior
+                this.logError(aiRepairError, {
+                    category: 'JSONRepairFailed',
+                    metadata: {
+                        originalError: originalError.message,
+                        json5Error: json5Error.message,
+                        aiError: aiRepairError.message,
+                        rawOutput: rawOutput.substring(0, 500)
+                    },
+                    maxErrorLength: params.maxErrorLength
+                });
                 throw new Error(`JSON repair failed after both JSON5 and AI attempts: ${originalError.message}`);
             }
         }
     }
+    /**
+     * Returns the parsed form of a prompt's `OutputExample` JSON, memoized by content.
+     * Parsing happens at most once per distinct example string for the life of the process;
+     * parse failures are cached too (so malformed examples aren't re-parsed every attempt).
+     */
+    getParsedOutputExample(outputExample) {
+        const cached = AIPromptRunner._outputExampleCache.get(outputExample);
+        if (cached) {
+            return cached;
+        }
+        let entry;
+        try {
+            entry = { parsed: JSON.parse(outputExample) };
+        }
+        catch (parseError) {
+            entry = { error: parseError instanceof Error ? parseError.message : String(parseError) };
+        }
+        AIPromptRunner._outputExampleCache.set(outputExample, entry);
+        return entry;
+    }
     /**
      * Validates parsed result against JSON schema derived from OutputExample
      */
     async validateAgainstSchema(parsedResult, outputExample, promptId) {
         const validationErrors = [];
         try {
-            // Parse the output example
-            let exampleObject;
-            try {
-                exampleObject = JSON.parse(outputExample);
-            }
-            catch (parseError) {
-                const error = new ValidationErrorInfo('outputExample', `Invalid OutputExample JSON: ${parseError.message}`, outputExample, ValidationErrorType.Failure);
+            // Parse the output example (cached by content — it's a static string reused across runs/retries)
+            const { parsed: exampleObject, error: exampleParseError } = this.getParsedOutputExample(outputExample);
+            if (exampleParseError) {
+                const error = new ValidationErrorInfo('outputExample', `Invalid OutputExample JSON: ${exampleParseError}`, outputExample, ValidationErrorType.Failure);
                 validationErrors.push(error);
                 return validationErrors;
             }
@@ -3915,6 +4023,12 @@ export class AIPromptRunner {
      */
     async updatePromptRun(promptRun, prompt, modelResult, parsedResult, endTime, executionTimeMS, validationAttempts, cumulativeTokens) {
         try {
+            // Ensure the initial 'Running' INSERT (and its BaseEntity.finalizeSave post-save reload, which does
+            // init() + SetMany(insertedRow)) has fully landed BEFORE we mutate the final state. Mutating while the
+            // INSERT is still in flight lets the reload revert these values, and the chained UPDATE then persists
+            // the stale 'Running' row (the same race fixed in the agent-run-step queue and action-execution-log).
+            // The model call between create and update almost always covers this; a fast-failing prompt could not.
+            await this._promptRunSaveChains.get(promptRun);
             promptRun.CompletedAt = endTime;
             promptRun.ExecutionTimeMS = executionTimeMS;
             // Determine what to save as the result
@@ -4058,7 +4172,8 @@ export class AIPromptRunner {
                         type: e.Type,
                         value: e.Value
                     })) || [],
-                    validationDecision: this.getValidationDecisionDescription(parsedResult.validationResult?.Success || false, validationAttempts.length, promptRun.ValidationBehavior || 'Warn')
+                    validationDecision: this.getValidationDecisionDescription(parsedResult.validationResult?.Success || false, validationAttempts.length, promptRun.ValidationBehavior || 'Warn'),
+                    jsonRepairInfo: promptRun._jsonRepairInfo || null
                 });
             }
             else {
@@ -4068,6 +4183,12 @@ export class AIPromptRunner {
                 promptRun.FinalValidationPassed = parsedResult.validationResult?.Success !== false;
                 promptRun.LastAttemptAt = endTime;
                 promptRun.TotalRetryDurationMS = 0;
+                // Even without validation, persist JSON repair info if a repair occurred
+                if (promptRun._jsonRepairInfo) {
+                    promptRun.ValidationSummary = JSON.stringify({
+                        jsonRepairInfo: promptRun._jsonRepairInfo
+                    });
+                }
             }
             // Set Success flag based on validation result
             promptRun.Success = modelResult.success && (parsedResult.validationResult?.Success !== false);
@@ -4093,28 +4214,10 @@ export class AIPromptRunner {
             if (promptRun.Cost !== undefined) {
                 promptRun.TotalCost = promptRun.Cost;
             }
-            const saveResult = await promptRun.Save();
-            if (!saveResult) {
-                // Safely extract error message using CompleteMessage getter
-                let errorMsg = 'Unknown error';
-                try {
-                    if (promptRun.LatestResult?.CompleteMessage) {
-                        errorMsg = typeof promptRun.LatestResult.CompleteMessage === 'string'
-                            ? promptRun.LatestResult.CompleteMessage
-                            : String(promptRun.LatestResult.CompleteMessage);
-                    }
-                }
-                catch (msgError) {
-                    errorMsg = 'Error accessing error message';
-                }
-                this.logError(`Failed to update AIPromptRun with results: ${errorMsg}`, {
-                    category: 'PromptRunUpdate',
-                    metadata: {
-                        promptRunId: promptRun.ID,
-                        updateError: errorMsg
-                    }
-                });
-            }
+            // 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, {