@juspay/neurolink 9.57.0 → 9.58.0

package/dist/lib/utils/conversationMemory.js

@@ -10,6 +10,85 @@ import { getAvailableInputTokens } from "../constants/contextWindows.js";
 import { buildSummarizationPrompt } from "../context/prompts/summarizationPrompt.js";
 import { logger } from "./logger.js";
 const memoryTracer = tracers.memory;
+/**
+ * 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 const ABORT_LEGACY_SENTINEL = "[generation was interrupted]";
+/**
+ * Tracks session IDs that have already emitted the
+ * "Dropped polluted assistant turns" warn log so we log once per session
+ * (not on every retrieval). The span attribute
+ * `neurolink.memory.polluted_turns_dropped` is still set every call, so
+ * Langfuse traces show the cleanup happening continuously even after the
+ * log is suppressed. Bounded to avoid unbounded growth on busy services —
+ * when capacity is reached the set is cleared (cheap) and warning resumes
+ * as if those sessions are new, which is acceptable behaviour.
+ */
+const POLLUTED_WARN_DEDUP_MAX = 1024;
+const pollutedWarnedSessions = new Set();
+/**
+ * True if a stored assistant turn looks like it was carrying tool activity
+ * (and is therefore safe to keep even with empty text content). storeTurn
+ * paths historically populate one of several fields depending on which
+ * provider/codepath wrote it, so this checks all of them. Mirrored across
+ * read filter + storage guard for symmetry.
+ *
+ *   - `msg.events` — stream-path event sequence (`tool:start`, `tool:end`)
+ *   - `msg.tool` / `msg.args` — assistant turn that invoked a tool by name
+ *   - `msg.result` — tool result attached to the assistant turn
+ *
+ * If none of these are set, the assistant turn is text-only.
+ *
+ * Named with the `message` prefix to avoid shadowing the local
+ * `hasToolActivity` boolean inside `storeConversationTurn` below — the two
+ * answer different questions (one inspects a stored message, the other
+ * inspects a live result object).
+ */
+function messageHasToolActivity(msg) {
+    if (msg.tool || msg.args || msg.result) {
+        return true;
+    }
+    const events = msg.events;
+    if (!Array.isArray(events)) {
+        return false;
+    }
+    return events.some((e) => {
+        const type = e?.type;
+        return type === "tool:start" || type === "tool:end";
+    });
+}
+/**
+ * Decides whether an assistant turn loaded from conversation memory is safe to
+ * include in the prompt sent to the provider. Drops:
+ *   - empty / whitespace-only text content with no tool activity
+ *   - the legacy abort sentinel — but only when the turn carries no tool
+ *     activity, mirroring the storeConversationTurn upper-layer guard so a
+ *     hypothetical tool-call-then-aborted turn doesn't lose its tool half
+ * tool_call and tool_result role messages are always preserved — they
+ * legitimately carry empty `content` (see redisConversationMemoryManager.ts:1870
+ * "Can be empty for tool calls"). Filtering them would break tool-pair
+ * semantics that downstream `repairToolPairs` relies on.
+ */
+function isPollutedAssistantTurn(msg) {
+    if (msg.role !== "assistant") {
+        return false;
+    }
+    const content = typeof msg.content === "string" ? msg.content : "";
+    const trimmed = content.trim();
+    if (trimmed === ABORT_LEGACY_SENTINEL) {
+        return !messageHasToolActivity(msg);
+    }
+    if (trimmed === "") {
+        return !messageHasToolActivity(msg);
+    }
+    return false;
+}
 // Cached NeuroLink instance for summarization to avoid creating a new instance per call
 let cachedSummarizer = null;
 /**
@@ -66,12 +145,49 @@ export async function getConversationMessages(conversationMemory, options) {
                 span.setAttribute("user.id", userId);
             }
             const enableSummarization = options.enableSummarization ?? undefined;
-            const messages = await conversationMemory.buildContextMessages(sessionId, userId, enableSummarization);
+            const rawMessages = await conversationMemory.buildContextMessages(sessionId, userId, enableSummarization);
+            // Read-time filter: drop assistant turns that are empty/whitespace or
+            // carry the legacy abort sentinel before they reach the provider.
+            // Self-heals historical Redis sessions polluted by the now-removed
+            // abort-path memory write (Curator SI-069 / SI-071) and defends
+            // against any future "fabricate-on-error" regression. Telemetry
+            // attributes record how many turns were dropped so polluted sessions
+            // are visible in Langfuse traces.
+            const messages = rawMessages.filter((msg) => !isPollutedAssistantTurn(msg));
+            const droppedCount = rawMessages.length - messages.length;
+            if (droppedCount > 0) {
+                // Span attribute is always set so polluted sessions stay visible in
+                // Langfuse traces on every read — that's the persistent debugging
+                // signal. The warn log is deduped per session so a long-lived
+                // polluted conversation only generates one log line, not one per
+                // turn (would otherwise be noisy at scale).
+                span.setAttribute("neurolink.memory.polluted_turns_dropped", droppedCount);
+                const alreadyWarned = pollutedWarnedSessions.has(sessionId);
+                if (!alreadyWarned) {
+                    if (pollutedWarnedSessions.size >= POLLUTED_WARN_DEDUP_MAX) {
+                        pollutedWarnedSessions.clear();
+                    }
+                    pollutedWarnedSessions.add(sessionId);
+                    logger.warn("[conversationMemoryUtils] Dropped polluted assistant turns from prompt context (logged once per session — span attribute records every read)", {
+                        sessionId,
+                        droppedCount,
+                        remainingCount: messages.length,
+                    });
+                }
+                else {
+                    logger.debug("[conversationMemoryUtils] Dropped polluted assistant turns (warn already logged for this session)", {
+                        sessionId,
+                        droppedCount,
+                        remainingCount: messages.length,
+                    });
+                }
+            }
             span.setAttribute("message.count", messages.length);
             if (logger.shouldLog("debug")) {
                 logger.debug("[conversationMemoryUtils] Conversation messages retrieved successfully", {
                     sessionId,
                     messageCount: messages.length,
+                    droppedPollutedCount: droppedCount,
                     messageTypes: messages.map((m) => m.role),
                 });
             }
@@ -147,6 +263,19 @@ export async function storeConversationTurn(conversationMemory, originalOptions,
         });
         return;
     }
+    // Belt-and-braces guard against the abort sentinel (Curator SI-069 / SI-071).
+    // The abort path itself was fixed in handleGenerateTextInternalFailure to
+    // never call this function, but we reject the legacy sentinel here too so a
+    // future regression cannot re-introduce the same pollution. Tool-bearing
+    // turns are explicitly preserved (the model may call a tool then abort).
+    if (aiResponse.trim() === ABORT_LEGACY_SENTINEL && !hasToolActivity) {
+        logger.warn("[conversationMemoryUtils] Refusing to store legacy abort sentinel — see Curator SI-069 / SI-071", {
+            sessionId,
+            userId,
+            userMessageLength: userMessage.length,
+        });
+        return;
+    }
     let providerDetails;
     if (result.provider && result.model) {
         providerDetails = {
@@ -154,6 +283,60 @@ export async function storeConversationTurn(conversationMemory, originalOptions,
             model: result.model,
         };
     }
+    // Persist a minimal `events` marker only on tool-bearing assistant turns
+    // whose surface text would otherwise trigger the read-time filter (empty /
+    // whitespace-only content). Turns that already have substantive text are
+    // never dropped by isPollutedAssistantTurn, so attaching synthesised events
+    // to them would change the stored shape and token estimation for no
+    // benefit. Sentinel-content turns never reach this point — the upper-layer
+    // guard at line 340 short-circuits them.
+    let toolActivityEvents;
+    if (hasToolActivity && !aiResponse.trim()) {
+        const now = Date.now();
+        const usedNames = new Set();
+        if (Array.isArray(result.toolsUsed)) {
+            for (const t of result.toolsUsed) {
+                if (typeof t === "string" && t) {
+                    usedNames.add(t);
+                }
+            }
+        }
+        if (Array.isArray(result.toolExecutions)) {
+            for (const exec of result.toolExecutions) {
+                const name = exec?.toolName;
+                if (typeof name === "string" && name) {
+                    usedNames.add(name);
+                }
+            }
+        }
+        toolActivityEvents = [];
+        let seq = 0;
+        for (const name of usedNames) {
+            // Match the canonical ToolExecutionEvent shape (src/lib/types/tools.ts):
+            // `tool` is the required field, `toolName` is the documented compat
+            // alias. Populate both so downstream consumers reading either name
+            // work uniformly.
+            toolActivityEvents.push({
+                type: "tool:start",
+                seq: seq++,
+                timestamp: now,
+                tool: name,
+                toolName: name,
+            });
+        }
+        if (toolActivityEvents.length === 0) {
+            // Tool activity reported but no names extractable — still leave a
+            // marker so retrieval doesn't drop the turn. Both `tool` and
+            // `toolName` are populated for the same compat reason.
+            toolActivityEvents.push({
+                type: "tool:start",
+                seq: 0,
+                timestamp: now,
+                tool: "unknown",
+                toolName: "unknown",
+            });
+        }
+    }
     await memoryTracer.startActiveSpan("neurolink.conversation.storeTurn", {
         kind: SpanKind.INTERNAL,
         attributes: {
@@ -174,6 +357,7 @@ export async function storeConversationTurn(conversationMemory, originalOptions,
                 providerDetails,
                 enableSummarization: originalOptions.enableSummarization,
                 requestId,
+                events: toolActivityEvents,
                 tokenUsage: result.usage
                     ? {
                         inputTokens: result.usage.input,

package/dist/lib/utils/errorHandling.d.ts

@@ -17,6 +17,7 @@ export declare const ERROR_CODES: {
     readonly PROVIDER_NOT_AVAILABLE: "PROVIDER_NOT_AVAILABLE";
     readonly PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED";
     readonly PROVIDER_QUOTA_EXCEEDED: "PROVIDER_QUOTA_EXCEEDED";
+    readonly OPERATION_ABORTED: "OPERATION_ABORTED";
     readonly INVALID_CONFIGURATION: "INVALID_CONFIGURATION";
     readonly MISSING_CONFIGURATION: "MISSING_CONFIGURATION";
     readonly INVALID_VIDEO_RESOLUTION: "INVALID_VIDEO_RESOLUTION";
@@ -106,6 +107,18 @@ export declare class ErrorFactory {
      * Create a memory exhaustion error
      */
     static memoryExhausted(toolName: string, memoryUsageMB: number): NeuroLinkError;
