@gram-ai/elements 1.33.2 → 1.35.0

package/src/contexts/ConnectionStatusContext.tsx

@@ -36,7 +36,7 @@ interface ConnectionStatusProviderProps {
 
 export const ConnectionStatusProvider = ({
   children,
-}: ConnectionStatusProviderProps) => {
+}: ConnectionStatusProviderProps): React.JSX.Element => {
   const [state, setState] = useState<ConnectionState>("connected");
   const [retryCount, setRetryCount] = useState(0);
   const [isOnline, setIsOnline] = useState(
@@ -138,7 +138,7 @@ export const ConnectionStatusProvider = ({
   );
 };
 
-export const useConnectionStatus = () => {
+export const useConnectionStatus = (): ConnectionStatusContextValue => {
   const context = useContext(ConnectionStatusContext);
   if (!context) {
     throw new Error(
@@ -153,6 +153,7 @@ export const useConnectionStatus = () => {
  * Returns null if not within a ConnectionStatusProvider (for backwards compatibility).
  */
 
-export const useConnectionStatusOptional = () => {
-  return useContext(ConnectionStatusContext);
-};
+export const useConnectionStatusOptional =
+  (): ConnectionStatusContextValue | null => {
+    return useContext(ConnectionStatusContext);
+  };

package/src/contexts/ElementsProvider.tsx

@@ -17,7 +17,6 @@ import {
   wrapToolsWithApproval,
   wrapToolsWithByteCap,
   type ApprovalHelpers,
-  type FrontendTool,
 } from "@/lib/tools";
 import { compactForModel } from "@/lib/contextCompaction";
 import { describeStreamError } from "@/lib/streamErrorMessage";
@@ -49,6 +48,8 @@ import {
   type ChatTransport,
   type UIMessage,
 } from "ai";
+
+type UIMessagePart = UIMessage["parts"][number];
 import {
   ReactNode,
   useCallback,
@@ -67,30 +68,47 @@ import { ElementsContext } from "./contexts";
 import { ToolApprovalProvider } from "./ToolApprovalContext";
 import { ToolExecutionProvider } from "./ToolExecutionContext";
 
+// Reads the active local thread id from the runtime's threads store. Goes
+// through assistant-ui's public ThreadListRuntime.getState() API.
+function getActiveLocalThreadId(
+  runtimeRef: React.RefObject<ReturnType<typeof useChatRuntime> | null>,
+): string | undefined {
+  const threadsState = runtimeRef.current?.threads.getState();
+  if (!threadsState) return undefined;
+  // `mainThreadId` is always populated by the SDK; the secondary read is a
+  // defensive fallback in case the SDK ever returns a state shape with an
+  // older `threadIds` field instead. The cast widens to an indexable shape
+  // because `ThreadListState` doesn't declare that historical field.
+  const legacy = (threadsState as { threadIds?: readonly string[] }).threadIds;
+  return threadsState.mainThreadId ?? legacy?.[0];
+}
+
+type ExecutableTool = {
+  execute?: (args: unknown, options?: unknown) => Promise<unknown>;
+};
+
 /**
  * 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.
+ *
+ * The AI SDK's `ToolExecuteFunction<INPUT, OUTPUT>` signature is too strict on
+ * its second parameter (a typed `ToolCallOptions`) and too broad on its return
+ * (`AsyncIterable | PromiseLike | OUTPUT`) to match `ExecutableTool.execute`
+ * directly. The reference is copied as-is — no runtime wrapping — and only the
+ * type surface is widened.
  */
 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> }
-> {
+  frontendTools: Record<string, AssistantTool> | undefined,
+): Record<string, ExecutableTool> {
   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,
-        },
-      ];
+      const toolDef = tool.unstable_tool as {
+        execute?: ExecutableTool["execute"];
+      };
+      return [name, { execute: toolDef.execute }];
     }),
   );
 }
@@ -141,13 +159,14 @@ function cleanMessagesForModel(messages: UIMessage[]): UIMessage[] {
       return message;
     }
 
-    // Process each part: strip providerOptions/providerMetadata and filter reasoning
-    // 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
-      const { callProviderMetadata: _, ...cleanPart } = part;
-      return cleanPart;
+    // Process each part: strip providerOptions/providerMetadata and filter reasoning.
+    // `callProviderMetadata` is not declared on `UIMessagePart`, so we widen the
+    // part to an indexable record just for the destructure.
+    const cleanedParts = partsArray.map((part) => {
+      const { callProviderMetadata: _omit, ...cleanPart } =
+        part as UIMessagePart & { callProviderMetadata?: unknown };
+      void _omit;
+      return cleanPart as UIMessagePart;
     });
 
     return {
@@ -205,6 +224,7 @@ const ElementsProviderInner = ({ children, config }: ElementsProviderProps) => {
       projectSlug: config.projectSlug,
       variant: config.variant,
     });
+    // oxlint-disable-next-line react-hooks/exhaustive-deps -- one-time init at mount; later config changes are intentionally ignored
   }, []);
 
   // Generate a stable chat ID for server-side persistence (when history is disabled)
