@applica-software-guru/persona-sdk 0.1.84 → 0.1.85

package/playground/src/hooks/theme.ts

@@ -0,0 +1,70 @@
+import { useCallback, useEffect, useState } from 'react';
+
+type Theme = 'light' | 'dark' | 'auto';
+const STORAGE_KEY = 'persona_theme_preference';
+
+function getSystemTheme(): 'light' | 'dark' {
+  if (typeof window === 'undefined' || !window.matchMedia) return 'light';
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+export function useColorScheme() {
+  const [theme, setTheme] = useState<Theme>(() => {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY);
+      return (stored as Theme) || 'auto';
+    } catch {
+      return 'auto';
+    }
+  });
+
+  const apply = useCallback((t: Theme) => {
+    const root = document.documentElement;
+    const effective = t === 'auto' ? getSystemTheme() : t;
+    if (effective === 'dark') root.classList.add('dark');
+    else root.classList.remove('dark');
+  }, []);
+
+  useEffect(() => {
+    // Apply on mount and whenever theme changes
+    apply(theme);
+
+    // Listen to system changes when in 'auto' mode
+    let mql: MediaQueryList | null = null;
+    const onChange = () => {
+      if (theme === 'auto') apply('auto');
+    };
+
+    if (typeof window !== 'undefined' && window.matchMedia) {
+      mql = window.matchMedia('(prefers-color-scheme: dark)');
+      if (mql.addEventListener) mql.addEventListener('change', onChange);
+      else mql.addListener(onChange as any);
+    }
+
+    return () => {
+      if (!mql) return;
+      if (mql.removeEventListener) mql.removeEventListener('change', onChange);
+      else mql.removeListener(onChange as any);
+    };
+  }, [theme, apply]);
+
+  const setThemeAndPersist = useCallback((t: Theme) => {
+    try {
+      localStorage.setItem(STORAGE_KEY, t);
+    } catch {}
+    setTheme(t);
+  }, []);
+
+  const toggle = useCallback(() => {
+    console.log('Toggling theme from');
+    setTheme((prev) => {
+      const next = prev === 'dark' ? 'light' : prev === 'light' ? 'auto' : 'dark';
+      try {
+        localStorage.setItem(STORAGE_KEY, next);
+      } catch {}
+      return next;
+    });
+  }, []);
+
+  return { theme, setTheme: setThemeAndPersist, toggle } as const;
+}

package/playground/src/hooks/use-mobile.ts

@@ -0,0 +1,19 @@
+import * as React from "react"
+
+const MOBILE_BREAKPOINT = 768
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    }
+    mql.addEventListener("change", onChange)
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    return () => mql.removeEventListener("change", onChange)
+  }, [])
+
+  return !!isMobile
+}

package/src/index.ts

@@ -3,3 +3,4 @@ export * from './logging';
 export * from './protocol';
 export * from './types';
 export * from './tools';
+export * from './storage';

package/src/messages.ts

@@ -1,5 +1,30 @@
 import { PersonaMessage } from './types';
