@gram-ai/elements 1.19.0 → 1.20.0

package/src/contexts/ElementsProvider.tsx

@@ -14,7 +14,11 @@ import {
 import { recommended } from '@/plugins'
 import { ElementsConfig, Model } from '@/types'
 import { Plugin } from '@/types/plugins'
-import { AssistantRuntimeProvider } from '@assistant-ui/react'
+import {
+  AssistantRuntimeProvider,
+  AssistantTool,
+  unstable_useRemoteThreadListRuntime as useRemoteThreadListRuntime,
+} from '@assistant-ui/react'
 import {
   frontendTools as convertFrontendToolsToAISDKTools,
   useChatRuntime,
@@ -41,6 +45,7 @@ import {
 import { useAuth } from '../hooks/useAuth'
 import { ElementsContext } from './contexts'
 import { ToolApprovalProvider } from './ToolApprovalContext'
+import { useGramThreadListAdapter } from '@/hooks/useGramThreadListAdapter'
 
 export interface ElementsProviderProps {
   children: ReactNode
@@ -78,8 +83,8 @@ function cleanMessagesForModel(messages: UIMessage[]): UIMessage[] {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const cleanedParts = partsArray.map((part: any) => {
       // Strip providerOptions and providerMetadata from all remaining parts
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-vars
-      const { callProviderMetadata, ...cleanPart } = part
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const { callProviderMetadata: _, ...cleanPart } = part
       return cleanPart
     })
 
@@ -90,6 +95,10 @@ function cleanMessagesForModel(messages: UIMessage[]): UIMessage[] {
   })
 }
 
+/**
+ * Main provider component that sets up auth, tools, and transport.
+ * Delegates to either WithHistory or WithoutHistory based on config.
+ */
 const ElementsProviderWithApproval = ({
   children,
   config,
@@ -109,7 +118,6 @@ const ElementsProviderWithApproval = ({
   )
   const [isOpen, setIsOpen] = useState(config.modal?.defaultOpen)
 
-  // If there are any user provided plugins, use them, otherwise use the recommended plugins
   const plugins = config.plugins ?? recommended
 
   const systemPrompt = mergeInternalSystemPromptWith(
@@ -117,7 +125,7 @@ const ElementsProviderWithApproval = ({
     plugins
   )
 
-  const { data: mcpTools, isLoading: mcpToolsLoading } = useMCPTools({
+  const { data: mcpTools } = useMCPTools({
     auth,
     mcp: config.mcp,
     environment: config.environment ?? {},
@@ -160,8 +168,13 @@ const ElementsProviderWithApproval = ({
     }
   }, [config.tools?.toolsRequiringApproval, getApprovalHelpers])
 
-  // Create custom transport
-  const transport = useMemo<ChatTransport<UIMessage> | undefined>(
+  // Ref to access runtime from within transport's sendMessages.
+  // This solves a circular dependency: transport needs runtime.thread.getModelContext(),
+  // but runtime is created using transport. The ref gets populated after runtime creation.
+  const runtimeRef = useRef<ReturnType<typeof useChatRuntime> | null>(null)
+
+  // Create chat transport configuration
+  const transport = useMemo<ChatTransport<UIMessage>>(
     () => ({
       sendMessages: async ({ messages, abortSignal }) => {
         const usingCustomModel = !!config.languageModel
@@ -170,7 +183,7 @@ const ElementsProviderWithApproval = ({
           throw new Error('Session is loading')
         }
 
-        const context = runtime.thread.getModelContext()
+        const context = runtimeRef.current?.thread.getModelContext()
         const frontendTools = toAISDKTools(
           getEnabledTools(context?.tools ?? {})
         )
@@ -231,52 +244,160 @@ const ElementsProviderWithApproval = ({
         }
       },
       reconnectToStream: async () => {
-        // Not implemented for client-side streaming
         throw new Error('Stream reconnection not supported')
       },
     }),
     [
-      config,
       config.languageModel,
+      config.tools?.toolsRequiringApproval,
       model,
       systemPrompt,
       mcpTools,
-      mcpToolsLoading,
       getApprovalHelpers,
       apiUrl,
       auth.headers,
+      auth.isLoading,
     ]
   )
 
-  const runtime = useChatRuntime({
-    transport,
+  const historyEnabled = config.history?.enabled ?? false
+
+  // Shared context value for ElementsContext
+  const contextValue = useMemo(
+    () => ({
+      config,
+      setModel,
+      model,
+      isExpanded,
+      setIsExpanded,
+      isOpen: isOpen ?? false,
+      setIsOpen,
+      plugins,
+    }),
+    [config, model, isExpanded, isOpen, plugins]
+  )
+
+  const frontendTools = config.tools?.frontendTools ?? {}
+
+  // Render the appropriate runtime provider based on history config.
+  // We use separate components to avoid conditional hook calls.
+  if (historyEnabled && !auth.isLoading) {
+    return (
+      <ElementsProviderWithHistory
+        transport={transport}
+        apiUrl={apiUrl}
+        headers={auth.headers}
+        contextValue={contextValue}
+        runtimeRef={runtimeRef}
+        frontendTools={frontendTools}
+      >
+        {children}
+      </ElementsProviderWithHistory>
+    )
+  }
+
+  return (
+    <ElementsProviderWithoutHistory
+      transport={transport}
+      contextValue={contextValue}
+      runtimeRef={runtimeRef}
+      frontendTools={frontendTools}
+    >
+      {children}
+    </ElementsProviderWithoutHistory>
+  )
+}
+
+// Separate component for history-enabled mode to avoid conditional hook calls
+interface ElementsProviderWithHistoryProps {
+  children: ReactNode
+  transport: ChatTransport<UIMessage>
+  apiUrl: string
+  headers: Record<string, string>
+  contextValue: React.ContextType<typeof ElementsContext>
+  runtimeRef: React.RefObject<ReturnType<typeof useChatRuntime> | null>
+  frontendTools: Record<string, AssistantTool>
+}
+
+const ElementsProviderWithHistory = ({
+  children,
+  transport,
+  apiUrl,
+  headers,
+  contextValue,
+  runtimeRef,
+  frontendTools,
+}: ElementsProviderWithHistoryProps) => {
+  const threadListAdapter = useGramThreadListAdapter({ apiUrl, headers })
+
+  // Hook factory for creating the base chat runtime
+  const useChatRuntimeHook = useCallback(() => {
+    return useChatRuntime({ transport })
+  }, [transport])
+
+  const runtime = useRemoteThreadListRuntime({
+    adapter: threadListAdapter,
+    runtimeHook: useChatRuntimeHook,
   })
 
+  // Populate runtimeRef so transport can access thread context
+  useEffect(() => {
+    runtimeRef.current = runtime as ReturnType<typeof useChatRuntime>
+  }, [runtime, runtimeRef])
+
+  // Get the Provider from our adapter to wrap the content
+  const HistoryProvider =
+    threadListAdapter.unstable_Provider ??
+    (({ children }: { children: React.ReactNode }) => <>{children}</>)
+
   return (
     <AssistantRuntimeProvider runtime={runtime}>
-      <ElementsContext.Provider
-        value={{
-          config,
-          setModel,
-          model,
-          isExpanded,
-          setIsExpanded,
-          isOpen: isOpen ?? false,
-          setIsOpen,
-          plugins,
-        }}
-      >
-        {children}
+      <HistoryProvider>
+        <ElementsContext.Provider value={contextValue}>
+          {children}
+          <FrontendTools tools={frontendTools} />
+        </ElementsContext.Provider>
+      </HistoryProvider>
+    </AssistantRuntimeProvider>
+  )
+}
 
-        {/* Doesn't render anything, but is used to register frontend tools */}
-        <FrontendTools tools={config.tools?.frontendTools ?? {}} />
+// Separate component for non-history mode to avoid conditional hook calls
+interface ElementsProviderWithoutHistoryProps {
+  children: ReactNode
+  transport: ChatTransport<UIMessage>
+  contextValue: React.ContextType<typeof ElementsContext>
+  runtimeRef: React.RefObject<ReturnType<typeof useChatRuntime> | null>
+  frontendTools: Record<string, AssistantTool>
+}
+
+const ElementsProviderWithoutHistory = ({
+  children,
+  transport,
+  contextValue,
+  runtimeRef,
+  frontendTools,
+}: ElementsProviderWithoutHistoryProps) => {
+  const runtime = useChatRuntime({ transport })
+
+  // Populate runtimeRef so transport can access thread context
+  useEffect(() => {
+    runtimeRef.current = runtime
+  }, [runtime, runtimeRef])
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <ElementsContext.Provider value={contextValue}>
+        {children}
+        <FrontendTools tools={frontendTools} />
       </ElementsContext.Provider>
     </AssistantRuntimeProvider>
   )
 }
 
+const queryClient = new QueryClient()
+
 export const ElementsProvider = (props: ElementsProviderProps) => {
-  const queryClient = new QueryClient()
   return (
     <QueryClientProvider client={queryClient}>
       <ToolApprovalProvider>

package/src/hooks/useGramThreadListAdapter.tsx

@@ -0,0 +1,302 @@
+import {
+  unstable_RemoteThreadListAdapter as RemoteThreadListAdapter,
+  ThreadMessage,
+  RuntimeAdapterProvider,
+  ThreadHistoryAdapter,
+  useAssistantApi,
+  type AssistantApi,
+} from '@assistant-ui/react'
+import type { AssistantStream } from 'assistant-stream'
+import {
+  GramChatOverview,
+  GramChat,
+  convertGramMessagesToExported,
+} from '@/lib/messageConverter'
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type PropsWithChildren,
+} from 'react'
+
+export interface ThreadListAdapterOptions {
+  apiUrl: string
+  headers: Record<string, string>
+}
+
+interface ListChatsResponse {
+  chats: GramChatOverview[]
+}
+
+/**
+ * Thread history adapter that loads messages from Gram API.
+ * Note: We use `as ThreadHistoryAdapter` cast because the withFormat generic
+ * signature doesn't match our concrete implementation, but it works at runtime.
+ */
+class GramThreadHistoryAdapter {
+  private apiUrl: string
+  private headers: Record<string, string>
+  private store: AssistantApi
+
+  constructor(
+    apiUrl: string,
+    headers: Record<string, string>,
+    store: AssistantApi
+  ) {
+    this.apiUrl = apiUrl
+    this.headers = headers
+    this.store = store
+  }
+
+  async load() {
+    const remoteId = this.store.threadListItem().getState().remoteId
+    if (!remoteId) {
+      return { messages: [], headId: null }
+    }
+
+    try {
+      const response = await fetch(
+        `${this.apiUrl}/rpc/chat.load?id=${encodeURIComponent(remoteId)}`,
+        { headers: this.headers }
+      )
+
+      if (!response.ok) {
+        console.error('Failed to load chat:', response.status)
+        return { messages: [], headId: null }
+      }
+
+      const chat = (await response.json()) as GramChat
+      return convertGramMessagesToExported(chat.messages)
+    } catch (error) {
+      console.error('Error loading chat:', error)
+      return { messages: [], headId: null }
+    }
+  }
+
+  async append() {
+    // No-op: Gram persists messages server-side during streaming.
+  }
+
+  // Required by ThreadHistoryAdapter - wraps adapter with format conversion.
+  // The _formatAdapter param is part of the interface but unused since we handle conversion ourselves.
+  // Using arrow functions to capture `this` lexically.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  withFormat(_formatAdapter: unknown) {
+    return {
+      load: async () => {
+        const remoteId = this.store.threadListItem().getState().remoteId
+        if (!remoteId) {
+          return { messages: [], headId: null }
+        }
+
+        try {
+          const response = await fetch(
+            `${this.apiUrl}/rpc/chat.load?id=${encodeURIComponent(remoteId)}`,
+            { headers: this.headers }
+          )
+
+          if (!response.ok) {
+            console.error('Failed to load chat (withFormat):', response.status)
+            return { messages: [], headId: null }
+          }
+
+          const chat = (await response.json()) as GramChat
+
+          // Filter out system messages (assistant-ui doesn't support them in the import path)
+          const filteredMessages = chat.messages.filter(
+            (msg) => msg.role !== 'system'
+          )
+
+          if (filteredMessages.length === 0) {
+            return { messages: [], headId: null }
+          }
+
+          // Convert to the format expected by useExternalHistory
+          // It expects UIMessage format with role and parts array
+          let prevId: string | null = null
+          const messages = filteredMessages.map((msg, index) => {
+            // Generate a fallback ID if missing (required by assistant-ui's MessageRepository)
+            const messageId = msg.id || `fallback-${index}-${Date.now()}`
+            const uiMessage = {
+              parentId: prevId,
+              message: {
+                id: messageId,
+                role: msg.role as 'user' | 'assistant',
+                parts: [{ type: 'text' as const, text: msg.content || '' }],
+                createdAt: msg.createdAt ? new Date(msg.createdAt) : new Date(),
+              },
+            }
+            prevId = messageId
+            return uiMessage
+          })
+
+          return {
+            headId: prevId,
+            messages,
+          }
+        } catch (error) {
+          console.error('Error loading chat (withFormat):', error)
+          return { messages: [], headId: null }
+        }
+      },
+      append: async () => {
+        // No-op
+      },
+    }
+  }
+}
+
+/**
+ * Hook to create a Gram thread history adapter.
+ */
+function useGramThreadHistoryAdapter(
+  optionsRef: React.RefObject<ThreadListAdapterOptions>
+): ThreadHistoryAdapter {
+  const store = useAssistantApi()
+  const [adapter] = useState(
+    () =>
+      new GramThreadHistoryAdapter(
+        optionsRef.current.apiUrl,
+        optionsRef.current.headers,
+        store
+      )
+  )
+  // Cast to ThreadHistoryAdapter - the withFormat generic doesn't match but works at runtime
+  return adapter as unknown as ThreadHistoryAdapter
+}
+
+/**
+ * Hook that creates a RemoteThreadListAdapter for the Gram API.
+ * This properly handles React component identity for the Provider.
+ */
+export function useGramThreadListAdapter(
+  options: ThreadListAdapterOptions
+): RemoteThreadListAdapter {
+  const optionsRef = useRef(options)
+  useEffect(() => {
+    optionsRef.current = options
+  }, [options])
+
+  // Create stable Provider component using useCallback
+  const unstable_Provider = useCallback(function GramHistoryProvider({
+    children,
+  }: PropsWithChildren) {
+    const history = useGramThreadHistoryAdapter(optionsRef)
+    const adapters = useMemo(() => ({ history }), [history])
+    return (
+      <RuntimeAdapterProvider adapters={adapters}>
+        {children}
+      </RuntimeAdapterProvider>
+    )
+  }, [])
+
+  // Return adapter with stable methods
+  return useMemo(
+    () => ({
+      unstable_Provider,
+
+      async list() {
+        try {
+          const response = await fetch(
+            `${optionsRef.current.apiUrl}/rpc/chat.list`,
+            {
+              headers: optionsRef.current.headers,
+            }
+          )
+
+          if (!response.ok) {
+            console.error('Failed to list chats:', response.status)
+            return { threads: [] }
+          }
+
+          const data = (await response.json()) as ListChatsResponse
+          return {
+            threads: data.chats.map((chat) => ({
+              remoteId: chat.id,
+              externalId: chat.id,
+              status: 'regular' as const,
+              title: chat.title || 'New Chat',
+            })),
+          }
+        } catch (error) {
+          console.error('Error listing chats:', error)
+          return { threads: [] }
+        }
+      },
+
+      async initialize(threadId: string) {
+        return {
+          remoteId: threadId,
+          externalId: threadId,
+        }
+      },
+
+      async rename() {
+        // No-op
+      },
+
+      async archive() {
+        // No-op
+      },
+
+      async unarchive() {
+        // No-op
+      },
+
+      async delete() {
+        // No-op
+      },
+
+      async generateTitle(
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        _remoteId: string,
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        _messages: readonly ThreadMessage[]
+      ): Promise<AssistantStream> {
+        // Return an empty stream that immediately completes
+        // Server generates titles automatically, so we just provide a placeholder
+        return new ReadableStream({
+          start(controller) {
+            controller.close()
+          },
+        }) as AssistantStream
+      },
+
+      async fetch(threadId: string) {
+        try {
+          const response = await fetch(
+            `${optionsRef.current.apiUrl}/rpc/chat.load?id=${encodeURIComponent(threadId)}`,
+            {
+              headers: optionsRef.current.headers,
+            }
+          )
+
+          if (!response.ok) {
+            console.error('Failed to fetch thread:', response.status)
+            return {
+              remoteId: threadId,
+              status: 'regular' as const,
+            }
+          }
+
+          const chat = await response.json()
+          return {
+            remoteId: chat.id,
+            externalId: chat.id,
+            status: 'regular' as const,
+            title: chat.title || 'New Chat',
+          }
+        } catch (error) {
+          console.error('Error fetching thread:', error)
+          return {
+            remoteId: threadId,
+            status: 'regular' as const,
+          }
+        }
+      },
+    }),
+    [unstable_Provider]
+  )
+}

package/src/index.ts

@@ -3,10 +3,13 @@ import './global.css'
 
 // Context Providers
 export { ElementsProvider as GramElementsProvider } from './contexts/ElementsProvider'
+export { ElementsProvider } from './contexts/ElementsProvider'
 export { useElements as useGramElements } from './hooks/useElements'
+export { useElements } from './hooks/useElements'
 
 // Core Components
 export { Chat } from '@/components/Chat'
+export { ThreadList as ChatHistory } from '@/components/assistant-ui/thread-list'
 
 // Frontend Tools
 export { defineFrontendTool } from './lib/tools'
@@ -25,6 +28,7 @@ export type {
   Dimensions,
   ElementsConfig,
   GetSessionFn,
+  HistoryConfig,
   ModalConfig,
   ModalTriggerPosition,
   Model,