@node-llm/core 1.8.0 → 1.10.0

package/dist/providers/openai/OpenAIProvider.d.ts

@@ -37,7 +37,7 @@ export declare class OpenAIProvider extends BaseProvider implements Provider {
     apiBase(): string;
     headers(): Record<string, string>;
     protected providerName(): string;
-    defaultModel(_feature?: string): string;
+    defaultModel(feature?: string): string;
     chat(request: ChatRequest): Promise<ChatResponse>;
     stream(request: ChatRequest): AsyncGenerator<ChatChunk>;
     listModels(): Promise<ModelInfo[]>;

package/dist/providers/openai/OpenAIProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OpenAIProvider.d.ts","sourceRoot":"","sources":["../../../src/providers/openai/OpenAIProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,SAAS,EACT,SAAS,EACT,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,cAAe,SAAQ,YAAa,YAAW,QAAQ;IAwBtD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,qBAAqB;IAvB7D,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,WAAW,EAAE,UAAU,CAAC;IAClC,SAAS,CAAC,gBAAgB,EAAE,eAAe,CAAC;IAC5C,SAAS,CAAC,aAAa,EAAE,YAAY,CAAC;IACtC,SAAS,CAAC,YAAY,EAAE,WAAW,CAAC;IACpC,SAAS,CAAC,oBAAoB,EAAE,mBAAmB,CAAC;IACpD,SAAS,CAAC,iBAAiB,EAAE,gBAAgB,CAAC;IAC9C,SAAS,CAAC,gBAAgB,EAAE,eAAe,CAAC;IAErC,YAAY;gCACO,MAAM;+BACP,MAAM;0CACK,MAAM;oCACZ,MAAM;yCACD,MAAM;uCACR,MAAM;oCACT,MAAM;mCACP,MAAM;yCACA,MAAM;kCAEb,MAAM;MAChC;gBAE6B,OAAO,EAAE,qBAAqB;IAYtD,OAAO,IAAI,MAAM;IAIjB,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAOxC,SAAS,CAAC,YAAY,IAAI,MAAM;IAIhB,YAAY,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM;IAIjD,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAIhD,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc,CAAC,SAAS,CAAC;IAIxD,UAAU,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAIlC,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAIpD,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIzE,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIjE,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAGnE"}
+{"version":3,"file":"OpenAIProvider.d.ts","sourceRoot":"","sources":["../../../src/providers/openai/OpenAIProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,SAAS,EACT,SAAS,EACT,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,cAAe,SAAQ,YAAa,YAAW,QAAQ;IAwBtD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,qBAAqB;IAvB7D,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,WAAW,EAAE,UAAU,CAAC;IAClC,SAAS,CAAC,gBAAgB,EAAE,eAAe,CAAC;IAC5C,SAAS,CAAC,aAAa,EAAE,YAAY,CAAC;IACtC,SAAS,CAAC,YAAY,EAAE,WAAW,CAAC;IACpC,SAAS,CAAC,oBAAoB,EAAE,mBAAmB,CAAC;IACpD,SAAS,CAAC,iBAAiB,EAAE,gBAAgB,CAAC;IAC9C,SAAS,CAAC,gBAAgB,EAAE,eAAe,CAAC;IAErC,YAAY;gCACO,MAAM;+BACP,MAAM;0CACK,MAAM;oCACZ,MAAM;yCACD,MAAM;uCACR,MAAM;oCACT,MAAM;mCACP,MAAM;yCACA,MAAM;kCAEb,MAAM;MAChC;gBAE6B,OAAO,EAAE,qBAAqB;IAYtD,OAAO,IAAI,MAAM;IAIjB,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAOxC,SAAS,CAAC,YAAY,IAAI,MAAM;IAIhB,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM;IAehD,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAIhD,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc,CAAC,SAAS,CAAC;IAIxD,UAAU,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAIlC,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAIpD,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIzE,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIjE,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAGnE"}

package/dist/providers/openai/OpenAIProvider.js

@@ -1,4 +1,5 @@
 import { BaseProvider } from "../BaseProvider.js";
+import { DEFAULT_OPENAI_BASE_URL } from "../../constants.js";
 import { Capabilities } from "./Capabilities.js";
 import { OpenAIChat } from "./Chat.js";
 import { OpenAIStreaming } from "./Streaming.js";
@@ -32,7 +33,7 @@ export class OpenAIProvider extends BaseProvider {
     constructor(options) {
         super();
         this.options = options;
-        this.baseUrl = options.baseUrl ?? "https://api.openai.com/v1";
+        this.baseUrl = options.baseUrl ?? DEFAULT_OPENAI_BASE_URL;
         this.chatHandler = new OpenAIChat(this, options.apiKey);
         this.streamingHandler = new OpenAIStreaming(this, options.apiKey);
         this.modelsHandler = new OpenAIModels(this.baseUrl, options.apiKey);
@@ -53,8 +54,19 @@ export class OpenAIProvider extends BaseProvider {
     providerName() {
         return "OpenAI";
     }
-    defaultModel(_feature) {
-        return "gpt-4o";
+    defaultModel(feature) {
+        switch (feature) {
+            case "embedding":
+                return "text-embedding-3-small";
+            case "transcription":
+                return "whisper-1";
+            case "moderation":
+                return "omni-moderation-latest";
+            case "image":
+                return "dall-e-3";
+            default:
+                return "gpt-4o";
+        }
     }
     async chat(request) {
         return this.chatHandler.execute(request);

package/dist/providers/openai/Streaming.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Streaming.d.ts","sourceRoot":"","sources":["../../../src/providers/openai/Streaming.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAQxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,qBAAa,eAAe;IAIxB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAGd,aAAa,EAAE,cAAc,GAAG,MAAM,EACtC,MAAM,EAAE,MAAM;IAK1B,OAAO,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,CAAC,EAAE,eAAe,GAAG,cAAc,CAAC,SAAS,CAAC;CAoM9F"}
+{"version":3,"file":"Streaming.d.ts","sourceRoot":"","sources":["../../../src/providers/openai/Streaming.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAQxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,qBAAa,eAAe;IAIxB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAGd,aAAa,EAAE,cAAc,GAAG,MAAM,EACtC,MAAM,EAAE,MAAM;IAK1B,OAAO,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,CAAC,EAAE,eAAe,GAAG,cAAc,CAAC,SAAS,CAAC;CAgN9F"}

package/dist/providers/openai/Streaming.js

@@ -50,6 +50,7 @@ export class OpenAIStreaming {
         if (request.thinking?.effort && request.thinking.effort !== "none") {
             body.reasoning_effort = request.thinking.effort;
         }
+        body.stream_options = { include_usage: true };
         let done = false;
         // Track tool calls being built across chunks
         const toolCallsMap = new Map();
@@ -154,6 +155,15 @@ export class OpenAIStreaming {
                                 }
                             }
                         }
+                        // Handle usage (usually in the special chunk when stream_options.include_usage: true)
+                        if (json.usage) {
+                            const usage = {
+                                input_tokens: json.usage.prompt_tokens,
+                                output_tokens: json.usage.completion_tokens,
+                                total_tokens: json.usage.total_tokens
+                            };
+                            yield { content: "", usage };
+                        }
                     }
                     catch (e) {
                         // Re-throw APIError

package/dist/providers/openrouter/OpenRouterProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OpenRouterProvider.d.ts","sourceRoot":"","sources":["../../../src/providers/openrouter/OpenRouterProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAG7D,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,kBAAmB,SAAQ,cAAc;IAC7C,YAAY;gCACO,MAAM;+BACP,MAAM;0CACK,MAAM;oCAEZ,MAAM;yCACD,MAAM;uCAER,MAAM;oCACT,MAAM;mCACP,MAAM;wCACD,MAAM;kCACZ,MAAM;MAChC;gBAEU,OAAO,EAAE,yBAAyB;IAO9C,SAAS,CAAC,YAAY,IAAI,MAAM;CAGjC"}
+{"version":3,"file":"OpenRouterProvider.d.ts","sourceRoot":"","sources":["../../../src/providers/openrouter/OpenRouterProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAI7D,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,kBAAmB,SAAQ,cAAc;IAC7C,YAAY;gCACO,MAAM;+BACP,MAAM;0CACK,MAAM;oCAEZ,MAAM;yCACD,MAAM;uCAER,MAAM;oCACT,MAAM;mCACP,MAAM;wCACD,MAAM;kCACZ,MAAM;MAChC;gBAEU,OAAO,EAAE,yBAAyB;IAO9C,SAAS,CAAC,YAAY,IAAI,MAAM;CAGjC"}

package/dist/providers/openrouter/OpenRouterProvider.js

@@ -1,4 +1,5 @@
 import { OpenAIProvider } from "../openai/OpenAIProvider.js";
+import { DEFAULT_OPENROUTER_BASE_URL } from "../../constants.js";
 import { OpenRouterCapabilities } from "./Capabilities.js";
 export class OpenRouterProvider extends OpenAIProvider {
     capabilities = {
@@ -16,7 +17,7 @@ export class OpenRouterProvider extends OpenAIProvider {
     constructor(options) {
         super({
             apiKey: options.apiKey,
-            baseUrl: options.baseUrl || "https://openrouter.ai/api/v1"
+            baseUrl: options.baseUrl || DEFAULT_OPENROUTER_BASE_URL
         });
     }
     providerName() {

package/dist/providers/registry.d.ts

@@ -8,8 +8,11 @@ import { registerOpenRouterProvider } from "./openrouter/index.js";
 import { registerBedrockProvider } from "./bedrock/index.js";
 import { NodeLLMConfig } from "../config.js";
 type ProviderFactory = (config?: NodeLLMConfig) => Provider;
+export type ProviderInterceptor = (provider: Provider) => Provider;
 declare class ProviderRegistry {
     private providers;
+    private globalInterceptor?;
+    setInterceptor(interceptor: ProviderInterceptor | undefined): void;
     /**
      * Register a provider factory
      */

package/dist/providers/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/providers/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,KAAK,eAAe,GAAG,CAAC,MAAM,CAAC,EAAE,aAAa,KAAK,QAAQ,CAAC;AAE5D,cAAM,gBAAgB;IACpB,OAAO,CAAC,SAAS,CAAsC;IAEvD;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI;IAQtD;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,QAAQ;IAUvD;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;OAEG;IACH,IAAI,IAAI,MAAM,EAAE;CAGjB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,kBAAyB,CAAC;AAGvD,OAAO,EACL,sBAAsB,IAAI,sBAAsB,EAChD,sBAAsB,EACtB,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,EACxB,CAAC"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/providers/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,KAAK,eAAe,GAAG,CAAC,MAAM,CAAC,EAAE,aAAa,KAAK,QAAQ,CAAC;AAC5D,MAAM,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,QAAQ,KAAK,QAAQ,CAAC;AAEnE,cAAM,gBAAgB;IACpB,OAAO,CAAC,SAAS,CAAsC;IACvD,OAAO,CAAC,iBAAiB,CAAC,CAAsB;IAEzC,cAAc,CAAC,WAAW,EAAE,mBAAmB,GAAG,SAAS;IAIlE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe;IAO/C;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,QAAQ;IAgBvD;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;OAEG;IACH,IAAI,IAAI,MAAM,EAAE;CAGjB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,kBAAyB,CAAC;AAGvD,OAAO,EACL,sBAAsB,IAAI,sBAAsB,EAChD,sBAAsB,EACtB,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,EACxB,CAAC"}

package/dist/providers/registry.js

@@ -7,6 +7,10 @@ import { registerOpenRouterProvider } from "./openrouter/index.js";
 import { registerBedrockProvider } from "./bedrock/index.js";
 class ProviderRegistry {
     providers = new Map();
+    globalInterceptor;
+    setInterceptor(interceptor) {
+        this.globalInterceptor = interceptor;
+    }
     /**
      * Register a provider factory
      */
@@ -22,9 +26,13 @@ class ProviderRegistry {
     resolve(name, config) {
         const factory = this.providers.get(name);
         if (!factory) {
-            throw new Error(`Unknown LLM provider '${name}'`);
+            throw new Error(`Provider ${name} not registered`);
+        }
+        let provider = factory(config);
+        if (this.globalInterceptor) {
+            provider = this.globalInterceptor(provider);
         }
-        return factory(config);
+        return provider;
     }
     /**
      * Check if a provider is registered

package/dist/types/Middleware.d.ts

@@ -0,0 +1,98 @@
+import { Message } from "../chat/Message.js";
+import { ChatOptions } from "../chat/ChatOptions.js";
+import { ChatResponseString } from "../chat/ChatResponse.js";
+import { ToolCall } from "../chat/Tool.js";
+/**
+ * Context passed to all middleware hooks.
+ * This object is shared across the lifecycle of a single request.
+ */
+export interface MiddlewareContext {
+    /**
+     * Unique ID for tracing the request across the system.
+     */
+    requestId: string;
+    /**
+     * The provider being used (e.g., "openai", "anthropic").
+     */
+    provider: string;
+    /**
+     * The model identifier being used.
+     */
+    model: string;
+    /**
+     * The messages sent to the model (Chat only).
+     * Mutating this array in `onRequest` affects the actual call.
+     */
+    messages?: Message[];
+    /**
+     * Configuration options for the chat request (Chat only).
+     * Mutating this object in `onRequest` affects the actual call.
+     */
+    options?: ChatOptions;
+    /**
+     * Input text(s) for embeddings (Embedding only).
+     */
+    input?: string | string[];
+    /**
+     * Options passed to the embedding request (Embedding only).
+     */
+    embeddingOptions?: Record<string, any>;
+    /**
+     * Options passed to the transcription request (Transcription only).
+     */
+    transcriptionOptions?: Record<string, any>;
+    /**
+     * Options passed to the moderation request (Moderation only).
+     */
+    moderationOptions?: Record<string, any>;
+    /**
+     * Options passed to the image generation request (Paint only).
+     */
+    imageOptions?: Record<string, any>;
+    /**
+     * Shared state storage for passing data between middleware hooks.
+     * Example: Storing start time in `onRequest` and reading it in `onResponse`.
+     */
+    state: Record<string, unknown>;
+}
+/**
+ * Directives for handling tool execution errors.
+ */
+export type ToolErrorDirective = "STOP" | "CONTINUE" | "RETRY" | void;
+/**
+ * Middleware interface for hooking into the LLM execution lifecycle.
+ */
+export interface Middleware {
+    /**
+     * Name of the middleware (useful for debugging).
+     */
+    name: string;
+    /**
+     * Called before the request is sent to the provider.
+     * Can allow modifying messages or options.
+     */
+    onRequest?(ctx: MiddlewareContext): Promise<void>;
+    /**
+     * Called after a successful response from the provider.
+     */
+    onResponse?(ctx: MiddlewareContext, result: ChatResponseString): Promise<void>;
+    /**
+     * Called if an error occurs during execution.
+     */
+    onError?(ctx: MiddlewareContext, error: Error): Promise<void>;
+    /**
+     * Called before a tool is executed.
+     * Throwing here will prevent the tool from running.
+     */
+    onToolCallStart?(ctx: MiddlewareContext, tool: ToolCall): Promise<void>;
+    /**
+     * Called after a tool completes successfully.
+     */
+    onToolCallEnd?(ctx: MiddlewareContext, tool: ToolCall, result: unknown): Promise<void>;
+    /**
+     * Called if a tool execution fails.
+     * Can return a directive to tell the engine how to proceed.
+     */
+    onToolCallError?(ctx: MiddlewareContext, tool: ToolCall, error: Error): Promise<ToolErrorDirective>;
+}
+//# sourceMappingURL=Middleware.d.ts.map

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

@@ -0,0 +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"}

package/dist/types/Middleware.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/json.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Boring, standard JSON extraction logic.
+ * Avoids cleverness in favor of predictable industry-standard patterns.
+ */
+export declare function extractJson(text: string): string;
+//# sourceMappingURL=json.d.ts.map

package/dist/utils/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/utils/json.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAwChD"}

package/dist/utils/json.js

@@ -0,0 +1,43 @@
+/**
+ * Boring, standard JSON extraction logic.
+ * Avoids cleverness in favor of predictable industry-standard patterns.
+ */
+export function extractJson(text) {
+    const cleaned = text.trim();
+    // 1. Fast path: The string is already just JSON
+    try {
+        JSON.parse(cleaned);
+        return cleaned;
+    }
+    catch {
+        // Continue extraction
+    }
+    // 2. Handle Markdown blocks (the most common LLM artifact)
+    const markdownMatch = cleaned.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (markdownMatch?.[1]) {
+        const candidate = markdownMatch[1].trim();
+        try {
+            JSON.parse(candidate);
+            return candidate;
+        }
+        catch {
+            // Invalid JSON inside backticks, fall through
+        }
+    }
+    // 3. Last resort: Find the first '{' and last '}'
+    // This handles conversational filler like "Here is your data: { ... }"
+    const firstBrace = cleaned.indexOf("{");
+    const lastBrace = cleaned.lastIndexOf("}");
+    if (firstBrace !== -1 && lastBrace !== -1 && lastBrace > firstBrace) {
+        const candidate = cleaned.substring(firstBrace, lastBrace + 1);
+        try {
+            JSON.parse(candidate);
+            return candidate;
+        }
+        catch {
+            // Not valid JSON
+        }
+    }
+    // 4. Return as-is and let the final JSON.parse() fail loudly
+    return cleaned;
+}

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

@@ -0,0 +1,7 @@
+import { Middleware, MiddlewareContext } from "../types/Middleware.js";
+/**
+ * Helper to execute middleware chains in order.
+ * @internal
+ */
+export declare function runMiddleware<T = void>(middlewares: Middleware[], hookName: keyof Middleware, context: MiddlewareContext, ...args: any[]): Promise<T | undefined>;
+//# sourceMappingURL=middleware-runner.d.ts.map

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

@@ -0,0 +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"}

package/dist/utils/middleware-runner.js

@@ -0,0 +1,20 @@
+/**
+ * Helper to execute middleware chains in order.
+ * @internal
+ */
+export async function runMiddleware(middlewares, hookName, context, ...args) {
+    if (!middlewares || middlewares.length === 0)
+        return undefined;
+    let finalResult;
+    for (const middleware of middlewares) {
+        if (typeof middleware[hookName] === "function") {
+            // @ts-ignore
+            const result = await middleware[hookName](context, ...args);
+            // Capture the first non-void result (for directives)
+            if (result !== undefined && finalResult === undefined) {
+                finalResult = result;
+            }
+        }
+    }
+    return finalResult;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@node-llm/core",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",