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

package/src/ai-components/conversation-state/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-state/controller/index.ts

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

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

@@ -0,0 +1,53 @@
+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,
+});
+
+/** The id of the person's latest message, the one they can edit. */
+export const latestUserMessageIdOf = (messages: readonly AIMessage[]) => {
+  for (let index = messages.length - 1; index >= 0; index--) {
+    if (messages[index].role === 'user') return messages[index].id;
+  }
+  return undefined;
+};
+
+// 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>,
+  {
+    latestUserMessageId,
+    status,
+  }: { latestUserMessageId: string | undefined; status: AIConversationStatus },
+  message: Message,
+): (() => void) | undefined => {
+  if (!offerer.actions.edit || message.role !== 'user' || isAIConversationAnswering(status)) {
+    return undefined;
+  }
+  return latestUserMessageId === message.id ? () => offerer.edit(message) : undefined;
+};

package/src/ai-components/conversation-state/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-state/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-state/fromStreamMessage.ts

@@ -0,0 +1,89 @@
+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, link previews Stream made from
+// the text are left out, and other kinds are the app's.
+const attachmentOf = (attachment: Attachment): AIMessageAttachmentData | undefined => {
+  if (attachment.og_scrape_url) return 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-state/index.ts

@@ -0,0 +1,3 @@
+export * from './controller';
+export * from './fromStreamMessage';
+export * from './types';

package/src/ai-components/conversation-state/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/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;
+};