@assistant-ui/core 0.2.4 → 0.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/core",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Framework-agnostic core runtime for assistant-ui",
   "keywords": [
     "assistant",
@@ -59,15 +59,15 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "assistant-stream": "^0.3.15",
+    "assistant-stream": "^0.3.17",
     "nanoid": "^5.1.11"
   },
   "peerDependencies": {
-    "@assistant-ui/store": "^0.2.11",
-    "@assistant-ui/tap": "^0.5.11",
+    "@assistant-ui/store": "^0.2.12",
+    "@assistant-ui/tap": "^0.5.12",
     "@types/react": "*",
     "react": "^18 || ^19",
-    "assistant-cloud": "^0.1.28",
+    "assistant-cloud": "^0.1.29",
     "zustand": "^5.0.11"
   },
   "peerDependenciesMeta": {
@@ -85,14 +85,14 @@
     }
   },
   "devDependencies": {
-    "@types/react": "^19.2.14",
-    "react": "^19.2.5",
-    "vitest": "^4.1.5",
+    "@types/react": "^19.2.15",
+    "react": "^19.2.6",
+    "vitest": "^4.1.7",
     "zustand": "^5.0.13",
-    "@assistant-ui/store": "0.2.11",
-    "@assistant-ui/tap": "0.5.11",
-    "@assistant-ui/x-buildutils": "0.0.8",
-    "assistant-cloud": "0.1.28"
+    "@assistant-ui/store": "0.2.12",
+    "@assistant-ui/tap": "0.5.12",
+    "@assistant-ui/x-buildutils": "0.0.9",
+    "assistant-cloud": "0.1.29"
   },
   "publishConfig": {
     "access": "public",

package/src/index.ts

@@ -9,6 +9,9 @@ export type {
   ImageMessagePart,
   FileMessagePart,
   DataMessagePart,
+  GenerativeUIMessagePart,
+  GenerativeUINode,
+  GenerativeUISpec,
   Unstable_AudioMessagePart,
   ToolCallMessagePart,
   ToolCallMessagePartMcpMetadata,
@@ -167,6 +170,7 @@ export type {
   RuntimeCapabilities,
   AddToolResultOptions,
   ResumeToolCallOptions,
+  RespondToToolApprovalOptions,
   SubmitFeedbackOptions,
   ThreadSuggestion,
   SpeechState,

package/src/react/index.ts

@@ -71,6 +71,10 @@ export type {
   ReasoningGroupComponent,
   QuoteMessagePartComponent,
   QuoteMessagePartProps,
+  GenerativeUIComponentRegistry,
+  GenerativeUIMessagePartComponent,
+  GenerativeUIMessagePartProps,
+  GenerativeUIRenderProps,
 } from "./types/MessagePartComponentTypes";
 export type {
   ToolsState,
@@ -143,6 +147,14 @@ export { useRemoteThreadListRuntime } from "./runtimes/useRemoteThreadListRuntim
 export { useCloudThreadListAdapter } from "./runtimes/cloud/useCloudThreadListAdapter";
 export { useAssistantCloudThreadHistoryAdapter } from "./runtimes/cloud/AssistantCloudThreadHistoryAdapter";
 export { CloudFileAttachmentAdapter } from "./runtimes/cloud/CloudFileAttachmentAdapter";
+export {
+  createLocalStorageAdapter,
+  type AsyncStorageLike,
+} from "./adapters/LocalStorageThreadListAdapter";
+export {
+  createSimpleTitleAdapter,
+  type TitleGenerationAdapter,
+} from "./adapters/TitleGenerationAdapter";
 
 // AssistantProvider base
 export {
@@ -166,6 +178,12 @@ export {
   type PartState,
 } from "./primitives/message/MessageParts";
 export { MessagePrimitiveGroupedParts } from "./primitives/message/MessageGroupedParts";
+export { groupPartByType } from "./utils/groupParts";
+export {
+  MessagePrimitiveGenerativeUI,
+  GenerativeUIRender,
+  GenerativeUIRenderError,
+} from "./primitives/generativeUI/GenerativeUI";
 export { MessagePrimitiveQuote } from "./primitives/message/MessageQuote";
 export {
   MessagePrimitiveAttachments,

package/src/react/primitives/generativeUI/GenerativeUI.tsx

@@ -0,0 +1,182 @@
+"use client";
+
+import {
+  type ComponentType,
+  type FC,
+  type ReactNode,
+  createElement,
+  useMemo,
+} from "react";
+import { useAuiState } from "@assistant-ui/store";
+import type {
+  GenerativeUINode,
+  GenerativeUISpec,
+} from "../../../types/message";
+import type {
+  GenerativeUIComponentRegistry,
+  GenerativeUIRenderProps,
+} from "../../types/MessagePartComponentTypes";
+
+/**
+ * Thrown when a generative-ui spec references a component name that is not
+ * present in the consumer-provided allowlist. The allowlist is the security
+ * boundary in the same-realm rendering path — there is no fallback by
+ * default. Pass `Fallback` to opt into a soft-fail UX.
+ */
+export class GenerativeUIRenderError extends Error {
+  public readonly componentName: string;
+
+  constructor(
+    componentName: string,
+    message = `Component "${componentName}" is not in the generative-ui allowlist.`,
+  ) {
+    super(message);
+    this.name = "GenerativeUIRenderError";
+    this.componentName = componentName;
+  }
+}
+
+const isObjectNode = (
+  node: GenerativeUINode,
+): node is Exclude<GenerativeUINode, string> =>
+  typeof node === "object" && node !== null;
+
+const renderNode = (
+  node: GenerativeUINode | undefined,
+  components: GenerativeUIComponentRegistry,
+  Fallback: GenerativeUIRenderProps["Fallback"],
+  path: string,
+): ReactNode => {
+  if (node === undefined || node === null) return null;
+
+  if (typeof node === "string") return node;
+
+  if (!isObjectNode(node) || !("component" in node)) {
+    if (
+      typeof process !== "undefined" &&
+      process.env?.NODE_ENV !== "production"
+    ) {
+      console.warn(`[generative-ui] Skipping malformed node at ${path}:`, node);
+    }
+    return null;
+  }
+
+  const { component, props, children, key } = node;
+
+  const Resolved = components[component];
+  if (!Resolved) {
+    if (Fallback) {
+      return <Fallback key={key ?? path} component={component} props={props} />;
+    }
+    throw new GenerativeUIRenderError(component);
+  }
+
+  const renderedChildren = children?.length
+    ? children.map((child, i) =>
+        renderNode(child, components, Fallback, `${path}/${i}`),
+      )
+    : undefined;
+
+  return createElement(
+    Resolved,
+    { ...(props ?? {}), key: key ?? path },
+    ...(renderedChildren ?? []),
+  );
+};
+
+const normalizeRoot = (
+  spec: GenerativeUISpec | undefined,
+): readonly GenerativeUINode[] => {
+  if (!spec || spec.root === undefined || spec.root === null) return [];
+  const root = spec.root;
+  return Array.isArray(root)
+    ? (root as readonly GenerativeUINode[])
+    : [root as GenerativeUINode];
+};
+
+/**
+ * Internal renderer. Resolves a {@link GenerativeUISpec} against the consumer
+ * allowlist. Used by `MessagePrimitive.GenerativeUI` and by
+ * `MessagePrimitive.Parts` when handling a `generative-ui` part.
+ */
+export const GenerativeUIRender: FC<GenerativeUIRenderProps> = ({
+  spec,
+  components,
+  Fallback,
+}) => {
+  const nodes = useMemo(() => normalizeRoot(spec), [spec]);
+
+  return (
+    <>
+      {nodes.map((node, i) => renderNode(node, components, Fallback, `${i}`))}
+    </>
+  );
+};
+
+GenerativeUIRender.displayName = "GenerativeUIRender";
+
+export namespace MessagePrimitiveGenerativeUI {
+  export type Props = {
+    /**
+     * The component allowlist. Keys are the names referenced in the spec
+     * (e.g. `"Card"`, `"Button"`), values are the React components.
+     *
+     * This is the security boundary — any name not in the allowlist is
+     * rejected with {@link GenerativeUIRenderError}.
+     */
+    components: GenerativeUIComponentRegistry;
+    /**
+     * Optional override spec. If omitted, the primitive reads the
+     * `generative-ui` part from the surrounding `MessagePartProvider` /
+     * `PartByIndexProvider` context.
+     */
+    spec?: GenerativeUISpec | undefined;
+    /** Optional fallback for unknown component names. */
+    Fallback?:
+      | ComponentType<{ component: string; props?: unknown }>
+      | undefined;
+  };
+}
+
+/**
+ * Renders a generative-ui message part using a consumer-provided allowlist.
+ *
+ * The agent emits a `generative-ui` message part containing a JSON spec
+ * (see {@link GenerativeUISpec}). This primitive walks the spec and resolves
+ * each `component` name against the allowlist. Names not in the allowlist
+ * throw {@link GenerativeUIRenderError} unless a `Fallback` is provided.
+ *
+ * Stream-friendly: a partial spec renders progressively as it is filled in.
+ *
+ * @example
+ * ```tsx
+ * <MessagePrimitive.GenerativeUI
+ *   components={{ Card: MyCard, Button: MyButton }}
+ * />
+ * ```
+ */
+export const MessagePrimitiveGenerativeUI: FC<
+  MessagePrimitiveGenerativeUI.Props
+> = ({ components, spec, Fallback }) => {
+  // Selector reads store state only — combining with the `spec` prop inside
+  // the selector closes over a value that may change identity per render and
+  // would trigger spurious tearing-detection re-renders in
+  // `useSyncExternalStore`.
+  const storeSpec = useAuiState((s) => {
+    const part = s.part as { type?: string; spec?: GenerativeUISpec };
+    return part?.type === "generative-ui" ? part.spec : undefined;
+  });
+  const partSpec = spec ?? storeSpec;
+
+  if (!partSpec) return null;
+
+  return (
+    <GenerativeUIRender
+      spec={partSpec}
+      components={components}
+      Fallback={Fallback}
+    />
+  );
+};
+
+MessagePrimitiveGenerativeUI.displayName = "MessagePrimitive.GenerativeUI";

package/src/react/primitives/message/MessageGroupedParts.tsx

@@ -10,9 +10,8 @@ import type {
 } from "../../../types/message";
 import {
   buildGroupTree,
-  type GroupKey,
+  GROUPBY_MEMO_KEY,
   type GroupNode,
-  normalizeGroupKey,
 } from "../../utils/groupParts";
 import { MessagePartChildren, type EnrichedPartState } from "./MessageParts";
 
@@ -47,30 +46,32 @@ export namespace MessagePrimitiveGroupedParts {
 
   export type Props<TKey extends `group-${string}` = `group-${string}`> = {
     /**
-     * Maps each part to its group key path. Adjacent parts that share a
-     * prefix coalesce up to that prefix. Return `null`, `undefined`, or
-     * `[]` to leave a part ungrouped — it will be rendered as a leaf
-     * through `children` with `part` set to its {@link EnrichedPartState}.
+     * Maps each part to a group-key path. Adjacent parts that share a
+     * prefix coalesce into the same group. Return `[]` (or `null`) to
+     * leave a part ungrouped.
      *
-     * Keys must start with `"group-"` so the renderer's
-     * `switch (part.type)` can distinguish groups from real part types.
+     * Group keys must start with `"group-"` so the renderer's
+     * `switch (part.type)` can tell groups apart from real part types.
      *
-     * For best performance, pass a stable reference (module-level
-     * constant or `useCallback`).
+     * **Prefer {@link groupPartByType}** for the common case of mapping by
+     * `part.type` — it ships a stable memo fingerprint so the tree
+     * survives unrelated re-renders. Use an inline function only when
+     * the helper isn't expressive enough (e.g. branching on
+     * `part.toolName` or part metadata).
      *
      * @example
-     * ```ts
-     * const groupBy = (part) =>
-     *   part.type === "reasoning" ? ["group-thought", "group-reasoning"] :
-     *   part.type === "tool-call" ? ["group-thought", "group-tool"] :
-     *   null;
+     * ```tsx
+     * import { groupPartByType } from "@assistant-ui/react";
+     *
+     * <MessagePrimitive.GroupedParts
+     *   groupBy={groupPartByType({
+     *     reasoning: ["group-thought", "group-reasoning"],
+     *     "tool-call": ["group-thought", "group-tool"],
+     *   })}
+     * >
      * ```
      */
-    readonly groupBy: (
-      part: PartState,
-      index: number,
-      parts: readonly PartState[],
-    ) => GroupKey<TKey>;
+    readonly groupBy: (part: PartState) => readonly TKey[] | null;
 
     /**
      * Render function called once per group node and once per leaf part.
@@ -79,7 +80,7 @@ export namespace MessagePrimitiveGroupedParts {
      *
      * Leaf parts receive the same {@link EnrichedPartState} that
      * `<MessagePrimitive.Parts>` would produce (`toolUI`, `addResult`,
-     * `resume`, `dataRendererUI`).
+     * `resume`, `respondToApproval`, `dataRendererUI`).
      */
     readonly children: (info: RenderInfo<TKey>) => ReactNode;
   };
@@ -148,11 +149,10 @@ const renderNode = <TKey extends `group-${string}`>(
  * @example
  * ```tsx
  * <MessagePrimitive.GroupedParts
- *   groupBy={(part) =>
- *     part.type === "reasoning" ? ["group-thought", "group-reasoning"] :
- *     part.type === "tool-call" ? ["group-thought", "group-tool"] :
- *     null
- *   }
+ *   groupBy={groupPartByType({
+ *     reasoning: ["group-thought", "group-reasoning"],
+ *     "tool-call": ["group-thought", "group-tool"],
+ *   })}
  * >
  *   {({ part, children }) => {
  *     switch (part.type) {
@@ -173,12 +173,19 @@ export const MessagePrimitiveGroupedParts = <TKey extends `group-${string}`>({
 }: MessagePrimitiveGroupedParts.Props<TKey>): ReactNode => {
   const parts = useAuiState(useShallow((s) => s.message.parts));
 
+  // Helpers like `groupPartByType` tag the function with `GROUPBY_MEMO_KEY`
+  // (a stable string fingerprint of the helper config). When present,
+  // memo on `[parts, memoKey]` so the tree survives unrelated renders.
+  // For inline `groupBy`, fall back to recomputing each render — O(n)
+  // and cheap.
+  const memoKey = (groupBy as { [GROUPBY_MEMO_KEY]?: string })[
+    GROUPBY_MEMO_KEY
+  ];
+  const memoDep = memoKey ?? groupBy;
+  // biome-ignore lint/correctness/useExhaustiveDependencies: groupBy is captured via memoDep — either as its identity (no memoKey) or as the helper's memoKey fingerprint. Listing groupBy directly would defeat the helper-tagged memo path.
   const tree = useMemo(
-    () =>
-      buildGroupTree(
-        parts.map((part, i) => normalizeGroupKey(groupBy(part, i, parts))),
-      ),
-    [parts, groupBy],
+    () => buildGroupTree(parts.map((part) => groupBy(part) ?? [])),
+    [parts, memoDep],
   );
 
   return <>{tree.map((node) => renderNode(node, parts, children))}</>;

package/src/react/primitives/message/MessageParts.tsx

@@ -30,8 +30,14 @@ import type {
   ReasoningMessagePartComponent,
   ReasoningGroupComponent,
   QuoteMessagePartComponent,
+  GenerativeUIComponentRegistry,
 } from "../../types/MessagePartComponentTypes";
-import { isMcpAppUri, type MessagePartStatus } from "../../../types/message";
+import { GenerativeUIRender } from "../generativeUI/GenerativeUI";
+import {
+  isMcpAppUri,
+  type MessagePartStatus,
+  type GenerativeUIMessagePart,
+} from "../../../types/message";
 import type { DataRenderersState } from "../../types/scopes/dataRenderers";
 import type { ToolsState } from "../../types/scopes/tools";
 import { useShallow } from "zustand/shallow";
@@ -174,6 +180,24 @@ export namespace MessagePrimitiveParts {
     data?: DataConfig | undefined;
     /** Component for rendering a quoted message reference (from metadata, not parts) */
     Quote?: QuoteMessagePartComponent | undefined;
+    /**
+     * Configuration for generative-ui part rendering.
+     *
+     * `components` is the consumer-provided allowlist of React components
+     * the agent's JSON spec is permitted to render. Any name not present in
+     * the registry is rejected with a typed `GenerativeUIRenderError` —
+     * this is the security boundary in the same-realm rendering path.
+     */
+    generativeUI?:
+      | {
+          /** The component allowlist (the security boundary). */
+          components: GenerativeUIComponentRegistry;
+          /** Optional fallback for unknown component names. */
+          Fallback?:
+            | ComponentType<{ component: string; props?: unknown }>
+            | undefined;
+        }
+      | undefined;
   };
 
   type ToolsConfig =
@@ -345,6 +369,7 @@ export const MessagePartComponent: FC<MessagePartComponentProps> = ({
     Unstable_Audio: Audio = defaultComponents.Unstable_Audio,
     tools = {},
     data,
+    generativeUI,
   } = {},
 }) => {
   const aui = useAui();
@@ -354,8 +379,16 @@ export const MessagePartComponent: FC<MessagePartComponentProps> = ({
   if (type === "tool-call") {
     const addResult = aui.part().addToolResult;
     const resume = aui.part().resumeToolCall;
+    const respondToApproval = aui.part().respondToToolApproval;
     if ("Override" in tools)
-      return <tools.Override {...part} addResult={addResult} resume={resume} />;
+      return (
+        <tools.Override
+          {...part}
+          addResult={addResult}
+          resume={resume}
+          respondToApproval={respondToApproval}
+        />
+      );
     const Tool = tools.by_name?.[part.toolName] ?? tools.Fallback;
     return (
       <ToolUIDisplay
@@ -363,6 +396,7 @@ export const MessagePartComponent: FC<MessagePartComponentProps> = ({
         Fallback={Tool}
         addResult={addResult}
         resume={resume}
+        respondToApproval={respondToApproval}
       />
     );
   }
@@ -394,6 +428,29 @@ export const MessagePartComponent: FC<MessagePartComponentProps> = ({
       return <DataUIDisplay {...part} Fallback={Data} />;
     }
 
+    case "generative-ui": {
+      if (!generativeUI?.components) {
+        if (
+          typeof process !== "undefined" &&
+          process.env?.NODE_ENV !== "production"
+        ) {
+          console.warn(
+            "MessagePrimitive.Parts received a generative-ui part but no " +
+              "`components.generativeUI.components` allowlist was provided. " +
+              "Pass an allowlist or render with <MessagePrimitive.GenerativeUI />.",
+          );
+        }
+        return null;
+      }
+      return (
+        <GenerativeUIRender
+          spec={(part as GenerativeUIMessagePart).spec}
+          components={generativeUI.components}
+          Fallback={generativeUI.Fallback}
+        />
+      );
+    }
+
     default:
       console.warn(`Unknown message part type: ${type}`);
       return null;
@@ -429,6 +486,7 @@ export const MessagePrimitivePartByIndex: FC<MessagePrimitivePartByIndex.Props>
       prev.components?.Unstable_Audio === next.components?.Unstable_Audio &&
       prev.components?.tools === next.components?.tools &&
       prev.components?.data === next.components?.data &&
+      prev.components?.generativeUI === next.components?.generativeUI &&
       prev.components?.ToolGroup === next.components?.ToolGroup &&
       prev.components?.ReasoningGroup === next.components?.ReasoningGroup,
   );
@@ -543,6 +601,7 @@ const RegisteredToolUI: FC = () => {
       {...part}
       addResult={aui.part().addToolResult}
       resume={aui.part().resumeToolCall}
+      respondToApproval={aui.part().respondToToolApproval}
     />
   );
 };
@@ -608,6 +667,8 @@ export type EnrichedPartState =
       addResult: ToolCallMessagePartProps["addResult"];
       /** Resume a tool call waiting for human input. */
       resume: ToolCallMessagePartProps["resume"];
+      /** Respond to a server-side tool approval gate. */
+      respondToApproval: ToolCallMessagePartProps["respondToApproval"];
     })
   | (Extract<PartState, { type: "data" }> & {
       /** The registered data renderer UI element, or null if none registered. */
@@ -657,6 +718,7 @@ export const MessagePartChildren: FC<{
                   toolUI: hasUI ? <RegisteredToolUI /> : null,
                   addResult: partMethods.addToolResult,
                   resume: partMethods.resumeToolCall,
+                  respondToApproval: partMethods.respondToToolApproval,
                 };
               }
               if (state.type === "data") {

package/src/react/providers/TextMessagePartProvider.tsx

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

package/src/react/runtimes/RemoteThreadListHookInstanceManager.tsx

@@ -128,6 +128,7 @@ export class RemoteThreadListHookInstanceManager extends BaseSubscribable {
 
     const aui = useAui();
     const initPromiseRef = useRef<Promise<unknown> | undefined>(undefined);
+    const hasInitializedRef = useRef(false);
 
     useEffect(() => {
       const runtimeCore = threadBinding.getState();
@@ -139,17 +140,20 @@ export class RemoteThreadListHookInstanceManager extends BaseSubscribable {
     }, [threadBinding]);
 
     useEffect(() => {
+      hasInitializedRef.current = false;
       return runtime.threads.main.unstable_on("initialize", () => {
+        if (hasInitializedRef.current) return;
+
         const state = aui.threadListItem().getState();
-        if (state.status === "new") {
-          initPromiseRef.current = aui.threadListItem().initialize();
+        if (state.status !== "new") return;
+        hasInitializedRef.current = true;
 
-          const dispose = runtime.thread.unstable_on("runEnd", () => {
-            dispose();
+        initPromiseRef.current = aui.threadListItem().initialize();
 
-            aui.threadListItem().generateTitle();
-          });
-        }
+        const dispose = runtime.thread.unstable_on("runEnd", () => {
+          dispose();
+          aui.threadListItem().generateTitle();
+        });
       });
     }, [runtime, aui]);
 

package/src/react/runtimes/RemoteThreadListThreadListRuntimeCore.tsx

@@ -274,7 +274,10 @@ export class RemoteThreadListThreadListRuntimeCore
     return getThreadData(this._state.value, threadIdOrRemoteId);
   }
 
-  public async switchToThread(threadIdOrRemoteId: string): Promise<void> {
+  public async switchToThread(
+    threadIdOrRemoteId: string,
+    options?: { unarchive?: boolean },
+  ): Promise<void> {
     let data = this.getItemById(threadIdOrRemoteId);
 
     if (!data) {
@@ -343,7 +346,9 @@ export class RemoteThreadListThreadListRuntimeCore
       task.then(() => this._notifySubscribers());
     }
 
-    if (data.status === "archived") await this.unarchive(data.id);
+    if (data.status === "archived" && options?.unarchive !== false) {
+      await this.unarchive(data.id);
+    }
     this._mainThreadId = data.id;
 
     this._notifySubscribers();

package/src/react/runtimes/cloud/auiV0.ts

@@ -163,7 +163,7 @@ export function auiV0Encode(message: ThreadMessage): AuiV0Message {
           };
 
         default: {
-          const unhandledType: "audio" | "data" = type;
+          const unhandledType: "audio" | "data" | "generative-ui" = type;
           throw new Error(
             `Message part type not supported by aui/v0: ${unhandledType}`,
           );