@juspay/neurolink 11.25.3 → 11.26.0

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;
@@ -76,6 +72,11 @@ export declare abstract class BaseProvider implements AIProvider {
      * that supplied `onError`).
      */
     private fireLifecycleErrorCallback;
+    /**
+     * Build the fake-stream output and apply the same incremental TTS wrapper
+     * used by the standard NeuroLink stream path.
+     */
+    private createFakeStreamingOutput;
     /**
      * Execute fake streaming - extracted method for reusability
      */
@@ -387,6 +388,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

@@ -1,10 +1,11 @@
 import { context, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 import { directAgentTools } from "../agent/directTools.js";
-import { isImageGenerationModel } from "../core/constants.js";
+import { isImageGenerationModel } from "./constants.js";
 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";
@@ -12,6 +13,7 @@ import { duckTypedStatusCode, extractRetryAfterMsFromError, } from "../utils/pro
 import { hasLifecycleErrorFired, markLifecycleErrorFired, } from "../utils/lifecycleCallbacks.js";
 import { resolveLifecycleTimeoutMs } from "../utils/lifecycleTimeout.js";
 import { logger } from "../utils/logger.js";
+import { interleaveTTSStream } from "../utils/ttsStream.js";
 import { TimeoutError as AsyncTimeoutError, withTimeoutFn, } from "../utils/async/withTimeout.js";
 import { composeAbortSignals, createTimeoutController, TimeoutError, } from "../utils/timeout.js";
 import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
@@ -48,6 +50,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 +350,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 +381,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 +432,7 @@ export class BaseProvider {
                         recoverable: false,
                     }), "onError");
                 }
-                throw err;
+                throw classifyStreamError(err);
             }
         })();
         return { ...result, stream: wrappedStream };
@@ -437,6 +487,61 @@ export class BaseProvider {
             logger.warn("[lifecycle] onError callback error:", e);
         }
     }
+    /**
+     * Build the fake-stream output and apply the same incremental TTS wrapper
+     * used by the standard NeuroLink stream path.
+     */
+    createFakeStreamingOutput(result, options, onTTSComplete) {
+        const incrementalTTS = options.tts?.enabled === true;
+        const source = (async function* () {
+            if (result?.content) {
+                const words = result.content.split(/(\s+)/);
+                let buffer = "";
+                for (let i = 0; i < words.length; i++) {
+                    buffer += words[i];
+                    const shouldYield = i === words.length - 1 ||
+                        buffer.length > 50 ||
+                        /[.!?;,]\s*$/.test(buffer);
+                    if (shouldYield && buffer.trim()) {
+                        yield { content: buffer };
+                        buffer = "";
+                        await new Promise((resolve) => {
+                            setTimeout(resolve, Math.random() * 9 + 1);
+                        });
+                    }
+                }
+                if (buffer.trim()) {
+                    yield { content: buffer };
+                }
+            }
+            if (result?.imageOutput) {
+                yield { type: "image", imageOutput: result.imageOutput };
+            }
+            if (result?.audio && !incrementalTTS) {
+                yield {
+                    type: "tts_audio",
+                    audio: {
+                        data: result.audio.buffer,
+                        format: result.audio.format,
+                        index: 0,
+                        isFinal: true,
+                        cumulativeSize: result.audio.size,
+                        voice: result.audio.voice,
+                        sampleRate: result.audio.sampleRate,
+                    },
+                };
+            }
+        })();
+        if (!incrementalTTS || !options.tts) {
+            return source;
+        }
+        return interleaveTTSStream({
+            stream: source,
+            provider: options.tts.provider ?? options.provider ?? this.providerName,
+            options: options.tts,
+            onComplete: onTTSComplete,
+        });
+    }
     /**
      * Execute fake streaming - extracted method for reusability
      */
