@gram-ai/elements 1.21.2 → 1.22.0

package/src/global.css

@@ -247,3 +247,48 @@
 [data-radius='pill'] .gram-elements {
   --radius: 9999px;
 }
+
+/* assistant-ui loading dot styles (from @assistant-ui/react-markdown/styles/dot.css) */
+@keyframes aui-pulse {
+  50% {
+    opacity: 0.5;
+  }
+}
+
+.gram-elements :where(.aui-md[data-status='running']):empty::after,
+.gram-elements
+  :where(.aui-md[data-status='running'])
+  > :where(:not(ol):not(ul):not(pre)):last-child::after,
+.gram-elements :where(.aui-md[data-status='running']) > pre:last-child code::after,
+.gram-elements
+  :where(.aui-md[data-status='running'])
+  > :where(:is(ol, ul):last-child)
+  > :where(li:last-child:not(:has(* > li)))::after,
+.gram-elements
+  :where(.aui-md[data-status='running'])
+  > :where(:is(ol, ul):last-child)
+  > :where(li:last-child)
+  > :where(:is(ol, ul):last-child)
+  > :where(li:last-child:not(:has(* > li)))::after,
+.gram-elements
+  :where(.aui-md[data-status='running'])
+  > :where(:is(ol, ul):last-child)
+  > :where(li:last-child)
+  > :where(:is(ol, ul):last-child)
+  > :where(li:last-child)
+  > :where(:is(ol, ul):last-child)
+  > :where(li:last-child)::after {
+  animation: aui-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+  font-family:
+    ui-sans-serif,
+    system-ui,
+    sans-serif,
+    'Apple Color Emoji',
+    'Segoe UI Emoji',
+    'Segoe UI Symbol',
+    'Noto Color Emoji';
+  --aui-content: '\25cf';
+  content: var(--aui-content);
+  margin-left: 0.25rem;
+  margin-right: 0.25rem;
+}

package/src/hooks/useGramThreadListAdapter.tsx

@@ -6,7 +6,7 @@ import {
   useAssistantApi,
   type AssistantApi,
 } from '@assistant-ui/react'
-import type { AssistantStream } from 'assistant-stream'
+import { createAssistantStream, type AssistantStream } from 'assistant-stream'
 import {
   GramChatOverview,
   GramChat,
@@ -21,9 +21,26 @@ import {
   type PropsWithChildren,
 } from 'react'
 
+/**
+ * Prefix used by assistant-ui for local thread IDs that haven't been persisted yet.
+ * This is an internal implementation detail of assistant-ui's RemoteThreadListThreadListRuntimeCore.
+ * If the library changes this prefix, we only need to update it here.
+ */
+const LOCAL_THREAD_ID_PREFIX = '__LOCALID_'
+
+/**
+ * Checks if a thread ID is a local (unpersisted) thread ID.
+ * Local IDs are generated by assistant-ui before the thread is initialized with a remote ID.
+ */
+export function isLocalThreadId(threadId: string | undefined): boolean {
+  return !!threadId?.startsWith(LOCAL_THREAD_ID_PREFIX)
+}
+
 export interface ThreadListAdapterOptions {
   apiUrl: string
   headers: Record<string, string>
+  /** Map to translate local thread IDs to UUIDs (shared with transport) */
+  localIdToUuidMap?: Map<string, string>
 }
 
 interface ListChatsResponse {
@@ -227,6 +244,26 @@ export function useGramThreadListAdapter(
       },
 
       async initialize(threadId: string) {
+        // For new threads (local IDs), check if sendMessages already created a UUID
+        if (isLocalThreadId(threadId)) {
+          // Check if transport already generated a UUID for this local ID
+          const existingUuid =
+            optionsRef.current.localIdToUuidMap?.get(threadId)
+          if (existingUuid) {
+            return {
+              remoteId: existingUuid,
+              externalId: existingUuid,
+            }
+          }
+          // Otherwise generate a new one and store it
+          const uuid = crypto.randomUUID()
+          optionsRef.current.localIdToUuidMap?.set(threadId, uuid)
+          return {
+            remoteId: uuid,
+            externalId: uuid,
+          }
+        }
+        // For existing threads, use the ID as-is
         return {
           remoteId: threadId,
           externalId: threadId,
@@ -250,21 +287,65 @@ export function useGramThreadListAdapter(
       },
 
       async generateTitle(
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        _remoteId: string,
+        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) {
+        // Skip if this is a local ID that hasn't been persisted yet
+        if (!remoteId || isLocalThreadId(remoteId)) {
+          return createAssistantStream((controller) => {
             controller.close()
-          },
-        }) as AssistantStream
+          })
+        }
+
+        // Call the server to generate and persist the title
+        try {
+          const response = await fetch(
+            `${optionsRef.current.apiUrl}/rpc/chat.generateTitle`,
+            {
+              method: 'POST',
+              headers: {
+                ...optionsRef.current.headers,
+                'Content-Type': 'application/json',
+              },
+              body: JSON.stringify({ id: remoteId }),
+            }
+          )
+
+          if (response.ok) {
+            const result = (await response.json()) as { title: string }
+            const title = result.title || 'New Chat'
+
+            // Return a stream that emits the title as text
+            return createAssistantStream((controller) => {
+              controller.appendText(title)
+              controller.close()
+            })
+          }
+
+          // 404 is expected for new chats that haven't been persisted yet
+          if (response.status !== 404) {
+            console.error('Error generating title:', response.status)
+          }
+        } catch (error) {
+          console.error('Error generating title:', error)
+        }
+
+        // Fallback: return empty stream
+        return createAssistantStream((controller) => {
+          controller.close()
+        })
       },
 
       async fetch(threadId: string) {
+        // Skip if this is a local ID that hasn't been persisted yet
+        if (!threadId || isLocalThreadId(threadId)) {
+          return {
+            remoteId: threadId,
+            status: 'regular' as const,
+          }
+        }
+
         try {
           const response = await fetch(
             `${optionsRef.current.apiUrl}/rpc/chat.load?id=${encodeURIComponent(threadId)}`,

package/src/hooks/useMCPTools.ts

@@ -11,17 +11,19 @@ export function useMCPTools({
   auth,
   mcp,
   environment,
+  gramEnvironment,
 }: {
   auth: Auth
   mcp: string | undefined
   environment: Record<string, unknown>
+  gramEnvironment?: string
 }): UseQueryResult<MCPToolsResult, Error> {
   const authQueryKey = Object.entries(auth.headers ?? {}).map(
     (k, v) => `${k}:${v}`
   )
 
   const queryResult = useQuery({
-    queryKey: ['mcpTools', mcp, ...authQueryKey],
+    queryKey: ['mcpTools', mcp, gramEnvironment, ...authQueryKey],
     queryFn: async () => {
       assert(!auth.isLoading, 'No auth found')
       assert(mcp, 'No MCP URL found')
@@ -34,6 +36,7 @@ export function useMCPTools({
           headers: {
             ...transformEnvironmentToHeaders(environment ?? {}),
             ...auth.headers,
+            ...(gramEnvironment && { 'Gram-Environment': gramEnvironment }),
           },
         },
       })

package/src/hooks/useToolMentions.ts

@@ -0,0 +1,93 @@
+import { useCallback, useMemo, useRef, useState } from 'react'
+import { useAssistantApi, useAssistantState } from '@assistant-ui/react'
+import {
+  MentionableTool,
+  parseMentionedTools,
+  removeToolMention,
+  toolSetToMentionableTools,
+} from '@/lib/tool-mentions'
+
+export interface UseToolMentionsOptions {
+  tools: Record<string, unknown> | undefined
+  enabled?: boolean
+}
+
+export interface UseToolMentionsReturn {
+  mentionableTools: MentionableTool[]
+  mentionedToolIds: string[]
+  value: string
+  cursorPosition: number
+  textareaRef: React.RefObject<HTMLTextAreaElement | null>
+  updateCursorPosition: () => void
+  handleAutocompleteChange: (value: string, cursorPosition: number) => void
+  removeMention: (toolId: string) => void
+  isActive: boolean
+}
+
+export function useToolMentions({
+  tools,
+  enabled = true,
+}: UseToolMentionsOptions): UseToolMentionsReturn {
+  const [cursorPosition, setCursorPosition] = useState(0)
+  const textareaRef = useRef<HTMLTextAreaElement | null>(null)
+  const api = useAssistantApi()
+  const composerText = useAssistantState(({ composer }) => composer.text)
+
+  const mentionableTools = useMemo(
+    () => toolSetToMentionableTools(tools),
+    [tools]
+  )
+
+  const mentionedToolIds = useMemo(
+    () => (enabled ? parseMentionedTools(composerText, tools) : []),
+    [composerText, tools, enabled]
+  )
+
+  const updateCursorPosition = useCallback(() => {
+    const textarea = textareaRef.current
+    if (textarea) {
+      setCursorPosition(textarea.selectionStart)
+    }
+  }, [])
+
+  const handleAutocompleteChange = useCallback(
+    (newValue: string, newCursorPosition: number) => {
+      api.composer().setText(newValue)
+      setCursorPosition(newCursorPosition)
+
+      setTimeout(() => {
+        const textarea = textareaRef.current
+        if (textarea) {
+          textarea.focus()
+          textarea.setSelectionRange(newCursorPosition, newCursorPosition)
+        }
+      }, 0)
+    },
+    [api]
+  )
+
+  const removeMention = useCallback(
+    (toolId: string) => {
+      const tool = mentionableTools.find((t) => t.id === toolId)
+      if (tool) {
+        const newValue = removeToolMention(composerText, tool.name)
+        api.composer().setText(newValue)
+      }
+    },
+    [composerText, mentionableTools, api]
+  )
+
+  const isActive = enabled && mentionableTools.length > 0
+
+  return {
+    mentionableTools,
+    mentionedToolIds,
+    value: composerText,
+    cursorPosition,
+    textareaRef,
+    updateCursorPosition,
+    handleAutocompleteChange,
+    removeMention,
+    isActive,
+  }
+}

package/src/index.ts

@@ -9,7 +9,7 @@ export { useElements } from './hooks/useElements'
 
 // Core Components
 export { Chat } from '@/components/Chat'
-export { ThreadList as ChatHistory } from '@/components/assistant-ui/thread-list'
+export { ChatHistory } from '@/components/ChatHistory'
 
 // Frontend Tools
 export { defineFrontendTool } from './lib/tools'
@@ -43,6 +43,7 @@ export type {
   SidecarConfig,
   Suggestion,
   ThemeConfig,
+  ToolMentionsConfig,
   ToolsConfig,
   Variant,
   VARIANTS,

package/src/lib/tool-mentions.ts

@@ -0,0 +1,106 @@
+export type ToolRecord = Record<string, unknown> | undefined
+
+export interface MentionableTool {
+  id: string
+  name: string
+  description?: string
+}
+
+export interface MentionContext {
+  isInMention: boolean
+  query: string
+  atPosition: number
+}
+
+const MENTION_PATTERN = /@(\w+)/g
+
+export function toolSetToMentionableTools(
+  tools: ToolRecord
+): MentionableTool[] {
+  if (!tools) return []
+
+  return Object.entries(tools).map(([name, tool]) => ({
+    id: name,
+    name,
+    description:
+      typeof tool === 'object' && tool !== null && 'description' in tool
+        ? String((tool as { description?: unknown }).description ?? '')
+        : undefined,
+  }))
+}
+
+export function parseMentionedTools(text: string, tools: ToolRecord): string[] {
+  if (!tools || !text) return []
+
+  const toolNames = Object.keys(tools)
+  const mentions: string[] = []
+  let match: RegExpExecArray | null
+
+  MENTION_PATTERN.lastIndex = 0
+  while ((match = MENTION_PATTERN.exec(text)) !== null) {
+    mentions.push(match[1].toLowerCase())
+  }
+
+  const matchedToolIds = toolNames.filter((name) =>
+    mentions.includes(name.toLowerCase())
+  )
+
+  return [...new Set(matchedToolIds)]
+}
+
+export function detectMentionContext(
+  text: string,
+  cursorPosition: number
+): MentionContext {
+  const textBeforeCursor = text.slice(0, cursorPosition)
+  const lastAtSymbol = textBeforeCursor.lastIndexOf('@')
+
+  if (lastAtSymbol === -1) {
+    return { isInMention: false, query: '', atPosition: -1 }
+  }
+
+  const textAfterAt = textBeforeCursor.slice(lastAtSymbol + 1)
+
+  if (textAfterAt.includes(' ') || textAfterAt.includes('\n')) {
+    return { isInMention: false, query: '', atPosition: -1 }
+  }
+
+  return {
+    isInMention: true,
+    query: textAfterAt.toLowerCase(),
+    atPosition: lastAtSymbol,
+  }
+}
+
+export function filterToolsByQuery(
+  tools: MentionableTool[],
+  query: string
+): MentionableTool[] {
+  if (!query) return tools
+
+  const queryLower = query.toLowerCase()
+
+  return tools.filter((tool) => {
+    const nameMatch = tool.name.toLowerCase().includes(queryLower)
+    const descMatch = tool.description?.toLowerCase().includes(queryLower)
+    return nameMatch || descMatch
+  })
+}
+
+export function insertToolMention(
+  text: string,
+  toolName: string,
+  atPosition: number,
+  cursorPosition: number
+): { text: string; cursorPosition: number } {
+  const beforeMention = text.slice(0, atPosition)
+  const afterCursor = text.slice(cursorPosition)
+  const newText = `${beforeMention}@${toolName} ${afterCursor}`
+  const newCursorPosition = atPosition + toolName.length + 2
+  return { text: newText, cursorPosition: newCursorPosition }
+}
+
+export function removeToolMention(text: string, toolName: string): string {
+  const pattern = new RegExp(`@${toolName}\\s?`, 'gi')
+  return text.replace(pattern, '')
+}

package/src/types/index.ts

@@ -111,6 +111,13 @@ export interface ElementsConfig {
    */
   environment?: Record<string, unknown>
 
+  /**
+   * The environment slug to use for resolving secrets.
+   * When specified, this is sent as the Gram-Environment header to select
+   * which environment's secrets to use for tool execution.
+   */
+  gramEnvironment?: string
+
   /**
    * The layout variant for the chat interface.
    *
@@ -747,6 +754,13 @@ export interface ComposerConfig {
    * @default true
    */
   attachments?: boolean | AttachmentsConfig
+
+  /**
+   * Configuration for @tool mentions in the composer.
+   * Set to `false` to disable, `true` for defaults, or an object for fine-grained control.
+   * @default true
+   */
+  toolMentions?: boolean | ToolMentionsConfig
 }
 
 /**
@@ -774,6 +788,14 @@ export interface AttachmentsConfig {
   maxSize?: number
 }
 
+export interface ToolMentionsConfig {
+  /** @default true */
+  enabled?: boolean
+  /** @default 10 */
+  maxSuggestions?: number
+  placeholder?: string
+}
+
 export interface SidecarConfig extends ExpandableConfig {
   /**
    * The title displayed in the sidecar header.
@@ -822,4 +844,5 @@ export type ElementsContextType = {
   isOpen: boolean
   setIsOpen: (isOpen: boolean) => void
   plugins: Plugin[]
+  mcpTools: Record<string, unknown> | undefined
 }

package/src/vite-env.d.ts

@@ -13,3 +13,8 @@ interface ImportMetaEnv {
 interface ImportMeta {
   readonly env: ImportMetaEnv
 }
+
+declare module '*.css?inline' {
+  const content: string
+  export default content
+}