@gram-ai/elements 1.22.5 → 1.23.0

package/src/contexts/ConnectionStatusContext.tsx

@@ -0,0 +1,158 @@
+'use client'
+
+import {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  useRef,
+  useEffect,
+  type ReactNode,
+} from 'react'
+
+export type ConnectionState = 'connected' | 'reconnecting' | 'disconnected'
+
+interface ConnectionStatusContextValue {
+  /** Current connection state */
+  state: ConnectionState
+  /** Number of reconnection attempts */
+  retryCount: number
+  /** Whether the browser reports being online */
+  isOnline: boolean
+  /** Mark connection as failed - will trigger reconnecting state */
+  markDisconnected: () => void
+  /** Mark connection as restored */
+  markConnected: () => void
+  /** Reset the connection state */
+  reset: () => void
+}
+
+const ConnectionStatusContext =
+  createContext<ConnectionStatusContextValue | null>(null)
+
+interface ConnectionStatusProviderProps {
+  children: ReactNode
+}
+
+export const ConnectionStatusProvider = ({
+  children,
+}: ConnectionStatusProviderProps) => {
+  const [state, setState] = useState<ConnectionState>('connected')
+  const [retryCount, setRetryCount] = useState(0)
+  const [isOnline, setIsOnline] = useState(
+    typeof navigator !== 'undefined' ? navigator.onLine : true
+  )
+  const reconnectTimeoutRef = useRef<NodeJS.Timeout | null>(null)
+
+  // Monitor browser online/offline status
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+
+    const handleOnline = () => {
+      setIsOnline(true)
+
+      // Clear any existing timeout
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current)
+        reconnectTimeoutRef.current = null
+      }
+
+      // Show "Reconnecting..." briefly, then mark as connected
+      setState('reconnecting')
+      reconnectTimeoutRef.current = setTimeout(() => {
+        setState('connected')
+        setRetryCount(0)
+      }, 1500) // Show reconnecting for 1.5s before clearing
+    }
+
+    const handleOffline = () => {
+      setIsOnline(false)
+      // Immediately mark as disconnected when browser goes offline
+      setState('disconnected')
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current)
+        reconnectTimeoutRef.current = null
+      }
+    }
+
+    window.addEventListener('online', handleOnline)
+    window.addEventListener('offline', handleOffline)
+
+    return () => {
+      window.removeEventListener('online', handleOnline)
+      window.removeEventListener('offline', handleOffline)
+      // Clear any pending timeout to prevent memory leak
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current)
+        reconnectTimeoutRef.current = null
+      }
+    }
+  }, [])
+
+  const markDisconnected = useCallback(() => {
+    setState('reconnecting')
+    setRetryCount((prev) => prev + 1)
+
+    // After 10 seconds of reconnecting, mark as fully disconnected
+    if (reconnectTimeoutRef.current) {
+      clearTimeout(reconnectTimeoutRef.current)
+    }
+    reconnectTimeoutRef.current = setTimeout(() => {
+      setState((current) =>
+        current === 'reconnecting' ? 'disconnected' : current
+      )
+    }, 10000)
+  }, [])
+
+  const markConnected = useCallback(() => {
+    if (reconnectTimeoutRef.current) {
+      clearTimeout(reconnectTimeoutRef.current)
+      reconnectTimeoutRef.current = null
+    }
+    setState('connected')
+    setRetryCount(0)
+  }, [])
+
+  const reset = useCallback(() => {
+    if (reconnectTimeoutRef.current) {
+      clearTimeout(reconnectTimeoutRef.current)
+      reconnectTimeoutRef.current = null
+    }
+    setState('connected')
+    setRetryCount(0)
+  }, [])
+
+  return (
+    <ConnectionStatusContext.Provider
+      value={{
+        state,
+        retryCount,
+        isOnline,
+        markDisconnected,
+        markConnected,
+        reset,
+      }}
+    >
+      {children}
+    </ConnectionStatusContext.Provider>
+  )
+}
+
+export const useConnectionStatus = () => {
+  const context = useContext(ConnectionStatusContext)
+  if (!context) {
+    throw new Error(
+      'useConnectionStatus must be used within a ConnectionStatusProvider'
+    )
+  }
+  return context
+}
+
+/**
+ * Hook that returns connection status helpers for use in sendMessages.
+ * Returns null if not within a ConnectionStatusProvider (for backwards compatibility).
+ */
+
+export const useConnectionStatusOptional = () => {
+  return useContext(ConnectionStatusContext)
+}

package/src/contexts/ElementsProvider.tsx

@@ -54,6 +54,39 @@ import {
 import { useAuth } from '../hooks/useAuth'
 import { ElementsContext } from './contexts'
 import { ToolApprovalProvider } from './ToolApprovalContext'
+import {
+  ConnectionStatusProvider,
+  useConnectionStatusOptional,
+} from './ConnectionStatusContext'
+import { ToolExecutionProvider } from './ToolExecutionContext'
+
+/**
+ * Extracts executable tools from frontend tool definitions.
+ * Frontend tools created via defineFrontendTool have an unstable_tool property
+ * that contains the tool definition with execute function.
+ */
+function extractExecutableTools(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  frontendTools: Record<string, FrontendTool<any, any>> | undefined
+): Record<
+  string,
+  { execute?: (args: unknown, options?: unknown) => Promise<unknown> }
+> {
+  if (!frontendTools) return {}
+
+  return Object.fromEntries(
+    Object.entries(frontendTools).map(([name, tool]) => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const toolDef = (tool as any).unstable_tool
+      return [
+        name,
+        {
+          execute: toolDef?.execute,
+        },
+      ]
+    })
+  )
+}
 
 export interface ElementsProviderProps {
   children: ReactNode
@@ -159,6 +192,9 @@ const ElementsProviderInner = ({ children, config }: ElementsProviderProps) => {
     whitelistTool: toolApproval.whitelistTool,
   })
 
+  // Connection status for tracking network failures
+  const connectionStatus = useConnectionStatusOptional()
+
   approvalHelpersRef.current = {
     requestApproval: toolApproval.requestApproval,
     isToolApproved: toolApproval.isToolApproved,
@@ -312,13 +348,47 @@ const ElementsProviderInner = ({ children, config }: ElementsProviderProps) => {
             onError: ({ error }) => {
               console.error('Stream error in onError callback:', error)
               trackError(error, { source: 'streaming' })
+
+              // Check if this is a network/connection error
+              const isNetworkError =
+                error instanceof TypeError ||
+                (error instanceof Error &&
+                  (error.message.includes('fetch') ||
+                    error.message.includes('network') ||
+                    error.message.includes('Failed to fetch') ||
+                    error.message.includes('NetworkError') ||
+                    error.message.includes('ECONNREFUSED') ||
+                    error.message.includes('ETIMEDOUT')))
+
+              if (isNetworkError) {
+                connectionStatus?.markDisconnected()
+              }
             },
           })
 
+          // Mark as connected when stream starts successfully
+          connectionStatus?.markConnected()
+
           return result.toUIMessageStream()
         } catch (error) {
           console.error('Error creating stream:', error)
           trackError(error, { source: 'stream-creation' })
+
+          // Check if this is a network/connection error
+          const isNetworkError =
+            error instanceof TypeError ||
+            (error instanceof Error &&
+              (error.message.includes('fetch') ||
+                error.message.includes('network') ||
+                error.message.includes('Failed to fetch') ||
+                error.message.includes('NetworkError') ||
+                error.message.includes('ECONNREFUSED') ||
+                error.message.includes('ETIMEDOUT')))
+
+          if (isNetworkError) {
+            connectionStatus?.markDisconnected()
+          }
+
           throw error
         }
       },
@@ -336,6 +406,7 @@ const ElementsProviderInner = ({ children, config }: ElementsProviderProps) => {
       apiUrl,
       auth.headers,
       auth.isLoading,
+      connectionStatus,
     ]
   )
 
