@lota-sdk/ui 0.1.5

package/src/runtime/use-session-messages.ts

@@ -0,0 +1,122 @@
+import { useInfiniteQuery, useQueryClient } from '@tanstack/react-query'
+import type { InfiniteData } from '@tanstack/react-query'
+import { useCallback, useMemo } from 'react'
+
+import { normalizeChatMessages } from '../chat/messages'
+
+export interface SessionMessagesPageResponse {
+  messages: unknown[]
+  hasMore: boolean
+  prevCursor: string | null
+}
+
+interface SessionMessagesPage<TMessage> {
+  messages: TMessage[]
+  hasMore: boolean
+  prevCursor: string | null
+}
+
+export interface UseSessionMessagesConfig<TMessage extends { id: string; metadata?: { createdAt?: unknown } }> {
+  sessionId: string | null
+  queryKey: readonly unknown[]
+  fetchLatestPage: (id: string) => Promise<SessionMessagesPageResponse>
+  fetchOlderPage: (id: string, cursor: string) => Promise<SessionMessagesPageResponse>
+  pollIntervalMs: number
+  pollEnabled: boolean
+  validateMessages?: (messages: unknown[]) => Promise<TMessage[]>
+}
+
+export interface UseSessionMessagesReturn<TMessage> {
+  messages: TMessage[]
+  isLoading: boolean
+  hasOlderMessages: boolean
+  isLoadingOlderMessages: boolean
+  loadOlderMessages: () => Promise<void>
+  refreshLatestPage: () => Promise<void>
+}
+
+function deduplicateAndSort<TMessage extends { id: string; metadata?: { createdAt?: unknown } }>(
+  messages: TMessage[],
+): TMessage[] {
+  return normalizeChatMessages(Array.from(new Map(messages.map((message) => [message.id, message])).values()))
+}
+
+async function normalizePage<TMessage extends { id: string; metadata?: { createdAt?: unknown } }>(params: {
+  response: SessionMessagesPageResponse
+  validateMessages?: (messages: unknown[]) => Promise<TMessage[]>
+}): Promise<SessionMessagesPage<TMessage>> {
+  const validatedMessages = params.validateMessages
+    ? await params.validateMessages(params.response.messages)
+    : (params.response.messages as TMessage[])
+
+  return {
+    messages: normalizeChatMessages(validatedMessages),
+    hasMore: params.response.hasMore,
+    prevCursor: params.response.prevCursor,
+  }
+}
+
+export function useSessionMessages<TMessage extends { id: string; metadata?: { createdAt?: unknown } }>({
+  sessionId,
+  queryKey,
+  fetchLatestPage,
+  fetchOlderPage,
+  pollIntervalMs,
+  pollEnabled,
+  validateMessages,
+}: UseSessionMessagesConfig<TMessage>): UseSessionMessagesReturn<TMessage> {
+  const queryClient = useQueryClient()
+  const infiniteQuery = useInfiniteQuery({
+    queryKey,
+    queryFn: async ({ pageParam }) => {
+      if (!sessionId) {
+        return { messages: [], hasMore: false, prevCursor: null } satisfies SessionMessagesPage<TMessage>
+      }
+
+      const response = pageParam ? await fetchOlderPage(sessionId, pageParam) : await fetchLatestPage(sessionId)
+      return await normalizePage({ response, validateMessages })
+    },
+    getNextPageParam: (lastPage) => (lastPage.hasMore ? lastPage.prevCursor : undefined),
+    initialPageParam: undefined as string | undefined,
+    enabled: Boolean(sessionId),
+    refetchInterval: pollEnabled ? pollIntervalMs : false,
+    refetchOnWindowFocus: false,
+  })
+
+  const messages = useMemo(() => {
+    if (!infiniteQuery.data) return []
+    return deduplicateAndSort(infiniteQuery.data.pages.flatMap((page) => page.messages))
+  }, [infiniteQuery.data])
+
+  const loadOlderMessages = useCallback(async () => {
+    if (infiniteQuery.hasNextPage && !infiniteQuery.isFetchingNextPage) {
+      await infiniteQuery.fetchNextPage()
+    }
+  }, [infiniteQuery])
+
+  const refreshLatestPage = useCallback(async () => {
+    if (!sessionId) return
+
+    const latestPage = await normalizePage({ response: await fetchLatestPage(sessionId), validateMessages })
+
+    queryClient.setQueryData(queryKey, (cached: InfiniteData<SessionMessagesPage<TMessage>> | undefined) => {
+      if (!cached || cached.pages.length === 0) {
+        return { pages: [latestPage], pageParams: [undefined] }
+      }
+
+      const pages = [...cached.pages]
+      pages[0] = latestPage
+
+      return { ...cached, pages, pageParams: cached.pageParams.length > 0 ? cached.pageParams : [undefined] }
+    })
+  }, [fetchLatestPage, queryClient, queryKey, sessionId, validateMessages])
+
+  return {
+    messages,
+    isLoading: infiniteQuery.isLoading,
+    hasOlderMessages: infiniteQuery.hasNextPage,
+    isLoadingOlderMessages: infiniteQuery.isFetchingNextPage,
+    loadOlderMessages,
+    refreshLatestPage,
+  }
+}

package/src/runtime/use-thread-chat.ts

@@ -0,0 +1,109 @@
+import { useChat } from '@ai-sdk/react'
+import type { UseChatHelpers } from '@ai-sdk/react'
+import { lastAssistantMessageIsCompleteWithApprovalResponses } from 'ai'
+import type { ChatInit, UIMessage } from 'ai'
+import { useCallback, useEffect, useRef } from 'react'
+
+type ChatTransport<UI_MESSAGE extends UIMessage> = NonNullable<ChatInit<UI_MESSAGE>['transport']>
+
+export interface UseThreadChatOptions<UI_MESSAGE extends UIMessage> {
+  threadId: string | null
+  initialMessages: UI_MESSAGE[]
+  transport: ChatTransport<UI_MESSAGE>
+  messageMetadataSchema?: ChatInit<UI_MESSAGE>['messageMetadataSchema']
+  dataPartSchemas?: ChatInit<UI_MESSAGE>['dataPartSchemas']
+  onMessagesSettled?: () => void
+  setThreadRunningState?: (isRunning: boolean) => void
+  notifyError?: (message: string, error: Error) => void
+  stopRemoteRun?: (threadId: string) => Promise<unknown>
+  experimentalThrottle?: number
+  sendAutomaticallyWhen?: ChatInit<UI_MESSAGE>['sendAutomaticallyWhen']
+  resume?: boolean
+  idPrefix?: string
+}
+
+export interface UseThreadChatReturn<UI_MESSAGE extends UIMessage> {
+  messages: UI_MESSAGE[]
+  status: UseChatHelpers<UI_MESSAGE>['status']
+  error: Error | undefined
+  clearError: () => void
+  sendMessage: UseChatHelpers<UI_MESSAGE>['sendMessage']
+  regenerate: UseChatHelpers<UI_MESSAGE>['regenerate']
+  stop: () => Promise<void>
+  setMessages: UseChatHelpers<UI_MESSAGE>['setMessages']
+  addToolApprovalResponse: UseChatHelpers<UI_MESSAGE>['addToolApprovalResponse']
+}
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+export function useThreadChat<UI_MESSAGE extends UIMessage>({
+  threadId,
+  initialMessages,
+  transport,
+  messageMetadataSchema,
+  dataPartSchemas,
+  onMessagesSettled,
+  setThreadRunningState,
+  notifyError,
+  stopRemoteRun,
+  experimentalThrottle = 50,
+  sendAutomaticallyWhen = lastAssistantMessageIsCompleteWithApprovalResponses,
+  resume = false,
+  idPrefix = 'thread',
+}: UseThreadChatOptions<UI_MESSAGE>): UseThreadChatReturn<UI_MESSAGE> {
+  const onMessagesSettledRef = useRef(onMessagesSettled)
+  const setThreadRunningStateRef = useRef(setThreadRunningState)
+
+  useEffect(() => {
+    onMessagesSettledRef.current = onMessagesSettled
+  }, [onMessagesSettled])
+
+  useEffect(() => {
+    setThreadRunningStateRef.current = setThreadRunningState
+  }, [setThreadRunningState])
+
+  const {
+    messages,
+    status,
+    error,
+    clearError,
+    sendMessage,
+    regenerate,
+    stop: stopChatStream,
+    setMessages,
+    addToolApprovalResponse,
+  } = useChat<UI_MESSAGE>({
+    id: threadId ? `${idPrefix}:${threadId}` : `${idPrefix}:none`,
+    transport,
+    messages: initialMessages,
+    messageMetadataSchema,
+    dataPartSchemas,
+    resume,
+    experimental_throttle: experimentalThrottle,
+    sendAutomaticallyWhen,
+    onFinish: () => {
+      setThreadRunningStateRef.current?.(false)
+      onMessagesSettledRef.current?.()
+    },
+    onError: (error) => {
+      if (!(error instanceof Error && error.name === 'AbortError')) {
+        notifyError?.('Chat stream failed.', toError(error))
+      }
+      setThreadRunningStateRef.current?.(false)
+      onMessagesSettledRef.current?.()
+    },
+  })
+
+  const stop = useCallback(async () => {
+    const stopRequest = threadId && stopRemoteRun ? stopRemoteRun(threadId) : Promise.resolve(null)
+    const [stopResponse] = await Promise.allSettled([stopRequest, stopChatStream()])
+    if (stopResponse.status === 'rejected') {
+      notifyError?.('Failed to stop chat.', toError(stopResponse.reason))
+    }
+    setThreadRunningStateRef.current?.(false)
+  }, [notifyError, stopChatStream, stopRemoteRun, threadId])
+
+  return { messages, status, error, clearError, sendMessage, regenerate, stop, setMessages, addToolApprovalResponse }
+}

package/src/runtime/use-thread-management.ts

@@ -0,0 +1,328 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react'
+
+const PLACEHOLDER_THREAD_PREFIX = '__placeholder_'
+
+export interface ThreadManagementItem<TAgentId extends string = string> {
+  threadId: string
+  title: string
+  status: 'regular' | 'archived'
+  mode: 'direct' | 'group'
+  core: boolean
+  isMutable: boolean
+  agentId?: TAgentId | null
+}
+
+export interface UseThreadManagementOptions<TThread extends ThreadManagementItem<TAgentId>, TAgentId extends string> {
+  enabled?: boolean
+  isCreatingThread?: boolean
+  threads: TThread[]
+  coreThreads: TThread[]
+  archivedThreads: TThread[]
+  currentThreadId: string | null
+  selectedAgentId: TAgentId | null
+  isLoadingThreads: boolean
+  isRefetchingThreads: boolean
+  hasMoreThreads: boolean
+  isFetchingNextThreadsPage: boolean
+  fetchNextThreadsPageRaw: () => Promise<unknown> | void
+  createThread: () => Promise<{ id: string }>
+  renameThread: (params: { threadId: string; title: string }) => Promise<unknown>
+  archiveThread: (threadId: string) => Promise<unknown>
+  unarchiveThread: (threadId: string) => Promise<unknown>
+  deleteThread: (threadId: string) => Promise<unknown>
+  setCurrentThreadId: (threadId: string | null) => void
+  setSelectedAgentId: (agentId: TAgentId | null) => void
+  defaultThreadTitle: string
+  primaryDirectAgentId?: TAgentId
+  placeholderThreadPrefix?: string
+  findReusableThreadId?: (threads: TThread[]) => string | null
+  notifyBackgroundError?: (error: unknown, message: string) => void
+}
+
+export interface UseThreadManagementReturn<TThread extends ThreadManagementItem<TAgentId>, TAgentId extends string> {
+  threads: TThread[]
+  coreThreads: TThread[]
+  archivedThreads: TThread[]
+  currentThreadId: string | null
+  selectedAgentId: TAgentId | null
+  isLoadingThreads: boolean
+  isRefetchingThreads: boolean
+  hasMoreThreads: boolean
+  isFetchingNextThreadsPage: boolean
+  fetchNextThreadsPage: () => void
+  handleCreateNewThread: () => Promise<void>
+  handleSwitchThread: (threadId: string) => void
+  handleRenameThread: (threadId: string, newTitle: string) => Promise<void>
+  handleArchiveThread: (threadId: string) => Promise<void>
+  handleUnarchiveThread: (threadId: string) => Promise<void>
+  handleDeleteThread: (threadId: string) => Promise<void>
+}
+
+export function findReusableRegularGroupThreadId<TThread extends ThreadManagementItem>(
+  threads: TThread[],
+  defaultThreadTitle: string,
+): string | null {
+  const draft = threads.find(
+    (thread) =>
+      thread.mode === 'group' &&
+      !thread.core &&
+      thread.status === 'regular' &&
+      thread.title.trim() === defaultThreadTitle,
+  )
+
+  return draft?.threadId ?? null
+}
+
+export function useThreadManagement<TThread extends ThreadManagementItem<TAgentId>, TAgentId extends string>({
+  enabled = true,
+  isCreatingThread = false,
+  threads,
+  coreThreads,
+  archivedThreads,
+  currentThreadId,
+  selectedAgentId,
+  isLoadingThreads,
+  isRefetchingThreads,
+  hasMoreThreads,
+  isFetchingNextThreadsPage,
+  fetchNextThreadsPageRaw,
+  createThread,
+  renameThread,
+  archiveThread,
+  unarchiveThread,
+  deleteThread,
+  setCurrentThreadId,
+  setSelectedAgentId,
+  defaultThreadTitle,
+  primaryDirectAgentId,
+  placeholderThreadPrefix = PLACEHOLDER_THREAD_PREFIX,
+  findReusableThreadId,
+  notifyBackgroundError,
+}: UseThreadManagementOptions<TThread, TAgentId>): UseThreadManagementReturn<TThread, TAgentId> {
+  const fetchNextThreadsPage = useCallback(() => {
+    if (!enabled) return
+    if (hasMoreThreads && !isFetchingNextThreadsPage) {
+      void fetchNextThreadsPageRaw()
+    }
+  }, [enabled, fetchNextThreadsPageRaw, hasMoreThreads, isFetchingNextThreadsPage])
+
+  const allThreads = useMemo(() => [...threads, ...archivedThreads], [threads, archivedThreads])
+  const isCreatingThreadRef = useRef(false)
+  const allThreadsRef = useRef<TThread[]>(allThreads)
+  const threadsRef = useRef<TThread[]>(threads)
+  const currentThreadIdRef = useRef<string | null>(currentThreadId)
+  const createThreadRef = useRef(createThread)
+  const renameThreadRef = useRef(renameThread)
+  const archiveThreadRef = useRef(archiveThread)
+  const unarchiveThreadRef = useRef(unarchiveThread)
+  const deleteThreadRef = useRef(deleteThread)
+
+  useEffect(() => {
+    allThreadsRef.current = allThreads
+  }, [allThreads])
+
+  useEffect(() => {
+    threadsRef.current = threads
+  }, [threads])
+
+  useEffect(() => {
+    currentThreadIdRef.current = currentThreadId
+  }, [currentThreadId])
+
+  useEffect(() => {
+    createThreadRef.current = createThread
+    renameThreadRef.current = renameThread
+    archiveThreadRef.current = archiveThread
+    unarchiveThreadRef.current = unarchiveThread
+    deleteThreadRef.current = deleteThread
+  }, [archiveThread, createThread, deleteThread, renameThread, unarchiveThread])
+
+  const resolveReusableThreadId = useCallback(
+    (candidateThreads: TThread[]) =>
+      findReusableThreadId
+        ? findReusableThreadId(candidateThreads)
+        : findReusableRegularGroupThreadId(candidateThreads, defaultThreadTitle),
+    [defaultThreadTitle, findReusableThreadId],
+  )
+
+  const handleSwitchThread = useCallback(
+    (threadId: string) => {
+      const resolvedThreadId = threadId.startsWith(placeholderThreadPrefix)
+        ? (() => {
+            const agentId = threadId.slice(placeholderThreadPrefix.length) as TAgentId
+            const directThread = allThreadsRef.current.find(
+              (thread) => thread.mode === 'direct' && thread.agentId === agentId,
+            )
+            return directThread?.threadId
+          })()
+        : threadId
+
+      if (!resolvedThreadId) return
+
+      const target = allThreadsRef.current.find((thread) => thread.threadId === resolvedThreadId)
+      const nextAgentId = target?.mode === 'direct' && target.agentId ? target.agentId : null
+      setCurrentThreadId(resolvedThreadId)
+      setSelectedAgentId(nextAgentId)
+    },
+    [placeholderThreadPrefix, setCurrentThreadId, setSelectedAgentId],
+  )
+
+  const handleCreateNewThread = useCallback(async () => {
+    if (isCreatingThread) return
+
+    try {
+      const existingDraftThreadId = resolveReusableThreadId(threadsRef.current)
+      if (existingDraftThreadId) {
+        setCurrentThreadId(existingDraftThreadId)
+        setSelectedAgentId(null)
+        return
+      }
+
+      const result = await createThreadRef.current()
+      setCurrentThreadId(result.id)
+      setSelectedAgentId(null)
+    } catch (error) {
+      notifyBackgroundError?.(error, 'Failed to create thread.')
+      throw error
+    }
+  }, [isCreatingThread, notifyBackgroundError, resolveReusableThreadId, setCurrentThreadId, setSelectedAgentId])
+
+  const handleRenameThread = useCallback(async (threadId: string, newTitle: string) => {
+    const target = allThreadsRef.current.find((thread) => thread.threadId === threadId)
+    if (!target || !target.isMutable) return
+    await renameThreadRef.current({ threadId, title: newTitle })
+  }, [])
+
+  const handleArchiveThread = useCallback(
+    async (threadId: string) => {
+      const target = allThreadsRef.current.find((thread) => thread.threadId === threadId)
+      if (!target || !target.isMutable) return
+      await archiveThreadRef.current(threadId)
+      if (currentThreadIdRef.current === threadId) {
+        const remaining = threadsRef.current.filter((thread) => thread.threadId !== threadId)
+        if (remaining.length > 0) {
+          handleSwitchThread(remaining[0].threadId)
+        } else {
+          setCurrentThreadId(null)
+          setSelectedAgentId(null)
+        }
+      }
+    },
+    [handleSwitchThread, setCurrentThreadId, setSelectedAgentId],
+  )
+
+  const handleUnarchiveThread = useCallback(async (threadId: string) => {
+    const target = allThreadsRef.current.find((thread) => thread.threadId === threadId)
+    if (!target || !target.isMutable) return
+    await unarchiveThreadRef.current(threadId)
+  }, [])
+
+  const handleDeleteThread = useCallback(
+    async (threadId: string) => {
+      const target = allThreadsRef.current.find((thread) => thread.threadId === threadId)
+      if (!target || !target.isMutable) return
+      await deleteThreadRef.current(threadId)
+      if (currentThreadIdRef.current === threadId) {
+        const remaining = threadsRef.current.filter((thread) => thread.threadId !== threadId)
+        if (remaining.length > 0) {
+          handleSwitchThread(remaining[0].threadId)
+        } else {
+          setCurrentThreadId(null)
+          setSelectedAgentId(null)
+        }
+      }
+    },
+    [handleSwitchThread, setCurrentThreadId, setSelectedAgentId],
+  )
+
+  useEffect(() => {
+    if (currentThreadId) return
+    if (isLoadingThreads) return
+
+    if (threads.length > 0) {
+      const preferredThread =
+        primaryDirectAgentId === undefined
+          ? threads[0]
+          : (threads.find((thread) => thread.mode === 'direct' && thread.agentId === primaryDirectAgentId) ??
+            threads[0])
+      setCurrentThreadId(preferredThread.threadId)
+      setSelectedAgentId(preferredThread.mode === 'direct' && preferredThread.agentId ? preferredThread.agentId : null)
+      return
+    }
+
+    if (isCreatingThreadRef.current) return
+    if (isCreatingThread) return
+    isCreatingThreadRef.current = true
+
+    handleCreateNewThread()
+      .catch(() => {})
+      .finally(() => {
+        isCreatingThreadRef.current = false
+      })
+  }, [
+    currentThreadId,
+    handleCreateNewThread,
+    isCreatingThread,
+    isLoadingThreads,
+    primaryDirectAgentId,
+    setCurrentThreadId,
+    setSelectedAgentId,
+    threads,
+  ])
+
+  useEffect(() => {
+    if (!currentThreadId?.startsWith(placeholderThreadPrefix)) return
+
+    const agentId = currentThreadId.slice(placeholderThreadPrefix.length) as TAgentId
+    const directThread = allThreads.find((thread) => thread.mode === 'direct' && thread.agentId === agentId)
+    if (!directThread) return
+
+    setCurrentThreadId(directThread.threadId)
+    setSelectedAgentId(directThread.agentId ?? null)
+  }, [allThreads, currentThreadId, placeholderThreadPrefix, setCurrentThreadId, setSelectedAgentId])
+
+  useEffect(() => {
+    if (currentThreadId !== null || selectedAgentId === null) return
+
+    const directThread = allThreads.find((thread) => thread.mode === 'direct' && thread.agentId === selectedAgentId)
+    if (!directThread) return
+
+    setCurrentThreadId(directThread.threadId)
+  }, [allThreads, currentThreadId, selectedAgentId, setCurrentThreadId])
+
+  useEffect(() => {
+    if (!currentThreadId) {
+      if (selectedAgentId !== null) {
+        setSelectedAgentId(null)
+      }
+      return
+    }
+
+    const activeThread = allThreads.find((thread) => thread.threadId === currentThreadId)
+    if (!activeThread) return
+
+    const expectedAgentId = activeThread.mode === 'direct' && activeThread.agentId ? activeThread.agentId : null
+    if (selectedAgentId !== expectedAgentId) {
+      setSelectedAgentId(expectedAgentId)
+    }
+  }, [allThreads, currentThreadId, selectedAgentId, setSelectedAgentId])
+
+  return {
+    threads,
+    coreThreads,
+    archivedThreads,
+    currentThreadId,
+    selectedAgentId,
+    isLoadingThreads,
+    isRefetchingThreads,
+    hasMoreThreads: enabled ? hasMoreThreads : false,
+    isFetchingNextThreadsPage,
+    fetchNextThreadsPage,
+    handleCreateNewThread,
+    handleSwitchThread,
+    handleRenameThread,
+    handleArchiveThread,
+    handleUnarchiveThread,
+    handleDeleteThread,
+  }
+}

