@node-llm/core 1.10.0 → 1.11.0

package/README.md

@@ -1,8 +1,8 @@
 # @node-llm/core
 
 <p align="left">
-  <a href="https://node-llm.eshaiju.com/">
-    <img src="https://node-llm.eshaiju.com/assets/images/logo.jpg" alt="NodeLLM logo" width="300" />
+  <a href="https://nodellm.dev/">
+    <img src="https://nodellm.dev/assets/images/logo.jpg" alt="NodeLLM logo" width="300" />
   </a>
 </p>
 
@@ -139,6 +139,54 @@ const safetyMiddleware = {
 
 ---
 
+## 🤖 Agent Class
+
+Define reusable, class-configured agents with a declarative DSL:
+
+```ts
+import { Agent, Tool, z } from "@node-llm/core";
+
+class LookupOrderTool extends Tool<{ orderId: string }> {
+  name = "lookup_order";
+  description = "Look up an order by ID";
+  schema = z.object({ orderId: z.string() });
+
+  async execute({ orderId }: { orderId: string }) {
+    return { status: "shipped", eta: "Tomorrow" };
+  }
+}
+
+class SupportAgent extends Agent {
+  static model = "gpt-4.1";
+  static instructions = "You are a helpful support agent.";
+  static tools = [LookupOrderTool];
+  static temperature = 0.2;
+}
+
+// Use anywhere in your app
+const agent = new SupportAgent();
+const response = await agent.ask("Where is order #123?");
+console.log(response.content);
+```
+
+### ToolHalt - Early Loop Termination
+
+Stop the agentic loop early when a definitive answer is found:
+
+```ts
+class FinalAnswerTool extends Tool<{ answer: string }> {
+  name = "final_answer";
+  description = "Return the final answer to the user";
+  schema = z.object({ answer: z.string() });
+
+  async execute({ answer }: { answer: string }) {
+    return this.halt(answer); // Stops the loop, returns this result
+  }
+}
+```
+
+---
+
 ## 💾 Ecosystem
 
 Looking for persistence? use **[@node-llm/orm](https://www.npmjs.com/package/@node-llm/orm)**.
@@ -150,11 +198,11 @@ Looking for persistence? use **[@node-llm/orm](https://www.npmjs.com/package/@no
 
 ## 📚 Full Documentation
 
-Visit **[node-llm.eshaiju.com](https://node-llm.eshaiju.com/)** for:
+Visit **[nodellm.dev](https://nodellm.dev/)** for:
 
-- [Deep Dive into Tool Calling](https://node-llm.eshaiju.com/core-features/tools)
-- [Multi-modal Vision & Audio Guide](https://node-llm.eshaiju.com/core-features/multimodal)
-- [Custom Provider Plugin System](https://node-llm.eshaiju.com/advanced/custom-providers)
+- [Deep Dive into Tool Calling](https://nodellm.dev/core-features/tools)
+- [Multi-modal Vision & Audio Guide](https://nodellm.dev/core-features/multimodal)
+- [Custom Provider Plugin System](https://nodellm.dev/advanced/custom-providers)
 
 ---
 

package/dist/agent/Agent.d.ts

@@ -0,0 +1,191 @@
+import { z } from "zod";
+import { Chat, AskOptions } from "../chat/Chat.js";
+import { ChatOptions } from "../chat/ChatOptions.js";
+import { ChatResponseString } from "../chat/ChatResponse.js";
+import { ToolResolvable } from "../chat/Tool.js";
+import { ThinkingConfig, ThinkingResult } from "../providers/Provider.js";
+import { Schema } from "../schema/Schema.js";
+import { NodeLLMCore } from "../llm.js";
+/**
+ * Configuration options that can be defined as static properties on Agent subclasses.
+ */
+export interface AgentConfig {
+    /** The model ID to use (e.g., "gpt-4o", "claude-sonnet-4-20250514") */
+    model?: string;
+    /** The provider to use (e.g., "openai", "anthropic") */
+    provider?: string;
+    /** System instructions for the agent */
+    instructions?: string;
+    /** Tools available to the agent */
+    tools?: ToolResolvable[];
+    /** Temperature for response generation (0.0 - 1.0) */
+    temperature?: number;
+    /** Extended thinking configuration */
+    thinking?: ThinkingConfig;
+    /** Output schema for structured responses */
+    schema?: z.ZodType | Schema | Record<string, unknown>;
+    /** Provider-specific parameters */
+    params?: Record<string, unknown>;
+    /** Custom headers for requests */
+    headers?: Record<string, string>;
+    /** Maximum tokens in response */
+    maxTokens?: number;
+    /** Maximum tool call iterations */
+    maxToolCalls?: number;
+    /** Assume model exists without validation */
+    assumeModelExists?: boolean;
+    /** Optional LLM instance to use instead of global NodeLLM */
+    llm?: NodeLLMCore;
+}
+/**
+ * Base class for creating reusable, class-configured agents.
+ *
+ * Define your agent configuration using static properties, then instantiate
+ * and use it anywhere in your application.
+ *
+ * @example
+ * ```typescript
+ * class SupportAgent extends Agent {
+ *   static model = "gpt-4o";
+ *   static instructions = "You are a helpful support agent";
+ *   static tools = [SearchDocs, LookupAccount];
+ *   static temperature = 0.2;
+ * }
+ *
+ * const agent = new SupportAgent();
+ * const response = await agent.ask("How can I reset my password?");
+ * ```
+ *
+ * @example Override configuration per instance:
+ * ```typescript
+ * const agent = new SupportAgent({ model: "gpt-4o-mini" });
+ * ```
+ */
+export declare abstract class Agent<S extends Record<string, unknown> = Record<string, unknown>> {
+    static model?: string;
+    static provider?: string;
+    static instructions?: string;
+    static tools?: ToolResolvable[];
+    static temperature?: number;
+    static thinking?: ThinkingConfig;
+    static schema?: z.ZodType | Schema | Record<string, unknown>;
+    static params?: Record<string, unknown>;
+    static headers?: Record<string, string>;
+    static maxTokens?: number;
+    static maxToolCalls?: number;
+    static assumeModelExists?: boolean;
+    /**
+     * Hook called when the agent starts a new session (ask/stream).
+     * @param context - Initial context including messages/options
+     */
+    static onStart(_context: {
+        messages: unknown[];
+    }): void | Promise<void>;
+    /**
+     * Hook called when the agent generates a reasoning trace (thinking).
+     * @param thinking - The content of the thinking trace
+     * @param result - The full response object containing the thinking
+     */
+    static onThinking(_thinking: ThinkingResult, _result: ChatResponseString): void | Promise<void>;
+    /**
+     * Hook called when a tool execution starts.
+     * @param toolCall - The tool call object (id, function name, arguments)
+     */
+    static onToolStart(_toolCall: unknown): void | Promise<void>;
+    /**
+     * Hook called when a tool execution ends.
+     * @param toolCall - The tool call object
+     * @param result - The result of the tool execution
+     */
+    static onToolEnd(_toolCall: unknown, _result: unknown): void | Promise<void>;
+    /**
+     * Hook called when a tool execution encounters an error.
+     * @param toolCall - The tool call object
+     * @param error - The error that occurred
+     */
+    static onToolError(_toolCall: unknown, _error: Error): void | Promise<void>;
+    /**
+     * Hook called when the agent completes a response turn.
+     * @param result - The final response object
+     */
+    static onComplete(_result: ChatResponseString): void | Promise<void>;
+    /**
+     * Run the agent immediately with a prompt.
+     * Creates a new instance of the agent, runs the prompt, and disposes it.
+     *
+     * @example
+     * ```typescript
+     * const result = await TravelAgent.ask("Find flights to Paris");
+     * ```
+     */
+    static ask(message: string, options?: AskOptions): Promise<ChatResponseString>;
+    /**
+     * Stream the agent response immediately.
+     * Creates a new instance of the agent and streams the response.
+     *
+     * @example
+     * ```typescript
+     * for await (const chunk of TravelAgent.stream("Write a poem")) {
+     *   process.stdout.write(chunk.content);
+     * }
+     * ```
+     */
+    static stream(message: string, options?: AskOptions): import("../index.js").Stream<import("../providers/Provider.js").ChatChunk>;
+    /** The underlying Chat instance */
+    protected readonly chat: Chat<S>;
+    /**
+     * Create a new agent instance.
+     * @param overrides - Optional configuration to override static properties
+     */
+    constructor(overrides?: Partial<AgentConfig & ChatOptions>);
+    /**
+     * Send a message to the agent and get a response.
+     * @param message - The user message
+     * @param options - Optional request options
+     */
+    ask(message: string, options?: AskOptions): Promise<ChatResponseString>;
+    /**
+     * Alias for ask()
+     */
+    say(message: string, options?: AskOptions): Promise<ChatResponseString>;
+    /**
+     * Stream a response from the agent.
+     * @param message - The user message
+     * @param options - Optional request options
+     */
+    stream(message: string, options?: AskOptions): import("../index.js").Stream<import("../providers/Provider.js").ChatChunk>;
+    /**
+     * Get the conversation history.
+     */
+    get history(): readonly import("../index.js").Message[];
+    /**
+     * Get the model ID being used.
+     */
+    get modelId(): string;
+    /**
+     * Get aggregate token usage across the conversation.
+     */
+    get totalUsage(): import("../providers/Provider.js").Usage;
+    /**
+     * Access the underlying Chat instance for advanced operations.
+     */
+    get underlyingChat(): Chat<S>;
+}
+/**
+ * Helper function to define an agent inline without creating a class.
+ *
+ * @example
+ * ```typescript
+ * const SupportAgent = defineAgent({
+ *   model: "gpt-4o",
+ *   instructions: "You are a helpful support agent",
+ *   tools: [SearchDocs, LookupAccount],
+ *   temperature: 0.2
+ * });
+ *
+ * const agent = new SupportAgent();
+ * const response = await agent.ask("Help me!");
+ * ```
+ */
+export declare function defineAgent<S extends Record<string, unknown> = Record<string, unknown>>(config: AgentConfig): new (overrides?: Partial<AgentConfig & ChatOptions>) => Agent<S>;
+//# sourceMappingURL=Agent.d.ts.map

package/dist/agent/Agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../src/agent/Agent.ts"],"names":[],"mappings":"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"}

package/dist/agent/Agent.js

@@ -0,0 +1,272 @@
+import { NodeLLM } from "../llm.js";
+/**
+ * Base class for creating reusable, class-configured agents.
+ *
+ * Define your agent configuration using static properties, then instantiate
+ * and use it anywhere in your application.
+ *
+ * @example
+ * ```typescript
+ * class SupportAgent extends Agent {
+ *   static model = "gpt-4o";
+ *   static instructions = "You are a helpful support agent";
+ *   static tools = [SearchDocs, LookupAccount];
+ *   static temperature = 0.2;
+ * }
+ *
+ * const agent = new SupportAgent();
+ * const response = await agent.ask("How can I reset my password?");
+ * ```
+ *
+ * @example Override configuration per instance:
+ * ```typescript
+ * const agent = new SupportAgent({ model: "gpt-4o-mini" });
+ * ```
+ */
+export class Agent {
+    // Static configuration properties - override these in subclasses
+    static model;
+    static provider;
+    static instructions;
+    static tools;
+    static temperature;
+    static thinking;
+    static schema;
+    static params;
+    static headers;
+    static maxTokens;
+    static maxToolCalls;
+    static assumeModelExists;
+    /**
+     * Hook called when the agent starts a new session (ask/stream).
+     * @param context - Initial context including messages/options
+     */
+    static onStart(_context) {
+        // Override in subclass
+    }
+    /**
+     * Hook called when the agent generates a reasoning trace (thinking).
+     * @param thinking - The content of the thinking trace
+     * @param result - The full response object containing the thinking
+     */
+    static onThinking(_thinking, _result) {
+        // Override in subclass
+    }
+    /**
+     * Hook called when a tool execution starts.
+     * @param toolCall - The tool call object (id, function name, arguments)
+     */
+    static onToolStart(_toolCall) {
+        // Override in subclass
+    }
+    /**
+     * Hook called when a tool execution ends.
+     * @param toolCall - The tool call object
+     * @param result - The result of the tool execution
+     */
+    static onToolEnd(_toolCall, _result) {
+        // Override in subclass
+    }
+    /**
+     * Hook called when a tool execution encounters an error.
+     * @param toolCall - The tool call object
+     * @param error - The error that occurred
+     */
+    static onToolError(_toolCall, _error) {
+        // Override in subclass
+    }
+    /**
+     * Hook called when the agent completes a response turn.
+     * @param result - The final response object
+     */
+    static onComplete(_result) {
+        // Override in subclass
+    }
+    // --- Static Execution API ---
+    /**
+     * Run the agent immediately with a prompt.
+     * Creates a new instance of the agent, runs the prompt, and disposes it.
+     *
+     * @example
+     * ```typescript
+     * const result = await TravelAgent.ask("Find flights to Paris");
+     * ```
+     */
+    static async ask(message, options) {
+        const Ctor = this;
+        const agent = new Ctor({});
+        return agent.ask(message, options);
+    }
+    /**
+     * Stream the agent response immediately.
+     * Creates a new instance of the agent and streams the response.
+     *
+     * @example
+     * ```typescript
+     * for await (const chunk of TravelAgent.stream("Write a poem")) {
+     *   process.stdout.write(chunk.content);
+     * }
+     * ```
+     */
+    static stream(message, options) {
+        const Ctor = this;
+        const agent = new Ctor({});
+        return agent.stream(message, options);
+    }
+    /** The underlying Chat instance */
+    chat;
+    /**
+     * Create a new agent instance.
+     * @param overrides - Optional configuration to override static properties
+     */
+    constructor(overrides = {}) {
+        const ctor = this.constructor;
+        // Build chat options from static properties + overrides
+        const chatOptions = {
+            provider: overrides.provider ?? ctor.provider,
+            assumeModelExists: overrides.assumeModelExists ?? ctor.assumeModelExists,
+            temperature: overrides.temperature ?? ctor.temperature,
+            maxTokens: overrides.maxTokens ?? ctor.maxTokens,
+            maxToolCalls: overrides.maxToolCalls ?? ctor.maxToolCalls,
+            headers: { ...ctor.headers, ...overrides.headers },
+            params: { ...ctor.params, ...overrides.params },
+            thinking: overrides.thinking ?? ctor.thinking,
+            messages: overrides.messages // Allow history injection
+        };
+        // Determine model
+        const model = overrides.model ?? ctor.model;
+        if (!model) {
+            throw new Error(`[Agent] No model specified. Set static model property or pass model in constructor.`);
+        }
+        // Use provided LLM instance or fall back to global NodeLLM
+        const llm = overrides.llm ?? NodeLLM;
+        this.chat = llm.chat(model, chatOptions);
+        // Apply instructions
+        const instructions = overrides.instructions ?? ctor.instructions;
+        if (instructions) {
+            this.chat.withInstructions(instructions);
+        }
+        // Apply tools
+        const tools = overrides.tools ?? ctor.tools;
+        if (tools && tools.length > 0) {
+            this.chat.withTools(tools);
+        }
+        // Apply schema
+        const schema = overrides.schema ?? ctor.schema;
+        if (schema) {
+            this.chat.withSchema(schema);
+        }
+        // Wire up global/static telemetry hooks
+        // Trigger onStart immediately
+        if (ctor.onStart) {
+            this.chat.beforeRequest(async (messages) => {
+                if (ctor.onStart) {
+                    await ctor.onStart({ messages });
+                }
+            });
+        }
+        if (ctor.onToolStart) {
+            this.chat.onToolCallStart(async (toolCall) => {
+                await ctor.onToolStart(toolCall);
+            });
+        }
+        if (ctor.onToolEnd) {
+            this.chat.onToolCallEnd(async (toolCall, result) => {
+                await ctor.onToolEnd(toolCall, result);
+            });
+        }
+        if (ctor.onToolError) {
+            this.chat.onToolCallError(async (toolCall, error) => {
+                await ctor.onToolError(toolCall, error);
+            });
+        }
+        if (ctor.onComplete || ctor.onThinking) {
+            this.chat.onEndMessage(async (msg) => {
+                if (msg.thinking && ctor.onThinking) {
+                    await ctor.onThinking(msg.thinking, msg);
+                }
+                if (ctor.onComplete) {
+                    await ctor.onComplete(msg);
+                }
+            });
+        }
+    }
+    /**
+     * Send a message to the agent and get a response.
+     * @param message - The user message
+     * @param options - Optional request options
+     */
+    async ask(message, options) {
+        return this.chat.ask(message, options);
+    }
+    /**
+     * Alias for ask()
+     */
+    async say(message, options) {
+        return this.ask(message, options);
+    }
+    /**
+     * Stream a response from the agent.
+     * @param message - The user message
+     * @param options - Optional request options
+     */
+    stream(message, options) {
+        return this.chat.stream(message, options);
+    }
+    /**
+     * Get the conversation history.
+     */
+    get history() {
+        return this.chat.history;
+    }
+    /**
+     * Get the model ID being used.
+     */
+    get modelId() {
+        return this.chat.modelId;
+    }
+    /**
+     * Get aggregate token usage across the conversation.
+     */
+    get totalUsage() {
+        return this.chat.totalUsage;
+    }
+    /**
+     * Access the underlying Chat instance for advanced operations.
+     */
+    get underlyingChat() {
+        return this.chat;
+    }
+}
+/**
+ * Helper function to define an agent inline without creating a class.
+ *
+ * @example
+ * ```typescript
+ * const SupportAgent = defineAgent({
+ *   model: "gpt-4o",
+ *   instructions: "You are a helpful support agent",
+ *   tools: [SearchDocs, LookupAccount],
+ *   temperature: 0.2
+ * });
+ *
+ * const agent = new SupportAgent();
+ * const response = await agent.ask("Help me!");
+ * ```
+ */
+export function defineAgent(config) {
+    return class extends Agent {
+        static model = config.model;
+        static provider = config.provider;
+        static instructions = config.instructions;
+        static tools = config.tools;
+        static temperature = config.temperature;
+        static thinking = config.thinking;
+        static schema = config.schema;
+        static params = config.params;
+        static headers = config.headers;
+        static maxTokens = config.maxTokens;
+        static maxToolCalls = config.maxToolCalls;
+        static assumeModelExists = config.assumeModelExists;
+    };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"Chat.d.ts","sourceRoot":"","sources":["../../src/chat/Chat.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Chat.d.ts","sourceRoot":"","sources":["../../src/chat/Chat.ts"],"names":[],"mappings":"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"}

package/dist/chat/Chat.js

@@ -423,7 +423,8 @@ export class Chat {
             }
             const maxToolCalls = options?.maxToolCalls ?? this.options.maxToolCalls ?? 5;
             let stepCount = 0;
-            while (response.tool_calls && response.tool_calls.length > 0) {
+            let haltTriggered = false;
+            while (response.tool_calls && response.tool_calls.length > 0 && !haltTriggered) {
                 // Dry-run mode: stop after proposing tools
                 if (!ToolHandler.shouldExecuteTools(response.tool_calls, this.options.toolExecution)) {
                     break;
@@ -448,6 +449,16 @@ export class Chat {
                         // 3. onToolCallEnd Hook
                         await runMiddleware(this.middlewares, "onToolCallEnd", context, toolCall, toolResult.content);
                         this.messages.push(this.provider.formatToolResultMessage(toolResult.tool_call_id, toolResult.content));
+                        // Check if tool signaled a halt - stop the agentic loop
+                        if (toolResult.halted) {
+                            haltTriggered = true;
+                            // Create final response from halt content
+                            assistantMessage = new ChatResponseString(toolResult.content, totalUsage, this.model, this.provider.id, undefined, undefined, undefined, "tool_halt");
+                            if (this.options.onEndMessage) {
+                                this.options.onEndMessage(assistantMessage);
+                            }
+                            break; // Exit the for loop
+                        }
                     }
                     catch (error) {
                         let currentError = error;
@@ -489,6 +500,10 @@ export class Chat {
                         logger.error(`Tool execution failed for '${toolCall.function.name}':`, currentError);
                     }
                 }
+                // If halt was triggered, exit the while loop immediately
+                if (haltTriggered) {
+                    break;
+                }
                 response = await this.executor.executeChat({
                     model: this.model,
                     messages: [...this.systemMessages, ...this.messages], // Use updated history

package/dist/chat/Tool.d.ts

@@ -14,7 +14,32 @@ export interface ToolDefinition {
         description?: string;
         parameters: Record<string, unknown>;
     };
-    handler?: (args: unknown) => Promise<string>;
+    handler?: (args: unknown) => Promise<string | ToolHalt>;
+}
+/**
+ * Stops the agentic tool execution loop and returns the content as the final response.
+ * Return this from a tool's execute() method to immediately end the conversation turn.
+ *
+ * @example
+ * ```typescript
+ * class PaymentTool extends Tool {
+ *   async execute({ amount }) {
+ *     if (amount > 10000) {
+ *       return this.halt("Payment requires manager approval. Please contact support.");
+ *     }
+ *     return processPayment(amount);
+ *   }
+ * }
+ * ```
+ */
+export declare class ToolHalt {
+    readonly content: string;
+    constructor(content: string);
+    toString(): string;
+    toJSON(): {
+        halt: true;
+        content: string;
+    };
 }
 /**
  * Anything that can be resolved into a ToolDefinition.
@@ -44,11 +69,27 @@ export declare abstract class Tool<T = Record<string, unknown>> {
      * 'args' will be parsed and validated based on 'schema'.
      */
     abstract execute(args: T): Promise<unknown>;
+    /**
+     * Stop the agentic loop and return this message as the final tool result.
+     * Use this when you want to end the conversation turn immediately.
+     *
+     * @example
+     * ```typescript
+     * async execute({ amount }) {
+     *   if (amount > 10000) {
+     *     return this.halt("Payment requires manager approval.");
+     *   }
+     *   return processPayment(amount);
+     * }
+     * ```
+     */
+    protected halt(message: string): ToolHalt;
     /**
      * Internal handler to bridge with LLM providers.
      * Converts any result to a string (usually JSON).
+     * Preserves ToolHalt instances for the execution loop to detect.
      */
-    handler(args: T): Promise<string>;
+    handler(args: T): Promise<string | ToolHalt>;
     /**
      * Converts the tool definition and logic into a standard ToolDefinition interface.
      * This is called automatically by NodeLLM when registering tools.

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

@@ -1 +1 @@
-{"version":3,"file":"Tool.d.ts","sourceRoot":"","sources":["../../src/chat/Tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG;IAAE,QAAQ,IAAI,CAAA;CAAE,GAAG,cAAc,CAAC;AAEtE;;GAEG;AACH,8BAAsB,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACpD;;OAEG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,SAAgB,WAAW,EAAE,MAAM,CAAC;IAEpC;;;OAGG;IACH,SAAgB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE7E;;;OAGG;aACa,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAElD;;;OAGG;IACU,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAM9C;;;OAGG;IACI,SAAS,IAAI,cAAc;CAuBnC"}
+{"version":3,"file":"Tool.d.ts","sourceRoot":"","sources":["../../src/chat/Tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,QAAQ;aACS,OAAO,EAAE,MAAM;gBAAf,OAAO,EAAE,MAAM;IAE3C,QAAQ,IAAI,MAAM;IAIlB,MAAM,IAAI;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;CAG1C;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG;IAAE,QAAQ,IAAI,CAAA;CAAE,GAAG,cAAc,CAAC;AAEtE;;GAEG;AACH,8BAAsB,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACpD;;OAEG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,SAAgB,WAAW,EAAE,MAAM,CAAC;IAEpC;;;OAGG;IACH,SAAgB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE7E;;;OAGG;aACa,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAElD;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ;IAIzC;;;;OAIG;IACU,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC;IAYzD;;;OAGG;IACI,SAAS,IAAI,cAAc;CAuBnC"}

package/dist/chat/Tool.js

@@ -1,14 +1,64 @@
 import { toJsonSchema } from "../schema/to-json-schema.js";
+/**
+ * Stops the agentic tool execution loop and returns the content as the final response.
+ * Return this from a tool's execute() method to immediately end the conversation turn.
+ *
+ * @example
+ * ```typescript
+ * class PaymentTool extends Tool {
+ *   async execute({ amount }) {
+ *     if (amount > 10000) {
+ *       return this.halt("Payment requires manager approval. Please contact support.");
+ *     }
+ *     return processPayment(amount);
+ *   }
+ * }
+ * ```
+ */
+export class ToolHalt {
+    content;
+    constructor(content) {
+        this.content = content;
+    }
+    toString() {
+        return this.content;
+    }
+    toJSON() {
+        return { halt: true, content: this.content };
+    }
+}
 /**
  * Subclass this to create tools with auto-generated schemas and type safety.
  */
 export class Tool {
+    /**
+     * Stop the agentic loop and return this message as the final tool result.
+     * Use this when you want to end the conversation turn immediately.
+     *
+     * @example
+     * ```typescript
+     * async execute({ amount }) {
+     *   if (amount > 10000) {
+     *     return this.halt("Payment requires manager approval.");
+     *   }
+     *   return processPayment(amount);
+     * }
+     * ```
+     */
+    halt(message) {
+        return new ToolHalt(message);
+    }
     /**
      * Internal handler to bridge with LLM providers.
      * Converts any result to a string (usually JSON).
+     * Preserves ToolHalt instances for the execution loop to detect.
      */
     async handler(args) {
         const result = await this.execute(args);
+        // Preserve ToolHalt for the execution loop to handle
+        if (result instanceof ToolHalt) {
+            return result;
+        }
         if (result === undefined || result === null)
             return "";
         return typeof result === "string" ? result : JSON.stringify(result);

package/dist/chat/ToolHandler.d.ts

@@ -1,12 +1,17 @@
 import { ToolExecutionMode } from "../constants.js";
 import { ToolCall, ToolDefinition } from "./Tool.js";
+/**
+ * Result of a tool execution, including halt status
+ */
+export interface ToolExecutionResult {
+    role: "tool";
+    tool_call_id: string;
+    content: string;
+    halted: boolean;
+}
 export declare class ToolHandler {
     static shouldExecuteTools(toolCalls: ToolCall[] | undefined, mode?: ToolExecutionMode): boolean;
     static requestToolConfirmation(toolCall: ToolCall, onConfirm?: (call: ToolCall) => Promise<boolean> | boolean): Promise<boolean>;
-    static execute(toolCall: ToolCall, tools: ToolDefinition[] | undefined, onStart?: (call: ToolCall) => void, onEnd?: (call: ToolCall, result: unknown) => void): Promise<{
-        role: "tool";
-        tool_call_id: string;
-        content: string;
-    }>;
+    static execute(toolCall: ToolCall, tools: ToolDefinition[] | undefined, onStart?: (call: ToolCall) => void, onEnd?: (call: ToolCall, result: unknown) => void): Promise<ToolExecutionResult>;
 }
 //# sourceMappingURL=ToolHandler.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ToolHandler.d.ts","sourceRoot":"","sources":["../../src/chat/ToolHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAErD,qBAAa,WAAW;IACtB,MAAM,CAAC,kBAAkB,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,SAAS,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,OAAO;WAMlF,uBAAuB,CAClC,QAAQ,EAAE,QAAQ,EAClB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,GACzD,OAAO,CAAC,OAAO,CAAC;WAMN,OAAO,CAClB,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,cAAc,EAAE,GAAG,SAAS,EACnC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,EAClC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,GAChD,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAwBpE"}
+{"version":3,"file":"ToolHandler.d.ts","sourceRoot":"","sources":["../../src/chat/ToolHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAY,MAAM,WAAW,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,WAAW;IACtB,MAAM,CAAC,kBAAkB,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,SAAS,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,OAAO;WAMlF,uBAAuB,CAClC,QAAQ,EAAE,QAAQ,EAClB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,GACzD,OAAO,CAAC,OAAO,CAAC;WAMN,OAAO,CAClB,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,cAAc,EAAE,GAAG,SAAS,EACnC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,EAClC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,GAChD,OAAO,CAAC,mBAAmB,CAAC;CAgChC"}

package/dist/chat/ToolHandler.js

@@ -1,5 +1,6 @@
 import { ToolExecutionMode } from "../constants.js";
 import { ToolError } from "../errors/index.js";
+import { ToolHalt } from "./Tool.js";
 export class ToolHandler {
     static shouldExecuteTools(toolCalls, mode) {
         if (!toolCalls || toolCalls.length === 0)
@@ -21,13 +22,20 @@ export class ToolHandler {
         if (tool?.handler) {
             const args = JSON.parse(toolCall.function.arguments);
             const result = await tool.handler(args);
-            const safeResult = typeof result === "string" ? result : JSON.stringify(result);
+            // Check if this is a halt signal
+            const isHalt = typeof result === "object" && result !== null && result instanceof ToolHalt;
+            const content = isHalt
+                ? result.content
+                : typeof result === "string"
+                    ? result
+                    : JSON.stringify(result);
             if (onEnd)
                 onEnd(toolCall, result);
             return {
                 role: "tool",
                 tool_call_id: toolCall.id,
-                content: safeResult
+                content,
+                halted: isHalt
             };
         }
         else {

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export * from "./chat/Chat.js";
 export * from "./chat/ChatStream.js";
 export * from "./streaming/Stream.js";
 export * from "./errors/index.js";
+export { Agent, defineAgent } from "./agent/Agent.js";
+export type { AgentConfig } from "./agent/Agent.js";
 export type { Middleware, MiddlewareContext } from "./types/Middleware.js";
 export * from "./middlewares/index.js";
 export { z } from "zod";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC3E,cAAc,wBAAwB,CAAC;AAEvC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,OAAO,EACP,aAAa,EACb,SAAS,EACT,WAAW,EACX,aAAa,EACb,UAAU,EACV,SAAS,EACT,aAAa,EACb,eAAe,EAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,SAAS,EACT,cAAc,EACd,cAAc,EACd,KAAK,EACL,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC3E,cAAc,wBAAwB,CAAC;AAEvC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,OAAO,EACP,aAAa,EACb,SAAS,EACT,WAAW,EACX,aAAa,EACb,UAAU,EACV,SAAS,EACT,aAAa,EACb,eAAe,EAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,SAAS,EACT,cAAc,EACd,cAAc,EACd,KAAK,EACL,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -7,6 +7,7 @@ export * from "./chat/Chat.js";
 export * from "./chat/ChatStream.js";
 export * from "./streaming/Stream.js";
 export * from "./errors/index.js";
+export { Agent, defineAgent } from "./agent/Agent.js";
 export * from "./middlewares/index.js";
 export { z } from "zod";
 export { NodeLLM, LegacyNodeLLM, createLLM, NodeLLMCore, Transcription, Moderation, Embedding, ModelRegistry, PricingRegistry } from "./llm.js";

package/dist/llm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../src/llm.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../src/llm.ts"],"names":[],"mappings":"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"}

package/dist/types/Middleware.d.ts

@@ -2,6 +2,14 @@ import { Message } from "../chat/Message.js";
 import { ChatOptions } from "../chat/ChatOptions.js";
 import { ChatResponseString } from "../chat/ChatResponse.js";
 import { ToolCall } from "../chat/Tool.js";
+import { GeneratedImage } from "../image/GeneratedImage.js";
+import { Transcription } from "../transcription/Transcription.js";
+import { Moderation } from "../moderation/Moderation.js";
+import { Embedding } from "../embedding/Embedding.js";
+/**
+ * All possible response types that can be returned by NodeLLM.
+ */
+export type NodeLLMResponse = ChatResponseString | GeneratedImage | Transcription | Moderation | Embedding;
 /**
  * Context passed to all middleware hooks.
  * This object is shared across the lifecycle of a single request.
@@ -36,19 +44,19 @@ export interface MiddlewareContext {
     /**
      * Options passed to the embedding request (Embedding only).
      */
-    embeddingOptions?: Record<string, any>;
+    embeddingOptions?: Record<string, unknown>;
     /**
      * Options passed to the transcription request (Transcription only).
      */
-    transcriptionOptions?: Record<string, any>;
+    transcriptionOptions?: Record<string, unknown>;
     /**
      * Options passed to the moderation request (Moderation only).
      */
-    moderationOptions?: Record<string, any>;
+    moderationOptions?: Record<string, unknown>;
     /**
      * Options passed to the image generation request (Paint only).
      */
-    imageOptions?: Record<string, any>;
+    imageOptions?: Record<string, unknown>;
     /**
      * Shared state storage for passing data between middleware hooks.
      * Example: Storing start time in `onRequest` and reading it in `onResponse`.
@@ -75,7 +83,7 @@ export interface Middleware {
     /**
      * Called after a successful response from the provider.
      */
-    onResponse?(ctx: MiddlewareContext, result: ChatResponseString): Promise<void>;
+    onResponse?(ctx: MiddlewareContext, result: NodeLLMResponse): Promise<void>;
     /**
      * Called if an error occurs during execution.
      */

package/dist/types/Middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Middleware.d.ts","sourceRoot":"","sources":["../../src/types/Middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3C;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IAErB;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAE1B;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEvC;;OAEG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE3C;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAExC;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEnC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,IAAI,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,SAAS,CAAC,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;OAEG;IACH,UAAU,CAAC,CAAC,GAAG,EAAE,iBAAiB,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/E;;OAEG;IACH,OAAO,CAAC,CAAC,GAAG,EAAE,iBAAiB,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D;;;OAGG;IACH,eAAe,CAAC,CAAC,GAAG,EAAE,iBAAiB,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExE;;OAEG;IACH,aAAa,CAAC,CAAC,GAAG,EAAE,iBAAiB,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvF;;;OAGG;IACH,eAAe,CAAC,CACd,GAAG,EAAE,iBAAiB,EACtB,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAChC"}
+{"version":3,"file":"Middleware.d.ts","sourceRoot":"","sources":["../../src/types/Middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,kBAAkB,GAClB,cAAc,GACd,aAAa,GACb,UAAU,GACV,SAAS,CAAC;AAEd;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IAErB;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAE1B;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE3C;;OAEG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE/C;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE5C;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEvC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,IAAI,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,SAAS,CAAC,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;OAEG;IACH,UAAU,CAAC,CAAC,GAAG,EAAE,iBAAiB,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5E;;OAEG;IACH,OAAO,CAAC,CAAC,GAAG,EAAE,iBAAiB,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D;;;OAGG;IACH,eAAe,CAAC,CAAC,GAAG,EAAE,iBAAiB,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExE;;OAEG;IACH,aAAa,CAAC,CAAC,GAAG,EAAE,iBAAiB,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvF;;;OAGG;IACH,eAAe,CAAC,CACd,GAAG,EAAE,iBAAiB,EACtB,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAChC"}

package/dist/utils/middleware-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware-runner.d.ts","sourceRoot":"","sources":["../../src/utils/middleware-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEvE;;;GAGG;AACH,wBAAsB,aAAa,CAAC,CAAC,GAAG,IAAI,EAC1C,WAAW,EAAE,UAAU,EAAE,EACzB,QAAQ,EAAE,MAAM,UAAU,EAC1B,OAAO,EAAE,iBAAiB,EAC1B,GAAG,IAAI,EAAE,GAAG,EAAE,GACb,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAiBxB"}
+{"version":3,"file":"middleware-runner.d.ts","sourceRoot":"","sources":["../../src/utils/middleware-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEvE;;;GAGG;AACH,wBAAsB,aAAa,CAAC,CAAC,GAAG,IAAI,EAC1C,WAAW,EAAE,UAAU,EAAE,EACzB,QAAQ,EAAE,MAAM,UAAU,EAC1B,OAAO,EAAE,iBAAiB,EAC1B,GAAG,IAAI,EAAE,GAAG,EAAE,GACb,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAuBxB"}

package/dist/utils/middleware-runner.js

@@ -5,8 +5,11 @@
 export async function runMiddleware(middlewares, hookName, context, ...args) {
     if (!middlewares || middlewares.length === 0)
         return undefined;
+    // Response and error hooks run in reverse order (stack model)
+    const isReverse = ["onResponse", "onError", "onToolCallEnd", "onToolCallError"].includes(hookName);
+    const chain = isReverse ? [...middlewares].reverse() : middlewares;
     let finalResult;
-    for (const middleware of middlewares) {
+    for (const middleware of chain) {
         if (typeof middleware[hookName] === "function") {
             // @ts-ignore
             const result = await middleware[hookName](context, ...args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@node-llm/core",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,6 +11,9 @@
     }
   },
   "description": "A provider-agnostic LLM core for Node.js, inspired by ruby-llm.",
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": [
     "llm",
     "large-language-models",
@@ -40,7 +43,7 @@
     "url": "https://github.com/node-llm/node-llm",
     "directory": "packages/core"
   },
-  "homepage": "https://node-llm.eshaiju.com",
+  "homepage": "https://nodellm.dev",
   "bugs": {
     "url": "https://github.com/node-llm/node-llm/issues"
   },
@@ -67,6 +70,7 @@
     "dev": "tsc -w",
     "lint": "tsc --noEmit",
     "test": "vitest run",
+    "test:docs": "vitest run test/docs",
     "test:watch": "vitest"
   }
 }