@juspay/neurolink 10.7.1 → 10.8.0

package/dist/core/baseProvider.d.ts

@@ -220,6 +220,7 @@ export declare abstract class BaseProvider implements AIProvider {
     private handleVideoFrameGeneration;
     private executeStandardGenerateFlow;
     protected synthesizeAIResponseIfNeeded(enhancedResult: EnhancedGenerateResult, options: TextGenerationOptions): Promise<EnhancedGenerateResult>;
+    private getTTSErrorDetails;
     /**
      * BACKWARD COMPATIBILITY: Legacy generateText method
      * Converts EnhancedGenerateResult to TextGenerationResult format

package/dist/core/baseProvider.js

@@ -4,16 +4,16 @@ import { IMAGE_GENERATION_MODELS } from "../core/constants.js";
 import { MiddlewareFactory } from "../middleware/factory.js";
 import { modelSupports } from "../models/modelRegistry.js";
 import { ATTR, tracers } from "../telemetry/index.js";
-import { isAbortError } from "../utils/errorHandling.js";
+import { isAbortError, NeuroLinkError } from "../utils/errorHandling.js";
 import { hasLifecycleErrorFired, markLifecycleErrorFired, } from "../utils/lifecycleCallbacks.js";
 import { resolveLifecycleTimeoutMs } from "../utils/lifecycleTimeout.js";
 import { logger } from "../utils/logger.js";
-import { withTimeoutFn } from "../utils/async/withTimeout.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";
 import { getKeyCount, getKeysAsString } from "../utils/transformationUtils.js";
 import { ToolExecutionRecorder, resolveToolExecutionRecords, } from "./toolExecutionRecorder.js";
-import { TTSProcessor } from "../utils/ttsProcessor.js";
+import { TTS_ERROR_CODES, TTSProcessor } from "../utils/ttsProcessor.js";
 import { executeVideoAnalysis, hasVideoFrames, } from "../utils/videoAnalysisProcessor.js";
 import { dedupeTools } from "./toolDedup.js";
 import { resolveToolPolicy, toolNameMatcher } from "../tools/toolPolicy.js";
@@ -1016,13 +1016,31 @@ export class BaseProvider {
             model: this.modelName,
             usage: { input: 0, output: 0, total: 0 },
         };
+        const ttsOptions = options.tts;
+        if (!ttsOptions) {
+            return this.enhanceResult(baseResult, options, startTime);
+        }
+        const ttsStartTime = Date.now();
+        const ttsProvider = ttsOptions.provider ?? options.provider ?? this.providerName;
+        const ttsTimeout = this.getTimeout(options);
         try {
-            if (!options.tts) {
-                return this.enhanceResult(baseResult, options, startTime);
-            }
-            baseResult.audio = await TTSProcessor.synthesize(textToSynthesize, options.tts.provider ?? options.provider ?? this.providerName, options.tts);
+            baseResult.audio = await withTimeoutFn(() => TTSProcessor.synthesize(textToSynthesize, ttsProvider, ttsOptions), ttsTimeout, `TTS synthesis timed out after ${ttsTimeout}ms for provider "${ttsProvider}"`);
+            baseResult.ttsMetadata = {
+                attempted: true,
+                success: true,
+                latency: Date.now() - ttsStartTime,
+            };
         }
         catch (ttsError) {
+            const latency = Date.now() - ttsStartTime;
+            const error = this.getTTSErrorDetails(ttsError);
+            baseResult.ttsMetadata = {
+                attempted: true,
+                success: false,
+                error,
+                latency,
+            };
+            this.telemetryHandler.recordTTSFailure(ttsProvider, error, latency);
             logger.error(`TTS synthesis failed in Mode 1 (direct input synthesis):`, ttsError);
         }
         return this.enhanceResult(baseResult, options, startTime);
@@ -1144,8 +1162,9 @@ export class BaseProvider {
         if (!options.tts?.enabled || !options.tts?.useAiResponse) {
             return enhancedResult;
         }
+        const ttsOptions = options.tts;
         const aiResponse = enhancedResult.content;
-        const ttsProvider = options.tts?.provider ?? options.provider ?? this.providerName;
+        const ttsProvider = ttsOptions.provider ?? options.provider ?? this.providerName;
         if (!aiResponse || !ttsProvider) {
             logger.warn(`TTS synthesis skipped despite being enabled`, {
                 provider: this.providerName,
@@ -1160,19 +1179,63 @@ export class BaseProvider {
                     ? "AI response is empty or undefined"
                     : "Provider is missing",
             });
-            return enhancedResult;
+            return {
+                ...enhancedResult,
+                ttsMetadata: {
+                    attempted: false,
+                    success: false,
+                },
+            };
         }
+        const ttsStartTime = Date.now();
+        const ttsTimeout = this.getTimeout(options);
         try {
-            const ttsResult = await TTSProcessor.synthesize(aiResponse, ttsProvider, options.tts);
+            const ttsResult = await withTimeoutFn(() => TTSProcessor.synthesize(aiResponse, ttsProvider, ttsOptions), ttsTimeout, `TTS synthesis timed out after ${ttsTimeout}ms for provider "${ttsProvider}"`);
             return {
                 ...enhancedResult,
                 audio: ttsResult,
+                ttsMetadata: {
+                    attempted: true,
+                    success: true,
+                    latency: Date.now() - ttsStartTime,
+                },
             };
         }
         catch (ttsError) {
+            const latency = Date.now() - ttsStartTime;
+            const error = this.getTTSErrorDetails(ttsError);
+            this.telemetryHandler.recordTTSFailure(ttsProvider, error, latency);
             logger.error(`TTS synthesis failed in Mode 2 (AI response synthesis):`, ttsError);
-            return enhancedResult;
+            return {
+                ...enhancedResult,
+                ttsMetadata: {
+                    attempted: true,
+                    success: false,
+                    error,
+                    latency,
+                },
+            };
+        }
+    }
+    getTTSErrorDetails(error) {
+        if (error instanceof AsyncTimeoutError) {
+            return {
+                code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+                message: error.message,
+                retriable: true,
+            };
+        }
+        if (error instanceof NeuroLinkError) {
+            return {
+                code: error.code,
+                message: error.message,
+                retriable: error.retriable,
+            };
         }
+        return {
+            code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+            message: error instanceof Error ? error.message : String(error),
+        };
     }
     /**
      * BACKWARD COMPATIBILITY: Legacy generateText method

package/dist/core/modules/TelemetryHandler.d.ts

@@ -14,7 +14,7 @@
  * @module core/modules/TelemetryHandler
  */
 import type { NeuroLink } from "../../neurolink.js";
-import type { StreamOptions, AIProviderName, AnalyticsData, EnhancedGenerateResult, EvaluationData, RawUsageObject, TextGenerationOptions, TokenUsage } from "../../types/index.js";
+import type { StreamOptions, AIProviderName, AnalyticsData, EnhancedGenerateResult, EvaluationData, RawUsageObject, TextGenerationOptions, TokenUsage, TTSMetadata } from "../../types/index.js";
 /**
  * TelemetryHandler class - Handles analytics and telemetry for AI providers
  */
@@ -35,6 +35,10 @@ export declare class TelemetryHandler {
      * Record performance metrics for a generation
      */
     recordPerformanceMetrics(usage: RawUsageObject | undefined, responseTime: number): Promise<void>;
+    /**
+     * Record a TTS synthesis failure without affecting the generation result.
+     */
+    recordTTSFailure(ttsProvider: string, error: NonNullable<TTSMetadata["error"]>, latency: number): void;
     /**
      * Calculate actual cost based on token usage and provider configuration.
      *

package/dist/core/modules/TelemetryHandler.js

@@ -100,6 +100,26 @@ export class TelemetryHandler {
             logger.warn("⚠️ Performance recording failed:", perfError);
         }
     }
+    /**
+     * Record a TTS synthesis failure without affecting the generation result.
+     */
+    recordTTSFailure(ttsProvider, error, latency) {
+        try {
+            const labels = {
+                provider: ttsProvider,
+                error_code: error.code,
+                ...(error.retriable !== undefined
+                    ? { retriable: error.retriable.toString() }
+                    : {}),
+            };
+            const telemetry = TelemetryService.getInstance();
+            telemetry.recordCustomMetric("tts_failures", 1, labels);
+            telemetry.recordCustomHistogram("tts_failure_latency_ms", latency, labels);
+        }
+        catch (telemetryError) {
+            logger.warn("TTS failure telemetry recording failed:", telemetryError);
+        }
+    }
     /**
      * Calculate actual cost based on token usage and provider configuration.
      *

package/dist/lib/adapters/replicate/predictionLifecycle.d.ts

@@ -18,7 +18,7 @@ import type { ReplicateAuth, ReplicateCreatePredictionInput, ReplicatePollOption
  * Submit a Replicate prediction. Uses `Prefer: wait=60` so quick
  * predictions complete in the initial POST and skip polling entirely.
  */
-export declare function createPrediction(auth: ReplicateAuth, input: ReplicateCreatePredictionInput): Promise<ReplicatePrediction>;
+export declare function createPrediction(auth: ReplicateAuth, input: ReplicateCreatePredictionInput, sleep?: (delayMs: number) => Promise<void>): Promise<ReplicatePrediction>;
 /**
  * Poll a Replicate prediction until it reaches a terminal status
  * (succeeded / failed / canceled) or the total timeout elapses.

package/dist/lib/adapters/replicate/predictionLifecycle.js

@@ -17,6 +17,8 @@ import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
 import { logger } from "../../utils/logger.js";
 import { NeuroLinkError, ERROR_CODES } from "../../utils/errorHandling.js";
 import { sanitizeForLog } from "../../utils/logSanitize.js";
+import { withProviderRetry } from "../../utils/providerRetry.js";
+import { parseRetryAfterMs } from "../../utils/retryAfter.js";
 import { safeDownload } from "../../utils/safeFetch.js";
 import { MAX_VIDEO_BYTES } from "../../utils/sizeGuard.js";
 // The submit path sends `Prefer: wait=60`, so Replicate can legitimately
@@ -31,7 +33,7 @@ const DEFAULT_TOTAL_TIMEOUT_MS = 5 * 60_000;
  * Submit a Replicate prediction. Uses `Prefer: wait=60` so quick
  * predictions complete in the initial POST and skip polling entirely.
  */
-export async function createPrediction(auth, input) {
+export async function createPrediction(auth, input, sleep) {
     const baseUrl = auth.baseUrl ?? "https://api.replicate.com";
     const [modelPath, version] = input.model.split(":", 2);
     const endpoint = version
@@ -46,51 +48,53 @@ export async function createPrediction(auth, input) {
     if (input.webhookEventsFilter && input.webhookEventsFilter.length > 0) {
         body.webhook_events_filter = input.webhookEventsFilter;
     }
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
-    let response;
-    try {
-        response = await fetch(endpoint, {
-            method: "POST",
-            headers: {
-                Authorization: `Token ${auth.apiToken}`,
-                "Content-Type": "application/json",
-                Prefer: "wait=60",
-            },
-            body: JSON.stringify(body),
-            signal: controller.signal,
-        });
-    }
-    catch (err) {
-        if (err instanceof NeuroLinkError) {
-            throw err;
-        }
-        if (err instanceof Error && err.name === "AbortError") {
-            throw new NeuroLinkError({
-                code: ERROR_CODES.OPERATION_ABORTED,
-                message: `Replicate predictions submit timed out after ${REQUEST_TIMEOUT_MS / 1000}s`,
-                category: ErrorCategory.TIMEOUT,
-                severity: ErrorSeverity.HIGH,
-                retriable: true,
-                originalError: err,
+    return withProviderRetry(async () => {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        try {
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers: {
+                    Authorization: `Token ${auth.apiToken}`,
+                    "Content-Type": "application/json",
+                    Prefer: "wait=60",
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
             });
+            if (!response.ok) {
+                const raw = await response.text();
+                throw new NeuroLinkError({
+                    code: ERROR_CODES.PROVIDER_NOT_AVAILABLE,
+                    message: `Replicate predictions submit failed: ${response.status} — ${sanitizeForLog(raw, 500)}`,
+                    category: ErrorCategory.NETWORK,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: response.status >= 500 || response.status === 429,
+                    retryAfterMs: parseRetryAfterMs(response.headers),
+                });
+            }
+            return (await response.json());
         }
-        throw err;
-    }
-    finally {
-        clearTimeout(timeoutId);
-    }
-    if (!response.ok) {
-        const raw = await response.text();
-        throw new NeuroLinkError({
-            code: ERROR_CODES.PROVIDER_NOT_AVAILABLE,
-            message: `Replicate predictions submit failed: ${response.status} — ${sanitizeForLog(raw, 500)}`,
-            category: ErrorCategory.NETWORK,
-            severity: ErrorSeverity.HIGH,
-            retriable: response.status >= 500,
-        });
-    }
-    return (await response.json());
+        catch (error) {
+            if (error instanceof NeuroLinkError) {
+                throw error;
+            }
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new NeuroLinkError({
+                    code: ERROR_CODES.OPERATION_ABORTED,
+                    message: `Replicate predictions submit timed out after ${REQUEST_TIMEOUT_MS / 1000}s`,
+                    category: ErrorCategory.TIMEOUT,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: true,
+                    originalError: error,
+                });
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }, undefined, "Replicate prediction submission", sleep);
 }
 /**
  * Poll a Replicate prediction until it reaches a terminal status
@@ -164,7 +168,8 @@ export async function pollPrediction(auth, predictionId, options = {}) {
                 message: `Replicate poll failed: ${response.status} — ${sanitizeForLog(raw, 500)}`,
                 category: ErrorCategory.NETWORK,
                 severity: ErrorSeverity.HIGH,
-                retriable: response.status >= 500,
+                retriable: response.status >= 500 || response.status === 429,
+                retryAfterMs: parseRetryAfterMs(response.headers),
             });
         }
         const pred = (await response.json());

package/dist/lib/core/baseProvider.d.ts

@@ -220,6 +220,7 @@ export declare abstract class BaseProvider implements AIProvider {
     private handleVideoFrameGeneration;
     private executeStandardGenerateFlow;
     protected synthesizeAIResponseIfNeeded(enhancedResult: EnhancedGenerateResult, options: TextGenerationOptions): Promise<EnhancedGenerateResult>;
+    private getTTSErrorDetails;
     /**
      * BACKWARD COMPATIBILITY: Legacy generateText method
      * Converts EnhancedGenerateResult to TextGenerationResult format

package/dist/lib/core/baseProvider.js

@@ -4,16 +4,16 @@ import { IMAGE_GENERATION_MODELS } from "../core/constants.js";
 import { MiddlewareFactory } from "../middleware/factory.js";
 import { modelSupports } from "../models/modelRegistry.js";
 import { ATTR, tracers } from "../telemetry/index.js";
-import { isAbortError } from "../utils/errorHandling.js";
+import { isAbortError, NeuroLinkError } from "../utils/errorHandling.js";
 import { hasLifecycleErrorFired, markLifecycleErrorFired, } from "../utils/lifecycleCallbacks.js";
 import { resolveLifecycleTimeoutMs } from "../utils/lifecycleTimeout.js";
 import { logger } from "../utils/logger.js";
-import { withTimeoutFn } from "../utils/async/withTimeout.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";
 import { getKeyCount, getKeysAsString } from "../utils/transformationUtils.js";
 import { ToolExecutionRecorder, resolveToolExecutionRecords, } from "./toolExecutionRecorder.js";
-import { TTSProcessor } from "../utils/ttsProcessor.js";
+import { TTS_ERROR_CODES, TTSProcessor } from "../utils/ttsProcessor.js";
 import { executeVideoAnalysis, hasVideoFrames, } from "../utils/videoAnalysisProcessor.js";
 import { dedupeTools } from "./toolDedup.js";
 import { resolveToolPolicy, toolNameMatcher } from "../tools/toolPolicy.js";
@@ -1016,13 +1016,31 @@ export class BaseProvider {
             model: this.modelName,
             usage: { input: 0, output: 0, total: 0 },
         };
+        const ttsOptions = options.tts;
+        if (!ttsOptions) {
+            return this.enhanceResult(baseResult, options, startTime);
+        }
+        const ttsStartTime = Date.now();
+        const ttsProvider = ttsOptions.provider ?? options.provider ?? this.providerName;
+        const ttsTimeout = this.getTimeout(options);
         try {
-            if (!options.tts) {
-                return this.enhanceResult(baseResult, options, startTime);
-            }
-            baseResult.audio = await TTSProcessor.synthesize(textToSynthesize, options.tts.provider ?? options.provider ?? this.providerName, options.tts);
+            baseResult.audio = await withTimeoutFn(() => TTSProcessor.synthesize(textToSynthesize, ttsProvider, ttsOptions), ttsTimeout, `TTS synthesis timed out after ${ttsTimeout}ms for provider "${ttsProvider}"`);
+            baseResult.ttsMetadata = {
+                attempted: true,
+                success: true,
+                latency: Date.now() - ttsStartTime,
+            };
         }
         catch (ttsError) {
+            const latency = Date.now() - ttsStartTime;
+            const error = this.getTTSErrorDetails(ttsError);
+            baseResult.ttsMetadata = {
+                attempted: true,
+                success: false,
+                error,
+                latency,
+            };
+            this.telemetryHandler.recordTTSFailure(ttsProvider, error, latency);
             logger.error(`TTS synthesis failed in Mode 1 (direct input synthesis):`, ttsError);
         }
         return this.enhanceResult(baseResult, options, startTime);
@@ -1144,8 +1162,9 @@ export class BaseProvider {
         if (!options.tts?.enabled || !options.tts?.useAiResponse) {
             return enhancedResult;
         }
+        const ttsOptions = options.tts;
         const aiResponse = enhancedResult.content;
-        const ttsProvider = options.tts?.provider ?? options.provider ?? this.providerName;
+        const ttsProvider = ttsOptions.provider ?? options.provider ?? this.providerName;
         if (!aiResponse || !ttsProvider) {
             logger.warn(`TTS synthesis skipped despite being enabled`, {
                 provider: this.providerName,
@@ -1160,19 +1179,63 @@ export class BaseProvider {
                     ? "AI response is empty or undefined"
                     : "Provider is missing",
             });
-            return enhancedResult;
+            return {
+                ...enhancedResult,
+                ttsMetadata: {
+                    attempted: false,
+                    success: false,
+                },
+            };
         }
+        const ttsStartTime = Date.now();
+        const ttsTimeout = this.getTimeout(options);
         try {
-            const ttsResult = await TTSProcessor.synthesize(aiResponse, ttsProvider, options.tts);
+            const ttsResult = await withTimeoutFn(() => TTSProcessor.synthesize(aiResponse, ttsProvider, ttsOptions), ttsTimeout, `TTS synthesis timed out after ${ttsTimeout}ms for provider "${ttsProvider}"`);
             return {
                 ...enhancedResult,
                 audio: ttsResult,
+                ttsMetadata: {
+                    attempted: true,
+                    success: true,
+                    latency: Date.now() - ttsStartTime,
+                },
             };
         }
         catch (ttsError) {
+            const latency = Date.now() - ttsStartTime;
+            const error = this.getTTSErrorDetails(ttsError);
+            this.telemetryHandler.recordTTSFailure(ttsProvider, error, latency);
             logger.error(`TTS synthesis failed in Mode 2 (AI response synthesis):`, ttsError);
-            return enhancedResult;
+            return {
+                ...enhancedResult,
+                ttsMetadata: {
+                    attempted: true,
+                    success: false,
+                    error,
+                    latency,
+                },
+            };
+        }
+    }
+    getTTSErrorDetails(error) {
+        if (error instanceof AsyncTimeoutError) {
+            return {
+                code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+                message: error.message,
+                retriable: true,
+            };
+        }
+        if (error instanceof NeuroLinkError) {
+            return {
+                code: error.code,
+                message: error.message,
+                retriable: error.retriable,
+            };
         }
+        return {
+            code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+            message: error instanceof Error ? error.message : String(error),
+        };
     }
     /**
      * BACKWARD COMPATIBILITY: Legacy generateText method

package/dist/lib/core/modules/TelemetryHandler.d.ts

@@ -14,7 +14,7 @@
  * @module core/modules/TelemetryHandler
  */
 import type { NeuroLink } from "../../neurolink.js";
-import type { StreamOptions, AIProviderName, AnalyticsData, EnhancedGenerateResult, EvaluationData, RawUsageObject, TextGenerationOptions, TokenUsage } from "../../types/index.js";
+import type { StreamOptions, AIProviderName, AnalyticsData, EnhancedGenerateResult, EvaluationData, RawUsageObject, TextGenerationOptions, TokenUsage, TTSMetadata } from "../../types/index.js";
 /**
  * TelemetryHandler class - Handles analytics and telemetry for AI providers
  */
@@ -35,6 +35,10 @@ export declare class TelemetryHandler {
      * Record performance metrics for a generation
      */
     recordPerformanceMetrics(usage: RawUsageObject | undefined, responseTime: number): Promise<void>;
+    /**
+     * Record a TTS synthesis failure without affecting the generation result.
+     */
+    recordTTSFailure(ttsProvider: string, error: NonNullable<TTSMetadata["error"]>, latency: number): void;
     /**
      * Calculate actual cost based on token usage and provider configuration.
      *

package/dist/lib/core/modules/TelemetryHandler.js

@@ -100,6 +100,26 @@ export class TelemetryHandler {
             logger.warn("⚠️ Performance recording failed:", perfError);
         }
     }
+    /**
+     * Record a TTS synthesis failure without affecting the generation result.
+     */
+    recordTTSFailure(ttsProvider, error, latency) {
+        try {
+            const labels = {
+                provider: ttsProvider,
+                error_code: error.code,
+                ...(error.retriable !== undefined
+                    ? { retriable: error.retriable.toString() }
+                    : {}),
+            };
+            const telemetry = TelemetryService.getInstance();
+            telemetry.recordCustomMetric("tts_failures", 1, labels);
+            telemetry.recordCustomHistogram("tts_failure_latency_ms", latency, labels);
+        }
+        catch (telemetryError) {
+            logger.warn("TTS failure telemetry recording failed:", telemetryError);
+        }
+    }
     /**
      * Calculate actual cost based on token usage and provider configuration.
      *

package/dist/lib/mcp/httpRateLimiter.js

@@ -4,6 +4,7 @@
  * Provides fault tolerance and prevents server overload
  */
 import { mcpLogger } from "../utils/logger.js";
+import { parseRetryAfterMs } from "../utils/retryAfter.js";
 import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../observability/index.js";
 import { getActiveTraceContext } from "../telemetry/traceContext.js";
 /**
@@ -176,48 +177,40 @@ export class HTTPRateLimiter {
      * @returns Wait time in milliseconds, or 0 if no rate limit headers found
      */
     handleRateLimitResponse(headers) {
-        // Check for Retry-After header (standard HTTP 429 response)
+        const parsedWaitTimeMs = parseRetryAfterMs(headers);
+        // Keep the existing source-specific logs while delegating delay parsing.
         const retryAfter = headers.get("Retry-After");
-        if (retryAfter) {
-            // Retry-After can be either a number of seconds or an HTTP-date
+        if (retryAfter && parsedWaitTimeMs !== undefined) {
             const seconds = parseInt(retryAfter, 10);
             if (!isNaN(seconds)) {
-                // It's a number of seconds
-                const waitTimeMs = seconds * 1000;
                 mcpLogger.info(`[HTTPRateLimiter] Server requested retry after ${seconds} seconds`);
-                return waitTimeMs;
+                return parsedWaitTimeMs;
             }
             else {
-                // Try to parse as HTTP-date
                 const retryDate = new Date(retryAfter);
                 if (!isNaN(retryDate.getTime())) {
-                    const waitTimeMs = Math.max(0, retryDate.getTime() - Date.now());
-                    mcpLogger.info(`[HTTPRateLimiter] Server requested retry at ${retryDate.toISOString()} (${waitTimeMs}ms)`);
-                    return waitTimeMs;
+                    mcpLogger.info(`[HTTPRateLimiter] Server requested retry at ${retryDate.toISOString()} (${parsedWaitTimeMs}ms)`);
+                    return parsedWaitTimeMs;
                 }
             }
         }
         // Check for X-RateLimit-Reset header (common non-standard header)
         const rateLimitReset = headers.get("X-RateLimit-Reset");
-        if (rateLimitReset) {
+        if (rateLimitReset && parsedWaitTimeMs !== undefined) {
             const resetTimestamp = parseInt(rateLimitReset, 10);
             if (!isNaN(resetTimestamp)) {
-                // Could be Unix timestamp (seconds) or milliseconds
                 const resetTime = resetTimestamp > 1e12 ? resetTimestamp : resetTimestamp * 1000;
-                const waitTimeMs = Math.max(0, resetTime - Date.now());
-                mcpLogger.info(`[HTTPRateLimiter] Rate limit resets at ${new Date(resetTime).toISOString()} (${waitTimeMs}ms)`);
-                return waitTimeMs;
+                mcpLogger.info(`[HTTPRateLimiter] Rate limit resets at ${new Date(resetTime).toISOString()} (${parsedWaitTimeMs}ms)`);
+                return parsedWaitTimeMs;
             }
         }
         // Check for X-RateLimit-Remaining header
         const remaining = headers.get("X-RateLimit-Remaining");
-        if (remaining === "0") {
-            // No remaining requests, use default backoff
-            const defaultBackoffMs = 1000;
-            mcpLogger.info(`[HTTPRateLimiter] Rate limit exhausted, using default backoff: ${defaultBackoffMs}ms`);
-            return defaultBackoffMs;
+        if (remaining === "0" && parsedWaitTimeMs !== undefined) {
+            mcpLogger.info(`[HTTPRateLimiter] Rate limit exhausted, using default backoff: ${parsedWaitTimeMs}ms`);
+            return parsedWaitTimeMs;
         }
-        return 0;
+        return parsedWaitTimeMs ?? 0;
     }
     /**
      * Get the number of remaining tokens

package/dist/lib/types/generate.d.ts

@@ -1418,9 +1418,25 @@ export type TextGenerationResult = {
 /**
  * Enhanced result type with optional analytics/evaluation
  */
+export type TTSMetadata = {
+    /** Whether TTS synthesis was invoked. False indicates TTS was skipped. */
+    attempted: boolean;
+    /** Whether TTS synthesis completed successfully. */
+    success: boolean;
+    /** Structured synthesis error details, present only when synthesis failed. */
+    error?: {
+        code: string;
+        message: string;
+        retriable?: boolean;
+    };
+    /** TTS synthesis time in milliseconds. */
+    latency?: number;
+};
 export type EnhancedGenerateResult = GenerateResult & {
     analytics?: AnalyticsData;
     evaluation?: EvaluationData;
+    /** Outcome metadata when TTS was enabled for this generation. */
+    ttsMetadata?: TTSMetadata;
 };
 /**
  * NL-004: Model alias/deprecation configuration.

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

@@ -70,6 +70,7 @@ export declare class NeuroLinkError extends Error {
     readonly category: ErrorCategory;
     readonly severity: ErrorSeverity;
     readonly retriable: boolean;
+    readonly retryAfterMs?: number;
     readonly context: Record<string, unknown>;
     readonly timestamp: Date;
     readonly toolName?: string;
@@ -80,6 +81,7 @@ export declare class NeuroLinkError extends Error {
         category: ErrorCategory;
         severity: ErrorSeverity;
         retriable: boolean;
+        retryAfterMs?: number;
         context?: Record<string, unknown>;
         originalError?: Error;
         toolName?: string;

package/dist/lib/utils/errorHandling.js

@@ -87,6 +87,7 @@ export class NeuroLinkError extends Error {
     category;
     severity;
     retriable;
+    retryAfterMs;
     context;
     timestamp;
     toolName;
@@ -98,6 +99,7 @@ export class NeuroLinkError extends Error {
         this.category = options.category;
         this.severity = options.severity;
         this.retriable = options.retriable;
+        this.retryAfterMs = options.retryAfterMs;
         this.context = options.context || {};
         this.timestamp = new Date();
         this.toolName = options.toolName;