@juspay/neurolink 9.57.0 → 9.58.0

package/dist/neurolink.js

@@ -146,6 +146,36 @@ function mcpCategoryToErrorCategory(mcpCategory) {
  * 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.
  */
+/**
+ * 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) {
@@ -334,6 +364,9 @@ export class NeuroLink {
     authInitPromise;
     // Per-provider credential overrides (instance-level default)
     credentials;
+    // Curator P2-3: instance-level fallback policy. Read by
+    // runWithFallbackOrchestration on model-access-denied.
+    fallbackConfig = {};
     /**
      * Merge instance-level credentials with per-call credentials.
      *
@@ -721,6 +754,14 @@ export class NeuroLink {
         if (config?.modelAliasConfig) {
             this.modelAliasConfig = config.modelAliasConfig;
         }
+        // Curator P2-3: capture fallback policy. Per-call options can still
+        // override, but these are the instance-level defaults.
+        if (config?.providerFallback) {
+            this.fallbackConfig.providerFallback = config.providerFallback;
+        }
+        if (config?.modelChain) {
+            this.fallbackConfig.modelChain = config.modelChain;
+        }
         logger.setEventEmitter(this.emitter);
         // Read tool cache duration from environment variables, with a default
         const cacheDurationEnv = process.env.NEUROLINK_TOOL_CACHE_DURATION;
@@ -2324,11 +2365,26 @@ Current user's request: ${currentInput}`;
                 if (traceCtx) {
                     span.parentSpanId = traceCtx.parentSpanId;
                 }
-                // Mark failed generations with ERROR status so metrics count them correctly
-                const spanStatus = data.success === false || data.error
-                    ? SpanStatus.ERROR
-                    : SpanStatus.OK;
-                span = SpanSerializer.endSpan(span, spanStatus, data.error ? String(data.error) : undefined);
+                // Mark failed generations with ERROR status so metrics count them
+                // correctly. Client aborts (data.aborted === true) are NOT failures —
+                // they are user-initiated cancellations and must not pollute the
+                // failure rate. Map them to WARNING with the canonical
+                // "Generation aborted by client" message (matches the Langfuse
+                // ContextEnricher mapping for outer/internal generation spans).
+                let spanStatus;
+                let statusMessage;
+                if (data.aborted === true) {
+                    spanStatus = SpanStatus.WARNING;
+                    statusMessage = "Generation aborted by client";
+                }
+                else if (data.success === false || data.error) {
+                    spanStatus = SpanStatus.ERROR;
+                    statusMessage = data.error ? String(data.error) : undefined;
+                }
+                else {
+                    spanStatus = SpanStatus.OK;
+                }
+                span = SpanSerializer.endSpan(span, spanStatus, statusMessage);
                 span.durationMs = responseTime;
                 // G2 fix: Check finishReason and escalate to WARNING for partial failures
                 const finishReason = result?.finishReason ??
@@ -2654,7 +2710,121 @@ Current user's request: ${currentInput}`;
      * @since 1.0.0
      */
     async generate(optionsOrPrompt) {
-        return tracers.sdk.startActiveSpan("neurolink.generate", { kind: SpanKind.INTERNAL }, (generateSpan) => this.executeGenerateWithMetricsContext(optionsOrPrompt, generateSpan));
+        return this.runWithFallbackOrchestration(optionsOrPrompt, "generate", (opts) => tracers.sdk.startActiveSpan("neurolink.generate", { kind: SpanKind.INTERNAL }, (generateSpan) => this.executeGenerateWithMetricsContext(opts, generateSpan)));
+    }
+    /**
+     * Curator P2-3: wraps a generate/stream call with the fallback
+     * orchestration (`providerFallback` callback + `modelChain` walker).
+     *
+     * On a model-access-denied error from the inner call:
+     *  1. Resolve the effective callback (per-call > instance > synthesised
+     *     from modelChain) and the effective chain (per-call > instance).
+     *  2. Walk attempts: invoke callback (or pop next chain entry) → emit
+     *     `model.fallback` event → re-call inner with the new {provider,
+     *     model}.
+     *  3. Stop on first success, on a callback returning null, or after
+     *     exhausting the chain (throw the most recent error).
+     */
+    async runWithFallbackOrchestration(optionsOrPrompt, kind, inner) {
+        const initialAttempt = await this.attemptInner(inner, optionsOrPrompt);
+        if ("ok" in initialAttempt) {
+            return initialAttempt.ok;
+        }
+        let lastError = initialAttempt.error;
+        if (!looksLikeModelAccessDenied(lastError)) {
+            throw lastError;
+        }
+        // Build the chain orchestration.
+        const requestedProvider = (typeof optionsOrPrompt === "object"
+            ? optionsOrPrompt.provider
+            : undefined);
+        const requestedModel = (typeof optionsOrPrompt === "object"
+            ? optionsOrPrompt.model
+            : undefined);
+        const callOpts = typeof optionsOrPrompt === "object"
+            ? optionsOrPrompt
+            : {};
+        const perCallCallback = callOpts.providerFallback;
+        const perCallChain = callOpts.modelChain;
+        const effectiveCallback = perCallCallback ?? this.fallbackConfig.providerFallback;
+        const effectiveChain = perCallChain ?? this.fallbackConfig.modelChain;
+        if (!effectiveCallback && !effectiveChain) {
+            throw lastError;
+        }
+        // Synthesise a callback from modelChain if no explicit callback exists.
+        const chainCursor = { i: 0, list: effectiveChain ?? [] };
+        const synthesizedFromChain = async () => {
+            while (chainCursor.i < chainCursor.list.length) {
+                const next = chainCursor.list[chainCursor.i++];
+                if (next !== requestedModel) {
+                    return { model: next };
+                }
+            }
+            return null;
+        };
+        const callback = effectiveCallback ?? synthesizedFromChain;
+        let attempts = 0;
+        const maxAttempts = (effectiveChain?.length ?? 0) + 5;
+        let attemptedRequestedModel = requestedModel;
+        while (attempts++ < maxAttempts) {
+            let next;
+            try {
+                next = await callback(lastError);
+            }
+            catch (cbErr) {
+                logger.warn("[NeuroLink] providerFallback callback threw", {
+                    error: cbErr instanceof Error ? cbErr.message : String(cbErr),
+                });
+                throw lastError;
+            }
+            if (!next) {
+                throw lastError;
+            }
+            // Emit model.fallback event so cost/audit listeners can record it.
+            try {
+                this.emitter.emit("model.fallback", {
+                    requestedProvider,
+                    requestedModel: attemptedRequestedModel,
+                    fallbackProvider: next.provider ?? requestedProvider,
+                    fallbackModel: next.model,
+                    reason: lastError instanceof Error ? lastError.message : String(lastError),
+                    kind,
+                    timestamp: Date.now(),
+                });
+            }
+            catch {
+                /* listener errors are non-fatal */
+            }
+            const retriedOptions = typeof optionsOrPrompt === "object"
+                ? {
+                    ...optionsOrPrompt,
+                    ...(next.provider && { provider: next.provider }),
+                    ...(next.model && { model: next.model }),
+                    // Strip the fallback hooks so the retry doesn't re-orchestrate.
+                    providerFallback: undefined,
+                    modelChain: undefined,
+                }
+                : optionsOrPrompt;
+            const retryAttempt = await this.attemptInner(inner, retriedOptions);
+            if ("ok" in retryAttempt) {
+                return retryAttempt.ok;
+            }
+            lastError = retryAttempt.error;
+            attemptedRequestedModel = next.model ?? attemptedRequestedModel;
+            if (!looksLikeModelAccessDenied(lastError)) {
+                throw lastError;
+            }
+        }
+        throw lastError;
+    }
+    async attemptInner(inner, options) {
+        try {
+            const ok = await inner(options);
+            return { ok };
+        }
+        catch (error) {
+            return { error };
+        }
     }
     async executeGenerateWithMetricsContext(optionsOrPrompt, generateSpan) {
         return metricsTraceContextStorage.run(this.createMetricsTraceContext(), () => this.executeGenerateRequest(optionsOrPrompt, generateSpan));
@@ -2674,10 +2844,22 @@ Current user's request: ${currentInput}`;
             return result;
         }
         catch (error) {
-            generateSpan.setStatus({
-                code: SpanStatusCode.ERROR,
-                message: error instanceof Error ? error.message : String(error),
-            });
+            // Match the inner-span discrimination: client aborts are user-initiated
+            // cancellations, not faults. Mark with finishReason=aborted and skip
+            // ERROR status so ContextEnricher routes the outer trace to
+            // langfuse.level=WARNING (matches Curator telemetry-gaps Issue 5a). All
+            // other errors keep the existing ERROR status + recordException pair.
+            if (isAbortError(error)) {
+                generateSpan.setAttribute("ai.finishReason", "aborted");
+                generateSpan.setAttribute("neurolink.aborted", true);
+            }
+            else {
+                generateSpan.recordException(error instanceof Error ? error : new Error(String(error)));
+                generateSpan.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
             // G7 fix: Distinguish context overflow errors with dedicated attributes
             if (error instanceof ContextBudgetExceededError) {
                 generateSpan.setAttribute("neurolink.error.type", "context_overflow");
@@ -2972,6 +3154,11 @@ Current user's request: ${currentInput}`;
         const errModel = typeof optionsOrPrompt === "object"
             ? optionsOrPrompt.model || "unknown"
             : "unknown";
+        // Distinguish client aborts from real failures so consumers (and Langfuse)
+        // can route them differently. `aborted: true` is additive — `success`
+        // remains false for backwards-compat with existing listeners that only
+        // branch on the boolean.
+        const aborted = isAbortError(error);
         try {
             this.emitter.emit("generation:end", {
                 provider: errProvider,
@@ -2979,6 +3166,7 @@ Current user's request: ${currentInput}`;
                 responseTime: 0,
                 error: error instanceof Error ? error.message : String(error),
                 success: false,
+                aborted,
             });
         }
         catch (emitError) {
@@ -3326,10 +3514,23 @@ Current user's request: ${currentInput}`;
             return await this.runGenerateTextInternalFlow(options, internalSpan, context);
         }
         catch (error) {
-            internalSpan.setStatus({
-                code: SpanStatusCode.ERROR,
-                message: error instanceof Error ? error.message : String(error),
-            });
+            // Client aborts are user-initiated cancellations, not system faults.
+            // Setting status=ERROR forces Langfuse to level=ERROR (see
+            // ContextEnricher.onEnd → instrumentation.ts:691). Instead leave status
+            // unset and stamp ai.finishReason=aborted so applyNonErrorLangfuseLevel
+            // maps it to level=WARNING with the canonical "Generation aborted by
+            // client" status_message. Matches Curator telemetry-gaps Issue 5a.
+            if (isAbortError(error)) {
+                internalSpan.setAttribute("ai.finishReason", "aborted");
+                internalSpan.setAttribute("neurolink.aborted", true);
+            }
+            else {
+                internalSpan.recordException(error instanceof Error ? error : new Error(String(error)));
+                internalSpan.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
             throw error;
         }
         finally {
@@ -3385,6 +3586,13 @@ Current user's request: ${currentInput}`;
             if (recoveredResult) {
                 return recoveredResult;
             }
+            // Convert raw DOMException AbortErrors (and other untyped abort shapes)
+            // into NeuroLinkError(ABORT) so callers can branch on
+            // `error.category === ErrorCategory.ABORT` instead of message matching.
+            // Skipped if the error is already a typed abort to avoid double-wrap.
+            if (isAbortError(error) && !(error instanceof NeuroLinkError)) {
+                throw ErrorFactory.aborted(error instanceof Error ? error : new Error(String(error)));
+            }
             throw error;
         }
     }
@@ -3442,28 +3650,24 @@ Current user's request: ${currentInput}`;
             return recoveredResult;
         }
         if (isAbortError(error)) {
-            logger.info(`[${context.functionTag}] Generation aborted — storing conversation turn for title generation`, {
+            // Aborted generations DO NOT write to conversation memory.
+            // Fabricating an assistant turn out of an error condition (the previous
+            // "[generation was interrupted]" sentinel) pollutes the next prompt and
+            // — at the right shape — causes the model to echo the sentinel as its
+            // response. See Curator SI-069 / SI-071. Aborts are signalled to
+            // callers via the thrown error and the "error" emitter event below;
+            // there is nothing to persist, so persisting nothing is correct.
+            //
+            // Title generation continues to work: it reads the user message of the
+            // first *successful* turn (RedisConversationMemoryManager
+            // .generateConversationTitle) and never required a fabricated assistant
+            // turn — the previous comment claiming otherwise was inaccurate.
+            logger.info(`[${context.functionTag}] Generation aborted — skipping memory write (aborts must not pollute conversation history)`, {
                 hasMemory: !!this.conversationMemory,
                 memoryType: this.conversationMemory?.constructor?.name || "NONE",
                 sessionId: options.context?.sessionId ||
                     "unknown",
             });
-            try {
-                const abortedResult = {
-                    content: "[generation was interrupted]",
-                    provider: options.provider || "unknown",
-                    model: options.model || "unknown",
-                    responseTime: Date.now() - context.generateInternalStartTime,
-                };
-                await withTimeout(storeConversationTurn(this.conversationMemory, options, abortedResult, new Date(context.generateInternalStartTime), context.requestId), 5000);
-            }
-            catch (storeError) {
-                logger.warn(`[${context.functionTag}] Failed to store conversation turn after abort`, {
-                    error: storeError instanceof Error
-                        ? storeError.message
-                        : String(storeError),
-                });
-            }
         }
         else {
             logger.error(`[${context.functionTag}] All generation methods failed`, {
@@ -3471,7 +3675,14 @@ Current user's request: ${currentInput}`;
             });
         }
         this.emitter.emit("response:end", "");
-        this.emitter.emit("error", error instanceof Error ? error : new Error(String(error)));
+        // Node EventEmitter rethrows the original error from emit("error", e) if
+        // there is no listener registered, which would short-circuit the caller's
+        // catch block and prevent the abort-typed-error wrap from running. Only
+        // emit when a consumer is listening; non-listening callers receive the
+        // error via the thrown rejection instead, which is the canonical path.
+        if (this.emitter.listenerCount("error") > 0) {
+            this.emitter.emit("error", error instanceof Error ? error : new Error(String(error)));
+        }
         return null;
     }
     async tryRecoverGenerateTextOverflow(options, functionTag, error) {
@@ -4510,7 +4721,128 @@ Current user's request: ${currentInput}`;
                 : [],
             optionKeys: Object.keys(options),
         });
-        return metricsTraceContextStorage.run(this.createMetricsTraceContext(), () => this.executeStreamRequest({ ...options }));
+        return this.streamWithIterationFallback(options);
+    }
+    /**
+     * Curator P2-3 / Reviewer Finding #2: stream-fallback that also covers
+     * errors thrown during async iteration (e.g. LiteLLM throwing inside
+     * `createLiteLLMTransformedStream`). The standard
+     * `runWithFallbackOrchestration` only catches errors thrown while the
+     * `StreamResult` is being created — once we hand the iterator back to
+     * the caller, errors raised during consumption used to bypass
+     * `providerFallback` / `modelChain`.
+     *
+     * This wrapper runs the orchestration to get an initial StreamResult,
+     * then wraps `result.stream` so that:
+     *   - chunks are forwarded transparently while consumption succeeds
+     *   - if iteration throws a model-access-denied error AND no chunks
+     *     have been yielded yet, we resolve the next fallback target,
+     *     emit `model.fallback`, and recurse
+     *   - if chunks were already yielded, the error propagates (mid-stream
+     *     recovery isn't safe — the consumer has half a response)
+     */
+    async streamWithIterationFallback(options) {
+        const result = await this.runWithFallbackOrchestration(options, "stream", (opts) => metricsTraceContextStorage.run(this.createMetricsTraceContext(), () => this.executeStreamRequest({ ...opts })));
+        const callOpts = options;
+        const perCallCallback = callOpts.providerFallback;
+        const perCallChain = callOpts.modelChain;
+        const effectiveCallback = perCallCallback ?? this.fallbackConfig.providerFallback;
+        const effectiveChain = perCallChain ?? this.fallbackConfig.modelChain;
+        if (!effectiveCallback && !effectiveChain) {
+            // No fallback configured — nothing to wrap.
+            return result;
+        }
+        // Build a chain cursor scoped to this stream's lifetime; consumers
+        // who set up `modelChain` get sequential progression here too.
+        const chainCursor = {
+            i: 0,
+            list: effectiveChain ?? [],
+            requestedModel: options.model,
+        };
+        const callback = effectiveCallback ??
+            (async () => {
+                while (chainCursor.i < chainCursor.list.length) {
+                    const next = chainCursor.list[chainCursor.i++];
+                    if (next !== chainCursor.requestedModel) {
+                        return { model: next };
+                    }
+                }
+                return null;
+            });
+        const self = this;
+        // Yield type is the original stream's element type, threaded through
+        // as unknown — we forward chunks unchanged so structural identity is
+        // preserved without a local type alias (CLAUDE.md rule 2).
+        const wrappedStream = (async function* () {
+            let yielded = 0;
+            let currentResult = result;
+            let attemptedRequestedProvider = options.provider;
+            let attemptedRequestedModel = options.model;
+            const maxAttempts = (effectiveChain?.length ?? 0) + 5;
+            for (let attempt = 0; attempt <= maxAttempts; attempt++) {
+                try {
+                    for await (const chunk of currentResult.stream) {
+                        yielded++;
+                        yield chunk;
+                    }
+                    return;
+                }
+                catch (err) {
+                    if (yielded > 0 || !looksLikeModelAccessDenied(err)) {
+                        throw err;
+                    }
+                    let next;
+                    try {
+                        next = await callback(err);
+                    }
+                    catch (cbErr) {
+                        logger.warn("[NeuroLink.stream] providerFallback callback threw during iteration", {
+                            error: cbErr instanceof Error ? cbErr.message : String(cbErr),
+                        });
+                        throw err;
+                    }
+                    if (!next) {
+                        throw err;
+                    }
+                    try {
+                        self.emitter.emit("model.fallback", {
+                            requestedProvider: attemptedRequestedProvider,
+                            requestedModel: attemptedRequestedModel,
+                            fallbackProvider: next.provider ?? attemptedRequestedProvider,
+                            fallbackModel: next.model,
+                            reason: err instanceof Error ? err.message : String(err),
+                            kind: "stream",
+                            phase: "iteration",
+                            timestamp: Date.now(),
+                        });
+                    }
+                    catch {
+                        /* listener errors are non-fatal */
+                    }
+                    const retriedOptions = {
+                        ...options,
+                        ...(next.provider && {
+                            provider: next.provider,
+                        }),
+                        ...(next.model && { model: next.model }),
+                        // Strip the hooks so the inner orchestration doesn't double-fall-back.
+                        providerFallback: undefined,
+                        modelChain: undefined,
+                    };
+                    attemptedRequestedProvider =
+                        next.provider ?? attemptedRequestedProvider;
+                    attemptedRequestedModel = next.model ?? attemptedRequestedModel;
+                    currentResult = await metricsTraceContextStorage.run(self.createMetricsTraceContext(), () => self.executeStreamRequest({ ...retriedOptions }));
+                }
+            }
+            // Exhausted attempts — re-throw the most recent error captured by
+            // the inner loop. We only get here if the loop didn't return.
+            throw new Error(`[NeuroLink.stream] iteration fallback exhausted ${maxAttempts} attempts`);
+        })();
+        return {
+            ...result,
+            stream: wrappedStream,
+        };
     }
     async executeStreamRequest(options) {
         // Dynamic argument resolution — resolve any function-valued options before downstream use
@@ -5701,8 +6033,12 @@ Current user's request: ${currentInput}`;
      * **Generation Events:**
      * - `generation:start` - Fired when text generation begins
      *   - `{ provider: string, timestamp: number }`
-     * - `generation:end` - Fired when text generation completes
-     *   - `{ provider: string, responseTime: number, toolsUsed?: string[], timestamp: number }`
+     * - `generation:end` - Fired when text generation completes (or fails / is aborted)
+     *   - `{ provider: string, responseTime: number, toolsUsed?: string[], timestamp: number, success?: boolean, aborted?: boolean, error?: string }`
+     *   - `success` is `false` for both failures and client aborts; `aborted: true`
+     *     distinguishes the latter so consumers can route cancellations
+     *     differently from real errors. Pipeline B's metrics span maps
+     *     `aborted: true` events to `SpanStatus.WARNING` (not ERROR).
      *
      * **Streaming Events:**
      * - `stream:start` - Fired when streaming begins
@@ -6643,7 +6979,13 @@ Current user's request: ${currentInput}`;
         prepared.metrics.errorCategories[category] =
             (prepared.metrics.errorCategories[category] || 0) + 1;
         this.emitToolEndEvent(toolName, executionContext.executionStartTime, false, undefined, structuredError);
-        this.emitter.emit("error", structuredError);
+        // Gate on listenerCount: Node EventEmitter rethrows the original error
+        // from emit("error", e) when no listener is registered, which would
+        // short-circuit the surrounding flow and surface as an unhandled
+        // rejection. Same pattern as handleGenerateTextInternalFailure.
+        if (this.emitter.listenerCount("error") > 0) {
+            this.emitter.emit("error", structuredError);
+        }
         structuredError = new NeuroLinkError({
             ...structuredError,
             context: {
@@ -6806,13 +7148,19 @@ Current user's request: ${currentInput}`;
                     result.success === false) {
                     const errorMessage = result.error || "Tool execution failed";
                     const errorToEmit = new Error(errorMessage);
-                    this.emitter.emit("error", errorToEmit);
+                    // Gate on listenerCount — see handleGenerateTextInternalFailure for
+                    // the rationale (Node EventEmitter rethrows on no listener).
+                    if (this.emitter.listenerCount("error") > 0) {
+                        this.emitter.emit("error", errorToEmit);
+                    }
                 }
                 return result;
             }
             catch (error) {
                 const errorToEmit = error instanceof Error ? error : new Error(String(error));
-                this.emitter.emit("error", errorToEmit);
+                if (this.emitter.listenerCount("error") > 0) {
+                    this.emitter.emit("error", errorToEmit);
+                }
                 // Check if tool was not found
                 if (error instanceof Error && error.message.includes("not found")) {
                     const availableTools = await this.getAllAvailableTools();

package/dist/types/config.d.ts

@@ -21,6 +21,16 @@ export type NeuroLinkConfig = {
     configVersion?: string;
     [key: string]: unknown;
 };
+/**
+ * Curator P2-3: callback signature for centralized fallback policy. Invoked
+ * when a generate/stream call fails with what looks like a model-access-denied
+ * error. Return `{ provider, model }` (either / both optional) to drive a
+ * retry; return `null` to bubble the original error untouched.
+ */
+export type ProviderFallbackCallback = (error: unknown) => Promise<{
+    provider?: string;
+    model?: string;
+} | null>;
 /**
  * Configuration object for NeuroLink constructor.
  */
@@ -43,6 +53,19 @@ export type NeurolinkConstructorConfig = {
      * from this NeuroLink instance. Per-call credentials override these.
      */
     credentials?: NeurolinkCredentials;
+    /**
+     * Curator P2-3: callback invoked on model-access-denied. Lets a host (e.g.
+     * Curator) centrally drive fallback policy. The callback receives the
+     * original error and returns the next `{ provider, model }` to try, or
+     * `null` to bubble the error.
+     */
+    providerFallback?: ProviderFallbackCallback;
+    /**
+     * Curator P2-3: ordered list of model names to try in sequence on
+     * model-access-denied. Sugar over `providerFallback`. The current
+     * provider is preserved across the chain; only the model name changes.
+     */
+    modelChain?: string[];
 };
 /**
  * Configuration for MCP enhancement modules wired into generate()/stream() paths.

package/dist/types/generate.d.ts

@@ -447,6 +447,19 @@ export type GenerateOptions = {
      * Unset providers fall through to instance credentials, then environment variables.
      */
     credentials?: NeurolinkCredentials;
+    /**
+     * Curator P2-3: per-call fallback callback. Overrides any
+     * instance-level `providerFallback` set on `new NeuroLink({...})`.
+     */
+    providerFallback?: (error: unknown) => Promise<{
+        provider?: string;
+        model?: string;
+    } | null>;
+    /**
+     * Curator P2-3: per-call ordered model chain. Overrides any
+     * instance-level `modelChain`. Tried in order on model-access-denied.
+     */
+    modelChain?: string[];
     /**
      * Per-call memory control.
      *

package/dist/types/stream.d.ts

@@ -445,6 +445,19 @@ export type StreamOptions = {
      * Unset providers fall through to instance credentials, then environment variables.
      */
     credentials?: NeurolinkCredentials;
+    /**
+     * Curator P2-3: per-call fallback callback. Overrides any
+     * instance-level `providerFallback` set on `new NeuroLink({...})`.
+     */
+    providerFallback?: (error: unknown) => Promise<{
+        provider?: string;
+        model?: string;
+    } | null>;
+    /**
+     * Curator P2-3: per-call ordered model chain. Overrides any
+     * instance-level `modelChain`. Tried in order on model-access-denied.
+     */
+    modelChain?: string[];
     /**
      * Per-call memory control.
      *

package/dist/utils/conversationMemory.d.ts

@@ -5,6 +5,16 @@
 import type { ConversationMemoryManager } from "../core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "../core/redisConversationMemoryManager.js";
 import type { ChatMessage, ConversationMemoryConfig, SessionMemory, TextGenerationOptions, TextGenerationResult } from "../types/index.js";
+/**
+ * Legacy sentinel string formerly written by the abort branch of
+ * handleGenerateTextInternalFailure (Curator SI-069 / SI-071). The producer is
+ * removed in this fix, but historical Redis sessions may still contain entries
+ * with this content. Filtered at the prompt-builder boundary so they never
+ * reach the provider — sessions self-heal on the next read without any
+ * migration. Keep in sync with any future renames; do not remove without a
+ * cross-repo grep.
+ */
+export declare const ABORT_LEGACY_SENTINEL = "[generation was interrupted]";
 /**
  * Apply conversation memory defaults to user configuration
  * Merges user config with environment variables and default values