@node-llm/core 1.9.0 → 1.11.0

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

@@ -6,6 +6,11 @@ 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 { 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";
 export { NodeLLM, LegacyNodeLLM, createLLM, NodeLLMCore, Transcription, Moderation, Embedding, ModelRegistry, PricingRegistry } from "./llm.js";
 export { config } from "./config.js";

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;AAEtC,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

@@ -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 { 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";
 export { config } from "./config.js";

package/dist/llm.d.ts

@@ -8,6 +8,7 @@ import { Transcription } from "./transcription/Transcription.js";
 import { Moderation } from "./moderation/Moderation.js";
 import { Embedding } from "./embedding/Embedding.js";
 import { NodeLLMConfig } from "./config.js";
+import { Middleware } from "./types/Middleware.js";
 export interface RetryOptions {
     attempts?: number;
     delayMs?: number;
@@ -15,6 +16,7 @@ export interface RetryOptions {
 type LLMConfig = {
     provider?: Provider | string;
     retry?: RetryOptions;
+    middlewares?: Middleware[];
     defaultChatModel?: string;
     defaultTranscriptionModel?: string;
     defaultModerationModel?: string;
@@ -24,10 +26,11 @@ export declare class NodeLLMCore {
     readonly config: NodeLLMConfig;
     readonly provider?: Provider | undefined;
     readonly retry: Required<RetryOptions>;
+    readonly middlewares: Middleware[];
     private readonly defaults;
     readonly models: typeof ModelRegistry;
     readonly pricing: typeof PricingRegistry;
-    constructor(config: NodeLLMConfig, provider?: Provider | undefined, retry?: Required<RetryOptions>, defaults?: {
+    constructor(config: NodeLLMConfig, provider?: Provider | undefined, retry?: Required<RetryOptions>, middlewares?: Middleware[], defaults?: {
         chat?: string;
         transcription?: string;
         moderation?: string;
@@ -57,6 +60,7 @@ export declare class NodeLLMCore {
         quality?: string;
         assumeModelExists?: boolean;
         requestTimeout?: number;
+        middlewares?: Middleware[];
     }): Promise<GeneratedImage>;
     transcribe(file: string, options?: {
         model?: string;
@@ -66,17 +70,20 @@ export declare class NodeLLMCore {
         speakerReferences?: string[];
         assumeModelExists?: boolean;
         requestTimeout?: number;
+        middlewares?: Middleware[];
     }): Promise<Transcription>;
     moderate(input: string | string[], options?: {
         model?: string;
         assumeModelExists?: boolean;
         requestTimeout?: number;
+        middlewares?: Middleware[];
     }): Promise<Moderation>;
     embed(input: string | string[], options?: {
         model?: string;
         dimensions?: number;
         assumeModelExists?: boolean;
         requestTimeout?: number;
+        middlewares?: Middleware[];
     }): Promise<Embedding>;
 }
 export { Transcription, Moderation, Embedding, ModelRegistry, PricingRegistry };

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":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAW9D,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAUrD,OAAO,EAAU,aAAa,EAAiB,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,UAAU,EAAqB,MAAM,uBAAuB,CAAC;AAItE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,SAAS,GAAG;IACf,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC7B,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,UAAU,CAAC,CAAC;AAa7C,qBAAa,WAAW;aAKJ,MAAM,EAAE,aAAa;aACrB,QAAQ,CAAC,EAAE,QAAQ;aACnB,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC;aAC7B,WAAW,EAAE,UAAU,EAAE;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAR3B,SAAgB,MAAM,uBAAiB;IACvC,SAAgB,OAAO,yBAAmB;gBAGxB,MAAM,EAAE,aAAa,EACrB,QAAQ,CAAC,EAAE,QAAQ,YAAA,EACnB,KAAK,GAAE,QAAQ,CAAC,YAAY,CAA+B,EAC3D,WAAW,GAAE,UAAU,EAAO,EAC7B,QAAQ,GAAE;QACzB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;KACf;IAOR,IAAI,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAEzC;IACD,IAAI,yBAAyB,IAAI,MAAM,GAAG,SAAS,CAElD;IACD,IAAI,sBAAsB,IAAI,MAAM,GAAG,SAAS,CAE/C;IACD,IAAI,qBAAqB,IAAI,MAAM,GAAG,SAAS,CAE9C;IAED;;;OAGG;IACH,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,WAAW;IAiBtF;;;OAGG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,QAAQ,GAAG,IAAI;IAI7D,cAAc;IAId,OAAO,CAAC,qBAAqB;IAY7B,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,IAAI;IAiB/C,UAAU,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAUlC,KAAK,CACT,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;KAC5B,GACA,OAAO,CAAC,cAAc,CAAC;IAoDpB,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;QAC7B,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;KAC5B,GACA,OAAO,CAAC,aAAa,CAAC;IAqDnB,QAAQ,CACZ,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EACxB,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;KAC5B,GACA,OAAO,CAAC,UAAU,CAAC;IAqDhB,KAAK,CACT,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EACxB,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;KAC5B,GACA,OAAO,CAAC,SAAS,CAAC;CAsDtB;AAED,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC;AAEhF;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,SAAc,GAAG,WAAW,CAkD9D;AAuCD;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO,EAAE,WA6BpB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,aAAa;wBACJ,SAAS,GAAG,CAAC,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;CAOlE,CAAC"}

package/dist/llm.js

@@ -10,6 +10,8 @@ import { ProviderNotConfiguredError, UnsupportedFeatureError, ModelCapabilityErr
 import { resolveModelAlias } from "./model_aliases.js";
 import { logger } from "./utils/logger.js";
 import { config, Configuration } from "./config.js";
+import { runMiddleware } from "./utils/middleware-runner.js";
+import { randomUUID } from "node:crypto";
 // Provider registration map
 const PROVIDER_REGISTRARS = {
     openai: ensureOpenAIRegistered,
@@ -24,13 +26,15 @@ export class NodeLLMCore {
     config;
     provider;
     retry;
+    middlewares;
     defaults;
     models = ModelRegistry;
     pricing = PricingRegistry;
-    constructor(config, provider, retry = { attempts: 1, delayMs: 0 }, defaults = {}) {
+    constructor(config, provider, retry = { attempts: 1, delayMs: 0 }, middlewares = [], defaults = {}) {
         this.config = config;
         this.provider = provider;
         this.retry = retry;
+        this.middlewares = middlewares;
         this.defaults = defaults;
         Object.freeze(this.config);
         Object.freeze(this.retry);
@@ -59,7 +63,8 @@ export class NodeLLMCore {
             ...baseConfig,
             ...scopedConfig,
             provider: providerName,
-            // Preserve defaults unless overridden (conceptually, though createLLM takes specific keys)
+            // Preserve middlewares and defaults unless overridden
+            middlewares: this.middlewares,
             defaultChatModel: this.defaults.chat,
             defaultTranscriptionModel: this.defaults.transcription,
             defaultModerationModel: this.defaults.moderation,
@@ -85,13 +90,18 @@ export class NodeLLMCore {
         }
         return this.provider;
     }
-    chat(model, options) {
+    chat(model, options = {}) {
         if (!this.provider) {
             throw new ProviderNotConfiguredError();
         }
         const rawModel = model || this.defaults.chat || this.provider.defaultModel("chat");
         const resolvedModel = resolveModelAlias(rawModel, this.provider.id);
-        return new Chat(this.provider, resolvedModel, options, this.retry);
+        // Merge global middlewares with local ones
+        const combinedOptions = {
+            ...options,
+            middlewares: [...this.middlewares, ...(options.middlewares || [])]
+        };
+        return new Chat(this.provider, resolvedModel, combinedOptions, this.retry);
     }
     async listModels() {
         const provider = this.ensureProviderSupport("listModels");
@@ -102,82 +112,169 @@ export class NodeLLMCore {
     }
     async paint(prompt, options) {
         const provider = this.ensureProviderSupport("paint");
-        const rawModel = options?.model;
-        const model = resolveModelAlias(rawModel || "", provider.id);
-        if (options?.assumeModelExists) {
-            logger.warn(`Skipping validation for model ${model}`);
+        const rawModel = options?.model || provider.defaultModel("image");
+        const model = resolveModelAlias(rawModel, provider.id);
+        const requestId = randomUUID();
+        const state = {};
+        const context = {
+            requestId,
+            provider: provider.id,
+            model,
+            input: prompt,
+            imageOptions: options,
+            state
+        };
+        const middlewares = [...this.middlewares, ...(options?.middlewares || [])];
+        try {
+            await runMiddleware(middlewares, "onRequest", context);
+            const currentPrompt = context.input || prompt;
+            if (options?.assumeModelExists) {
+                logger.warn(`Skipping validation for model ${model}`);
+            }
+            else if (model &&
+                provider.capabilities &&
+                !provider.capabilities.supportsImageGeneration(model)) {
+                throw new ModelCapabilityError(model, "image generation");
+            }
+            const response = await provider.paint({
+                prompt: currentPrompt,
+                ...options,
+                model,
+                requestTimeout: options?.requestTimeout ?? this.config.requestTimeout
+            });
+            const imageResult = new GeneratedImage(response);
+            await runMiddleware(middlewares, "onResponse", context, imageResult);
+            return imageResult;
         }
-        else if (model &&
-            provider.capabilities &&
-            !provider.capabilities.supportsImageGeneration(model)) {
-            throw new ModelCapabilityError(model, "image generation");
+        catch (error) {
+            await runMiddleware(middlewares, "onError", context, error);
+            throw error;
         }
-        const response = await provider.paint({
-            prompt,
-            ...options,
-            model,
-            requestTimeout: options?.requestTimeout ?? this.config.requestTimeout
-        });
-        return new GeneratedImage(response);
     }
     async transcribe(file, options) {
         const provider = this.ensureProviderSupport("transcribe");
-        const rawModel = options?.model || this.defaults.transcription || "";
+        const rawModel = options?.model || this.defaults.transcription || provider.defaultModel("transcription");
         const model = resolveModelAlias(rawModel, provider.id);
-        if (options?.assumeModelExists) {
-            logger.warn(`Skipping validation for model ${model}`);
+        const requestId = randomUUID();
+        const state = {};
+        const context = {
+            requestId,
+            provider: provider.id,
+            model,
+            input: file,
+            transcriptionOptions: options,
+            state
+        };
+        const middlewares = [...this.middlewares, ...(options?.middlewares || [])];
+        try {
+            await runMiddleware(middlewares, "onRequest", context);
+            const currentFile = context.input || file;
+            if (options?.assumeModelExists) {
+                logger.warn(`Skipping validation for model ${model}`);
+            }
+            else if (model &&
+                provider.capabilities &&
+                !provider.capabilities.supportsTranscription(model)) {
+                throw new ModelCapabilityError(model, "transcription");
+            }
+            const response = await provider.transcribe({
+                file: currentFile,
+                ...options,
+                model,
+                requestTimeout: options?.requestTimeout ?? this.config.requestTimeout
+            });
+            const transcriptionResult = new Transcription(response);
+            await runMiddleware(middlewares, "onResponse", context, transcriptionResult);
+            return transcriptionResult;
         }
-        else if (model &&
-            provider.capabilities &&
-            !provider.capabilities.supportsTranscription(model)) {
-            throw new ModelCapabilityError(model, "transcription");
+        catch (error) {
+            await runMiddleware(middlewares, "onError", context, error);
+            throw error;
         }
-        const response = await provider.transcribe({
-            file,
-            ...options,
-            model,
-            requestTimeout: options?.requestTimeout ?? this.config.requestTimeout
-        });
-        return new Transcription(response);
     }
     async moderate(input, options) {
         const provider = this.ensureProviderSupport("moderate");
-        const rawModel = options?.model || this.defaults.moderation || "";
+        const rawModel = options?.model || this.defaults.moderation || provider.defaultModel("moderation");
         const model = resolveModelAlias(rawModel, provider.id);
-        if (options?.assumeModelExists) {
-            logger.warn(`Skipping validation for model ${model}`);
+        const requestId = randomUUID();
+        const state = {};
+        const context = {
+            requestId,
+            provider: provider.id,
+            model,
+            input,
+            moderationOptions: options,
+            state
+        };
+        const middlewares = [...this.middlewares, ...(options?.middlewares || [])];
+        try {
+            await runMiddleware(middlewares, "onRequest", context);
+            const currentInput = context.input || input;
+            if (options?.assumeModelExists) {
+                logger.warn(`Skipping validation for model ${model}`);
+            }
+            else if (model &&
+                provider.capabilities &&
+                !provider.capabilities.supportsModeration(model)) {
+                throw new ModelCapabilityError(model, "moderation");
+            }
+            const response = await provider.moderate({
+                input: currentInput,
+                ...options,
+                model,
+                requestTimeout: options?.requestTimeout ?? this.config.requestTimeout
+            });
+            const moderationResult = new Moderation(response);
+            await runMiddleware(middlewares, "onResponse", context, moderationResult);
+            return moderationResult;
         }
-        else if (model && provider.capabilities && !provider.capabilities.supportsModeration(model)) {
-            throw new ModelCapabilityError(model, "moderation");
+        catch (error) {
+            await runMiddleware(middlewares, "onError", context, error);
+            throw error;
         }
-        const response = await provider.moderate({
-            input,
-            ...options,
-            model,
-            requestTimeout: options?.requestTimeout ?? this.config.requestTimeout
-        });
-        return new Moderation(response);
     }
     async embed(input, options) {
         const provider = this.ensureProviderSupport("embed");
-        const rawModel = options?.model || this.defaults.embedding || "";
+        const rawModel = options?.model || this.defaults.embedding || provider.defaultModel("embedding");
         const model = resolveModelAlias(rawModel, provider.id);
-        const request = {
-            input,
+        const requestId = randomUUID();
+        const state = {};
+        const context = {
+            requestId,
+            provider: provider.id,
             model,
-            dimensions: options?.dimensions,
-            requestTimeout: options?.requestTimeout ?? this.config.requestTimeout
+            input,
+            embeddingOptions: options,
+            state
         };
-        if (options?.assumeModelExists) {
-            logger.warn(`Skipping validation for model ${request.model}`);
+        const middlewares = [...this.middlewares, ...(options?.middlewares || [])];
+        try {
+            await runMiddleware(middlewares, "onRequest", context);
+            // Re-read input from context as it might have been modified
+            const currentInput = context.input || input;
+            const request = {
+                input: currentInput,
+                model,
+                dimensions: options?.dimensions,
+                requestTimeout: options?.requestTimeout ?? this.config.requestTimeout
+            };
+            if (options?.assumeModelExists) {
+                logger.warn(`Skipping validation for model ${request.model}`);
+            }
+            else if (request.model &&
+                provider.capabilities &&
+                !provider.capabilities.supportsEmbeddings(request.model)) {
+                throw new ModelCapabilityError(request.model, "embeddings");
+            }
+            const response = await provider.embed(request);
+            const embeddingResult = new Embedding(response);
+            await runMiddleware(middlewares, "onResponse", context, embeddingResult);
+            return embeddingResult;
         }
-        else if (request.model &&
-            provider.capabilities &&
-            !provider.capabilities.supportsEmbeddings(request.model)) {
-            throw new ModelCapabilityError(request.model, "embeddings");
+        catch (error) {
+            await runMiddleware(middlewares, "onError", context, error);
+            throw error;
         }
-        const response = await provider.embed(request);
-        return new Embedding(response);
     }
 }
 export { Transcription, Moderation, Embedding, ModelRegistry, PricingRegistry };
@@ -230,7 +327,7 @@ export function createLLM(options = {}) {
         moderation: options.defaultModerationModel,
         embedding: options.defaultEmbeddingModel
     };
-    return new NodeLLMCore(baseConfig, providerInstance, retry, defaults);
+    return new NodeLLMCore(baseConfig, providerInstance, retry, options.middlewares || [], defaults);
 }
 /**
  * DEFAULT IMMUTABLE INSTANCE

package/dist/middlewares/CostGuardMiddleware.d.ts

@@ -0,0 +1,24 @@
+import { Middleware, MiddlewareContext } from "../types/Middleware.js";
+import { ChatResponseString } from "../chat/ChatResponse.js";
+export interface CostGuardOptions {
+    /**
+     * Maximum allowed cost (in USD) for a single request sequence.
+     */
+    maxCost: number;
+    /**
+     * Callback when the limit is exceeded.
+     */
+    onLimitExceeded?: (ctx: MiddlewareContext, currentCost: number) => void;
+}
+/**
+ * Middleware that monitors accumulated cost during a session (especially multi-turn tool calls)
+ * and throws an error if a defined limit is exceeded.
+ */
+export declare class CostGuardMiddleware implements Middleware {
+    private options;
+    readonly name = "CostGuard";
+    private accumulatedCost;
+    constructor(options: CostGuardOptions);
+    onResponse(ctx: MiddlewareContext, result: ChatResponseString): Promise<void>;
+}
+//# sourceMappingURL=CostGuardMiddleware.d.ts.map

package/dist/middlewares/CostGuardMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CostGuardMiddleware.d.ts","sourceRoot":"","sources":["../../src/middlewares/CostGuardMiddleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;CACzE;AAED;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,UAAU;IAIxC,OAAO,CAAC,OAAO;IAH3B,SAAgB,IAAI,eAAe;IACnC,OAAO,CAAC,eAAe,CAAa;gBAEhB,OAAO,EAAE,gBAAgB;IAMvC,UAAU,CAAC,GAAG,EAAE,iBAAiB,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;CAWpF"}

package/dist/middlewares/CostGuardMiddleware.js

@@ -0,0 +1,23 @@
+/**
+ * Middleware that monitors accumulated cost during a session (especially multi-turn tool calls)
+ * and throws an error if a defined limit is exceeded.
+ */
+export class CostGuardMiddleware {
+    options;
+    name = "CostGuard";
+    accumulatedCost = 0;
+    constructor(options) {
+        this.options = options;
+        if (options.maxCost <= 0) {
+            throw new Error("CostGuard maxCost must be greater than 0");
+        }
+    }
+    async onResponse(ctx, result) {
+        const cost = result.usage?.cost || 0;
+        this.accumulatedCost += cost;
+        if (this.accumulatedCost > this.options.maxCost) {
+            this.options.onLimitExceeded?.(ctx, this.accumulatedCost);
+            throw new Error(`[CostGuard] Budget exceeded. Accumulated cost $${this.accumulatedCost.toFixed(6)} exceeds limit $${this.options.maxCost.toFixed(6)}`);
+        }
+    }
+}