package/src/tools/execution-plan.ts

@@ -0,0 +1,80 @@
+import type { SerializableExecutionPlanTask } from '@lota-sdk/shared/schemas/execution-plan'
+import type { ExecutionPlanToolResultData } from '@lota-sdk/shared/schemas/tools'
+
+export function getLatestExecutionPlanResult(output: unknown): ExecutionPlanToolResultData | null {
+  if (output && typeof output === 'object' && 'hasPlan' in output) {
+    return output as ExecutionPlanToolResultData
+  }
+
+  if (Array.isArray(output)) {
+    for (let index = output.length - 1; index >= 0; index -= 1) {
+      const candidate = getLatestExecutionPlanResult(output[index])
+      if (candidate) return candidate
+    }
+  }
+
+  return null
+}
+
+export function getExecutionPlanActionLabel(action: string, isRunning: boolean): string {
+  if (isRunning) return 'Updating execution plan'
+
+  switch (action) {
+    case 'created':
+      return 'Execution plan created'
+    case 'replaced':
+      return 'Execution plan replaced'
+    case 'task-status-updated':
+      return 'Execution plan updated'
+    case 'task-restarted':
+      return 'Execution task restarted'
+    case 'loaded':
+      return 'Execution plan loaded'
+    default:
+      return 'Execution plan'
+  }
+}
+
+export function getExecutionPlanStatusLabel(status: string | null | undefined): string {
+  if (status === 'draft') return 'Draft'
+  if (status === 'executing') return 'Executing'
+  if (status === 'blocked') return 'Blocked'
+  if (status === 'completed') return 'Completed'
+  if (status === 'aborted') return 'Aborted'
+  return 'Idle'
+}
+
+export function getExecutionPlanOwnerLabel(
+  task: SerializableExecutionPlanTask,
+  displayNameByOwnerRef: Record<string, string> = {},
+): string {
+  if (task.ownerType === 'agent' && task.ownerRef in displayNameByOwnerRef) {
+    return displayNameByOwnerRef[task.ownerRef]
+  }
+  if (task.ownerType === 'user') return 'User'
+  return task.ownerRef
+}
+
+export function buildExecutionPlanToolViewModel(params: { input: unknown; isRunning: boolean; output: unknown }) {
+  const result = getLatestExecutionPlanResult(params.output)
+  const plan = result?.plan ?? null
+  const inputTitle =
+    params.input &&
+    typeof params.input === 'object' &&
+    'title' in params.input &&
+    typeof params.input.title === 'string'
+      ? params.input.title.trim()
+      : ''
+  const title = plan && plan.title.trim() ? plan.title.trim() : inputTitle || 'Execution plan'
+
+  return {
+    actionLabel: getExecutionPlanActionLabel(result?.action ?? 'none', params.isRunning),
+    hasPlan: plan !== null,
+    latestEvent: plan ? plan.recentEvents.at(-1)?.message.trim() : undefined,
+    plan,
+    progressSummary: plan ? `${plan.progress.completed}/${plan.progress.total} complete` : 'No active plan',
+    result,
+    statusLabel: getExecutionPlanStatusLabel(result?.status ?? plan?.status),
+    title,
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,3 @@
+export * from './execution-plan'
+export * from './tool-registry'
+export * from './user-questions'

package/src/tools/tool-registry.ts

@@ -0,0 +1,22 @@
+export type ToolRenderMode = 'framed' | 'standalone'
+
+export type ToolRegistryEntry<TComponent> = { component: TComponent; renderMode?: ToolRenderMode }
+
+export function createToolRegistry<const TRegistry extends Record<string, ToolRegistryEntry<unknown>>>(
+  registry: TRegistry,
+) {
+  type ToolName = keyof TRegistry & string
+
+  return {
+    registry,
+    isRegisteredTool(toolName: string): toolName is ToolName {
+      return toolName in registry
+    },
+    getToolComponent<TName extends ToolName>(toolName: TName): TRegistry[TName]['component'] | undefined {
+      return registry[toolName]?.component
+    },
+    resolveToolRenderMode(toolName: ToolName): ToolRenderMode {
+      return registry[toolName]?.renderMode ?? 'framed'
+    },
+  }
+}