@node-llm/core 1.5.0 → 1.5.2

package/dist/chat/Chat.d.ts

@@ -1,8 +1,9 @@
 import { Message } from "./Message.js";
+import { ContentPart } from "./Content.js";
 import { ChatOptions } from "./ChatOptions.js";
 import { Provider, Usage, ChatChunk } from "../providers/Provider.js";
 import { Stream } from "../streaming/Stream.js";
-import { Tool } from "./Tool.js";
+import { ToolResolvable } from "./Tool.js";
 import { Schema } from "../schema/Schema.js";
 import { z } from "zod";
 import { ToolExecutionMode } from "../constants.js";
@@ -40,7 +41,7 @@ export declare class Chat {
      * Add a tool to the chat session (fluent API)
      * Supports passing a tool instance or a tool class (which will be instantiated).
      */
-    withTool(tool: any): this;
+    withTool(tool: ToolResolvable): this;
     /**
    * Add multiple tools to the chat session.
    * Supports passing Tool classes (which will be instantiated) or instances.
@@ -49,9 +50,7 @@ export declare class Chat {
    * @example
    * chat.withTools([WeatherTool, new CalculatorTool()], { replace: true });
    */
-    withTools(tools: (Tool | {
-        new (): Tool;
-    } | any)[], options?: {
+    withTools(tools: ToolResolvable[], options?: {
         replace?: boolean;
     }): this;
     /**
@@ -107,10 +106,7 @@ export declare class Chat {
      * 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;
+    onToolCallError(handler: (toolCall: any, error: Error) => 'STOP' | 'CONTINUE' | void | Promise<'STOP' | 'CONTINUE' | void>): this;
     /**
      * Set the tool execution mode.
      * - "auto": (Default) Automatically execute all tool calls.
@@ -140,19 +136,10 @@ 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;
+    stream(content: string | ContentPart[], options?: AskOptions): Stream<ChatChunk>;
     /**
-     * Execute a single tool call and return the result message.
+     * Normalizes a ToolResolvable into a ToolDefinition.
      */
-    private executeToolCall;
+    private normalizeTool;
 }
 //# 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

@@ -1,4 +1,5 @@
 import { FileLoader } from "../utils/FileLoader.js";
+import { isBinaryContent, formatMultimodalContent } from "./Content.js";
 import { Executor } from "../executor/Executor.js";
 import { ChatStream } from "./ChatStream.js";
 import { Schema } from "../schema/Schema.js";
@@ -6,6 +7,9 @@ import { toJsonSchema } from "../schema/to-json-schema.js";
 import { z } from "zod";
 import { config } from "../config.js";
 import { ToolExecutionMode } from "../constants.js";
+import { ConfigurationError } from "../errors/index.js";
+import { ChatValidator } from "./Validation.js";
+import { ToolHandler } from "./ToolHandler.js";
 import { ChatResponseString } from "./ChatResponse.js";
 export class Chat {
     provider;
@@ -35,6 +39,11 @@ export class Chat {
         if (!this.options.toolExecution) {
             this.options.toolExecution = config.toolExecution || ToolExecutionMode.AUTO;
         }
+        if (options.tools) {
+            const toolList = options.tools;
+            this.options.tools = []; // Clear and re-add via normalized method
+            this.withTools(toolList);
+        }
     }
     /**
      * Read-only access to message history
@@ -84,27 +93,9 @@ export class Chat {
             this.options.tools = [];
         }
         for (const tool of tools) {
-            let toolInstance;
-            // Handle class constructor
-            if (typeof tool === "function") {
-                try {
-                    toolInstance = new tool();
-                }
-                catch (e) {
-                    console.error(`[NodeLLM] Failed to instantiate tool class: ${tool.name}`, e);
-                    continue;
-                }
-            }
-            else {
-                toolInstance = tool;
-            }
-            // Normalized to standard ToolDefinition interface if it's a Tool class instance
-            if (toolInstance && typeof toolInstance.toLLMTool === "function") {
-                this.options.tools.push(toolInstance.toLLMTool());
-            }
-            else {
-                // Fallback for legacy raw tool objects (defined as objects with type: 'function')
-                this.options.tools.push(toolInstance);
+            const normalized = this.normalizeTool(tool);
+            if (normalized) {
+                this.options.tools.push(normalized);
             }
         }
         return this;
@@ -213,9 +204,6 @@ export class Chat {
         this.options.onToolCallEnd = handler;
         return this;
     }
-    /**
-     * Called when a tool call fails.
-     */
     onToolCallError(handler) {
         this.options.onToolCallError = handler;
         return this;
@@ -261,41 +249,13 @@ export class Chat {
         let messageContent = content;
         const files = [...(options?.images ?? []), ...(options?.files ?? [])];
         if (files.length > 0) {
-            const processedFiles = await Promise.all(files.map(f => FileLoader.load(f)));
-            const hasBinary = processedFiles.some(p => p.type === "image_url" || p.type === "input_audio" || p.type === "video_url");
-            if (hasBinary && !this.options.assumeModelExists && this.provider.capabilities && !this.provider.capabilities.supportsVision(this.model)) {
-                throw new Error(`Model ${this.model} does not support vision/binary files.`);
-            }
-            if (hasBinary && this.options.assumeModelExists) {
-                console.warn(`[NodeLLM] Skipping vision capability validation for model ${this.model}`);
-            }
-            // Separate text files from binary files
-            const textFiles = processedFiles.filter(p => p.type === "text");
-            const binaryFiles = processedFiles.filter(p => p.type !== "text");
-            // Concatenate text files into the main content
-            let fullText = content;
-            if (textFiles.length > 0) {
-                fullText += "\n" + textFiles.map(f => f.text).join("\n");
-            }
-            // If we have binary files, create multimodal content
-            if (binaryFiles.length > 0) {
-                messageContent = [
-                    { type: "text", text: fullText },
-                    ...binaryFiles
-                ];
-            }
-            else {
-                // Only text files, keep as string
-                messageContent = fullText;
-            }
+            const processedFiles = await Promise.all(files.map((f) => FileLoader.load(f)));
+            const hasBinary = processedFiles.some(isBinaryContent);
+            ChatValidator.validateVision(this.provider, this.model, hasBinary, this.options);
+            messageContent = formatMultimodalContent(content, processedFiles);
         }
         if (this.options.tools && this.options.tools.length > 0) {
-            if (!this.options.assumeModelExists && this.provider.capabilities && !this.provider.capabilities.supportsTools(this.model)) {
-                throw new Error(`Model ${this.model} does not support tool calling.`);
-            }
-            if (this.options.assumeModelExists) {
-                console.warn(`[NodeLLM] Skipping tool capability validation for model ${this.model}`);
-            }
+            ChatValidator.validateTools(this.provider, this.model, true, this.options);
         }
         this.messages.push({
             role: "user",
@@ -304,12 +264,7 @@ export class Chat {
         // Process Schema/Structured Output
         let responseFormat = this.options.responseFormat;
         if (this.options.schema) {
-            if (!this.options.assumeModelExists && this.provider.capabilities && !this.provider.capabilities.supportsStructuredOutput(this.model)) {
-                throw new Error(`Model ${this.model} does not support structured output.`);
-            }
-            if (this.options.assumeModelExists) {
-                console.warn(`[NodeLLM] Skipping structured output capability validation for model ${this.model}`);
-            }
+            ChatValidator.validateStructuredOutput(this.provider, this.model, true, this.options);
             const jsonSchema = toJsonSchema(this.options.schema.definition.schema);
             responseFormat = {
                 type: "json_schema",
@@ -381,7 +336,7 @@ export class Chat {
         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)) {
+            if (!ToolHandler.shouldExecuteTools(response.tool_calls, this.options.toolExecution)) {
                 break;
             }
             stepCount++;
@@ -389,9 +344,9 @@ export class Chat {
                 throw new Error(`[NodeLLM] Maximum tool execution calls (${maxToolCalls}) exceeded.`);
             }
             for (const toolCall of response.tool_calls) {
-                // Confirm mode: request approval
+                // Human-in-the-loop: check for approval
                 if (this.options.toolExecution === ToolExecutionMode.CONFIRM) {
-                    const approved = await this.requestToolConfirmation(toolCall, this.options.onConfirmToolCall);
+                    const approved = await ToolHandler.requestToolConfirmation(toolCall, this.options.onConfirmToolCall);
                     if (!approved) {
                         this.messages.push({
                             role: "tool",
@@ -401,9 +356,30 @@ export class Chat {
                         continue;
                     }
                 }
-                // 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);
+                try {
+                    const toolResult = await ToolHandler.execute(toolCall, this.options.tools, this.options.onToolCallStart, this.options.onToolCallEnd);
+                    this.messages.push(toolResult);
+                }
+                catch (error) {
+                    const directive = await this.options.onToolCallError?.(toolCall, error);
+                    if (directive === 'STOP') {
+                        throw error;
+                    }
+                    this.messages.push({
+                        role: "tool",
+                        tool_call_id: toolCall.id,
+                        content: `Fatal error executing tool '${toolCall.function.name}': ${error.message}`,
+                    });
+                    if (directive === 'CONTINUE') {
+                        continue;
+                    }
+                    // Default short-circuit logic
+                    const isFatal = error.fatal === true || error.status === 401 || error.status === 403;
+                    if (isFatal) {
+                        throw error;
+                    }
+                    console.error(`[NodeLLM] Tool execution failed for '${toolCall.function.name}':`, error);
+                }
             }
             response = await this.executor.executeChat({
                 model: this.model,
@@ -438,68 +414,46 @@ export class Chat {
     /**
      * Streams the model's response to a user question.
      */
-    stream(content) {
+    stream(content, options = {}) {
         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;
+        return streamer.create(content, options);
     }
     /**
-     * Request user confirmation for a tool call in "confirm" mode.
-     * Returns true if approved, false if rejected.
+     * Normalizes a ToolResolvable into a ToolDefinition.
      */
-    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) {
+    normalizeTool(tool) {
+        let toolInstance;
+        // Handle class constructor
+        if (typeof tool === "function") {
             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,
-                };
+                toolInstance = new tool();
             }
-            catch (error) {
-                if (onError)
-                    onError(toolCall, error);
-                return {
-                    role: "tool",
-                    tool_call_id: toolCall.id,
-                    content: `Error executing tool: ${error.message}`,
-                };
+            catch (e) {
+                console.error(`[NodeLLM] Failed to instantiate tool class: ${tool.name}`, e);
+                return null;
             }
         }
         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",
-            };
+            toolInstance = tool;
+        }
+        if (!toolInstance)
+            return null;
+        // Normalized to standard ToolDefinition interface if it's a Tool class instance
+        if (typeof toolInstance.toLLMTool === "function") {
+            return toolInstance.toLLMTool();
+        }
+        if (!toolInstance.function || !toolInstance.function.name) {
+            // 1. Validate structure
+            throw new ConfigurationError(`[NodeLLM] Tool validation failed: 'function.name' is required for raw tool objects.`);
+        }
+        if (toolInstance.type !== 'function') {
+            // 2. Ensure 'type: function' exists (standardize for providers)
+            toolInstance.type = 'function';
+        }
+        if (typeof toolInstance.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()')`);
         }
+        return toolInstance;
     }
 }

package/dist/chat/ChatOptions.d.ts

@@ -1,19 +1,19 @@
 import { Message } from "./Message.js";
-import { ToolDefinition } from "./Tool.js";
+import { ToolResolvable } 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[];
-    tools?: ToolDefinition[];
+    tools?: ToolResolvable[];
     temperature?: number;
     maxTokens?: number;
     onNewMessage?: () => void;
     onEndMessage?: (message: any) => void;
     onToolCallStart?: (toolCall: any) => void;
     onToolCallEnd?: (toolCall: any, result: any) => void;
-    onToolCallError?: (toolCall: any, error: Error) => void;
+    onToolCallError?: (toolCall: any, error: Error) => 'STOP' | 'CONTINUE' | void | Promise<'STOP' | 'CONTINUE' | void>;
     headers?: Record<string, string>;
     schema?: Schema;
     responseFormat?: {

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;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"}
+{"version":3,"file":"ChatOptions.d.ts","sourceRoot":"","sources":["../../src/chat/ChatOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAkB,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3D,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,MAAM,GAAG,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC,CAAC;IACpH,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/ChatStream.d.ts

@@ -1,7 +1,9 @@
 import { Message } from "./Message.js";
+import { ContentPart } from "./Content.js";
 import { ChatOptions } from "./ChatOptions.js";
 import { Provider, ChatChunk } from "../providers/Provider.js";
 import { Stream } from "../streaming/Stream.js";
+import { AskOptions } from "./Chat.js";
 /**
  * Internal handler for chat streaming logic.
  * Wraps the provider's stream with side effects like history updates and events.
@@ -13,27 +15,7 @@ export declare class ChatStream {
     private messages;
     private systemMessages;
     constructor(provider: Provider, model: string, options?: ChatOptions, messages?: Message[], systemMessages?: Message[]);
-    /**
-     * Read-only access to message history
-     */
     get history(): readonly Message[];
-    /**
-     * Creates a high-level Stream object for the chat response.
-     * @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;
+    create(content: string | ContentPart[], options?: AskOptions): Stream<ChatChunk>;
 }
 //# sourceMappingURL=ChatStream.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ChatStream.d.ts","sourceRoot":"","sources":["../../src/chat/ChatStream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAIhD;;;GAGG;AACH,qBAAa,UAAU;IAKnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAY;IAC5B,OAAO,CAAC,cAAc,CAAY;gBAGf,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,EAC1C,QAAQ,CAAC,EAAE,OAAO,EAAE,EACpB,cAAc,CAAC,EAAE,OAAO,EAAE;IA8B5B;;OAEG;IACH,IAAI,OAAO,IAAI,SAAS,OAAO,EAAE,CAEhC;IAED;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC;IA6J1C;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAM1B;;;OAGG;YACW,uBAAuB;IASrC;;OAEG;YACW,eAAe;CA2C9B"}
+{"version":3,"file":"ChatStream.d.ts","sourceRoot":"","sources":["../../src/chat/ChatStream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAA4C,MAAM,cAAc,CAAC;AACrF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAS,MAAM,0BAA0B,CAAC;AAEtE,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAGhD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAOvC;;;GAGG;AACH,qBAAa,UAAU;IAKnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAY;IAC5B,OAAO,CAAC,cAAc,CAAY;gBAGf,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,WAAgB,EAC1C,QAAQ,CAAC,EAAE,OAAO,EAAE,EACpB,cAAc,CAAC,EAAE,OAAO,EAAE;IA6B5B,IAAI,OAAO,IAAI,SAAS,OAAO,EAAE,CAEhC;IAED,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,EAAE,OAAO,GAAE,UAAe,GAAG,MAAM,CAAC,SAAS,CAAC;CAsOrF"}