@gram-ai/elements 1.21.2 → 1.22.0

package/src/components/assistant-ui/mentioned-tools-badges.tsx

@@ -0,0 +1,105 @@
+import { FC } from 'react'
+import { Wrench, X } from 'lucide-react'
+import { AnimatePresence } from 'motion/react'
+import * as m from 'motion/react-m'
+
+import { cn } from '@/lib/utils'
+import { useDensity } from '@/hooks/useDensity'
+import { useRadius } from '@/hooks/useRadius'
+import { EASE_OUT_QUINT } from '@/lib/easing'
+import { MentionableTool } from '@/lib/tool-mentions'
+
+export interface MentionedToolsBadgesProps {
+  mentionedToolIds: string[]
+  tools: MentionableTool[]
+  onRemove?: (toolId: string) => void
+  className?: string
+}
+
+export const MentionedToolsBadges: FC<MentionedToolsBadgesProps> = ({
+  mentionedToolIds,
+  tools,
+  onRemove,
+  className,
+}) => {
+  const d = useDensity()
+  const mentionedTools = tools.filter((tool) =>
+    mentionedToolIds.includes(tool.id)
+  )
+
+  if (mentionedTools.length === 0) {
+    return null
+  }
+
+  return (
+    <div
+      className={cn(
+        'aui-mentioned-tools-badges flex flex-wrap items-center gap-1',
+        d('px-sm'),
+        d('py-xs'),
+        className
+      )}
+    >
+      <span className="text-muted-foreground flex-shrink-0 text-xs">
+        Tools:
+      </span>
+      <AnimatePresence mode="popLayout">
+        {mentionedTools.map((tool) => (
+          <m.div
+            key={tool.id}
+            layout
+            initial={{ opacity: 0, scale: 0.8 }}
+            animate={{ opacity: 1, scale: 1 }}
+            exit={{ opacity: 0, scale: 0.8 }}
+            transition={{ duration: 0.15, ease: EASE_OUT_QUINT }}
+          >
+            <ToolBadge
+              tool={tool}
+              onRemove={onRemove ? () => onRemove(tool.id) : undefined}
+            />
+          </m.div>
+        ))}
+      </AnimatePresence>
+    </div>
+  )
+}
+
+interface ToolBadgeProps {
+  tool: MentionableTool
+  onRemove?: () => void
+}
+
+const ToolBadge: FC<ToolBadgeProps> = ({ tool, onRemove }) => {
+  const d = useDensity()
+  const r = useRadius()
+
+  return (
+    <div
+      className={cn(
+        'aui-tool-badge bg-primary/10 text-primary inline-flex items-center gap-1',
+        r('md'),
+        d('px-sm'),
+        d('py-xs')
+      )}
+    >
+      <Wrench className="size-3 flex-shrink-0" />
+      <span className="text-xs font-medium">{tool.name}</span>
+      {onRemove && (
+        <button
+          type="button"
+          onClick={(e) => {
+            e.preventDefault()
+            e.stopPropagation()
+            onRemove()
+          }}
+          className="hover:opacity-70 focus:outline-none"
+          aria-label={`Remove ${tool.name}`}
+        >
+          <X className="size-3 flex-shrink-0" />
+        </button>
+      )}
+    </div>
+  )
+}
+
+export default MentionedToolsBadges

package/src/components/assistant-ui/thread-list.tsx

@@ -11,7 +11,6 @@ import { Skeleton } from '@/components/ui/skeleton'
 import { useRadius } from '@/hooks/useRadius'
 import { cn } from '@/lib/utils'
 import { useDensity } from '@/hooks/useDensity'
-import { ROOT_SELECTOR } from '@/constants/tailwind'
 
 interface ThreadListProps {
   className?: string
@@ -24,8 +23,7 @@ export const ThreadList: FC<ThreadListProps> = ({ className }) => {
       className={cn(
         'aui-root aui-thread-list-root bg-background flex flex-col items-stretch',
         d('gap-sm'),
-        className,
-        ROOT_SELECTOR
+        className
       )}
     >
       <div

package/src/components/assistant-ui/thread.tsx

@@ -23,6 +23,7 @@ import {
 import { LazyMotion, MotionConfig, domAnimation } from 'motion/react'
 import * as m from 'motion/react-m'
 import { useEffect, useRef, useState, type FC } from 'react'
+import { AnimatePresence } from 'motion/react'
 
 import {
   ComposerAddAttachment,
@@ -32,8 +33,11 @@ import {
 import { MarkdownText } from '@/components/assistant-ui/markdown-text'
 import { Reasoning, ReasoningGroup } from '@/components/assistant-ui/reasoning'
 import { ToolFallback } from '@/components/assistant-ui/tool-fallback'
+import { ToolMentionAutocomplete } from '@/components/assistant-ui/tool-mention-autocomplete'
+import { MentionedToolsBadges } from '@/components/assistant-ui/mentioned-tools-badges'
 import { TooltipIconButton } from '@/components/assistant-ui/tooltip-icon-button'
 import { Button } from '@/components/ui/button'
+import { useToolMentions } from '@/hooks/useToolMentions'
 
 import { useDensity } from '@/hooks/useDensity'
 import { useElements } from '@/hooks/useElements'
@@ -262,8 +266,97 @@ const ThreadSuggestions: FC = () => {
   )
 }
 
+/**
+ * Component that handles tool mentions (@tool) in the composer.
+ * Shows autocomplete dropdown and badges for mentioned tools.
+ */
+const ComposerToolMentions: FC<{
+  tools: Record<string, unknown> | undefined
+}> = ({ tools }) => {
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  const {
+    mentionableTools,
+    mentionedToolIds,
+    value,
+    cursorPosition,
+    textareaRef,
+    updateCursorPosition,
+    handleAutocompleteChange,
+    removeMention,
+    isActive,
+  } = useToolMentions({ tools })
+
+  // Find and attach to the textarea within the composer
+  useEffect(() => {
+    if (!isActive) return
+
+    const findTextarea = () => {
+      const textarea = document.querySelector(
+        '.aui-composer-input'
+      ) as HTMLTextAreaElement | null
+      if (textarea && textareaRef.current !== textarea) {
+        textareaRef.current = textarea
+
+        const handleSelectionChange = () => updateCursorPosition()
+        textarea.addEventListener('click', handleSelectionChange)
+        textarea.addEventListener('keyup', handleSelectionChange)
+        textarea.addEventListener('input', handleSelectionChange)
+
+        return () => {
+          textarea.removeEventListener('click', handleSelectionChange)
+          textarea.removeEventListener('keyup', handleSelectionChange)
+          textarea.removeEventListener('input', handleSelectionChange)
+        }
+      }
+    }
+
+    const cleanup = findTextarea()
+
+    const observer = new MutationObserver(() => {
+      findTextarea()
+    })
+
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+    })
+
+    return () => {
+      cleanup?.()
+      observer.disconnect()
+    }
+  }, [isActive, textareaRef, updateCursorPosition])
+
+  if (!isActive) {
+    return null
+  }
+
+  return (
+    <div ref={containerRef} className="aui-composer-tool-mentions relative">
+      {/* Badges showing mentioned tools */}
+      <MentionedToolsBadges
+        mentionedToolIds={mentionedToolIds}
+        tools={mentionableTools}
+        onRemove={removeMention}
+      />
+
+      {/* Autocomplete dropdown */}
+      <AnimatePresence>
+        <ToolMentionAutocomplete
+          tools={mentionableTools}
+          value={value}
+          cursorPosition={cursorPosition}
+          onValueChange={handleAutocompleteChange}
+          textareaRef={textareaRef}
+        />
+      </AnimatePresence>
+    </div>
+  )
+}
+
 const Composer: FC = () => {
-  const { config } = useElements()
+  const { config, mcpTools } = useElements()
   const r = useRadius()
   const d = useDensity()
   const composerConfig = config.composer ?? {
@@ -272,6 +365,15 @@ const Composer: FC = () => {
   }
   const components = config.components ?? {}
 
+  // Determine if tool mentions are enabled (default: true)
+  const toolMentionsEnabled =
+    composerConfig.toolMentions === undefined ||
+    composerConfig.toolMentions === true ||
+    (typeof composerConfig.toolMentions === 'object' &&
+      composerConfig.toolMentions.enabled !== false)
+
+  const composerRootRef = useRef<HTMLFormElement>(null)
+
   if (components.Composer) {
     return <components.Composer />
   }
@@ -287,6 +389,7 @@ const Composer: FC = () => {
     >
       <ThreadScrollToBottom />
       <ComposerPrimitive.Root
+        ref={composerRootRef}
         className={cn(
           'aui-composer-root group/input-group border-input bg-background has-[textarea:focus-visible]:border-ring has-[textarea:focus-visible]:ring-ring/5 dark:bg-background relative flex w-full flex-col border px-1 pt-2 shadow-xs transition-[color,box-shadow] outline-none has-[textarea:focus-visible]:ring-1',
           r('xl')
@@ -294,6 +397,8 @@ const Composer: FC = () => {
       >
         {composerConfig.attachments && <ComposerAttachments />}
 
+        {toolMentionsEnabled && <ComposerToolMentions tools={mcpTools} />}
+
         <ComposerPrimitive.Input
           placeholder={composerConfig.placeholder}
           className={cn(

package/src/components/assistant-ui/tool-mention-autocomplete.tsx

@@ -0,0 +1,253 @@
+import { FC, useCallback, useEffect, useRef, useState } from 'react'
+import { Wrench } from 'lucide-react'
+import * as m from 'motion/react-m'
+
+import { cn } from '@/lib/utils'
+import { useDensity } from '@/hooks/useDensity'
+import { useRadius } from '@/hooks/useRadius'
+import { EASE_OUT_QUINT } from '@/lib/easing'
+import {
+  MentionableTool,
+  detectMentionContext,
+  filterToolsByQuery,
+  insertToolMention,
+} from '@/lib/tool-mentions'
+
+export interface ToolMentionAutocompleteProps {
+  tools: MentionableTool[]
+  value: string
+  cursorPosition: number
+  onValueChange: (value: string, cursorPosition: number) => void
+  textareaRef: React.RefObject<HTMLTextAreaElement | null>
+  className?: string
+}
+
+export const ToolMentionAutocomplete: FC<ToolMentionAutocompleteProps> = ({
+  tools,
+  value,
+  cursorPosition,
+  onValueChange,
+  textareaRef,
+  className,
+}) => {
+  const [selectedIndex, setSelectedIndex] = useState(0)
+  const [isVisible, setIsVisible] = useState(false)
+  const [filteredTools, setFilteredTools] = useState<MentionableTool[]>([])
+  const [mentionContext, setMentionContext] = useState<{
+    atPosition: number
+    query: string
+  } | null>(null)
+
+  const containerRef = useRef<HTMLDivElement>(null)
+  const d = useDensity()
+  const r = useRadius()
+
+  useEffect(() => {
+    const context = detectMentionContext(value, cursorPosition)
+
+    if (context.isInMention && tools.length > 0) {
+      const filtered = filterToolsByQuery(tools, context.query)
+      setFilteredTools(filtered)
+      setIsVisible(filtered.length > 0)
+      setMentionContext({
+        atPosition: context.atPosition,
+        query: context.query,
+      })
+      setSelectedIndex(0)
+    } else {
+      setIsVisible(false)
+      setMentionContext(null)
+    }
+  }, [value, cursorPosition, tools])
+
+  const selectTool = useCallback(
+    (tool: MentionableTool) => {
+      if (!mentionContext) return
+
+      const result = insertToolMention(
+        value,
+        tool.name,
+        mentionContext.atPosition,
+        cursorPosition
+      )
+
+      onValueChange(result.text, result.cursorPosition)
+      setIsVisible(false)
+    },
+    [mentionContext, value, cursorPosition, onValueChange, textareaRef]
+  )
+
+  useEffect(() => {
+    if (!isVisible) return
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      switch (e.key) {
+        case 'ArrowDown':
+          e.preventDefault()
+          e.stopPropagation()
+          setSelectedIndex((prev) => (prev + 1) % filteredTools.length)
+          break
+        case 'ArrowUp':
+          e.preventDefault()
+          e.stopPropagation()
+          setSelectedIndex(
+            (prev) => (prev - 1 + filteredTools.length) % filteredTools.length
+          )
+          break
+        case 'Enter':
+        case 'Tab':
+          e.preventDefault()
+          e.stopPropagation()
+          if (filteredTools[selectedIndex]) {
+            selectTool(filteredTools[selectedIndex])
+          }
+          break
+        case 'Escape':
+          e.preventDefault()
+          e.stopPropagation()
+          setIsVisible(false)
+          break
+      }
+    }
+
+    const textarea = textareaRef.current
+    if (textarea) {
+      textarea.addEventListener('keydown', handleKeyDown, { capture: true })
+      return () =>
+        textarea.removeEventListener('keydown', handleKeyDown, {
+          capture: true,
+        })
+    }
+  }, [isVisible, filteredTools, selectedIndex, selectTool, textareaRef])
+
+  // Scroll selected item into view
+  useEffect(() => {
+    if (!isVisible) return
+    const container = containerRef.current
+    if (!container) return
+
+    const selectedItem = container.querySelector(
+      `[data-index="${selectedIndex}"]`
+    ) as HTMLElement
+    if (selectedItem) {
+      selectedItem.scrollIntoView({ block: 'nearest' })
+    }
+  }, [selectedIndex, isVisible])
+
+  useEffect(() => {
+    if (!isVisible) return
+
+    const handleClickOutside = (e: MouseEvent) => {
+      if (
+        containerRef.current &&
+        !containerRef.current.contains(e.target as Node) &&
+        textareaRef.current &&
+        !textareaRef.current.contains(e.target as Node)
+      ) {
+        setIsVisible(false)
+      }
+    }
+
+    document.addEventListener('mousedown', handleClickOutside)
+    return () => document.removeEventListener('mousedown', handleClickOutside)
+  }, [isVisible, textareaRef])
+
+  // When autocomplete is visible, modify composer styles and position autocomplete to match composer width
+  useEffect(() => {
+    const textarea = textareaRef.current
+    if (!textarea) return
+
+    const composer = textarea.closest('.aui-composer-root') as HTMLElement
+    if (!composer) return
+
+    const updateStyles = () => {
+      const autocomplete = containerRef.current
+      if (!autocomplete) return
+
+      if (isVisible) {
+        // Modify composer to connect with autocomplete
+        composer.style.borderTopColor = 'var(--ring)'
+        composer.style.borderTopLeftRadius = '0'
+        composer.style.borderTopRightRadius = '0'
+
+        // Position autocomplete to match composer width
+        const composerRect = composer.getBoundingClientRect()
+        const autocompleteParent = autocomplete.offsetParent as HTMLElement
+        if (autocompleteParent) {
+          const parentRect = autocompleteParent.getBoundingClientRect()
+          autocomplete.style.left = `${composerRect.left - parentRect.left}px`
+          autocomplete.style.right = 'auto'
+          autocomplete.style.width = `${composerRect.width}px`
+        }
+      }
+    }
+
+    if (isVisible) {
+      // Use requestAnimationFrame to ensure DOM is updated
+      requestAnimationFrame(updateStyles)
+    } else {
+      composer.style.borderTopColor = ''
+      composer.style.borderTopLeftRadius = ''
+      composer.style.borderTopRightRadius = ''
+    }
+
+    return () => {
+      composer.style.borderTopColor = ''
+      composer.style.borderTopLeftRadius = ''
+      composer.style.borderTopRightRadius = ''
+    }
+  }, [isVisible, textareaRef])
+
+  if (!isVisible || filteredTools.length === 0) {
+    return null
+  }
+
+  return (
+    <m.div
+      ref={containerRef}
+      initial={{ opacity: 0, y: 8 }}
+      animate={{ opacity: 1, y: 0 }}
+      exit={{ opacity: 0, y: 8 }}
+      transition={{ duration: 0.15, ease: EASE_OUT_QUINT }}
+      className={cn(
+        'aui-tool-mention-autocomplete border-ring bg-background absolute bottom-full z-50 max-h-[220px] overflow-clip overflow-y-auto overscroll-contain rounded-br-none! rounded-bl-none! border border-b-0 shadow-xs',
+        r('xl'),
+        className
+      )}
+    >
+      <div className="flex flex-col gap-1">
+        {filteredTools.map((tool, index) => (
+          <button
+            key={tool.id}
+            type="button"
+            data-index={index}
+            className={cn(
+              'aui-tool-mention-item flex w-full items-center gap-2 text-left transition-colors',
+              d('p-sm'),
+              'hover:bg-accent hover:text-accent-foreground',
+              index === selectedIndex && 'bg-accent text-accent-foreground'
+            )}
+            onClick={(e) => {
+              e.preventDefault()
+              e.stopPropagation()
+              selectTool(tool)
+            }}
+            onMouseEnter={() => setSelectedIndex(index)}
+          >
+            <Wrench className="mt-0.5 size-4 flex-shrink-0 opacity-50" />
+            <div className="min-w-0 flex-1">
+              <div className="text-sm font-medium">{tool.name}</div>
+              {tool.description && (
+                <div className="text-muted-foreground line-clamp-2 text-xs">
+                  {tool.description}
+                </div>
+              )}
+            </div>
+          </button>
+        ))}
+      </div>
+    </m.div>
+  )
+}
+
+export default ToolMentionAutocomplete

package/src/components/ui/tool-ui.tsx

@@ -322,7 +322,7 @@ function ToolUISection({
     <div data-slot="tool-ui-section" className="border-border border-t">
       <button
         onClick={() => setIsExpanded(!isExpanded)}
-        className="hover:bg-accent/50 flex w-full cursor-pointer items-center justify-between px-4 py-2.5 text-left transition-colors"
+        className="hover:bg-accent/50 flex w-full cursor-pointer items-center justify-between px-5 py-2.5 text-left transition-colors"
       >
         <span className="text-muted-foreground text-sm">{title}</span>
         <div className="flex items-center gap-1">

package/src/contexts/ElementsProvider.tsx

@@ -46,7 +46,11 @@ import {
 import { useAuth } from '../hooks/useAuth'
 import { ElementsContext } from './contexts'
 import { ToolApprovalProvider } from './ToolApprovalContext'
-import { useGramThreadListAdapter } from '@/hooks/useGramThreadListAdapter'
+import {
+  isLocalThreadId,
+  useGramThreadListAdapter,
+} from '@/hooks/useGramThreadListAdapter'
+import { ROOT_SELECTOR } from '@/constants/tailwind'
 
 export interface ElementsProviderProps {
   children: ReactNode
@@ -139,6 +143,7 @@ const ElementsProviderWithApproval = ({
     auth,
     mcp: config.mcp,
     environment: config.environment ?? {},
+    gramEnvironment: config.gramEnvironment,
   })
 
   // Store approval helpers in ref so they can be used in async contexts
@@ -187,6 +192,9 @@ const ElementsProviderWithApproval = ({
   // When history is enabled, the thread adapter manages chat IDs instead
   const chatIdRef = useRef<string | null>(null)
 
+  // Map to share local thread IDs to UUIDs between adapter and transport (for history mode)
+  const localIdToUuidMapRef = useRef(new Map<string, string>())
+
   // Create chat transport configuration
   const transport = useMemo<ChatTransport<UIMessage>>(
     () => ({
@@ -197,9 +205,47 @@ const ElementsProviderWithApproval = ({
           throw new Error('Session is loading')
         }
 
-        // Generate chat ID on first message if not already set
-        if (!chatIdRef.current) {
-          chatIdRef.current = crypto.randomUUID()
+        // Get chat ID - try runtime's thread remoteId first (history mode),
+        // fall back to generated ID (non-history mode)
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const runtimeAny = runtimeRef.current as any
+
+        // Try multiple paths to get thread info
+        const threadListItemState = runtimeAny?.threadListItem?.getState?.()
+        const threadsState = runtimeAny?.threads?.getState?.()
+
+        // Get the thread ID - try different sources
+        const threadRemoteId = threadListItemState?.remoteId as
+          | string
+          | undefined
+        const localThreadId = (threadListItemState?.id ??
+          threadsState?.mainThreadId ??
+          threadsState?.threadIds?.[0]) as string | undefined
+
+        let chatId = threadRemoteId
+
+        if (isLocalThreadId(chatId) || (!chatId && localThreadId)) {
+          const lookupKey = chatId ?? localThreadId
+          if (lookupKey) {
+            // For local thread IDs, check if we already have a UUID mapping
+            const existingUuid = localIdToUuidMapRef.current.get(lookupKey)
+            if (existingUuid) {
+              chatId = existingUuid
+            } else {
+              // Generate a new UUID and store the mapping
+              const newUuid = crypto.randomUUID()
+              localIdToUuidMapRef.current.set(lookupKey, newUuid)
+              chatId = newUuid
+            }
+          }
+        }
+
+        if (!chatId) {
+          // Non-history mode fallback - use stable chatIdRef
+          if (!chatIdRef.current) {
+            chatIdRef.current = crypto.randomUUID()
+          }
+          chatId = chatIdRef.current
         }
 
         const context = runtimeRef.current?.thread.getModelContext()
@@ -207,10 +253,13 @@ const ElementsProviderWithApproval = ({
           getEnabledTools(context?.tools ?? {})
         )
 
-        // Include Gram-Chat-ID header for chat persistence
+        // Include Gram-Chat-ID header for chat persistence and Gram-Environment for environment selection
         const headersWithChatId = {
           ...auth.headers,
-          'Gram-Chat-ID': chatIdRef.current,
+          'Gram-Chat-ID': chatId,
+          ...(config.gramEnvironment && {
+            'Gram-Environment': config.gramEnvironment,
+          }),
         }
 
         // Create OpenRouter model (only needed when not using custom model)
@@ -300,8 +349,9 @@ const ElementsProviderWithApproval = ({
       isOpen: isOpen ?? false,
       setIsOpen,
       plugins,
+      mcpTools,
     }),
-    [config, model, isExpanded, isOpen, plugins]
+    [config, model, isExpanded, isOpen, plugins, mcpTools]
   )
 
   const frontendTools = config.tools?.frontendTools ?? {}
@@ -317,6 +367,7 @@ const ElementsProviderWithApproval = ({
         contextValue={contextValue}
         runtimeRef={runtimeRef}
         frontendTools={frontendTools}
+        localIdToUuidMap={localIdToUuidMapRef.current}
       >
         {children}
       </ElementsProviderWithHistory>
@@ -344,6 +395,7 @@ interface ElementsProviderWithHistoryProps {
   contextValue: React.ContextType<typeof ElementsContext>
   runtimeRef: React.RefObject<ReturnType<typeof useChatRuntime> | null>
   frontendTools: Record<string, AssistantTool>
+  localIdToUuidMap: Map<string, string>
 }
 
 const ElementsProviderWithHistory = ({
@@ -354,8 +406,13 @@ const ElementsProviderWithHistory = ({
   contextValue,
   runtimeRef,
   frontendTools,
+  localIdToUuidMap,
 }: ElementsProviderWithHistoryProps) => {
-  const threadListAdapter = useGramThreadListAdapter({ apiUrl, headers })
+  const threadListAdapter = useGramThreadListAdapter({
+    apiUrl,
+    headers,
+    localIdToUuidMap,
+  })
 
   // Hook factory for creating the base chat runtime
   const useChatRuntimeHook = useCallback(() => {
@@ -381,7 +438,7 @@ const ElementsProviderWithHistory = ({
     <AssistantRuntimeProvider runtime={runtime}>
       <HistoryProvider>
         <ElementsContext.Provider value={contextValue}>
-          {children}
+          <div className={`${ROOT_SELECTOR} h-full`}>{children}</div>
           <FrontendTools tools={frontendTools} />
         </ElementsContext.Provider>
       </HistoryProvider>
@@ -415,7 +472,7 @@ const ElementsProviderWithoutHistory = ({
   return (
     <AssistantRuntimeProvider runtime={runtime}>
       <ElementsContext.Provider value={contextValue}>
-        {children}
+        <div className={`${ROOT_SELECTOR} h-full`}>{children}</div>
         <FrontendTools tools={frontendTools} />
       </ElementsContext.Provider>
     </AssistantRuntimeProvider>

package/src/embedded.ts

@@ -0,0 +1,3 @@
+// Side-effect import to include embedded CSS in build
+// Use this CSS for embedding elements in apps that already have Tailwind CSS
+import './global-embedded.css'