+    /**
+     * Create a typed abort error preserving the originating exception. Callers
+     * can switch on `error.category === ErrorCategory.ABORT` and
+     * `error.code === ERROR_CODES.OPERATION_ABORTED` instead of message-string
+     * matching DOMException / AI SDK error wrappers.
+     *
+     * `error.name` is intentionally set to "AbortError" (overriding the default
+     * "NeuroLinkError") so existing callers that branch on
+     * `err.name === "AbortError"` keep working without code changes — the new
+     * structured fields (category, code, retriable) are additive.
+     */
+    static aborted(originalError?: Error): NeuroLinkError;
     /**
      * Create a missing configuration error (e.g., missing API key)
      */

package/dist/lib/utils/errorHandling.js

@@ -23,6 +23,8 @@ export const ERROR_CODES = {
     PROVIDER_NOT_AVAILABLE: "PROVIDER_NOT_AVAILABLE",
     PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED",
     PROVIDER_QUOTA_EXCEEDED: "PROVIDER_QUOTA_EXCEEDED",
+    // Cancellation
+    OPERATION_ABORTED: "OPERATION_ABORTED",
     // Configuration errors
     INVALID_CONFIGURATION: "INVALID_CONFIGURATION",
     MISSING_CONFIGURATION: "MISSING_CONFIGURATION",
@@ -201,6 +203,30 @@ export class ErrorFactory {
             toolName,
         });
     }
+    /**
+     * Create a typed abort error preserving the originating exception. Callers
+     * can switch on `error.category === ErrorCategory.ABORT` and
+     * `error.code === ERROR_CODES.OPERATION_ABORTED` instead of message-string
+     * matching DOMException / AI SDK error wrappers.
+     *
+     * `error.name` is intentionally set to "AbortError" (overriding the default
+     * "NeuroLinkError") so existing callers that branch on
+     * `err.name === "AbortError"` keep working without code changes — the new
+     * structured fields (category, code, retriable) are additive.
+     */
+    static aborted(originalError) {
+        const err = new NeuroLinkError({
+            code: ERROR_CODES.OPERATION_ABORTED,
+            message: originalError?.message || "The operation was aborted",
+            category: ErrorCategory.ABORT,
+            severity: ErrorSeverity.LOW,
+            retriable: false,
+            context: {},
+            originalError,
+        });
+        err.name = "AbortError";
+        return err;
+    }
     // ============================================================================
     // CONFIGURATION ERRORS
     // ============================================================================
@@ -904,6 +930,11 @@ export function isAbortError(error) {
     if (error instanceof Error && error.name === "AbortError") {
         return true;
     }
+    // Typed NeuroLinkError abort - canonical from-now-on shape.
+    if (error instanceof NeuroLinkError &&
+        error.category === ErrorCategory.ABORT) {
+        return true;
+    }
     if (error instanceof Error &&
         (error.message?.includes("This operation was aborted") ||
             error.message?.includes("The operation was aborted") ||

package/dist/neurolink.d.ts

@@ -60,6 +60,7 @@ export declare class NeuroLink {
     private pendingAuthConfig?;
     private authInitPromise?;
     private credentials?;
+    private readonly fallbackConfig;
     /**
      * Merge instance-level credentials with per-call credentials.
      *
@@ -541,6 +542,21 @@ export declare class NeuroLink {
      * @since 1.0.0
      */
     generate(optionsOrPrompt: GenerateOptions | DynamicOptions | string): Promise<GenerateResult>;
+    /**
+     * 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).
+     */
+    private runWithFallbackOrchestration;
+    private attemptInner;
     private executeGenerateWithMetricsContext;
     private executeGenerateRequest;
     private prepareGenerateRequest;
@@ -697,6 +713,25 @@ export declare class NeuroLink {
      * @throws {Error} When conversation memory operations fail (if enabled)
      */
     stream(options: StreamOptions | DynamicOptions): Promise<StreamResult>;
+    /**
+     * 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)
+     */
+    private streamWithIterationFallback;
     private executeStreamRequest;
     private validateStreamRequestOptions;
     private maybeHandleWorkflowStreamRequest;
@@ -881,8 +916,12 @@ export declare class NeuroLink {
      * **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