@gram-ai/elements 1.33.2 → 1.34.0

package/src/types/index.ts

@@ -7,7 +7,7 @@ import {
   TextMessagePartComponent,
   ToolCallMessagePartComponent,
 } from "@assistant-ui/react";
-import { LanguageModel } from "ai";
+import { ChatTransport, LanguageModel, UIMessage } from "ai";
 import {
   ComponentType,
   Dispatch,
@@ -49,6 +49,39 @@ export interface MCPServerEntry {
 export const VARIANTS = ["widget", "sidecar", "standalone"] as const;
 export type Variant = (typeof VARIANTS)[number];
 
+/**
+ * Live chat context handed to a {@link ElementsTransportFactory}.
+ */
+export interface ElementsTransportContext {
+  /**
+   * The active conversation's persisted chat id, or null when the current
+   * thread has no server-side chat yet (a brand-new, not-yet-sent thread).
+   * Sourced from the thread-list runtime, so it stays current as the user
+   * switches conversations.
+   */
+  getChatId: () => string | null;
+
+  /**
+   * Adopt a chat id assigned out-of-band (e.g. a server-minted id a consumer
+   * transport receives on the first send). Call at the START of an async send
+   * to capture the active conversation, then invoke the returned function with
+   * the server's id once it's known. The closure binds to the conversation the
+   * send originated from, so a thread switch or a parallel send on another
+   * thread during the round-trip can't mis-associate the id.
+   */
+  adoptChatId: () => (chatId: string) => void;
+}
+
+/**
+ * A factory for a {@link ChatTransport}. When `ElementsConfig.transport` is a
+ * function, Elements invokes it once inside the provider and passes the live
+ * chat context, letting the transport read the current chat id at send time
+ * without reaching into Elements internals.
+ */
+export type ElementsTransportFactory = (
+  ctx: ElementsTransportContext,
+) => ChatTransport<UIMessage>;
+
 /**
  * The top level configuration object for the Elements library.
  *
@@ -65,6 +98,29 @@ export interface ElementsConfig {
    */
   systemPrompt?: string;
 
+  /**
+   * Optional chat transport override. When provided, Elements uses this
+   * transport instead of its built-in client-side streaming transport — e.g.
+   * to route the conversation through a persistent server-side assistant that
+   * generates replies and is polled for them. When omitted, the default
+   * client-side transport is used.
+   *
+   * May be a {@link ChatTransport} directly, or an {@link ElementsTransportFactory}
+   * that Elements invokes inside the provider with the live chat context — use
+   * the factory form when the transport needs the active chat id at send time.
+   */
+  transport?: ChatTransport<UIMessage> | ElementsTransportFactory;
+
+  /**
+   * Whether to expose the inline message-edit affordance on user messages.
+   * Edit relies on assistant-ui's local branch rewriting; transports backed by a
+   * persistent server-side assistant typically can't honour that, so the
+   * sidebar uses this to hide the action rather than offer a broken control.
+   *
+   * @default true
+   */
+  allowMessageEdit?: boolean;
+
   /**
    * Any plugins to use for the Elements library.
    *
@@ -1003,6 +1059,22 @@ export interface HistoryConfig {
    */
   enabled: boolean;
 
+  /**
+   * Extra query parameters forwarded to the thread-list request, used to
+   * filter which conversations are shown. Opaque to Elements — the consumer
+   * decides the keys (e.g. a search term, or a backend-specific scope). When
+   * omitted, all of the caller's chats are listed.
+   */
+  threadListFilters?: Record<string, string>;
+
+  /**
+   * Let the backend own chat-id creation. When true, a brand-new thread does not
+   * get a client-generated id; instead the transport assigns the id (e.g. one
+   * the server minted on the first send, reported via the transport context's
+   * `adoptChatId`). Use with a server-backed `transport`.
+   */
+  deferThreadIdMinting?: boolean;
+
   /**
    * Whether to show the thread list sidebar/panel.
    * Only applicable for widget and sidecar variants.