@juspay/neurolink 9.75.0 → 9.77.0

package/dist/neurolink.js

@@ -55,7 +55,7 @@ import { resolveDynamicArgument } from "./dynamic/dynamicResolver.js";
 import { initializeHippocampus } from "./memory/hippocampusInitializer.js";
 import { createMemoryRetrievalTools } from "./memory/memoryRetrievalTools.js";
 import { getMetricsAggregator, MetricsAggregator, } from "./observability/metricsAggregator.js";
-import { SpanStatus, SpanType, CircuitBreakerOpenError, ConversationMemoryError, AuthenticationError, AuthorizationError, InvalidModelError, ModelAccessDeniedError, } from "./types/index.js";
+import { SpanStatus, SpanType, CircuitBreakerOpenError, ConversationMemoryError, ModelAccessDeniedError, } from "./types/index.js";
 import { SpanSerializer } from "./observability/utils/spanSerializer.js";
 import { flushOpenTelemetry, getLangfuseContext, getLangfuseHealthStatus, initializeOpenTelemetry, isOpenTelemetryInitialized, runWithCurrentLangfuseContext, setLangfuseContext, shutdownOpenTelemetry, stampGuestRescueIdentity, } from "./services/server/ai/observability/instrumentation.js";
 import { TaskManager } from "./tasks/taskManager.js";
@@ -78,7 +78,6 @@ import { resolveModel } from "./utils/modelAliasResolver.js";
 // Import orchestration components
 import { ModelRouter } from "./utils/modelRouter.js";
 import { getBestProvider } from "./utils/providerUtils.js";
-import { NON_RETRYABLE_HTTP_STATUS_CODES, isDeterministicClientErrorMessage, } from "./utils/retryability.js";
 import { isZodSchema } from "./utils/schemaConversion.js";
 import { BinaryTaskClassifier } from "./utils/taskClassifier.js";
 // Tool detection and execution imports
