vanilla-agent 1.2.0 → 1.4.0

package/dist/index.d.cts

@@ -206,6 +206,74 @@ type AgentWidgetVoiceRecognitionConfig = {
     recordingBorderColor?: string;
     showRecordingIndicator?: boolean;
 };
+type AgentWidgetToolCallConfig = {
+    backgroundColor?: string;
+    borderColor?: string;
+    borderWidth?: string;
+    borderRadius?: string;
+    headerBackgroundColor?: string;
+    headerTextColor?: string;
+    headerPaddingX?: string;
+    headerPaddingY?: string;
+    contentBackgroundColor?: string;
+    contentTextColor?: string;
+    contentPaddingX?: string;
+    contentPaddingY?: string;
+    codeBlockBackgroundColor?: string;
+    codeBlockBorderColor?: string;
+    codeBlockTextColor?: string;
+    toggleTextColor?: string;
+    labelTextColor?: string;
+};
+/**
+ * Interface for pluggable stream parsers that extract text from streaming responses.
+ * Parsers handle incremental parsing to extract text values from structured formats (JSON, XML, etc.).
+ *
+ * @example
+ * ```typescript
+ * const jsonParser: AgentWidgetStreamParser = {
+ *   processChunk: async (content) => {
+ *     // Extract text from JSON - return null if not JSON or text not available yet
+ *     if (!content.trim().startsWith('{')) return null;
+ *     const match = content.match(/"text"\s*:\s*"([^"]*)"/);
+ *     return match ? match[1] : null;
+ *   },
+ *   getExtractedText: () => extractedText
+ * };
+ * ```
+ */
+interface AgentWidgetStreamParserResult {
+    /**
+     * The extracted text to display (may be partial during streaming)
+     */
+    text: string | null;
+    /**
+     * Optional: The raw accumulated content (useful for middleware that needs the original format)
+     */
+    raw?: string;
+}
+interface AgentWidgetStreamParser {
+    /**
+     * Process a chunk of content and return the extracted text (if available).
+     * This method is called for each chunk as it arrives during streaming.
+     * Return null if the content doesn't match this parser's format or if text is not yet available.
+     *
+     * @param accumulatedContent - The full accumulated content so far (including new chunk)
+     * @returns The extracted text value and optionally raw content, or null if not yet available or format doesn't match
+     */
+    processChunk(accumulatedContent: string): Promise<AgentWidgetStreamParserResult | string | null> | AgentWidgetStreamParserResult | string | null;
+    /**
+     * Get the currently extracted text value (may be partial).
+     * This is called synchronously to get the latest extracted text without processing.
+     *
+     * @returns The currently extracted text value, or null if not yet available
+     */
+    getExtractedText(): string | null;
+    /**
+     * Clean up any resources when parsing is complete.
+     */
+    close?(): Promise<void> | void;
+}
 type AgentWidgetConfig = {
     apiUrl?: string;
     flowId?: string;
@@ -227,12 +295,44 @@ type AgentWidgetConfig = {
     sendButton?: AgentWidgetSendButtonConfig;
     statusIndicator?: AgentWidgetStatusIndicatorConfig;
     voiceRecognition?: AgentWidgetVoiceRecognitionConfig;
+    toolCall?: AgentWidgetToolCallConfig;
     postprocessMessage?: (context: {
         text: string;
         message: AgentWidgetMessage;
         streaming: boolean;
     }) => string;
     plugins?: AgentWidgetPlugin[];
+    /**
+     * Custom stream parser for extracting text from streaming structured responses.
+     * Handles incremental parsing of JSON, XML, or other formats.
+     * If not provided, uses the default JSON parser.
+     *
+     * @example
+     * ```typescript
+     * streamParser: () => ({
+     *   processChunk: async (content) => {
+     *     // Return null if not your format, or extracted text if available
+     *     if (!content.trim().startsWith('{')) return null;
+     *     return extractText(content);
+     *   },
+     *   getExtractedText: () => extractedText
+     * })
+     * ```
+     */
+    streamParser?: () => AgentWidgetStreamParser;
+    /**
+     * Additional localStorage key to clear when the clear chat button is clicked.
+     * The widget automatically clears `"vanilla-agent-chat-history"` by default.
+     * Use this option to clear additional keys (e.g., if you're using a custom storage key).
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   clearChatHistoryStorageKey: "my-custom-chat-history"
+     * }
+     * ```
+     */
+    clearChatHistoryStorageKey?: string;
 };
 type AgentWidgetMessageRole = "user" | "assistant" | "system";
 type AgentWidgetReasoning = {
@@ -256,6 +356,22 @@ type AgentWidgetToolCall = {
     durationMs?: number;
 };
 type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool";
+/**
+ * Represents a message in the chat conversation.
+ *
+ * @property id - Unique message identifier
+ * @property role - Message role: "user", "assistant", or "system"
+ * @property content - Message text content
+ * @property createdAt - ISO timestamp when message was created
+ * @property streaming - Whether message is still streaming (for assistant messages)
+ * @property variant - Message variant for assistant messages: "assistant", "reasoning", or "tool"
+ * @property sequence - Message ordering number
+ * @property reasoning - Reasoning data for assistant reasoning messages
+ * @property toolCall - Tool call data for assistant tool messages
+ * @property tools - Array of tool calls
+ * @property viaVoice - Set to `true` when a user message is sent via voice recognition.
+ *                      Useful for implementing voice-specific behaviors like auto-reactivation.
+ */
 type AgentWidgetMessage = {
     id: string;
     role: AgentWidgetMessageRole;
@@ -267,6 +383,7 @@ type AgentWidgetMessage = {
     reasoning?: AgentWidgetReasoning;
     toolCall?: AgentWidgetToolCall;
     tools?: AgentWidgetToolCall[];
+    viaVoice?: boolean;
 };
 type AgentWidgetEvent = {
     type: "message";
@@ -297,6 +414,7 @@ type Controller = {
     submitMessage: (message?: string) => boolean;
     startVoiceRecognition: () => boolean;
     stopVoiceRecognition: () => boolean;
+    injectTestMessage: (event: AgentWidgetEvent) => void;
 };
 declare const createAgentExperience: (mount: HTMLElement, initialConfig?: AgentWidgetConfig) => Controller;
 type AgentWidgetController = Controller;
@@ -327,7 +445,10 @@ declare class AgentWidgetSession {
     getMessages(): AgentWidgetMessage[];
     getStatus(): AgentWidgetSessionStatus;
     isStreaming(): boolean;
-    sendMessage(rawInput: string): Promise<void>;
+    injectTestEvent(event: AgentWidgetEvent): void;
+    sendMessage(rawInput: string, options?: {
+        viaVoice?: boolean;
+    }): Promise<void>;
     cancel(): void;
     clearMessages(): void;
     private handleEvent;
@@ -350,6 +471,7 @@ declare class AgentWidgetClient {
     private readonly apiUrl;
     private readonly headers;
     private readonly debug;
+    private readonly createStreamParser;
     constructor(config?: AgentWidgetConfig);
     dispatch(options: DispatchOptions, onEvent: SSEHandler): Promise<void>;
     private streamResponse;
@@ -372,6 +494,33 @@ declare const escapeHtml: (text: string) => string;
  */
 declare const directivePostprocessor: (text: string) => string;
 
+/**
+ * Plain text parser - passes through text as-is without any parsing.
+ * This is the default parser.
+ */
+declare const createPlainTextParser: () => AgentWidgetStreamParser;
+/**
+ * JSON parser using regex-based extraction.
+ * Extracts the 'text' field from JSON responses using regex patterns.
+ * This is a simpler regex-based alternative to createJsonStreamParser.
+ * Less robust for complex/malformed JSON but has no external dependencies.
+ */
+declare const createRegexJsonParser: () => AgentWidgetStreamParser;
+/**
+ * JSON stream parser using partial-json library.
+ * Extracts the 'text' field from JSON responses using the partial-json library,
+ * which is specifically designed for parsing incomplete JSON from LLMs.
+ * This is the recommended parser as it's more robust than regex.
+ *
+ * Library: https://github.com/promplate/partial-json-parser-js
+ */
+declare const createJsonStreamParser: () => AgentWidgetStreamParser;
+/**
+ * XML stream parser.
+ * Extracts text from <text>...</text> tags in XML responses.
+ */
+declare const createXmlParser: () => AgentWidgetStreamParser;
+
 declare class PluginRegistry {
     private plugins;
     /**
@@ -409,4 +558,4 @@ declare const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig>;
  */
 declare function mergeWithDefaults(config?: Partial<AgentWidgetConfig>): Partial<AgentWidgetConfig>;
 
-export { AgentWidgetClient, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetMessage, type AgentWidgetPlugin, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetTheme, DEFAULT_WIDGET_CONFIG, createAgentExperience, initAgentWidget as default, directivePostprocessor, escapeHtml, initAgentWidget, markdownPostprocessor, mergeWithDefaults, pluginRegistry };
+export { AgentWidgetClient, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetMessage, type AgentWidgetPlugin, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, DEFAULT_WIDGET_CONFIG, createAgentExperience, createJsonStreamParser, createPlainTextParser, createRegexJsonParser, createXmlParser, initAgentWidget as default, directivePostprocessor, escapeHtml, initAgentWidget, markdownPostprocessor, mergeWithDefaults, pluginRegistry };

package/dist/index.d.ts

@@ -206,6 +206,74 @@ type AgentWidgetVoiceRecognitionConfig = {
     recordingBorderColor?: string;
     showRecordingIndicator?: boolean;
 };
+type AgentWidgetToolCallConfig = {
+    backgroundColor?: string;
+    borderColor?: string;
+    borderWidth?: string;
+    borderRadius?: string;
+    headerBackgroundColor?: string;
+    headerTextColor?: string;
+    headerPaddingX?: string;
+    headerPaddingY?: string;
+    contentBackgroundColor?: string;
+    contentTextColor?: string;
+    contentPaddingX?: string;
+    contentPaddingY?: string;
+    codeBlockBackgroundColor?: string;
+    codeBlockBorderColor?: string;
+    codeBlockTextColor?: string;
+    toggleTextColor?: string;
+    labelTextColor?: string;
+};
+/**
+ * Interface for pluggable stream parsers that extract text from streaming responses.
+ * Parsers handle incremental parsing to extract text values from structured formats (JSON, XML, etc.).
+ *
+ * @example
+ * ```typescript
+ * const jsonParser: AgentWidgetStreamParser = {
+ *   processChunk: async (content) => {
+ *     // Extract text from JSON - return null if not JSON or text not available yet
+ *     if (!content.trim().startsWith('{')) return null;
+ *     const match = content.match(/"text"\s*:\s*"([^"]*)"/);
+ *     return match ? match[1] : null;
+ *   },
+ *   getExtractedText: () => extractedText
+ * };
+ * ```
+ */
+interface AgentWidgetStreamParserResult {
+    /**
+     * The extracted text to display (may be partial during streaming)
+     */
+    text: string | null;
+    /**
+     * Optional: The raw accumulated content (useful for middleware that needs the original format)
+     */
+    raw?: string;
+}
+interface AgentWidgetStreamParser {
+    /**
+     * Process a chunk of content and return the extracted text (if available).
+     * This method is called for each chunk as it arrives during streaming.
+     * Return null if the content doesn't match this parser's format or if text is not yet available.
+     *
+     * @param accumulatedContent - The full accumulated content so far (including new chunk)
+     * @returns The extracted text value and optionally raw content, or null if not yet available or format doesn't match
+     */
+    processChunk(accumulatedContent: string): Promise<AgentWidgetStreamParserResult | string | null> | AgentWidgetStreamParserResult | string | null;
+    /**
+     * Get the currently extracted text value (may be partial).
+     * This is called synchronously to get the latest extracted text without processing.
+     *
+     * @returns The currently extracted text value, or null if not yet available
+     */
+    getExtractedText(): string | null;
+    /**
+     * Clean up any resources when parsing is complete.
+     */
+    close?(): Promise<void> | void;
+}
 type AgentWidgetConfig = {
     apiUrl?: string;
     flowId?: string;
@@ -227,12 +295,44 @@ type AgentWidgetConfig = {
     sendButton?: AgentWidgetSendButtonConfig;
     statusIndicator?: AgentWidgetStatusIndicatorConfig;
     voiceRecognition?: AgentWidgetVoiceRecognitionConfig;
+    toolCall?: AgentWidgetToolCallConfig;
     postprocessMessage?: (context: {
         text: string;
         message: AgentWidgetMessage;
         streaming: boolean;
     }) => string;
     plugins?: AgentWidgetPlugin[];
+    /**
+     * Custom stream parser for extracting text from streaming structured responses.
+     * Handles incremental parsing of JSON, XML, or other formats.
+     * If not provided, uses the default JSON parser.
+     *
+     * @example
+     * ```typescript
+     * streamParser: () => ({
+     *   processChunk: async (content) => {
+     *     // Return null if not your format, or extracted text if available
+     *     if (!content.trim().startsWith('{')) return null;
+     *     return extractText(content);
+     *   },
+     *   getExtractedText: () => extractedText
+     * })
+     * ```
+     */
+    streamParser?: () => AgentWidgetStreamParser;
+    /**
+     * Additional localStorage key to clear when the clear chat button is clicked.
+     * The widget automatically clears `"vanilla-agent-chat-history"` by default.
+     * Use this option to clear additional keys (e.g., if you're using a custom storage key).
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   clearChatHistoryStorageKey: "my-custom-chat-history"
+     * }
+     * ```
+     */
+    clearChatHistoryStorageKey?: string;
 };
 type AgentWidgetMessageRole = "user" | "assistant" | "system";
 type AgentWidgetReasoning = {
@@ -256,6 +356,22 @@ type AgentWidgetToolCall = {
     durationMs?: number;
 };
 type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool";
+/**
+ * Represents a message in the chat conversation.
+ *
+ * @property id - Unique message identifier
+ * @property role - Message role: "user", "assistant", or "system"
+ * @property content - Message text content
+ * @property createdAt - ISO timestamp when message was created
+ * @property streaming - Whether message is still streaming (for assistant messages)
+ * @property variant - Message variant for assistant messages: "assistant", "reasoning", or "tool"
+ * @property sequence - Message ordering number
+ * @property reasoning - Reasoning data for assistant reasoning messages
+ * @property toolCall - Tool call data for assistant tool messages
+ * @property tools - Array of tool calls
+ * @property viaVoice - Set to `true` when a user message is sent via voice recognition.
+ *                      Useful for implementing voice-specific behaviors like auto-reactivation.
+ */
 type AgentWidgetMessage = {
     id: string;
     role: AgentWidgetMessageRole;
@@ -267,6 +383,7 @@ type AgentWidgetMessage = {
     reasoning?: AgentWidgetReasoning;
     toolCall?: AgentWidgetToolCall;
     tools?: AgentWidgetToolCall[];
+    viaVoice?: boolean;
 };
 type AgentWidgetEvent = {
     type: "message";
@@ -297,6 +414,7 @@ type Controller = {
     submitMessage: (message?: string) => boolean;
     startVoiceRecognition: () => boolean;
     stopVoiceRecognition: () => boolean;
+    injectTestMessage: (event: AgentWidgetEvent) => void;
 };
 declare const createAgentExperience: (mount: HTMLElement, initialConfig?: AgentWidgetConfig) => Controller;
 type AgentWidgetController = Controller;
@@ -327,7 +445,10 @@ declare class AgentWidgetSession {
     getMessages(): AgentWidgetMessage[];
     getStatus(): AgentWidgetSessionStatus;
     isStreaming(): boolean;
-    sendMessage(rawInput: string): Promise<void>;
+    injectTestEvent(event: AgentWidgetEvent): void;
+    sendMessage(rawInput: string, options?: {
+        viaVoice?: boolean;
+    }): Promise<void>;
     cancel(): void;
     clearMessages(): void;
     private handleEvent;
@@ -350,6 +471,7 @@ declare class AgentWidgetClient {
     private readonly apiUrl;
     private readonly headers;
     private readonly debug;
+    private readonly createStreamParser;
     constructor(config?: AgentWidgetConfig);
     dispatch(options: DispatchOptions, onEvent: SSEHandler): Promise<void>;
     private streamResponse;
@@ -372,6 +494,33 @@ declare const escapeHtml: (text: string) => string;
  */
 declare const directivePostprocessor: (text: string) => string;
 
+/**
+ * Plain text parser - passes through text as-is without any parsing.
+ * This is the default parser.
+ */
+declare const createPlainTextParser: () => AgentWidgetStreamParser;
+/**
+ * JSON parser using regex-based extraction.
+ * Extracts the 'text' field from JSON responses using regex patterns.
+ * This is a simpler regex-based alternative to createJsonStreamParser.
+ * Less robust for complex/malformed JSON but has no external dependencies.
+ */
+declare const createRegexJsonParser: () => AgentWidgetStreamParser;
+/**
+ * JSON stream parser using partial-json library.
+ * Extracts the 'text' field from JSON responses using the partial-json library,
+ * which is specifically designed for parsing incomplete JSON from LLMs.
+ * This is the recommended parser as it's more robust than regex.
+ *
+ * Library: https://github.com/promplate/partial-json-parser-js
+ */
+declare const createJsonStreamParser: () => AgentWidgetStreamParser;
+/**
+ * XML stream parser.
+ * Extracts text from <text>...</text> tags in XML responses.
+ */
+declare const createXmlParser: () => AgentWidgetStreamParser;
+
 declare class PluginRegistry {
     private plugins;
     /**
@@ -409,4 +558,4 @@ declare const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig>;
  */
 declare function mergeWithDefaults(config?: Partial<AgentWidgetConfig>): Partial<AgentWidgetConfig>;
 
-export { AgentWidgetClient, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetMessage, type AgentWidgetPlugin, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetTheme, DEFAULT_WIDGET_CONFIG, createAgentExperience, initAgentWidget as default, directivePostprocessor, escapeHtml, initAgentWidget, markdownPostprocessor, mergeWithDefaults, pluginRegistry };
+export { AgentWidgetClient, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetMessage, type AgentWidgetPlugin, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, DEFAULT_WIDGET_CONFIG, createAgentExperience, createJsonStreamParser, createPlainTextParser, createRegexJsonParser, createXmlParser, initAgentWidget as default, directivePostprocessor, escapeHtml, initAgentWidget, markdownPostprocessor, mergeWithDefaults, pluginRegistry };