@@ -476,10 +581,10 @@ export class BaseProvider {
                 skipToolPromptInjection: options.skipToolPromptInjection,
                 timeout: options.timeout,
                 stt: options.stt,
-                // Forward TTS options too — without this, the fake-streaming fallback
-                // path silently drops `tts` and the resulting StreamResult never
-                // produces a `tts_audio` chunk even when synthesis was requested.
-                tts: options.tts,
+                // Streaming TTS is synthesized incrementally by
+                // createFakeStreamingOutput; do not let generate() perform a duplicate
+                // input- or whole-response synthesis first.
+                tts: options.tts?.enabled ? undefined : options.tts,
             };
             logger.debug(`Calling generate for fake streaming`, {
                 provider: this.providerName,
@@ -496,58 +601,45 @@ export class BaseProvider {
                 hasImageOutput: !!result?.imageOutput,
                 timestamp: Date.now(),
             });
-            // Create a synthetic stream from the generate result that simulates progressive delivery
-            return {
-                stream: (async function* () {
-                    if (result?.content) {
-                        // Split content into words for more natural streaming
-                        const words = result.content.split(/(\s+)/); // Keep whitespace
-                        let buffer = "";
-                        for (let i = 0; i < words.length; i++) {
-                            buffer += words[i];
-                            // Yield chunks of roughly 5-10 words or at punctuation
-                            const shouldYield = i === words.length - 1 || // Last word
-                                buffer.length > 50 || // Buffer getting long
-                                /[.!?;,]\s*$/.test(buffer); // End of sentence/clause
-                            if (shouldYield && buffer.trim()) {
-                                yield { content: buffer };
-                                buffer = "";
-                                // Small delay to simulate streaming (1-10ms)
-                                await new Promise((resolve) => {
-                                    setTimeout(resolve, Math.random() * 9 + 1);
-                                });
-                            }
+            const incrementalTTS = options.tts?.enabled === true;
+            const ttsProvider = options.tts?.provider ?? options.provider ?? this.providerName;
+            const ttsStartedAt = Date.now();
+            let resolveAudio;
+            let audioSettled = false;
+            const audio = incrementalTTS
+                ? new Promise((resolve) => {
+                    resolveAudio = resolve;
+                }).catch(() => undefined)
+                : undefined;
+            const ttsMetadata = incrementalTTS
+                ? {
+                    attempted: TTSProcessor.supports(ttsProvider),
+                    success: false,
+                }
+                : result?.ttsMetadata;
+            const onTTSComplete = incrementalTTS
+                ? (ttsResult, error) => {
+                    if (audioSettled) {
+                        return;
+                    }
+                    audioSettled = true;
+                    if (ttsMetadata) {
+                        ttsMetadata.success =
+                            error === undefined && ttsResult !== undefined;
+                        if (error) {
+                            ttsMetadata.error = error;
                         }
-                        // Yield all remaining content
-                        if (buffer.trim()) {
-                            yield { content: buffer };
+                        else {
+                            delete ttsMetadata.error;
                         }
+                        ttsMetadata.latency = Date.now() - ttsStartedAt;
                     }
-                    // 🔧 CRITICAL FIX: Yield image output if present
-                    if (result?.imageOutput) {
-                        yield {
-                            type: "image",
-                            imageOutput: result.imageOutput,
-                        };
-                    }
-                    // Yield synthesized audio so callers using stream() with tts.enabled
-                    // still receive a tts_audio chunk on the fake-streaming fallback
-                    // path (matches the discriminator used by the real streaming path).
-                    if (result?.audio) {
-                        yield {
-                            type: "tts_audio",
-                            audio: {
-                                data: result.audio.buffer,
-                                format: result.audio.format,
-                                index: 0,
-                                isFinal: true,
-                                cumulativeSize: result.audio.size,
-                                voice: result.audio.voice,
-                                sampleRate: result.audio.sampleRate,
-                            },
-                        };
-                    }
-                })(),
+                    resolveAudio?.(ttsResult);
+                }
+                : undefined;
+            // Create a synthetic stream from the generate result that simulates progressive delivery
+            return {
+                stream: this.createFakeStreamingOutput(result, options, onTTSComplete),
                 usage: result?.usage,
                 provider: result?.provider,
                 model: result?.model,
@@ -569,6 +661,8 @@ export class BaseProvider {
                 // 🔧 FIX: Include analytics and evaluation from generate result
                 analytics: result?.analytics,
                 evaluation: result?.evaluation,
+                audio,
+                ttsMetadata,
             };
         }
         catch (error) {
@@ -1573,6 +1667,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 +1797,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/neurolink.d.ts

@@ -945,7 +945,9 @@ export declare class NeuroLink {
      *
      * // Consume the stream
      * for await (const chunk of result.stream) {
-     *   process.stdout.write(chunk.content);
+     *   if ("content" in chunk) {
+     *     process.stdout.write(chunk.content);
+     *   }
      * }
      *
      * // Advanced streaming with options
@@ -1031,25 +1033,10 @@ export declare class NeuroLink {
     private validateStreamRequestOptions;
     private maybeHandleWorkflowStreamRequest;
     private runStandardStreamRequest;
-    /**
-     * TTS Mode 2 synthesis helper for the stream() pipeline.
-     *
-     * m5 — extracted from runStandardStreamRequest so the surrounding generator
-     * stays under the max-lines-per-function lint budget. Behaviour preserved
-     * exactly:
-     * - When Mode 2 is enabled (`tts.enabled && tts.useAiResponse`) AND the
-     *   model produced non-empty content: synthesises one final audio buffer
-     *   and returns it as an `audioChunk` for the caller to `yield`. Resolves
-     *   `ttsResolver` with the `TTSResult`.
-     * - When Mode 2 is enabled but synthesis fails: logs a warning and resolves
-     *   `ttsResolver` with `undefined`.
-     * - When Mode 2 is requested but skipped (empty content / wrong mode):
-     *   resolves `ttsResolver` with `undefined` early so callers awaiting
-     *   `result.audio` unblock before the surrounding `finally` cleanup
-     *   completes (Issue 7 latency micro-opt — the finally block also resolves
-     *   defensively, so this is a redundant early signal, not a coverage fix).
-     */
-    private synthesizeStreamModeTwo;
+    /** Wrap one provider stream with incremental TTS synthesis. */
+    private createIncrementalTTSStream;
+    /** Prevent provider fallback streams from duplicating outer streaming TTS. */
+    private deferProviderStreamTTS;
     /**
      * Prepare stream options: initialize memory, MCP, retrieval, orchestration,
      * Ollama tool auto-disable, factory processing, and tool detection.