@@ -87,6 +86,8 @@ import { extractToolNames, optimizeToolForCollection, transformAvailableTools, t
 import { isNonNullObject } from "./utils/typeUtils.js";
 import { getWorkflow } from "./workflow/core/workflowRegistry.js";
 import { runWorkflow } from "./workflow/core/workflowRunner.js";
+import { ModelPool, classifyProviderError } from "./routing/index.js";
+import { looksLikeModelAccessDenied as sharedLooksLikeModelAccessDenied, isNonRetryableProviderError as sharedIsNonRetryableProviderError, } from "./utils/providerErrorClassification.js";
 /**
  * NL-002: Classify MCP error messages into categories for AI disambiguation.
  * Returns a human-readable error category based on error message content.
@@ -151,95 +152,12 @@ function mcpCategoryToErrorCategory(mcpCategory) {
  * This prevents wasting tokens and latency on guaranteed-to-fail retries.
  * For example, a NOT_FOUND error for a model causes 6 retries of a 418KB
  * message, wasting ~628,000 tokens and adding 10+ seconds of latency.
+ *
+ * Delegates to the shared utility in utils/providerErrorClassification.ts so
+ * that modelPool.ts (classifyProviderError) and this function stay in sync.
  */
-/**
- * Curator P2-3: detect model-access-denied without requiring the typed
- * ModelAccessDeniedError class to be present (Issue #1 ships that class
- * separately). Matches LiteLLM "team not allowed" / "team can only access
- * models=[...]" plus typed-error markers when present.
- */
-function looksLikeModelAccessDenied(error) {
-    if (!error) {
-        return false;
-    }
-    const e = error;
-    if (e.name === "ModelAccessDeniedError") {
-        return true;
-    }
-    if (e.code === "MODEL_ACCESS_DENIED") {
-        return true;
-    }
-    const msg = typeof e.message === "string"
-        ? e.message
-        : error instanceof Error
-            ? error.message
-            : String(error);
-    if (!msg) {
-        return false;
-    }
-    const lower = msg.toLowerCase();
-    return ((lower.includes("team") && lower.includes("not allowed")) ||
-        lower.includes("team can only access") ||
-        /not\s+allowed\s+to\s+access\s+(this\s+)?model/i.test(msg));
-}
-function isNonRetryableProviderError(error) {
-    // Check for typed error classes from providers
-    if (error instanceof InvalidModelError) {
-        return true;
-    }
-    if (error instanceof AuthenticationError) {
-        return true;
-    }
-    if (error instanceof AuthorizationError) {
-        return true;
-    }
-    // Curator P1-1: model-access-denied is permanent for the (provider, model)
-    // pair until the team whitelist changes. Retrying with the same config
-    // would just waste a second roundtrip. Caller / fallback-orchestrator
-    // should pick a different model.
-    if (error instanceof ModelAccessDeniedError) {
-        return true;
-    }
-    // Note: ContextBudgetExceededError is intentionally NOT non-retryable.
-    // Each provider has its own context window, so a budget rejection on
-    // one provider doesn't preclude another provider's window fitting the
-    // same payload. The directProviderGeneration loop should continue
-    // trying alternate providers; the after-loop rethrow preserves the
-    // typed error when all providers reject (see `directProviderGeneration`).
-    // Check for HTTP status codes on error objects (e.g., from Vercel AI SDK)
-    if (error && typeof error === "object") {
-        const err = error;
-        const status = typeof err.status === "number"
-            ? err.status
-            : typeof err.statusCode === "number"
-                ? err.statusCode
-                : undefined;
-        if (status && NON_RETRYABLE_HTTP_STATUS_CODES.includes(status)) {
-            return true;
-        }
-    }
-    // Check error message for NOT_FOUND patterns (catches wrapped errors)
-    if (error instanceof Error) {
-        const msg = error.message;
-        if (msg.includes("NOT_FOUND") ||
-            msg.includes("Model Not Found") ||
-            msg.includes("model not found") ||
-            msg.includes("PERMISSION_DENIED") ||
-            msg.includes("UNAUTHENTICATED")) {
-            return true;
-        }
-        // A deterministic 400 / malformed-request whose status is only present in
-        // the message string (e.g. Vertex wraps `{"code":400,"status":
-        // "INVALID_ARGUMENT"}` inside the message). The object-level status check
-        // above misses it, so without this the fallback orchestrator retries the
-        // identical bad payload on every other provider — they reject it the same
-        // way. The request itself is malformed, so abort fast.
-        if (isDeterministicClientErrorMessage(msg)) {
-            return true;
-        }
-    }
-    return false;
-}
+const looksLikeModelAccessDenied = sharedLooksLikeModelAccessDenied;
+const isNonRetryableProviderError = sharedIsNonRetryableProviderError;
 /**
  * NeuroLink - Universal AI Development Platform
  *
@@ -445,6 +363,8 @@ export class NeuroLink {
     // Lazy-initialized routing decision cache (ITEM C). Created on first use so
     // instances that don't use routing pay no overhead.
     toolRoutingCacheInstance;
+    // Opt-in tool-signature deduplication config.
+    toolDedupConfig;
     // Add orchestration property
     enableOrchestration;
     // Authentication provider for secure access control
@@ -456,6 +376,12 @@ export class NeuroLink {
     // Curator P2-3: instance-level fallback policy. Read by
     // runWithFallbackOrchestration on model-access-denied.
     fallbackConfig = {};
+    // ModelPool: opt-in multi-provider failover with per-member cooldown.
+    // Built once from config.modelPool in the constructor; null when not configured.
+    modelPool;
+    // RequestRouter: pluggable pre-call provider/model selector.
+    // Stored directly from config.requestRouter; null when not configured.
+    requestRouter;
     /**
      * Merge instance-level credentials with per-call credentials.
      *
@@ -857,6 +783,13 @@ export class NeuroLink {
             // multiple NeuroLink instances.
             this.toolRoutingConfig = { ...config.toolRouting };
         }
+        if (config?.toolDedup) {
+            this.toolDedupConfig = { ...config.toolDedup };
+        }
+        // ModelPool: build one instance from config; null when not configured.
+        this.modelPool = config?.modelPool ? new ModelPool(config.modelPool) : null;
+        // RequestRouter: store the host-supplied function; null when not configured.
+        this.requestRouter = config?.requestRouter ?? null;
         logger.setEventEmitter(this.emitter);
         // Read tool cache duration from environment variables, with a default
         const cacheDurationEnv = process.env.NEUROLINK_TOOL_CACHE_DURATION;
@@ -3167,6 +3100,11 @@ Current user's request: ${currentInput}`;
     async runStandardGenerateRequest(options, originalPrompt, generateSpan) {
         const startTime = Date.now();
         await this.maybeApplyGenerateOrchestration(options);
+        // Pre-call request router: opt-in, only when the caller did not set both
+        // provider+model. Fails open (any router error leaves options unchanged).
+        await this.applyRequestRouter(options, options.input?.text ?? originalPrompt ?? "", !options.disableTools &&
+            (!!(options.tools && Object.keys(options.tools).length > 0) ||
+                this.getCustomTools().size > 0), !!(options.input?.images && options.input.images.length > 0), options.thinkingConfig?.thinkingLevel);
         this.emitter.emit("generation:start", {
             provider: options.provider || "auto",
             timestamp: startTime,
@@ -3275,6 +3213,94 @@ Current user's request: ${currentInput}`;
             });
         }
     }
+    /**
+     * Applies the host-configured `requestRouter` to `options` in place.
+     *
+     * The router is skipped when:
+     *   - no `requestRouter` is configured on this instance, 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).
+     *
+     * Fails open: any router error is logged at WARN level and the call
+     * continues with the original options unmodified.
+     *
+     * @param options — the mutable options object (generate or stream).
+     * @param promptText — the text prompt used to build the RouterInputContext.
+     * @param hasTools — true when at least one tool is available for this call.
+     * @param requiresVision — true when the call includes image attachments.
+     * @param thinkingLevel — optional thinking level string from the call options.
+     */
+    async applyRequestRouter(options, promptText, hasTools, requiresVision, thinkingLevel) {
+        if (!this.requestRouter) {
+            return;
+        }
+        // Skip if the caller explicitly set both provider AND model — they know
+        // what they want; the router should not override an intentional choice.
+        if (options.provider && options.model) {
+            return;
+        }
+        // Skip when a ModelPool is also configured: the pool unconditionally
+        // overrides provider+model for each member it selects.  Allowing the
+        // router to run first would set options.provider/model to a value the
+        // pool immediately clobbers, creating silent ownership confusion and
+        // making the pool bypass the "user didn't set provider+model" guard above
+        // on subsequent attempts.
+        if (this.modelPool) {
+            logger.debug("[NeuroLink] applyRequestRouter: skipped — modelPool takes precedence");
+            return;
+        }
+        const ctx = {
+            prompt: promptText,
+            // Cheap token estimate: ~4 chars/token.
+            estimatedInputTokens: Math.ceil(promptText.length / 4),
+            hasTools,
+            requiresVision,
+            thinkingLevel,
+        };
+        try {
+            const decision = await this.requestRouter(ctx);
+            // Apply provider/model/region as a coherent set: when the router supplies
+            // a provider (the caller didn't pin one), take its model and region too.
+            // If the caller pinned the provider but not the model, only apply the
+            // router's model when it targets the same provider.
+            if (decision.provider && !options.provider) {
+                options.provider = decision.provider;
+                // Adopt the router's model and region only when they belong to the
+                // provider the router just selected — never mix a router model onto a
+                // caller-pinned different provider.
+                if (decision.model && !options.model) {
+                    options.model = decision.model;
+                }
+                if (decision.region && !options.region) {
+                    options.region = decision.region;
+                }
+            }
+            else if (!decision.provider) {
+                // Router returned a no-op or model-only decision.
+                if (decision.model && !options.model) {
+                    options.model = decision.model;
+                }
+                if (decision.region && !options.region) {
+                    options.region = decision.region;
+                }
+            }
+            // If decision.provider differs from the caller-pinned options.provider,
+            // we skip the router result entirely to avoid an incoherent pairing.
+            if (decision.reason) {
+                logger.debug("[NeuroLink] requestRouter decision", {
+                    reason: decision.reason,
+                    provider: options.provider,
+                    model: options.model,
+                });
+            }
+        }
+        catch (routerErr) {
+            logger.warn("[NeuroLink] requestRouter threw — proceeding unrouted", {
+                error: routerErr instanceof Error ? routerErr.message : String(routerErr),
+            });
+        }
+    }
     async prepareGenerateAugmentations(options) {
         if (options.rag?.files?.length) {
             try {
@@ -4956,6 +4982,149 @@ Current user's request: ${currentInput}`;
             tryProviders,
             allowFallback: !requestedProvider || !!preferredOrchestrated,
         });
+        // ─── ModelPool path ──────────────────────────────────────────────────────
+        // When a ModelPool is configured, source the candidate sequence from the
+        // pool instead of (or in addition to) the static tryProviders list.
+        // Preserves the existing isNonRetryableProviderError short-circuit and
+        // AbortError propagation semantics. Falls through to the standard path
+        // when no pool is configured.
+        if (this.modelPool) {
+            const pool = this.modelPool;
+            const maxPoolAttempts = pool.maxAttempts;
+            const triedKeys = new Set();
+            let poolLastError = null;
+            for (let attempt = 0; attempt < maxPoolAttempts; attempt++) {
+                if (options.abortSignal?.aborted) {
+                    throw new DOMException("The operation was aborted", "AbortError");
+                }
+                const member = pool.selectNext(triedKeys);
+                if (!member) {
+                    // All available members exhausted.
+                    break;
+                }
+                triedKeys.add(pool.memberKey(member));
+                // Temporarily override provider/model/region from the pool member.
+                const savedProvider = options.provider;
+                const savedModel = options.model;
+                const savedRegion = options.region;
+                options.provider = member.provider;
+                // When the member omits model/region, clear inherited values so the
+                // provider's own default is used rather than a mismatched caller value.
+                options.model = member.model ?? undefined;
+                options.region = member.region ?? undefined;
+                const poolProviderName = member.provider;
+                logger.debug(`[${functionTag}] ModelPool: attempting member`, {
+                    provider: poolProviderName,
+                    model: member.model ?? options.model,
+                    attempt,
+                });
+                try {
+                    // Get conversation messages for context (use pre-compacted if provided)
+                    const poolOptionsWithMessages = options;
+                    const poolConversationMessages = poolOptionsWithMessages
+                        .conversationMessages?.length
+                        ? poolOptionsWithMessages.conversationMessages
+                        : await getConversationMessages(this.conversationMemory, options);
+                    const poolProvider = await AIProviderFactory.createProvider(poolProviderName, options.model, !options.disableTools, this, options.region, this.resolveCredentials(options.credentials));
+                    poolProvider.setTraceContext(this._metricsTraceContext);
+                    poolProvider.setupToolExecutor({
+                        customTools: this.getCustomTools(),
+                        executeTool: (toolName, params) => this.executeTool(toolName, params, {
+                            disableToolCache: options.disableToolCache,
+                        }),
+                    }, functionTag);
+                    const poolResult = await poolProvider.generate({
+                        ...options,
+                        conversationMessages: poolConversationMessages,
+                    });
+                    if (!poolResult) {
+                        throw new Error(`ModelPool: provider ${poolProviderName} returned null result`);
+                    }
+                    pool.recordSuccess(member);
+                    const responseTime = Date.now() - startTime;
+                    // Restore original options fields so callers see a clean object.
+                    options.provider = savedProvider;
+                    options.model = savedModel;
+                    options.region = savedRegion;
+                    return {
+                        content: poolResult.content || "",
+                        provider: poolProviderName,
+                        model: poolResult.model,
+                        usage: poolResult.usage,
+                        responseTime,
+                        finishReason: poolResult.finishReason,
+                        toolsUsed: poolResult.toolsUsed || [],
+                        toolExecutions: poolResult.toolExecutions?.map((te) => {
+                            const t = te;
+                            return {
+                                ...te,
+                                toolName: te.name,
+                                executionTime: typeof t.executionTime === "number"
+                                    ? t.executionTime
+                                    : typeof t.duration === "number"
+                                        ? t.duration
+                                        : 0,
+                                success: typeof t.success === "boolean"
+                                    ? t.success
+                                    : t.status === "success",
+                            };
+                        }),
+                        enhancedWithTools: !!poolResult.toolExecutions?.length,
+                        analytics: poolResult.analytics,
+                        evaluation: poolResult.evaluation,
+                        audio: poolResult.audio,
+                        video: poolResult.video,
+                        avatar: poolResult.avatar,
+                        music: poolResult.music,
+                        ppt: poolResult.ppt,
+                        imageOutput: poolResult.imageOutput,
+                        reasoning: poolResult.reasoning,
+                        reasoningTokens: poolResult.reasoningTokens,
+                        _generationEndEmitted: poolResult._generationEndEmitted,
+                    };
+                }
+                catch (poolError) {
+                    // Restore options unconditionally on failure.
+                    options.provider = savedProvider;
+                    options.model = savedModel;
+                    options.region = savedRegion;
+                    if (isAbortError(poolError)) {
+                        throw poolError;
+                    }
+                    if (isNonRetryableProviderError(poolError)) {
+                        const poolErrMsg = poolError instanceof Error
+                            ? poolError.message
+                            : String(poolError);
+                        logger.warn(`[${functionTag}] ModelPool: non-retryable error from ${poolProviderName}, stopping pool`, { error: poolErrMsg });
+                        pool.recordFailure(member, classifyProviderError(poolError));
+                        // Wrap in a plain Error so runWithFallbackOrchestration does not
+                        // mistake this for a ModelAccessDeniedError and start a second
+                        // retry layer on top of the already-exhausted pool.
+                        throw new Error(`[ModelPool] non-retryable: ${poolErrMsg}`, {
+                            cause: poolError,
+                        });
+                    }
+                    pool.recordFailure(member, classifyProviderError(poolError));
+                    poolLastError =
+                        poolError instanceof Error
+                            ? poolError
+                            : new Error(String(poolError));
+                    logger.warn(`[${functionTag}] ModelPool: member ${poolProviderName} failed`, { error: poolLastError.message });
+                }
+            }
+            // All pool members failed or were exhausted.
+            const poolResponseTime = Date.now() - startTime;
+            logger.error(`[${functionTag}] ModelPool: all members failed`, {
+                triedKeys: Array.from(triedKeys),
+                lastError: poolLastError?.message,
+                responseTime: poolResponseTime,
+            });
+            // Wrap in a plain Error (not a typed error class) so that
+            // runWithFallbackOrchestration does not re-activate the modelChain /
+            // providerFallback layer on top of an already-exhausted pool.
+            throw new Error(`[ModelPool] all members failed: ${poolLastError?.message ?? "no members available"}`);
+        }
+        // ─── End ModelPool path ───────────────────────────────────────────────────
         let lastError = null;
         // Try each provider in order
         for (const providerName of tryProviders) {
@@ -5654,6 +5823,11 @@ Current user's request: ${currentInput}`;
             // classify correctly. After the workflow short-circuit, so workflow
             // streams skip it.
             await context.with(streamSpanContext, () => this.setLangfuseContextFromOptions(options, () => this.applyToolRoutingExclusions(options, originalPrompt)));
+            // Pre-call request router for stream: opt-in, fails open.
+            await this.applyRequestRouter(options, originalPrompt, !options.disableTools &&
+                (!!(options.tools && Object.keys(options.tools).length > 0) ||
+                    this.getCustomTools().size > 0), !!(options.input?.images && options.input.images.length > 0), options
+                .thinking?.thinkingLevel);
             // TTS Mode 2 deferred: stream() emits text first, then synthesizes the
             // accumulated response into a single audio chunk at end-of-stream and
             // resolves `streamResult.audio` with the same TTSResult. The resolver is
@@ -7114,6 +7288,114 @@ Current user's request: ${currentInput}`;
                 }
             }
         }
