@assistant-ui/core 0.2.4 → 0.2.6

package/src/react/runtimes/external-message-converter.ts

@@ -22,6 +22,22 @@ import type {
 } from "../../types/message";
 import type { MessageTiming } from "../../types/message";
 
+type ThreadMessageLikeContentItem = Exclude<
+  ThreadMessageLike["content"],
+  string
+>[number];
+
+const isPendingToolCall = (c: ThreadMessageLikeContentItem): boolean =>
+  c.type === "tool-call" && c.result === undefined;
+
+const isInterruptedToolCall = (c: ThreadMessageLikeContentItem): boolean => {
+  if (c.type !== "tool-call" || c.result !== undefined) return false;
+  return (
+    c.interrupt != null ||
+    (c.approval != null && c.approval.approved === undefined)
+  );
+};
+
 export namespace useExternalMessageConverter {
   export type Message =
     | (ThreadMessageLike & {
@@ -335,15 +351,16 @@ export const convertExternalMessages = <T extends WeakKey>(
   const result = chunks.map((message, idx) => {
     const isLast = idx === chunks.length - 1;
     const joined = joinExternalMessages(message.outputs);
+    const hasInterruptedToolCalls =
+      typeof joined.content === "object" &&
+      joined.content.some(isInterruptedToolCall);
     const hasPendingToolCalls =
       typeof joined.content === "object" &&
-      joined.content.some(
-        (c) => c.type === "tool-call" && c.result === undefined,
-      );
+      joined.content.some(isPendingToolCall);
     const autoStatus = getAutoStatus(
       isLast,
       isRunning,
-      hasPendingToolCalls,
+      hasInterruptedToolCalls,
       hasPendingToolCalls,
       isLast ? metadata.error : undefined,
     );
@@ -425,20 +442,16 @@ export const useExternalMessageConverter = <T extends WeakKey>({
         const isLast = idx === chunks.length - 1;
 
         const joined = joinExternalMessages(message.outputs);
-        const hasSuspendedToolCalls =
+        const hasInterruptedToolCalls =
           typeof joined.content === "object" &&
-          joined.content.some(
-            (c) => c.type === "tool-call" && c.result === undefined,
-          );
+          joined.content.some(isInterruptedToolCall);
         const hasPendingToolCalls =
           typeof joined.content === "object" &&
-          joined.content.some(
-            (c) => c.type === "tool-call" && c.result === undefined,
-          );
+          joined.content.some(isPendingToolCall);
         const autoStatus = getAutoStatus(
           isLast,
           isRunning,
-          hasSuspendedToolCalls,
+          hasInterruptedToolCalls,
           hasPendingToolCalls,
           isLast ? state.metadata.error : undefined,
         );

package/src/react/types/MessagePartComponentTypes.ts

@@ -3,6 +3,8 @@ import type {
   MessagePartStatus,
   DataMessagePart,
   FileMessagePart,
+  GenerativeUIMessagePart,
+  GenerativeUISpec,
   ImageMessagePart,
   ReasoningMessagePart,
   SourceMessagePart,
@@ -69,6 +71,14 @@ export type ToolCallMessagePartProps<
      * paused frontend tool execution.
      */
     resume: (payload: unknown) => void;
+    /**
+     * Responds to a server-side tool approval gate. Only valid while
+     * `approval` is set on the part and `approval.approved === undefined`.
+     */
+    respondToApproval: (response: {
+      approved: boolean;
+      reason?: string;
+    }) => void;
   };
 
 /** Component used to render a tool-call message part. */
@@ -79,3 +89,27 @@ export type ToolCallMessagePartComponent<
 
 export type QuoteMessagePartProps = QuoteInfo;
 export type QuoteMessagePartComponent = ComponentType<QuoteMessagePartProps>;
+
+/**
+ * The consumer-provided allowlist of components a generative-ui spec is
+ * permitted to render. Keys are the component names referenced in the spec
+ * (e.g. `"Card"`, `"Button"`); values are the React components.
+ *
+ * This registry is the security boundary in the same-realm rendering path —
+ * any name not present in the registry is rejected with a typed error.
+ */
+export type GenerativeUIComponentRegistry = Record<string, ComponentType<any>>;
+
+export type GenerativeUIMessagePartProps = MessagePartState &
+  GenerativeUIMessagePart;
+export type GenerativeUIMessagePartComponent =
+  ComponentType<GenerativeUIMessagePartProps>;
+
+export type GenerativeUIRenderProps = {
+  /** The JSON spec to render. */
+  spec: GenerativeUISpec;
+  /** The component allowlist. */
+  components: GenerativeUIComponentRegistry;
+  /** Optional fallback for unknown component names. */
+  Fallback?: ComponentType<{ component: string; props?: unknown }> | undefined;
+};

package/src/react/utils/groupParts.ts

@@ -1,3 +1,6 @@
+import { isMcpAppUri } from "../../types/message";
+import type { PartState } from "../../store/scopes/part";
+
 /**
  * Hierarchical adjacent-coalescing grouping for message parts.
  *
@@ -11,16 +14,71 @@
  */
 
 /**
- * Public group key type. Group keys must be prefixed with `group-` so
- * that a unified `switch (part.type)` in the renderer can distinguish
- * a group key (e.g. `"group-thought"`) from a real part type
- * (`"text"`, `"tool-call"`).
+ * Symbol attached to memoizable `groupBy` functions (e.g. those returned
+ * by {@link groupPartByType}). Carries a string fingerprint of the config
+ * so `MessagePrimitive.GroupedParts` can memo the tree on
+ * `[parts, memoKey]` across renders — even when the helper call site
+ * reconstructs the function each render.
+ */
+export const GROUPBY_MEMO_KEY: unique symbol = Symbol.for(
+  "@assistant-ui/groupBy.memoKey",
+);
+
+/**
+ * Synthetic part-type key recognized by {@link groupPartByType}: a
+ * tool-call whose `mcp.app.resourceUri` points at an assistant-ui MCP
+ * app. Map this key to control how MCP-app tool calls are grouped —
+ * separately from regular `"tool-call"` parts.
+ */
+type GroupPartType = PartState["type"] | "mcp-app";
+
+/**
+ * Build a `groupBy` from a `part.type → group-key path` lookup.
+ * Parts whose type isn't in the map are left ungrouped. The returned
+ * function carries a stable {@link GROUPBY_MEMO_KEY} fingerprint so
+ * `<MessagePrimitive.GroupedParts>` can memoize its tree across renders.
+ *
+ * Special key `"mcp-app"` matches tool-call parts that point at an
+ * assistant-ui MCP app resource (`ui://...`) and takes precedence over
+ * the `"tool-call"` entry for those parts.
+ *
+ * @example
+ * ```tsx
+ * <MessagePrimitive.GroupedParts
+ *   groupBy={groupPartByType({
+ *     reasoning: ["group-thought", "group-reasoning"],
+ *     "tool-call": ["group-thought", "group-tool"],
+ *     "mcp-app": [],
+ *   })}
+ * >
+ *   {({ part, children }) => { ... }}
+ * </MessagePrimitive.GroupedParts>
+ * ```
  */
-export type GroupKey<TKey extends `group-${string}` = `group-${string}`> =
-  | TKey
-  | readonly TKey[]
-  | null
-  | undefined;
+export const groupPartByType = <TKey extends `group-${string}`>(
+  map: Partial<Readonly<Record<GroupPartType, readonly TKey[]>>>,
+): ((part: PartState) => readonly TKey[]) => {
+  const lookup = map as Readonly<Record<string, readonly TKey[] | undefined>>;
+  const fn = ((part) => {
+    if (
+      part.type === "tool-call" &&
+      lookup["mcp-app"] !== undefined &&
+      isMcpAppUri(part.mcp?.app?.resourceUri)
+    ) {
+      return lookup["mcp-app"]!;
+    }
+    return lookup[part.type] ?? [];
+  }) as ((part: PartState) => readonly TKey[]) & {
+    [GROUPBY_MEMO_KEY]?: string;
+  };
+  // Sort keys so the fingerprint is insensitive to map insertion order —
+  // two maps with the same key/value pairs but different declaration order
+  // would otherwise hash differently and invalidate the memo unnecessarily.
+  const sortedKeys = Object.keys(map).sort();
+  const sortedEntries = sortedKeys.map((k) => [k, map[k as keyof typeof map]]);
+  fn[GROUPBY_MEMO_KEY] = `groupPartByType:${JSON.stringify(sortedEntries)}`;
+  return fn;
+};
 
 export type GroupNode = GroupNodeGroup | GroupNodePart;
 
@@ -43,19 +101,6 @@ export interface GroupNodePart {
   readonly nodeKey: string;
 }
 
-const EMPTY_PATH: readonly string[] = Object.freeze([]);
-
-/**
- * Normalize a `groupBy` return value to a path array.
- * `null`/`undefined`/`[]` → `[]` (ungrouped).
- * `"foo"` → `["foo"]`. Arrays pass through.
- */
-export const normalizeGroupKey = (key: GroupKey): readonly string[] => {
-  if (key == null) return EMPTY_PATH;
-  if (typeof key === "string") return [key];
-  return key;
-};
-
 interface BuildFrame {
   key: string;
   nodeKey: string;

package/src/runtime/api/message-part-runtime.ts

@@ -26,6 +26,7 @@ type MessagePartSnapshotBinding = SubscribableWithState<
 export type MessagePartRuntime = {
   addToolResult(result: any | ToolResponse<any>): void;
   resumeToolCall(payload: unknown): void;
+  respondToToolApproval(response: { approved: boolean; reason?: string }): void;
 
   readonly path: MessagePartRuntimePath;
   getState(): MessagePartState;
@@ -48,6 +49,7 @@ export class MessagePartRuntimeImpl implements MessagePartRuntime {
   protected __internal_bindMethods() {
     this.addToolResult = this.addToolResult.bind(this);
     this.resumeToolCall = this.resumeToolCall.bind(this);
+    this.respondToToolApproval = this.respondToToolApproval.bind(this);
     this.getState = this.getState.bind(this);
     this.subscribe = this.subscribe.bind(this);
   }
@@ -102,6 +104,30 @@ export class MessagePartRuntimeImpl implements MessagePartRuntime {
     });
   }
 
+  public respondToToolApproval(response: {
+    approved: boolean;
+    reason?: string;
+  }) {
+    const state = this.contentBinding.getState();
+    if (!state) throw new Error("Message part is not available");
+
+    if (state.type !== "tool-call")
+      throw new Error(
+        "Tried to respond to tool approval on non-tool message part",
+      );
+
+    if (!state.approval || state.approval.approved !== undefined)
+      throw new Error("Tool call has no pending approval");
+
+    if (!this.threadApi) throw new Error("Thread API is not available");
+
+    this.threadApi.getState().respondToToolApproval({
+      approvalId: state.approval.id,
+      approved: response.approved,
+      ...(response.reason != null && { reason: response.reason }),
+    });
+  }
+
   public subscribe(callback: () => void) {
     return this.contentBinding.subscribe(callback);
   }

package/src/runtime/api/thread-list-item-runtime.ts

@@ -36,7 +36,7 @@ export type ThreadListItemRuntime = {
   initialize(): Promise<{ remoteId: string; externalId: string | undefined }>;
   generateTitle(): Promise<void>;
 
-  switchTo(): Promise<void>;
+  switchTo(options?: { unarchive?: boolean }): Promise<void>;
   rename(newTitle: string): Promise<void>;
   archive(): Promise<void>;
   unarchive(): Promise<void>;
@@ -89,9 +89,9 @@ export class ThreadListItemRuntimeImpl implements ThreadListItemRuntime {
     return this._core.getState();
   }
 
-  public switchTo(): Promise<void> {
+  public switchTo(options?: { unarchive?: boolean }): Promise<void> {
     const state = this._core.getState();
-    return this._threadListBinding.switchToThread(state.id);
+    return this._threadListBinding.switchToThread(state.id, options);
   }
 
   public rename(newTitle: string): Promise<void> {

package/src/runtime/api/thread-list-runtime.ts

@@ -48,7 +48,10 @@ export type ThreadListRuntime = {
   getItemByIndex(idx: number): ThreadListItemRuntime;
   getArchivedItemByIndex(idx: number): ThreadListItemRuntime;
 
-  switchToThread(threadId: string): Promise<void>;
+  switchToThread(
+    threadId: string,
+    options?: { unarchive?: boolean },
+  ): Promise<void>;
   switchToNewThread(): Promise<void>;
 
   getLoadThreadsPromise(): Promise<void>;
@@ -152,8 +155,11 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
     this.getArchivedItemByIndex = this.getArchivedItemByIndex.bind(this);
   }
 
-  public switchToThread(threadId: string): Promise<void> {
-    return this._core.switchToThread(threadId);
+  public switchToThread(
+    threadId: string,
+    options?: { unarchive?: boolean },
+  ): Promise<void> {
+    return this._core.switchToThread(threadId, options);
   }
 
   public switchToNewThread(): Promise<void> {

package/src/runtime/base/base-thread-runtime-core.ts

@@ -15,6 +15,7 @@ import { DefaultThreadComposerRuntimeCore } from "./default-thread-composer-runt
 import type {
   AddToolResultOptions,
   ResumeToolCallOptions,
+  RespondToToolApprovalOptions,
   ThreadSuggestion,
   SubmitFeedbackOptions,
   ThreadRuntimeCore,
@@ -59,6 +60,9 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
   public abstract resumeRun(config: ResumeRunConfig): void;
   public abstract addToolResult(options: AddToolResultOptions): void;
   public abstract resumeToolCall(options: ResumeToolCallOptions): void;
+  public abstract respondToToolApproval(
+    options: RespondToToolApprovalOptions,
+  ): void;
   public abstract cancelRun(): void;
   public abstract exportExternalState(): any;
   public abstract importExternalState(state: any): void;
@@ -478,6 +482,14 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
     }
     subscribers.add(wrapped);
 
+    // `initialize` latches: replay it (deferred) to subscribers that attach
+    // after the thread already initialized, mirroring a BehaviorSubject.
+    if (event === "initialize" && this._isInitialized) {
+      queueMicrotask(() => {
+        if (subscribers.has(wrapped)) wrapped({});
+      });
+    }
+
     return () => {
       this._eventSubscribers.get(event)?.delete(wrapped);
     };

package/src/runtime/interfaces/thread-list-runtime-core.ts

@@ -32,7 +32,10 @@ export type ThreadListRuntimeCore = {
 
   getItemById(threadId: string): ThreadListItemCoreState | undefined;
 
-  switchToThread(threadId: string): Promise<void>;
+  switchToThread(
+    threadId: string,
+    options?: { unarchive?: boolean },
+  ): Promise<void>;
   switchToNewThread(): Promise<void>;
 
   getLoadThreadsPromise(): Promise<void>;

package/src/runtime/interfaces/thread-runtime-core.ts

@@ -45,6 +45,12 @@ export type ResumeToolCallOptions = {
   payload: unknown;
 };
 
+export type RespondToToolApprovalOptions = {
+  approvalId: string;
+  approved: boolean;
+  reason?: string;
+};
+
 export type SubmitFeedbackOptions = {
   messageId: string;
   type: "negative" | "positive";
@@ -85,11 +91,12 @@ export type ThreadRuntimeEventPayload = {
    */
   runEnd: Record<string, never>;
   /**
-   * @deprecated State-derivable. This event fires at the initialization
-   * transition immediately BEFORE the first message is added, so reading state
-   * inside the handler still sees an empty thread; observe `state.messages`
-   * becoming non-empty via a regular `subscribe` callback instead. Kept for
-   * backward compatibility.
+   * @deprecated State-derivable. Observe `state.messages` becoming non-empty
+   * via a regular `subscribe` callback instead. This event fires once at the
+   * initialization transition; subscribers that attach afterwards receive a
+   * one-off replay (on a microtask), by which point the thread already has
+   * messages, so handler-visible state differs between live and replayed
+   * delivery. Kept for backward compatibility.
    */
   initialize: Record<string, never>;
   /**
@@ -136,6 +143,7 @@ export type ThreadRuntimeCore = Readonly<{
 
   addToolResult: (options: AddToolResultOptions) => void;
   resumeToolCall: (options: ResumeToolCallOptions) => void;
+  respondToToolApproval: (options: RespondToToolApprovalOptions) => void;
 
   speak: (messageId: string) => void;
   stopSpeaking: () => void;

package/src/runtime/utils/thread-message-like.ts

@@ -14,6 +14,7 @@ import type {
   ThreadSystemMessage,
   FileMessagePart,
   DataMessagePart,
+  GenerativeUIMessagePart,
   Unstable_AudioMessagePart,
 } from "../../types/message";
 import type { CompleteAttachment } from "../../types/attachment";
@@ -39,6 +40,7 @@ export type ThreadMessageLike = {
         | ImageMessagePart
         | FileMessagePart
         | DataMessagePart
+        | GenerativeUIMessagePart
         | Unstable_AudioMessagePart
         | DataPrefixedPart
         | {
@@ -52,6 +54,13 @@ export type ThreadMessageLike = {
             readonly isError?: boolean | undefined;
             readonly parentId?: string | undefined;
             readonly messages?: readonly ThreadMessage[] | undefined;
+            readonly interrupt?: { type: "human"; payload: unknown };
+            readonly approval?: {
+              readonly id: string;
+              readonly approved?: boolean;
+              readonly reason?: string;
+              readonly isAutomatic?: boolean;
+            };
           }
       )[];
   readonly id?: string | undefined;
@@ -105,10 +114,13 @@ export const fromThreadMessageLike = (
     image,
     ...rest
   }: ImageMessagePart): ImageMessagePart | null => {
-    const match = image.match(
-      /^data:image\/(png|jpeg|jpg|gif|webp);base64,(.*)$/,
+    const dataUri = image.match(
+      /^data:image\/(png|jpeg|jpg|gif|webp|svg\+xml);base64,(.*)$/,
     );
-    if (match) {
+    if (dataUri) {
+      return { ...rest, image };
+    }
+    if (/^(https:\/\/|blob:)/.test(image)) {
       return { ...rest, image };
     }
     console.warn(`Invalid image data format detected`);
@@ -148,6 +160,9 @@ export const fromThreadMessageLike = (
               case "data":
                 return part;
 
+              case "generative-ui":
+                return part;
+
               case "tool-call": {
                 const { parentId, messages, ...basePart } = part;
                 const commonProps = {

package/src/runtimes/external-store/external-store-adapter.ts

@@ -9,6 +9,7 @@ import type { RealtimeVoiceAdapter } from "../../adapters/voice";
 import type { FeedbackAdapter } from "../../adapters/feedback";
 import type {
   AddToolResultOptions,
+  RespondToToolApprovalOptions,
   StartRunConfig,
   ResumeRunConfig,
   ThreadSuggestion,
@@ -108,6 +109,9 @@ type ExternalStoreAdapterBase<T> = {
   onResumeToolCall?:
     | ((options: { toolCallId: string; payload: unknown }) => void)
     | undefined;
+  onRespondToToolApproval?:
+    | ((options: RespondToToolApprovalOptions) => Promise<void> | void)
+    | undefined;
   convertMessage?: ExternalStoreMessageConverter<T> | undefined;
   adapters?:
     | {

package/src/runtimes/external-store/external-store-thread-list-runtime-core.ts

@@ -168,7 +168,10 @@ export class ExternalStoreThreadListRuntimeCore
     this._notifySubscribers();
   }
 
-  public async switchToThread(threadId: string): Promise<void> {
+  public async switchToThread(
+    threadId: string,
+    _options?: { unarchive?: boolean },
+  ): Promise<void> {
     if (this._mainThreadId === threadId) return;
     const onSwitchToThread = this.adapter.onSwitchToThread;
     if (!onSwitchToThread)

package/src/runtimes/external-store/external-store-thread-runtime-core.ts

@@ -3,6 +3,7 @@ import type {
   AddToolResultOptions,
   ResumeRunConfig,
   ResumeToolCallOptions,
+  RespondToToolApprovalOptions,
   StartRunConfig,
   ThreadSuggestion,
 } from "../../runtime/interfaces/thread-runtime-core";
@@ -372,6 +373,12 @@ export class ExternalStoreThreadRuntimeCore
     this._store.onResumeToolCall(options);
   }
 
+  public respondToToolApproval(options: RespondToToolApprovalOptions) {
+    if (!this._store.onRespondToToolApproval)
+      throw new Error("Runtime does not support tool approvals.");
+    this._store.onRespondToToolApproval(options);
+  }
+
   public override reset(initialMessages?: readonly ThreadMessageLike[]) {
     this._lastSyncedMessageIds = new Set();
     const repo = new MessageRepository();

package/src/runtimes/local/local-thread-runtime-core.ts

@@ -9,6 +9,7 @@ import type { LocalRuntimeOptionsBase } from "./local-runtime-options";
 import type {
   AddToolResultOptions,
   ResumeToolCallOptions,
+  RespondToToolApprovalOptions,
   ThreadSuggestion,
   ThreadRuntimeCore,
   StartRunConfig,
@@ -535,4 +536,8 @@ export class LocalThreadRuntimeCore
   public resumeToolCall(_options: ResumeToolCallOptions) {
     throw new Error("Local runtime does not support resuming tool calls.");
   }
+
+  public respondToToolApproval(_options: RespondToToolApprovalOptions) {
+    throw new Error("Local runtime does not support tool approvals.");
+  }
 }

package/src/runtimes/readonly/ReadonlyThreadRuntimeCore.ts

@@ -65,6 +65,10 @@ export class ReadonlyThreadRuntimeCore
     throw READONLY_THREAD_ERROR;
   }
 
+  respondToToolApproval(): void {
+    throw READONLY_THREAD_ERROR;
+  }
+
   speak(): void {
     throw READONLY_THREAD_ERROR;
   }

package/src/runtimes/remote-thread-list/empty-thread-core.ts

@@ -40,6 +40,10 @@ export const EMPTY_THREAD_CORE: ThreadRuntimeCore = {
     throw EMPTY_THREAD_ERROR;
   },
 
+  respondToToolApproval() {
+    throw EMPTY_THREAD_ERROR;
+  },
+
   speak() {
     throw EMPTY_THREAD_ERROR;
   },

package/src/store/clients/thread-message-client.ts

@@ -38,6 +38,9 @@ const ThreadMessagePartClient = resource(
       resumeToolCall: () => {
         throw new Error("Not supported");
       },
+      respondToToolApproval: () => {
+        throw new Error("Not supported");
+      },
     };
   },
 );

package/src/store/runtime-clients/message-part-runtime-client.ts

@@ -11,6 +11,8 @@ export const MessagePartClient = resource(
       getState: () => state,
       addToolResult: (result) => runtime.addToolResult(result),
       resumeToolCall: (payload) => runtime.resumeToolCall(payload),
+      respondToToolApproval: (response) =>
+        runtime.respondToToolApproval(response),
       __internal_getRuntime: () => runtime,
     };
   },

package/src/store/runtime-clients/thread-list-runtime-client.ts

@@ -81,8 +81,8 @@ export const ThreadListClient = resource(
           : state.threadIds[index]!;
         return threadItems.get({ key: id });
       },
-      switchToThread: async (threadId) => {
-        await runtime.switchToThread(threadId);
+      switchToThread: async (threadId, options) => {
+        await runtime.switchToThread(threadId, options);
       },
       switchToNewThread: async () => {
         await runtime.switchToNewThread();

package/src/store/scopes/part.ts

@@ -26,6 +26,10 @@ export type PartMethods = {
    * This is useful when a tool has requested human input and is waiting for a response.
    */
   resumeToolCall(payload: unknown): void;
+  /**
+   * Respond to a server-side tool approval gate. The approval id is read from the part.
+   */
+  respondToToolApproval(response: { approved: boolean; reason?: string }): void;
   __internal_getRuntime?(): MessagePartRuntime;
 };
 

package/src/store/scopes/thread-list-item.ts

@@ -12,7 +12,7 @@ export type ThreadListItemState = {
 
 export type ThreadListItemMethods = {
   getState(): ThreadListItemState;
-  switchTo(): void;
+  switchTo(options?: { unarchive?: boolean }): void;
   rename(newTitle: string): void;
   archive(): void;
   unarchive(): void;

package/src/store/scopes/threads.ts

@@ -19,7 +19,7 @@ export type ThreadsState = {
 
 export type ThreadsMethods = {
   getState(): ThreadsState;
-  switchToThread(threadId: string): void;
+  switchToThread(threadId: string, options?: { unarchive?: boolean }): void;
   switchToNewThread(): void;
   item(
     threadIdOrOptions: