@juspay/neurolink 12.56.0 → 12.56.1

package/dist/neurolink.d.ts

@@ -1,10 +1,3 @@
-/**
- * NeuroLink - Unified AI Interface with Real MCP Tool Integration
- *
- * REDESIGNED FALLBACK CHAIN - NO CIRCULAR DEPENDENCIES
- * Enhanced AI provider system with natural MCP tool access.
- * Uses real MCP infrastructure for tool discovery and execution.
- */
 import type { DecisionCallerOptions, DecisionLimitsQuery, DecisionLimitsReading, DecisionOptions, DecisionResult, AgentDefinition, AgentNetworkConfig, AgentRunOptions, AgentRunOutcome, AgentToolRegistrationOptions, IsolatedAgentDefinition, NetworkExecutionInput, NetworkExecutionOptions, NetworkExecutionResult, NetworkStreamChunk, WorkerInstanceOptions } from "./types/index.js";
 import type { CompactionConfig, CompactionResult, ArtifactStore, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ConversationSeedMessage, ConversationSeedOptions, RecordConversationTurnOptions, RecordConversationTurnResult, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPServerHealth, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig, KnowledgeEngineStatus, ChecklistState, ArtifactPageRequest, BankArtifactOptions, BankedArtifactRef, DelegateCollectRequest, DelegateCollectResult, DelegateHandle, DelegateRegistrationOptions, DelegateSpawnOptions, BackgroundCommandHandle, BackgroundCommandOptions, BackgroundCommandOutputPage, BackgroundCommandPageRequest, BackgroundCommandPolicy, BackgroundCommandStatus, GitToolResult, GitToolsetOptions } from "./types/index.js";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
