@juspay/neurolink 9.29.1 → 9.30.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [9.30.0](https://github.com/juspay/neurolink/compare/v9.29.1...v9.30.0) (2026-03-21)
+
+### Features
+
+- **(middleware):** add lifecycle middleware with onFinish, onError, onChunk callbacks ([2d23087](https://github.com/juspay/neurolink/commit/2d230879272a8e67fd936ff087b232bb25f612c0))
+
 ## [9.29.1](https://github.com/juspay/neurolink/compare/v9.29.0...v9.29.1) (2026-03-20)
 
 ### Bug Fixes

package/dist/index.d.ts

@@ -53,6 +53,7 @@ import { createContextEnricher, flushOpenTelemetry, getLangfuseContext, getLangf
 export type { LangfuseContext } from "./services/server/ai/observability/instrumentation.js";
 export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, getLangfuseContext, getTracer, runWithCurrentLangfuseContext, };
 export { clearAnalyticsMetrics, createAnalyticsMiddleware, getAnalyticsMetrics, } from "./middleware/builtin/analytics.js";
+export { createLifecycleMiddleware } from "./middleware/builtin/lifecycle.js";
 export { MiddlewareFactory } from "./middleware/factory.js";
 export { ExporterRegistry } from "./observability/exporterRegistry.js";
 export { NoOpExporter } from "./observability/exporters/baseExporter.js";

package/dist/index.js

@@ -71,6 +71,7 @@ getLangfuseContext, getTracer,
 runWithCurrentLangfuseContext, };
 // Analytics Middleware exports
 export { clearAnalyticsMetrics, createAnalyticsMiddleware, getAnalyticsMetrics, } from "./middleware/builtin/analytics.js";
+export { createLifecycleMiddleware } from "./middleware/builtin/lifecycle.js";
 export { MiddlewareFactory } from "./middleware/factory.js";
 export { ExporterRegistry } from "./observability/exporterRegistry.js";
 export { NoOpExporter } from "./observability/exporters/baseExporter.js";

package/dist/lib/index.d.ts

@@ -53,6 +53,7 @@ import { createContextEnricher, flushOpenTelemetry, getLangfuseContext, getLangf
 export type { LangfuseContext } from "./services/server/ai/observability/instrumentation.js";
 export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, getLangfuseContext, getTracer, runWithCurrentLangfuseContext, };
 export { clearAnalyticsMetrics, createAnalyticsMiddleware, getAnalyticsMetrics, } from "./middleware/builtin/analytics.js";
+export { createLifecycleMiddleware } from "./middleware/builtin/lifecycle.js";
 export { MiddlewareFactory } from "./middleware/factory.js";
 export { ExporterRegistry } from "./observability/exporterRegistry.js";
 export { NoOpExporter } from "./observability/exporters/baseExporter.js";

package/dist/lib/index.js

@@ -71,6 +71,7 @@ getLangfuseContext, getTracer,
 runWithCurrentLangfuseContext, };
 // Analytics Middleware exports
 export { clearAnalyticsMetrics, createAnalyticsMiddleware, getAnalyticsMetrics, } from "./middleware/builtin/analytics.js";
+export { createLifecycleMiddleware } from "./middleware/builtin/lifecycle.js";
 export { MiddlewareFactory } from "./middleware/factory.js";
 export { ExporterRegistry } from "./observability/exporterRegistry.js";
 export { NoOpExporter } from "./observability/exporters/baseExporter.js";

package/dist/lib/middleware/builtin/lifecycle.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Lifecycle Middleware
+ *
+ * Provides onFinish, onError, and onChunk callbacks for observing
+ * generation and streaming lifecycle events.
+ *
+ * This middleware is automatically enabled when lifecycle callbacks
+ * (onFinish, onError, onChunk) are passed in GenerateOptions or StreamOptions.
+ */
+import type { NeuroLinkMiddleware, LifecycleMiddlewareConfig } from "../../types/middlewareTypes.js";
+export declare function createLifecycleMiddleware(config?: LifecycleMiddlewareConfig): NeuroLinkMiddleware;

package/dist/lib/middleware/builtin/lifecycle.js

@@ -0,0 +1,165 @@
+/**
+ * Lifecycle Middleware
+ *
+ * Provides onFinish, onError, and onChunk callbacks for observing
+ * generation and streaming lifecycle events.
+ *
+ * This middleware is automatically enabled when lifecycle callbacks
+ * (onFinish, onError, onChunk) are passed in GenerateOptions or StreamOptions.
+ */
+import { logger } from "../../utils/logger.js";
+import { isRecoverableError } from "../../utils/errorHandling.js";
+export function createLifecycleMiddleware(config = {}) {
+    const metadata = {
+        id: "lifecycle",
+        name: "Lifecycle Callbacks",
+        description: "Provides onFinish, onError, and onChunk callbacks for generation and streaming lifecycle events",
+        priority: 110,
+        defaultEnabled: false,
+    };
+    const middleware = {
+        wrapGenerate: async ({ doGenerate }) => {
+            const startTime = Date.now();
+            try {
+                const result = await doGenerate();
+                if (config.onFinish) {
+                    try {
+                        const callbackResult = config.onFinish({
+                            text: result.text ?? "",
+                            usage: result.usage
+                                ? {
+                                    promptTokens: result.usage.promptTokens ?? 0,
+                                    completionTokens: result.usage.completionTokens ?? 0,
+                                }
+                                : undefined,
+                            duration: Date.now() - startTime,
+                            finishReason: result.finishReason,
+                        });
+                        Promise.resolve(callbackResult).catch((e) => {
+                            logger.warn("[LifecycleMiddleware] onFinish callback error:", e);
+                        });
+                    }
+                    catch (e) {
+                        logger.warn("[LifecycleMiddleware] onFinish callback error:", e);
+                    }
+                }
+                return result;
+            }
+            catch (error) {
+                if (config.onError) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    try {
+                        const callbackResult = config.onError({
+                            error: err,
+                            duration: Date.now() - startTime,
+                            recoverable: isRecoverableError(err),
+                        });
+                        Promise.resolve(callbackResult).catch((e) => {
+                            logger.warn("[LifecycleMiddleware] onError callback error:", e);
+                        });
+                    }
+                    catch (e) {
+                        logger.warn("[LifecycleMiddleware] onError callback error:", e);
+                    }
+                }
+                throw error;
+            }
+        },
+        wrapStream: async ({ doStream }) => {
+            const startTime = Date.now();
+            try {
+                const result = await doStream();
+                if (!config.onChunk && !config.onFinish && !config.onError) {
+                    return result;
+                }
+                let sequenceNumber = 0;
+                let accumulatedText = "";
+                const transformStream = new TransformStream({
+                    transform(chunk, controller) {
+                        try {
+                            if (chunk.type === "text-delta") {
+                                accumulatedText += chunk.textDelta;
+                            }
+                            if (config.onChunk && chunk.type) {
+                                try {
+                                    const callbackResult = config.onChunk({
+                                        type: chunk.type,
+                                        textDelta: chunk.type === "text-delta" ? chunk.textDelta : undefined,
+                                        sequenceNumber: sequenceNumber++,
+                                    });
+                                    Promise.resolve(callbackResult).catch((e) => {
+                                        logger.warn("[LifecycleMiddleware] onChunk callback error:", e);
+                                    });
+                                }
+                                catch (e) {
+                                    logger.warn("[LifecycleMiddleware] onChunk callback error:", e);
+                                }
+                            }
+                            controller.enqueue(chunk);
+                        }
+                        catch (error) {
+                            if (config.onError) {
+                                const err = error instanceof Error ? error : new Error(String(error));
+                                try {
+                                    const callbackResult = config.onError({
+                                        error: err,
+                                        duration: Date.now() - startTime,
+                                        recoverable: isRecoverableError(err),
+                                    });
+                                    Promise.resolve(callbackResult).catch((e) => {
+                                        logger.warn("[LifecycleMiddleware] onError callback error:", e);
+                                    });
+                                }
+                                catch (e) {
+                                    logger.warn("[LifecycleMiddleware] onError callback error:", e);
+                                }
+                            }
+                            throw error;
+                        }
+                    },
+                    flush() {
+                        if (config.onFinish) {
+                            try {
+                                const callbackResult = config.onFinish({
+                                    text: accumulatedText,
+                                    duration: Date.now() - startTime,
+                                });
+                                Promise.resolve(callbackResult).catch((e) => {
+                                    logger.warn("[LifecycleMiddleware] onFinish callback error:", e);
+                                });
+                            }
+                            catch (e) {
+                                logger.warn("[LifecycleMiddleware] onFinish callback error:", e);
+                            }
+                        }
+                    },
+                });
+                return {
+                    ...result,
+                    stream: result.stream.pipeThrough(transformStream),
+                };
+            }
+            catch (error) {
+                if (config.onError) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    try {
+                        const callbackResult = config.onError({
+                            error: err,
+                            duration: Date.now() - startTime,
+                            recoverable: isRecoverableError(err),
+                        });
+                        Promise.resolve(callbackResult).catch((e) => {
+                            logger.warn("[LifecycleMiddleware] onError callback error:", e);
+                        });
+                    }
+                    catch (e) {
+                        logger.warn("[LifecycleMiddleware] onError callback error:", e);
+                    }
+                }
+                throw error;
+            }
+        },
+    };
+    return { ...middleware, metadata };
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/lib/middleware/factory.js

@@ -3,6 +3,7 @@ import { MiddlewareRegistry } from "./registry.js";
 import { createAnalyticsMiddleware } from "./builtin/analytics.js";
 import { createGuardrailsMiddleware } from "./builtin/guardrails.js";
 import { createAutoEvaluationMiddleware } from "./builtin/autoEvaluation.js";
+import { createLifecycleMiddleware } from "./builtin/lifecycle.js";
 import { logger } from "../utils/logger.js";
 /**
  * Middleware factory for creating and applying middleware chains.
@@ -26,6 +27,7 @@ export class MiddlewareFactory {
             analytics: createAnalyticsMiddleware,
             guardrails: createGuardrailsMiddleware,
             autoEvaluation: createAutoEvaluationMiddleware,
+            lifecycle: createLifecycleMiddleware,
         };
         // Register built-in presets
         this.registerPreset({
@@ -142,6 +144,7 @@ export class MiddlewareFactory {
             analytics: createAnalyticsMiddleware,
             guardrails: createGuardrailsMiddleware,
             autoEvaluation: createAutoEvaluationMiddleware,
+            lifecycle: createLifecycleMiddleware,
         };
         logger.debug("Getting creator for middleware ID:", id);
         return builtInMiddlewareCreators[id];

package/dist/lib/middleware/index.d.ts

@@ -9,4 +9,5 @@ import { MiddlewareFactory } from "./factory.js";
 export type { NeuroLinkMiddleware, MiddlewareConfig, MiddlewareContext, MiddlewareConditions, MiddlewareRegistrationOptions, MiddlewareExecutionResult, MiddlewareChainStats, MiddlewarePreset, MiddlewareFactoryOptions, BuiltInMiddlewareType, } from "../types/middlewareTypes.js";
 export type { LanguageModelV1Middleware } from "ai";
 export { MiddlewareFactory };
+export { createLifecycleMiddleware } from "./builtin/lifecycle.js";
 export default MiddlewareFactory;

package/dist/lib/middleware/index.js

@@ -9,6 +9,8 @@
 import { MiddlewareFactory } from "./factory.js";
 // Factory for creating and applying middleware chains
 export { MiddlewareFactory };
+// Built-in middleware creators
+export { createLifecycleMiddleware } from "./builtin/lifecycle.js";
 // Export the factory as the default export for clean, direct usage
 export default MiddlewareFactory;
 //# sourceMappingURL=index.js.map

package/dist/lib/neurolink.js

@@ -2209,6 +2209,26 @@ Current user's request: ${currentInput}`;
                             },
                         });
                     }
+                    // Auto-inject lifecycle middleware when callbacks are provided
+                    // (must happen before workflow/PPT early returns so those paths get middleware too)
+                    if (options.onFinish || options.onError) {
+                        options.middleware = {
+                            ...options.middleware,
+                            middlewareConfig: {
+                                ...options.middleware?.middlewareConfig,
+                                lifecycle: {
+                                    ...options.middleware?.middlewareConfig?.lifecycle,
+                                    enabled: true,
+                                    config: {
+                                        ...options.middleware?.middlewareConfig?.lifecycle
+                                            ?.config,
+                                        onFinish: options.onFinish,
+                                        onError: options.onError,
+                                    },
+                                },
+                            },
+                        };
+                    }
                     // Check if workflow is requested
                     if (options.workflow || options.workflowConfig) {
                         return await this.generateWithWorkflow(options);
@@ -2364,6 +2384,7 @@ Current user's request: ${currentInput}`;
                             fileRegistry: this.fileRegistry,
                             abortSignal: options.abortSignal,
                             skipToolPromptInjection: options.skipToolPromptInjection,
+                            middleware: options.middleware,
                         };
                         // Auto-map top-level sessionId/userId to context for convenience
                         // Tests and users may pass sessionId/userId as top-level options
@@ -2400,7 +2421,6 @@ Current user's request: ${currentInput}`;
                                 toolResults: toolResults.length,
                             });
                         }
-                        // Use redesigned generation logic
                         const textResult = await this.generateTextInternal(textOptions);
                         // Emit generation completion event (NeuroLink format - enhanced with content)
                         this.emitter.emit("generation:end", {
@@ -4024,6 +4044,26 @@ Current user's request: ${currentInput}`;
                     });
                 }
                 this.emitStreamStartEvents(options, startTime);
+                // Auto-inject lifecycle middleware when callbacks are provided
+                // (must happen before workflow early return so that path gets middleware too)
+                if (options.onFinish || options.onError || options.onChunk) {
+                    options.middleware = {
+                        ...options.middleware,
+                        middlewareConfig: {
+                            ...options.middleware?.middlewareConfig,
+                            lifecycle: {
+                                ...options.middleware?.middlewareConfig?.lifecycle,
+                                enabled: true,
+                                config: {
+                                    ...options.middleware?.middlewareConfig?.lifecycle?.config,
+                                    onFinish: options.onFinish,
+                                    onError: options.onError,
+                                    onChunk: options.onChunk,
+                                },
+                            },
+                        },
+                    };
+                }
                 // Check if workflow is requested
                 if (options.workflow || options.workflowConfig) {
                     const result = await this.streamWithWorkflow(options, startTime);

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

@@ -6,7 +6,7 @@ import type { JsonValue } from "./common.js";
 import type { Content, ImageWithAltText } from "./content.js";
 import type { ChatMessage, ConversationMemoryConfig } from "./conversation.js";
 import type { EvaluationData } from "./evaluation.js";
-import type { MiddlewareFactoryOptions } from "./middlewareTypes.js";
+import type { MiddlewareFactoryOptions, OnFinishCallback, OnErrorCallback } from "./middlewareTypes.js";
 import type { DirectorModeOptions, DirectorSegment, VideoGenerationResult, VideoOutputOptions } from "./multimodal.js";
 import type { PPTGenerationResult, PPTOutputOptions } from "./pptTypes.js";
 import type { TTSOptions, TTSResult } from "./ttsTypes.js";
@@ -399,6 +399,12 @@ export type GenerateOptions = {
      * @internal Set by NeuroLink SDK — not typically used directly by consumers.
      */
     fileRegistry?: unknown;
+    /** Per-call middleware configuration. */
+    middleware?: import("./middlewareTypes.js").MiddlewareFactoryOptions;
+    /** Callback invoked when generation completes successfully. */
+    onFinish?: OnFinishCallback;
+    /** Callback invoked when generation encounters an error. */
+    onError?: OnErrorCallback;
 };
 /**
  * Generate function result type - Primary output format

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

@@ -110,7 +110,7 @@ export type MiddlewareChainStats = {
 /**
  * Built-in middleware types
  */
-export type BuiltInMiddlewareType = "analytics" | "guardrails" | "logging" | "caching" | "rateLimit" | "retry" | "timeout" | "autoEvaluation";
+export type BuiltInMiddlewareType = "analytics" | "guardrails" | "logging" | "caching" | "rateLimit" | "retry" | "timeout" | "autoEvaluation" | "lifecycle";
 /**
  * Middleware preset configurations
  */
@@ -233,3 +233,56 @@ export type MiddlewareChainConfig = {
     timeout?: number;
     retries?: number;
 };
+/**
+ * Payload delivered to onFinish callbacks after generation or streaming completes.
+ */
+export type LifecycleFinishPayload = {
+    /** The generated text content */
+    text: string;
+    /** Token usage from the provider */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+    /** Wall-clock duration in milliseconds */
+    duration: number;
+    /** Why generation stopped */
+    finishReason?: string;
+};
+/**
+ * Payload delivered to onError callbacks when generation or streaming fails.
+ */
+export type LifecycleErrorPayload = {
+    /** The error that occurred */
+    error: Error;
+    /** Wall-clock duration until failure in milliseconds */
+    duration: number;
+    /** Whether the error is likely recoverable (rate limit, timeout, network) */
+    recoverable: boolean;
+};
+/**
+ * Payload delivered to onChunk callbacks for each streaming chunk.
+ */
+export type LifecycleChunkPayload = {
+    /** Chunk type from the AI SDK stream */
+    type: string;
+    /** Text content for text-delta chunks */
+    textDelta?: string;
+    /** Zero-based chunk sequence number */
+    sequenceNumber: number;
+};
+/** Callback invoked when generation or streaming finishes successfully. */
+export type OnFinishCallback = (payload: LifecycleFinishPayload) => void | Promise<void>;
+/** Callback invoked when generation or streaming encounters an error. */
+export type OnErrorCallback = (payload: LifecycleErrorPayload) => void | Promise<void>;
+/** Callback invoked for each chunk during streaming. */
+export type OnChunkCallback = (payload: LifecycleChunkPayload) => void | Promise<void>;
+/**
+ * Configuration for the lifecycle middleware.
+ * Pass callbacks to observe generation/streaming lifecycle events.
+ */
+export type LifecycleMiddlewareConfig = {
+    onFinish?: OnFinishCallback;
+    onError?: OnErrorCallback;
+    onChunk?: OnChunkCallback;
+};

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

@@ -3,7 +3,7 @@ import type { AIProviderName } from "../constants/enums.js";
 import type { EvaluationData } from "../index.js";
 import type { RAGConfig } from "../rag/types.js";
 import type { AnalyticsData, ToolExecutionEvent, ToolExecutionSummary } from "../types/index.js";
-import type { MiddlewareFactoryOptions } from "../types/middlewareTypes.js";
+import type { MiddlewareFactoryOptions, OnFinishCallback, OnErrorCallback, OnChunkCallback } from "../types/middlewareTypes.js";
 import type { TokenUsage } from "./analytics.js";
 import type { JsonValue, UnknownRecord } from "./common.js";
 import type { Content, ImageWithAltText } from "./content.js";
@@ -409,6 +409,12 @@ export type StreamOptions = {
      * @internal Set by NeuroLink SDK — not typically used directly by consumers.
      */
     fileRegistry?: unknown;
+    /** Callback invoked when streaming completes successfully. */
+    onFinish?: OnFinishCallback;
+    /** Callback invoked when streaming encounters an error. */
+    onError?: OnErrorCallback;
+    /** Callback invoked for each streaming chunk. */
+    onChunk?: OnChunkCallback;
 };
 /**
  * Stream function result type - Primary output format for streaming

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

@@ -258,6 +258,11 @@ export declare function isAbortError(error: unknown): boolean;
  * Error handler that decides whether to retry based on error type
  */
 export declare function isRetriableError(error: Error): boolean;
+/**
+ * Determines if an error is likely recoverable (rate limit, timeout, network issues).
+ * Useful for deciding whether to retry or fail fast.
+ */
+export declare function isRecoverableError(error: Error): boolean;
 /**
  * Enhanced error logger that provides structured logging
  */

package/dist/lib/utils/errorHandling.js

@@ -865,6 +865,44 @@ export function isRetriableError(error) {
     ];
     return retriablePatterns.some((pattern) => pattern.test(error.message));
 }
+/**
+ * Determines if an error is likely recoverable (rate limit, timeout, network issues).
+ * Useful for deciding whether to retry or fail fast.
+ */
+export function isRecoverableError(error) {
+    // Check NeuroLinkError.retriable first
+    const errorWithRetriable = error;
+    if ("retriable" in error &&
+        typeof errorWithRetriable.retriable === "boolean") {
+        return errorWithRetriable.retriable;
+    }
+    const message = error.message?.toLowerCase() || "";
+    // Rate limit errors
+    if (message.includes("rate limit") || message.includes("too many requests")) {
+        return true;
+    }
+    if (/\b429\b/.test(message)) {
+        return true;
+    }
+    // Timeout errors
+    if (message.includes("timeout") ||
+        message.includes("etimedout") ||
+        message.includes("timed out")) {
+        return true;
+    }
+    // Network errors
+    if (message.includes("econnreset") ||
+        message.includes("econnrefused") ||
+        message.includes("network") ||
+        message.includes("socket")) {
+        return true;
+    }
+    // Server errors (use word boundaries to avoid false matches)
+    if (/\b50[0234]\b/.test(message)) {
+        return true;
+    }
+    return false;
+}
 /**
  * Enhanced error logger that provides structured logging
  */

package/dist/middleware/builtin/lifecycle.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Lifecycle Middleware
+ *
+ * Provides onFinish, onError, and onChunk callbacks for observing
+ * generation and streaming lifecycle events.
+ *
+ * This middleware is automatically enabled when lifecycle callbacks
+ * (onFinish, onError, onChunk) are passed in GenerateOptions or StreamOptions.
+ */
+import type { NeuroLinkMiddleware, LifecycleMiddlewareConfig } from "../../types/middlewareTypes.js";
+export declare function createLifecycleMiddleware(config?: LifecycleMiddlewareConfig): NeuroLinkMiddleware;

package/dist/middleware/builtin/lifecycle.js

@@ -0,0 +1,164 @@
+/**
+ * Lifecycle Middleware
+ *
+ * Provides onFinish, onError, and onChunk callbacks for observing
+ * generation and streaming lifecycle events.
+ *
+ * This middleware is automatically enabled when lifecycle callbacks
+ * (onFinish, onError, onChunk) are passed in GenerateOptions or StreamOptions.
+ */
+import { logger } from "../../utils/logger.js";
+import { isRecoverableError } from "../../utils/errorHandling.js";
+export function createLifecycleMiddleware(config = {}) {
+    const metadata = {
+        id: "lifecycle",
+        name: "Lifecycle Callbacks",
+        description: "Provides onFinish, onError, and onChunk callbacks for generation and streaming lifecycle events",
+        priority: 110,
+        defaultEnabled: false,
+    };
+    const middleware = {
+        wrapGenerate: async ({ doGenerate }) => {
+            const startTime = Date.now();
+            try {
+                const result = await doGenerate();
+                if (config.onFinish) {
+                    try {
+                        const callbackResult = config.onFinish({
+                            text: result.text ?? "",
+                            usage: result.usage
+                                ? {
+                                    promptTokens: result.usage.promptTokens ?? 0,
+                                    completionTokens: result.usage.completionTokens ?? 0,
+                                }
+                                : undefined,
+                            duration: Date.now() - startTime,
+                            finishReason: result.finishReason,
+                        });
+                        Promise.resolve(callbackResult).catch((e) => {
+                            logger.warn("[LifecycleMiddleware] onFinish callback error:", e);
+                        });
+                    }
+                    catch (e) {
+                        logger.warn("[LifecycleMiddleware] onFinish callback error:", e);
+                    }
+                }
+                return result;
+            }
+            catch (error) {
+                if (config.onError) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    try {
+                        const callbackResult = config.onError({
+                            error: err,
+                            duration: Date.now() - startTime,
+                            recoverable: isRecoverableError(err),
+                        });
+                        Promise.resolve(callbackResult).catch((e) => {
+                            logger.warn("[LifecycleMiddleware] onError callback error:", e);
+                        });
+                    }
+                    catch (e) {
+                        logger.warn("[LifecycleMiddleware] onError callback error:", e);
+                    }
+                }
+                throw error;
+            }
+        },
+        wrapStream: async ({ doStream }) => {
+            const startTime = Date.now();
+            try {
+                const result = await doStream();
+                if (!config.onChunk && !config.onFinish && !config.onError) {
+                    return result;
+                }
+                let sequenceNumber = 0;
+                let accumulatedText = "";
+                const transformStream = new TransformStream({
+                    transform(chunk, controller) {
+                        try {
+                            if (chunk.type === "text-delta") {
+                                accumulatedText += chunk.textDelta;
+                            }
+                            if (config.onChunk && chunk.type) {
+                                try {
+                                    const callbackResult = config.onChunk({
+                                        type: chunk.type,
+                                        textDelta: chunk.type === "text-delta" ? chunk.textDelta : undefined,
+                                        sequenceNumber: sequenceNumber++,
+                                    });
+                                    Promise.resolve(callbackResult).catch((e) => {
+                                        logger.warn("[LifecycleMiddleware] onChunk callback error:", e);
+                                    });
+                                }
+                                catch (e) {
+                                    logger.warn("[LifecycleMiddleware] onChunk callback error:", e);
+                                }
+                            }
+                            controller.enqueue(chunk);
+                        }
+                        catch (error) {
+                            if (config.onError) {
+                                const err = error instanceof Error ? error : new Error(String(error));
+                                try {
+                                    const callbackResult = config.onError({
+                                        error: err,
+                                        duration: Date.now() - startTime,
+                                        recoverable: isRecoverableError(err),
+                                    });
+                                    Promise.resolve(callbackResult).catch((e) => {
+                                        logger.warn("[LifecycleMiddleware] onError callback error:", e);
+                                    });
+                                }
+                                catch (e) {
+                                    logger.warn("[LifecycleMiddleware] onError callback error:", e);
+                                }
+                            }
+                            throw error;
+                        }
+                    },
+                    flush() {
+                        if (config.onFinish) {
+                            try {
+                                const callbackResult = config.onFinish({
+                                    text: accumulatedText,
+                                    duration: Date.now() - startTime,
+                                });
+                                Promise.resolve(callbackResult).catch((e) => {
+                                    logger.warn("[LifecycleMiddleware] onFinish callback error:", e);
+                                });
+                            }
+                            catch (e) {
+                                logger.warn("[LifecycleMiddleware] onFinish callback error:", e);
+                            }
+                        }
+                    },
+                });
+                return {
+                    ...result,
+                    stream: result.stream.pipeThrough(transformStream),
+                };
+            }
+            catch (error) {
+                if (config.onError) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    try {
+                        const callbackResult = config.onError({
+                            error: err,
+                            duration: Date.now() - startTime,
+                            recoverable: isRecoverableError(err),
+                        });
+                        Promise.resolve(callbackResult).catch((e) => {
+                            logger.warn("[LifecycleMiddleware] onError callback error:", e);
+                        });
+                    }
+                    catch (e) {
+                        logger.warn("[LifecycleMiddleware] onError callback error:", e);
+                    }
+                }
+                throw error;
+            }
+        },
+    };
+    return { ...middleware, metadata };
+}

package/dist/middleware/factory.js

@@ -3,6 +3,7 @@ import { MiddlewareRegistry } from "./registry.js";
 import { createAnalyticsMiddleware } from "./builtin/analytics.js";
 import { createGuardrailsMiddleware } from "./builtin/guardrails.js";
 import { createAutoEvaluationMiddleware } from "./builtin/autoEvaluation.js";
+import { createLifecycleMiddleware } from "./builtin/lifecycle.js";
 import { logger } from "../utils/logger.js";
 /**
  * Middleware factory for creating and applying middleware chains.
@@ -26,6 +27,7 @@ export class MiddlewareFactory {
             analytics: createAnalyticsMiddleware,
             guardrails: createGuardrailsMiddleware,
             autoEvaluation: createAutoEvaluationMiddleware,
+            lifecycle: createLifecycleMiddleware,
         };
         // Register built-in presets
         this.registerPreset({
@@ -142,6 +144,7 @@ export class MiddlewareFactory {
             analytics: createAnalyticsMiddleware,
             guardrails: createGuardrailsMiddleware,
             autoEvaluation: createAutoEvaluationMiddleware,
+            lifecycle: createLifecycleMiddleware,
         };
         logger.debug("Getting creator for middleware ID:", id);
         return builtInMiddlewareCreators[id];

package/dist/middleware/index.d.ts

@@ -9,4 +9,5 @@ import { MiddlewareFactory } from "./factory.js";
 export type { NeuroLinkMiddleware, MiddlewareConfig, MiddlewareContext, MiddlewareConditions, MiddlewareRegistrationOptions, MiddlewareExecutionResult, MiddlewareChainStats, MiddlewarePreset, MiddlewareFactoryOptions, BuiltInMiddlewareType, } from "../types/middlewareTypes.js";
 export type { LanguageModelV1Middleware } from "ai";
 export { MiddlewareFactory };
+export { createLifecycleMiddleware } from "./builtin/lifecycle.js";
 export default MiddlewareFactory;

package/dist/middleware/index.js

@@ -9,5 +9,7 @@
 import { MiddlewareFactory } from "./factory.js";
 // Factory for creating and applying middleware chains
 export { MiddlewareFactory };
+// Built-in middleware creators
+export { createLifecycleMiddleware } from "./builtin/lifecycle.js";
 // Export the factory as the default export for clean, direct usage
 export default MiddlewareFactory;

package/dist/neurolink.js

@@ -2209,6 +2209,26 @@ Current user's request: ${currentInput}`;
                             },
                         });
                     }
+                    // Auto-inject lifecycle middleware when callbacks are provided
+                    // (must happen before workflow/PPT early returns so those paths get middleware too)
+                    if (options.onFinish || options.onError) {
+                        options.middleware = {
+                            ...options.middleware,
+                            middlewareConfig: {
+                                ...options.middleware?.middlewareConfig,
+                                lifecycle: {
+                                    ...options.middleware?.middlewareConfig?.lifecycle,
+                                    enabled: true,
+                                    config: {
+                                        ...options.middleware?.middlewareConfig?.lifecycle
+                                            ?.config,
+                                        onFinish: options.onFinish,
+                                        onError: options.onError,
+                                    },
+                                },
+                            },
+                        };
+                    }
                     // Check if workflow is requested
                     if (options.workflow || options.workflowConfig) {
                         return await this.generateWithWorkflow(options);
@@ -2364,6 +2384,7 @@ Current user's request: ${currentInput}`;
                             fileRegistry: this.fileRegistry,
                             abortSignal: options.abortSignal,
                             skipToolPromptInjection: options.skipToolPromptInjection,
+                            middleware: options.middleware,
                         };
                         // Auto-map top-level sessionId/userId to context for convenience
                         // Tests and users may pass sessionId/userId as top-level options
@@ -2400,7 +2421,6 @@ Current user's request: ${currentInput}`;
                                 toolResults: toolResults.length,
                             });
                         }
-                        // Use redesigned generation logic
                         const textResult = await this.generateTextInternal(textOptions);
                         // Emit generation completion event (NeuroLink format - enhanced with content)
                         this.emitter.emit("generation:end", {
@@ -4024,6 +4044,26 @@ Current user's request: ${currentInput}`;
                     });
                 }
                 this.emitStreamStartEvents(options, startTime);
+                // Auto-inject lifecycle middleware when callbacks are provided
+                // (must happen before workflow early return so that path gets middleware too)
+                if (options.onFinish || options.onError || options.onChunk) {
+                    options.middleware = {
+                        ...options.middleware,
+                        middlewareConfig: {
+                            ...options.middleware?.middlewareConfig,
+                            lifecycle: {
+                                ...options.middleware?.middlewareConfig?.lifecycle,
+                                enabled: true,
+                                config: {
+                                    ...options.middleware?.middlewareConfig?.lifecycle?.config,
+                                    onFinish: options.onFinish,
+                                    onError: options.onError,
+                                    onChunk: options.onChunk,
+                                },
+                            },
+                        },
+                    };
+                }
                 // Check if workflow is requested
                 if (options.workflow || options.workflowConfig) {
                     const result = await this.streamWithWorkflow(options, startTime);

package/dist/types/generateTypes.d.ts

@@ -6,7 +6,7 @@ import type { JsonValue } from "./common.js";
 import type { Content, ImageWithAltText } from "./content.js";
 import type { ChatMessage, ConversationMemoryConfig } from "./conversation.js";
 import type { EvaluationData } from "./evaluation.js";
-import type { MiddlewareFactoryOptions } from "./middlewareTypes.js";
+import type { MiddlewareFactoryOptions, OnFinishCallback, OnErrorCallback } from "./middlewareTypes.js";
 import type { DirectorModeOptions, DirectorSegment, VideoGenerationResult, VideoOutputOptions } from "./multimodal.js";
 import type { PPTGenerationResult, PPTOutputOptions } from "./pptTypes.js";
 import type { TTSOptions, TTSResult } from "./ttsTypes.js";
@@ -399,6 +399,12 @@ export type GenerateOptions = {
      * @internal Set by NeuroLink SDK — not typically used directly by consumers.
      */
     fileRegistry?: unknown;
+    /** Per-call middleware configuration. */
+    middleware?: import("./middlewareTypes.js").MiddlewareFactoryOptions;
+    /** Callback invoked when generation completes successfully. */
+    onFinish?: OnFinishCallback;
+    /** Callback invoked when generation encounters an error. */
+    onError?: OnErrorCallback;
 };
 /**
  * Generate function result type - Primary output format

package/dist/types/middlewareTypes.d.ts

@@ -110,7 +110,7 @@ export type MiddlewareChainStats = {
 /**
  * Built-in middleware types
  */
-export type BuiltInMiddlewareType = "analytics" | "guardrails" | "logging" | "caching" | "rateLimit" | "retry" | "timeout" | "autoEvaluation";
+export type BuiltInMiddlewareType = "analytics" | "guardrails" | "logging" | "caching" | "rateLimit" | "retry" | "timeout" | "autoEvaluation" | "lifecycle";
 /**
  * Middleware preset configurations
  */
@@ -233,3 +233,56 @@ export type MiddlewareChainConfig = {
     timeout?: number;
     retries?: number;
 };
+/**
+ * Payload delivered to onFinish callbacks after generation or streaming completes.
+ */
+export type LifecycleFinishPayload = {
+    /** The generated text content */
+    text: string;
+    /** Token usage from the provider */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+    /** Wall-clock duration in milliseconds */
+    duration: number;
+    /** Why generation stopped */
+    finishReason?: string;
+};
+/**
+ * Payload delivered to onError callbacks when generation or streaming fails.
+ */
+export type LifecycleErrorPayload = {
+    /** The error that occurred */
+    error: Error;
+    /** Wall-clock duration until failure in milliseconds */
+    duration: number;
+    /** Whether the error is likely recoverable (rate limit, timeout, network) */
+    recoverable: boolean;
+};
+/**
+ * Payload delivered to onChunk callbacks for each streaming chunk.
+ */
+export type LifecycleChunkPayload = {
+    /** Chunk type from the AI SDK stream */
+    type: string;
+    /** Text content for text-delta chunks */
+    textDelta?: string;
+    /** Zero-based chunk sequence number */
+    sequenceNumber: number;
+};
+/** Callback invoked when generation or streaming finishes successfully. */
+export type OnFinishCallback = (payload: LifecycleFinishPayload) => void | Promise<void>;
+/** Callback invoked when generation or streaming encounters an error. */
+export type OnErrorCallback = (payload: LifecycleErrorPayload) => void | Promise<void>;
+/** Callback invoked for each chunk during streaming. */
+export type OnChunkCallback = (payload: LifecycleChunkPayload) => void | Promise<void>;
+/**
+ * Configuration for the lifecycle middleware.
+ * Pass callbacks to observe generation/streaming lifecycle events.
+ */
+export type LifecycleMiddlewareConfig = {
+    onFinish?: OnFinishCallback;
+    onError?: OnErrorCallback;
+    onChunk?: OnChunkCallback;
+};

package/dist/types/streamTypes.d.ts

@@ -3,7 +3,7 @@ import type { AIProviderName } from "../constants/enums.js";
 import type { EvaluationData } from "../index.js";
 import type { RAGConfig } from "../rag/types.js";
 import type { AnalyticsData, ToolExecutionEvent, ToolExecutionSummary } from "../types/index.js";
-import type { MiddlewareFactoryOptions } from "../types/middlewareTypes.js";
+import type { MiddlewareFactoryOptions, OnFinishCallback, OnErrorCallback, OnChunkCallback } from "../types/middlewareTypes.js";
 import type { TokenUsage } from "./analytics.js";
 import type { JsonValue, UnknownRecord } from "./common.js";
 import type { Content, ImageWithAltText } from "./content.js";
@@ -409,6 +409,12 @@ export type StreamOptions = {
      * @internal Set by NeuroLink SDK — not typically used directly by consumers.
      */
     fileRegistry?: unknown;
+    /** Callback invoked when streaming completes successfully. */
+    onFinish?: OnFinishCallback;
+    /** Callback invoked when streaming encounters an error. */
+    onError?: OnErrorCallback;
+    /** Callback invoked for each streaming chunk. */
+    onChunk?: OnChunkCallback;
 };
 /**
  * Stream function result type - Primary output format for streaming

package/dist/utils/errorHandling.d.ts

@@ -258,6 +258,11 @@ export declare function isAbortError(error: unknown): boolean;
  * Error handler that decides whether to retry based on error type
  */
 export declare function isRetriableError(error: Error): boolean;
+/**
+ * Determines if an error is likely recoverable (rate limit, timeout, network issues).
+ * Useful for deciding whether to retry or fail fast.
+ */
+export declare function isRecoverableError(error: Error): boolean;
 /**
  * Enhanced error logger that provides structured logging
  */

package/dist/utils/errorHandling.js

@@ -865,6 +865,44 @@ export function isRetriableError(error) {
     ];
     return retriablePatterns.some((pattern) => pattern.test(error.message));
 }
+/**
+ * Determines if an error is likely recoverable (rate limit, timeout, network issues).
+ * Useful for deciding whether to retry or fail fast.
+ */
+export function isRecoverableError(error) {
+    // Check NeuroLinkError.retriable first
+    const errorWithRetriable = error;
+    if ("retriable" in error &&
+        typeof errorWithRetriable.retriable === "boolean") {
+        return errorWithRetriable.retriable;
+    }
+    const message = error.message?.toLowerCase() || "";
+    // Rate limit errors
+    if (message.includes("rate limit") || message.includes("too many requests")) {
+        return true;
+    }
+    if (/\b429\b/.test(message)) {
+        return true;
+    }
+    // Timeout errors
+    if (message.includes("timeout") ||
+        message.includes("etimedout") ||
+        message.includes("timed out")) {
+        return true;
+    }
+    // Network errors
+    if (message.includes("econnreset") ||
+        message.includes("econnrefused") ||
+        message.includes("network") ||
+        message.includes("socket")) {
+        return true;
+    }
+    // Server errors (use word boundaries to avoid false matches)
+    if (/\b50[0234]\b/.test(message)) {
+        return true;
+    }
+    return false;
+}
 /**
  * Enhanced error logger that provides structured logging
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.29.1",
+  "version": "9.30.0",
   "description": "Universal AI Development Platform with working MCP integration, multi-provider support, and professional CLI. Built-in tools operational, 58+ external MCP servers discoverable. Connect to filesystem, GitHub, database operations, and more. Build, test, and deploy AI applications with 13 providers: OpenAI, Anthropic, Google AI, AWS Bedrock, Azure, Hugging Face, Ollama, and Mistral AI.",
   "author": {
     "name": "Juspay Technologies",
@@ -66,6 +66,7 @@
     "test:mcp": "npx tsx test/continuous-test-suite-mcp-http.ts",
     "test:media": "npx tsx test/continuous-test-suite-media-gen.ts",
     "test:memory": "npx tsx test/continuous-test-suite-memory.ts",
+    "test:middleware": "npx tsx test/continuous-test-suite-middleware.ts",
     "test:observability": "npx tsx test/continuous-test-suite-observability.ts",
     "test:ppt": "npx tsx test/continuous-test-suite-ppt.ts",
     "test:providers": "npx tsx test/continuous-test-suite-providers.ts",