@@ -359,6 +430,24 @@ const ElementsProviderInner = ({ children, config }: ElementsProviderProps) => {
 
   const frontendTools = config.tools?.frontendTools ?? {}
 
+  // Create combined executable tools for direct tool execution (ActionButton)
+  // Uses a simplified type that focuses on the execute function
+  type ExecutableToolSet = Record<
+    string,
+    | { execute?: (args: unknown, options?: unknown) => Promise<unknown> }
+    | undefined
+  >
+  const executableTools = useMemo<ExecutableToolSet>(() => {
+    const extractedFrontendTools = extractExecutableTools(
+      config.tools?.frontendTools
+    )
+    // MCP tools and extracted frontend tools both have execute functions
+    return {
+      ...mcpTools,
+      ...extractedFrontendTools,
+    } as ExecutableToolSet
+  }, [mcpTools, 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) {
@@ -372,6 +461,7 @@ const ElementsProviderInner = ({ children, config }: ElementsProviderProps) => {
         frontendTools={frontendTools}
         localIdToUuidMap={localIdToUuidMapRef.current}
         currentRemoteIdRef={currentRemoteIdRef}
+        executableTools={executableTools}
       >
         {children}
       </ElementsProviderWithHistory>
@@ -384,12 +474,20 @@ const ElementsProviderInner = ({ children, config }: ElementsProviderProps) => {
       contextValue={contextValue}
       runtimeRef={runtimeRef}
       frontendTools={frontendTools}
+      executableTools={executableTools}
     >
       {children}
     </ElementsProviderWithoutHistory>
   )
 }
 
+// Shared type for executable tools
+type ExecutableToolSet = Record<
+  string,
+  | { execute?: (args: unknown, options?: unknown) => Promise<unknown> }
+  | undefined
+>
+
 // Separate component for history-enabled mode to avoid conditional hook calls
 interface ElementsProviderWithHistoryProps {
   children: ReactNode
@@ -402,6 +500,7 @@ interface ElementsProviderWithHistoryProps {
   frontendTools: Record<string, AssistantTool | FrontendTool<any, any>>
   localIdToUuidMap: Map<string, string>
   currentRemoteIdRef: React.RefObject<string | null>
+  executableTools: ExecutableToolSet
 }
 
 /**
@@ -432,6 +531,7 @@ const ElementsProviderWithHistory = ({
   frontendTools,
   localIdToUuidMap,
   currentRemoteIdRef,
+  executableTools,
 }: ElementsProviderWithHistoryProps) => {
   const threadListAdapter = useGramThreadListAdapter({
     apiUrl,
@@ -480,17 +580,19 @@ const ElementsProviderWithHistory = ({
       <ThreadIdSync remoteIdRef={currentRemoteIdRef} />
       <HistoryProvider>
         <ElementsContext.Provider value={contextValue}>
-          <div
-            className={cn(
-              ROOT_SELECTOR,
-              (contextValue?.config.variant === 'standalone' ||
-                contextValue?.config.variant === 'sidecar') &&
-                'h-full'
-            )}
-          >
-            {children}
-          </div>
-          <FrontendTools tools={frontendTools} />
+          <ToolExecutionProvider tools={executableTools}>
+            <div
+              className={cn(
+                ROOT_SELECTOR,
+                (contextValue?.config.variant === 'standalone' ||
+                  contextValue?.config.variant === 'sidecar') &&
+                  'h-full'
+              )}
+            >
+              {children}
+            </div>
+            <FrontendTools tools={frontendTools} />
+          </ToolExecutionProvider>
         </ElementsContext.Provider>
       </HistoryProvider>
     </AssistantRuntimeProvider>
@@ -505,6 +607,7 @@ interface ElementsProviderWithoutHistoryProps {
   runtimeRef: React.RefObject<ReturnType<typeof useChatRuntime> | null>
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   frontendTools: Record<string, AssistantTool | FrontendTool<any, any>>
+  executableTools: ExecutableToolSet
 }
 
 const ElementsProviderWithoutHistory = ({
@@ -513,6 +616,7 @@ const ElementsProviderWithoutHistory = ({
   contextValue,
   runtimeRef,
   frontendTools,
+  executableTools,
 }: ElementsProviderWithoutHistoryProps) => {
   const runtime = useChatRuntime({ transport })
 
@@ -524,17 +628,19 @@ const ElementsProviderWithoutHistory = ({
   return (
     <AssistantRuntimeProvider runtime={runtime}>
       <ElementsContext.Provider value={contextValue}>
-        <div
-          className={cn(
-            ROOT_SELECTOR,
-            (contextValue?.config.variant === 'standalone' ||
-              contextValue?.config.variant === 'sidecar') &&
-              'h-full'
-          )}
-        >
-          {children}
-        </div>
-        <FrontendTools tools={frontendTools} />
+        <ToolExecutionProvider tools={executableTools}>
+          <div
+            className={cn(
+              ROOT_SELECTOR,
+              (contextValue?.config.variant === 'standalone' ||
+                contextValue?.config.variant === 'sidecar') &&
+                'h-full'
+            )}
+          >
+            {children}
+          </div>
+          <FrontendTools tools={frontendTools} />
+        </ToolExecutionProvider>
       </ElementsContext.Provider>
     </AssistantRuntimeProvider>
   )
@@ -545,9 +651,11 @@ const queryClient = new QueryClient()
 export const ElementsProvider = (props: ElementsProviderProps) => {
   return (
     <QueryClientProvider client={queryClient}>
-      <ToolApprovalProvider>
-        <ElementsProviderInner {...props} />
-      </ToolApprovalProvider>
+      <ConnectionStatusProvider>
+        <ToolApprovalProvider>
+          <ElementsProviderInner {...props} />
+        </ToolApprovalProvider>
+      </ConnectionStatusProvider>
     </QueryClientProvider>
   )
 }

package/src/contexts/ToolExecutionContext.tsx

@@ -0,0 +1,101 @@
+'use client'
+
+import { createContext, useContext, useCallback, ReactNode } from 'react'
+
+// Define a minimal tool type for direct execution
+// This avoids strict AI SDK type requirements while still being type-safe
+interface ExecutableTool {
+  execute?: (args: unknown, options?: unknown) => Promise<unknown>
+}
+
+type ExecutableToolSet = Record<string, ExecutableTool | undefined>
+
+export interface ToolExecutionResult {
+  success: boolean
+  result?: unknown
+  error?: string
+}
+
+interface ToolExecutionContextValue {
+  executeTool: (
+    toolName: string,
+    args: Record<string, unknown>
+  ) => Promise<ToolExecutionResult>
+  isToolAvailable: (toolName: string) => boolean
+}
+
+const ToolExecutionContext = createContext<ToolExecutionContextValue | null>(
+  null
+)
+
+interface ToolExecutionProviderProps {
+  children: ReactNode
+  tools: ExecutableToolSet | undefined
+}
+
+export function ToolExecutionProvider({
+  children,
+  tools,
+}: ToolExecutionProviderProps) {
+  const executeTool = useCallback(
+    async (
+      toolName: string,
+      args: Record<string, unknown>
+    ): Promise<ToolExecutionResult> => {
+      if (!tools) {
+        return { success: false, error: 'Tools not available' }
+      }
+
+      const tool = tools[toolName]
+      if (!tool) {
+        return { success: false, error: `Tool "${toolName}" not found` }
+      }
+
+      if (!tool.execute) {
+        return {
+          success: false,
+          error: `Tool "${toolName}" has no execute function`,
+        }
+      }
+
+      try {
+        // Generate a unique toolCallId for this execution
+        const toolCallId = `action-${Date.now()}-${Math.random().toString(36).slice(2)}`
+        const result = await tool.execute(args, { toolCallId, messages: [] })
+        return { success: true, result }
+      } catch (err) {
+        const errorMessage =
+          err instanceof Error ? err.message : 'Unknown error'
+        return { success: false, error: errorMessage }
+      }
+    },
+    [tools]
+  )
+
+  const isToolAvailable = useCallback(
+    (toolName: string): boolean => {
+      return !!tools?.[toolName]?.execute
+    },
+    [tools]
+  )
+
+  return (
+    <ToolExecutionContext.Provider value={{ executeTool, isToolAvailable }}>
+      {children}
+    </ToolExecutionContext.Provider>
+  )
+}
+
+export function useToolExecution(): ToolExecutionContextValue {
+  const context = useContext(ToolExecutionContext)
+  if (!context) {
+    return {
+      executeTool: async (): Promise<ToolExecutionResult> => ({
+        success: false,
+        error: 'ToolExecutionProvider not found',
+      }),
+      isToolAvailable: () => false,
+    }
+  }
+  return context
+}

package/src/lib/generative-ui.ts

@@ -0,0 +1,18 @@
+// Type for json-render tree structure
+export interface JsonRenderNode {
+  type: string
+  props?: Record<string, unknown>
+  children?: JsonRenderNode[]
+}
+
+/**
+ * Check if content is a json-render compatible tree structure
+ */
+export function isJsonRenderTree(content: unknown): content is JsonRenderNode {
+  return (
+    typeof content === 'object' &&
+    content !== null &&
+    'type' in content &&
+    typeof (content as JsonRenderNode).type === 'string'
+  )
+}

package/src/plugins/chart/component.tsx

@@ -8,6 +8,7 @@ import { AlertCircleIcon } from 'lucide-react'
 import { FC, useEffect, useMemo, useRef, useState } from 'react'
 import { parse, View, Warn } from 'vega'
 import { expressionInterpreter } from 'vega-interpreter'
+import { PluginLoadingState } from '../components/PluginLoadingState'
 
 export const ChartRenderer: FC<SyntaxHighlighterProps> = ({ code }) => {
   const containerRef = useRef<HTMLDivElement>(null)
@@ -84,21 +85,20 @@ export const ChartRenderer: FC<SyntaxHighlighterProps> = ({ code }) => {
     }
   }, [shouldRender, parsedSpec])
 
+  // Show loading state while JSON is incomplete/streaming
+  if (!shouldRender && !error) {
+    return <PluginLoadingState text="Rendering chart..." />
+  }
+
   return (
     <div
       className={cn(
         // the after:hidden is to prevent assistant-ui from showing its default code block loading indicator
-        'relative min-h-[400px] w-fit max-w-full min-w-[400px] overflow-auto border p-6 after:hidden',
+        'border-border relative min-h-[400px] w-fit max-w-full min-w-[400px] overflow-auto border after:hidden',
         r('lg'),
         d('p-lg')
       )}
     >
-      {!shouldRender && !error && (
-        <div className="shimmer text-muted-foreground bg-background/80 absolute inset-0 z-10 flex items-center justify-center">
-          Rendering chart...
-        </div>
-      )}
-
       {error && (
         <div className="bg-background absolute inset-0 z-10 flex items-center justify-center gap-2 text-rose-500">
           <AlertCircleIcon name="alert-circle" className="h-4 w-4" />
@@ -106,7 +106,7 @@ export const ChartRenderer: FC<SyntaxHighlighterProps> = ({ code }) => {
         </div>
       )}
 
-      <div ref={containerRef} className={!shouldRender ? 'hidden' : 'block'} />
+      <div ref={containerRef} className={error ? 'hidden' : 'block'} />
     </div>
   )
 }

package/src/plugins/components/PluginLoadingState.tsx

@@ -0,0 +1,35 @@
+'use client'
+
+import { useRadius } from '@/hooks/useRadius'
+import { cn } from '@/lib/utils'
+import { FC } from 'react'
+
+interface PluginLoadingStateProps {
+  text: string
+  className?: string
+}
+
+/**
+ * Shared loading state component for plugins.
+ * Displays a shimmer effect with loading text.
+ */
+export const PluginLoadingState: FC<PluginLoadingStateProps> = ({
+  text,
+  className,
+}) => {
+  const r = useRadius()
+
+  return (
+    <div
+      className={cn(
+        'border-border bg-card relative min-h-[400px] w-fit max-w-full min-w-[400px] overflow-hidden border after:hidden',
+        r('lg'),
+        className
+      )}
+    >
+      <div className="shimmer text-muted-foreground absolute inset-0 flex items-center justify-center">
+        {text}
+      </div>
+    </div>
+  )
+}

package/src/plugins/components/index.ts

@@ -0,0 +1 @@
+export { PluginLoadingState } from './PluginLoadingState'

package/src/plugins/generative-ui/component.tsx

@@ -0,0 +1,56 @@
+'use client'
+
+import { GenerativeUI } from '@/components/ui/generative-ui'
+import { SyntaxHighlighterProps } from '@assistant-ui/react-markdown'
+import { FC, useMemo } from 'react'
+import { PluginLoadingState } from '../components/PluginLoadingState'
+
+const loadingMessages = [
+  'Preparing your data...',
+  'Building your view...',
+  'Generating results...',
+  'Loading content...',
+  'Fetching information...',
+  'Processing your request...',
+  'Almost ready...',
+  'Setting things up...',
+]
+
+function getRandomLoadingMessage() {
+  return loadingMessages[Math.floor(Math.random() * loadingMessages.length)]
+}
+
+export const GenerativeUIRenderer: FC<SyntaxHighlighterProps> = ({ code }) => {
+  // Parse JSON - returns null if invalid (still streaming)
+  const content = useMemo(() => {
+    const trimmedCode = code.trim()
+    if (!trimmedCode) return null
+
+    try {
+      const parsed = JSON.parse(trimmedCode)
+      // Validate it has a type field (basic json-render structure)
+      if (!parsed || typeof parsed !== 'object' || !('type' in parsed)) {
+        return null
+      }
+      return parsed
+    } catch {
+      // JSON is incomplete (still streaming) - return null to show loading state
+      return null
+    }
+  }, [code])
+
+  // Memoize the loading message so it doesn't change on every render
+  const loadingMessage = useMemo(() => getRandomLoadingMessage(), [])
+
+  // Show loading shimmer while JSON is incomplete/streaming
+  if (!content) {
+    return <PluginLoadingState text={loadingMessage} />
+  }
+
+  // Render without outer border - the Card component inside provides the border
+  return (
+    <div className="overflow-hidden after:hidden">
+      <GenerativeUI content={content} />
+    </div>
+  )
+}