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

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

@@ -0,0 +1,57 @@
+import type { AIUIDocument } from '../generative-ui/AIUIDocument';
+import type { AIMessageAttachmentData } from '../message/AIMessageAttachment';
+import type { AIMessageRating } from '../message/AIReplyActions';
+import type { AIMessagePartData } from '../message-parts/types';
+
+/** Who wrote a message: the person using the app (`user`) or the agent (`assistant`). */
+export type AIMessageRole = 'user' | 'assistant' | (string & {});
+
+/**
+ * A message of the conversation as the AI components show it. `fromStreamMessage` makes one
+ * from a Stream message.
+ */
+export type AIMessage = {
+  id: string;
+  /** Who wrote it. Each of the person's messages starts a turn. */
+  role: AIMessageRole;
+  /** What it says. A reply's text is Markdown. */
+  text: string;
+  /** What it carries besides its text, such as images and files. */
+  attachments?: AIMessageAttachmentData[];
+  /** Whether the agent is still writing it. */
+  isGenerating?: boolean;
+  /**
+   * How the person rated a reply, as your backend has it. An `AIConversationController` shows it
+   * until the person rates the reply on this device.
+   */
+  rating?: AIMessageRating | null;
+  /** The steps the agent took for it, in order: reasoning, tool calls and kinds of its own. */
+  parts?: AIMessagePartData[];
+  /**
+   * The whole of a reasoning step's thinking when the app has it, such as from live updates.
+   * Without it, the step shows its own excerpt. It is read on every render, so look it up
+   * rather than work it out.
+   */
+  reasoningText?: (stepId: string) => string | undefined;
+  /**
+   * The UI the agent wrote for a reply, which shows in place of its text when the
+   * conversation's `ui` host has a renderer for it. A person's message has none.
+   */
+  uiDocument?: AIUIDocument;
+};
+
+/**
+ * A message the person sent that is not in the conversation's messages yet. The conversation
+ * shows it until its copy arrives, and shows the agent thinking meanwhile.
+ */
+export type AIPendingMessage = {
+  /**
+   * The message's id once it arrives, when you know it (such as the id you send it with). Its
+   * copy is then found by it rather than by where it lands. Keep it the same while it waits.
+   */
+  id: string;
+  /** What the person wrote. */
+  text: string;
+  /** What they sent with it, such as the photos and files they picked. Its copy shows these too. */
+  attachments?: AIMessageAttachmentData[];
+};

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

