stream-chat-react-native-core 9.12.1 → 9.13.0

package/src/ai-components/conversation/controller/AIConversationExchange.ts

@@ -0,0 +1,132 @@
+import isEqual from 'lodash/isEqual';
+
+import type { AIConversationRequest } from './types';
+
+import { generateUUIDv4 } from '../../internal/uuid';
+import type { AIMessageAttachmentData } from '../../message/AIMessageAttachment';
+import type { MediaAsset } from '../../services/media-picker-service/AbstractMediaPickerService';
+import type { AIMessage, AIPendingMessage } from '../types';
+
+// Where the request is: waiting for its reply, stopped by the person before it started, not
+// sent because the transport failed, or not answered by the agent.
+export type AIConversationExchangeState = 'waiting' | 'stopped' | 'failed' | 'unanswered';
+
+// A reply the agent has started with no text, steps or attachments yet. Its generated UI can
+// still show, when the conversation's host reads it.
+export const hasEmptyContent = (message: AIMessage) =>
+  message.role !== 'user' &&
+  message.text === '' &&
+  !message.parts?.length &&
+  !message.attachments?.length;
+
+// Whether a reply is written again since it was `original`: it started anew, or it shows
+// something else.
+const isRewritten = (message: AIMessage, original: AIMessage) =>
+  (!!message.isGenerating && !original.isGenerating) ||
+  message.text !== original.text ||
+  !isEqual(message.parts ?? [], original.parts ?? []) ||
+  !isEqual(message.attachments ?? [], original.attachments ?? []) ||
+  !isEqual(message.uiDocument, original.uiDocument);
+
+export const attachmentOfAsset = (asset: MediaAsset): AIMessageAttachmentData => ({
+  kind: !asset.type || asset.type.startsWith('image') ? 'image' : 'file',
+  mimeType: asset.type?.includes('/') ? asset.type : undefined,
+  name: asset.name,
+  size: asset.size,
+  url: asset.uri,
+});
+
+// The latest request, until its reply starts or another request takes its place.
+export class AIConversationExchange<Message extends AIMessage> {
+  state: AIConversationExchangeState = 'waiting';
+  // The messages there were when it was made, none of which is its reply.
+  readonly known: Set<string>;
+  // The messages it replaces, as they were, which the conversation leaves out while it waits:
+  // the reply written again, or the message edited, and those after it.
+  readonly replaced: Map<string, Message>;
+  // The person's message on its way.
+  readonly pending: AIPendingMessage | undefined;
+
+  constructor(
+    // Tells it apart from the requests before and after it.
+    readonly id: number,
+    readonly request: AIConversationRequest<Message>,
+    conversation: readonly Message[],
+  ) {
+    this.known = new Set(conversation.map((message) => message.id));
+    const target = request.message
+      ? conversation.findIndex((message) => message.id === request.message?.id)
+      : -1;
+    this.replaced = new Map(
+      target >= 0 && (request.kind === 'regenerate' || request.kind === 'edit')
+        ? conversation.slice(target).map((message) => [message.id, message])
+        : [],
+    );
+    if (request.kind === 'regenerate') {
+      this.pending = undefined;
+    } else {
+      const edited = request.kind === 'edit' ? (request.message?.attachments ?? []) : [];
+      this.pending = {
+        attachments: [...edited, ...request.attachments.map(attachmentOfAsset)],
+        id: request.messageId,
+        text: request.text,
+      };
+    }
+  }
+
+  get hasFailed() {
+    return this.state === 'failed' || this.state === 'unanswered';
+  }
+
+  // The person's message while the conversation shows it: until its reply starts, and for a
+  // new message also once it is stopped or failed, since the agent may have it, or `retry()`
+  // sends it again. The messages an edit replaces come back instead.
+  get shownPending() {
+    return this.state === 'waiting' || this.request.kind === 'message' ? this.pending : undefined;
+  }
+
+  // The latest message when it is the request's reply: a reply that wasn't there, or one the
+  // request replaces, once it is written again.
+  reply(conversation: readonly Message[]) {
+    const last = conversation[conversation.length - 1];
+    if (!last || last.role === 'user') return undefined;
+    const original = this.replaced.get(last.id);
+    const rewritten = original ? isRewritten(last, original) : false;
+    return !this.known.has(last.id) || rewritten ? last : undefined;
+  }
+
+  // Whether its reply has started: it shows something, or it is already finished.
+  hasReplyStarted(conversation: readonly Message[]) {
+    const reply = this.reply(conversation);
+    return !!reply && (!hasEmptyContent(reply) || !reply.isGenerating);
+  }
+
+  // Whether the person's message is in the conversation: one with its id, or one of theirs
+  // after the messages there were.
+  hasMessageArrived(conversation: readonly Message[]) {
+    if (conversation.some((message) => message.id === this.request.messageId)) return true;
+    let lastKnown = -1;
+    conversation.forEach((message, index) => {
+      if (this.known.has(message.id)) lastKnown = index;
+    });
+    return conversation.slice(lastKnown + 1).some((message) => message.role === 'user');
+  }
+
+  // What `retry()` sends: the request again, or, when the agent had the person's message but
+  // couldn't answer it, a request for its reply, since sending it again would add it twice.
+  retryRequest(conversation: readonly Message[]): AIConversationRequest<Message> {
+    if (
+      this.state !== 'unanswered' ||
+      this.request.kind !== 'message' ||
+      !this.hasMessageArrived(conversation)
+    ) {
+      return this.request;
+    }
+    return {
+      attachments: [],
+      kind: 'regenerate',
+      messageId: generateUUIDv4(),
+      text: this.request.text,
+    };
+  }
+}

