npm / @assistant-ui/react
@assistant-ui/react
What changed in @assistant-ui/react 0.11 to 0.15, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-17.
79 breaking2 security20 deprecations159 new APIs and options1 performance37 behavior and defaults1 tooling156 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@assistant-ui/react 0.15207 changes
Breaking changes 26
Disposing a frame immediately tells its parent it is gone, causing waiting tool calls to be rejected instead of timing out after 30 seconds.
Attachment rendering now includes still-uploading attachments, so renderers receive Attachment rather than CompleteAttachment.
The runtime state returned by ThreadRuntime.getState() now has a named exported type.
@assistant-ui/core now requires assistant-cloud version 0.2.0 or newer.
The function now returns a promise that rejects when the runtime cannot record the response, leaving refused requests retryable.
Moves useAssistantTransportRuntime into core/react, changing the package location developers use to import it.
The Assistant augmentation namespace moved from @assistant-ui/react into @assistant-ui/core, so imports may need updating.
ExternalThread moved from @assistant-ui/react into @assistant-ui/core, so imports may need updating.
SingleThreadList moved from @assistant-ui/react into @assistant-ui/core, so imports may need updating.
ExternalThread edit composer now reads editing state live; same-tick beginEdit + setText + send dispatches the edit, while invalid send and duplicate beginEdit throw.
beginEdit now fails fast when no edit handler is configured.
Unchanged edits now resend the message on a new branch instead of silently closing the composer.
AuiConfig(...) creates branded configurations accepted by AuiProvider, including top-level and nested client scopes.
Nested providers must pass extends with a client to extend or null to isolate; empty configs extend the parent client.
ExternalThreadQueueAdapter clear(reason) is removed; queue clearing policy is host-owned.
edit is now required on ExternalThreadQueueAdapter.
ExternalThreadQueueAdapter enqueue no longer accepts steer options; steering is a separate operation.
move is now required on ExternalThreadQueueAdapter.
QueueItemState.parts is now required.
ExternalThreadQueueAdapter steer(queueItemId) is replaced by move with a steer lane and null insertion point.
steerItems is now required on ExternalThreadQueueAdapter.
Custom resources must return a stable object identity to avoid repeated refetches and loadingFallback during re-renders.
Unavailable scopes no longer throw during selection; check availability through source before reading other properties or calling.
The mcp-app group key was removed; use standalone-tool-call instead.
The component-only ToolsState.tools map was removed; use toolUIs instead.
Legacy context hooks deprecated in v0.12/v0.14 were removed; use useAui or useAuiState instead.
Security 1
MCP App resource CSP metadata is enforced inside widget frames.
Deprecations 12
The Unstable_TriggerPopover aliases are now struck through as deprecated in TypeScript.
Experimental APIs are marked deprecated since their experimental date so editors strike them through and no-deprecated checks report them.
The unused history adapter option on useAssistantTransportRuntime is deprecated.
ThreadState remains a runtime-state alias for now but is deprecated ahead of its store-state meaning in 0.16.
Primitive.Empty is deprecated on react-native and react-ink in favor of AuiIf.
Primitive.If is deprecated on react-native and react-ink in favor of AuiIf.
Deprecated in favor of threads.selectionChanged, which also covers selection changes previously missed by the switched events.
Deprecated in favor of threads.selectionChanged, which also covers selection changes previously missed by the switched events.
The value prop is deprecated and now exposes a new client extending the given one rather than the exact instance.
The useAui extension overload is deprecated.
Audio message parts are deprecated in favor of file parts with an audio/* MIME type.
Nullary scope accessors are now properties; calling them still works but is deprecated.
New APIs and options 51
Adds an adapter for direct browser voice sessions with streamed transcripts, typed input, mute controls, and cancellable WebRTC setup.
Tool approvals can ask multiple questions or allow multiple answers, with validation and recorded answers exposed to response handlers and converters.
Long threads can be virtualized per part using stable thread rows, reducing rerenders while tokens stream and enabling turn-duration footers.
Threads can open on their latest page and load older messages on demand through external-store, runtime, primitive, and React Native APIs.
Converter metadata can be invalidated at message scope.
Reasoning parts now expose optional start and end timing, enabling hosts and grouped parts to show agent thinking duration.
Visible component action settle delays can be configured.
The package now re-exports MessageRole, RunConfig, RuntimeCapabilities, RemoteThreadListOptions, ThreadsState, JoinStrategy, title adapters, and ChainOfThoughtPartByIndexProvider.
The package now re-exports additional runtime, voice, tool, generative UI, message queue, and cloud thread list APIs.
The package now re-exports voice, cloud thread list, generative UI, runtime state, and adapter types.
CloudRendererHost can render stored conversations in the Assistant Cloud dashboard using the app's components.
Voice sessions can accept typed text through sendText, committing it as a typed turn.
Recorded tool interactions are kept on the part and stored in cloud history.
External stores receive recorded tool interactions through a new callback.
Tool UIs can record user actions on tool calls, with records persisted according to the runtime or external store.
useAssistantTransportRuntime accepts cloud, enabling Assistant Cloud thread lists and cloud thread IDs on requests.
VoiceSessionState exposes canSendText so composers can determine whether typed text is accepted.
An opt-in cache preserves unchanged ThreadMessage objects across calls, avoiding rebuilds for nested streamed transcripts.
Voice transcript messages are marked with metadata.modality.
Cloud files now provide a presigned download URL generator.
Custom scores can now be created through cloud.scores.create.
CloudAPIError now exposes an error code, including plan_limit_reached for a 402 response.
CloudAPIError now exposes structured error details.
A createRunReport builder assembles expanded Assistant Cloud run report bodies for the runtime and cloud SDK.
Engagement events are batched without message content, and telemetry.events: false opts out.
Upload responses now include the object key.
useCloudChat now exposes message feedback alongside the assistant-ui FeedbackAdapter.
Trace metadata can be applied so browser reports and server spans merge into one run.
Renderer options can now be resolved per part, including host context, display-related fallbacks, sandbox, host information, and handlers.
Sandboxed frames that never finish loading are reported through onError with re-exported error types.
Sandboxed frames that never finish loading are reported through onError with re-exported error types.
Approval requests can describe their prompt, display mode, and freeform-answer support so renderers can distinguish questions from permission gates.
Tool approval responses can include a text answer, resolving the request as answered rather than approved.
Adds a provider for publishing frontend tools to a WebMCP-capable browser.
createSuggestionAdapter and its option types are exported from the distribution packages.
Adds a remote thread-list store entry that lets AssistantClient hosts run remote thread lists using an adapter and thread factory.
Adds unstable_useAdapters so RemoteThreadList can load per-thread history without rendering unstable_Provider.
Adds a selectionChanged event carrying threadId and previousThreadId for thread-selection changes.
ThreadSuggestion gains an optional label, allowing adapters to display a separate label while preserving the full prompt.
ThreadSuggestion gains an optional title so adapters can display a short pill while sending the full prompt.
Moves useCloudThreadListRuntime into core/react and removes the unused React copy of the aui/v0 codec.
ExternalThread can wire threads.reloadMainThread() through onRefetchThread, with refetchThread capability derived from the callback’s presence.
ExternalThread now supports feedback adapters.
ExternalThread now supports speech synthesis adapters.
AssistantRuntimeProvider accepts an optional config prop whose scopes are provided alongside the runtime scope.
The ref prop exposes the resulting client.
Decoders and the state accumulator support opt-in strict: false mode to reconcile malformed stream input instead of throwing.
File message parts can opt in to source types so attachment adapters can send URL or ID file references.
Thread list rows can determine whether their own thread is running, including background runs.
Runtimes that keep background threads alive can report per-thread running state through a new optional runtime method.
The open thread's remote state can be refetched in place.
Performance 1
Sparse suggestion lists are compacted before per-suggestion lookup.
Behavior and default changes 17
MCP App ui/initialize parameters, including declared display modes, are passed to onInitialized as McpAppInitializeParams.
Composer trigger popover primitives and related types receive stable names, while Unstable_ names remain deprecated aliases.
Tool execution and model output use successful Standard Schema output while preserving original arguments for validation errors and stored calls.
thread.tasks is derived from tool calls carrying nested conversations, with a task scope.
Anonymous threads can move into an authenticated Assistant Cloud workspace after sign-in.
The store now emits composer, message, and thread events consumed by engagement reporting.
The default handler accepts MCP Apps
{ role, content }parameters and appends text blocks in order, while preserving legacy result fields.Rejected sendMessage results now include the MCP Apps
isError: truefield while retaining legacyokandreasonfields.Assistant frame messaging now defaults to the current origin.
Trigger popovers can override query matching.
When configured with cloud, AISDKThreads uses RemoteThreadList and remounts each thread like useChatRuntime.
Selection-driven scrolling now engages for InMemoryThreadList changes, new threads, and resolved deep links.
App-authored reasoning summaries are now preserved on message parts.
Custom children are rendered and asChild is supported instead of always replacing content with an automatic label.
Message queues now use two lanes, placement awareness, and steer-by-default mid-run sends.
Accessor identity is stable across renders until a structural binding change, making accessor-keyed memoization invalidate precisely.
Scope accessors expose source, query, and name selection metadata as properties, reserving those names for scope methods.
Fixes and other changes 99
Selections made before an active thread change are ignored so files do not enter the replacement conversation.
Runs no longer move focus into the composer when focus starts outside the thread, while preserving the existing composer selection.
Frame tools and pending calls are cleared when the iframe document changes or reloads.
Pending attachment selections are preserved when unrelated assistant scopes change.
Sparse MCP Apps message content is handled without scanning array holes.
Disposes the host when its iframe is removed, rejects pending calls immediately, removes tools from model context, and serves a newly mounted iframe.
On React 18, inert composers now render the inert attribute so the cancel focus loop skips them as on React 19.
Typing, attachments, sends, and message editing are blocked while a thread is disabled.
MCP Apps are rendered through ToolUIDisplay across Parts, grouped, native, and ink rendering modes.
Grouped message parts are rendered through the core part renderer, keeping rendering behavior aligned with core.
Layout effects no longer cause React 18 server-render warnings while client layout timing remains unchanged.
The scroll-to-bottom control now appears after a wheel interrupts smooth scrolling.
The selection toolbar now appears after a window blur and when a selection ends at offset zero at the start of the next message.
Cancelling a message edit with Escape or keyboard or assistive-technology activation restores focus to the thread composer.
The thread viewport follows content that grows without DOM changes and updates isAtBottom so the scroll-to-bottom button can appear.
The viewport stops following the thread bottom when a user expands a disclosure inside a message, keeping the opened card in view.
User scrolls coalesced with programmatic bottom scrolling are now recognized correctly.
Streaming text, tool durations, and stall detection no longer read wall-clock time during render, allowing cacheComponents prerendering.
Cancelled and pre-load failed sandbox frame renders are cleaned up correctly.
Enter or Escape ending an IME composition is ignored, preventing Safari conversion commits from sending messages and cancellations from cancelling runs or stopping read-aloud.
Message parts are keyed by id when same-type parts do not share it, preventing replaced or reordered parts from retaining another part's component state.
Scopes Escape-triggered speech cancellation to the targeted thread.
Honors user={false}, assistant={false}, and system={false} by migrating them to matching AuiIf inequalities.
Modified arrow keys remain available to application shortcuts while ordinary thread-list focus navigation is preserved.
Publishes committed WebMCP tool implementations before layout effects.
Component, tool, and data-part registries only resolve own keys, preventing inherited Object.prototype names from rendering.
Disabled attachment dropzones no longer navigate to dropped files or retain drag state.
The download anchor is attached to the document so Firefox starts Markdown downloads.
Feedback submission state is now exposed to assistive technology.
Native MessageContent and grouped parts now honor registered data-part fallbacks.
Without cloud, this environment variable selects Assistant Cloud for useAssistantTransportRuntime, matching useLocalRuntime.
The transport request body is now typed, and threadId is an optional string rather than string | null.
Read-only threads report themselves disabled, disable their composer, and ignore composer input instead of throwing.
Typed turns in voice sessions retain their own modality and are no longer persisted as spoken messages.
Bottom following now resumes when auto-scroll is enabled at runtime.
Pending animation frames are canceled during teardown and between selection events.
Pending frame tool calls are settled when cancellation fails.
Scroll listeners continue receiving notifications after one listener fails.
MCP App bridge messages stop after disposal.
Flat mention items are ignored when categories is an empty list.
Message part text now renders inside the supplied render element.
Explicit render elements now control message part text rendering.
Stall detection resets when content changes without changing its length.
Every part renderer option is forwarded through MessagePrimitive.Parts, preserving data renderers through ChainOfThought.
Controlled and uncontrolled modal owners are notified when a run opens a closed modal.
Parent IDs are no longer conflated with ungrouped message parts.
Queued live completion requests no longer start after the component unmounts.
Quote selections crossing excluded content are rejected.
Sandbox teardown now finishes even when bridge cleanup reports errors.
Requested scroll behavior is preserved across nested viewport providers.
Tool allowlist changes now apply to mounted MCP app frames.
Root scrollers now measure viewport scrollbar width correctly to prevent horizontal page shifting during collapsible animations.
WebMCP tool cancellation works below the AbortSignal.any browser floor and with non-native caller signals.
WebMCP tools are cancelled while asynchronous validation is pending.
Newly mounted MCP Apps are loaded through the committed host.
Model-context mentions remain current during updates.
Explicit tool categories are honored without requiring custom categories.
Committed MCP App host options remain active during interrupted renders.
MCP App renderer handlers are exposed for integrations that need access to them.
MCP App server routing remains scoped to committed renders.
Sandbox bridge options remain scoped to committed renders.
Slash commands remain scoped to committed renders, and search now matches the displayed label or /id fallback.
DevTools updates continue flowing when a subscriber throws.
Rejected asynchronous Markdown exports are handled.
Render failures after teardown are contained.
Unrevealed smooth text is drained when a message completes before any frame.
ThreadIf now uses the loading-aware thread.isEmpty field instead of checking messages.length.
The trigger popover cursor is resynchronized after selection.
Assistant transport lifecycle callback failures are isolated so one failing callback does not disrupt transport handling.
Transport response callbacks are awaited, and unfinished responses are canceled when callbacks fail.
Data message parts are now persisted in aui/v0 cloud history.
Deleting the last thread creates a fresh thread, notifies the new onDelete callback, and applies deletes safely in batches.
Live completion results refresh after their data source changes, including synchronous live completion failures.
MCP App error replies remain reliable when error callbacks or notification callbacks throw.
Validates MCP App resource responses, improving reliability for integrations returning invalid resources.
Sandbox frames are disposed when bridge setup fails, preventing failed integrations from retaining frame resources.
Custom compositions must mount ThreadPrimitive.Root for Escape-to-stop-speaking to remain active when message action bars are hidden.
In-memory thread IDs are now generated uniquely.
A runtime rejecting onNew with MessageNotSentError restores the composer’s text, quote, and attachments when the send never reached the backend.
Replay response readers are released after completion, cancellation, and errors.
Suggestions scope is derived from the thread, allowing runtime-provided suggestions to render through ThreadPrimitive.Suggestions.
Edits carrying sourceId are routed to onEdit instead of the queue adapter.
Dropped assistant transport resume requests are now cleared.
Failed live completion searches can now be retried.
Blob URL revocation is deferred so the download fetch can start before revocation.
Hydrated assistant transport resumes now use their retained initial state.
Transport runs settle even when finish callbacks fail.
Extension-less filenames no longer render a bare period; the attachment type is used instead.
Escape during IME composition is ignored, preventing composition dismissal from cancelling the composer.
User onMouseDown handlers run before preventDefault through composed event handling.
Action button primitives no longer force type="button"; callers can override the default.
useAui({}) now mounts a rooted host so its scope set can grow across renders.
Object.keys and spread enumeration now includes scopes inherited from parent clients.
Assistant transport now skips add-message commands containing no supported parts.
Assistant-transport resume always decodes leniently, including when stream input is malformed.
Renaming a thread now persists the new title instead of dropping it.
Tool results such as false, 0, empty string, or null remain distinguishable from unfinished calls across the cloud round trip.
Using send no longer overwrites the composer draft during a run, and is disabled mid-run when queue support is unavailable.
The encoder now persists only enumerated attachment content fields, keeping per-part status out of the stored shape.
@assistant-ui/react 0.14135 changes
Breaking changes 29
Invoking an unset optional callback now throws a capability error.
Public enums are represented as as-const objects to support erasableSyntaxOnly.
Copied message text now excludes reasoning parts and includes only type: "text" content.
hitl moves from @assistant-ui/next to @assistant-ui/react and remains a build-time-stripped no-op marker.
The groupBy callback now accepts only a part and must return an array of group keys or null; bare-string returns are no longer supported.
Removed; use AuiIf instead.
Removed registerModelConfigProvider; use registerModelContextProvider instead.
Removed reset; use thread.reset instead.
Removed switchToNewThread; use threads.switchToNewThread instead.
Removed switchToThread; use threads.switchToThread instead.
Removed threadList; use threads instead.
Removed config; use context instead.
Removed; use toToolsJSONSchema from assistant-stream instead.
Removed the singular API; use getExternalStoreMessages instead.
Removed the submittedFeedback field; use message.metadata.submittedFeedback instead.
Removed onSwitchToThread; use load instead.
Removed getModelConfig; use getModelContext instead.
Removed the positional parentId overload; pass { parentId } instead.
Removed unstable_loadExternalState; use importExternalState instead.
Removed unstable_resumeRun; use resumeRun instead.
Removed; use toToolsJSONSchema from assistant-stream instead.
Removed the unstable_ alias; use InMemoryThreadListAdapter instead.
Removed the unstable_ alias; use RemoteThreadListAdapter instead.
Removed the unstable_ alias; use useCloudThreadListAdapter instead.
Removed the unstable_ alias; use useRemoteThreadListRuntime instead.
Removed; use useAui instead.
Removed; use useAuiEvent instead.
Removed; use useAuiState instead.
Removed the alias; use useLocalRuntime instead.
Security 1
Adds a primitive for rendering agent-described React UI from JSON using a consumer-provided component allowlist.
Deprecations 4
fromThreadMessageLike is now marked experimental and may change without notice.
generateId is now marked experimental and may change without notice.
hitlTool is deprecated in favor of humanTool, while compatibility aliases remain available.
humanTool replaces hitlTool as the preferred tool name, with compatibility aliases retained.
New APIs and options 51
ExternalThread adds assistant-transport props for loading, state, extras, resume, tool results, external state, tool calls, and attachments, plus importExternalState.
ToolInvocationTracker is exported from core internal.
AssistantModalPrimitive Trigger, Anchor, and Content now support render props.
ComposerPrimitive.Root now supports compact mode.
Quote selection now supports exclusions using data-aui-quote-selectable="false".
MCP toolkit entries can now be disabled.
MCP toolkit now supports prefixed tool names.
MCP toolkit tools can now be disabled.
The selection toolbar now supports opt-in quote regions.
MCP Apps metadata and host calls now accept an optional serverId for multi-MCP routing.
ThreadListItemMorePrimitive.Root adds sharedFocusGroup to extend keyboard focus handling into the menu, make it non-modal, and restore row focus on close.
Adds an isLoading prop so asynchronous completion sources can render a loading state.
Exported from the public API so developers can materialize a ThreadMessageLike without reaching into internals.
Exported from the public API so developers can generate IDs for hand-built messages without reaching into internals.
Adds minCommitMs to throttle committed reveal updates while preserving per-frame commits by default.
Bridges async completion sources into the synchronous Unstable_TriggerAdapter with debounced fetching and stale-request cancellation.
A compiler-runtime subpath now mirrors react/compiler-runtime's c export for compiled packages.
ExternalThread now provides an onRespondToToolApproval callback for handling tool approval responses.
respondToApproval now accepts optionId, resolving core approval behavior from the selected option kind.
External-store hosts can now provide tool-call timing through ThreadMessageLike.
Tool approval responses can record the selected option through optionId.
Tool approval requests can now include machine-readable options for allow-once, allow-always, reject-once, reject-always, and custom kinds.
Tool approvals can now record cancelled or expired terminal outcomes.
Tool calls now expose startedAt and optional completedAt epoch milliseconds, automatically populated during streaming.
The new hook reports mid-run output stalls using a configurable threshold and message content fingerprint.
The React shim exports useMemoCache with tap and React compiler-runtime behavior, including a React 18 polyfill.
The new hook returns elapsed tool-call milliseconds and updates once per second while the call is running.
Adds an optional branches adapter for retrieving sibling branches and switching the visible branch.
The smooth prop now accepts boolean or SmoothOptions for tunable text reveal behavior.
The smooth prop now accepts boolean or SmoothOptions for tunable text reveal behavior.
Adds terminal-style ArrowUp and ArrowDown history navigation for thread composer input while preserving drafts and yielding to other input behaviors.
Exports useSmooth and SmoothOptions publicly, adding tunable backlog draining, reveal intervals, and per-frame character limits.
Messages sent during a run are queued and processed once the run settles.
Queued messages can be rendered through ComposerPrimitive.Queue and QueueItemPrimitive APIs.
External-store adapters can opt into message queuing with a queue adapter built using createMessageQueue.
Adds externalTool for render-only generative toolkit entries.
useLangGraphRuntime and useLocalRuntime can opt into message queuing with this option.
Provides defineToolkit() from @assistant-ui/react for authoring permissive toolkits; its marker is stripped by the use generative compiler.
Adds permissive ToolkitDeclaration and ToolkitDeclarationDefinition types for authoring toolkits whose backend tools may declare description, parameters, or execute.
Tool-call parts in approval-requested state now expose approval metadata containing an id and optional automatic flag.
Adds a typed helper for mapping part types to group-key paths, with support for MCP app routing and inline reconstruction.
Tool components can acknowledge AI SDK v6 approval gates through a first-class prop without threading chatHelpers through application context.
Adds a message part containing a named component tree that supports streaming partial specs.
Adds the components.generativeUI option for composing generative UI rendering with MessagePrimitive.Parts.
Adds an unarchive option so callers can keep an archived thread archived when switching to it; the default remains true.
Adds an unarchive option so callers can keep an archived thread archived when switching through the item runtime.
Adds newline insertion on plain Enter for touch-primary devices while preserving existing submitMode behavior.
The default directive formatter is re-exported so downstream packages need not depend directly on @assistant-ui/core.
The directive formatter is re-exported so downstream packages need not depend directly on @assistant-ui/core.
The directive segment is re-exported so downstream packages need not depend directly on @assistant-ui/core.
The trigger item is re-exported so downstream packages need not depend directly on @assistant-ui/core.
Behavior and default changes 9
Attachment-add rejections are no longer logged per file to the console when the structured event already surfaces them.
ExternalThread edit composers now receive the attachment adapter.
Runs paused for tool approval are now persisted.
Clicking blank space in ComposerPrimitive.Root now focuses the composer input.
Thread list items support Up/Down navigation and Right navigation to an item's More button, with RTL mirroring; every item remains a Tab stop.
The kit approval bar now renders supplied options and can show an opt-in confirmation step describing persistent grants.
The ToolFallback trigger now renders tool-call duration when timing information is present.
defineToolkit and hitl markers move from @assistant-ui/next to @assistant-ui/react and are shipped across distributions as build-time no-op markers.
Inline groupBy functions are now safe to use because memoization uses a helper fingerprint or rebuilds the tree cheaply per render.
Tooling 1
aui-build now runs React Compiler over packages that depend on tap, allowing compiled hooks and components to work in tap resource renders.
Fixes and other changes 40
onError now reads live in-transit commands at error time instead of a stale render snapshot.
parentId is consumed once per run, preventing unrelated later runs from resending it.
Follow-up runs with empty command queues now no-op instead of throwing an error.
In-transit commands are marked delivered when a run completes successfully without state chunks.
Commands queued during resume runs are flushed by a follow-up run instead of remaining starved.
In-flight runs are aborted on unmount to prevent fetch leaks.
The adapter accept string is validated on every addAttachment entry point.
clearAttachments and reset now call adapter.remove for pending attachments.
Queue-adapter sends now stamp the thread head as parentId.
Failed sends are merged back into the draft with text, attachments, and quote preserved.
Duplicate message ids are deduplicated with a warning; the last occurrence wins instead of throwing.
Rejected file picker attachment additions are now handled.
Thread-list position is preserved when an on-demand fetch settles after a concurrent list call.
Controlled assistant-visible inputs remain synchronized after edits.
Attachments work without requiring a global File constructor.
Prevents instant auto-scroll from interrupting active top-anchored runs.
Transient part-type mismatches no longer throw during thread switches and unmount the app.
Part selectors should not throw; transient part-type mismatches are handled stably during React Ink rendering.
The top-anchor reserve is preserved between turns.
Cloud history now preserves user attachments.
MCP App host request errors now include error context.
providerMetadata now survives conversion on text, reasoning, and tool-call message parts.
Opening and closing a menu preserves focus on the thread row so the focus-visible highlight remains continuous.
Compiled context store hooks no longer skip subscriptions, preventing missed updates for developers using them.
Peer and dependency ranges were updated for @assistant-ui/tap 0.9, affecting compatible package configurations.
Typecheck regressions were resolved, preventing related type-checking failures for developers.
useSubscribable now builds on useSyncExternalStore so store reads remain visible to the React Compiler.
Empty running messages now emit the streaming indicator so the assistant slot shows loading feedback immediately after sending.
Scrollbar gutter compensation prevents collapsible animations from shifting centered content on classic scrollbars.
Preserves the original part type for reasoning parts instead of always returning type: "text".
Pointer interaction now clears pending bottom-scroll intent, preventing collapsible interactions from moving the thread to the bottom.
MCP app bridge messages now support the 2026-01-26 dialect so spec widgets initialize and receive tool results.
defineToolkit now works with plain runtime toolkits.
ExternalThreadQueueAdapter now lives in @assistant-ui/core while remaining re-exported from @assistant-ui/react.
Removes a transient requires-action flicker when tool calls reach the approval-responded state.
Distinguishes interrupt and pending tool calls using explicit interrupt or approval fields instead of an undefined result.
Resyncs displayed text during render when the part changes or streaming continuity breaks, preventing one frame of stale text after a thread switch.
Copy operations no longer throw when navigator.clipboard is unavailable or permission is denied.
External store synchronization removes message ids that disappeared, preventing phantom assistant siblings.
Thread initialization timing was fixed so scrollToBottomOnInitialize works reliably.
@assistant-ui/react 0.1288 changes
Breaking changes 19
Adds hierarchical adjacent grouping of message parts through a new primitive.
The CSS class aui-mention-chip is renamed to aui-directive-chip.
Mention data attributes are renamed from data-mention-* to data-directive-*.
The react-lexical mentionChip prop is renamed to directiveChip.
react-lexical MentionChipProvider is renamed to DirectiveChipProvider.
react-lexical mention node APIs are renamed to directive node APIs.
react-lexical MentionPlugin is renamed to DirectivePlugin.
Replaces action onSelect handlers with the Action primitive and onExecute prop.
Replaces the insertDirective onSelect form with the Directive primitive and formatter prop.
The renamed mention adapter accepts a categories option.
The renamed mention adapter accepts includeModelContextTools.
The renamed mention adapter accepts an items option.
The slash command adapter now returns adapter and action, with execute retained in the hook closure.
The tool-specific mention adapter hook is renamed to unstable_useMentionAdapter.
Adds a generic trigger-popover resource supporting multiple trigger characters.
Removes the aui-source export condition from package.json exports.
Removes makeInteractable and its related types.
Renames useInteractable to useAssistantInteractable for registration, with the hook returning an id.
Renames UseInteractableConfig to AssistantInteractableProps.
Deprecations 3
The legacy ToolGroup prop on Parts is deprecated but continues working for backwards compatibility.
The legacy adjacent-grouping component is deprecated but continues working for backwards compatibility.
The legacy top-level request-body spread remains supported for backward compatibility but will be removed in a future version.
New APIs and options 48
Accepts a user-supplied groupBy function to coalesce adjacent parts by key-path prefixes.
Exposes highlightIndex(index) on the TriggerPopover scope for programmatic highlighting.
Adds reload() to ThreadListRuntime and aui.threads() to refresh threads after asynchronous authentication completes.
composer.send() accepts a startRun flag through SendOptions.
Introduces a plugin protocol that decouples ComposerInput from mention-specific code.
Adds slash-command primitives for slash command support.
Adds trigger-popover primitives for building generic trigger interactions.
Adds an EditComposerRuntimeCore interface extending ComposerRuntimeCore.
EditComposerState exposes parentId for edit lineage.
EditComposerState exposes sourceId for edit lineage.
Adds the slash command adapter type.
Adds the slash command item type.
Adds a generic trigger adapter type supporting multiple trigger characters.
Adds a generic trigger category type for the trigger popover architecture.
Adds a generic trigger item type for the trigger popover architecture.
Adds a hook for building slash command adapters.
ThreadListRuntime now exposes getLoadThreadsPromise() as a public API.
useRemoteThreadListRuntime now accepts an initialThreadId option.
Adds per-id error tracking for interactable persistence.
Adds interactable state export for persistence.
Adds immediate synchronization for interactable persistence.
Adds interactable state import for persistence.
Adds per-id pending-state tracking for interactable persistence.
Adds a realtime voice adapter with VoiceOrb UI and mode and volume support.
All primitives now support render props for compatibility with the shadcn Base component library.
Adds a debounced persistence adapter for interactable state synchronization.
Adds callback-based context providers that inject computed text into the system prompt using current application state.
Adds a hook for reading and writing interactable state.
Adds a hook that derives per-property streaming completion status from tool-call arguments.
Adds a scope resource that generates update tools and injects a system prompt.
Adds a factory for registering AI-controllable UI interactables.
Adds selection support that marks an interactable as focused and surfaces it in the system prompt.
Adds a hook for registering AI-controllable UI interactables.
Adds a hotkey that sends with steer enabled and interrupts the current run.
Adds a steer flag to send messages while interrupting the current run.
Adds queueItem() for accessing queue items through composer methods.
Adds a composer primitive for rendering the queue list.
Adds queue state to the composer.
Adds a queue adapter for runtimes that support message queuing.
Adds clear with edit, reload, and cancel-run reasons for queue management.
Adds cursor-aware triggers, keyboard navigation, search, and Lexical rich editor support for mentions.
Adds a primitive for rendering removable queue items.
Adds a primitive for rendering steer queue items.
Adds a primitive for rendering text queue items.
Adds queue capability detection to runtime capabilities.
Adds the queueItem scope for queue item rendering.
Adds the SingleThreadList resource for developers to use.
Primitives now support a children API with part.toolUI, part.dataRendererUI, and MessagePrimitive.Quote.
Behavior and default changes 6
Dropped attachments are processed in parallel so multiple files appear together instead of one by one.
callSettings and config are now nested objects in the request body; the old top-level spread remains temporarily for backward compatibility.
Interactable persistence now automatically flushes when a component unregisters.
Interactables with the same name and different IDs receive separate update tools.
Auto-generated tools use partial schemas so AI sends only changed fields.
Routes thread.append through queue.enqueue when a queue adapter is present.
Fixes and other changes 12
TriggerPopover now synchronizes mouse hover with keyboard highlighting and accessibility state.
Dropdown menu primitives now support render props.
MessagePrimitive.Root now forwards viewport slack props.
The text-unchanged guard is bypassed when startRun is explicitly set.
EMPTY_THREAD_CORE.isLoading is now true to prevent a Welcome page flash during thread switching.
Remains enabled during runs when queue support is available.
Cancel, edit, and reload operations now clear the queue with the appropriate reason.
Prevents double-submit when ComposerPrimitive.Send is a submit button.
ActionBarMorePrimitive no longer disappears when ActionBarPrimitive.Root uses autohide="not-last" on non-last messages.
External message conversion no longer crashes when orphaned tool results lack a matching tool call.
Consecutive assistant snapshots no longer produce duplicate toolCallId parts during external message conversion.
Tool invocation argument stream rewrites recover safely and avoid premature closure for non-executable client tools.
@assistant-ui/react 0.1125 changes
Breaking changes 5
ResourceElementConstructor was renamed to Resource.
ResourceElement.type now uses Resource instead of ResourceFn.
toolUIs was renamed to tools.
The ToolUI API was removed.
Introduces the Toolkit API for developers using the technology.
Deprecations 1
All old context API hooks are now deprecated, so developers should avoid using them for new code.
New APIs and options 9
AI SDK v5 data parts are integrated into message content.
ThreadHistoryAdapter can store runConfig.
AssistantCloudThreads gains get for retrieving individual threads.
RemoteThreadListAdapter gains fetch for retrieving individual threads.
Adds a scroll lock hook for the reasoning component.
Introduces the AssistantTransport wire format for transporting assistant interactions.
Introduces useAssistantTransportState for managing assistant transport state.
ThreadMessageLike support was added.
Adds submittedFeedback to ThreadAssistantMessage.
Behavior and default changes 5
Commands can now be enqueued from onError and onCancel handlers.
Queued commands are canceled when an error occurs.
switchToThread now fetches and loads threads missing from the current list.
The technology now displays AI SDK errors, making these errors visible to developers or users.
submittedFeedback moved to metadata.
Fixes and other changes 5
Fixed LocalThreadRuntime deleting branches during message reloads.
The scroll-to-bottom button is now separate from autoScroll behavior.
The scroll-position check used by autoscroll was corrected.
Added support for submittedFeedback in the external message converter.
Fixes enqueueing a chunk into a readable stream that is closed or has been requested to be closed.