@node-llm/core 1.5.4 → 1.6.1

package/README.md

@@ -1,6 +1,6 @@
 <p align="left">
   <a href="https://node-llm.eshaiju.com/">
-    <img src="docs/assets/images/logo.jpg" alt="NodeLLM logo" width="300" />
+    <img src="https://node-llm.eshaiju.com/assets/images/logo.jpg" alt="NodeLLM logo" width="300" />
   </a>
 </p>
 
@@ -44,9 +44,10 @@ Integrating multiple LLM providers often means juggling different SDKs, API styl
 NodeLLM represents a clear architectural boundary between your system and LLM vendors.
 
 NodeLLM is **NOT**:
- - A wrapper around a single provider SDK (like `openai` or `@google/generative-ai`)
- - A prompt-engineering framework
- - An agent playground or experimental toy
+
+- A wrapper around a single provider SDK (like `openai` or `@google/generative-ai`)
+- A prompt-engineering framework
+- An agent playground or experimental toy
 
 ---
 
@@ -57,6 +58,7 @@ Direct integrations often become tightly coupled to specific providers, making i
 NodeLLM helps solve **architectural problems**, not just provide API access. It serves as the core integration layer for LLMs in the Node.js ecosystem.
 
 ### Strategic Goals
+
 - **Provider Isolation**: Decouple your services from vendor SDKs.
 - **Production-Ready**: Native support for streaming, automatic retries, and unified error handling.
 - **Predictable API**: Consistent behavior for Tools, Vision, and Structured Outputs across all models, **now including full parity for streaming**.
@@ -68,16 +70,14 @@ NodeLLM helps solve **architectural problems**, not just provide API access. It
 ```ts
 import { NodeLLM } from "@node-llm/core";
 
-// 1. Configure once (Safe for ESM + dotenv race conditions)
-NodeLLM.configure({ provider: "openai" });
+// 1. Zero-Config (NodeLLM automatically reads NODELLM_PROVIDER and API keys)
+const chat = NodeLLM.chat("gpt-4o");
 
 // 2. Chat (High-level request/response)
-const chat = NodeLLM.chat("gpt-4o");
 const response = await chat.ask("Explain event-driven architecture");
 console.log(response.content);
 
 // 3. Streaming (Standard AsyncIterator)
-// NOW with full support for Tools, Vision, and Schemas!
 for await (const chunk of chat.stream("Explain event-driven architecture")) {
   process.stdout.write(chunk.content);
 }
@@ -85,14 +85,9 @@ for await (const chunk of chat.stream("Explain event-driven architecture")) {
 
 ### 🎯 Real-World Example: Brand Perception Checker
 
-Built with NodeLLM - Multi-provider AI analysis, tool calling, and structured outputs working together:
-
-<p align="center">
-  <img src="assets/brand-perception-checker.png" alt="Brand Perception Checker" width="800" />
-</p>
-
-**[View Example →](examples/brand-perception-checker/)**
+Built with NodeLLM - Multi-provider AI analysis, tool calling, and structured outputs working together.
 
+**[View Example →](https://github.com/node-llm/node-llm/tree/main/examples/applications/brand-perception-checker)**
 
 ---
 
@@ -102,16 +97,16 @@ NodeLLM provides a flexible, **lazy-initialized** configuration system designed
 
 ```ts
 // Recommended for multi-provider pipelines