package/src/ai-components/conversation/controller/index.ts

@@ -0,0 +1,4 @@
+export * from './AIAgentError';
+export * from './AIConversationController';
+export * from './types';
+export * from './useAIConversationState';

package/src/ai-components/conversation/controller/offers.ts

@@ -0,0 +1,43 @@
+import { type AIConversationStatus, isAIConversationAnswering } from './types';
+
+import type { AIMessageRating, AIReplyActionsProps } from '../../message/AIReplyActions';
+import type { AIMessage } from '../types';
+
+type Offerer<Message extends AIMessage> = {
+  actions: { edit: boolean; rate: boolean; regenerate: boolean };
+  edit: (message: Message) => void;
+  rate: (reply: Message, rating: AIMessageRating | null) => void;
+  regenerate: (reply: Message) => void;
+};
+
+// What the person can do with a finished reply: rate it, and write it again while it is the
+// latest and the agent isn't answering.
+export const replyActionsOf = <Message extends AIMessage>(
+  offerer: Offerer<Message>,
+  {
+    ratings,
+    status,
+  }: { ratings: Readonly<Record<string, AIMessageRating>>; status: AIConversationStatus },
+  reply: Message,
+  isLatestReply: boolean,
+): Omit<AIReplyActionsProps, 'text'> => ({
+  onRate: offerer.actions.rate ? (rating) => offerer.rate(reply, rating) : undefined,
+  onRegenerate:
+    offerer.actions.regenerate && isLatestReply && !isAIConversationAnswering(status)
+      ? () => offerer.regenerate(reply)
+      : undefined,
+  rating: ratings[reply.id] ?? null,
+});
+
+// Edits a message of the person's, when it is their latest and the agent isn't answering.
+export const editActionOf = <Message extends AIMessage>(
+  offerer: Offerer<Message>,
+  { messages, status }: { messages: readonly Message[]; status: AIConversationStatus },
+  message: Message,
+): (() => void) | undefined => {
+  if (!offerer.actions.edit || message.role !== 'user' || isAIConversationAnswering(status)) {
+    return undefined;
+  }
+  const latest = [...messages].reverse().find((item) => item.role === 'user');
+  return latest?.id === message.id ? () => offerer.edit(message) : undefined;
+};

package/src/ai-components/conversation/controller/types.ts

@@ -0,0 +1,154 @@
+import type { AIMessageRating } from '../../message/AIReplyActions';
+import type { AIChatOption } from '../../message-composer/ChatOptions';
+import type { MediaAsset } from '../../services/media-picker-service/AbstractMediaPickerService';
+import type { AIMessage } from '../types';
+
+/**
+ * Where the latest exchange with the agent is:
+ * - `ready`: nothing is on its way: the agent answered, or the person stopped it.
+ * - `submitted`: the person's request is on its way, or the agent is working on it and its reply
+ *   shows nothing yet.
+ * - `streaming`: the agent is writing its reply.
+ * - `error`: the latest request failed, or the agent couldn't answer it. `retry()` tries again.
+ */
+export type AIConversationStatus = 'ready' | 'submitted' | 'streaming' | 'error';
+
+/** Whether the agent is answering: the request is submitted, or its reply streaming. */
+export const isAIConversationAnswering = (status: AIConversationStatus) =>
+  status === 'submitted' || status === 'streaming';
+
+/**
+ * What the person asks for:
+ * - `message`: a new message from the person.
+ * - `regenerate`: a new reply in place of the request's `message`, which is a reply, and of those
+ *   after it. Without `message`, a reply to the latest message, which has none, such as after the
+ *   agent couldn't answer it.
+ * - `edit`: the person changed the request's `message`, one of theirs, to say its `text`: it is
+ *   answered again, in place of the replies after it.
+ *
+ * An open set: a kind of your own is on its way like a message.
+ */
+export type AIConversationRequestKind = 'message' | 'regenerate' | 'edit' | (string & {});
+
+/** What the person asks the agent, as an `AIConversationTransport` sends it. */
+export type AIConversationRequest<Message extends AIMessage = AIMessage> = {
+  /** What the person asks for. */
+  kind: AIConversationRequestKind;
+  /**
+   * An id for the person's message. A transport that creates the message with it lets the
+   * conversation find its copy by it. A retry of the request keeps it.
+   */
+  messageId: string;
+  /** What the person wrote. When a reply is written again, the message it answers says it. */
+  text: string;
+  /** The files the person picked, on this device, to upload with their message. */
+  attachments: MediaAsset[];
+  /** The option the person picked in the composer, such as thinking harder. */
+  chatOption?: AIChatOption;
+  /** What the composer held besides, as `ComposerState.custom`. */
+  custom?: Record<string, unknown>;
+  /** The message it is about: the reply to write again, or the person's message they edited. */
+  message?: Message;
+};
+
+/** The ids of the states Stream Chat's AI indicator reports. */
+export const AIAgentActivityStates = {
+  checkingExternalSources: 'AI_STATE_EXTERNAL_SOURCES',
+  error: 'AI_STATE_ERROR',
+  generating: 'AI_STATE_GENERATING',
+  thinking: 'AI_STATE_THINKING',
+} as const;
+
+/**
+ * What the agent is doing. An open set: compare against the states you know. Those of
+ * `AIAgentActivityStates` are Stream Chat's AI indicator's.
+ */
+export type AIAgentActivityState =
+  | (typeof AIAgentActivityStates)[keyof typeof AIAgentActivityStates]
+  | (string & {});
+
+/** What the agent says it is doing besides what its reply shows, such as checking sources. */
+export type AIAgentActivity = {
+  state: AIAgentActivityState;
+  /** What it says about it, such as "Searching the web", or why it couldn't answer. */
+  text?: string;
+};
+
+/** What the conversation's views offer the person to do with its messages. All by default. */
+export type AIConversationActions = {
+  /** Editing the person's latest message, which is then answered again. */
+  edit?: boolean;
+  /** Rating replies. */
+  rate?: boolean;
+  /** Asking for a new reply in place of the latest. */
+  regenerate?: boolean;
+};
+
+/**
+ * Where an `AIConversationTransport` tells its `AIConversationController` what the conversation
+ * holds. Once the controller is disposed, its updates go nowhere.
+ */
+export type AIConversationFeed<Message extends AIMessage = AIMessage> = {
+  /** Whether the controller it updates is still there. Stop following what it holds once it isn't. */
+  readonly isConnected: boolean;
+  /** The conversation's messages, oldest first, each time they change. */
+  updateMessages: (messages: readonly Message[]) => void;
+  /** Whether there are messages before the first one, which `loadOlderMessages` loads. */
+  updateHasOlderMessages: (hasOlderMessages: boolean) => void;
+  /** What the agent says it is doing, or `undefined` once it stops saying. */
+  updateActivity: (activity: AIAgentActivity | undefined) => void;
+};
+
+/**
+ * How an `AIConversationController` reaches the agent and learns what it holds: it sends what the
+ * person asks, stops the agent, and tells the controller its messages as they change.
+ *
+ * With Stream Chat, the conversation is a channel: the transport follows its messages and AI
+ * indicator events, and sends each request through the channel or your agent's own API.
+ *
+ * ```ts
+ * const transport: AIConversationTransport = {
+ *   connect: (feed) => {
+ *     const update = () => feed.updateMessages(channel.state.messages.map(fromStreamMessage));
+ *     update();
+ *     return channel.on(update).unsubscribe;
+ *   },
+ *   send: (request) => agent.respond(request.text, request.attachments),
+ *   stop: () => agent.interrupt(),
+ * };
+ * ```
+ */
+export type AIConversationTransport<Message extends AIMessage = AIMessage> = {
+  /**
+   * Starts telling `feed` what the conversation holds: its messages each time they change,
+   * whether there are older ones to load, and what the agent says it is doing. The controller
+   * calls it once, as it is made, and calls what it returns once it is disposed.
+   */
+  connect: (feed: AIConversationFeed<Message>) => void | (() => void);
+  /**
+   * Sends what the person asks. Resolve once the agent has the request: its reply arrives
+   * through the feed. A rejection shows as the conversation's error, and the person can retry,
+   * which sends the same request again with the same `messageId`: if the first attempt reached
+   * your backend, or you keep a copy of the failed message, use the id so the message isn't added
+   * twice. A rejection with an `AbortError` ends the request without an error.
+   *
+   * The controller leaves out the messages a `regenerate` or an `edit` replaces only until the
+   * new reply starts. From then on it shows the messages as the feed has them, so update the
+   * conversation before the new reply arrives:
+   * - For a regenerate, remove the request's `message` and the messages after it, or write the
+   *   new reply in place of `message`, under its id.
+   * - For an edit, change the person's `message` to say the request's `text`, under its id, and
+   *   remove the messages after it.
+   */
+  send: (request: AIConversationRequest<Message>) => Promise<void>;
+  /** Stops the reply the agent is writing. What it wrote so far stays. */
+  stop: () => Promise<void>;
+  /** Loads the messages before the first one, which arrive through the feed. */
+  loadOlderMessages?: () => Promise<void>;
+  /**
+   * Tells your backend how the person rated a reply, or that they took their rating back with
+   * `null`. Without it, the controller keeps the ratings on this device. Ratings your backend has
+   * show through each message's `rating`.
+   */
+  rate?: (reply: Message, rating: AIMessageRating | null) => Promise<void>;
+};