@@ -612,6 +605,12 @@ export declare class NeuroLink {
      * @returns Modified options with orchestrated provider marked in context, or empty object if validation fails
      */
     private applyStreamOrchestration;
+    /**
+     * Read a nonempty orchestration preference only when provider is absent/auto.
+     * An explicit provider always takes precedence over incoming or generated
+     * context; empty, non-string and auto preferences are ignored.
+     */
+    private getOrchestratedPreferredProvider;
     /**
      * MAIN ENTRY POINT: Enhanced generate method with new function signature
      * Replaces both generateText and legacy methods
@@ -937,6 +936,7 @@ export declare class NeuroLink {
      *
      * The router is skipped when:
      *   - no `requestRouter` is configured on this instance, or
+     *   - a valid orchestration preference already owns the provider/model pair, or
      *   - the caller explicitly set both `options.provider` AND `options.model`
      *     (we only skip the router if BOTH are set; a caller setting only one
      *     still lets the router fill in the other field).
@@ -1118,6 +1118,8 @@ export declare class NeuroLink {
     private generateWithMCPProvider;
     /**
      * Direct provider generation (no MCP, no recursion)
+     * An explicit provider precedes orchestration context; otherwise a valid
+     * orchestration preference is tried before the existing provider fallback list.
      */
     private directProviderGeneration;
     /**
@@ -1324,7 +1326,9 @@ export declare class NeuroLink {
      */
     private emitStreamStartEvents;
     /**
-     * Create MCP stream
+     * Create the provider-backed MCP stream with the existing tool lifecycle.
+     * An explicit provider precedes a valid orchestration context preference;
+     * absent either, getBestProvider retains its normal automatic selection.
      */
     private createMCPStream;
     /**

package/dist/neurolink.js

@@ -1,3 +1,4 @@
+import { beginOllamaDiagnostic, captureOllamaDiagnosticContext, completeOllamaDiagnostic, getOllamaDiagnosticErrorMessage, } from "./utils/ollamaDiagnostics.js";
 /**
  * NeuroLink - Unified AI Interface with Real MCP Tool Integration
  *
@@ -203,13 +204,6 @@ const isNonRetryableForPool = sharedIsNonRetryableForPool;
  */
 const MEMORY_WRITE_TIMEOUT_MS = 30_000;
 /** Native tags share the health check's endpoint precedence and origin. */
-function getOllamaTagsUrl() {
-    const baseUrl = process.env.OLLAMA_BASE_URL ||
-        process.env.OLLAMA_API_BASE ||
-        "http://localhost:11434";
-    // Native /api/tags is at the origin even if the compatible base ends /v1.
-    return new URL("/api/tags", baseUrl).toString();
-}
 /**
  * NeuroLink - Universal AI Development Platform
  *
@@ -2737,8 +2731,17 @@ Current user's request: ${currentInput}`;
             }
             // For Ollama, check if service is running and model is available
             if (route.provider === "ollama") {
+                let ollamaAttempt;
+                let ollamaOutcome = "not-run";
                 try {
-                    const response = await fetch(getOllamaTagsUrl(), {
+                    const ollamaContext = captureOllamaDiagnosticContext();
+                    const gate = beginOllamaDiagnostic(ollamaContext);
+                    if (gate.kind === "suppressed") {
+                        return {};
+                    }
+                    ollamaAttempt = gate;
+                    ollamaOutcome = "transport-failure";
+                    const response = await fetch(ollamaContext.url, {
                         method: "GET",
                         signal: AbortSignal.timeout(2000),
                     });
@@ -2752,6 +2755,7 @@ Current user's request: ${currentInput}`;
                         });
                         return {}; // Return empty object to preserve existing fallback behavior
                     }
+                    ollamaOutcome = "protocol-failure";
                     const responseData = await response.json();
                     const models = responseData?.models;
                     // Runtime-safe guard: ensure models is an array with valid objects
@@ -2762,6 +2766,7 @@ Current user's request: ${currentInput}`;
                         });
                         return {}; // Return empty object for fallback behavior
                     }
+                    ollamaOutcome = "success";
                     // Filter and validate models before comparison
                     const validModels = models.filter((m) => m && typeof m === "object" && typeof m.name === "string");
                     const targetModel = route.model;
@@ -2807,12 +2812,17 @@ Current user's request: ${currentInput}`;
                         routedProvider: route.provider,
                         routedModel: route.model,
                         reason: error instanceof Error
-                            ? error.message
+                            ? getOllamaDiagnosticErrorMessage(error)
                             : "Ollama service check failed",
                         orchestrationTime: `${Date.now() - startTime}ms`,
                     });
                     return {}; // Return empty object to preserve existing fallback behavior
                 }
+                finally {
+                    if (ollamaAttempt) {
+                        completeOllamaDiagnostic(ollamaAttempt, ollamaOutcome);
+                    }
+                }
             }
             logger.debug("Orchestration route determined", {
                 taskType: classification.type,
@@ -2875,8 +2885,17 @@ Current user's request: ${currentInput}`;
             }
             // For Ollama, check if service is running and model is available
             if (route.provider === "ollama") {
+                let ollamaAttempt;
+                let ollamaOutcome = "not-run";
                 try {
-                    const response = await fetch(getOllamaTagsUrl(), {
+                    const ollamaContext = captureOllamaDiagnosticContext();
+                    const gate = beginOllamaDiagnostic(ollamaContext);
+                    if (gate.kind === "suppressed") {
+                        return {};
+                    }
+                    ollamaAttempt = gate;
+                    ollamaOutcome = "transport-failure";
+                    const response = await fetch(ollamaContext.url, {
                         method: "GET",
                         signal: AbortSignal.timeout(2000),
                     });
@@ -2890,6 +2909,7 @@ Current user's request: ${currentInput}`;
                         });
                         return {}; // Return empty object to preserve existing fallback behavior
                     }
+                    ollamaOutcome = "protocol-failure";
                     const responseData = await response.json();
                     const models = responseData?.models;
                     // Runtime-safe guard: ensure models is an array with valid objects
@@ -2900,6 +2920,7 @@ Current user's request: ${currentInput}`;
                         });
                         return {}; // Return empty object for fallback behavior
                     }
+                    ollamaOutcome = "success";
                     // Filter and validate models before comparison
                     const validModels = models.filter((m) => m && typeof m === "object" && typeof m.name === "string");
                     const targetModel = route.model;
@@ -2945,12 +2966,17 @@ Current user's request: ${currentInput}`;
                         routedProvider: route.provider,
                         routedModel: route.model,
                         reason: error instanceof Error
-                            ? error.message
+                            ? getOllamaDiagnosticErrorMessage(error)
                             : "Ollama service check failed",
                         orchestrationTime: `${Date.now() - startTime}ms`,
                     });
                     return {}; // Return empty object to preserve existing fallback behavior
                 }
+                finally {
+                    if (ollamaAttempt) {
+                        completeOllamaDiagnostic(ollamaAttempt, ollamaOutcome);
+                    }
+                }
             }
             logger.debug("Stream orchestration route determined", {
                 taskType: classification.type,
@@ -2978,6 +3004,22 @@ Current user's request: ${currentInput}`;
             throw error;
         }
     }
+    /**
+     * Read a nonempty orchestration preference only when provider is absent/auto.
+     * An explicit provider always takes precedence over incoming or generated
+     * context; empty, non-string and auto preferences are ignored.
+     */
+    getOrchestratedPreferredProvider(options) {
+        if (options.provider && options.provider !== "auto") {
+            return undefined;
+        }
+        const preferred = options.context?.__orchestratedPreferredProvider;
+        return typeof preferred === "string" &&
+            preferred.length > 0 &&
+            preferred !== "auto"
+            ? preferred
+            : undefined;
+    }
     /**
      * MAIN ENTRY POINT: Enhanced generate method with new function signature
      * Replaces both generateText and legacy methods
@@ -4339,6 +4381,7 @@ Current user's request: ${currentInput}`;
      *
      * The router is skipped when:
      *   - no `requestRouter` is configured on this instance, or
+     *   - a valid orchestration preference already owns the provider/model pair, or
      *   - the caller explicitly set both `options.provider` AND `options.model`
      *     (we only skip the router if BOTH are set; a caller setting only one
      *     still lets the router fill in the other field).
@@ -4358,8 +4401,11 @@ Current user's request: ${currentInput}`;
         }
         // Stand down if the classifier router already selected a provider/model on
         // this turn — one explicit precedence order: classifierRouter wins.
-        if (options.context
-            ?.__classifierRouted) {
+        if (options.context?.__classifierRouted) {
+            return;
+        }
+        // Keep an orchestration-selected model with the provider that owns it.
+        if (this.getOrchestratedPreferredProvider(options)) {
             return;
         }
         // Skip if the caller explicitly set both provider AND model — they know
@@ -6577,6 +6623,8 @@ Current user's request: ${currentInput}`;
     }
     /**
      * Direct provider generation (no MCP, no recursion)
+     * An explicit provider precedes orchestration context; otherwise a valid
+     * orchestration preference is tried before the existing provider fallback list.
      */
     async directProviderGeneration(options) {
         const startTime = Date.now();
@@ -6593,13 +6641,8 @@ Current user's request: ${currentInput}`;
             "ollama",
         ];
         const requestedProvider = options.provider === "auto" ? undefined : options.provider;
-        // Check for orchestrated preferred provider in context
-        const preferredOrchestrated = options.context &&
-            typeof options.context === "object" &&
-            "__orchestratedPreferredProvider" in options.context
-            ? options.context
-                .__orchestratedPreferredProvider
-            : undefined;
+        // Read the shared preference while keeping an explicit provider first.
+        const preferredOrchestrated = this.getOrchestratedPreferredProvider(options);
         // Build provider list with orchestrated preference first, then fallback to full list
         const tryProviders = preferredOrchestrated
             ? [
@@ -9425,11 +9468,16 @@ Current user's request: ${currentInput}`;
         this.emitter.emit("message", `Starting ${options.provider || "auto"} stream...`);
     }
     /**
-     * Create MCP stream
+     * Create the provider-backed MCP stream with the existing tool lifecycle.
+     * An explicit provider precedes a valid orchestration context preference;
+     * absent either, getBestProvider retains its normal automatic selection.
      */
     async createMCPStream(options) {
-        // Simplified placeholder - in the actual implementation this would contain the complex MCP stream logic
-        const providerName = await getBestProvider(options.provider);
+        // Consume the validated orchestration choice after an explicit provider.
+        const requestedProvider = options.provider && options.provider !== "auto"
+            ? options.provider
+            : this.getOrchestratedPreferredProvider(options);
+        const providerName = await getBestProvider(requestedProvider);
         const provider = await AIProviderFactory.createProvider(providerName, options.model, !options.disableTools, // Pass disableTools as inverse of enableMCP
         this, // Pass SDK instance
         options.region, // Pass region parameter
@@ -11900,14 +11948,24 @@ Current user's request: ${currentInput}`;
                 }
                 // Special handling for Ollama
                 if (providerName === "ollama") {
+                    let ollamaAttempt;
+                    let ollamaOutcome = "not-run";
                     try {
-                        const response = await fetch(getOllamaTagsUrl(), {
+                        const ollamaContext = captureOllamaDiagnosticContext();
+                        const gate = beginOllamaDiagnostic(ollamaContext);
+                        if (gate.kind === "suppressed") {
+                            throw new Error(gate.reason);
+                        }
+                        ollamaAttempt = gate;
+                        ollamaOutcome = "transport-failure";
+                        const response = await fetch(ollamaContext.url, {
                             method: "GET",
                             signal: AbortSignal.timeout(PROVIDER_TIMEOUTS.AUTH_MS),
                         });
                         if (!response.ok) {
                             throw new Error("Ollama service not responding");
                         }
+                        ollamaOutcome = "protocol-failure";
                         const responseData = await response.json();
                         const models = responseData?.models;
                         // Runtime-safe guard: ensure models is an array with valid objects
@@ -11918,6 +11976,7 @@ Current user's request: ${currentInput}`;
                             });
                             throw new Error("Invalid models format from Ollama API");
                         }
+                        ollamaOutcome = "success";
                         // Filter and validate models before comparison
                         const validModels = models.filter((m) => m && typeof m === "object" && typeof m.name === "string");
                         if (validModels.length > 0) {
@@ -11948,11 +12007,16 @@ Current user's request: ${currentInput}`;
                             configured: false,
                             authenticated: false,
                             error: error instanceof Error
-                                ? error.message
+                                ? getOllamaDiagnosticErrorMessage(error)
                                 : "Ollama service not running",
                             responseTime: Date.now() - startTime,
                         };
                     }
+                    finally {
+                        if (ollamaAttempt) {
+                            completeOllamaDiagnostic(ollamaAttempt, ollamaOutcome);
+                        }
+                    }
                 }
                 // Test other providers with actual generation call. The losing
                 // side of the race is aborted in `finally` below — previously the

package/dist/types/index.d.ts

@@ -103,3 +103,4 @@ export * from "./dispatch.js";
 export * from "./proxyRestart.js";
 export * from "./proxyBudget.js";
 export * from "./decision.js";
+export * from "./ollamaDiagnostics.js";

package/dist/types/index.js

@@ -119,3 +119,4 @@ export * from "./proxyRestart.js";
 export * from "./proxyBudget.js";
 // `decide` inference-type contracts (TypeSafe Jev is the first provider)
 export * from "./decision.js";
+export * from "./ollamaDiagnostics.js";

package/dist/types/ollamaDiagnostics.d.ts

@@ -0,0 +1,31 @@
+/** Native Ollama diagnostic identity, outcome and captured policy state. */
+export type OllamaDiagnosticContext = Readonly<{
+    /** Private resolved URL: never include it, its key, or credentials in logs. */
+    url: string;
+    key: string;
+    model: string;
+}>;
+export type OllamaDiagnosticSnapshot = Readonly<{
+    count: number;
+    lastFailureAt: number | undefined;
+    revision: number;
+    generation: number;
+}>;
+export type OllamaDiagnosticState = {
+    count: number;
+    lastFailureAt: number | undefined;
+    revision: number;
+    generation: number;
+};
+export type OllamaDiagnosticPermit = Readonly<{
+    kind: "allowed";
+    context: OllamaDiagnosticContext;
+    generation: number;
+}>;
+export type OllamaDiagnosticGate = OllamaDiagnosticPermit | Readonly<{
+    kind: "suppressed";
+    count: number;
+    reason: string;
+    generation: number;
+}>;
+export type OllamaDiagnosticOutcome = "success" | "transport-failure" | "protocol-failure" | "not-run";

package/dist/types/ollamaDiagnostics.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/ollamaDiagnostics.d.ts

@@ -0,0 +1,69 @@
+import type { OllamaDiagnosticContext, OllamaDiagnosticGate, OllamaDiagnosticOutcome, OllamaDiagnosticPermit, OllamaDiagnosticSnapshot } from "../types/index.js";
+export declare const OLLAMA_DIAGNOSTIC_RESET_MS = 300000;
+/**
+ * Validate the shared failure threshold once and reuse that first-use value.
+ * Missing or invalid PROVIDER_FAILURE_THRESHOLD values use the existing default
+ * of three; ProviderHealthChecker retains its original initialization point.
+ */
+export declare function getValidatedProviderFailureThreshold(): number;
+/** Return diagnostic error text with URL secrets redacted for logs and status. */
+export declare function getOllamaDiagnosticErrorMessage(error: unknown): string;
+/**
+ * Normalize an endpoint identity without its fragment, retaining path and query.
+ * The key can contain credentials and must remain private like the source URL.
+ */
+export declare function getOllamaDiagnosticEndpointKey(url: string): string;
+/**
+ * Resolve native /api/tags at the configured Ollama origin, independently of a
+ * compatible /v1 base path. OLLAMA_BASE_URL precedes the legacy OLLAMA_API_BASE
+ * alias, then localhost; malformed URLs and non-HTTP(S) schemes are rejected.
+ */
+export declare function resolveOllamaNativeTagsUrl(): string;
+/**
+ * Capture endpoint identity and model before asynchronous diagnostic work.
+ * Later environment changes cannot retarget this context or its health-cache
+ * identity; failure accounting remains shared by endpoint rather than model.
+ */
+export declare function captureOllamaDiagnosticContext(model?: string): OllamaDiagnosticContext;
+/**
+ * Copy the current policy state after applying initialization or timed expiry.
+ * This observation issues no request and records neither failure nor recovery.
+ */
+export declare function getOllamaDiagnosticSnapshot(context: OllamaDiagnosticContext): OllamaDiagnosticSnapshot;
+/**
+ * Admit a native probe or report backoff at the current failure threshold.
+ * Timed expiry is applied before this decision. Admission captures the clear
+ * generation without reserving a request or recording an outcome; callers must
+ * record the actual outcome on completion.
+ */
+export declare function beginOllamaDiagnostic(context: OllamaDiagnosticContext): OllamaDiagnosticGate;
+/**
+ * Apply timed expiry, then an admitted outcome once to the latest endpoint state.
+ * Transport/protocol failures increment its current count; success clears a
+ * nonzero count; not-run records no outcome. Timed expiry preserves permits,
+ * including those admitted before the boundary and completed after it.
+ * Duplicate permits and permits invalidated by explicit clearing are ignored.
+ *
+ * @returns A copy of the resulting state, or undefined for an ignored permit.
+ */
+export declare function completeOllamaDiagnostic(attempt: OllamaDiagnosticPermit, outcome: OllamaDiagnosticOutcome): OllamaDiagnosticSnapshot | undefined;
+/**
+ * Clear every endpoint and advance generation, invalidating in-flight permits.
+ * Unlike timed expiry, this prevents an older completion from repopulating state.
+ */
+export declare function clearOllamaDiagnostics(): void;
+/**
+ * Separate cached health by captured endpoint and model without splitting the
+ * endpoint-wide diagnostic counter. This private key can contain URL secrets.
+ */
+export declare function getOllamaHealthCacheKey(context: OllamaDiagnosticContext): string;
+export declare class OllamaProtocolError extends Error {
+    /** Identify an answered tags response whose models envelope is malformed. */
+    constructor();
+}
+/**
+ * Require an object containing a models array, including an empty array.
+ * Individual model entries are left to existing normalization; a malformed
+ * envelope throws OllamaProtocolError rather than appearing as no models.
+ */
+export declare function readOllamaTagsModels(payload: unknown): unknown[];

package/dist/utils/ollamaDiagnostics.js

@@ -0,0 +1,192 @@
+/** Internal native-diagnostic policy; inference and provider selection are separate. */
+import { logger } from "./logger.js";
+import { DEFAULT_OLLAMA_MODEL } from "../providers/ollama/constants.js";
+import { redactUrlsInText } from "./logSanitize.js";
+export const OLLAMA_DIAGNOSTIC_RESET_MS = 300000;
+let validatedFailureThreshold;
+/**
+ * Validate the shared failure threshold once and reuse that first-use value.
+ * Missing or invalid PROVIDER_FAILURE_THRESHOLD values use the existing default
+ * of three; ProviderHealthChecker retains its original initialization point.
+ */
+export function getValidatedProviderFailureThreshold() {
+    if (validatedFailureThreshold !== undefined) {
+        return validatedFailureThreshold;
+    }
+    const envValue = process.env.PROVIDER_FAILURE_THRESHOLD;
+    if (!envValue) {
+        validatedFailureThreshold = 3;
+        return validatedFailureThreshold;
+    }
+    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`);
+        validatedFailureThreshold = 3;
+        return validatedFailureThreshold;
+    }
+    validatedFailureThreshold = parsed;
+    return validatedFailureThreshold;
+}
+/** Return diagnostic error text with URL secrets redacted for logs and status. */
+export function getOllamaDiagnosticErrorMessage(error) {
+    return redactUrlsInText(error instanceof Error ? error.message : String(error));
+}
+const states = new Map();
+const completed = new WeakSet();
+let clearGeneration = 0;
+/**
+ * Normalize an endpoint identity without its fragment, retaining path and query.
+ * The key can contain credentials and must remain private like the source URL.
+ */
+export function getOllamaDiagnosticEndpointKey(url) {
+    const parsed = new URL(url);
+    parsed.hash = "";
+    return parsed.toString();
+}
+/**
+ * Resolve native /api/tags at the configured Ollama origin, independently of a
+ * compatible /v1 base path. OLLAMA_BASE_URL precedes the legacy OLLAMA_API_BASE
+ * alias, then localhost; malformed URLs and non-HTTP(S) schemes are rejected.
+ */
+export function resolveOllamaNativeTagsUrl() {
+    const base = process.env.OLLAMA_BASE_URL ||
+        process.env.OLLAMA_API_BASE ||
+        "http://localhost:11434";
+    const resolved = new URL("/api/tags", base);
+    if (resolved.protocol !== "http:" && resolved.protocol !== "https:") {
+        throw new Error("Invalid OLLAMA_BASE_URL format (OLLAMA_API_BASE is still accepted as a legacy alias)");
+    }
+    resolved.hash = "";
+    return resolved.toString();
+}
+/**
+ * Capture endpoint identity and model before asynchronous diagnostic work.
+ * Later environment changes cannot retarget this context or its health-cache
+ * identity; failure accounting remains shared by endpoint rather than model.
+ */
+export function captureOllamaDiagnosticContext(model = process.env.OLLAMA_MODEL || DEFAULT_OLLAMA_MODEL) {
+    const url = resolveOllamaNativeTagsUrl();
+    return { url, key: getOllamaDiagnosticEndpointKey(url), model };
+}
+/**
+ * Initialize endpoint state or expire failures five minutes after the latest one.
+ * Expiry clears the count/timestamp and advances revision, retaining generation
+ * so existing in-flight permits remain valid. Only an explicit clear changes
+ * generation and invalidates those permits.
+ */
+function getState(context) {
+    let state = states.get(context.key);
+    if (!state) {
+        state = {
+            count: 0,
+            lastFailureAt: undefined,
+            revision: 0,
+            generation: clearGeneration,
+        };
+        states.set(context.key, state);
+    }
+    if (state.lastFailureAt !== undefined &&
+        Date.now() - state.lastFailureAt >= OLLAMA_DIAGNOSTIC_RESET_MS) {
+        // This is a fixed-window expiry, not an outcome from a cache hit/probe.
+        state.count = 0;
+        state.lastFailureAt = undefined;
+        state.revision++;
+    }
+    return state;
+}
+/**
+ * Copy the current policy state after applying initialization or timed expiry.
+ * This observation issues no request and records neither failure nor recovery.
+ */
+export function getOllamaDiagnosticSnapshot(context) {
+    return { ...getState(context) };
+}
+/**
+ * Admit a native probe or report backoff at the current failure threshold.
+ * Timed expiry is applied before this decision. Admission captures the clear
+ * generation without reserving a request or recording an outcome; callers must
+ * record the actual outcome on completion.
+ */
+export function beginOllamaDiagnostic(context) {
+    const state = getState(context);
+    if (state.count >= getValidatedProviderFailureThreshold()) {
+        return {
+            kind: "suppressed",
+            count: state.count,
+            reason: `Ollama native diagnostic backed off after ${state.count} consecutive transport failures`,
+            generation: state.generation,
+        };
+    }
+    return { kind: "allowed", context, generation: state.generation };
+}
+/**
+ * Apply timed expiry, then an admitted outcome once to the latest endpoint state.
+ * Transport/protocol failures increment its current count; success clears a
+ * nonzero count; not-run records no outcome. Timed expiry preserves permits,
+ * including those admitted before the boundary and completed after it.
+ * Duplicate permits and permits invalidated by explicit clearing are ignored.
+ *
+ * @returns A copy of the resulting state, or undefined for an ignored permit.
+ */
+export function completeOllamaDiagnostic(attempt, outcome) {
+    if (completed.has(attempt)) {
+        return undefined;
+    }
+    completed.add(attempt);
+    const storedState = states.get(attempt.context.key);
+    if (!storedState || storedState.generation !== attempt.generation) {
+        return undefined; // Explicit clearing invalidated this in-flight token.
+    }
+    const state = getState(attempt.context);
+    if (outcome === "transport-failure" || outcome === "protocol-failure") {
+        // Read and increment the latest completed state, never the starting count.
+        state.count++;
+        state.lastFailureAt = Date.now();
+        state.revision++;
+    }
+    else if (outcome === "success" && state.count !== 0) {
+        state.count = 0;
+        state.lastFailureAt = undefined;
+        state.revision++;
+    }
+    // Only admitted probes may reach this function. not-run cannot claim failure
+    // or recovery; genuine success while already clear retains the cache revision.
+    return { ...state };
+}
+/**
+ * Clear every endpoint and advance generation, invalidating in-flight permits.
+ * Unlike timed expiry, this prevents an older completion from repopulating state.
+ */
+export function clearOllamaDiagnostics() {
+    clearGeneration++;
+    states.clear();
+}
+/**
+ * Separate cached health by captured endpoint and model without splitting the
+ * endpoint-wide diagnostic counter. This private key can contain URL secrets.
+ */
+export function getOllamaHealthCacheKey(context) {
+    return JSON.stringify(["ollama", context.key, context.model]);
+}
+export class OllamaProtocolError extends Error {
+    /** Identify an answered tags response whose models envelope is malformed. */
+    constructor() {
+        super("Invalid models format from Ollama API");
+        this.name = "OllamaProtocolError";
+    }
+}
+/**
+ * Require an object containing a models array, including an empty array.
+ * Individual model entries are left to existing normalization; a malformed
+ * envelope throws OllamaProtocolError rather than appearing as no models.
+ */
+export function readOllamaTagsModels(payload) {
+    if (payload === null ||
+        typeof payload !== "object" ||
+        Array.isArray(payload) ||
+        !("models" in payload) ||
+        !Array.isArray(payload.models)) {
+        throw new OllamaProtocolError();
+    }
+    return payload.models;
+}