vanilla-agent 1.9.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vanilla-agent",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Themeable, plugable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",

package/src/client.ts

@@ -5,7 +5,11 @@ import {
   AgentWidgetStreamParser,
   AgentWidgetContextProvider,
   AgentWidgetRequestMiddleware,
-  AgentWidgetRequestPayload
+  AgentWidgetRequestPayload,
+  AgentWidgetCustomFetch,
+  AgentWidgetSSEEventParser,
+  AgentWidgetHeadersFunction,
+  AgentWidgetSSEEventResult
 } from "./types";
 import { 
   extractTextFromJson, 
@@ -48,6 +52,9 @@ export class AgentWidgetClient {
   private readonly createStreamParser: () => AgentWidgetStreamParser;
   private readonly contextProviders: AgentWidgetContextProvider[];
   private readonly requestMiddleware?: AgentWidgetRequestMiddleware;
+  private readonly customFetch?: AgentWidgetCustomFetch;
+  private readonly parseSSEEvent?: AgentWidgetSSEEventParser;
+  private readonly getHeaders?: AgentWidgetHeadersFunction;
 
   constructor(private config: AgentWidgetConfig = {}) {
     this.apiUrl = config.apiUrl ?? DEFAULT_ENDPOINT;
@@ -60,6 +67,9 @@ export class AgentWidgetClient {
     this.createStreamParser = config.streamParser ?? getParserFromType(config.parserType);
     this.contextProviders = config.contextProviders ?? [];
     this.requestMiddleware = config.requestMiddleware;
+    this.customFetch = config.customFetch;
+    this.parseSSEEvent = config.parseSSEEvent;
+    this.getHeaders = config.getHeaders;
   }
 
   public async dispatch(options: DispatchOptions, onEvent: SSEHandler) {
@@ -70,19 +80,54 @@ export class AgentWidgetClient {
 
     onEvent({ type: "status", status: "connecting" });
 
-    const body = await this.buildPayload(options.messages);
+    const payload = await this.buildPayload(options.messages);
 
     if (this.debug) {
       // eslint-disable-next-line no-console
-      console.debug("[AgentWidgetClient] dispatch body", body);
+      console.debug("[AgentWidgetClient] dispatch payload", payload);
     }
 
-    const response = await fetch(this.apiUrl, {
-      method: "POST",
-      headers: this.headers,
-      body: JSON.stringify(body),
-      signal: controller.signal
-    });
+    // Build headers - merge static headers with dynamic headers if provided
+    let headers = { ...this.headers };
+    if (this.getHeaders) {
+      try {
+        const dynamicHeaders = await this.getHeaders();
+        headers = { ...headers, ...dynamicHeaders };
+      } catch (error) {
+        if (typeof console !== "undefined") {
+          // eslint-disable-next-line no-console
+          console.error("[AgentWidget] getHeaders error:", error);
+        }
+      }
+    }
+
+    // Use customFetch if provided, otherwise use default fetch
+    let response: Response;
+    if (this.customFetch) {
+      try {
+        response = await this.customFetch(
+          this.apiUrl,
+          {
+            method: "POST",
+            headers,
+            body: JSON.stringify(payload),
+            signal: controller.signal
+          },
+          payload
+        );
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        onEvent({ type: "error", error: err });
+        throw err;
+      }
+    } else {
+      response = await fetch(this.apiUrl, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+    }
 
     if (!response.ok || !response.body) {
       const error = new Error(
@@ -112,7 +157,7 @@ export class AgentWidgetClient {
       })
       .map((message) => ({
         role: message.role,
-        content: message.content,
+        content: message.rawContent || message.content,
         createdAt: message.createdAt
       }));
 
@@ -167,6 +212,70 @@ export class AgentWidgetClient {
     return payload;
   }
 
+  /**
+   * Handle custom SSE event parsing via parseSSEEvent callback
+   * Returns true if event was handled, false otherwise
+   */
+  private async handleCustomSSEEvent(
+    payload: unknown,
+    onEvent: SSEHandler,
+    assistantMessageRef: { current: AgentWidgetMessage | null },
+    emitMessage: (msg: AgentWidgetMessage) => void,
+    nextSequence: () => number
+  ): Promise<boolean> {
+    if (!this.parseSSEEvent) return false;
+
+    try {
+      const result = await this.parseSSEEvent(payload);
+      if (result === null) return false; // Event should be ignored
+
+      const ensureAssistant = () => {
+        if (assistantMessageRef.current) return assistantMessageRef.current;
+        const msg: AgentWidgetMessage = {
+          id: `assistant-${Date.now()}-${Math.random().toString(16).slice(2)}`,
+          role: "assistant",
+          content: "",
+          createdAt: new Date().toISOString(),
+          streaming: true,
+          variant: "assistant",
+          sequence: nextSequence()
+        };
+        assistantMessageRef.current = msg;
+        emitMessage(msg);
+        return msg;
+      };
+
+      if (result.text !== undefined) {
+        const assistant = ensureAssistant();
+        assistant.content += result.text;
+        emitMessage(assistant);
+      }
+
+      if (result.done) {
+        if (assistantMessageRef.current) {
+          assistantMessageRef.current.streaming = false;
+          emitMessage(assistantMessageRef.current);
+        }
+        onEvent({ type: "status", status: "idle" });
+      }
+
+      if (result.error) {
+        onEvent({
+          type: "error",
+          error: new Error(result.error)
+        });
+      }
+
+      return true; // Event was handled
+    } catch (error) {
+      if (typeof console !== "undefined") {
+        // eslint-disable-next-line no-console
+        console.error("[AgentWidget] parseSSEEvent error:", error);
+      }
+      return false;
+    }
+  }
+
   private async streamResponse(
     body: ReadableStream<Uint8Array>,
     onEvent: SSEHandler
@@ -215,6 +324,8 @@ export class AgentWidgetClient {
     };
 
     let assistantMessage: AgentWidgetMessage | null = null;
+    // Reference to track assistant message for custom event handler
+    const assistantMessageRef = { current: null as AgentWidgetMessage | null };
     const reasoningMessages = new Map<string, AgentWidgetMessage>();
     const toolMessages = new Map<string, AgentWidgetMessage>();
     const reasoningContext = {
@@ -265,7 +376,6 @@ export class AgentWidgetClient {
         content: "",
         createdAt: new Date().toISOString(),
         streaming: true,
-        variant: "assistant",
         sequence: nextSequence()
       };
       emitMessage(assistantMessage);
@@ -471,6 +581,24 @@ export class AgentWidgetClient {
         const payloadType =
           eventType !== "message" ? eventType : payload.type ?? "message";
 
+        // If custom SSE event parser is provided, try it first
+        if (this.parseSSEEvent) {
+          // Keep assistant message ref in sync
+          assistantMessageRef.current = assistantMessage;
+          const handled = await this.handleCustomSSEEvent(
+            payload,
+            onEvent,
+            assistantMessageRef,
+            emitMessage,
+            nextSequence
+          );
+          // Update assistantMessage from ref (in case it was created)
+          if (assistantMessageRef.current && !assistantMessage) {
+            assistantMessage = assistantMessageRef.current;
+          }
+          if (handled) continue; // Skip default handling if custom handler processed it
+        }
+
         if (payloadType === "reason_start") {
           const reasoningId =
             resolveReasoningId(payload, true) ?? `reason-${nextSequence()}`;
@@ -635,7 +763,8 @@ export class AgentWidgetClient {
             continue;
           }
           const assistant = ensureAssistantMessage();
-          const chunk = payload.text ?? payload.delta ?? payload.content ?? "";
+          // Support various field names: text, delta, content, chunk (Travrse uses 'chunk')
+          const chunk = payload.text ?? payload.delta ?? payload.content ?? payload.chunk ?? "";
           if (chunk) {
             // Accumulate raw content for structured format parsing
             const rawBuffer = rawContentBuffers.get(assistant.id) ?? "";

package/src/components/forms.ts

@@ -167,3 +167,4 @@ export const enhanceWithForms = (
 
 
 
+

package/src/components/registry.ts

@@ -0,0 +1,87 @@
+import { AgentWidgetConfig, AgentWidgetMessage } from "../types";
+
+/**
+ * Context provided to component renderers
+ */
+export interface ComponentContext {
+  message: AgentWidgetMessage;
+  config: AgentWidgetConfig;
+  /**
+   * Update component props during streaming
+   */
+  updateProps: (newProps: Record<string, unknown>) => void;
+}
+
+/**
+ * Component renderer function signature
+ */
+export type ComponentRenderer = (
+  props: Record<string, unknown>,
+  context: ComponentContext
+) => HTMLElement;
+
+/**
+ * Component registry for managing custom components
+ */
+class ComponentRegistry {
+  private components: Map<string, ComponentRenderer> = new Map();
+
+  /**
+   * Register a custom component
+   */
+  register(name: string, renderer: ComponentRenderer): void {
+    if (this.components.has(name)) {
+      console.warn(`[ComponentRegistry] Component "${name}" is already registered. Overwriting.`);
+    }
+    this.components.set(name, renderer);
+  }
+
+  /**
+   * Unregister a component
+   */
+  unregister(name: string): void {
+    this.components.delete(name);
+  }
+
+  /**
+   * Get a component renderer by name
+   */
+  get(name: string): ComponentRenderer | undefined {
+    return this.components.get(name);
+  }
+
+  /**
+   * Check if a component is registered
+   */
+  has(name: string): boolean {
+    return this.components.has(name);
+  }
+
+  /**
+   * Get all registered component names
+   */
+  getAllNames(): string[] {
+    return Array.from(this.components.keys());
+  }
+
+  /**
+   * Clear all registered components
+   */
+  clear(): void {
+    this.components.clear();
+  }
+
+  /**
+   * Register multiple components at once
+   */
+  registerAll(components: Record<string, ComponentRenderer>): void {
+    Object.entries(components).forEach(([name, renderer]) => {
+      this.register(name, renderer);
+    });
+  }
+}
+
+/**
+ * Global component registry instance
+ */
+export const componentRegistry = new ComponentRegistry();

package/src/index.ts

@@ -12,7 +12,12 @@ export type {
   AgentWidgetLauncherConfig,
   AgentWidgetEvent,
   AgentWidgetStreamParser,
-  AgentWidgetStreamParserResult
+  AgentWidgetStreamParserResult,
+  AgentWidgetRequestPayload,
+  AgentWidgetCustomFetch,
+  AgentWidgetSSEEventParser,
+  AgentWidgetSSEEventResult,
+  AgentWidgetHeadersFunction
 } from "./types";
 
 export { initAgentWidgetFn as initAgentWidget };
@@ -36,7 +41,7 @@ export {
   escapeHtml,
   directivePostprocessor
 } from "./postprocessors";
-export { 
+export {
   createPlainTextParser,
   createJsonStreamParser,
   createFlexibleJsonStreamParser,
@@ -49,6 +54,21 @@ export type { AgentWidgetInitHandle };
 export type { AgentWidgetPlugin } from "./plugins/types";
 export { pluginRegistry } from "./plugins/registry";
 
+// Component system exports
+export { componentRegistry } from "./components/registry";
+export type { ComponentRenderer, ComponentContext } from "./components/registry";
+export {
+  createComponentStreamParser,
+  isComponentDirectiveType
+} from "./utils/component-parser";
+export type { ComponentDirective } from "./utils/component-parser";
+export {
+  renderComponentDirective,
+  createComponentMiddleware,
+  hasComponentDirective,
+  extractComponentDirectiveFromMessage
+} from "./utils/component-middleware";
+
 // Default configuration exports
 export { DEFAULT_WIDGET_CONFIG, mergeWithDefaults } from "./defaults";
 

package/src/plugins/registry.ts

@@ -74,3 +74,4 @@ export const pluginRegistry = new PluginRegistry();
 
 
 
+

package/src/plugins/types.ts

@@ -92,3 +92,4 @@ export interface AgentWidgetPlugin {
 
 
 
+

package/src/types.ts

@@ -339,10 +339,72 @@ export interface AgentWidgetStreamParser {
 }
 
 
+/**
+ * Component renderer function signature for custom components
+ */
+export type AgentWidgetComponentRenderer = (
+  props: Record<string, unknown>,
+  context: {
+    message: AgentWidgetMessage;
+    config: AgentWidgetConfig;
+    updateProps: (newProps: Record<string, unknown>) => void;
+  }
+) => HTMLElement;
+
+/**
+ * Result from custom SSE event parser
+ */
+export type AgentWidgetSSEEventResult = {
+  /** Text content to display */
+  text?: string;
+  /** Whether the stream is complete */
+  done?: boolean;
+  /** Error message if an error occurred */
+  error?: string;
+} | null;
+
+/**
+ * Custom SSE event parser function
+ * Allows transforming non-standard SSE event formats to vanilla-agent's expected format
+ */
+export type AgentWidgetSSEEventParser = (
+  eventData: unknown
+) => AgentWidgetSSEEventResult | Promise<AgentWidgetSSEEventResult>;
+
+/**
+ * Custom fetch function for full control over API requests
+ * Use this for custom authentication, request transformation, etc.
+ */
+export type AgentWidgetCustomFetch = (
+  url: string,
+  init: RequestInit,
+  payload: AgentWidgetRequestPayload
+) => Promise<Response>;
+
+/**
+ * Dynamic headers function - called before each request
+ */
+export type AgentWidgetHeadersFunction = () => Record<string, string> | Promise<Record<string, string>>;
+
 export type AgentWidgetConfig = {
   apiUrl?: string;
   flowId?: string;
+  /**
+   * Static headers to include with each request.
+   * For dynamic headers (e.g., auth tokens), use `getHeaders` instead.
+   */
   headers?: Record<string, string>;
+  /**
+   * Dynamic headers function - called before each request.
+   * Useful for adding auth tokens that may change.
+   * @example
+   * ```typescript
+   * getHeaders: async () => ({
+   *   'Authorization': `Bearer ${await getAuthToken()}`
+   * })
+   * ```
+   */
+  getHeaders?: AgentWidgetHeadersFunction;
   copy?: {
     welcomeTitle?: string;
     welcomeSubtitle?: string;
@@ -374,6 +436,32 @@ export type AgentWidgetConfig = {
   actionParsers?: AgentWidgetActionParser[];
   actionHandlers?: AgentWidgetActionHandler[];
   storageAdapter?: AgentWidgetStorageAdapter;
+  /**
+   * Registry of custom components that can be rendered from JSON directives.
+   * Components are registered by name and can be invoked via JSON responses
+   * with the format: `{"component": "ComponentName", "props": {...}}`
+   * 
+   * @example
+   * ```typescript
+   * config: {
+   *   components: {
+   *     ProductCard: (props, context) => {
+   *       const card = document.createElement("div");
+   *       card.innerHTML = `<h3>${props.title}</h3><p>$${props.price}</p>`;
+   *       return card;
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  components?: Record<string, AgentWidgetComponentRenderer>;
+  /**
+   * Enable component streaming. When true, component props will be updated
+   * incrementally as they stream in from the JSON response.
+   * 
+   * @default true
+   */
+  enableComponentStreaming?: boolean;
   /**
    * Custom stream parser for extracting text from streaming structured responses.
    * Handles incremental parsing of JSON, XML, or other formats.
@@ -430,6 +518,68 @@ export type AgentWidgetConfig = {
    * ```
    */
   parserType?: "plain" | "json" | "regex-json" | "xml";
+  /**
+   * Custom fetch function for full control over API requests.
+   * Use this for custom authentication, request/response transformation, etc.
+   *
+   * When provided, this function is called instead of the default fetch.
+   * You receive the URL, RequestInit, and the payload that would be sent.
+   *
+   * @example
+   * ```typescript
+   * config: {
+   *   customFetch: async (url, init, payload) => {
+   *     // Transform request for your API format
+   *     const myPayload = {
+   *       flow: { id: 'my-flow-id' },
+   *       messages: payload.messages,
+   *       options: { stream_response: true }
+   *     };
+   *
+   *     // Add auth header
+   *     const token = await getAuthToken();
+   *
+   *     return fetch('/my-api/dispatch', {
+   *       method: 'POST',
+   *       headers: {
+   *         'Content-Type': 'application/json',
+   *         'Authorization': `Bearer ${token}`
+   *       },
+   *       body: JSON.stringify(myPayload),
+   *       signal: init.signal
+   *     });
+   *   }
+   * }
+   * ```
+   */
+  customFetch?: AgentWidgetCustomFetch;
+  /**
+   * Custom SSE event parser for non-standard streaming response formats.
+   *
+   * Use this when your API returns SSE events in a different format than expected.
+   * Return `{ text }` for text chunks, `{ done: true }` for completion,
+   * `{ error }` for errors, or `null` to ignore the event.
+   *
+   * @example
+   * ```typescript
+   * // For Travrse API format
+   * config: {
+   *   parseSSEEvent: (data) => {
+   *     if (data.type === 'step_chunk' && data.chunk) {
+   *       return { text: data.chunk };
+   *     }
+   *     if (data.type === 'flow_complete') {
+   *       return { done: true };
+   *     }
+   *     if (data.type === 'step_error') {
+   *       return { error: data.error };
+   *     }
+   *     return null; // Ignore other events
+   *   }
+   * }
+   * ```
+   */
+  parseSSEEvent?: AgentWidgetSSEEventParser;
 };
 
 export type AgentWidgetMessageRole = "user" | "assistant" | "system";

package/src/ui.ts

@@ -31,6 +31,13 @@ import {
   defaultActionHandlers,
   defaultJsonActionParser
 } from "./utils/actions";
+import { createLocalStorageAdapter } from "./utils/storage";
+import { componentRegistry } from "./components/registry";
+import {
+  renderComponentDirective,
+  extractComponentDirectiveFromMessage,
+  hasComponentDirective
+} from "./utils/component-middleware";
 
 // Default localStorage key for chat history (automatically cleared on clear chat)
 const DEFAULT_CHAT_HISTORY_STORAGE_KEY = "vanilla-agent-chat-history";
@@ -132,10 +139,15 @@ export const createAgentExperience = (
 
   // Get plugins for this instance
   const plugins = pluginRegistry.getForInstance(config.plugins);
+  
+  // Register components from config
+  if (config.components) {
+    componentRegistry.registerAll(config.components);
+  }
   const eventBus = createEventBus<AgentWidgetControllerEventMap>();
 
-  const storageAdapter: AgentWidgetStorageAdapter | undefined =
-    config.storageAdapter;
+  const storageAdapter: AgentWidgetStorageAdapter =
+    config.storageAdapter ?? createLocalStorageAdapter();
   let persistentMetadata: Record<string, unknown> = {};
   let pendingStoredState: Promise<AgentWidgetStoredState | null> | null = null;
 
@@ -302,11 +314,17 @@ export const createAgentExperience = (
       : [];
 
   function persistState(messagesOverride?: AgentWidgetMessage[]) {
-    if (!storageAdapter?.save || !session) return;
+    if (!storageAdapter?.save) return;
+
+    // Allow saving even if session doesn't exist yet (for metadata during init)
+    const messages = messagesOverride
+      ? stripStreamingFromMessages(messagesOverride)
+      : session
+        ? getMessagesForPersistence()
+        : [];
+
     const payload = {
-      messages: messagesOverride
-        ? stripStreamingFromMessages(messagesOverride)
-        : getMessagesForPersistence(),
+      messages,
       metadata: persistentMetadata
     };
     try {
@@ -518,6 +536,51 @@ export const createAgentExperience = (
         }
       }
 
+      // Check for component directive if no plugin handled it
+      if (!bubble && message.role === "assistant" && !message.variant) {
+        const enableComponentStreaming = config.enableComponentStreaming !== false; // Default to true
+        if (enableComponentStreaming && hasComponentDirective(message)) {
+          const directive = extractComponentDirectiveFromMessage(message);
+          if (directive) {
+            const componentBubble = renderComponentDirective(directive, {
+              config,
+              message,
+              transform
+            });
+            if (componentBubble) {
+              // Wrap component in standard bubble styling
+              const wrapper = document.createElement("div");
+              wrapper.className = [
+                "vanilla-message-bubble",
+                "tvw-max-w-[85%]",
+                "tvw-rounded-2xl",
+                "tvw-bg-cw-surface",
+                "tvw-border",
+                "tvw-border-cw-message-border",
+                "tvw-p-4"
+              ].join(" ");
+              wrapper.setAttribute("data-message-id", message.id);
+
+              // Add text content above component if present (combined text+component response)
+              if (message.content && message.content.trim()) {
+                const textDiv = document.createElement("div");
+                textDiv.className = "tvw-mb-3 tvw-text-sm tvw-leading-relaxed";
+                textDiv.innerHTML = transform({
+                  text: message.content,
+                  message,
+                  streaming: Boolean(message.streaming),
+                  raw: message.rawContent
+                });
+                wrapper.appendChild(textDiv);
+              }
+
+              wrapper.appendChild(componentBubble);
+              bubble = wrapper;
+            }
+          }
+        }
+      }
+
       // Fallback to default rendering if plugin returned null or no plugin matched
       if (!bubble) {
         if (message.variant === "reasoning" && message.reasoning) {