package/src/ai-components/conversation/controller/useAIConversationState.ts

@@ -0,0 +1,21 @@
+import { useStateStore } from '@stream-io/state-store/react-bindings';
+
+import type {
+  AIConversationController,
+  AIConversationControllerState,
+} from './AIConversationController';
+
+import type { AIMessage } from '../types';
+
+/**
+ * Follows what `selector` picks of a conversation's state, such as its `status` or `error`: the
+ * component renders again when it changes. Keep `selector` outside the component, so it stays the
+ * same between renders.
+ */
+export const useAIConversationState = <
+  Message extends AIMessage,
+  Selected extends Readonly<Record<string, unknown>>,
+>(
+  conversation: AIConversationController<Message>,
+  selector: (state: AIConversationControllerState<Message>) => Selected,
+) => useStateStore(conversation.state, selector);

package/src/ai-components/conversation/entries.ts

@@ -0,0 +1,177 @@
+import type { AIMessage, AIPendingMessage } from './types';
+
+import type { AIUIDocument } from '../generative-ui/AIUIDocument';
+import type { AIMessageAttachmentData } from '../message/AIMessageAttachment';
+import { isToolCallFinished } from '../message-parts/parseMessageParts';
+
+/** A row of the conversation: a message, or a message the person sent that is on its way. */
+export type AIConversationEntry = {
+  /** The message's id, or, for the copy of a message that was on its way, that message's. */
+  id: string;
+  isFromUser: boolean;
+  /** Whether it is a reply that ends the conversation. */
+  isLatestReply: boolean;
+  /** The message, or `undefined` for one on its way. */
+  message?: AIMessage;
+  /** The message on its way, until its copy arrives. */
+  pending?: AIPendingMessage;
+  /** What the person sent with a message on its way, which its copy shows rather than load it again. */
+  sentAttachments: AIMessageAttachmentData[];
+};
+
+/** The person's message and the replies to it. */
+export type AIConversationTurn = { entries: AIConversationEntry[]; id: string };
+
+/** Whether a reply's generated UI shows, such as `AIUIHost.canShow`. */
+export type AIConversationCanShowUI = (document: AIUIDocument) => boolean;
+
+const showsNoUI: AIConversationCanShowUI = () => false;
+
+// A reply the agent has started but that has nothing to show yet: no text, steps or attachments,
+// and no UI that `canShowUI` says shows.
+const showsNothing = (message: AIMessage, canShowUI: AIConversationCanShowUI) =>
+  message.role !== 'user' &&
+  message.text === '' &&
+  !message.parts?.length &&
+  !message.attachments?.length &&
+  !(message.uiDocument && canShowUI(message.uiDocument));
+
+// Whether a step is over: a round of reasoning that stopped streaming, or a call that finished.
+// A step of a kind this SDK doesn't know counts as over, since it can't say otherwise.
+const isStepOver = ({ reasoning, toolCall }: NonNullable<AIMessage['parts']>[number]) =>
+  reasoning
+    ? reasoning.status !== 'streaming'
+    : toolCall
+      ? isToolCallFinished(toolCall.status)
+      : true;
+
+/**
+ * Whether the reply is being written, took steps that are all over, and shows no UI: once its
+ * answer stops growing, the agent is thinking again, between its steps. An agent's backend can
+ * write a round of reasoning as a step only once it is done, so nothing would show meanwhile. A
+ * step still going, such as a call waiting for the person, shows itself instead.
+ */
+export const hasFinishedSteps = (
+  message: AIMessage | undefined,
+  canShowUI: AIConversationCanShowUI = showsNoUI,
+): message is AIMessage =>
+  !!message &&
+  message.role !== 'user' &&
+  !!message.isGenerating &&
+  !!message.parts?.length &&
+  message.parts.every(isStepOver) &&
+  !(message.uiDocument && canShowUI(message.uiDocument));
+
+/** Groups the rows into turns, each starting with one of the person's messages. */
+export const turnsOf = (entries: AIConversationEntry[]) =>
+  entries.reduce<AIConversationTurn[]>((turns, entry) => {
+    const last = turns[turns.length - 1];
+    if (!last || entry.isFromUser) turns.push({ entries: [entry], id: entry.id });
+    else last.entries.push(entry);
+    return turns;
+  }, []);
+
+/**
+ * Follows a message the person sent until its copy arrives in the messages, so the copy takes
+ * over its row (and its key) without a flicker, and tells whether the agent is surely about to
+ * answer.
+ */
+export class AIPendingMessageTracker {
+  // The person's messages each pending message's copy cannot be: those there were when it was
+  // first seen, and those that arrived since without being its copy, such as older ones.
+  private seen = new Map<string, Set<string>>();
+  // The pending message each copy took over, by the copy's id.
+  private copies = new Map<string, AIPendingMessage>();
+  // The pending message of the last update, whose copy can arrive in the update that stops
+  // passing it.
+  private lastPending?: AIPendingMessage;
+
+  // The rows of a conversation: its messages, apart from replies with nothing to show yet, and
+  // a message on its way until its copy arrives. A reply's UI shows when `canShowUI` says.
+  entries(
+    messages: AIMessage[],
+    pending?: AIPendingMessage | null,
+    canShowUI: AIConversationCanShowUI = showsNoUI,
+  ): AIConversationEntry[] {
+    let showsPending = !!pending;
+    // A copy that arrives in the update that stops passing its pending message still takes over
+    // its row. Only then: a message sent later is not the copy of one that failed.
+    const awaited = pending ?? this.lastPending;
+    if (awaited) {
+      const sent = messages.filter((message) => message.role === 'user');
+      const ids = new Set(sent.map((message) => message.id));
+      const known = this.seen.get(awaited.id) ?? ids;
+      const matched = [...this.copies].find(
+        ([copyId, original]) => original.id === awaited.id && ids.has(copyId),
+      )?.[0];
+      const copy = matched ?? this.copyOf(awaited, sent, known);
+      if (copy !== undefined) {
+        if (!this.copies.has(copy)) this.copies.set(copy, awaited);
+        showsPending = false;
+      } else {
+        this.seen.set(awaited.id, new Set([...known, ...ids]));
+      }
+    }
+    this.lastPending = pending ?? undefined;
+
+    const entries: AIConversationEntry[] = messages
+      .filter((message) => !showsNothing(message, canShowUI))
+      .map((message) => {
+        const taken = this.copies.get(message.id);
+        return {
+          id: taken?.id ?? message.id,
+          isFromUser: message.role === 'user',
+          isLatestReply: false,
+          message,
+          sentAttachments: taken?.attachments ?? [],
+        };
+      });
+    if (showsPending && pending) {
+      entries.push({
+        id: pending.id,
+        isFromUser: true,
+        isLatestReply: false,
+        pending,
+        sentAttachments: [],
+      });
+    }
+    const last = entries[entries.length - 1];
+    if (last && !last.isFromUser) last.isLatestReply = true;
+    return entries;
+  }
+
+  // The copy of a message that was on its way: the person's message with its id, when the app
+  // knew it. Otherwise their first after those known, which older messages loading above cannot
+  // be. With none of theirs known, it is their latest, when that is the only new one or says the
+  // same.
+  private copyOf(pending: AIPendingMessage, sent: AIMessage[], known: Set<string>) {
+    const ids = sent.map((message) => message.id);
+    if (ids.includes(pending.id)) return pending.id;
+    let lastKnown = -1;
+    ids.forEach((id, index) => {
+      if (known.has(id)) lastKnown = index;
+    });
+    if (lastKnown >= 0) return ids[lastKnown + 1];
+    const fresh = sent.filter((message) => !known.has(message.id));
+    const latest = fresh[fresh.length - 1];
+    if (!latest || (fresh.length !== 1 && latest.text !== pending.text)) return undefined;
+    return latest.id;
+  }
+
+  // Whether the latest message is surely waiting for a reply that shows nothing yet: it is on its
+  // way, it is the copy of the one on its way, or its reply is being written but shows nothing.
+  // Call it after `entries`, which matches the copies.
+  isAwaitingReply(
+    messages: AIMessage[],
+    pending?: AIPendingMessage | null,
+    canShowUI: AIConversationCanShowUI = showsNoUI,
+  ) {
+    const last = messages[messages.length - 1];
+    if (last && last.role !== 'user' && last.isGenerating && showsNothing(last, canShowUI))
+      return true;
+    if (!pending) return false;
+    const copy = [...this.copies].find(([, original]) => original.id === pending.id)?.[0];
+    if (copy === undefined) return true;
+    return last?.id === copy;
+  }
+}

