vanilla-agent 1.31.0 → 1.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vanilla-agent",
-  "version": "1.31.0",
+  "version": "1.32.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

@@ -139,15 +139,21 @@ export class AgentWidgetClient {
   }
 
   private async _doInitSession(): Promise<ClientSession> {
+    // Get stored session_id if available (for session resumption)
+    const storedSessionId = this.config.getStoredSessionId?.() || null;
+    
+    const requestBody: Record<string, unknown> = {
+      token: this.config.clientToken,
+      ...(this.config.flowId && { flow_id: this.config.flowId }),
+      ...(storedSessionId && { session_id: storedSessionId }),
+    };
+
     const response = await fetch(this.getClientApiUrl('init'), {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
       },
-      body: JSON.stringify({
-        token: this.config.clientToken,
-        flow_id: this.config.flowId,
-      }),
+      body: JSON.stringify(requestBody),
     });
 
     if (!response.ok) {
@@ -162,6 +168,12 @@ export class AgentWidgetClient {
     }
 
     const data: ClientInitResponse = await response.json();
+    
+    // Store the new session_id for future resumption
+    if (this.config.setStoredSessionId) {
+      this.config.setStoredSessionId(data.session_id);
+    }
+    
     return {
       sessionId: data.session_id,
       expiresAt: new Date(data.expires_at),
@@ -381,6 +393,13 @@ export class AgentWidgetClient {
       const basePayload = await this.buildPayload(options.messages);
 
       // Build the chat request payload with message IDs for feedback tracking
+      // Filter out session_id from metadata if present (it's only for local storage)
+      const sanitizedMetadata = basePayload.metadata 
+        ? Object.fromEntries(
+            Object.entries(basePayload.metadata).filter(([key]) => key !== 'session_id')
+          )
+        : undefined;
+      
       const chatRequest: ClientChatRequest = {
         session_id: session.sessionId,
         messages: options.messages.map(m => ({
@@ -390,8 +409,8 @@ export class AgentWidgetClient {
         })),
         // Include pre-generated assistant message ID if provided
         ...(options.assistantMessageId && { assistant_message_id: options.assistantMessageId }),
-        // Include metadata/context from middleware if present
-        ...(basePayload.metadata && { metadata: basePayload.metadata }),
+        // Include metadata/context from middleware if present (excluding session_id)
+        ...(sanitizedMetadata && Object.keys(sanitizedMetadata).length > 0 && { metadata: sanitizedMetadata }),
         ...(basePayload.context && { context: basePayload.context }),
       };
 

package/src/types.ts

@@ -1114,6 +1114,37 @@ export type AgentWidgetConfig = {
    * ```
    */
   onSessionExpired?: () => void;
+  /**
+   * Get stored session ID for session resumption (client token mode only).
+   * Called when initializing a new session to check if there's a previous session_id
+   * that should be passed to /client/init to resume the same conversation record.
+   * 
+   * @example
+   * ```typescript
+   * config: {
+   *   getStoredSessionId: () => {
+   *     const stored = localStorage.getItem('session_id');
+   *     return stored || null;
+   *   }
+   * }
+   * ```
+   */
+  getStoredSessionId?: () => string | null;
+  /**
+   * Store session ID for session resumption (client token mode only).
+   * Called when a new session is initialized to persist the session_id
+   * so it can be used to resume the conversation later.
+   * 
+   * @example
+   * ```typescript
+   * config: {
+   *   setStoredSessionId: (sessionId) => {
+   *     localStorage.setItem('session_id', sessionId);
+   *   }
+   * }
+   * ```
+   */
+  setStoredSessionId?: (sessionId: string) => void;
   /**
    * Static headers to include with each request.
    * For dynamic headers (e.g., auth tokens), use `getHeaders` instead.

package/src/ui.ts

@@ -204,8 +204,8 @@ export const createAgentExperience = (
     }
   }
 
-  const getMetadata = () => persistentMetadata;
-  const updateMetadata = (
+  const getSessionMetadata = () => persistentMetadata;
+  const updateSessionMetadata = (
     updater: (prev: Record<string, unknown>) => Record<string, unknown>
   ) => {
     const next = updater({ ...persistentMetadata }) ?? {};
@@ -226,8 +226,8 @@ export const createAgentExperience = (
   let actionManager = createActionManager({
     parsers: resolvedActionParsers,
     handlers: resolvedActionHandlers,
-    getMetadata,
-    updateMetadata,
+    getSessionMetadata,
+    updateSessionMetadata,
     emit: eventBus.emit,
     documentRef: typeof document !== "undefined" ? document : null
   });
@@ -758,7 +758,7 @@ export const createAgentExperience = (
     });
   };
   const persistVoiceMetadata = () => {
-    updateMetadata((prev) => ({
+    updateSessionMetadata((prev) => ({
       ...prev,
       voiceState: {
         active: voiceState.active,
@@ -1282,6 +1282,24 @@ export const createAgentExperience = (
     textarea.style.fontWeight = fontWeight;
   };
 
+  // Add session ID persistence callbacks for client token mode
+  // These allow the widget to resume conversations by passing session_id to /client/init
+  if (config.clientToken) {
+    config = {
+      ...config,
+      getStoredSessionId: () => {
+        const storedId = persistentMetadata['session_id'];
+        return typeof storedId === 'string' ? storedId : null;
+      },
+      setStoredSessionId: (sessionId: string) => {
+        updateSessionMetadata((prev) => ({
+          ...prev,
+          session_id: sessionId,
+        }));
+      },
+    };
+  }
+
   session = new AgentWidgetSession(config, {
     onMessagesChanged(messages) {
       renderMessagesWithPlugins(messagesWrapper, messages, postprocess);
@@ -2570,8 +2588,8 @@ export const createAgentExperience = (
       actionManager = createActionManager({
         parsers: nextParsers,
         handlers: nextHandlers,
-        getMetadata,
-        updateMetadata,
+        getSessionMetadata,
+        updateSessionMetadata,
         emit: eventBus.emit,
         documentRef: typeof document !== "undefined" ? document : null
       });
@@ -3015,7 +3033,7 @@ export const createAgentExperience = (
     updatePersistentMetadata(
       updater: (prev: Record<string, unknown>) => Record<string, unknown>
     ) {
-      updateMetadata(updater);
+      updateSessionMetadata(updater);
     },
     on(event, handler) {
       return eventBus.on(event, handler);

package/src/utils/actions.ts

@@ -19,8 +19,8 @@ type ActionManagerProcessContext = {
 type ActionManagerOptions = {
   parsers: AgentWidgetActionParser[];
   handlers: AgentWidgetActionHandler[];
-  getMetadata: () => Record<string, unknown>;
-  updateMetadata: (
+  getSessionMetadata: () => Record<string, unknown>;
+  updateSessionMetadata: (
     updater: (prev: Record<string, unknown>) => Record<string, unknown>
   ) => void;
   emit: <K extends keyof AgentWidgetControllerEventMap>(
@@ -123,18 +123,18 @@ const ensureArrayOfStrings = (value: unknown): string[] => {
 
 export const createActionManager = (options: ActionManagerOptions) => {
   let processedIds = new Set(
-    ensureArrayOfStrings(options.getMetadata().processedActionMessageIds)
+    ensureArrayOfStrings(options.getSessionMetadata().processedActionMessageIds)
   );
 
   const syncFromMetadata = () => {
     processedIds = new Set(
-      ensureArrayOfStrings(options.getMetadata().processedActionMessageIds)
+      ensureArrayOfStrings(options.getSessionMetadata().processedActionMessageIds)
     );
   };
 
   const persistProcessedIds = () => {
     const latestIds = Array.from(processedIds);
-    options.updateMetadata((prev) => ({
+    options.updateSessionMetadata((prev) => ({
       ...prev,
       processedActionMessageIds: latestIds
     }));
@@ -195,8 +195,8 @@ export const createActionManager = (options: ActionManagerOptions) => {
       try {
         const handlerResult = handler(action, {
           message: context.message,
-          metadata: options.getMetadata(),
-          updateMetadata: options.updateMetadata,
+          metadata: options.getSessionMetadata(),
+          updateMetadata: options.updateSessionMetadata,
           document: options.documentRef
         } as AgentWidgetActionContext) as AgentWidgetActionHandlerResult | void;