@node-llm/core 1.4.3 → 1.5.0

package/README.md

@@ -150,7 +150,34 @@ class WeatherTool extends Tool {
 // Now the model can use it automatically
 await chat.withTool(WeatherTool).ask("What's the weather in Tokyo?");
 ```
-**[Full Tool Calling Guide →](https://node-llm.eshaiju.com/core-features/tool-calling)**
+
+### 🛡️ Loop Protection & Resource Limits
+Prevent runaway costs, infinite loops, and hanging requests with comprehensive protection against resource exhaustion.
+
+NodeLLM provides **defense-in-depth** security that you can configure globally or per-request:
+
+```ts
+// 1. Global config
+NodeLLM.configure({ 
+  requestTimeout: 30000, // Timeout requests after 30 seconds (default)
+  maxToolCalls: 5,       // Stop after 5 sequential tool execution turns
+  maxRetries: 2,         // Retry provider-level errors up to 2 times
+  maxTokens: 4096        // Limit output to 4K tokens (default)
+});
+
+// 2. Per request override
+await chat.ask("Deep search task", { 
+  requestTimeout: 120000, // 2 minutes for this request
+  maxToolCalls: 10,
+  maxTokens: 8192         // 8K tokens for this request
+});
+```
+
+**Security Benefits:**
+- **`requestTimeout`**: Prevents DoS attacks and hanging requests
+- **`maxToolCalls`**: Prevents infinite tool execution loops
+- **`maxRetries`**: Prevents retry storms during outages
+- **`maxTokens`**: Prevents excessive output and cost overruns
 
 ### 🔍 Comprehensive Debug Logging
 Enable detailed logging for all API requests and responses across every feature and provider:
@@ -166,6 +193,42 @@ process.env.NODELLM_DEBUG = "true";
 ```
 **Covers:** Chat, Streaming, Images, Embeddings, Transcription, Moderation - across all providers!
 
+### 🛡️ Content Policy Hooks
+NodeLLM provides pluggable hooks to implement custom security, compliance, and moderation logic. Instead of hard-coded rules, you can inject your own policies at the edge.
+
+- **`beforeRequest()`**: Intercept and modify messages before they hit the LLM (e.g., PII detection/redaction).
+- **`afterResponse()`**: Process the final response before it returns to your code (e.g., output masking or compliance checks).
+
+```ts
+chat
+  .beforeRequest(async (messages) => {
+    // Detect PII and redact
+    return redactSSN(messages);
+  })
+  .afterResponse(async (response) => {
+    // Ensure output compliance
+    return response.withContent(maskSensitiveData(response.content));
+  });
+```
+
+### 🧱 Smart Context Isolation
+Stop worrying about prompt injection or instruction drift. NodeLLM automatically separates system instructions from the conversation history, providing a higher level of protection and strictness.
+
+- **Zero-Config Security**: Enabled by default for all chats. No special flags required.
+- **Smart Model Mapping**: Automatically uses OpenAI's modern `developer` role for compatible models (GPT-4o, o1, o3) while safely falling back to the standard `system` role for older or local models (Ollama, DeepSeek, etc.).
+- **Universal Context**: Instructions stay separated internally, ensuring they are always prioritized by the model and never accidentally overridden by user messages.
+- **Provider Agnostic**: Write instructions once; NodeLLM handles the specific role requirements for every major provider (OpenAI, Anthropic, Gemini).
+
+### 🔍 Observability & Tool Auditing
+For enterprise compliance, NodeLLM provides deep visibility into the tool execution lifecycle. You can monitor, log, and audit every step of a tool's execution.
+
+```ts
+chat
+  .onToolCallStart((call) => log(`Starting tool: ${call.function.name}`))
+  .onToolCallEnd((call, res) => log(`Tool ${call.id} finished with: ${res}`))
+  .onToolCallError((call, err) => alert(`Tool ${call.function.name} failed: ${err.message}`));
+```
+
 ### ✨ Structured Output
 Get type-safe, validated JSON back using **Zod** schemas.
 ```ts
@@ -222,7 +285,7 @@ console.log(res.reasoning); // Chain-of-thought
 
 | Provider | Supported Features |
 | :--- | :--- |
-| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openai.svg" height="18"> **OpenAI** | Chat, **Streaming + Tools**, Vision, Audio, Images, Transcription, **Reasoning** |
+| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openai.svg" height="18"> **OpenAI** | Chat, **Streaming + Tools**, Vision, Audio, Images, Transcription, **Reasoning**, **Smart Developer Role** |
 | <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/gemini-color.svg" height="18"> **Gemini** | Chat, **Streaming + Tools**, Vision, Audio, Video, Embeddings |
 | <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/anthropic-text.svg" height="12"> **Anthropic** | Chat, **Streaming + Tools**, Vision, PDF, Structured Output |
 | <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/deepseek-color.svg" height="18"> **DeepSeek** | Chat (V3), **Reasoning (R1)**, **Streaming + Tools** |

package/dist/chat/Chat.d.ts

@@ -5,12 +5,15 @@ import { Stream } from "../streaming/Stream.js";
 import { Tool } from "./Tool.js";
 import { Schema } from "../schema/Schema.js";
 import { z } from "zod";
+import { ToolExecutionMode } from "../constants.js";
 export interface AskOptions {
     images?: string[];
     files?: string[];
     temperature?: number;
     maxTokens?: number;
     headers?: Record<string, string>;
+    maxToolCalls?: number;
+    requestTimeout?: number;
 }
 import { ChatResponseString } from "./ChatResponse.js";
 export declare class Chat {
@@ -18,6 +21,7 @@ export declare class Chat {
     private model;
     private readonly options;
     private messages;
+    private systemMessages;
     private executor;
     constructor(provider: Provider, model: string, options?: ChatOptions, retryConfig?: {
         attempts: number;
@@ -95,6 +99,40 @@ export declare class Chat {
     onEndMessage(handler: (message: ChatResponseString) => void): this;
     onToolCall(handler: (toolCall: any) => void): this;
     onToolResult(handler: (result: any) => void): this;
+    /**
+     * Called when a tool call starts.
+     */
+    onToolCallStart(handler: (toolCall: any) => void): this;
+    /**
+     * Called when a tool call ends successfully.
+     */
+    onToolCallEnd(handler: (toolCall: any, result: any) => void): this;
+    /**
+     * Called when a tool call fails.
+     */
+    onToolCallError(handler: (toolCall: any, error: Error) => void): this;
+    /**
+     * Set the tool execution mode.
+     * - "auto": (Default) Automatically execute all tool calls.
+     * - "confirm": Call onConfirmToolCall before executing each tool.
+     * - "dry-run": Propose tool calls but do not execute them.
+     */
+    withToolExecution(mode: ToolExecutionMode): this;
+    /**
+     * Hook for confirming tool execution in "confirm" mode.
+     * Return true to proceed, false to cancel the specific call.
+     */
+    onConfirmToolCall(handler: (toolCall: any) => Promise<boolean> | boolean): this;
+    /**
+     * Add a hook to process messages before sending to the LLM.
+     * Useful for PII detection, redaction, and input moderation.
+     */
+    beforeRequest(handler: (messages: Message[]) => Promise<Message[] | void>): this;
+    /**
+     * Add a hook to process the response before returning it.
+     * Useful for output redaction, compliance, and post-moderation.
+     */
+    afterResponse(handler: (response: ChatResponseString) => Promise<ChatResponseString | void>): this;
     /**
      * Ask the model a question
      */
@@ -103,5 +141,18 @@ export declare class Chat {
      * Streams the model's response to a user question.
      */
     stream(content: string): Stream<ChatChunk>;
+    /**
+     * Check if tool execution should proceed based on the current mode.
+     */
+    private shouldExecuteTools;
+    /**
+     * Request user confirmation for a tool call in "confirm" mode.
+     * Returns true if approved, false if rejected.
+     */
+    private requestToolConfirmation;
+    /**
+     * Execute a single tool call and return the result message.
+     */
+    private executeToolCall;
 }
 //# sourceMappingURL=Chat.d.ts.map

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

@@ -4,12 +4,15 @@ import { ChatStream } from "./ChatStream.js";
 import { Schema } from "../schema/Schema.js";
 import { toJsonSchema } from "../schema/to-json-schema.js";
 import { z } from "zod";
+import { config } from "../config.js";
+import { ToolExecutionMode } from "../constants.js";
 import { ChatResponseString } from "./ChatResponse.js";
 export class Chat {
     provider;
     model;
     options;
     messages = [];
+    systemMessages = [];
     executor;
     constructor(provider, model, options = {}, retryConfig = { attempts: 1, delayMs: 0 }) {
         this.provider = provider;
@@ -17,20 +20,27 @@ export class Chat {
         this.options = options;
         this.executor = new Executor(provider, retryConfig);
         if (options.systemPrompt) {
-            this.messages.push({
-                role: "system",
-                content: options.systemPrompt,
-            });
+            this.withInstructions(options.systemPrompt);
         }
         if (options.messages) {
-            this.messages.push(...options.messages);
+            for (const msg of options.messages) {
+                if (msg.role === "system" || msg.role === "developer") {
+                    this.systemMessages.push(msg);
+                }
+                else {
+                    this.messages.push(msg);
+                }
+            }
+        }
+        if (!this.options.toolExecution) {
+            this.options.toolExecution = config.toolExecution || ToolExecutionMode.AUTO;
         }
     }
     /**
      * Read-only access to message history
      */
     get history() {
-        return this.messages;
+        return [...this.systemMessages, ...this.messages];
     }
     get modelId() {
         return this.model;
@@ -106,19 +116,10 @@ export class Chat {
      */
     withInstructions(instruction, options) {
         if (options?.replace) {
-            this.messages = this.messages.filter((m) => m.role !== "system");
-        }
-        // System messages usually go first, but for "appending" behavior 
-        // mid-conversation, most providers handle them fine in history.
-        // Ideally, if it's "replace", we might want to unshift it to index 0,
-        // but simply pushing a new system message works for "updating" context too.
-        // For consistency with "replace" meaning "this is THE system prompt":
-        if (options?.replace) {
-            this.messages.unshift({ role: "system", content: instruction });
-        }
-        else {
-            this.messages.push({ role: "system", content: instruction });
+            this.systemMessages = [];
         }
+        // Always push to isolated storage
+        this.systemMessages.push({ role: "system", content: instruction });
         return this;
     }
     /**
@@ -193,11 +194,64 @@ export class Chat {
         return this;
     }
     onToolCall(handler) {
-        this.options.onToolCall = handler;
-        return this;
+        return this.onToolCallStart(handler);
     }
     onToolResult(handler) {
-        this.options.onToolResult = handler;
+        return this.onToolCallEnd((_call, result) => handler(result));
+    }
+    /**
+     * Called when a tool call starts.
+     */
+    onToolCallStart(handler) {
+        this.options.onToolCallStart = handler;
+        return this;
+    }
+    /**
+     * Called when a tool call ends successfully.
+     */
+    onToolCallEnd(handler) {
+        this.options.onToolCallEnd = handler;
+        return this;
+    }
+    /**
+     * Called when a tool call fails.
+     */
+    onToolCallError(handler) {
+        this.options.onToolCallError = handler;
+        return this;
+    }
+    /**
+     * Set the tool execution mode.
+     * - "auto": (Default) Automatically execute all tool calls.
+     * - "confirm": Call onConfirmToolCall before executing each tool.
+     * - "dry-run": Propose tool calls but do not execute them.
+     */
+    withToolExecution(mode) {
+        this.options.toolExecution = mode;
+        return this;
+    }
+    /**
+     * Hook for confirming tool execution in "confirm" mode.
+     * Return true to proceed, false to cancel the specific call.
+     */
+    onConfirmToolCall(handler) {
+        this.options.onConfirmToolCall = handler;
+        return this;
+    }
+    /**
+     * Add a hook to process messages before sending to the LLM.
+     * Useful for PII detection, redaction, and input moderation.
+     */
+    beforeRequest(handler) {
+        this.options.onBeforeRequest = handler;
+        return this;
+    }
+    /**
+     * Add a hook to process the response before returning it.
+     * Useful for output redaction, compliance, and post-moderation.
+     */
+    afterResponse(handler) {
+        this.options.onAfterResponse = handler;
         return this;
     }
     /**
@@ -269,14 +323,24 @@ export class Chat {
         }
         const executeOptions = {
             model: this.model,
-            messages: this.messages,
+            messages: [...this.systemMessages, ...this.messages],
             tools: this.options.tools,
             temperature: options?.temperature ?? this.options.temperature,
-            max_tokens: options?.maxTokens ?? this.options.maxTokens,
+            max_tokens: options?.maxTokens ?? this.options.maxTokens ?? config.maxTokens,
             headers: { ...this.options.headers, ...options?.headers },
             response_format: responseFormat, // Pass to provider
+            requestTimeout: options?.requestTimeout ?? this.options.requestTimeout ?? config.requestTimeout,
             ...this.options.params,
         };
+        // --- Content Policy Hooks (Input) ---
+        if (this.options.onBeforeRequest) {
+            const messagesToProcess = [...this.systemMessages, ...this.messages];
+            const result = await this.options.onBeforeRequest(messagesToProcess);
+            if (result) {
+                // If the hook returned modified messages, use them for this request
+                executeOptions.messages = result;
+            }
+        }
         let totalUsage = { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
         const trackUsage = (u) => {
             if (u) {
@@ -296,60 +360,70 @@ export class Chat {
             this.options.onNewMessage();
         let response = await this.executor.executeChat(executeOptions);
         trackUsage(response.usage);
-        const firstAssistantMessage = new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model, this.provider.id, response.reasoning);
+        let assistantMessage = new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model, this.provider.id, response.reasoning, response.tool_calls);
+        // --- Content Policy Hooks (Output - Turn 1) ---
+        if (this.options.onAfterResponse) {
+            const result = await this.options.onAfterResponse(assistantMessage);
+            if (result) {
+                assistantMessage = result;
+            }
+        }
         this.messages.push({
             role: "assistant",
-            content: firstAssistantMessage,
+            content: assistantMessage || null,
             tool_calls: response.tool_calls,
             usage: response.usage,
         });
         if (this.options.onEndMessage && (!response.tool_calls || response.tool_calls.length === 0)) {
-            this.options.onEndMessage(firstAssistantMessage);
+            this.options.onEndMessage(assistantMessage);
         }
+        const maxToolCalls = options?.maxToolCalls ?? this.options.maxToolCalls ?? 5;
+        let stepCount = 0;
         while (response.tool_calls && response.tool_calls.length > 0) {
+            // Dry-run mode: stop after proposing tools
+            if (!this.shouldExecuteTools(response.tool_calls, this.options.toolExecution)) {
+                break;
+            }
+            stepCount++;
+            if (stepCount > maxToolCalls) {
+                throw new Error(`[NodeLLM] Maximum tool execution calls (${maxToolCalls}) exceeded.`);
+            }
             for (const toolCall of response.tool_calls) {
-                if (this.options.onToolCall)
-                    this.options.onToolCall(toolCall);
-                const tool = this.options.tools?.find((t) => t.function.name === toolCall.function.name);
-                if (tool?.handler) {
-                    try {
-                        const args = JSON.parse(toolCall.function.arguments);
-                        const result = await tool.handler(args);
-                        if (this.options.onToolResult)
-                            this.options.onToolResult(result);
-                        this.messages.push({
-                            role: "tool",
-                            tool_call_id: toolCall.id,
-                            content: result,
-                        });
-                    }
-                    catch (error) {
+                // Confirm mode: request approval
+                if (this.options.toolExecution === ToolExecutionMode.CONFIRM) {
+                    const approved = await this.requestToolConfirmation(toolCall, this.options.onConfirmToolCall);
+                    if (!approved) {
                         this.messages.push({
                             role: "tool",
                             tool_call_id: toolCall.id,
-                            content: `Error executing tool: ${error.message}`,
+                            content: "Action cancelled by user.",
                         });
+                        continue;
                     }
                 }
-                else {
-                    this.messages.push({
-                        role: "tool",
-                        tool_call_id: toolCall.id,
-                        content: "Error: Tool not found or no handler provided",
-                    });
-                }
+                // Execute the tool
+                const toolResult = await this.executeToolCall(toolCall, this.options.tools, this.options.onToolCallStart, this.options.onToolCallEnd, this.options.onToolCallError);
+                this.messages.push(toolResult);
             }
             response = await this.executor.executeChat({
                 model: this.model,
-                messages: this.messages,
+                messages: [...this.systemMessages, ...this.messages],
                 tools: this.options.tools,
                 headers: this.options.headers,
+                requestTimeout: options?.requestTimeout ?? this.options.requestTimeout ?? config.requestTimeout,
             });
             trackUsage(response.usage);
-            const assistantMessage = new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model, this.provider.id, response.reasoning);
+            assistantMessage = new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model, this.provider.id, response.reasoning);
+            // --- Content Policy Hooks (Output - Tool Turns) ---
+            if (this.options.onAfterResponse) {
+                const result = await this.options.onAfterResponse(assistantMessage);
+                if (result) {
+                    assistantMessage = result;
+                }
+            }
             this.messages.push({
                 role: "assistant",
-                content: assistantMessage,
+                content: assistantMessage || null,
                 tool_calls: response.tool_calls,
                 usage: response.usage,
             });
@@ -359,13 +433,73 @@ export class Chat {
         }
         // For the final return, we might want to aggregate reasoning too if it happened in multiple turns? 
         // Usually reasoning only happens once or we just want the last one.
-        return new ChatResponseString(response.content ?? "", totalUsage, this.model, this.provider.id, response.reasoning);
+        return new ChatResponseString(assistantMessage.toString() || "", totalUsage, this.model, this.provider.id, assistantMessage.reasoning, response.tool_calls);
     }
     /**
      * Streams the model's response to a user question.
      */
     stream(content) {
-        const streamer = new ChatStream(this.provider, this.model, this.options, this.messages);
+        const streamer = new ChatStream(this.provider, this.model, this.options, this.messages, this.systemMessages);
         return streamer.create(content);
     }
+    /**
+     * Check if tool execution should proceed based on the current mode.
+     */
+    shouldExecuteTools(toolCalls, mode) {
+        if (!toolCalls || toolCalls.length === 0)
+            return false;
+        if (mode === ToolExecutionMode.DRY_RUN)
+            return false;
+        return true;
+    }
+    /**
+     * Request user confirmation for a tool call in "confirm" mode.
+     * Returns true if approved, false if rejected.
+     */
+    async requestToolConfirmation(toolCall, onConfirm) {
+        if (!onConfirm)
+            return true;
+        const confirmed = await onConfirm(toolCall);
+        return confirmed !== false;
+    }
+    /**
+     * Execute a single tool call and return the result message.
+     */
+    async executeToolCall(toolCall, tools, onStart, onEnd, onError) {
+        if (onStart)
+            onStart(toolCall);
+        const tool = tools?.find((t) => t.function.name === toolCall.function.name);
+        if (tool?.handler) {
+            try {
+                const args = JSON.parse(toolCall.function.arguments);
+                const result = await tool.handler(args);
+                if (onEnd)
+                    onEnd(toolCall, result);
+                return {
+                    role: "tool",
+                    tool_call_id: toolCall.id,
+                    content: result,
+                };
+            }
+            catch (error) {
+                if (onError)
+                    onError(toolCall, error);
+                return {
+                    role: "tool",
+                    tool_call_id: toolCall.id,
+                    content: `Error executing tool: ${error.message}`,
+                };
+            }
+        }
+        else {
+            const error = new Error("Tool not found or no handler provided");
+            if (onError)
+                onError(toolCall, error);
+            return {
+                role: "tool",
+                tool_call_id: toolCall.id,
+                content: "Error: Tool not found or no handler provided",
+            };
+        }
+    }
 }

package/dist/chat/ChatOptions.d.ts

@@ -1,6 +1,8 @@
 import { Message } from "./Message.js";
 import { ToolDefinition } from "./Tool.js";
 import { Schema } from "../schema/Schema.js";
+import { ChatResponseString } from "./ChatResponse.js";
+import { ToolExecutionMode } from "../constants.js";
 export interface ChatOptions {
     systemPrompt?: string;
     messages?: Message[];
@@ -9,8 +11,9 @@ export interface ChatOptions {
     maxTokens?: number;
     onNewMessage?: () => void;
     onEndMessage?: (message: any) => void;
-    onToolCall?: (toolCall: any) => void;
-    onToolResult?: (result: any) => void;
+    onToolCallStart?: (toolCall: any) => void;
+    onToolCallEnd?: (toolCall: any, result: any) => void;
+    onToolCallError?: (toolCall: any, error: Error) => void;
     headers?: Record<string, string>;
     schema?: Schema;
     responseFormat?: {
@@ -19,5 +22,11 @@ export interface ChatOptions {
     params?: Record<string, any>;
     assumeModelExists?: boolean;
     provider?: string;
+    maxToolCalls?: number;
+    requestTimeout?: number;
+    toolExecution?: ToolExecutionMode;
+    onConfirmToolCall?: (toolCall: any) => Promise<boolean> | boolean;
+    onBeforeRequest?: (messages: Message[]) => Promise<Message[] | void>;
+    onAfterResponse?: (response: ChatResponseString) => Promise<ChatResponseString | void>;
 }
 //# sourceMappingURL=ChatOptions.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ChatOptions.d.ts","sourceRoot":"","sources":["../../src/chat/ChatOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,MAAM,WAAW,WAAW;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,CAAC;IACtC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;IACrC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE;QAAE,IAAI,EAAE,aAAa,GAAG,MAAM,CAAA;KAAE,CAAC;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"ChatOptions.d.ts","sourceRoot":"","sources":["../../src/chat/ChatOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,MAAM,WAAW,WAAW;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,CAAC;IACtC,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;IAC1C,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IACrD,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE;QAAE,IAAI,EAAE,aAAa,GAAG,MAAM,CAAA;KAAE,CAAC;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAClE,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACrE,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;CACxF"}

package/dist/chat/ChatResponse.d.ts

@@ -1,4 +1,5 @@
 import { Usage } from "../providers/Provider.js";
+import { ToolCall } from "./Tool.js";
 /**
  * Enhanced string that includes token usage metadata.
  * Behaves like a regular string but has .usage and .input_tokens etc.
@@ -8,7 +9,8 @@ export declare class ChatResponseString extends String {
     readonly model: string;
     readonly provider: string;
     readonly reasoning?: string | null | undefined;
-    constructor(content: string, usage: Usage, model: string, provider: string, reasoning?: string | null | undefined);
+    readonly tool_calls?: ToolCall[] | undefined;
+    constructor(content: string, usage: Usage, model: string, provider: string, reasoning?: string | null | undefined, tool_calls?: ToolCall[] | undefined);
     get input_tokens(): number;
     get output_tokens(): number;
     get total_tokens(): number;
@@ -19,6 +21,10 @@ export declare class ChatResponseString extends String {
     get content(): string;
     get model_id(): string;
     toString(): string;
+    /**
+     * Return a new ChatResponseString with modified content but preserved metadata.
+     */
+    withContent(newContent: string): ChatResponseString;
     /**
      * Attempt to parse the content as JSON.
      * Returns the parsed object or null if parsing fails.

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

@@ -1 +1 @@
-{"version":3,"file":"ChatResponse.d.ts","sourceRoot":"","sources":["../../src/chat/ChatResponse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAEjD;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,MAAM;aAG1B,KAAK,EAAE,KAAK;aACZ,KAAK,EAAE,MAAM;aACb,QAAQ,EAAE,MAAM;aAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;gBAJzC,OAAO,EAAE,MAAM,EACC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,YAAA;IAK3C,IAAI,YAAY,WAAsC;IACtD,IAAI,aAAa,WAAuC;IACxD,IAAI,YAAY,WAAsC;IACtD,IAAI,aAAa,uBAAuC;IACxD,IAAI,IAAI,uBAA8B;IACtC,IAAI,UAAU,uBAAoC;IAClD,IAAI,WAAW,uBAAqC;IAEpD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,QAAQ;IAIR;;;OAGG;IACH,IAAI,MAAM,IAAI,GAAG,CAMhB;CACF"}
+{"version":3,"file":"ChatResponse.d.ts","sourceRoot":"","sources":["../../src/chat/ChatResponse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,MAAM;aAG1B,KAAK,EAAE,KAAK;aACZ,KAAK,EAAE,MAAM;aACb,QAAQ,EAAE,MAAM;aAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;aACzB,UAAU,CAAC,EAAE,QAAQ,EAAE;gBALvC,OAAO,EAAE,MAAM,EACC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,YAAA,EACzB,UAAU,CAAC,EAAE,QAAQ,EAAE,YAAA;IAKzC,IAAI,YAAY,WAAsC;IACtD,IAAI,aAAa,WAAuC;IACxD,IAAI,YAAY,WAAsC;IACtD,IAAI,aAAa,uBAAuC;IACxD,IAAI,IAAI,uBAA8B;IACtC,IAAI,UAAU,uBAAoC;IAClD,IAAI,WAAW,uBAAqC;IAEpD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,QAAQ;IAIR;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB;IAWnD;;;OAGG;IACH,IAAI,MAAM,IAAI,GAAG,CAMhB;CACF"}

package/dist/chat/ChatResponse.js

@@ -7,12 +7,14 @@ export class ChatResponseString extends String {
     model;
     provider;
     reasoning;
-    constructor(content, usage, model, provider, reasoning) {
+    tool_calls;
+    constructor(content, usage, model, provider, reasoning, tool_calls) {
         super(content);
         this.usage = usage;
         this.model = model;
         this.provider = provider;
         this.reasoning = reasoning;
+        this.tool_calls = tool_calls;
     }
     get input_tokens() { return this.usage.input_tokens; }
     get output_tokens() { return this.usage.output_tokens; }
@@ -30,6 +32,12 @@ export class ChatResponseString extends String {
     toString() {
         return this.valueOf();
     }
+    /**
+     * Return a new ChatResponseString with modified content but preserved metadata.
+     */
+    withContent(newContent) {
+        return new ChatResponseString(newContent, this.usage, this.model, this.provider, this.reasoning, this.tool_calls);
+    }
     /**
      * Attempt to parse the content as JSON.
      * Returns the parsed object or null if parsing fails.

package/dist/chat/ChatStream.d.ts

@@ -11,7 +11,8 @@ export declare class ChatStream {
     private readonly model;
     private readonly options;
     private messages;
-    constructor(provider: Provider, model: string, options?: ChatOptions, messages?: Message[]);
+    private systemMessages;
+    constructor(provider: Provider, model: string, options?: ChatOptions, messages?: Message[], systemMessages?: Message[]);
     /**
      * Read-only access to message history
      */
@@ -21,5 +22,18 @@ export declare class ChatStream {
      * @param content The user's question.
      */
     create(content: string): Stream<ChatChunk>;
+    /**
+     * Check if tool execution should proceed based on the current mode.
+     */
+    private shouldExecuteTools;
+    /**
+     * Request user confirmation for a tool call in "confirm" mode.
+     * Returns true if approved, false if rejected.
+     */
+    private requestToolConfirmation;
+    /**
+     * Execute a single tool call and return the result message.
+     */
+    private executeToolCall;
 }
 //# sourceMappingURL=ChatStream.d.ts.map