@juspay/neurolink 11.25.2 → 11.25.4

package/dist/core/baseProvider.d.ts

@@ -4,10 +4,6 @@ import type { NeuroLink } from "../neurolink.js";
 import type { UnknownRecord, MiddlewareFactoryOptions, StreamOptions, StreamResult, AIProvider, AnalyticsData, EnhancedGenerateResult, TextGenerationOptions, TextGenerationResult, ValidationSchema } from "../types/index.js";
 import { TelemetryHandler } from "./modules/TelemetryHandler.js";
 import type { LanguageModel, ModelMessage, Tool, ToolCallRepairFunction, ToolSet } from "../types/index.js";
-/**
- * Abstract base class for all AI providers
- * Tools are integrated as first-class citizens - always available by default
- */
 export declare abstract class BaseProvider implements AIProvider {
     protected modelName: string;
     protected readonly providerName: AIProviderName;
@@ -387,6 +383,56 @@ export declare abstract class BaseProvider implements AIProvider {
      * original identity so that isAbortError() can detect them in
      * retry/fallback loops (directProviderGeneration, performMCPGenerationRetries).
      */
+    /**
+     * Classify an error that escaped while the consumer was ITERATING a stream.
+     *
+     * `stream()` only awaits the CONSTRUCTION of the provider's stream object, and a provider
+     * that discovers its failure lazily throws on first pull instead — so the raw upstream
+     * error reached the consumer with no provider tag and no classification, while the same
+     * failure through `generate()` was classified normally. Measured on OpenAI:
+     *
+     *   streaming      "You have no credits remaining."
+     *   non-streaming  "[openai] OpenAI quota exhausted — this will not resolve by retrying..."
+     *
+     * Three guards. Only the third is load-bearing against today's code; the first two are
+     * deliberate depth against a hazard that is real but not currently reachable. Measured,
+     * rather than assumed — see the note after the list.
+     *
+     * 1. ALREADY STAMPED — everything that went through `handleProviderError` carries the mark,
+     *    including the two formatters whose results escape the ProviderError hierarchy
+     *    (`amazonSagemaker` returns SageMakerError, `replicate` returns NeuroLinkError; both
+     *    extend Error directly). Without this they would be classified a second time and
+     *    degraded.
+     * 2. ALREADY A ProviderError — covers providers that call `formatProviderError` DIRECTLY,
+     *    bypassing `handleProviderError` and therefore the stamp. Anthropic does this in its
+     *    own streaming catch (`anthropic/client.ts`), and its result is a ProviderError.
+     * 3. HAS AN HTTP STATUS — without this, an ordinary bug is relabelled as a provider
+     *    failure. `classifyProviderError` ends in an unconditional catch-all
+     *    (`utils/errorClassifier.ts`: `if (!rule) return new ProviderError(...)`) that is not
+     *    gated on the error having come off the wire. Measured with the guard absent:
+     *      TypeError "Cannot read properties of undefined (reading 'content')"
+     *        became  ProviderError "[openai] openai error: Cannot read properties of undefined..."
+     *    which would hide a real defect behind a plausible provider message.
+     *
+     * WHY 1 AND 2 ARE NOT CURRENTLY REACHABLE, and why they stay anyway. A statusCode is
+     * attached to a formatted error in exactly one place — `handleProviderError` below — and
+     * that same method applies the stamp. So a ProviderError carrying a status is always
+     * stamped (caught by guard 1's own condition), and a ProviderError produced by a direct
+     * `formatProviderError` call carries no status, so guard 3 already returns it untouched.
+     * Verified by disabling guards 1 and 2 together, rebuilding, and re-running: the mocked
+     * provider contract suite stayed 64/64 and a mocked Anthropic streaming 429 was
+     * byte-identical (`RateLimitError`, one `[anthropic]` prefix).
+     *
+     * They remain because the hazard they cover is measured and real: `handleProviderError`
+     * is NOT idempotent — it copies statusCode onto its own output, so a second pass
+     * re-matches the bare 429 rule and DEGRADES the classification:
+     *   pass 1  ProviderError  "...quota exhausted — this will not resolve by retrying..."
+     *   pass 2  RateLimitError "...rate limit exceeded..."
+     * The day any provider attaches a status to an error it formats itself, guard 3 stops
+     * covering that case and this degradation becomes live. Cheap insurance, not dead code —
+     * but do not cite guards 1 and 2 as proven-by-failure the way guard 3 is.
+     */
+    protected classifyStreamError(error: unknown): Error;
     protected handleProviderError(error: unknown): Error;
     /**
      * Image generation method. Providers that support it should override this.

package/dist/core/baseProvider.js

@@ -5,6 +5,7 @@ import { MiddlewareFactory } from "../middleware/factory.js";
 import { modelSupports } from "../models/modelRegistry.js";
 import { ATTR, tracers } from "../telemetry/index.js";
 import { ERROR_CODES, isAbortError, NeuroLinkError, } from "../utils/errorHandling.js";
+import { ProviderError } from "../types/index.js";
 import { sanitizeErrorCause } from "../utils/logSanitize.js";
 import { createAnalytics as buildAnalytics } from "./analytics.js";
 import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
@@ -48,6 +49,47 @@ function getLifecycleMiddlewareConfig(options) {
  * Abstract base class for all AI providers
  * Tools are integrated as first-class citizens - always available by default
  */
+/**
+ * Marks an error as already run through `formatProviderError`.
+ *
+ * `handleProviderError` is NOT idempotent — measured: feeding its own output back in
+ * degrades a specific classification into a generic one, because it copies `statusCode`
+ * onto the formatted error, so a second pass re-matches the bare 429 rule while the more
+ * specific rule (which keyed on the raw body) no longer can:
+ *
+ *   pass 1  ProviderError  "[openai] OpenAI quota exhausted — this will not resolve by retrying..."
+ *   pass 2  RateLimitError "[openai] OpenAI rate limit exceeded. Please try again later."
+ *
+ * Since the stream path can now reach a classifier that other paths already reached, that
+ * second pass became possible and had to be made impossible.
+ *
+ * Same `Symbol.for` stamping technique as `utils/lifecycleCallbacks.ts` and for the same
+ * reason: it survives across module copies where a closed-over WeakSet would not, and a
+ * frozen error degrades to one extra classification rather than a throw.
+ */
+const PROVIDER_ERROR_CLASSIFIED = Symbol.for("neurolink.providerErrorClassified");
+function markProviderErrorClassified(error) {
+    if (error === null || typeof error !== "object") {
+        return;
+    }
+    try {
+        Object.defineProperty(error, PROVIDER_ERROR_CLASSIFIED, {
+            value: true,
+            enumerable: false,
+            writable: false,
+            configurable: false,
+        });
+    }
+    catch {
+        // Non-extensible error — worst case is one redundant classification.
+    }
+}
+function isProviderErrorClassified(error) {
+    if (error === null || typeof error !== "object") {
+        return false;
+    }
+    return error[PROVIDER_ERROR_CLASSIFIED] === true;
+}
 export class BaseProvider {
     // Not `readonly` because providers that auto-discover the model from a
     // /v1/models endpoint (lm-studio, llamacpp) need to update modelName after
@@ -307,10 +349,14 @@ export class BaseProvider {
      */
     wrapStreamWithLifecycleCallbacks(result, options) {
         const lifecycle = getLifecycleMiddlewareConfig(options);
-        if (!lifecycle?.onChunk && !lifecycle?.onFinish && !lifecycle?.onError) {
-            return result;
-        }
-        const { onChunk, onFinish, onError } = lifecycle;
+        // No early return when there are no callbacks. This wrapper is the only point
+        // every provider's stream passes through unconditionally (the real-streaming path
+        // plus all three fake-streaming paths), and returning `result` untouched here is
+        // exactly why a provider error that surfaces during ITERATION reached the consumer
+        // unclassified: the object handed back was the provider's own generator, by
+        // reference, and every layer below is a proven passthrough. The callbacks below are
+        // each individually guarded, so with none registered this only adds the catch.
+        const { onChunk, onFinish, onError } = lifecycle ?? {};
         const startTime = Date.now();
         const originalStream = result.stream;
         // Lifecycle callbacks are awaited with a bounded deadline so callers
@@ -334,6 +380,9 @@ export class BaseProvider {
                 logger.warn(`[lifecycle] ${label} callback error:`, e);
             }
         };
+        // Arrow, like `safeFire` above: the generator is a plain function expression, so
+        // `this` is not bound inside it.
+        const classifyStreamError = (e) => this.classifyStreamError(e);
         const wrappedStream = (async function* () {
             let accumulated = "";
             let seq = 0;
@@ -382,7 +431,7 @@ export class BaseProvider {
                         recoverable: false,
                     }), "onError");
                 }
-                throw err;
+                throw classifyStreamError(err);
             }
         })();
         return { ...result, stream: wrappedStream };