package/src/ai-components/conversation/fromStreamMessage.ts

@@ -0,0 +1,87 @@
+import type { Attachment, LocalMessage, MessageResponse } from 'stream-chat';
+
+import type { AIMessage } from './types';
+
+import { AI_UI_CUSTOM_DATA_KEY, parseAIUIDocument } from '../generative-ui/AIUIDocument';
+import type { AIMessageAttachmentData } from '../message/AIMessageAttachment';
+import { parseMessageParts } from '../message-parts/parseMessageParts';
+
+/** A Stream message, as the channel's state or an event has it. */
+export type AIStreamMessage = Pick<LocalMessage | MessageResponse, 'attachments' | 'id' | 'text'> &
+  Record<string, unknown>;
+
+export type FromStreamMessageOptions = {
+  /** Whether the agent wrote it. Defaults to the message's `ai_generated` field. */
+  isAssistant?: (message: AIStreamMessage) => boolean;
+  /** The whole of a reasoning step's thinking, when the app has it, such as from live updates. */
+  reasoningText?: (messageId: string, stepId: string) => string | undefined;
+};
+
+// Images and files only: the steps (`ai_*`) are read as parts, and other kinds are the app's.
+const attachmentOf = (attachment: Attachment): AIMessageAttachmentData | undefined => {
+  const name = attachment.title ?? attachment.fallback ?? undefined;
+  if (attachment.type === 'image') {
+    const url = attachment.image_url ?? attachment.asset_url ?? attachment.thumb_url;
+    return url ? { kind: 'image', mimeType: attachment.mime_type, name, url } : undefined;
+  }
+  if (attachment.type === 'file') {
+    const size = Number(attachment.file_size);
+    return attachment.asset_url
+      ? {
+          kind: 'file',
+          mimeType: attachment.mime_type,
+          name,
+          size: Number.isFinite(size) && size > 0 ? size : undefined,
+          url: attachment.asset_url,
+        }
+      : undefined;
+  }
+  return undefined;
+};
+
+/**
+ * Adapts a Stream message for `AIConversation`: a reply is one with `ai_generated: true`, it is
+ * being written while `generating: true`, its steps are its `ai_reasoning` and `ai_tool_call`
+ * attachments, its images and files are its other attachments, and the UI the agent wrote for
+ * it is its `ai_ui` field. A person's message has no UI, whatever its fields say.
+ */
+export const fromStreamMessage = (
+  message: AIStreamMessage,
+  { isAssistant, reasoningText }: FromStreamMessageOptions = {},
+): AIMessage => {
+  const attachments = message.attachments ?? [];
+  const assistant = isAssistant ? isAssistant(message) : message.ai_generated === true;
+  const uiDocument = assistant ? parseAIUIDocument(message[AI_UI_CUSTOM_DATA_KEY]) : undefined;
+  return {
+    attachments: attachments
+      .map(attachmentOf)
+      .filter((attachment): attachment is AIMessageAttachmentData => !!attachment),
+    id: message.id,
+    isGenerating: message.generating === true,
+    parts: parseMessageParts(attachments),
+    reasoningText: reasoningText
+      ? (stepId: string) => reasoningText(message.id, stepId)
+      : undefined,
+    role: assistant ? 'assistant' : 'user',
+    text: message.text ?? '',
+    ...(uiDocument ? { uiDocument } : {}),
+  };
+};
+
+/**
+ * A `fromStreamMessage` that gives back the same `AIMessage` for the same Stream message object.
+ * The channel's state replaces only the messages that change, so mapping its messages through it
+ * on every update leaves the others as they were, and `AIConversation` renders only the changed
+ * ones again. Make one per conversation, such as with `useState(() => createFromStreamMessage())`.
+ */
+export const createFromStreamMessage = (options?: FromStreamMessageOptions) => {
+  const cache = new WeakMap<AIStreamMessage, AIMessage>();
+  return (message: AIStreamMessage) => {
+    let adapted = cache.get(message);
+    if (!adapted) {
+      adapted = fromStreamMessage(message, options);
+      cache.set(message, adapted);
+    }
+    return adapted;
+  };
+};

package/src/ai-components/conversation/index.ts

@@ -0,0 +1,5 @@
+export * from './AIConversation';
+export * from './controller';
+export * from './fromStreamMessage';
+export * from './types';
+export type { AIConversationCanShowUI, AIConversationEntry, AIConversationTurn } from './entries';