-NodeLLM.configure({
+const llm = createLLM({
   openaiApiKey: process.env.OPENAI_API_KEY,
   anthropicApiKey: process.env.ANTHROPIC_API_KEY,
-  ollamaApiBase: process.env.OLLAMA_API_BASE,
+  ollamaApiBase: process.env.OLLAMA_API_BASE
 });
 
 // Support for Custom Endpoints (e.g., Azure or LocalAI)
-NodeLLM.configure({
+const llm = createLLM({
   openaiApiKey: process.env.AZURE_KEY,
-  openaiApiBase: "https://your-resource.openai.azure.com/openai/deployments/...",
+  openaiApiBase: "https://your-resource.openai.azure.com/openai/deployments/..."
 });
 ```
 
@@ -124,21 +119,29 @@ NodeLLM.configure({
 ## 🔮 Capabilities
 
 ### 💬 Unified Chat
+
 Stop rewriting code for every provider. `NodeLLM` normalizes inputs and outputs into a single, predictable mental model.
+
 ```ts
-const chat = NodeLLM.chat(); // Defaults to GPT-4o
+import { NodeLLM } from "@node-llm/core";
+
+// Uses NODELLM_PROVIDER from environment (defaults to GPT-4o)
+const chat = NodeLLM.chat();
 await chat.ask("Hello world");
 ```
 
 ### 👁️ Smart Vision & Files
+
 Pass images, PDFs, or audio files directly to **both `ask()` and `stream()`**. We handle the heavy lifting: fetching remote URLs, base64 encoding, and MIME type mapping.
+
 ```ts
-await chat.ask("Analyze this interface", { 
-  files: ["./screenshot.png", "https://example.com/spec.pdf"] 
+await chat.ask("Analyze this interface", {
+  files: ["./screenshot.png", "https://example.com/spec.pdf"]
 });
 ```
 
 ### 🛠️ Auto-Executing Tools
+
 Define tools once;`NodeLLM` manages the recursive execution loop for you, keeping your controller logic clean. **Works seamlessly with both regular chat and streaming!**
 
 ```ts
@@ -150,8 +153,8 @@ class WeatherTool extends Tool {
   description = "Get current weather";
   schema = z.object({ location: z.string() });
 
-  async execute({ location }) { 
-    return `Sunny in ${location}`; 
+  async execute({ location }) {
+    return `Sunny in ${location}`;
   }
 }
 
@@ -159,12 +162,15 @@ class WeatherTool extends Tool {
 await chat.withTool(WeatherTool).ask("What's the weather in Tokyo?");
 
 // Lifecycle Hooks for Error & Flow Control
-chat.onToolCallError((call, err) => "STOP"); 
+chat.onToolCallError((call, err) => "STOP");
 ```
+
 **[Full Tool Calling Guide →](https://node-llm.eshaiju.com/core-features/tool-calling)**
 
 ### 🔍 Comprehensive Debug Logging
+
 Enable detailed logging for all API requests and responses across every feature and provider:
+
 ```ts
 // Set environment variable
 process.env.NODELLM_DEBUG = "true";
@@ -175,10 +181,13 @@ process.env.NODELLM_DEBUG = "true";
 // [NodeLLM] [OpenAI] Response: 200 OK
 // { "id": "chatcmpl-123", ... }
 ```
+
 **Covers:** Chat, Streaming, Images, Embeddings, Transcription, Moderation - across all providers!
 
 ### ✨ Structured Output
+
 Get type-safe, validated JSON back using **Zod** schemas.
+
 ```ts
 import { z } from "@node-llm/core";
 const Product = z.object({ name: z.string(), price: z.number() });
@@ -188,27 +197,50 @@ console.log(res.parsed.name); // Full type-safety
 ```
 
 ### 🎨 Image Generation
+
 ```ts
 await NodeLLM.paint("A cyberpunk city in rain");
 ```
 
 ### 🎤 Audio Transcription
+
 ```ts
 await NodeLLM.transcribe("meeting-recording.wav");
 ```
 
+### 💾 Persistence Layer
+
+Automatically track chat history, tool executions, and API metrics with **@node-llm/orm**.
+
+```ts
+import { createChat } from "@node-llm/orm/prisma";
+
+// Chat state is automatically saved to your database (Postgres/MySQL/SQLite)
+const chat = await createChat(prisma, llm, { model: "gpt-4o" });
+
+await chat.ask("Hello");
+// -> Saves User Message
+// -> Saves Assistant Response
+// -> Tracks Token Usage & Cost
+// -> Logs Tool Calls & Results
+```
+
 ### ⚡ Scoped Parallelism
+
 Run multiple providers in parallel safely without global configuration side effects using isolated contexts.
+
 ```ts
 const [gpt, claude] = await Promise.all([
   // Each call branch off into its own isolated context
   NodeLLM.withProvider("openai").chat("gpt-4o").ask(prompt),
-  NodeLLM.withProvider("anthropic").chat("claude-3-5-sonnet").ask(prompt),
+  NodeLLM.withProvider("anthropic").chat("claude-3-5-sonnet").ask(prompt)
 ]);
 ```
 
 ### 🧠 Deep Reasoning
+
 Direct access to the thought process of models like **DeepSeek R1** or **OpenAI o1/o3** using the `.reasoning` field.
+
 ```ts
 const res = await NodeLLM.chat("deepseek-reasoner").ask("Solve this logical puzzle");
 console.log(res.reasoning); // Chain-of-thought
@@ -218,27 +250,27 @@ console.log(res.reasoning); // Chain-of-thought
 
 ## 🚀 Why use this over official SDKs?
 
-| Feature | NodeLLM | Official SDKs | Architectural Impact |
-| :--- | :--- | :--- | :--- |
-| **Provider Logic** | Transparently Handled | Exposed to your code | **Low Coupling** |
-| **Streaming** | Standard `AsyncIterator` | Vendor-specific Events | **Predictable Data Flow** |
-| **Streaming + Tools** | Automated Execution | Manual implementation | **Seamless UX** |
-| **Tool Loops** | Automated Recursion | Manual implementation | **Reduced Boilerplate** |
-| **Files/Vision** | Intelligent Path/URL handling | Base64/Buffer management | **Cleaner Service Layer** |
-| **Configuration** | Centralized & Global | Per-instance initialization | **Easier Lifecycle Mgmt** |
+| Feature               | NodeLLM                       | Official SDKs               | Architectural Impact      |
+| :-------------------- | :---------------------------- | :-------------------------- | :------------------------ |
+| **Provider Logic**    | Transparently Handled         | Exposed to your code        | **Low Coupling**          |
+| **Streaming**         | Standard `AsyncIterator`      | Vendor-specific Events      | **Predictable Data Flow** |
+| **Streaming + Tools** | Automated Execution           | Manual implementation       | **Seamless UX**           |
+| **Tool Loops**        | Automated Recursion           | Manual implementation       | **Reduced Boilerplate**   |
+| **Files/Vision**      | Intelligent Path/URL handling | Base64/Buffer management    | **Cleaner Service Layer** |
+| **Configuration**     | Centralized & Global          | Per-instance initialization | **Easier Lifecycle Mgmt** |
 
 ---
 
 ## 📋 Supported Providers
 
-| 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/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** |
-| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openrouter.svg" height="18"> **OpenRouter** | **Aggregator**, Chat, Streaming, Tools, Vision, Embeddings, **Reasoning** |
-| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/ollama.svg" height="18"> **Ollama** | **Local Inference**, Chat, Streaming, Tools, Vision, Embeddings |
+| 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/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**                             |
+| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openrouter.svg" height="18"> **OpenRouter**    | **Aggregator**, Chat, Streaming, Tools, Vision, Embeddings, **Reasoning**        |
+| <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/ollama.svg" height="18"> **Ollama**            | **Local Inference**, Chat, Streaming, Tools, Vision, Embeddings                  |
 
 ---
 
@@ -251,7 +283,9 @@ npm install @node-llm/core
 **[View Full Documentation ↗](https://node-llm.eshaiju.com/)**
 
 ### 🍿 Try the Live Demo
+
 Want to see it in action? Run this in your terminal:
+
 ```bash
 git clone https://github.com/node-llm/node-llm.git
 cd node-llm
@@ -259,7 +293,6 @@ npm install
 npm run demo
 ```
 
-
 ---
 
 ## 🤝 Contributing

package/dist/aliases.d.ts

@@ -375,6 +375,10 @@ declare const _default: {
         readonly openai: "gpt-5.2-chat-latest";
         readonly openrouter: "openai/gpt-5.2-chat-latest";
     };
+    readonly "gpt-5.2-codex": {
+        readonly openai: "gpt-5.2-codex";
+        readonly openrouter: "openai/gpt-5.2-codex";
+    };
     readonly "gpt-5.2-pro": {
         readonly openai: "gpt-5.2-pro";
         readonly openrouter: "openai/gpt-5.2-pro";

package/dist/aliases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aliases.d.ts","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,wBA+mBW"}
+{"version":3,"file":"aliases.d.ts","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,wBAmnBW"}

package/dist/aliases.js

@@ -375,6 +375,10 @@ export default {
         "openai": "gpt-5.2-chat-latest",
         "openrouter": "openai/gpt-5.2-chat-latest"
     },
+    "gpt-5.2-codex": {
+        "openai": "gpt-5.2-codex",
+        "openrouter": "openai/gpt-5.2-codex"
+    },
     "gpt-5.2-pro": {
         "openai": "gpt-5.2-pro",
         "openrouter": "openai/gpt-5.2-pro"

package/dist/chat/Chat.d.ts

@@ -44,13 +44,13 @@ export declare class Chat {
      */
     withTool(tool: ToolResolvable): this;
     /**
-   * Add multiple tools to the chat session.
-   * Supports passing Tool classes (which will be instantiated) or instances.
-   * Can replace existing tools if options.replace is true.
-   *
-   * @example
-   * chat.withTools([WeatherTool, new CalculatorTool()], { replace: true });
-   */
+     * Add multiple tools to the chat session.
+     * Supports passing Tool classes (which will be instantiated) or instances.
+     * Can replace existing tools if options.replace is true.
+     *
+     * @example
+     * chat.withTools([WeatherTool, new CalculatorTool()], { replace: true });
+     */
     withTools(tools: ToolResolvable[], options?: {
         replace?: boolean;
     }): this;
@@ -68,6 +68,17 @@ export declare class Chat {
     withSystemPrompt(instruction: string, options?: {
         replace?: boolean;
     }): this;
+    /**
+     * Alias for withInstructions
+     */
+    system(instruction: string, options?: {
+        replace?: boolean;
+    }): this;
+    /**
+     * Add a message manually to the chat history.
+     * Useful for rehydrating sessions from a database.
+     */
+    add(role: "user" | "assistant" | "system" | "developer", content: string): this;
     /**
      * Set the temperature for the chat session.
      * Controls randomness: 0.0 (deterministic) to 1.0 (creative).
@@ -83,31 +94,31 @@ export declare class Chat {
      */
     withRequestOptions(options: {
         headers?: Record<string, string>;
-        responseFormat?: any;
+        responseFormat?: unknown;
     }): this;
     /**
      * Set provider-specific parameters.
      * These will be merged into the final request payload.
      */
-    withParams(params: Record<string, any>): this;
+    withParams(params: Record<string, unknown>): this;
     /**
      * Enforce a specific schema for the output.
      * Can accept a Schema object or a Zod schema/JSON Schema directly.
      */
-    withSchema(schema: Schema | z.ZodType<any> | Record<string, any> | null): this;
+    withSchema(schema: Schema | z.ZodType<unknown> | Record<string, unknown> | null): this;
     onNewMessage(handler: () => void): this;
     onEndMessage(handler: (message: ChatResponseString) => void): this;
-    onToolCall(handler: (toolCall: any) => void): this;
-    onToolResult(handler: (result: any) => void): this;
+    onToolCall(handler: (toolCall: unknown) => void): this;
+    onToolResult(handler: (result: unknown) => void): this;
     /**
      * Called when a tool call starts.
      */
-    onToolCallStart(handler: (toolCall: any) => void): this;
+    onToolCallStart(handler: (toolCall: unknown) => void): this;
     /**
      * Called when a tool call ends successfully.
      */
-    onToolCallEnd(handler: (toolCall: any, result: any) => void): this;
-    onToolCallError(handler: (toolCall: any, error: Error) => 'STOP' | 'CONTINUE' | void | Promise<'STOP' | 'CONTINUE' | void>): this;
+    onToolCallEnd(handler: (toolCall: unknown, result: unknown) => void): this;
+    onToolCallError(handler: (toolCall: unknown, error: Error) => "STOP" | "CONTINUE" | "RETRY" | void | Promise<"STOP" | "CONTINUE" | "RETRY" | void>): this;
     /**
      * Set the tool execution mode.
      * - "auto": (Default) Automatically execute all tool calls.
@@ -119,7 +130,7 @@ export declare class Chat {
      * 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;
+    onConfirmToolCall(handler: (toolCall: unknown) => Promise<boolean> | boolean): this;
     /**
      * Add a hook to process messages before sending to the LLM.
      * Useful for PII detection, redaction, and input moderation.
@@ -133,7 +144,7 @@ export declare class Chat {
     /**
      * Ask the model a question
      */
-    ask(content: string | any[], options?: AskOptions): Promise<ChatResponseString>;
+    ask(content: string | ContentPart[], options?: AskOptions): Promise<ChatResponseString>;
     /**
      * Streams the model's response to a user question.
      */

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

@@ -65,11 +65,19 @@ export class Chat {
                 acc.output_tokens += msg.usage.output_tokens;
                 acc.total_tokens += msg.usage.total_tokens;
                 acc.cached_tokens = (acc.cached_tokens ?? 0) + (msg.usage.cached_tokens ?? 0);
-                acc.cache_creation_tokens = (acc.cache_creation_tokens ?? 0) + (msg.usage.cache_creation_tokens ?? 0);
+                acc.cache_creation_tokens =
+                    (acc.cache_creation_tokens ?? 0) + (msg.usage.cache_creation_tokens ?? 0);
                 acc.cost = (acc.cost ?? 0) + (msg.usage.cost ?? 0);
             }
             return acc;
-        }, { input_tokens: 0, output_tokens: 0, total_tokens: 0, cached_tokens: 0, cache_creation_tokens: 0, cost: 0 });
+        }, {
+            input_tokens: 0,
+            output_tokens: 0,
+            total_tokens: 0,
+            cached_tokens: 0,
+            cache_creation_tokens: 0,
+            cost: 0
+        });
     }
     /**
      * Add a tool to the chat session (fluent API)
@@ -79,13 +87,13 @@ export class Chat {
         return this.withTools([tool]);
     }
     /**
-   * Add multiple tools to the chat session.
-   * Supports passing Tool classes (which will be instantiated) or instances.
-   * Can replace existing tools if options.replace is true.
-   *
-   * @example
-   * chat.withTools([WeatherTool, new CalculatorTool()], { replace: true });
-   */
+     * Add multiple tools to the chat session.
+     * Supports passing Tool classes (which will be instantiated) or instances.
+     * Can replace existing tools if options.replace is true.
+     *
+     * @example
+     * chat.withTools([WeatherTool, new CalculatorTool()], { replace: true });
+     */
     withTools(tools, options) {
         if (options?.replace) {
             this.options.tools = [];
@@ -120,6 +128,25 @@ export class Chat {
     withSystemPrompt(instruction, options) {
         return this.withInstructions(instruction, options);
     }
+    /**
+     * Alias for withInstructions
+     */
+    system(instruction, options) {
+        return this.withInstructions(instruction, options);
+    }
+    /**
+     * Add a message manually to the chat history.
+     * Useful for rehydrating sessions from a database.
+     */
+    add(role, content) {
+        if (role === "system" || role === "developer") {
+            this.systemMessages.push({ role, content });
+        }
+        else {
+            this.messages.push({ role, content });
+        }
+        return this;
+    }
     /**
      * Set the temperature for the chat session.
      * Controls randomness: 0.0 (deterministic) to 1.0 (creative).
@@ -260,7 +287,7 @@ export class Chat {
         }
         this.messages.push({
             role: "user",
-            content: messageContent,
+            content: messageContent
         });
         // Process Schema/Structured Output
         let responseFormat = this.options.responseFormat;
@@ -273,7 +300,7 @@ export class Chat {
                     name: this.options.schema.definition.name,
                     description: this.options.schema.definition.description,
                     strict: this.options.schema.definition.strict ?? true,
-                    schema: jsonSchema,
+                    schema: jsonSchema
                 }
             };
         }
@@ -287,7 +314,7 @@ export class Chat {
             response_format: responseFormat, // Pass to provider
             requestTimeout: options?.requestTimeout ?? this.options.requestTimeout ?? config.requestTimeout,
             signal: options?.signal,
-            ...this.options.params,
+            ...this.options.params
         };
         // --- Content Policy Hooks (Input) ---
         if (this.options.onBeforeRequest) {
@@ -298,7 +325,7 @@ export class Chat {
                 executeOptions.messages = result;
             }
         }
-        let totalUsage = { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
+        const totalUsage = { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
         const trackUsage = (u) => {
             if (u) {
                 totalUsage.input_tokens += u.input_tokens;
@@ -327,9 +354,9 @@ export class Chat {
         }
         this.messages.push({
             role: "assistant",
-            content: assistantMessage || null,
+            content: assistantMessage?.toString() || null,
             tool_calls: response.tool_calls,
-            usage: response.usage,
+            usage: response.usage
         });
         if (this.options.onEndMessage && (!response.tool_calls || response.tool_calls.length === 0)) {
             this.options.onEndMessage(assistantMessage);
@@ -350,37 +377,42 @@ export class Chat {
                 if (this.options.toolExecution === ToolExecutionMode.CONFIRM) {
                     const approved = await ToolHandler.requestToolConfirmation(toolCall, this.options.onConfirmToolCall);
                     if (!approved) {
-                        this.messages.push({
-                            role: "tool",
-                            tool_call_id: toolCall.id,
-                            content: "Action cancelled by user.",
-                        });
+                        this.messages.push(this.provider.formatToolResultMessage(toolCall.id, "Action cancelled by user."));
                         continue;
                     }
                 }
                 try {
                     const toolResult = await ToolHandler.execute(toolCall, this.options.tools, this.options.onToolCallStart, this.options.onToolCallEnd);
-                    this.messages.push(toolResult);
+                    this.messages.push(this.provider.formatToolResultMessage(toolResult.tool_call_id, toolResult.content));
                 }
                 catch (error) {
-                    const directive = await this.options.onToolCallError?.(toolCall, error);
-                    if (directive === 'STOP') {
-                        throw error;
+                    let currentError = error;
+                    const directive = await this.options.onToolCallError?.(toolCall, currentError);
+                    if (directive === "STOP") {
+                        throw currentError;
+                    }
+                    if (directive === "RETRY") {
+                        try {
+                            const toolResult = await ToolHandler.execute(toolCall, this.options.tools, this.options.onToolCallStart, this.options.onToolCallEnd);
+                            this.messages.push(this.provider.formatToolResultMessage(toolResult.tool_call_id, toolResult.content));
+                            continue;
+                        }
+                        catch (retryError) {
+                            // If retry also fails, fall through to default logic
+                            currentError = retryError;
+                        }
                     }
-                    this.messages.push({
-                        role: "tool",
-                        tool_call_id: toolCall.id,
-                        content: `Fatal error executing tool '${toolCall.function.name}': ${error.message}`,
-                    });
-                    if (directive === 'CONTINUE') {
+                    this.messages.push(this.provider.formatToolResultMessage(toolCall.id, `Fatal error executing tool '${toolCall.function.name}': ${currentError.message}`, { isError: true }));
+                    if (directive === "CONTINUE") {
                         continue;
                     }
                     // Default short-circuit logic
-                    const isFatal = error.fatal === true || error.status === 401 || error.status === 403;
+                    const errorObj = currentError;
+                    const isFatal = errorObj.fatal === true || errorObj.status === 401 || errorObj.status === 403;
                     if (isFatal) {
-                        throw error;
+                        throw currentError;
                     }
-                    logger.error(`Tool execution failed for '${toolCall.function.name}':`, error);
+                    logger.error(`Tool execution failed for '${toolCall.function.name}':`, currentError);
                 }
             }
             response = await this.executor.executeChat({
@@ -393,7 +425,7 @@ export class Chat {
                 response_format: responseFormat,
                 requestTimeout: options?.requestTimeout ?? this.options.requestTimeout ?? config.requestTimeout,
                 signal: options?.signal,
-                ...this.options.params,
+                ...this.options.params
             });
             trackUsage(response.usage);
             assistantMessage = new ChatResponseString(response.content ?? "", response.usage ?? { input_tokens: 0, output_tokens: 0, total_tokens: 0 }, this.model, this.provider.id, response.reasoning);
@@ -406,15 +438,15 @@ export class Chat {
             }
             this.messages.push({
                 role: "assistant",
-                content: assistantMessage || null,
+                content: assistantMessage?.toString() || null,
                 tool_calls: response.tool_calls,
-                usage: response.usage,
+                usage: response.usage
             });
             if (this.options.onEndMessage && (!response.tool_calls || response.tool_calls.length === 0)) {
                 this.options.onEndMessage(assistantMessage);
             }
         }
-        // For the final return, we might want to aggregate reasoning too if it happened in multiple turns? 
+        // For the final return, we might want to aggregate reasoning too if it happened in multiple turns?
         // Usually reasoning only happens once or we just want the last one.
         return new ChatResponseString(assistantMessage.toString() || "", totalUsage, this.model, this.provider.id, assistantMessage.reasoning, response.tool_calls);
     }
@@ -449,17 +481,18 @@ export class Chat {
         if (typeof toolInstance.toLLMTool === "function") {
             return toolInstance.toLLMTool();
         }
-        if (!toolInstance.function || !toolInstance.function.name) {
+        const toolObj = toolInstance;
+        if (!toolObj.function || !toolObj.function.name) {
             // 1. Validate structure
             throw new ConfigurationError(`[NodeLLM] Tool validation failed: 'function.name' is required for raw tool objects.`);
         }
-        if (toolInstance.type !== 'function') {
+        if (toolObj.type !== "function") {
             // 2. Ensure 'type: function' exists (standardize for providers)
-            toolInstance.type = 'function';
+            toolObj.type = "function";
         }
-        if (typeof toolInstance.handler !== 'function') {
+        if (typeof toolObj.handler !== "function") {
             // 3. Validate handler existence
-            throw new ConfigurationError(`[NodeLLM] Tool validation failed: Tool '${toolInstance.function.name}' must have a 'handler' function. (Note: Only Tool subclasses use 'execute()')`);
+            throw new ConfigurationError(`[NodeLLM] Tool validation failed: Tool '${toolObj.function.name}' must have a 'handler' function. (Note: Only Tool subclasses use 'execute()')`);
         }
         return toolInstance;
     }