@juspay/neurolink 12.56.0 → 12.56.1

package/dist/utils/providerHealth.d.ts

@@ -1,7 +1,3 @@
-/**
- * Provider Health Checking System
- * Prevents 500 errors by validating provider availability and configuration
- */
 import { AIProviderName } from "../constants/enums.js";
 import type { ProviderHealthCheckOptions, ProviderHealthStatusOptions } from "../types/index.js";
 export declare class ProviderHealthChecker {
@@ -9,20 +5,16 @@ export declare class ProviderHealthChecker {
     private static readonly DEFAULT_TIMEOUT;
     private static readonly DEFAULT_CACHE_AGE;
     /**
-     * Fixed backoff window for the circuit breaker below, in milliseconds.
-     * Deliberately NOT the per-call `maxCacheAge` option: `consecutiveFailures`
-     * is a single process-wide map keyed only by provider name, shared by every
-     * caller (e.g. `checkFallbackProviderAvailability` hard-codes a 15s
-     * `maxCacheAge` for its own health-status cache). Evicting the breaker
-     * entry using whichever caller happens to read it next would let a
-     * short-TTL caller silently erase a backoff another caller is relying on
-     * — see `checkProviderHealth`. This constant governs breaker expiry alone
-     * and is intentionally independent of `maxCacheAge`/`DEFAULT_CACHE_AGE`.
+     * Fixed backoff for the existing non-Ollama provider breaker. Ollama uses
+     * the same fixed window in ollamaDiagnostics, shared by every native caller.
+     * Neither window depends on a caller's maxCacheAge: expiring a health cache
+     * must not silently erase a transport backoff owned by another caller.
      */
     private static readonly CIRCUIT_BREAKER_RESET_MS;
     private static readonly CONSECUTIVE_FAILURE_THRESHOLD;
     /**
-     * Circuit breaker state, keyed by provider.
+     * Non-Ollama circuit breaker state, keyed by provider. Ollama's separate
+     * native policy captures the actual endpoint and records aggregate outcomes.
      *
      * `count` is a count of consecutive failed CONNECTIVITY PROBES (plus the
      * rare case of the check itself throwing) — never of "the provider is
@@ -56,11 +48,14 @@ export declare class ProviderHealthChecker {
      */
     private static readonly MAX_CONCURRENT_HEALTH_CHECKS;
     /**
-     * Validate and return a safe failure threshold value
+     * Preserve the validated threshold's original first-use initialization.
      */
     private static getValidatedFailureThreshold;
     /**
-     * Comprehensive health check for a provider
+     * Check configuration and optional connectivity/model availability.
+     * Ollama captures its endpoint/model once and records only probes that run;
+     * a cache hit or missing configured model does not invent a transport failure.
+     * Its cached result must match the current diagnostic revision/generation.
      */
     static checkProviderHealth(providerName: AIProviderName, options?: ProviderHealthCheckOptions): Promise<ProviderHealthStatusOptions>;
     /**
@@ -189,18 +184,33 @@ export declare class ProviderHealthChecker {
     private static getLiteLLMModelsUrl;
     private static getConfiguredLiteLLMModel;
     private static getOllamaBaseUrl;
+    /** Resolve the shared native tags URL rather than the compatible models URL. */
     private static getOllamaTagsUrl;
     private static getConfiguredOllamaModel;
     private static fetchJsonWithTimeout;
     private static normalizeModelList;
     private static hasRequestedModel;
+    /**
+     * Fetch native tags from the captured endpoint and normalize its models.
+     * A malformed envelope rejects; a valid empty list remains an empty result.
+     */
     private static getOllamaAvailableModels;
     private static getLiteLLMAvailableModels;
+    /**
+     * Check a requested model against native tags while keeping diagnostic outcome
+     * separate from model availability. An answered valid list is diagnostic
+     * success even if that model is absent; malformed JSON/envelopes are protocol
+     * failures. A caller recording an aggregate health probe disables recording
+     * here so its admitted permit is completed only once at the outer boundary.
+     */
     private static checkOllamaAvailability;
     private static checkLiteLLMAvailability;
     private static checkLiteLLMConfig;
     /**
-     * Check Ollama configuration
+     * Report Ollama configuration and model availability using the captured context.
+     * Backoff can suppress native work; a missing installed model is a configuration
+     * issue after a successful probe. Return actual probe activity/failure for the
+     * enclosing health check to record, without completing a second policy permit.
      */
     private static checkOllamaConfig;
     /**
@@ -208,7 +218,9 @@ export declare class ProviderHealthChecker {
      */
     private static getCommonModelsForProvider;
     /**
-     * Get cached health status if still valid
+     * Return health within the caller's TTL and, for Ollama, the captured identity.
+     * Ollama revision/generation changes invalidate cached status; reading the
+     * snapshot may apply timed expiry but never records a probe outcome.
      */
     private static getCachedHealth;
     /**
@@ -267,7 +279,9 @@ export declare class ProviderHealthChecker {
      */
     static initializeBackgroundHealthChecks(): void;
     /**
-     * Clear health cache for a provider or all providers
+     * Clear cached health and failure state for one provider or every provider.
+     * Clearing Ollama removes all endpoint/model cache entries and explicitly
+     * advances diagnostic generation so older in-flight permits cannot commit.
      */
     static clearHealthCache(providerName?: AIProviderName): void;
     static checkFallbackProviderAvailability(providerName: string, model: string): Promise<{

package/dist/utils/providerHealth.js

@@ -1,7 +1,8 @@
 /**
- * Provider Health Checking System
- * Prevents 500 errors by validating provider availability and configuration
+ * Provider health checking with captured native diagnostics for Ollama.
+ * Configuration/model availability and transport failures remain separate.
  */
+import { beginOllamaDiagnostic, captureOllamaDiagnosticContext, clearOllamaDiagnostics, completeOllamaDiagnostic, getOllamaDiagnosticErrorMessage, getOllamaDiagnosticSnapshot, getOllamaHealthCacheKey, getValidatedProviderFailureThreshold, OllamaProtocolError, readOllamaTagsModels, resolveOllamaNativeTagsUrl, } from "./ollamaDiagnostics.js";
 import { logger } from "./logger.js";
 import { AIProviderName, OpenAIModels, GoogleAIModels, AnthropicModels, BedrockModels, } from "../constants/enums.js";
 import { PROJECT_ID_FORMAT, satisfiesFallbacks } from "./providerConfig.js";
@@ -15,20 +16,16 @@ export class ProviderHealthChecker {
     static DEFAULT_TIMEOUT = 5000; // 5 seconds
     static DEFAULT_CACHE_AGE = 300000; // 5 minutes
     /**
-     * Fixed backoff window for the circuit breaker below, in milliseconds.
-     * Deliberately NOT the per-call `maxCacheAge` option: `consecutiveFailures`
-     * is a single process-wide map keyed only by provider name, shared by every
-     * caller (e.g. `checkFallbackProviderAvailability` hard-codes a 15s
-     * `maxCacheAge` for its own health-status cache). Evicting the breaker
-     * entry using whichever caller happens to read it next would let a
-     * short-TTL caller silently erase a backoff another caller is relying on
-     * — see `checkProviderHealth`. This constant governs breaker expiry alone
-     * and is intentionally independent of `maxCacheAge`/`DEFAULT_CACHE_AGE`.
+     * Fixed backoff for the existing non-Ollama provider breaker. Ollama uses
+     * the same fixed window in ollamaDiagnostics, shared by every native caller.
+     * Neither window depends on a caller's maxCacheAge: expiring a health cache
+     * must not silently erase a transport backoff owned by another caller.
      */
     static CIRCUIT_BREAKER_RESET_MS = 300000; // 5 minutes
     static CONSECUTIVE_FAILURE_THRESHOLD = ProviderHealthChecker.getValidatedFailureThreshold();
     /**
-     * Circuit breaker state, keyed by provider.
+     * Non-Ollama circuit breaker state, keyed by provider. Ollama's separate
+     * native policy captures the actual endpoint and records aggregate outcomes.
      *
      * `count` is a count of consecutive failed CONNECTIVITY PROBES (plus the
      * rare case of the check itself throwing) — never of "the provider is
@@ -62,28 +59,35 @@ export class ProviderHealthChecker {
      */
     static MAX_CONCURRENT_HEALTH_CHECKS = 8;
     /**
-     * Validate and return a safe failure threshold value
+     * Preserve the validated threshold's original first-use initialization.
      */
     static getValidatedFailureThreshold() {
-        const envValue = process.env.PROVIDER_FAILURE_THRESHOLD;
-        if (!envValue) {
-            return 3; // default
-        }
-        const parsed = Number(envValue);
-        if (isNaN(parsed) || parsed <= 0 || parsed > 10) {
-            logger.warn(`Invalid PROVIDER_FAILURE_THRESHOLD: ${envValue} (must be between 1 and 10), using default: 3`);
-            return 3;
-        }
-        return parsed;
+        return getValidatedProviderFailureThreshold();
     }
     /**
-     * Comprehensive health check for a provider
+     * Check configuration and optional connectivity/model availability.
+     * Ollama captures its endpoint/model once and records only probes that run;
+     * a cache hit or missing configured model does not invent a transport failure.
+     * Its cached result must match the current diagnostic revision/generation.
      */
     static async checkProviderHealth(providerName, options = {}) {
         const { timeout = this.DEFAULT_TIMEOUT, includeConnectivityTest = false, includeModelValidation = false, cacheResults = true, maxCacheAge = this.DEFAULT_CACHE_AGE, } = options;
-        // Check cache first
-        if (cacheResults) {
-            const cached = this.getCachedHealth(providerName, maxCacheAge);
+        const isOllama = providerName === AIProviderName.OLLAMA;
+        let ollamaContext;
+        if (isOllama) {
+            try {
+                ollamaContext = captureOllamaDiagnosticContext();
+            }
+            catch {
+                // The local configuration path below reports the invalid URL without
+                // fabricating an outbound transport failure or reusing old cached health.
+            }
+        }
+        let ollamaProbeRan = false;
+        let ollamaProbeFailed = false;
+        // Cache hits remain observations: they neither begin nor complete a probe.
+        if (cacheResults && (!isOllama || ollamaContext)) {
+            const cached = this.getCachedHealth(providerName, maxCacheAge, ollamaContext);
             if (cached) {
                 logger.debug(`Using cached health status for ${providerName}`);
                 return cached;
@@ -112,24 +116,26 @@ export class ProviderHealthChecker {
         // down, so a dead local proxy still gets backed off instead of eating a
         // full timeout on every call forever.
         //
-        // A run of failures older than CIRCUIT_BREAKER_RESET_MS is forgotten,
-        // which is what makes the "will be retried after cache TTL expires"
-        // warning below true. Nothing else could clear it, because the
-        // breaker's whole effect is to suppress the probe that would disprove
-        // it. This is deliberately the fixed CIRCUIT_BREAKER_RESET_MS window,
-        // not this call's own `maxCacheAge` — `consecutiveFailures` is a single
-        // shared map keyed only by provider name, so reusing whichever caller
-        // happens to invoke `checkProviderHealth` next (some call sites pass a
-        // much shorter `maxCacheAge` for their own unrelated caching needs)
-        // would let that caller silently evict a backoff a different caller is
-        // relying on.
+        // Ollama consults its captured endpoint policy; other providers retain
+        // their existing provider-keyed map. Both expire at the fixed reset window,
+        // independently of this caller's health-cache TTL.
         const breaker = this.consecutiveFailures.get(providerName);
-        if (breaker !== undefined &&
+        if (!isOllama &&
+            breaker !== undefined &&
             Date.now() - breaker.lastFailureAt >= this.CIRCUIT_BREAKER_RESET_MS) {
             this.consecutiveFailures.delete(providerName);
         }
-        const failureCount = this.consecutiveFailures.get(providerName)?.count ?? 0;
-        const blacklisted = failureCount >= this.CONSECUTIVE_FAILURE_THRESHOLD;
+        const ollamaGate = ollamaContext
+            ? beginOllamaDiagnostic(ollamaContext)
+            : undefined;
+        const failureCount = isOllama
+            ? ollamaContext
+                ? getOllamaDiagnosticSnapshot(ollamaContext).count
+                : 0
+            : (this.consecutiveFailures.get(providerName)?.count ?? 0);
+        const blacklisted = isOllama
+            ? ollamaGate?.kind === "suppressed"
+            : failureCount >= this.CONSECUTIVE_FAILURE_THRESHOLD;
         if (blacklisted) {
             logger.warn(`Provider ${providerName} blacklisted due to consecutive failures`, { failureCount });
         }
@@ -147,14 +153,16 @@ export class ProviderHealthChecker {
             // 1. Check environment configuration. For LiteLLM/Ollama this
             // includes a breaker-governed runtime probe — see the comment on
             // `blacklisted` above.
-            const runtimeProbe = await this.checkEnvironmentConfiguration(providerName, healthStatus, timeout, !blacklisted);
+            const runtimeProbe = await this.checkEnvironmentConfiguration(providerName, healthStatus, timeout, !blacklisted, ollamaContext);
+            ollamaProbeRan = runtimeProbe.ran;
+            ollamaProbeFailed = runtimeProbe.failed;
             // 2. Check API key validity (basic format validation)
             await this.checkApiKeyValidity(providerName, healthStatus);
             // 3. Optional: Connectivity test. Also governed by the breaker.
             const issuesBeforeProbe = healthStatus.configurationIssues.length;
             const probed = includeConnectivityTest && !blacklisted;
             if (probed) {
-                await this.checkConnectivity(providerName, healthStatus, timeout);
+                await this.checkConnectivity(providerName, healthStatus, timeout, ollamaContext);
             }
             const probeFailed = probed && healthStatus.configurationIssues.length > issuesBeforeProbe;
             // Fold the step-1 runtime probe (if this provider has one) together
@@ -164,6 +172,8 @@ export class ProviderHealthChecker {
             // requests).
             const anyProbeRan = probed || runtimeProbe.ran;
             const anyProbeFailed = probeFailed || runtimeProbe.failed;
+            ollamaProbeRan = anyProbeRan;
+            ollamaProbeFailed = anyProbeFailed;
             // 4. Optional: Model validation
             if (includeModelValidation) {
                 await this.checkModelAvailability(providerName, healthStatus);
@@ -182,7 +192,7 @@ export class ProviderHealthChecker {
                     healthStatus.configurationIssues.length === 0;
             healthStatus.responseTime = Date.now() - startTime;
             // Cache results
-            if (cacheResults) {
+            if (cacheResults && !isOllama) {
                 this.healthCache.set(providerName, {
                     status: healthStatus,
                     timestamp: Date.now(),
@@ -191,14 +201,38 @@ export class ProviderHealthChecker {
             // Only a probe that actually ran moves the breaker. A check that
             // issued no request is not evidence either way: it neither proves the
             // provider is failing nor that it has recovered.
-            if (anyProbeFailed) {
-                this.consecutiveFailures.set(providerName, {
-                    count: failureCount + 1,
-                    lastFailureAt: Date.now(),
-                });
+            if (isOllama) {
+                if (ollamaGate?.kind === "allowed") {
+                    completeOllamaDiagnostic(ollamaGate, anyProbeFailed
+                        ? "transport-failure"
+                        : anyProbeRan
+                            ? "success"
+                            : "not-run");
+                }
+                if (cacheResults && ollamaContext) {
+                    const snapshot = getOllamaDiagnosticSnapshot(ollamaContext);
+                    if (ollamaGate && snapshot.generation === ollamaGate.generation) {
+                        // Bind the FINAL recorded revision, never the pre-request revision.
+                        // Clearing also invalidates a suppressed call's pending cache write.
+                        this.healthCache.set(getOllamaHealthCacheKey(ollamaContext), {
+                            status: healthStatus,
+                            timestamp: Date.now(),
+                            ollamaRevision: snapshot.revision,
+                            ollamaGeneration: snapshot.generation,
+                        });
+                    }
+                }
             }
-            else if (anyProbeRan) {
-                this.consecutiveFailures.delete(providerName);
+            else {
+                if (anyProbeFailed) {
+                    this.consecutiveFailures.set(providerName, {
+                        count: failureCount + 1,
+                        lastFailureAt: Date.now(),
+                    });
+                }
+                else if (anyProbeRan) {
+                    this.consecutiveFailures.delete(providerName);
+                }
             }
             logger.debug(`Health check completed for ${providerName}`, {
                 isHealthy: healthStatus.isHealthy,
@@ -207,19 +241,38 @@ export class ProviderHealthChecker {
             });
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorMessage = isOllama
+                ? getOllamaDiagnosticErrorMessage(error)
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
             healthStatus.error = errorMessage;
             healthStatus.configurationIssues.push(`Health check failed: ${errorMessage}`);
             healthStatus.responseTime = Date.now() - startTime;
-            // A check that threw failed to answer at all, which is a failure in
-            // the sense the breaker is for — unlike an answered "not configured".
-            this.consecutiveFailures.set(providerName, {
-                count: failureCount + 1,
-                lastFailureAt: Date.now(),
-            });
+            // Keep legacy error accounting for other providers. Ollama records only
+            // probes that actually ran, so a local exception cannot invent an outage.
+            if (isOllama) {
+                if (ollamaGate?.kind === "allowed") {
+                    completeOllamaDiagnostic(ollamaGate, ollamaProbeFailed
+                        ? "transport-failure"
+                        : ollamaProbeRan
+                            ? "success"
+                            : "not-run");
+                }
+            }
+            else {
+                this.consecutiveFailures.set(providerName, {
+                    count: failureCount + 1,
+                    lastFailureAt: Date.now(),
+                });
+            }
             logger.warn(`Health check failed for ${providerName}`, {
                 error: errorMessage,
-                consecutiveFailures: failureCount + 1,
+                consecutiveFailures: isOllama
+                    ? ollamaContext
+                        ? getOllamaDiagnosticSnapshot(ollamaContext).count
+                        : 0
+                    : failureCount + 1,
             });
         }
         return healthStatus;
@@ -227,7 +280,7 @@ export class ProviderHealthChecker {
     /**
      * Check environment configuration for a provider
      */
-    static async checkEnvironmentConfiguration(providerName, healthStatus, timeout, allowRuntimeProbe) {
+    static async checkEnvironmentConfiguration(providerName, healthStatus, timeout, allowRuntimeProbe, ollamaContext) {
         const requiredEnvVars = this.getRequiredEnvironmentVariables(providerName);
         logger.debug(`[ProviderHealthChecker] Checking environment configuration for ${providerName}`, {
             requiredEnvVars,
@@ -258,7 +311,7 @@ export class ProviderHealthChecker {
             healthStatus.recommendations.push(`Set the following environment variables: ${missingVars.join(", ")}`);
         }
         // Provider-specific configuration checks
-        return this.checkProviderSpecificConfig(providerName, healthStatus, timeout, allowRuntimeProbe);
+        return this.checkProviderSpecificConfig(providerName, healthStatus, timeout, allowRuntimeProbe, ollamaContext);
     }
     /**
      * Check API key validity (format validation)
@@ -341,8 +394,10 @@ export class ProviderHealthChecker {
     /**
      * Check connectivity to provider endpoints
      */
-    static async checkConnectivity(providerName, healthStatus, timeout) {
-        const endpoint = this.getProviderHealthEndpoint(providerName);
+    static async checkConnectivity(providerName, healthStatus, timeout, ollamaContext) {
+        const endpoint = providerName === AIProviderName.OLLAMA
+            ? (ollamaContext?.url ?? null)
+            : this.getProviderHealthEndpoint(providerName);
         if (!endpoint) {
             healthStatus.warning = "No connectivity test available for this provider";
             return;
@@ -558,7 +613,7 @@ export class ProviderHealthChecker {
     /**
      * Provider-specific configuration checks
      */
-    static async checkProviderSpecificConfig(providerName, healthStatus, timeout, allowRuntimeProbe) {
+    static async checkProviderSpecificConfig(providerName, healthStatus, timeout, allowRuntimeProbe, ollamaContext) {
         switch (providerName) {
             case AIProviderName.VERTEX:
                 await this.checkVertexAIConfig(healthStatus);
@@ -572,7 +627,7 @@ export class ProviderHealthChecker {
             case AIProviderName.LITELLM:
                 return this.checkLiteLLMConfig(healthStatus, timeout, allowRuntimeProbe);
             case AIProviderName.OLLAMA:
-                return this.checkOllamaConfig(healthStatus, timeout, allowRuntimeProbe);
+                return this.checkOllamaConfig(healthStatus, timeout, allowRuntimeProbe, ollamaContext);
         }
         // Every other provider's config check above is local (env vars, file
         // existence) — never a network request, so there is no probe to report.
@@ -785,8 +840,9 @@ export class ProviderHealthChecker {
             process.env.OLLAMA_API_BASE ||
             "http://localhost:11434");
     }
+    /** Resolve the shared native tags URL rather than the compatible models URL. */
     static getOllamaTagsUrl() {
-        return new URL("/api/tags", this.getOllamaBaseUrl()).toString();
+        return resolveOllamaNativeTagsUrl();
     }
     static getConfiguredOllamaModel() {
         return process.env.OLLAMA_MODEL || DEFAULT_OLLAMA_MODEL;
@@ -840,11 +896,13 @@ export class ProviderHealthChecker {
                 (model.startsWith(`${normalizedRequestedModel}:`) ||
                     model.startsWith(`${normalizedRequestedModel}@`))));
     }
-    static async getOllamaAvailableModels(timeout = 2000) {
-        const payload = (await this.fetchJsonWithTimeout(this.getOllamaTagsUrl(), {
-            timeout,
-        }));
-        return this.normalizeModelList(payload.models ?? []);
+    /**
+     * Fetch native tags from the captured endpoint and normalize its models.
+     * A malformed envelope rejects; a valid empty list remains an empty result.
+     */
+    static async getOllamaAvailableModels(timeout = 2000, endpoint = this.getOllamaTagsUrl()) {
+        const payload = await this.fetchJsonWithTimeout(endpoint, { timeout });
+        return this.normalizeModelList(readOllamaTagsModels(payload));
     }
     static async getLiteLLMAvailableModels(timeout = 2000) {
         const payload = (await this.fetchJsonWithTimeout(this.getLiteLLMModelsUrl(), {
@@ -856,25 +914,69 @@ export class ProviderHealthChecker {
         }));
         return this.normalizeModelList(payload.data ?? []);
     }
+    /**
+     * Check a requested model against native tags while keeping diagnostic outcome
+     * separate from model availability. An answered valid list is diagnostic
+     * success even if that model is absent; malformed JSON/envelopes are protocol
+     * failures. A caller recording an aggregate health probe disables recording
+     * here so its admitted permit is completed only once at the outer boundary.
+     */
     static async checkOllamaAvailability(options) {
+        let context;
+        try {
+            context =
+                options.context ?? captureOllamaDiagnosticContext(options.model);
+        }
+        catch (error) {
+            return {
+                available: false,
+                reason: getOllamaDiagnosticErrorMessage(error),
+                models: [],
+                diagnosticOutcome: "configuration-failure",
+            };
+        }
+        const gate = options.recordDiagnostic === false
+            ? undefined
+            : beginOllamaDiagnostic(context);
+        if (gate?.kind === "suppressed") {
+            return {
+                available: false,
+                reason: gate.reason,
+                models: [],
+                diagnosticOutcome: "suppressed",
+            };
+        }
+        let outcome;
         try {
-            const models = await this.getOllamaAvailableModels(options.timeout);
+            const models = await this.getOllamaAvailableModels(options.timeout, context.url);
+            outcome = "success";
             if (!this.hasRequestedModel(models, options.model)) {
                 return {
                     available: false,
                     reason: `Configured Ollama model '${options.model}' is not installed`,
                     models,
+                    diagnosticOutcome: outcome,
                 };
             }
-            return { available: true, models };
+            return { available: true, models, diagnosticOutcome: outcome };
         }
         catch (error) {
+            outcome =
+                error instanceof OllamaProtocolError || error instanceof SyntaxError
+                    ? "protocol-failure"
+                    : "transport-failure";
             return {
                 available: false,
-                reason: error instanceof Error ? error.message : String(error),
+                reason: getOllamaDiagnosticErrorMessage(error),
                 models: [],
+                diagnosticOutcome: outcome,
             };
         }
+        finally {
+            if (gate?.kind === "allowed") {
+                completeOllamaDiagnostic(gate, outcome ?? "not-run");
+            }
+        }
     }
     static async checkLiteLLMAvailability(options) {
         try {
@@ -958,10 +1060,13 @@ export class ProviderHealthChecker {
         return { ran: true, failed: false };
     }
     /**
-     * Check Ollama configuration
+     * Report Ollama configuration and model availability using the captured context.
+     * Backoff can suppress native work; a missing installed model is a configuration
+     * issue after a successful probe. Return actual probe activity/failure for the
+     * enclosing health check to record, without completing a second policy permit.
      */
-    static async checkOllamaConfig(healthStatus, timeout = this.DEFAULT_TIMEOUT, allowRuntimeProbe = true) {
-        const ollamaBase = this.getOllamaBaseUrl();
+    static async checkOllamaConfig(healthStatus, timeout = this.DEFAULT_TIMEOUT, allowRuntimeProbe = true, ollamaContext) {
+        const ollamaBase = ollamaContext?.url ?? this.getOllamaBaseUrl();
         if (!ollamaBase.startsWith("http")) {
             healthStatus.isConfigured = false;
             healthStatus.configurationIssues.push("Invalid OLLAMA_BASE_URL format (OLLAMA_API_BASE is still accepted as a legacy alias)");
@@ -978,14 +1083,22 @@ export class ProviderHealthChecker {
             return { ran: false, failed: false };
         }
         const availability = await this.checkOllamaAvailability({
-            model: this.getConfiguredOllamaModel(),
+            model: ollamaContext?.model ?? this.getConfiguredOllamaModel(),
             timeout,
+            context: ollamaContext,
+            recordDiagnostic: false,
         });
         if (!availability.available) {
             healthStatus.isConfigured = false;
             healthStatus.configurationIssues.push(`Ollama runtime check failed: ${availability.reason ?? "unknown error"}`);
             healthStatus.recommendations.push("Start Ollama and install the configured model before using Ollama as a fallback provider");
-            return { ran: true, failed: true };
+            return {
+                ran: availability.diagnosticOutcome === "success" ||
+                    availability.diagnosticOutcome === "transport-failure" ||
+                    availability.diagnosticOutcome === "protocol-failure",
+                failed: availability.diagnosticOutcome === "transport-failure" ||
+                    availability.diagnosticOutcome === "protocol-failure",
+            };
         }
         healthStatus.isConfigured = true;
         return { ran: true, failed: false };
@@ -1055,16 +1168,29 @@ export class ProviderHealthChecker {
         }
     }
     /**
-     * Get cached health status if still valid
+     * Return health within the caller's TTL and, for Ollama, the captured identity.
+     * Ollama revision/generation changes invalidate cached status; reading the
+     * snapshot may apply timed expiry but never records a probe outcome.
      */
-    static getCachedHealth(providerName, maxAge) {
-        const cached = this.healthCache.get(providerName);
+    static getCachedHealth(providerName, maxAge, ollamaContext) {
+        const key = ollamaContext
+            ? getOllamaHealthCacheKey(ollamaContext)
+            : providerName;
+        const cached = this.healthCache.get(key);
         if (!cached) {
             return null;
         }
+        if (ollamaContext) {
+            const snapshot = getOllamaDiagnosticSnapshot(ollamaContext);
+            if (cached.ollamaRevision !== snapshot.revision ||
+                cached.ollamaGeneration !== snapshot.generation) {
+                this.healthCache.delete(key);
+                return null;
+            }
+        }
         const age = Date.now() - cached.timestamp;
         if (age > maxAge) {
-            this.healthCache.delete(providerName);
+            this.healthCache.delete(key);
             return null;
         }
         return cached.status;
@@ -1472,16 +1598,29 @@ export class ProviderHealthChecker {
         backgroundHealthCheck();
     }
     /**
-     * Clear health cache for a provider or all providers
+     * Clear cached health and failure state for one provider or every provider.
+     * Clearing Ollama removes all endpoint/model cache entries and explicitly
+     * advances diagnostic generation so older in-flight permits cannot commit.
      */
     static clearHealthCache(providerName) {
         if (providerName) {
-            this.healthCache.delete(providerName);
+            if (providerName === AIProviderName.OLLAMA) {
+                for (const [key, cached] of this.healthCache) {
+                    if (cached.status.provider === providerName) {
+                        this.healthCache.delete(key);
+                    }
+                }
+                clearOllamaDiagnostics();
+            }
+            else {
+                this.healthCache.delete(providerName);
+            }
             this.consecutiveFailures.delete(providerName);
         }
         else {
             this.healthCache.clear();
             this.consecutiveFailures.clear();
+            clearOllamaDiagnostics();
         }
     }
     static async checkFallbackProviderAvailability(providerName, model) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.56.0",
+  "version": "12.56.1",
   "packageManager": "pnpm@10.15.1",
   "description": "The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002/call) for routing, tool selection and context budgeting. MCP-native (4 transports), voice TTS/STT/realtime, RAG, agents, memory, compaction, 9 observability exporters. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · TypeSafe Jev and more.",
   "author": {
@@ -156,6 +156,7 @@
     "test:catalog-auth-header-style": "pnpm exec tsx test/continuous-test-suite-catalog-auth-header-style.ts",
     "test:decide-catalog-schema": "pnpm exec tsx test/continuous-test-suite-decide-catalog-schema.ts",
     "test:provider-descriptors": "pnpm exec tsx test/continuous-test-suite-provider-descriptors.ts",
+    "test:ollama-diagnostics": "pnpm exec tsx test/continuous-test-suite-ollama-diagnostics.ts",
     "test:decide-engine": "pnpm exec tsx test/continuous-test-suite-decide-engine.ts",
     "test:provider-structure": "pnpm exec tsx test/continuous-test-suite-provider-structure.ts",
     "test:model-manifests": "pnpm exec tsx test/continuous-test-suite-model-manifests.ts",
@@ -163,6 +164,7 @@
     "test:provider-fallback": "pnpm exec tsx test/continuous-test-suite-provider-fallback.ts",
     "test:provider-fallback-latency": "pnpm exec tsx test/continuous-test-suite-provider-fallback-latency.ts",
     "test:provider-wiring": "pnpm exec tsx test/continuous-test-suite-provider-wiring.ts",
+    "test:orchestrated-provider-selection": "pnpm exec tsx test/continuous-test-suite-orchestrated-provider-selection.ts",
     "test:embedding-response-validation": "pnpm exec tsx test/continuous-test-suite-embedding-response-validation.ts",
     "test:xiaomi-mimo-pilot": "pnpm exec tsx test/continuous-test-suite-xiaomi-mimo-pilot.ts",
     "test:mimo-overflow-budget": "pnpm exec tsx test/continuous-test-suite-mimo-overflow-budget.ts",