@@ -1573,6 +1622,65 @@ export class BaseProvider {
      * original identity so that isAbortError() can detect them in
      * retry/fallback loops (directProviderGeneration, performMCPGenerationRetries).
      */
+    /**
+     * Classify an error that escaped while the consumer was ITERATING a stream.
+     *
+     * `stream()` only awaits the CONSTRUCTION of the provider's stream object, and a provider
+     * that discovers its failure lazily throws on first pull instead — so the raw upstream
+     * error reached the consumer with no provider tag and no classification, while the same
+     * failure through `generate()` was classified normally. Measured on OpenAI:
+     *
+     *   streaming      "You have no credits remaining."
+     *   non-streaming  "[openai] OpenAI quota exhausted — this will not resolve by retrying..."
+     *
+     * Three guards. Only the third is load-bearing against today's code; the first two are
+     * deliberate depth against a hazard that is real but not currently reachable. Measured,
+     * rather than assumed — see the note after the list.
+     *
+     * 1. ALREADY STAMPED — everything that went through `handleProviderError` carries the mark,
+     *    including the two formatters whose results escape the ProviderError hierarchy
+     *    (`amazonSagemaker` returns SageMakerError, `replicate` returns NeuroLinkError; both
+     *    extend Error directly). Without this they would be classified a second time and
+     *    degraded.
+     * 2. ALREADY A ProviderError — covers providers that call `formatProviderError` DIRECTLY,
+     *    bypassing `handleProviderError` and therefore the stamp. Anthropic does this in its
+     *    own streaming catch (`anthropic/client.ts`), and its result is a ProviderError.
+     * 3. HAS AN HTTP STATUS — without this, an ordinary bug is relabelled as a provider
+     *    failure. `classifyProviderError` ends in an unconditional catch-all
+     *    (`utils/errorClassifier.ts`: `if (!rule) return new ProviderError(...)`) that is not
+     *    gated on the error having come off the wire. Measured with the guard absent:
+     *      TypeError "Cannot read properties of undefined (reading 'content')"
+     *        became  ProviderError "[openai] openai error: Cannot read properties of undefined..."
+     *    which would hide a real defect behind a plausible provider message.
+     *
+     * WHY 1 AND 2 ARE NOT CURRENTLY REACHABLE, and why they stay anyway. A statusCode is
+     * attached to a formatted error in exactly one place — `handleProviderError` below — and
+     * that same method applies the stamp. So a ProviderError carrying a status is always
+     * stamped (caught by guard 1's own condition), and a ProviderError produced by a direct
+     * `formatProviderError` call carries no status, so guard 3 already returns it untouched.
+     * Verified by disabling guards 1 and 2 together, rebuilding, and re-running: the mocked
+     * provider contract suite stayed 64/64 and a mocked Anthropic streaming 429 was
+     * byte-identical (`RateLimitError`, one `[anthropic]` prefix).
+     *
+     * They remain because the hazard they cover is measured and real: `handleProviderError`
+     * is NOT idempotent — it copies statusCode onto its own output, so a second pass
+     * re-matches the bare 429 rule and DEGRADES the classification:
+     *   pass 1  ProviderError  "...quota exhausted — this will not resolve by retrying..."
+     *   pass 2  RateLimitError "...rate limit exceeded..."
+     * The day any provider attaches a status to an error it formats itself, guard 3 stops
+     * covering that case and this degradation becomes live. Cheap insurance, not dead code —
+     * but do not cite guards 1 and 2 as proven-by-failure the way guard 3 is.
+     */
+    classifyStreamError(error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        if (isProviderErrorClassified(err) || err instanceof ProviderError) {
+            return err;
+        }
+        if (duckTypedStatusCode(err) === undefined) {
+            return err;
+        }
+        return this.handleProviderError(err);
+    }
     handleProviderError(error) {
         if (isAbortError(error)) {
             // Preserve AbortError identity — never wrap in provider-specific formatting
@@ -1644,6 +1752,10 @@ export class BaseProvider {
         catch {
             // Non-blocking — telemetry failures shouldn't mask the original error
         }
+        // Stamp AFTER formatting so any later catch site can tell this error has
+        // already been classified. Deliberately not applied to the AbortError
+        // passthrough above — that returns the original error untouched.
+        markProviderErrorClassified(formatted);
         return formatted;
     }
     /**

package/dist/localUsage/claudeCodeReader.js

@@ -27,8 +27,8 @@ import { readdir, stat } from "fs/promises";
 import { homedir } from "os";
 import { join } from "path";
 import { calculateCost, hasPricing } from "../utils/pricing.js";
+import { resolveScanCutoffMs } from "./scanWindow.js";
 const CLI_ID = "claude-code";
-const DEFAULT_SINCE_DAYS = 30;
 const PROVIDER = "anthropic";
 function projectsRoot() {
     return join(homedir(), ".claude", "projects");
@@ -190,11 +190,7 @@ export async function createClaudeCodeReader() {
             // 32.8s — the same unbounded sweep this guard exists to prevent, reached
             // by a different door. The old guard caught it with Number.isFinite and
             // the replacement dropped that check.
-            const requestedDays = options?.sinceDays ?? DEFAULT_SINCE_DAYS;
-            const sinceDays = Number.isNaN(requestedDays) ? 0 : requestedDays;
-            const cutoff = sinceDays === Infinity
-                ? undefined
-                : Date.now() - Math.max(0, sinceDays) * 86_400_000;
+            const cutoff = resolveScanCutoffMs(options?.sinceDays);
             let filesScanned = 0;
             for (const file of files) {
                 try {

package/dist/localUsage/codexReader.js

@@ -31,8 +31,8 @@ import { createInterface } from "readline";
 import { readdir, stat } from "fs/promises";
 import { homedir } from "os";
 import { join } from "path";
+import { resolveScanCutoffMs } from "./scanWindow.js";
 const CLI_ID = "codex";
-const DEFAULT_SINCE_DAYS = 30;
 function sessionsRoot() {
     return join(homedir(), ".codex", "sessions");
 }
@@ -178,11 +178,7 @@ export async function createCodexReader() {
             // 32.8s — the same unbounded sweep this guard exists to prevent, reached
             // by a different door. The old guard caught it with Number.isFinite and
             // the replacement dropped that check.
-            const requestedDays = options?.sinceDays ?? DEFAULT_SINCE_DAYS;
-            const sinceDays = Number.isNaN(requestedDays) ? 0 : requestedDays;
-            const cutoff = sinceDays === Infinity
-                ? undefined
-                : Date.now() - Math.max(0, sinceDays) * 86_400_000;
+            const cutoff = resolveScanCutoffMs(options?.sinceDays);
             let filesScanned = 0;
             for (const file of files) {
                 try {

package/dist/localUsage/openCodeReader.js

@@ -35,8 +35,8 @@
 import { stat } from "fs/promises";
 import { homedir } from "os";
 import { join } from "path";
+import { resolveScanCutoffMs } from "./scanWindow.js";
 const CLI_ID = "opencode";
-const DEFAULT_SINCE_DAYS = 30;
 function databasePath() {
     return join(homedir(), ".local", "share", "opencode", "opencode.db");
 }
@@ -131,11 +131,9 @@ export async function createOpenCodeReader() {
             // "no such column: NaN" — so the whole scan failed rather than
             // over-reading. The cutoff is a bound parameter now, so a value can
             // never be SQL syntax whatever it is.
-            const requestedDays = options?.sinceDays ?? DEFAULT_SINCE_DAYS;
-            const sinceDays = Number.isNaN(requestedDays) ? 0 : requestedDays;
-            const cutoffMs = sinceDays === Infinity
-                ? 0
-                : Date.now() - Math.max(0, sinceDays) * 86_400_000;
+            // `?? 0` because this value becomes a SQL parameter: an unbounded scan
+            // is expressed as "since the epoch", never as a non-finite number.
+            const cutoffMs = resolveScanCutoffMs(options?.sinceDays) ?? 0;
             let db;
             try {
                 // Read-only: this is the user's live store and OpenCode may be running.

package/dist/localUsage/scanWindow.d.ts

@@ -0,0 +1,29 @@
+/**
+ * One definition of "how far back does a local-usage scan reach".
+ *
+ * This calculation lived in three copies — claudeCodeReader, codexReader and
+ * openCodeReader — and has been wrong three separate times, each a different
+ * door into the same failure: an unbounded sweep of every transcript on the
+ * machine in answer to the narrowest possible request.
+ *
+ *   sinceDays: 0          left the cutoff undefined       17,534 files, 35.9s
+ *   sinceDays: NaN        Math.max(0, NaN) is NaN, and every comparison
+ *                         against NaN is false, so the filter passed
+ *                         everything                       17,537 files, 32.8s
+ *   sinceDays: MAX_VALUE  MAX_VALUE * 86_400_000 overflows to Infinity, so the
+ *                         cutoff became -Infinity and every file passed
+ *
+ * Three fixes in three files each closed one door and left the others open.
+ * The logic lives here once now, so the next door closes everywhere at once.
+ *
+ * Contract: `Infinity` is the ONLY value meaning all-history. Anything that is
+ * not a usable finite window — NaN, negative, or so large the arithmetic stops
+ * being finite — collapses to a zero-length window, which is what a
+ * nonsensical request should read as.
+ */
+export declare const DEFAULT_SINCE_DAYS = 30;
+/**
+ * @returns the epoch-ms cutoff a scan must not read past, or `undefined` for an
+ * unbounded (all-history) scan — which only `Infinity` produces.
+ */
+export declare function resolveScanCutoffMs(sinceDays: number | undefined, defaultDays?: number): number | undefined;

package/dist/localUsage/scanWindow.js

@@ -0,0 +1,42 @@
+/**
+ * One definition of "how far back does a local-usage scan reach".
+ *
+ * This calculation lived in three copies — claudeCodeReader, codexReader and
+ * openCodeReader — and has been wrong three separate times, each a different
+ * door into the same failure: an unbounded sweep of every transcript on the
+ * machine in answer to the narrowest possible request.
+ *
+ *   sinceDays: 0          left the cutoff undefined       17,534 files, 35.9s
+ *   sinceDays: NaN        Math.max(0, NaN) is NaN, and every comparison
+ *                         against NaN is false, so the filter passed
+ *                         everything                       17,537 files, 32.8s
+ *   sinceDays: MAX_VALUE  MAX_VALUE * 86_400_000 overflows to Infinity, so the
+ *                         cutoff became -Infinity and every file passed
+ *
+ * Three fixes in three files each closed one door and left the others open.
+ * The logic lives here once now, so the next door closes everywhere at once.
+ *
+ * Contract: `Infinity` is the ONLY value meaning all-history. Anything that is
+ * not a usable finite window — NaN, negative, or so large the arithmetic stops
+ * being finite — collapses to a zero-length window, which is what a
+ * nonsensical request should read as.
+ */
+export const DEFAULT_SINCE_DAYS = 30;
+const MS_PER_DAY = 86_400_000;
+/**
+ * @returns the epoch-ms cutoff a scan must not read past, or `undefined` for an
+ * unbounded (all-history) scan — which only `Infinity` produces.
+ */
+export function resolveScanCutoffMs(sinceDays, defaultDays = DEFAULT_SINCE_DAYS) {
+    const requested = sinceDays ?? defaultDays;
+    const days = Number.isNaN(requested) ? 0 : requested;
+    if (days === Infinity) {
+        return undefined;
+    }
+    const span = Math.max(0, days) * MS_PER_DAY;
+    // A finite `days` can still produce a non-finite span: Number.MAX_VALUE and
+    // anything near it overflow on the multiply. Treat that as no window rather
+    // than letting `Date.now() - Infinity` become -Infinity, which every
+    // timestamp compares as newer than.
+    return Date.now() - (Number.isFinite(span) ? span : 0);
+}

package/dist/providers/anthropic/client.js

@@ -1738,7 +1738,28 @@ export class AnthropicProvider extends BaseProvider {
                     }
                 }
             })();
-            const result = await resultPromise;
+            // `pump` is detached: it starts draining the engine's channel the moment
+            // it is created, and `await pump` below is the only thing that adopts its
+            // rejection. When resultPromise rejects, that line is never reached, so
+            // pump's rejection stays unhandled — and an unhandled rejection
+            // TERMINATES the consumer's process. Measured: a caller that correctly
+            // try/catches a streaming error still died with ERR_UNHANDLED_REJECTION,
+            // exit code 1, with no way to defend against it from outside this
+            // library. The rejection carried the raw SDK error, distinct from the
+            // formatted one the caller received, which is why the existing
+            // `loopPromise.catch` guard below does not cover it.
+            //
+            // Same shape googleAiStudio/client.ts and googleVertex/client.ts already
+            // use at every one of their pump sites; Anthropic was the only provider
+            // missing it.
+            let result;
+            try {
+                result = await resultPromise;
+            }
+            catch (error) {
+                await pump.catch(() => { });
+                throw error;
+            }
             await pump;
             totalInput += result.usage.inputTokens;
             totalOutput += result.usage.outputTokens;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "11.25.2",
+  "version": "11.25.4",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {