@node-llm/core 1.9.0 → 1.10.0

package/dist/chat/Chat.js

@@ -5,6 +5,7 @@ import { ChatStream } from "./ChatStream.js";
 import { ModelRegistry } from "../models/ModelRegistry.js";
 import { Schema } from "../schema/Schema.js";
 import { toJsonSchema } from "../schema/to-json-schema.js";
+import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { config } from "../config.js";
 import { ToolExecutionMode } from "../constants.js";
@@ -12,6 +13,7 @@ import { ConfigurationError } from "../errors/index.js";
 import { ChatValidator } from "./Validation.js";
 import { ToolHandler } from "./ToolHandler.js";
 import { logger } from "../utils/logger.js";
+import { runMiddleware } from "../utils/middleware-runner.js";
 import { ChatResponseString } from "./ChatResponse.js";
 export class Chat {
     provider;
@@ -20,10 +22,12 @@ export class Chat {
     messages = [];
     systemMessages = [];
     executor;
+    middlewares = [];
     constructor(provider, model, options = {}, retryConfig = { attempts: 1, delayMs: 0 }) {
         this.provider = provider;
         this.model = model;
         this.options = options;
+        this.middlewares = options.middlewares || [];
         this.executor = new Executor(provider, retryConfig);
         if (options.systemPrompt) {
             this.withInstructions(options.systemPrompt);
@@ -302,6 +306,8 @@ export class Chat {
      * Ask the model a question
      */
     async ask(content, options) {
+        const requestId = randomUUID();
+        const state = {};
         let messageContent = content;
         const files = [...(options?.images ?? []), ...(options?.files ?? [])];
         if (files.length > 0) {
@@ -332,146 +338,74 @@ export class Chat {
                 }
             };
         }
-        const executeOptions = {
+        // Prepare Middleware Context
+        const context = {
+            requestId,
+            provider: this.provider.id,
             model: this.model,
             messages: [...this.systemMessages, ...this.messages],
-            tools: this.options.tools,
-            temperature: options?.temperature ?? this.options.temperature,
-            max_tokens: options?.maxTokens ?? this.options.maxTokens ?? config.maxTokens,
-            headers: { ...this.options.headers, ...options?.headers },
-            response_format: responseFormat, // Pass to provider
-            requestTimeout: options?.requestTimeout ?? this.options.requestTimeout ?? config.requestTimeout,
-            thinking: options?.thinking ?? this.options.thinking,
-            signal: options?.signal,
-            ...this.options.params
+            options: this.options,
+            state
         };
-        // --- Content Policy Hooks (Input) ---
-        if (this.options.onBeforeRequest) {
-            const messagesToProcess = [...this.systemMessages, ...this.messages];
-            const result = await this.options.onBeforeRequest(messagesToProcess);
-            if (result) {
-                // If the hook returned modified messages, use them for this request
-                executeOptions.messages = result;
-            }
-        }
-        const totalUsage = { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
-        const trackUsage = (u) => {
-            if (u) {
-                // Fallback cost calculation if provider didn't return it
-                if (u.cost === undefined) {
-                    const withCost = ModelRegistry.calculateCost(u, this.model, this.provider.id);
-                    u.cost = withCost.cost;
-                    u.input_cost = withCost.input_cost;
-                    u.output_cost = withCost.output_cost;
-                }
-                totalUsage.input_tokens += u.input_tokens;
-                totalUsage.output_tokens += u.output_tokens;
-                totalUsage.total_tokens += u.total_tokens;
-                if (u.cached_tokens) {
-                    totalUsage.cached_tokens = (totalUsage.cached_tokens ?? 0) + u.cached_tokens;
-                }
-                if (u.cost !== undefined) {
-                    totalUsage.cost = (totalUsage.cost ?? 0) + u.cost;
-                }
-                if (u.input_cost !== undefined) {
-                    totalUsage.input_cost = (totalUsage.input_cost ?? 0) + u.input_cost;
-                }
-                if (u.output_cost !== undefined) {
-                    totalUsage.output_cost = (totalUsage.output_cost ?? 0) + u.output_cost;
+        try {
+            // 1. onRequest Hook
+            await runMiddleware(this.middlewares, "onRequest", context);
+            // Re-read mutable context
+            const messagesToUse = context.messages || [];
+            const executeOptions = {
+                model: this.model,
+                messages: messagesToUse,
+                tools: this.options.tools,
+                temperature: options?.temperature ?? this.options.temperature,
+                max_tokens: options?.maxTokens ?? this.options.maxTokens ?? config.maxTokens,
+                headers: { ...this.options.headers, ...options?.headers },
+                response_format: responseFormat, // Pass to provider
+                requestTimeout: options?.requestTimeout ?? this.options.requestTimeout ?? config.requestTimeout,
+                thinking: options?.thinking ?? this.options.thinking,
+                signal: options?.signal,
+                ...this.options.params
+            };
+            // --- Content Policy Hooks (Input) ---
+            if (this.options.onBeforeRequest) {
+                const result = await this.options.onBeforeRequest(executeOptions.messages);
+                if (result) {
+                    executeOptions.messages = result;
                 }
             }
-        };
-        // First round
-        if (this.options.onNewMessage)
-            this.options.onNewMessage();
-        let response = await this.executor.executeChat(executeOptions);
-        trackUsage(response.usage);
-        let assistantMessage = new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model, this.provider.id, response.thinking, response.reasoning, response.tool_calls, response.finish_reason, this.options.schema);
-        // --- Content Policy Hooks (Output - Turn 1) ---
-        if (this.options.onAfterResponse) {
-            const result = await this.options.onAfterResponse(assistantMessage);
-            if (result) {
-                assistantMessage = result;
-            }
-        }
-        this.messages.push({
-            role: "assistant",
-            content: assistantMessage?.toString() || null,
-            tool_calls: response.tool_calls,
-            usage: response.usage
-        });
-        if (this.options.onEndMessage && (!response.tool_calls || response.tool_calls.length === 0)) {
-            this.options.onEndMessage(assistantMessage);
-        }
-        const maxToolCalls = options?.maxToolCalls ?? this.options.maxToolCalls ?? 5;
-        let stepCount = 0;
-        while (response.tool_calls && response.tool_calls.length > 0) {
-            // Dry-run mode: stop after proposing tools
-            if (!ToolHandler.shouldExecuteTools(response.tool_calls, this.options.toolExecution)) {
-                break;
-            }
-            stepCount++;
-            if (stepCount > maxToolCalls) {
-                throw new Error(`[NodeLLM] Maximum tool execution calls (${maxToolCalls}) exceeded.`);
-            }
-            for (const toolCall of response.tool_calls) {
-                // Human-in-the-loop: check for approval
-                if (this.options.toolExecution === ToolExecutionMode.CONFIRM) {
-                    const approved = await ToolHandler.requestToolConfirmation(toolCall, this.options.onConfirmToolCall);
-                    if (!approved) {
-                        this.messages.push(this.provider.formatToolResultMessage(toolCall.id, "Action cancelled by user."));
-                        continue;
+            const totalUsage = { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
+            const trackUsage = (u) => {
+                if (u) {
+                    // Fallback cost calculation if provider didn't return it
+                    if (u.cost === undefined) {
+                        const withCost = ModelRegistry.calculateCost(u, this.model, this.provider.id);
+                        u.cost = withCost.cost;
+                        u.input_cost = withCost.input_cost;
+                        u.output_cost = withCost.output_cost;
                     }
-                }
-                try {
-                    const toolResult = await ToolHandler.execute(toolCall, this.options.tools, this.options.onToolCallStart, this.options.onToolCallEnd);
-                    this.messages.push(this.provider.formatToolResultMessage(toolResult.tool_call_id, toolResult.content));
-                }
-                catch (error) {
-                    let currentError = error;
-                    const directive = await this.options.onToolCallError?.(toolCall, currentError);
-                    if (directive === "STOP") {
-                        throw currentError;
+                    totalUsage.input_tokens += u.input_tokens;
+                    totalUsage.output_tokens += u.output_tokens;
+                    totalUsage.total_tokens += u.total_tokens;
+                    if (u.cached_tokens) {
+                        totalUsage.cached_tokens = (totalUsage.cached_tokens ?? 0) + u.cached_tokens;
                     }
-                    if (directive === "RETRY") {
-                        try {
-                            const toolResult = await ToolHandler.execute(toolCall, this.options.tools, this.options.onToolCallStart, this.options.onToolCallEnd);
-                            this.messages.push(this.provider.formatToolResultMessage(toolResult.tool_call_id, toolResult.content));
-                            continue;
-                        }
-                        catch (retryError) {
-                            // If retry also fails, fall through to default logic
-                            currentError = retryError;
-                        }
+                    if (u.cost !== undefined) {
+                        totalUsage.cost = (totalUsage.cost ?? 0) + u.cost;
                     }
-                    this.messages.push(this.provider.formatToolResultMessage(toolCall.id, `Fatal error executing tool '${toolCall.function.name}': ${currentError.message}`, { isError: true }));
-                    if (directive === "CONTINUE") {
-                        continue;
+                    if (u.input_cost !== undefined) {
+                        totalUsage.input_cost = (totalUsage.input_cost ?? 0) + u.input_cost;
                     }
-                    // Default short-circuit logic
-                    const errorObj = currentError;
-                    const isFatal = errorObj.fatal === true || errorObj.status === 401 || errorObj.status === 403;
-                    if (isFatal) {
-                        throw currentError;
+                    if (u.output_cost !== undefined) {
+                        totalUsage.output_cost = (totalUsage.output_cost ?? 0) + u.output_cost;
                     }
-                    logger.error(`Tool execution failed for '${toolCall.function.name}':`, currentError);
                 }
-            }
-            response = await this.executor.executeChat({
-                model: this.model,
-                messages: [...this.systemMessages, ...this.messages],
-                tools: this.options.tools,
-                temperature: options?.temperature ?? this.options.temperature,
-                max_tokens: options?.maxTokens ?? this.options.maxTokens ?? config.maxTokens,
-                headers: this.options.headers,
-                response_format: responseFormat,
-                requestTimeout: options?.requestTimeout ?? this.options.requestTimeout ?? config.requestTimeout,
-                signal: options?.signal,
-                ...this.options.params
-            });
+            };
+            // First round
+            if (this.options.onNewMessage)
+                this.options.onNewMessage();
+            let response = await this.executor.executeChat(executeOptions);
             trackUsage(response.usage);
-            assistantMessage = new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model, this.provider.id, response.thinking, response.reasoning, response.tool_calls, response.finish_reason, this.options.schema);
-            // --- Content Policy Hooks (Output - Tool Turns) ---
+            let assistantMessage = new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model, this.provider.id, response.thinking, response.reasoning, response.tool_calls, response.finish_reason, this.options.schema);
+            // --- Content Policy Hooks (Output - Turn 1) ---
             if (this.options.onAfterResponse) {
                 const result = await this.options.onAfterResponse(assistantMessage);
                 if (result) {
@@ -487,10 +421,114 @@ export class Chat {
             if (this.options.onEndMessage && (!response.tool_calls || response.tool_calls.length === 0)) {
                 this.options.onEndMessage(assistantMessage);
             }
+            const maxToolCalls = options?.maxToolCalls ?? this.options.maxToolCalls ?? 5;
+            let stepCount = 0;
+            while (response.tool_calls && response.tool_calls.length > 0) {
+                // Dry-run mode: stop after proposing tools
+                if (!ToolHandler.shouldExecuteTools(response.tool_calls, this.options.toolExecution)) {
+                    break;
+                }
+                stepCount++;
+                if (stepCount > maxToolCalls) {
+                    throw new Error(`[NodeLLM] Maximum tool execution calls (${maxToolCalls}) exceeded.`);
+                }
+                for (const toolCall of response.tool_calls) {
+                    // Human-in-the-loop: check for approval
+                    if (this.options.toolExecution === ToolExecutionMode.CONFIRM) {
+                        const approved = await ToolHandler.requestToolConfirmation(toolCall, this.options.onConfirmToolCall);
+                        if (!approved) {
+                            this.messages.push(this.provider.formatToolResultMessage(toolCall.id, "Action cancelled by user."));
+                            continue;
+                        }
+                    }
+                    // 2. onToolCallStart Hook
+                    await runMiddleware(this.middlewares, "onToolCallStart", context, toolCall);
+                    try {
+                        const toolResult = await ToolHandler.execute(toolCall, this.options.tools, this.options.onToolCallStart, this.options.onToolCallEnd);
+                        // 3. onToolCallEnd Hook
+                        await runMiddleware(this.middlewares, "onToolCallEnd", context, toolCall, toolResult.content);
+                        this.messages.push(this.provider.formatToolResultMessage(toolResult.tool_call_id, toolResult.content));
+                    }
+                    catch (error) {
+                        let currentError = error;
+                        // 4. onToolCallError Hook
+                        const middlewareDirective = await runMiddleware(this.middlewares, "onToolCallError", context, toolCall, currentError);
+                        const directive = middlewareDirective ||
+                            (await this.options.onToolCallError?.(toolCall, currentError));
+                        if (directive === "STOP") {
+                            throw currentError;
+                        }
+                        if (directive === "RETRY") {
+                            // ... retry logic (simplified: recurse or duplicate logic? adhering to original logic)
+                            // Original logic duplicated the execution block. For brevity in this replacement, I'll simplified retry to "try once more"
+                            try {
+                                // Retry Hook? Maybe skip start hook on retry or re-run?
+                                // Let's assume onToolCallStart fires again for cleanliness?
+                                // Or just execute directly to match existing behavior.
+                                // Existing logs show we just call ToolHandler.execute again.
+                                const toolResult = await ToolHandler.execute(toolCall, this.options.tools, this.options.onToolCallStart, this.options.onToolCallEnd);
+                                await runMiddleware(this.middlewares, "onToolCallEnd", context, toolCall, toolResult.content);
+                                this.messages.push(this.provider.formatToolResultMessage(toolResult.tool_call_id, toolResult.content));
+                                continue;
+                            }
+                            catch (retryError) {
+                                currentError = retryError;
+                                await runMiddleware(this.middlewares, "onToolCallError", context, toolCall, currentError);
+                            }
+                        }
+                        this.messages.push(this.provider.formatToolResultMessage(toolCall.id, `Fatal error executing tool '${toolCall.function.name}': ${currentError.message}`, { isError: true }));
+                        if (directive === "CONTINUE") {
+                            continue;
+                        }
+                        // Default short-circuit logic
+                        const errorObj = currentError;
+                        const isFatal = errorObj.fatal === true || errorObj.status === 401 || errorObj.status === 403;
+                        if (isFatal) {
+                            throw currentError;
+                        }
+                        logger.error(`Tool execution failed for '${toolCall.function.name}':`, currentError);
+                    }
+                }
+                response = await this.executor.executeChat({
+                    model: this.model,
+                    messages: [...this.systemMessages, ...this.messages], // Use updated history
+                    tools: this.options.tools,
+                    temperature: options?.temperature ?? this.options.temperature,
+                    max_tokens: options?.maxTokens ?? this.options.maxTokens ?? config.maxTokens,
+                    headers: this.options.headers,
+                    response_format: responseFormat, // Pass to provider
+                    requestTimeout: options?.requestTimeout ?? this.options.requestTimeout ?? config.requestTimeout,
+                    signal: options?.signal,
+                    ...this.options.params
+                });
+                trackUsage(response.usage);
+                assistantMessage = new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model, this.provider.id, response.thinking, response.reasoning, response.tool_calls, response.finish_reason, this.options.schema);
+                if (this.options.onAfterResponse) {
+                    const result = await this.options.onAfterResponse(assistantMessage);
+                    if (result)
+                        assistantMessage = result;
+                }
+                this.messages.push({
+                    role: "assistant",
+                    content: assistantMessage?.toString() || null,
+                    tool_calls: response.tool_calls,
+                    usage: response.usage
+                });
+                if (this.options.onEndMessage &&
+                    (!response.tool_calls || response.tool_calls.length === 0)) {
+                    this.options.onEndMessage(assistantMessage);
+                }
+            }
+            const finalResponse = new ChatResponseString(assistantMessage.toString() || "", totalUsage, this.model, this.provider.id, assistantMessage.thinking, assistantMessage.reasoning, response.tool_calls, assistantMessage.finish_reason, this.options.schema);
+            // 5. onResponse Hook
+            await runMiddleware(this.middlewares, "onResponse", context, finalResponse);
+            return finalResponse;
+        }
+        catch (err) {
+            // 6. onError Hook
+            await runMiddleware(this.middlewares, "onError", context, err);
+            throw err;
         }
-        // For the final return, we might want to aggregate reasoning too if it happened in multiple turns?
-        // Usually reasoning only happens once or we just want the last one.
-        return new ChatResponseString(assistantMessage.toString() || "", totalUsage, this.model, this.provider.id, assistantMessage.thinking, assistantMessage.reasoning, response.tool_calls, assistantMessage.finish_reason, this.options.schema);
     }
     /**
      * Streams the model's response to a user question.

package/dist/chat/ChatOptions.d.ts

@@ -1,3 +1,4 @@
+import { Middleware } from "../types/Middleware.js";
 import { Message } from "./Message.js";
 import { ToolResolvable } from "./Tool.js";
 import { Schema } from "../schema/Schema.js";
@@ -6,6 +7,7 @@ import { ToolExecutionMode } from "../constants.js";
 import { ResponseFormat, ThinkingConfig } from "../providers/Provider.js";
 export interface ChatOptions {
     systemPrompt?: string;
+    middlewares?: Middleware[];
     messages?: Message[];
     tools?: ToolResolvable[];
     temperature?: number;

package/dist/chat/ChatOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChatOptions.d.ts","sourceRoot":"","sources":["../../src/chat/ChatOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1E,MAAM,WAAW,WAAW;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;IACrD,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9C,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7D,eAAe,CAAC,EAAE,CAChB,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,KAAK,KACT,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACtE,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACrE,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;CACxF"}
+{"version":3,"file":"ChatOptions.d.ts","sourceRoot":"","sources":["../../src/chat/ChatOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1E,MAAM,WAAW,WAAW;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;IACrD,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9C,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7D,eAAe,CAAC,EAAE,CAChB,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,KAAK,KACT,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACtE,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACrE,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;CACxF"}

package/dist/chat/ChatStream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChatStream.d.ts","sourceRoot":"","sources":["../../src/chat/ChatStream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EACL,WAAW,EAIZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAyB,MAAM,0BAA0B,CAAC;AAEtF,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAGhD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAUvC;;;GAGG;AACH,qBAAa,UAAU;IAKnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAY;IAC5B,OAAO,CAAC,cAAc,CAAY;gBAGf,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,EAC1C,QAAQ,CAAC,EAAE,OAAO,EAAE,EACpB,cAAc,CAAC,EAAE,OAAO,EAAE;IA6B5B,IAAI,OAAO,IAAI,SAAS,OAAO,EAAE,CAEhC;IAED,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,EAAE,OAAO,GAAE,UAAe,GAAG,MAAM,CAAC,SAAS,CAAC;CA0RrF"}
+{"version":3,"file":"ChatStream.d.ts","sourceRoot":"","sources":["../../src/chat/ChatStream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EACL,WAAW,EAIZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAyB,MAAM,0BAA0B,CAAC;AAEtF,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAGhD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAavC;;;GAGG;AACH,qBAAa,UAAU;IAKnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAY;IAC5B,OAAO,CAAC,cAAc,CAAY;gBAGf,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,EAC1C,QAAQ,CAAC,EAAE,OAAO,EAAE,EACpB,cAAc,CAAC,EAAE,OAAO,EAAE;IA6B5B,IAAI,OAAO,IAAI,SAAS,OAAO,EAAE,CAEhC;IAED,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,EAAE,OAAO,GAAE,UAAe,GAAG,MAAM,CAAC,SAAS,CAAC;CA8WrF"}

package/dist/chat/ChatStream.js

@@ -9,6 +9,8 @@ import { ChatValidator } from "./Validation.js";
 import { ToolHandler } from "./ToolHandler.js";
 import { logger } from "../utils/logger.js";
 import { ModelRegistry } from "../models/ModelRegistry.js";
+import { runMiddleware } from "../utils/middleware-runner.js";
+import { randomUUID } from "node:crypto";
 /**
  * Internal handler for chat streaming logic.
  * Wraps the provider's stream with side effects like history updates and events.
@@ -58,6 +60,9 @@ export class ChatStream {
                 ...requestOptions,
                 headers: { ...baseOptions.headers, ...requestOptions.headers }
             };
+            const requestId = randomUUID();
+            const state = {};
+            const middlewares = options.middlewares || [];
             // Process Multimodal Content
             let messageContent = content;
             const files = [...(requestOptions.images ?? []), ...(requestOptions.files ?? [])];
@@ -71,63 +76,73 @@ export class ChatStream {
                 ChatValidator.validateTools(provider, model, true, options);
             }
             messages.push({ role: "user", content: messageContent });
-            if (!provider.stream) {
-                throw new Error("Streaming not supported by provider");
-            }
-            // Process Schema/Structured Output
-            let responseFormat = options.responseFormat;
-            if (!responseFormat && options.schema) {
-                ChatValidator.validateStructuredOutput(provider, model, true, options);
-                const jsonSchema = toJsonSchema(options.schema.definition.schema);
-                responseFormat = {
-                    type: "json_schema",
-                    json_schema: {
-                        name: options.schema.definition.name,
-                        description: options.schema.definition.description,
-                        strict: options.schema.definition.strict ?? true,
-                        schema: jsonSchema
+            // Prepare Middleware Context
+            const context = {
+                requestId,
+                provider: provider.id,
+                model: model,
+                messages: [...systemMessages, ...messages],
+                options: options,
+                state
+            };
+            try {
+                // 1. onRequest Hook
+                await runMiddleware(middlewares, "onRequest", context);
+                if (!provider.stream) {
+                    throw new Error("Streaming not supported by provider");
+                }
+                // Process Schema/Structured Output
+                let responseFormat = options.responseFormat;
+                if (!responseFormat && options.schema) {
+                    ChatValidator.validateStructuredOutput(provider, model, true, options);
+                    const jsonSchema = toJsonSchema(options.schema.definition.schema);
+                    responseFormat = {
+                        type: "json_schema",
+                        json_schema: {
+                            name: options.schema.definition.name,
+                            description: options.schema.definition.description,
+                            strict: options.schema.definition.strict ?? true,
+                            schema: jsonSchema
+                        }
+                    };
+                }
+                let isFirst = true;
+                const maxToolCalls = options.maxToolCalls ?? 5;
+                let stepCount = 0;
+                const totalUsage = { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
+                const trackUsage = (u) => {
+                    if (u) {
+                        // Fallback cost calculation if provider didn't return it
+                        if (u.cost === undefined) {
+                            const withCost = ModelRegistry.calculateCost(u, model, provider.id);
+                            u.cost = withCost.cost;
+                            u.input_cost = withCost.input_cost;
+                            u.output_cost = withCost.output_cost;
+                        }
+                        totalUsage.input_tokens += u.input_tokens;
+                        totalUsage.output_tokens += u.output_tokens;
+                        totalUsage.total_tokens += u.total_tokens;
+                        if (u.cached_tokens) {
+                            totalUsage.cached_tokens = (totalUsage.cached_tokens ?? 0) + u.cached_tokens;
+                        }
+                        if (u.cost !== undefined) {
+                            totalUsage.cost = (totalUsage.cost ?? 0) + u.cost;
+                        }
                     }
                 };
-            }
-            if (!provider.stream) {
-                throw new Error("Streaming not supported by provider");
-            }
-            let isFirst = true;
-            const maxToolCalls = options.maxToolCalls ?? 5;
-            let stepCount = 0;
-            const totalUsage = { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
-            const trackUsage = (u) => {
-                if (u) {
-                    // Fallback cost calculation if provider didn't return it
-                    if (u.cost === undefined) {
-                        const withCost = ModelRegistry.calculateCost(u, model, provider.id);
-                        u.cost = withCost.cost;
-                        u.input_cost = withCost.input_cost;
-                        u.output_cost = withCost.output_cost;
+                let assistantResponse;
+                while (true) {
+                    stepCount++;
+                    if (stepCount > maxToolCalls) {
+                        throw new Error(`[NodeLLM] Maximum tool execution calls (${maxToolCalls}) exceeded during streaming.`);
                     }
-                    totalUsage.input_tokens += u.input_tokens;
-                    totalUsage.output_tokens += u.output_tokens;
-                    totalUsage.total_tokens += u.total_tokens;
-                    if (u.cached_tokens) {
-                        totalUsage.cached_tokens = (totalUsage.cached_tokens ?? 0) + u.cached_tokens;
-                    }
-                    if (u.cost !== undefined) {
-                        totalUsage.cost = (totalUsage.cost ?? 0) + u.cost;
-                    }
-                }
-            };
-            while (true) {
-                stepCount++;
-                if (stepCount > maxToolCalls) {
-                    throw new Error(`[NodeLLM] Maximum tool execution calls (${maxToolCalls}) exceeded during streaming.`);
-                }
-                let fullContent = "";
-                let fullReasoning = "";
-                const thinking = { text: "" };
-                let toolCalls;
-                let currentTurnUsage;
-                try {
-                    let requestMessages = [...systemMessages, ...messages];
+                    let fullContent = "";
+                    let fullReasoning = "";
+                    const thinking = { text: "" };
+                    let toolCalls;
+                    let currentTurnUsage;
+                    context.messages = [...systemMessages, ...messages];
+                    let requestMessages = context.messages; // Use up-to-date messages from context
                     if (options.onBeforeRequest) {
                         const result = await options.onBeforeRequest(requestMessages);
                         if (result) {
@@ -180,7 +195,7 @@ export class ChatStream {
                             trackUsage(currentTurnUsage);
                         }
                     }
-                    let assistantResponse = new ChatResponseString(fullContent || "", currentTurnUsage || { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, model, provider.id, thinking.text || thinking.signature ? thinking : undefined, fullReasoning || undefined, toolCalls, undefined, // finish_reason
+                    assistantResponse = new ChatResponseString(fullContent || "", currentTurnUsage || { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, model, provider.id, thinking.text || thinking.signature ? thinking : undefined, fullReasoning || undefined, toolCalls, undefined, // finish_reason
                     options.schema);
                     if (options.onAfterResponse) {
                         const result = await options.onAfterResponse(assistantResponse);
@@ -212,34 +227,62 @@ export class ChatStream {
                                 continue;
                             }
                         }
+                        // 2. onToolCallStart Hook
+                        await runMiddleware(middlewares, "onToolCallStart", context, toolCall);
                         try {
                             const toolResult = await ToolHandler.execute(toolCall, options.tools, options.onToolCallStart, options.onToolCallEnd);
+                            // 3. onToolCallEnd Hook
+                            await runMiddleware(middlewares, "onToolCallEnd", context, toolCall, toolResult.content);
                             messages.push(provider.formatToolResultMessage(toolResult.tool_call_id, toolResult.content));
                         }
                         catch (error) {
-                            const err = error;
-                            const directive = await options.onToolCallError?.(toolCall, err);
+                            let currentError = error;
+                            // 4. onToolCallError Hook
+                            const middlewareDirective = await runMiddleware(middlewares, "onToolCallError", context, toolCall, currentError);
+                            const directive = middlewareDirective || (await options.onToolCallError?.(toolCall, currentError));
                             if (directive === "STOP") {
                                 throw error;
                             }
-                            messages.push(provider.formatToolResultMessage(toolCall.id, `Fatal error executing tool '${toolCall.function.name}': ${err.message}`, { isError: true }));
+                            if (directive === "RETRY") {
+                                try {
+                                    const toolResult = await ToolHandler.execute(toolCall, options.tools, options.onToolCallStart, options.onToolCallEnd);
+                                    await runMiddleware(middlewares, "onToolCallEnd", context, toolCall, toolResult.content);
+                                    messages.push(provider.formatToolResultMessage(toolResult.tool_call_id, toolResult.content));
+                                    continue;
+                                }
+                                catch (retryError) {
+                                    currentError = retryError;
+                                    await runMiddleware(middlewares, "onToolCallError", context, toolCall, currentError);
+                                }
+                            }
+                            messages.push(provider.formatToolResultMessage(toolCall.id, `Fatal error executing tool '${toolCall.function.name}': ${currentError.message}`, { isError: true }));
                             if (directive === "CONTINUE") {
                                 continue;
                             }
-                            const isFatal = err.fatal === true || err.status === 401 || err.status === 403;
+                            const isFatal = currentError.fatal === true ||
+                                currentError.status === 401 ||
+                                currentError.status === 403;
                             if (isFatal) {
-                                throw err;
+                                throw currentError;
                             }
-                            logger.error(`Tool execution failed for '${toolCall.function.name}':`, error);
+                            logger.error(`Tool execution failed for '${toolCall.function.name}':`, currentError);
                         }
                     }
+                    // Loop continues -> streaming next chunk
                 }
-                catch (error) {
-                    if (error instanceof Error && error.name === "AbortError") {
-                        // Aborted
-                    }
-                    throw error;
+                // 5. onResponse Hook
+                if (assistantResponse) {
+                    await runMiddleware(middlewares, "onResponse", context, assistantResponse);
+                }
+            }
+            catch (err) {
+                // 6. onError Hook
+                await runMiddleware(middlewares, "onError", context, err);
+                if (err instanceof Error && err.name === "AbortError") {
+                    // Aborted, still maybe want onError? Middleware logic says "onError".
+                    // But rethrow for sure.
                 }
+                throw err;
             }
         };
         return new Stream(() => sideEffectGenerator(this, this.provider, this.model, this.messages, this.systemMessages, this.options, controller, content, options), controller);

package/dist/index.d.ts

@@ -6,6 +6,9 @@ export * from "./chat/ChatResponse.js";
 export * from "./chat/Chat.js";
 export * from "./chat/ChatStream.js";
 export * from "./streaming/Stream.js";
+export * from "./errors/index.js";
+export type { Middleware, MiddlewareContext } from "./types/Middleware.js";
+export * from "./middlewares/index.js";
 export { z } from "zod";
 export { NodeLLM, LegacyNodeLLM, createLLM, NodeLLMCore, Transcription, Moderation, Embedding, ModelRegistry, PricingRegistry } from "./llm.js";
 export { config } from "./config.js";