@@ -0,0 +1,230 @@
+import { type ReactNode, useLayoutEffect, useMemo, useRef, useState } from 'react';
+
+import {
+  type AIConversationCanShowUI,
+  type AIConversationEntry,
+  type AIConversationTurn,
+  AIPendingMessageTracker,
+  hasFinishedSteps,
+  turnsOf,
+} from './entries';
+import type { AIMessage, AIPendingMessage } from './types';
+
+import type { AIMessageAttachmentData } from '../message/AIMessageAttachment';
+import { AIThinkingClock } from '../reasoning/thinkingClock';
+
+/**
+ * Where a row is: the first of a turn, or within one. The first turn has the same room above it as
+ * the others, so older messages arriving above it leave it where it is.
+ */
+export type RowPosition = 'turn' | 'message';
+
+/** A row of the list: one message, with the turn it belongs to. */
+export type EntryRow = {
+  entry: AIConversationEntry;
+  key: string;
+  kind: 'entry';
+  position: RowPosition;
+  turnKey: string;
+  /** The turn's first reasoning step, which takes over the seconds the turn was seen thinking. */
+  firstStepId?: string;
+  /**
+   * When the agent started thinking again between the steps of this reply, which is being
+   * written, and which its seconds count from. It thinks under the reply, in the reply's row, so
+   * it moves with the reply's steps as they fold.
+   */
+  thinkingSince?: number;
+};
+
+/**
+ * What ends the latest turn: the agent thinking, and the app's footer. A row of its own rather than
+ * the list's footer: the list lays its rows out itself, together with the room it leaves under the
+ * latest turn, while a footer that goes away shrinks the content at once, which moves the view.
+ */
+export type TailRow = {
+  isThinking: boolean;
+  key: string;
+  kind: 'tail';
+  turnKey: string;
+  firstStepId?: string;
+  footer?: ReactNode;
+};
+
+export type ConversationRow = EntryRow | TailRow;
+
+const TAIL_KEY = 'ai-conversation-tail';
+
+// What the latest message was at the last render, to tell whether its answer grew since, and when
+// the agent started thinking between its steps, if it is.
+type BetweenSteps = {
+  messageId: string | undefined;
+  textLength: number;
+  since?: number;
+  stepsKey?: string;
+};
+
+const sameAttachments = (a: AIMessageAttachmentData[], b: AIMessageAttachmentData[]) =>
+  a === b || (a.length === 0 && b.length === 0);
+
+// Whether a row can be kept as it was: the list renders a row again only for a new item.
+const isSameRow = (row: EntryRow, next: Omit<EntryRow, 'key'>) =>
+  row.entry.message === next.entry.message &&
+  row.entry.pending === next.entry.pending &&
+  row.entry.isLatestReply === next.entry.isLatestReply &&
+  sameAttachments(row.entry.sentAttachments, next.entry.sentAttachments) &&
+  row.firstStepId === next.firstStepId &&
+  row.thinkingSince === next.thinkingSince &&
+  row.position === next.position &&
+  row.turnKey === next.turnKey;
+
+// The turn's first reasoning step, which takes over the seconds the turn was seen thinking.
+const firstStepOf = (turn: AIConversationTurn | undefined) => {
+  for (const { message } of turn?.entries ?? []) {
+    if (!message || message.role === 'user') continue;
+    const step = message.parts?.find((part) => part.reasoning);
+    if (step) return step.id;
+  }
+  return undefined;
+};
+
+export type UseConversationRowsOptions = {
+  messages: AIMessage[];
+  /** Whether a reply's generated UI shows, so a reply that shows only UI has a row. */
+  canShowUI?: AIConversationCanShowUI;
+  footer?: ReactNode;
+  isThinking?: boolean;
+  /** Whether `isThinking` alone says whether the agent is thinking, rather than the rows too. */
+  isThinkingKnown?: boolean;
+  pendingMessage?: AIPendingMessage | null;
+};
+
+export type ConversationRows = {
+  /** The key of the latest turn's first row, which pins to the top: `undefined` with no turns. */
+  anchorKey: string | undefined;
+  /** The turns' thinking clock, for `AIThinkingTurnContext`. */
+  clock: AIThinkingClock;
+  /** The rows to list: each message, then what ends the latest turn while there is any. */
+  rows: ConversationRow[];
+  /** Whether there are no messages to show yet, not even one on its way. */
+  isEmpty: boolean;
+};
+
+/**
+ * The conversation's data, as rows for a list: its messages grouped into turns, a message on its
+ * way until its copy arrives, and what ends the latest turn. Each unchanged row keeps its object,
+ * so the list renders only the rows that changed. Knows nothing about the list itself.
+ */
+export const useConversationRows = ({
+  canShowUI,
+  footer,
+  isThinking = false,
+  isThinkingKnown = false,
+  messages,
+  pendingMessage,
+}: UseConversationRowsOptions): ConversationRows => {
+  const [tracker] = useState(() => new AIPendingMessageTracker());
+  const [clock] = useState(() => new AIThinkingClock());
+
+  const entries = useMemo(
+    () => tracker.entries(messages, pendingMessage, canShowUI),
+    [canShowUI, messages, pendingMessage, tracker],
+  );
+  // after `entries`, which matched the copies
+  const thinking =
+    isThinking ||
+    (!isThinkingKnown && tracker.isAwaitingReply(messages, pendingMessage, canShowUI));
+
+  // The agent thinking again between the latest reply's steps: from the update in which a step
+  // ended without the answer growing, until the answer grows. A step that ends together with more
+  // of the answer means the answer is under way.
+  const lastMessage = messages[messages.length - 1];
+  const stepsKey = hasFinishedSteps(lastMessage, canShowUI)
+    ? `${lastMessage.id}:${lastMessage.parts?.length}`
+    : undefined;
+  // A break the agent's backend adds after what came before a step isn't more of the answer.
+  const textLength = lastMessage?.text.trimEnd().length ?? 0;
+  const [gap, setGap] = useState<BetweenSteps>();
+  if (
+    gap?.messageId !== lastMessage?.id ||
+    gap?.stepsKey !== stepsKey ||
+    gap?.textLength !== textLength
+  ) {
+    const grew = gap?.messageId === lastMessage?.id && textLength > (gap?.textLength ?? 0);
+    setGap({
+      messageId: lastMessage?.id,
+      since:
+        grew || stepsKey === undefined
+          ? undefined
+          : stepsKey === gap?.stepsKey
+            ? gap.since
+            : Date.now(),
+      stepsKey,
+      textLength,
+    });
+  }
+  const thinkingSince = !thinking && stepsKey !== undefined ? gap?.since : undefined;
+  const thinkingReplyId = thinkingSince !== undefined ? lastMessage?.id : undefined;
+  const turns = useMemo(() => turnsOf(entries), [entries]);
+  const latest = turns[turns.length - 1];
+  const latestHasReplies = (latest?.entries.length ?? 0) > 1;
+  const latestFirstStepId = firstStepOf(latest);
+  const latestHasFirstStep = latestFirstStepId !== undefined;
+  // Before the views below read it in their effects and next renders: a turn's thinking starts
+  // and ends once.
+  useLayoutEffect(() => {
+    clock.update(latest?.id, thinking, latestHasReplies, latestHasFirstStep);
+  }, [clock, latest?.id, latestHasFirstStep, latestHasReplies, thinking]);
+
+  // The rows, keeping each unchanged one's object, so the list renders only the rows that changed.
+  const rowCache = useRef(new Map<string, EntryRow>());
+  const entryRows = useMemo(() => {
+    const cache = new Map<string, EntryRow>();
+    const next: EntryRow[] = [];
+    turns.forEach((turn) => {
+      const firstStepId = firstStepOf(turn);
+      turn.entries.forEach((entry, index) => {
+        const fields = {
+          entry,
+          firstStepId,
+          kind: 'entry' as const,
+          position: (index > 0 ? 'message' : 'turn') as RowPosition,
+          thinkingSince:
+            thinkingReplyId !== undefined && entry.message?.id === thinkingReplyId
+              ? thinkingSince
+              : undefined,
+          turnKey: turn.id,
+        };
+        const previous = rowCache.current.get(entry.id);
+        const row =
+          previous && isSameRow(previous, fields) ? previous : { ...fields, key: entry.id };
+        cache.set(entry.id, row);
+        next.push(row);
+      });
+    });
+    rowCache.current = cache;
+    return next;
+  }, [thinkingReplyId, thinkingSince, turns]);
+
+  // A turn's id is its first entry's, so the latest turn's first row has its key.
+  const lastTurnKey = latest?.id;
+  const tailRow = useMemo<TailRow | undefined>(
+    () =>
+      lastTurnKey !== undefined && (thinking || footer)
+        ? {
+            firstStepId: latestFirstStepId,
+            footer,
+            isThinking: thinking,
+            key: TAIL_KEY,
+            kind: 'tail',
+            turnKey: lastTurnKey,
+          }
+        : undefined,
+    [footer, lastTurnKey, latestFirstStepId, thinking],
+  );
+  const rows = useMemo<ConversationRow[]>(
+    () => (tailRow ? [...entryRows, tailRow] : entryRows),
+    [entryRows, tailRow],
+  );
+
+  return { anchorKey: lastTurnKey, clock, isEmpty: entryRows.length === 0, rows };
+};