+        // ─── ModelPool stream path ────────────────────────────────────────────────
+        // When a pool is configured, replaces the single provider.stream() call
+        // with a retry loop over pool members. Compaction/budget-check above ran
+        // once on the initially-selected `providerName`; the pool may redirect to
+        // a different provider, but those checks are conservative enough that the
+        // redirected provider will also accept the payload (if it has a smaller
+        // window, the budget check would have already thrown before we get here).
+        // On exhaustion, throws the last member error — does NOT fall through to
+        // the static provider path below.
+        if (this.modelPool) {
+            const streamPool = this.modelPool;
+            const maxStreamAttempts = streamPool.maxAttempts;
+            const streamTriedKeys = new Set();
+            let streamLastError = null;
+            for (let attempt = 0; attempt < maxStreamAttempts; attempt++) {
+                if (options.abortSignal?.aborted) {
+                    throw new DOMException("The operation was aborted", "AbortError");
+                }
+                const streamMember = streamPool.selectNext(streamTriedKeys);
+                if (!streamMember) {
+                    break;
+                }
+                streamTriedKeys.add(streamPool.memberKey(streamMember));
+                // Override provider/model/region from the pool member.
+                // When the member omits model/region, use undefined (provider default)
+                // rather than inheriting the caller's value for a different provider.
+                const poolStreamProviderName = streamMember.provider;
+                const poolStreamModel = streamMember.model ?? undefined;
+                const poolStreamRegion = streamMember.region ?? undefined;
+                logger.debug(`[createMCPStream] ModelPool: attempting member ${poolStreamProviderName}`, { model: poolStreamModel, attempt });
+                try {
+                    const poolStreamProvider = await AIProviderFactory.createProvider(poolStreamProviderName, poolStreamModel, !options.disableTools, this, poolStreamRegion, this.resolveCredentials(options.credentials));
+                    poolStreamProvider.setTraceContext(this._metricsTraceContext);
+                    poolStreamProvider.setupToolExecutor({
+                        customTools: this.getCustomTools(),
+                        executeTool: (toolName, params) => this.executeTool(toolName, params, {
+                            disableToolCache: options.disableToolCache,
+                        }),
+                    }, "NeuroLink.createMCPStream");
+                    const poolStreamResult = await poolStreamProvider.stream({
+                        ...options,
+                        provider: poolStreamProviderName,
+                        model: poolStreamModel,
+                        region: poolStreamRegion,
+                        systemPrompt: enhancedSystemPrompt,
+                        conversationMessages,
+                    });
+                    logger.debug("[createMCPStream] ModelPool stream handle obtained", {
+                        provider: poolStreamProviderName,
+                    });
+                    // Wrap the stream so we can record success/failure based on what
+                    // actually happens during consumption, not merely on obtaining the
+                    // handle.  Recording success at handle-acquisition time (before any
+                    // tokens are delivered) would mean a mid-stream provider drop is
+                    // never reflected as a cooldown.
+                    const capturedMember = streamMember;
+                    const wrappedStream = (async function* () {
+                        try {
+                            yield* poolStreamResult.stream;
+                            streamPool.recordSuccess(capturedMember);
+                        }
+                        catch (streamConsumeErr) {
+                            streamPool.recordFailure(capturedMember, classifyProviderError(streamConsumeErr));
+                            throw streamConsumeErr;
+                        }
+                    })();
+                    return {
+                        stream: wrappedStream,
+                        provider: poolStreamProviderName,
+                        usage: poolStreamResult.usage,
+                        model: poolStreamResult.model || poolStreamModel,
+                        finishReason: poolStreamResult.finishReason,
+                        toolCalls: poolStreamResult.toolCalls ?? [],
+                        toolResults: poolStreamResult.toolResults ?? [],
+                        analytics: poolStreamResult.analytics,
+                    };
+                }
+                catch (poolStreamError) {
+                    if (isAbortError(poolStreamError)) {
+                        throw poolStreamError;
+                    }
+                    if (isNonRetryableProviderError(poolStreamError)) {
+                        const poolStreamErrMsg = poolStreamError instanceof Error
+                            ? poolStreamError.message
+                            : String(poolStreamError);
+                        streamPool.recordFailure(streamMember, classifyProviderError(poolStreamError));
+                        // Wrap in a plain Error so runWithFallbackOrchestration /
+                        // streamWithIterationFallback does not re-activate the modelChain
+                        // layer on top of an already-exhausted pool.
+                        throw new Error(`[ModelPool] non-retryable: ${poolStreamErrMsg}`, {
+                            cause: poolStreamError,
+                        });
+                    }
+                    streamPool.recordFailure(streamMember, classifyProviderError(poolStreamError));
+                    streamLastError =
+                        poolStreamError instanceof Error
+                            ? poolStreamError
+                            : new Error(String(poolStreamError));
+                    logger.warn(`[createMCPStream] ModelPool: member ${poolStreamProviderName} failed`, { error: streamLastError.message });
+                }
+            }
+            // All pool stream members failed.
+            // Wrap in a plain Error (not a typed error class) so that the
+            // surrounding fallback orchestrator does not start a second retry layer
+            // over the already-exhausted pool.
+            throw new Error(`[ModelPool] all stream members failed: ${streamLastError?.message ?? "no stream members available"}`);
+        }
+        // ─── End ModelPool stream path ────────────────────────────────────────────
         // 🔧 FIX: Pass enhanced system prompt to real streaming
         // Tools will be accessed through the streamText call in executeStream
         const streamResult = await provider.stream({
@@ -7513,6 +7795,21 @@ Current user's request: ${currentInput}`;
     getEventEmitter() {
         return this.emitter;
     }
+    /**
+     * Returns the instance-level tool-dedup configuration, or `undefined` when
+     * toolDedup was not provided at construction time.
+     *
+     * The stored object is returned as-is whenever `toolDedup` was supplied,
+     * including when `enabled: false` — only the complete absence of a `toolDedup`
+     * option results in `undefined`.
+     *
+     * Called by `BaseProvider.applyToolFiltering` so the dedup pass uses the
+     * same config for every generate/stream call without threading an extra
+     * parameter through the full call stack.
+     */
+    getToolDedupConfig() {
+        return this.toolDedupConfig;
+    }
     /**
      * Curator P1-1: synchronous credential health check for a single provider.
      *

package/dist/routing/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Routing subsystem public API.
+ *
+ * Exports runtime values only — types are exported from src/lib/types/.
+ */
+export { classifyProviderError, ModelPool } from "./modelPool.js";
+export { createDefaultRequestRouter } from "./requestRouter.js";

package/dist/routing/index.js

@@ -0,0 +1,7 @@
+/**
+ * Routing subsystem public API.
+ *
+ * Exports runtime values only — types are exported from src/lib/types/.
+ */
+export { classifyProviderError, ModelPool } from "./modelPool.js";
+export { createDefaultRequestRouter } from "./requestRouter.js";

package/dist/routing/modelPool.d.ts

@@ -0,0 +1,83 @@
+/**
+ * ModelPool runtime — multi-provider failover with per-member cooldown.
+ *
+ * This module is PURE (no provider imports, no circular dependencies).
+ * It works exclusively with provider NAMES + (provider, model, region) tuples;
+ * the existing AIProviderFactory creates actual provider instances.
+ *
+ * Usage:
+ *   const pool = new ModelPool({ members: [...], strategy: "round-robin" });
+ *   const member = pool.selectNext();
+ *   try {
+ *     await callProvider(member);
+ *     pool.recordSuccess(member);
+ *   } catch (err) {
+ *     pool.recordFailure(member, classifyProviderError(err));
+ *     // try next member ...
+ *   }
+ */
+import type { ModelPoolConfig, ModelPoolMember, ProviderErrorClass } from "../types/index.js";
+/**
+ * Classify a provider error into a coarse `ProviderErrorClass`.
+ *
+ * Rules (checked in order):
+ * 1. HTTP 429 or message pattern → "rate_limit"
+ * 2. HTTP 401/403, access-denied pattern, or auth keywords → "auth"
+ * 3. Context-window / token-limit message → "context_window"
+ * 4. HTTP 5xx or server-error message → "server"
+ * 5. Network connectivity error → "network"
+ * 6. Everything else → "unknown"
+ */
+export declare function classifyProviderError(error: unknown): ProviderErrorClass;
+/**
+ * Multi-provider pool with per-member cooldown and strategy-based selection.
+ *
+ * All state (cooldowns, cursor) is instance-local and resets on construction.
+ * Thread safety is not required — Node.js is single-threaded for async work.
+ */
+export declare class ModelPool {
+    private readonly config;
+    private readonly strategy;
+    private readonly cooldownMs;
+    private readonly state;
+    private cursor;
+    private readonly now;
+    constructor(config: ModelPoolConfig, injectors?: {
+        now?: () => number;
+    });
+    /**
+     * The maximum number of attempts per call (pool config value or member count).
+     * Used by callers that drive the retry loop externally.
+     */
+    get maxAttempts(): number;
+    /**
+     * Returns a stable string key for a pool member.
+     * Format: `${provider}:${model ?? "*"}:${region ?? "*"}`
+     */
+    memberKey(member: ModelPoolMember): string;
+    /** Returns members whose cooldown has expired (or were never cooled). */
+    availableMembers(): ModelPoolMember[];
+    /**
+     * Selects the next member to try according to the configured strategy.
+     *
+     * @param excludedKeys — keys of members already attempted this call.
+     * @returns the chosen member, or undefined when all members are exhausted.
+     */
+    selectNext(excludedKeys?: Set<string>): ModelPoolMember | undefined;
+    /**
+     * Records a provider failure, setting a cooldown appropriate for the error class.
+     *
+     * - Retryable classes (rate_limit, server, network, unknown): timed cooldown
+     *   for `cooldownMs` so the member can recover and be retried later.
+     * - Non-retryable classes (auth, context_window): permanent cooldown for the
+     *   lifetime of this ModelPool instance, because these errors are structural
+     *   and will not resolve between calls (wrong credentials, model not available
+     *   in team whitelist, payload exceeds the model's context window).
+     */
+    recordFailure(member: ModelPoolMember, errorClass: ProviderErrorClass): void;
+    /**
+     * Records a successful response, clearing any existing cooldown for this member
+     * so it remains fully available.
+     */
+    recordSuccess(member: ModelPoolMember): void;
+}