@@ -214,7 +234,11 @@ const ElementsProviderInner = ({ children, config }: ElementsProviderProps) => {
   // State to expose the current chat ID via context
   const [currentChatId, setCurrentChatId] = useState<string | null>(null);
 
-  const { data: mcpTools, mcpHeaders } = useMCPTools({
+  const {
+    data: mcpTools,
+    mcpHeaders,
+    isLoading: mcpQueryLoading,
+  } = useMCPTools({
     auth,
     mcp: config.mcp,
     mcps: config.mcps,
@@ -222,6 +246,11 @@ const ElementsProviderInner = ({ children, config }: ElementsProviderProps) => {
     toolsToInclude: config.tools?.toolsToInclude,
     gramEnvironment: config.gramEnvironment,
   });
+  // Treat auth-loading as "tools not yet resolved" too — the MCP query is
+  // disabled (and so not "loading") until auth settles, so without this a
+  // tool-list consumer would briefly see an empty, settled state before tools
+  // arrive.
+  const mcpToolsLoading = auth.isLoading || mcpQueryLoading;
 
   // Store approval helpers in ref so they can be used in async contexts
   const approvalHelpersRef = useRef<ApprovalHelpers>({
@@ -276,8 +305,10 @@ const ElementsProviderInner = ({ children, config }: ElementsProviderProps) => {
   // in a way that's accessible from the transport's sendMessages function.
   const currentRemoteIdRef = useRef<string | null>(null);
 
-  // Create chat transport configuration
-  const transport = useMemo<ChatTransport<UIMessage>>(
+  // Create chat transport configuration. This is the built-in client-side
+  // streaming transport; a consumer can override it via config.transport (see
+  // below) to route the conversation through a server-side assistant instead.
+  const defaultTransport = useMemo<ChatTransport<UIMessage>>(
     () => ({
       sendMessages: async ({ messages, abortSignal }) => {
         const usingCustomModel = !!config.languageModel;
@@ -298,12 +329,7 @@ const ElementsProviderInner = ({ children, config }: ElementsProviderProps) => {
           // chatId is already set correctly from the synced ref
         } else if (isLocalThreadId(chatId) || !chatId) {
           // For local thread IDs or no ID, check/generate UUID mapping
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          const runtimeAny = runtimeRef.current as any;
-          const threadsState = runtimeAny?.threads?.getState?.();
-          const localThreadId = (threadsState?.mainThreadId ??
-            threadsState?.threadIds?.[0]) as string | undefined;
-
+          const localThreadId = getActiveLocalThreadId(runtimeRef);
           const lookupKey = chatId ?? localThreadId;
           if (lookupKey) {
             const existingUuid = localIdToUuidMapRef.current.get(lookupKey);
@@ -512,8 +538,11 @@ const ElementsProviderInner = ({ children, config }: ElementsProviderProps) => {
       config.contextCompaction?.maxTokens,
       config.contextCompaction?.compactAtFraction,
       config.contextCompaction?.keepRecent,
+      config.gramEnvironment,
+      config.api?.headers,
       model,
       mcpTools,
+      mcpHeaders,
       getApprovalHelpers,
       apiUrl,
       auth.isLoading,
@@ -521,6 +550,44 @@ const ElementsProviderInner = ({ children, config }: ElementsProviderProps) => {
     ],
   );
 
+  // A consumer-supplied transport (e.g. a server-side assistant transport) takes
+  // precedence over the built-in client-side one. It may be a ChatTransport or a
+  // factory: a factory is invoked here, inside the provider, with a getChatId()
+  // sourced from the synced thread state, so the transport can read the active
+  // chat id at send time without reaching into Elements internals. Local
+  // (unpersisted) thread ids read as null so the transport can treat them as a
+  // brand-new conversation.
+  const getChatId = useCallback(() => {
+    const id = currentRemoteIdRef.current;
+    return id && !isLocalThreadId(id) ? id : null;
+  }, []);
+  // Capture the active local thread identity now and return a bind function
+  // closing over it. Consumer transports call this at the start of
+  // `sendMessages`; once a server-minted chat id is known, invoking the
+  // returned function reconciles the captured thread to it — the same
+  // reconciliation the built-in transport does inline when it generates an id.
+  // Closing over the captured id (instead of re-reading active state at bind
+  // time) is what makes a thread switch or a parallel send on another thread
+  // during the round-trip safe.
+  const adoptChatId = useCallback(() => {
+    const capturedLocalThreadId = getActiveLocalThreadId(runtimeRef);
+    return (chatId: string) => {
+      if (capturedLocalThreadId) {
+        localIdToUuidMapRef.current.set(capturedLocalThreadId, chatId);
+      }
+      currentRemoteIdRef.current = chatId;
+      mcpHeaders["Gram-Chat-ID"] = chatId;
+      setCurrentChatId(chatId);
+    };
+  }, [mcpHeaders, setCurrentChatId]);
+  const configTransport = config.transport;
+  const transport = useMemo<ChatTransport<UIMessage>>(() => {
+    if (typeof configTransport === "function") {
+      return configTransport({ getChatId, adoptChatId });
+    }
+    return configTransport ?? defaultTransport;
+  }, [configTransport, defaultTransport, getChatId, adoptChatId]);
+
   const historyEnabled = config.history?.enabled ?? false;
 
   // Shared context value for ElementsContext
@@ -535,8 +602,9 @@ const ElementsProviderInner = ({ children, config }: ElementsProviderProps) => {
       setIsOpen,
       plugins,
       mcpTools,
+      mcpToolsLoading,
     }),
-    [config, model, isExpanded, isOpen, plugins, mcpTools],
+    [config, model, isExpanded, isOpen, plugins, mcpTools, mcpToolsLoading],
   );
 
   const frontendTools = config.tools?.frontendTools ?? {};
@@ -610,8 +678,7 @@ interface ElementsProviderWithHistoryProps {
   headers: Record<string, string>;
   contextValue: React.ContextType<typeof ElementsContext>;
   runtimeRef: React.RefObject<ReturnType<typeof useChatRuntime> | null>;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  frontendTools: Record<string, AssistantTool | FrontendTool<any, any>>;
+  frontendTools: Record<string, AssistantTool>;
   localIdToUuidMap: Map<string, string>;
   currentRemoteIdRef: React.RefObject<string | null>;
   executableTools: ExecutableToolSet;
@@ -658,6 +725,9 @@ const ElementsProviderWithHistory = ({
     apiUrl,
     headers,
     localIdToUuidMap,
+    threadListFilters: contextValue?.config.history?.threadListFilters,
+    deferThreadIdMinting: contextValue?.config.history?.deferThreadIdMinting,
+    transformChatMessage: contextValue?.config.history?.transformChatMessage,
   });
   const initialThreadId = contextValue?.config.history?.initialThreadId;
 
@@ -665,6 +735,7 @@ const ElementsProviderWithHistory = ({
   // half-finished: the tool-result is patched in but the agent never resumes,
   // so the next user message lands on top of an unresolved tool-call sequence.
   const useChatRuntimeHook = useCallback(() => {
+    // oxlint-disable-next-line react-hooks/rules-of-hooks -- intentional: useChatRuntime is invoked by useRemoteThreadListRuntime as a hook for each thread
     return useChatRuntime({
       transport,
       sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
@@ -736,8 +807,7 @@ interface ElementsProviderWithoutHistoryProps {
   transport: ChatTransport<UIMessage>;
   contextValue: React.ContextType<typeof ElementsContext>;
   runtimeRef: React.RefObject<ReturnType<typeof useChatRuntime> | null>;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  frontendTools: Record<string, AssistantTool | FrontendTool<any, any>>;
+  frontendTools: Record<string, AssistantTool>;
   executableTools: ExecutableToolSet;
   currentChatId: string | null;
 }
@@ -786,7 +856,9 @@ const ElementsProviderWithoutHistory = ({
 
 const queryClient = new QueryClient();
 
-export const ElementsProvider = (props: ElementsProviderProps) => {
+export const ElementsProvider = (
+  props: ElementsProviderProps,
+): React.JSX.Element => {
   return (
     <QueryClientProvider client={queryClient}>
       <ConnectionStatusProvider>

package/src/contexts/ReplayContext.ts

@@ -2,6 +2,6 @@ import { createContext, useContext } from "react";
 
 export const ReplayContext = createContext<{ isReplay: boolean } | null>(null);
 
-export function useReplayContext() {
+export function useReplayContext(): { isReplay: boolean } | null {
   return useContext(ReplayContext);
 }

package/src/contexts/ToolApprovalContext.tsx

@@ -26,7 +26,11 @@ interface ToolApprovalContextType {
   getPendingApproval: (toolCallId: string) => PendingApproval | undefined;
 }
 
-export function ToolApprovalProvider({ children }: { children: ReactNode }) {
+export function ToolApprovalProvider({
+  children,
+}: {
+  children: ReactNode;
+}): React.JSX.Element {
   const [pendingApprovals, setPendingApprovals] = useState<
     Map<string, PendingApproval>
   >(new Map());

package/src/contexts/ToolExecutionContext.tsx

@@ -36,7 +36,7 @@ interface ToolExecutionProviderProps {
 export function ToolExecutionProvider({
   children,
   tools,
-}: ToolExecutionProviderProps) {
+}: ToolExecutionProviderProps): React.JSX.Element {
   const executeTool = useCallback(
     async (
       toolName: string,

package/src/contexts/portal-container.tsx

@@ -11,7 +11,7 @@ export function PortalContainerProvider({
 }: {
   containerRef: RefObject<HTMLElement | null>;
   children: React.ReactNode;
-}) {
+}): React.JSX.Element {
   return (
     <PortalContainerContext.Provider value={containerRef}>
       {children}

package/src/hooks/useAuth.ts

@@ -131,7 +131,8 @@ export const useAuth = ({
   // useMCPTools). Today the dashboard uses this to forward
   // `Authorization: Bearer <user-session JWT>` so the runtime gateway can
   // resolve the user's upstream credentials for issuer-gated toolsets.
-  const extraHeaders = auth?.headers ?? {};
+  const authHeaders = auth?.headers;
+  const extraHeaders = useMemo(() => authHeaders ?? {}, [authHeaders]);
 
   const ensureValidHeaders = useCallback(async (): Promise<
     Record<string, string>

package/src/hooks/useDensity.ts

@@ -102,7 +102,7 @@ type DensityToken = keyof (typeof densityClasses)["normal"];
  * Hook to get density classes based on theme config
  * Use: const d = useDensity(); then d('p-md') returns the appropriate padding class
  */
-export const useDensity = () => {
+export const useDensity = (): ((token: DensityToken) => string) => {
   const { config } = useElements();
   const density = config.theme?.density ?? "normal";
 

package/src/hooks/useElements.ts

@@ -1,11 +1,12 @@
 import { useContext } from "react";
 import { ElementsContext } from "@/contexts/contexts";
+import type { ElementsContextType } from "@/types";
 
 /**
  * @private Internal hook to access the ElementsContext
  *
  */
-export const useElements = () => {
+export const useElements = (): ElementsContextType => {
   const context = useContext(ElementsContext);
   if (!context) {
     throw new Error("useElements must be used within a ElementsProvider");

package/src/hooks/useFollowOnSuggestions.ts

@@ -1,5 +1,4 @@
 import { useReplayContext } from "@/contexts/ReplayContext";
-import { getApiUrl } from "@/lib/api";
 import { useAssistantState } from "@assistant-ui/react";
 import { generateObject } from "ai";
 import { useCallback, useEffect, useRef, useState } from "react";
@@ -64,8 +63,6 @@ export function useFollowOnSuggestions(): {
   const isRunning = useAssistantState(({ thread }) => thread.isRunning);
   const messages = useAssistantState(({ thread }) => thread.messages);
 
-  const apiUrl = getApiUrl(config);
-
   const fetchSuggestions = useCallback(async () => {
     if (!isEnabled || auth.isLoading || !auth.headers) return;
 
@@ -89,7 +86,7 @@ export function useFollowOnSuggestions(): {
     let lastAssistantMessage = "";
     for (let i = recentMessages.length - 1; i >= 0; i--) {
       const msg = recentMessages[i];
-      if (msg.role === "assistant") {
+      if (msg && msg.role === "assistant") {
         lastAssistantMessage = msg.content;
         break;
       }
@@ -191,7 +188,7 @@ ${conversation}`,
         abortControllerRef.current = null;
       }
     }
-  }, [isEnabled, apiUrl, auth.headers, auth.isLoading, messages]);
+  }, [isEnabled, auth.headers, auth.isLoading, messages, model]);
 
   // Fetch suggestions when:
   // 1. The thread stops running (assistant finished responding)
@@ -224,7 +221,7 @@ ${conversation}`,
     if (lastProcessedMessageIdRef.current === lastMessage.id) return;
 
     lastProcessedMessageIdRef.current = lastMessage.id;
-    fetchSuggestions();
+    void fetchSuggestions();
   }, [isRunning, messages, fetchSuggestions, auth.isLoading, auth.headers]);
 
   // Cleanup on unmount

package/src/hooks/useGramThreadListAdapter.tsx

@@ -10,9 +10,11 @@ import { createAssistantStream, type AssistantStream } from "assistant-stream";
 import {
   GramChatOverview,
   GramChat,
+  GramChatMessage,
   convertGramMessagesToExported,
   convertGramMessagesToUIMessages,
 } from "@/lib/messageConverter";
+import { sleep } from "@/lib/utils";
 import {
   useCallback,
   useEffect,
@@ -37,11 +39,61 @@ export function isLocalThreadId(threadId: string | null | undefined): boolean {
   return !!threadId?.startsWith(LOCAL_THREAD_ID_PREFIX);
 }
 
+/**
+ * Polls the shared local→remote id map until the transport assigns an id for
+ * `threadId`, or a deadline passes. Used in deferred-minting mode so a new
+ * thread adopts the backend-minted chat id instead of a client-generated one.
+ * The timeout is generous to tolerate cold serverless boots on the first send.
+ */
+async function waitForMappedId(
+  map: Map<string, string> | undefined,
+  threadId: string,
+  timeoutMs = 30_000,
+  intervalMs = 50,
+): Promise<string | undefined> {
+  if (!map) return undefined;
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const id = map.get(threadId);
+    if (id) return id;
+    if (Date.now() >= deadline) return undefined;
+    await sleep(intervalMs);
+  }
+}
+
+/**
+ * Transforms or drops a persisted chat message before it is rendered from
+ * history. Return the (possibly rewritten) message, or `null` to omit it.
+ */
+export type ChatMessageTransform = (
+  message: GramChatMessage,
+) => GramChatMessage | null;
+
 export interface ThreadListAdapterOptions {
   apiUrl: string;
   headers: Record<string, string>;
   /** Map to translate local thread IDs to UUIDs (shared with transport) */
   localIdToUuidMap?: Map<string, string>;
+  /**
+   * Extra query parameters forwarded to `chat.list` to filter which threads are
+   * listed. Opaque to the adapter — the consumer chooses the keys.
+   */
+  threadListFilters?: Record<string, string>;
+  /**
+   * Don't client-mint a chat id for a brand-new thread. When true, `initialize`
+   * waits for the transport to assign the id (via the shared `localIdToUuidMap`,
+   * e.g. a server-minted id reported through the transport context's
+   * `adoptChatId` bind closure) instead of generating one with
+   * `crypto.randomUUID()`. Use this when the backend owns chat-id creation.
+   */
+  deferThreadIdMinting?: boolean;
+  /**
+   * Optional hook to transform or drop each persisted message before it is
+   * converted for rendering. Return a message to render it (possibly rewritten),
+   * or `null` to omit it. Keeps product-specific transcript conventions out of
+   * the library — see {@link HistoryConfig.transformChatMessage}.
+   */
+  transformChatMessage?: ChatMessageTransform;
 }
 
 interface ListChatsResponse {
@@ -57,15 +109,41 @@ class GramThreadHistoryAdapter {
   private apiUrl: string;
   private headers: Record<string, string>;
   private store: AssistantApi;
+  // Read lazily rather than captured: the adapter is constructed once, but the
+  // consumer may swap `transformChatMessage` across renders, so resolve it from
+  // the live options on every load instead of snapshotting it here.
+  private getTransformChatMessage?: () => ChatMessageTransform | undefined;
 
   constructor(
     apiUrl: string,
     headers: Record<string, string>,
     store: AssistantApi,
+    getTransformChatMessage?: () => ChatMessageTransform | undefined,
   ) {
     this.apiUrl = apiUrl;
     this.headers = headers;
     this.store = store;
+    this.getTransformChatMessage = getTransformChatMessage;
+  }
+
+  /**
+   * Applies the consumer-supplied `transformChatMessage` hook to a loaded
+   * transcript: rewrites each message and drops any the hook returns `null` for.
+   * Without a hook configured the messages pass through untouched.
+   */
+  private applyTransform(messages: GramChatMessage[]): GramChatMessage[] {
+    const transform = this.getTransformChatMessage?.();
+    if (!transform) {
+      return messages;
+    }
+    const result: GramChatMessage[] = [];
+    for (const message of messages) {
+      const transformed = transform(message);
+      if (transformed) {
+        result.push(transformed);
+      }
+    }
+    return result;
   }
 
   async load() {
@@ -86,7 +164,7 @@ class GramThreadHistoryAdapter {
       }
 
       const chat = (await response.json()) as GramChat;
-      return convertGramMessagesToExported(chat.messages);
+      return convertGramMessagesToExported(this.applyTransform(chat.messages));
     } catch (error) {
       console.error("Error loading chat:", error);
       return { messages: [], headId: null };
@@ -120,7 +198,9 @@ class GramThreadHistoryAdapter {
         }
 
         const chat = (await response.json()) as GramChat;
-        return convertGramMessagesToUIMessages(chat.messages);
+        return convertGramMessagesToUIMessages(
+          this.applyTransform(chat.messages),
+        );
 
         // // Filter out system messages (assistant-ui doesn't support them in the import path)
         // const filteredMessages = chat.messages.filter(
@@ -175,6 +255,7 @@ function useGramThreadHistoryAdapter(
         optionsRef.current.apiUrl,
         optionsRef.current.headers,
         store,
+        () => optionsRef.current.transformChatMessage,
       ),
   );
   // Cast to ThreadHistoryAdapter - the withFormat generic doesn't match but works at runtime
@@ -213,12 +294,14 @@ export function useGramThreadListAdapter(
 
       async list() {
         try {
-          const response = await fetch(
-            `${optionsRef.current.apiUrl}/rpc/chat.list`,
-            {
-              headers: optionsRef.current.headers,
-            },
-          );
+          const { apiUrl, headers, threadListFilters } = optionsRef.current;
+          const qs = threadListFilters
+            ? new URLSearchParams(threadListFilters).toString()
+            : "";
+          const listUrl = qs
+            ? `${apiUrl}/rpc/chat.list?${qs}`
+            : `${apiUrl}/rpc/chat.list`;
+          const response = await fetch(listUrl, { headers });
 
           if (!response.ok) {
             console.error("Failed to list chats:", response.status);
@@ -252,6 +335,30 @@ export function useGramThreadListAdapter(
               externalId: existingUuid,
             };
           }
+          // When the backend owns chat-id creation, don't client-mint: wait for
+          // the transport to report the server-minted id (it assigns it during
+          // the first send via the adoptChatId bind closure, populating the
+          // shared map — the same path the built-in transport uses).
+          if (optionsRef.current.deferThreadIdMinting) {
+            const mappedUuid = await waitForMappedId(
+              optionsRef.current.localIdToUuidMap,
+              threadId,
+            );
+            if (mappedUuid) {
+              return {
+                remoteId: mappedUuid,
+                externalId: mappedUuid,
+              };
+            }
+            // Falling through to crypto.randomUUID() here would defeat deferred
+            // minting: the client id would race the server-minted one reported
+            // later via the adoptChatId bind closure, leaving runtime state
+            // and the local→remote map disagreeing. Surface the failure to
+            // the user instead.
+            throw new Error(
+              "Backend did not mint a chat id in time — first send may have failed or is still in flight. Retry the send.",
+            );
+          }
           // Otherwise generate a new one and store it
           const uuid = crypto.randomUUID();
           optionsRef.current.localIdToUuidMap?.set(threadId, uuid);
@@ -298,7 +405,9 @@ export function useGramThreadListAdapter(
         // Title generation happens async server-side via Temporal after first completion.
         // This delay allows the OpenRouter LLM call to complete before we fetch the title.
         const TITLE_GENERATION_DELAY_MS = 2000;
-        await new Promise((r) => setTimeout(r, TITLE_GENERATION_DELAY_MS));
+        await new Promise((r) => {
+          setTimeout(r, TITLE_GENERATION_DELAY_MS);
+        });
 
         try {
           // TODO: rename generateTitle endpoint to getTitle

package/src/hooks/useMCPTools.ts

@@ -42,10 +42,10 @@ export function useMCPTools({
   );
 
   const envQueryKey = Object.entries(environment ?? {}).map(
-    ([k, v]) => `${k}:${v}`,
+    ([k, v]) => `${k}:${String(v)}`,
   );
   const authQueryKey = Object.entries(auth.headers ?? {}).map(
-    ([k, v]) => `${k}:${v}`,
+    ([k, v]) => `${k}:${String(v)}`,
   );
   const serversQueryKey = servers.map(
     (s) => `${s.url}|${s.name ?? ""}|${s.environment ?? ""}`,

package/src/hooks/useModel.ts

@@ -5,9 +5,7 @@ import { useAuth } from "./useAuth";
 import { useElements } from "./useElements";
 
 // Creates an OpenRouter client to be used for "internal Gram" usage, such as follow-on suggestions
-export const useModel = (
-  model: string = "openai/gpt-5.4-mini",
-): LanguageModel => {
+export const useModel = (model = "openai/gpt-5.4-mini"): LanguageModel => {
   const { config } = useElements();
 
   const auth = useAuth({

package/src/hooks/usePluginComponents.ts

@@ -15,7 +15,9 @@ type ComponentsByLanguage =
     >
   | undefined;
 
-export function useComponentsByLanguage(plugins: Plugin[]) {
+export function useComponentsByLanguage(
+  plugins: Plugin[],
+): ComponentsByLanguage {
   return useMemo(() => {
     return plugins.reduce((acc, plugin) => {
       if (acc?.[plugin.language] && !plugin.overrideExisting) {