package/src/ai-components/generative-ui/AIUIAction.ts

@@ -0,0 +1,73 @@
+import type { AIUIFormat } from './AIUIDocument';
+import { utf8ByteLength } from './AIUIHelpers';
+
+/**
+ * What the person did in a reply's UI, such as tapping a place or submitting a form. It goes to
+ * the agent as their next message: `label` is its text and `aiUIActionJSON(action)` what it
+ * carries.
+ */
+export type AIUIAction = {
+  /** The format of the UI it came from. */
+  format: AIUIFormat;
+  /** What the person did, in their words, such as "Tell me more about St. Naum". */
+  label: string;
+  /** The reply whose UI it came from. */
+  messageId: string;
+  /**
+   * What happened, such as an event of an app's component (`ask_about`) or OpenUI's
+   * `continue_conversation`.
+   */
+  name: string;
+  /** The details in the format's own shape, such as what was chosen and a form's values. */
+  payload: Record<string, unknown>;
+};
+
+/** The action as the JSON object an agent's backend reads. */
+export type AIUIActionJSON = {
+  format: AIUIFormat;
+  message_id: string;
+  name: string;
+  payload: Record<string, unknown>;
+  v: 1;
+};
+
+/** The custom field of the person's message that holds the action. */
+export const AI_UI_ACTION_CUSTOM_DATA_KEY = 'ai_ui_action';
+/**
+ * The most an action may take as JSON. The agents router refuses a larger one, and its
+ * refusal would lose the person's message with it.
+ */
+export const AI_UI_ACTION_MAX_BYTES = 8 * 1024;
+
+/**
+ * The action as the JSON object an agent's backend reads, such as the `uiAction` of
+ * `session.responses.create(action.label, { uiAction })`. The label is not in it: it is the
+ * text of the person's message.
+ */
+export const aiUIActionJSON = (action: AIUIAction): AIUIActionJSON => ({
+  format: action.format,
+  message_id: action.messageId,
+  name: action.name,
+  payload: action.payload,
+  v: 1,
+});
+
+/**
+ * Why the agent's backend would refuse the action, or `undefined` when it would take it: it
+ * names its reply, its format and what happened, in at most `AI_UI_ACTION_MAX_BYTES` of JSON.
+ */
+export const aiUIActionProblem = (action: AIUIAction): string | undefined => {
+  if (!action.messageId) return 'an action names the reply it came from';
+  if (!action.format) return 'an action names the format of its UI';
+  if (!action.name) return 'an action names what happened';
+  let json: string;
+  try {
+    json = JSON.stringify(aiUIActionJSON(action));
+  } catch {
+    return 'an action carries only JSON';
+  }
+  const bytes = utf8ByteLength(json);
+  return bytes > AI_UI_ACTION_MAX_BYTES
+    ? `an action takes at most ${AI_UI_ACTION_MAX_BYTES} bytes as JSON, and this one takes ${bytes}`
+    : undefined;
+};