-import { FileMessagePart, ThreadMessageLike } from '@assistant-ui/react';
+import { FileMessagePart, ThreadMessageLike, MessageStatus } from '@assistant-ui/react';
+
+let messageIdCounter = 0;
+
+export function generateMessageId(): string {
+  return `msg_${Date.now()}_${messageIdCounter++}`;
+}
+
+export function ensureMessageId(message: PersonaMessage): PersonaMessage {
+  // Convert thought to reasoning type
+  if (message.thought) {
+    message = { ...message, type: 'reasoning' };
+  }
+
+  if (!message.id) {
+    return {
+      ...message,
+      id: generateMessageId(),
+      createdAt: message.createdAt || new Date(),
+    };
+  }
+  if (!message.createdAt) {
+    return { ...message, createdAt: new Date() };
+  }
+  return message;
+}
 
 function removeEmptyMessages(messages: PersonaMessage[]): PersonaMessage[] {
   return messages.filter((message) => {
@@ -13,10 +38,14 @@ function parseMessages(messages: PersonaMessage[]): PersonaMessage[] {
   const outputMessages: PersonaMessage[] = [];
   let currentMessage: PersonaMessage | null = null;
 
-  for (const message of messages) {
+  for (let message of messages) {
+    // Ensure every message has an ID
+    message = ensureMessageId(message);
+
     if (message.type === 'transaction') {
       continue;
     }
+
     if (message.file) {
       if (currentMessage) {
         outputMessages.push(currentMessage);
@@ -39,11 +68,20 @@ function parseMessages(messages: PersonaMessage[]): PersonaMessage[] {
       currentMessage &&
       message.type === currentMessage.type &&
       message.protocol === currentMessage.protocol &&
-      currentMessage.role === message.role
+      currentMessage.role === message.role &&
+      // CRITICAL: Only merge if the new message has the same ID (streaming chunks)
+      // OR if the current message doesn't have a finishReason yet (still streaming)
+      // This preserves branches while allowing streaming to work
+      (message.id === currentMessage.id || !currentMessage.finishReason)
     ) {
+      // Merge streaming chunks
       currentMessage.text += message.text;
       currentMessage.file = currentMessage.file || message.file;
+      currentMessage.finishReason = message.finishReason || currentMessage.finishReason;
+      // Keep the ID of the first chunk
+      currentMessage.id = currentMessage.id || message.id;
     } else {
+      // Different message or current is complete - don't merge
       if (currentMessage) {
         outputMessages.push(currentMessage);
       }
@@ -73,29 +111,81 @@ function convertMessage(message: PersonaMessage): ThreadMessageLike {
       ]
     : [];
 
+  // Determine message status for assistant messages
+  let messageStatus: MessageStatus | undefined;
+
+  if (message.role === 'assistant' || message.role === 'function') {
+    if (message.status) {
+      // Use existing status if provided
+      messageStatus = message.status as any;
+    } else if (message.finishReason === 'stop') {
+      messageStatus = { type: 'complete', reason: 'stop' } as const;
+    } else if (message.finishReason === 'function_call') {
+      messageStatus = { type: 'complete', reason: 'stop' } as const;
+    } else if (!message.finishReason) {
+      // Message is still being generated - this will trigger optimistic updates
+      messageStatus = undefined; // Let the runtime handle in-progress state
+    }
+  }
+
+  // Handle function/tool calls
   if (message.role === 'function') {
-    return {
+    const result: ThreadMessageLike = {
       id: message.id!,
       role: 'assistant',
-      status: message?.functionResponse === null ? { type: 'running' } : { type: 'complete', reason: 'stop' },
+      createdAt: message.createdAt,
       content:
         message.functionCalls?.map((call) => ({
           type: 'tool-call',
           toolName: call.name,
-          toolCallId: call.id,
+          toolCallId: call.id || `tool_${Date.now()}`,
           args: call.args,
           result: message.functionResponse?.result,
         })) ?? [],
+      metadata: {
+        ...message.metadata,
+        custom: {
+          protocol: message.protocol,
+          sessionId: message.sessionId,
+          sources: message.sources,
+          ...message.metadata?.custom,
+        },
+      },
     };
+
+    if (messageStatus) {
+      return { ...result, status: messageStatus };
+    }
+    return result;
   }
-  return {
+
+  // Handle regular messages
+  const baseMessage: ThreadMessageLike = {
     id: message.id!,
     role: message.role,
+    createdAt: message.createdAt,
     content:
       message.type === 'reasoning'
-        ? [{ type: 'reasoning', text: message.text }, ...files]
+        ? [{ type: 'reasoning' as any, text: message.text }, ...files]
         : [{ type: 'text', text: message.text }, ...files],
+    metadata: {
+      ...message.metadata,
+      custom: {
+        protocol: message.protocol,
+        sessionId: message.sessionId,
+        sources: message.sources,
+        type: message.type,
+        ...message.metadata?.custom,
+      },
+    },
   };
+
+  // Add status only for assistant messages
+  if (message.role === 'assistant' && messageStatus) {
+    return { ...baseMessage, status: messageStatus };
+  }
+
+  return baseMessage;
 }
 
 export { parseMessages, convertMessage, removeEmptyMessages };

package/src/protocol/webrtc.ts

@@ -124,6 +124,7 @@ class PersonaWebRTCClient {
       const metadata = {
         apiKey: this.config.apiKey,
         agentId: this.config.agentId,
+        userId: this.config.userId || 'anonymous',
         sessionCode: session as string,
       };
       this.config.logger?.debug('Opening connection to WebRTC server: ', metadata);

package/src/protocol/websocket.ts

@@ -49,7 +49,10 @@ class PersonaWebSocketProtocol extends PersonaProtocolBase {
 
     const apiKey = encodeURIComponent(this.config.apiKey);
     const agentId = this.config.agentId;
-    const webSocketUrl = `${this.config.webSocketUrl}?sessionCode=${sid}&agentId=${agentId}&apiKey=${apiKey}`;
+    const userId = this.config.userId || 'anonymous';
+    const webSocketUrl = `${this.config.webSocketUrl}?sessionCode=${sid}&agentId=${agentId}&apiKey=${apiKey}&userId=${encodeURIComponent(
+      userId,
+    )}`;
     this.setStatus('connecting');
     this.webSocket = new WebSocket(webSocketUrl);
     this.webSocket.addEventListener('open', () => {
@@ -87,7 +90,7 @@ class PersonaWebSocketProtocol extends PersonaProtocolBase {
   public disconnect(): Promise<void> {
     this.config.logger?.debug('Disconnecting WebSocket');
     if (this.webSocket && this.status === 'connected') {
-      this.webSocket.close();
+      this.webSocket.close(1000, 'Normal closure');
       this.setStatus('disconnected');
       this.webSocket = null;
     }

package/src/runtime/context.ts

@@ -0,0 +1,88 @@
+import { createContext, useContext } from 'react';
+import { PersonaProtocol, ProtocolStatus } from '../types';
+import { PersonaMessage } from '../types';
+import { PersonaWebRTCProtocol } from '../protocol';
+import { getFirstAvailableProtocolEndpoint } from './utils';
+
+export type PersonaRuntimeContextType = {
+  protocols: PersonaProtocol[];
+  protocolsStatus: Map<string, ProtocolStatus>;
+  getMessages: () => PersonaMessage[];
+};
+
+export const PersonaRuntimeContext = createContext<PersonaRuntimeContextType | undefined>(undefined);
+
+/**
+ * Hook to access the PersonaRuntime context
+ */
+export function usePersonaRuntime(): PersonaRuntimeContextType {
+  const context = useContext(PersonaRuntimeContext);
+  if (!context) {
+    throw new Error('usePersonaRuntime must be used within a PersonaRuntimeProvider');
+  }
+  return context;
+}
+
+/**
+ * Retrieves a specific protocol instance from the PersonaRuntimeContext.
+ *
+ * @param protocol - The name of the protocol to use.
+ * @returns {PersonaProtocol | null} - The protocol instance or null if not found.
+ * @throws {Error} - If the hook is used outside of a PersonaRuntimeProvider.
+ */
+export function usePersonaRuntimeProtocol(protocol: string): PersonaProtocol | null {
+  const context = useContext(PersonaRuntimeContext);
+  if (!context) {
+    throw new Error('usePersonaRuntimeProtocol must be used within a PersonaRuntimeProvider');
+  }
+
+  const protocolInstance = context.protocols.find((p) => p.getName() === protocol);
+  if (!protocolInstance) {
+    return null;
+  }
+
+  const status = context.protocolsStatus.get(protocolInstance.getName());
+
+  return {
+    ...protocolInstance,
+    connect: protocolInstance.connect.bind(protocolInstance),
+    disconnect: protocolInstance.disconnect.bind(protocolInstance),
+    sendPacket: protocolInstance.sendPacket.bind(protocolInstance),
+    setSession: protocolInstance.setSession.bind(protocolInstance),
+    addStatusChangeListener: protocolInstance.addStatusChangeListener.bind(protocolInstance),
+    addPacketListener: protocolInstance.addPacketListener.bind(protocolInstance),
+    getName: protocolInstance.getName.bind(protocolInstance),
+    getPriority: protocolInstance.getPriority.bind(protocolInstance),
+    status: status || protocolInstance.status,
+  };
+}
+
+/**
+ * Gets the endpoint URL of the first available protocol
+ */
+export function usePersonaRuntimeEndpoint(): string | null {
+  const context = useContext(PersonaRuntimeContext);
+  if (!context) {
+    throw new Error('usePersonaRuntimeEndpoint must be used within a PersonaRuntimeProvider');
+  }
+
+  return getFirstAvailableProtocolEndpoint(context.protocols);
+}
+
+/**
+ * Gets the WebRTC protocol instance
+ */
+export function usePersonaRuntimeWebRTCProtocol(): PersonaWebRTCProtocol | null {
+  return usePersonaRuntimeProtocol('webrtc') as PersonaWebRTCProtocol;
+}
+
+/**
+ * Gets all messages from the current conversation
+ */
+export function usePersonaRuntimeMessages(): PersonaMessage[] {
+  const context = useContext(PersonaRuntimeContext);
+  if (!context) {
+    throw new Error('usePersonaRuntimeMessages must be used within a PersonaRuntimeProvider');
+  }
+  return context.getMessages();
+}

package/src/runtime/handlers.ts

@@ -0,0 +1,276 @@
+import { AppendMessage } from '@assistant-ui/react';
+import { StartRunConfig } from '@assistant-ui/react/dist/legacy-runtime/runtime-cores/core/ThreadRuntimeCore';
+import { PersonaProtocol, PersonaMessage, TransformMessages } from '../types';
+import type { PersonaLogger } from '../logging';
+import { parseMessages } from '../messages';
+import { fileToBase64 } from './utils';
+
+/**
+ * Creates the onNew handler for new messages
+ */
+export function createOnNewHandler(
+  protocols: PersonaProtocol[],
+  setMessages: React.Dispatch<React.SetStateAction<PersonaMessage[]>>,
+  setIsRunning: React.Dispatch<React.SetStateAction<boolean>>,
+  transformMessages?: TransformMessages,
+  logger?: PersonaLogger,
+) {
+  return async (message: AppendMessage) => {
+    if (message.content[0]?.type !== 'text') {
+      throw new Error('Only text messages are supported');
+    }
+
+    const ready = protocols.some((protocol) => protocol.getName() !== 'transaction' && protocol.status === 'connected');
+
+    if (!ready) {
+      setMessages((currentConversation) => {
+        const errorMessage: PersonaMessage = {
+          role: 'assistant',
+          type: 'text',
+          text: 'No protocol is connected.',
+          createdAt: new Date(),
+          finishReason: 'stop',
+        };
+        const newMessages = [...currentConversation, errorMessage];
+        return transformMessages ? transformMessages(newMessages) : newMessages;
+      });
+      return;
+    }
+
+    const input = message.content[0].text;
+    const userMessage: PersonaMessage = {
+      role: 'user',
+      type: 'text',
+      text: input,
+      createdAt: new Date(),
+    };
+
+    setMessages((currentConversation) => {
+      const newMessages = parseMessages([...currentConversation, userMessage]);
+      return transformMessages ? transformMessages(newMessages) : newMessages;
+    });
+
+    setIsRunning(true);
+
+    const protocol = protocols.sort((a, b) => b.getPriority() - a.getPriority()).find((protocol) => protocol.status === 'connected');
+
+    const content: Array<PersonaMessage> = [];
+
+    if (message.attachments) {
+      for (const attachment of message.attachments) {
+        if (attachment.contentType.startsWith('image/') && attachment.file) {
+          content.push({
+            role: 'user',
+            image: {
+              contentType: attachment.contentType,
+              content: await fileToBase64(attachment.file),
+            },
+            text: '',
+            type: 'text',
+            createdAt: new Date(),
+          });
+        }
+      }
+    }
+
+    if (message.content) {
+      content.push({
+        role: 'user',
+        text: message.content[0].text,
+        type: 'text',
+        createdAt: new Date(),
+      });
+    }
+
+    logger?.debug('Sending message:', content);
+    await protocol?.sendPacket({ type: 'request', payload: content });
+  };
+}
+
+/**
+ * Creates the onEdit handler for editing messages
+ */
+export function createOnEditHandler(
+  protocols: PersonaProtocol[],
+  messages: PersonaMessage[],
+  setMessages: React.Dispatch<React.SetStateAction<PersonaMessage[]>>,
+  setIsRunning: React.Dispatch<React.SetStateAction<boolean>>,
+  transformMessages?: TransformMessages,
+  logger?: PersonaLogger,
+) {
+  return async (message: AppendMessage) => {
+    if (message.content[0]?.type !== 'text') {
+      throw new Error('Only text messages are supported');
+    }
+
+    const protocol = protocols.sort((a, b) => b.getPriority() - a.getPriority()).find((protocol) => protocol.status === 'connected');
+
+    if (!protocol) {
+      logger?.debug('No protocol available for edit');
+      return;
+    }
+
+    const parentId = message.parentId;
+    if (!parentId) {
+      logger?.debug('No parent ID provided for edit');
+      return;
+    }
+
+    const parentIndex = messages.findIndex((m) => m.id === parentId);
+    if (parentIndex === -1) {
+      logger?.debug('Parent message not found:', parentId);
+      return;
+    }
+
+    const messagesToKeep = messages.slice(0, parentIndex + 1);
+    const editedMessage: PersonaMessage = {
+      role: 'user',
+      text: message.content[0].text,
+      type: 'text',
+      createdAt: new Date(),
+    };
+
+    const newMessages = parseMessages([...messagesToKeep, editedMessage]);
+    setMessages(transformMessages ? transformMessages(newMessages) : newMessages);
+
+    setIsRunning(true);
+
+    const content: Array<PersonaMessage> = [
+      {
+        role: 'user',
+        text: message.content[0].text,
+        type: 'text',
+        createdAt: new Date(),
+      },
+    ];
+
+    logger?.debug('Sending edited message:', content);
+    await protocol.sendPacket({ type: 'request', payload: content });
+  };
+}
+
+/**
+ * Creates the onReload handler for regenerating messages
+ */
+export function createOnReloadHandler(
+  protocols: PersonaProtocol[],
+  messages: PersonaMessage[],
+  setMessages: React.Dispatch<React.SetStateAction<PersonaMessage[]>>,
+  setIsRunning: React.Dispatch<React.SetStateAction<boolean>>,
+  transformMessages?: TransformMessages,
+  logger?: PersonaLogger,
+) {
+  return async (parentId: string | null, config: StartRunConfig) => {
+    const protocol = protocols.sort((a, b) => b.getPriority() - a.getPriority()).find((protocol) => protocol.status === 'connected');
+
+    if (!protocol) {
+      logger?.debug('No protocol available for reload');
+      return;
+    }
+
+    const actualParentId = config.parentId ?? parentId;
+    if (!actualParentId) {
+      logger?.debug('No parent ID provided for reload');
+      return;
+    }
+
+    const parentIndex = messages.findIndex((msg) => msg.id === actualParentId);
+    if (parentIndex === -1) {
+      logger?.debug('Parent message not found:', actualParentId);
+      return;
+    }
+
+    const parentMessage = messages[parentIndex];
+
+    setMessages((currentMessages) => {
+      const messagesToKeep = currentMessages.slice(0, parentIndex + 1);
+      return transformMessages ? transformMessages(messagesToKeep) : messagesToKeep;
+    });
+
+    let userMessage: PersonaMessage | undefined;
+    if (parentMessage.role === 'assistant' || parentMessage.role === 'function') {
+      for (let i = parentIndex - 1; i >= 0; i--) {
+        if (messages[i].role === 'user') {
+          userMessage = messages[i];
+          break;
+        }
+      }
+    } else if (parentMessage.role === 'user') {
+      userMessage = parentMessage;
+    }
+
+    if (!userMessage) {
+      logger?.debug('No user message found to regenerate from');
+      return;
+    }
+
+    setIsRunning(true);
+
+    const content: Array<PersonaMessage> = [];
+
+    if (userMessage.image) {
+      content.push({
+        role: 'user',
+        image: userMessage.image,
+        text: '',
+        type: 'text',
+        createdAt: new Date(),
+      });
+    }
+
+    content.push({
+      role: 'user',
+      text: userMessage.text,
+      type: 'text',
+      createdAt: new Date(),
+    });
+
+    logger?.debug('Regenerating message with config:', {
+      actualParentId,
+      sourceId: config.sourceId,
+      custom: config.runConfig.custom,
+    });
+    await protocol.sendPacket({ type: 'request', payload: content });
+  };
+}
+
+/**
+ * Creates the onCancel handler for cancelling message generation
+ */
+export function createOnCancelHandler(
+  protocols: PersonaProtocol[],
+  setMessages: React.Dispatch<React.SetStateAction<PersonaMessage[]>>,
+  setIsRunning: React.Dispatch<React.SetStateAction<boolean>>,
+  transformMessages?: TransformMessages,
+) {
+  return () => {
+    setIsRunning(false);
+
+    setMessages((currentMessages) => {
+      const lastMessage = currentMessages[currentMessages.length - 1];
+      if (lastMessage?.role === 'assistant' && !lastMessage.finishReason) {
+        const updatedMessages = [...currentMessages];
+        updatedMessages[updatedMessages.length - 1] = {
+          ...lastMessage,
+          finishReason: 'stop',
+          status: { type: 'incomplete' },
+        };
+        return transformMessages ? transformMessages(updatedMessages) : updatedMessages;
+      }
+      return currentMessages;
+    });
+
+    protocols.forEach((protocol) => {
+      if (protocol.status === 'connected') {
+        protocol
+          .sendPacket({
+            type: 'command',
+            payload: { command: 'set_initial_context', arguments: { cancel: true } },
+          })
+          .catch(() => {});
+      }
+    });
+
+    return Promise.resolve();
+  };
+}

package/src/runtime/index.ts

@@ -0,0 +1,6 @@
+export * from './context';
+export * from './utils';
+export * from './protocols';
+export * from './handlers';
+export * from './listeners';
+export * from './threads';