package/src/ai-components/generative-ui/AIUIArguments.ts

@@ -0,0 +1,117 @@
+import type { AIUIJSONSchema, AIUIParameter } from './AIUIComponentDefinition';
+import { aiUIParametersOf } from './AIUIComponentDefinition';
+import { isRecord } from './AIUIHelpers';
+
+// Thrown inside decoding only, so a value that does not fit stops it at once.
+class DoesNotFit extends Error {}
+
+const RFC_3339 = /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+const DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+/**
+ * A date the agent wrote: an RFC 3339 moment, or a whole day as `yyyy-MM-dd` that the calendar
+ * has, which is that day's start where the person is. Anything else is not a date.
+ */
+export const aiUIDate = (text: string): Date | undefined => {
+  if (RFC_3339.test(text)) {
+    const moment = new Date(text);
+    return Number.isNaN(moment.getTime()) ? undefined : moment;
+  }
+  const day = DAY.exec(text);
+  if (!day) return undefined;
+  const [year, month, date] = [Number(day[1]), Number(day[2]), Number(day[3])];
+  const start = new Date(year, month - 1, date);
+  start.setFullYear(year);
+  return start.getFullYear() === year && start.getMonth() === month - 1 && start.getDate() === date
+    ? start
+    : undefined;
+};
+
+/** `place_name` as `placeName`, the way the agent's snake_case reads in JavaScript. */
+export const aiUICamelCase = (key: string) => {
+  const [, leading = '', middle = '', trailing = ''] = /^(_*)(.*?)(_*)$/.exec(key) ?? [];
+  if (!middle.includes('_')) return key;
+  const [first = '', ...rest] = middle.split('_').filter(Boolean);
+  return (
+    leading +
+    first +
+    rest.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join('') +
+    trailing
+  );
+};
+
+const camelCased = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(camelCased);
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [aiUICamelCase(key), camelCased(item)]),
+  );
+};
+
+const decodeObject = (value: unknown, parameters: AIUIParameter[]) => {
+  if (!isRecord(value)) throw new DoesNotFit();
+  const declared = new Set(parameters.map(({ name }) => name));
+  const decoded: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (!declared.has(key)) decoded[aiUICamelCase(key)] = camelCased(item);
+  }
+  for (const { isRequired, name, type } of parameters) {
+    const item = value[name];
+    if (item === undefined || item === null) {
+      if (isRequired) throw new DoesNotFit();
+      continue;
+    }
+    decoded[aiUICamelCase(name)] = decodeValue(item, type);
+  }
+  return decoded;
+};
+
+const decodeValue = (value: unknown, schema: AIUIJSONSchema): unknown => {
+  switch (schema.type) {
+    case 'string': {
+      if (typeof value !== 'string') throw new DoesNotFit();
+      if (Array.isArray(schema.enum) && !schema.enum.includes(value)) throw new DoesNotFit();
+      if (schema.format === 'date' || schema.format === 'date-time') {
+        const date = aiUIDate(value);
+        if (!date) throw new DoesNotFit();
+        return date;
+      }
+      return value;
+    }
+    case 'number':
+      if (typeof value !== 'number' || !Number.isFinite(value)) throw new DoesNotFit();
+      return value;
+    case 'integer':
+      if (!Number.isInteger(value)) throw new DoesNotFit();
+      return value;
+    case 'boolean':
+      if (typeof value !== 'boolean') throw new DoesNotFit();
+      return value;
+    case 'array': {
+      if (!Array.isArray(value)) throw new DoesNotFit();
+      const items = isRecord(schema.items) ? schema.items : {};
+      return value.map((item) => decodeValue(item, items));
+    }
+    case 'object':
+      return decodeObject(value, aiUIParametersOf(schema));
+    default:
+      return camelCased(value);
+  }
+};
+
+/**
+ * The arguments the agent wrote for a component, as its view reads them: keys in camelCase,
+ * dates as `Date`s. `undefined` while they do not fit its parameters, such as while they are
+ * still streaming in: a required one is missing, or one is of the wrong type.
+ */
+export const decodeAIUIArguments = <Arguments = Record<string, unknown>>(
+  args: Record<string, unknown>,
+  parameters: AIUIParameter[],
+): Arguments | undefined => {
+  try {
+    return decodeObject(args, parameters) as Arguments;
+  } catch (error) {
+    if (error instanceof DoesNotFit) return undefined;
+    throw error;
+  }
+};

package/src/ai-components/generative-ui/AIUIComponent.tsx

@@ -0,0 +1,106 @@
+import React, { type ComponentType, useMemo } from 'react';
+
+import { decodeAIUIArguments } from './AIUIArguments';
+import type { AIUIComponentDefinition } from './AIUIComponentDefinition';
+import { AIUIEntrance } from './AIUIEntrance';
+import { AIUIErrorBoundary } from './AIUIErrorBoundary';
+import type { AIUIHost } from './AIUIHost';
+
+/** Where an app's component is shown, and how it tells the agent what the person did. */
+export type AIUIComponentContext = {
+  /**
+   * Tells the agent about one of the component's events, as the person's next message.
+   * `label` is what the person did, in their words, such as "Tell me more about St. Naum".
+   */
+  emit: (event: string, label: string, payload?: Record<string, unknown>) => void;
+  /** The conversation's host, for running the app's tools and opening links. */
+  host: AIUIHost;
+  /** Whether the agent is still writing the reply's UI, so the arguments may still change. */
+  isStreaming: boolean;
+  /** The reply the component is in. */
+  messageId: string;
+};
+
+export type AIUIComponentProps<Arguments> = {
+  /** What the agent filled in: keys in camelCase, dates as `Date`s. */
+  args: Arguments;
+  context: AIUIComponentContext;
+};
+
+/**
+ * One of the app's views that the agent can place in a reply's UI, in whichever format it
+ * writes, such as a map or a card over the app's own data.
+ */
+export type AIUIComponent = {
+  Component: ComponentType<AIUIComponentProps<never>>;
+  /** Its description, the same on every platform and for the agent. */
+  definition: AIUIComponentDefinition;
+};
+
+/**
+ * One of the app's components, with what its view reads from the agent's arguments. The view
+ * gets them only once they fit the definition's parameters, so it can rely on their types.
+ *
+ * A conversation reuses its views: one scrolled out of sight shows another reply's UI next, so
+ * state the view keeps of its own has to start afresh for a new `context.messageId`.
+ */
+export const defineAIUIComponent = <Arguments,>(
+  definition: AIUIComponentDefinition,
+  Component: ComponentType<AIUIComponentProps<Arguments>>,
+): AIUIComponent => ({
+  // The arguments are checked against `definition` before the view gets them.
+  Component: Component as unknown as ComponentType<AIUIComponentProps<never>>,
+  definition,
+});
+
+// What an app's component was given, to try it again once that changes or the reply is written.
+const attemptOf = (args: Record<string, unknown>, isStreaming: boolean) => {
+  try {
+    return `${isStreaming}\u0000${JSON.stringify(args)}`;
+  } catch {
+    return args;
+  }
+};
+
+/**
+ * An app's component for the arguments the agent wrote, coming in as it shows, or nothing
+ * while they don't fit its parameters, such as while they are still streaming in. Renderers
+ * place the app's components with it. One that throws leaves only itself out of the reply's
+ * UI, is tried again when its arguments change, and is reported once the reply is written.
+ */
+export const AIUIComponentView = ({
+  args,
+  component,
+  context,
+}: {
+  args: Record<string, unknown>;
+  component: AIUIComponent;
+  context: AIUIComponentContext;
+}) => {
+  const { host, isStreaming, messageId } = context;
+  // Worked out again only when the arguments change, for a renderer that keeps the same object
+  // while they don't, as the A2UI renderer does.
+  const decoded = useMemo(
+    () => decodeAIUIArguments(args, component.definition.parameters),
+    [args, component],
+  );
+  const resetKey = useMemo(
+    () => (decoded === undefined ? undefined : attemptOf(decoded, isStreaming)),
+    [decoded, isStreaming],
+  );
+  if (decoded === undefined) return null;
+  const { Component } = component;
+  return (
+    <AIUIErrorBoundary
+      onError={(error) => {
+        // While the reply streams, what the component was given may still be incomplete.
+        if (!isStreaming) host.reportRenderError(error, messageId);
+      }}
+      resetKey={resetKey}
+    >
+      <AIUIEntrance>
+        <Component args={decoded as never} context={context} />
+      </AIUIEntrance>
+    </AIUIErrorBoundary>
+  );
+};