Skip to content

The Open Standard for Generative UI

Group & Display Interleaved Content (#916)

ABd88215f63a17
diff --git a/packages/react-headless/package.json b/packages/react-headless/package.json
index fa5eb69a9..56e412829 100644
--- a/packages/react-headless/package.json
+++ b/packages/react-headless/package.json
@@ -1,6 +1,6 @@
{
"name": "@openuidev/react-headless",
- "version": "0.9.4",
+ "version": "0.9.5",
"description": "Headless React primitives for AI chat — state management, streaming adapters for OpenAI and AG-UI, message format converters, and thread management for OpenUI generative UI apps",
"license": "MIT",
"type": "module",
diff --git a/packages/react-headless/src/stream/__tests__/processStreamedMessage.test.ts b/packages/react-headless/src/stream/__tests__/processStreamedMessage.test.ts
index f3c98b9aa..466b42368 100644
--- a/packages/react-headless/src/stream/__tests__/processStreamedMessage.test.ts
+++ b/packages/react-headless/src/stream/__tests__/processStreamedMessage.test.ts
@@ -105,3 +105,75 @@ describe("processStreamedMessage — TOOL_CALL_RESULT handling", () => {
expect(toolMessages[1]).toMatchObject({ toolCallId: "tc-2", content: "res-2" });
});
});
+
+describe("processStreamedMessage — interleaved output message items", () => {
+ it("splits a run with multiple message items into separate assistant messages in wire order", async () => {
+ // Per-section backend: prose → tool call → prose → tool call, each its own
+ // output message item — must reconstruct live the way reload rebuilds it.
+ const adapter = adapterFromEvents([
+ { type: EventType.TEXT_MESSAGE_START, messageId: "item-1", role: "assistant" },
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "item-1", delta: "Let me search. " },
+ { type: EventType.TOOL_CALL_START, toolCallId: "tc-1", toolCallName: "thesys_web_search" },
+ { type: EventType.TOOL_CALL_ARGS, toolCallId: "tc-1", delta: '{"q":"a"}' },
+ { type: EventType.TOOL_CALL_END, toolCallId: "tc-1" },
+ {
+ type: EventType.TOOL_CALL_RESULT,
+ toolCallId: "tc-1",
+ content: '{"hits":1}',
+ messageId: "out-1",
+ role: "tool",
+ },
+ { type: EventType.TEXT_MESSAGE_START, messageId: "item-2", role: "assistant" },
+ {
+ type: EventType.TEXT_MESSAGE_CONTENT,
+ messageId: "item-2",
+ delta: "Found it. Final answer.",
+ },
+ ]);
+
+ const created: Message[] = [];
+ const updatedById = new Map<string, Message>();
+
+ await processStreamedMessage({
+ response: new Response(""),
+ createMessage: (m) => created.push(m),
+ updateMessage: (m) => updatedById.set(m.id, m),
+ adapter,
+ });
+
+ await flush();
+
+ // Creation order preserves wire order: segment 1, its tool result, segment 2.
+ expect(created.map((m) => m.role)).toEqual(["assistant", "tool", "assistant"]);
+
+ const seg1 = created[0] as Message & { content?: string; toolCalls?: unknown[] };
+ const seg2 = created[2] as Message & { content?: string; toolCalls?: unknown[] };
+ const finalSeg1 = (updatedById.get(seg1.id) ?? seg1) as typeof seg1;
+ const finalSeg2 = (updatedById.get(seg2.id) ?? seg2) as typeof seg2;
+
+ expect(finalSeg1.content).toBe("Let me search. ");
+ expect(finalSeg1.toolCalls).toHaveLength(1);
+ expect(finalSeg2.content).toBe("Found it. Final answer.");
+ expect(finalSeg2.toolCalls ?? []).toHaveLength(0);
+ });
+
+ it("does not split when the same message item id starts twice", async () => {
+ const adapter = adapterFromEvents([
+ { type: EventType.TEXT_MESSAGE_START, messageId: "item-1", role: "assistant" },
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "item-1", delta: "Hello" },
+ { type: EventType.TEXT_MESSAGE_START, messageId: "item-1", role: "assistant" },
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "item-1", delta: " world" },
+ ]);
+
+ const created: Message[] = [];
+ await processStreamedMessage({
+ response: new Response(""),
+ createMessage: (m) => created.push(m),
+ updateMessage: () => {},
+ adapter,
+ });
+ await flush();
+
+ expect(created.filter((m) => m.role === "assistant")).toHaveLength(1);
+ });
+});
diff --git a/packages/react-headless/src/stream/adapters/openai-responses.ts b/packages/react-headless/src/stream/adapters/openai-responses.ts
index 486411721..a07860a3b 100644
--- a/packages/react-headless/src/stream/adapters/openai-responses.ts
+++ b/packages/react-headless/src/stream/adapters/openai-responses.ts
@@ -16,6 +16,8 @@ export const openAIResponsesAdapter = (): StreamProtocolAdapter => ({
const decoder = new TextDecoder();
// Map item_id → call_id so TOOL_CALL_ARGS can reference the correct toolCallId
const itemIdToCallId: Record<string, string> = {};
+ // The text output-item currently streaming.
+ let textItemId: string | null = null;
let buffer = "";
while (true) {
@@ -44,6 +46,7 @@ export const openAIResponsesAdapter = (): StreamProtocolAdapter => ({
// not declare it. Widen the type so we can branch on it below.
const item = event.item as typeof event.item | ResponseFunctionToolCallOutputItem;
if (item.type === "message" && item.role === "assistant") {
+ textItemId = item.id;
yield {
type: EventType.TEXT_MESSAGE_START,
messageId: item.id,
@@ -68,7 +71,7 @@ export const openAIResponsesAdapter = (): StreamProtocolAdapter => ({
yield {
type: EventType.TOOL_CALL_START,
toolCallId: item.id,
- toolCallName: "thesys_web_search",
+ toolCallName: "web_search",
};
} else if (item.type === "mcp_call") {
yield {
@@ -96,6 +99,17 @@ export const openAIResponsesAdapter = (): StreamProtocolAdapter => ({
}
case "response.output_text.delta":
+ // A delta for a not-yet-seen item id opens its message — covers
+ // backends that switch item id on the delta without a preceding
+ // `output_item.added` (idempotent when that event did fire).
+ if (event.item_id !== textItemId) {
+ textItemId = event.item_id;
+ yield {
+ type: EventType.TEXT_MESSAGE_START,
+ messageId: event.item_id,
+ role: "assistant",
+ };
+ }
yield {
type: EventType.TEXT_MESSAGE_CONTENT,
messageId: event.item_id,
diff --git a/packages/react-headless/src/stream/processStreamedMessage.ts b/packages/react-headless/src/stream/processStreamedMessage.ts
index 0be567fa0..e22f46291 100644
--- a/packages/react-headless/src/stream/processStreamedMessage.ts
+++ b/packages/react-headless/src/stream/processStreamedMessage.ts
@@ -42,6 +42,9 @@ export const processStreamedMessage = async ({
let isFirst = true;
+ // The wire message-item id whose text currently streams into currentMessage.
+ let currentTextItemId: string | null = null;
+
// Tool messages by toolCallId, so repeated TOOL_CALL_RESULTs for the same
// call UPDATE one message in place instead of duplicating it.
const toolMessagesByCallId = new Map<string, ToolMessage>();
@@ -153,13 +156,34 @@ export const processStreamedMessage = async ({
break;
}
- case EventType.TEXT_MESSAGE_START:
- // The optimistic id is kept regardless of `event.messageId` — swapping
- // ids mid-stream by deleting + re-creating the assistant message
- // breaks ordering when tool messages have already been appended
- // between the original create and this event (e.g. from
- // TOOL_CALL_RESULT). Persistence layers should map ids on save.
+ case EventType.TEXT_MESSAGE_START: {
+ // A DIFFERENT item id after content/tool calls have accumulated means
+ // the model opened a new output message item — interleaving prose with
+ // tool calls (several sections in one run). Split into a fresh assistant
+ // message so the live structure matches what reload reconstructs from
+ // storage
+ const startId = (event as { messageId?: string }).messageId ?? null;
+ const hasBody =
+ (currentMessage.content?.length ?? 0) > 0 || (currentMessage.toolCalls?.length ?? 0) > 0;
+ if (hasBody && startId !== currentTextItemId) {
+ if (rafId !== null) {
+ // Flush the pending update so the finished segment's final state
+ // lands before the next segment is created.
+ cancelAnimationFrame(rafId);
+ rafId = null;
+ if (!isFirst) updateMessage(currentMessage);
+ }
+ currentMessage = {
+ id: crypto.randomUUID(),
+ role: "assistant",
+ content: "",
+ toolCalls: [],
+ };
+ isFirst = true;
+ }
+ currentTextItemId = startId;
break;
+ }
case EventType.TOOL_CALL_RESULT: {
// Result landed → no longer executing / in flight.
diff --git a/packages/react-ui/src/components/AgentInterface/Thread.tsx b/packages/react-ui/src/components/AgentInterface/Thread.tsx
index 001b6ccd8..a03c77134 100644
--- a/packages/react-ui/src/components/AgentInterface/Thread.tsx
+++ b/packages/react-ui/src/components/AgentInterface/Thread.tsx
@@ -3,13 +3,17 @@ import {
MessageProvider,
useActiveDetailedView,
useArtifactList,
+ useArtifactRendererRegistry,
useThread,
useToolActivities,
} from "@openuidev/react-headless";
import clsx from "clsx";
-import React, { memo, useId, useRef } from "react";
+import React, { memo, useId, useMemo, useRef } from "react";
import { useLayoutContext } from "../../context/LayoutContext";
import { ScrollVariant, useScrollToBottom } from "../../hooks/useScrollToBottom";
+import { getLastAssistantMessageId, getMatchedRendererActivities } from "../../utils/messages";
+import { hasLangSyntax, separateContentAndContext } from "../../utils/sentinelParser";
+import { ToolCallTimeline, type TimelineStep } from "../ToolCall";
import {
DetailedViewOverlay,
DetailedViewPanel,
@@ -321,6 +325,179 @@ export const ThreadError = () => {
);
};
+/**
+ * Groups a message list into turns: a run of consecutive assistant/tool
+ * messages becomes ONE group; every other message (user, system, …) stands alone.
+ * `startIndex` is the group's position in the original list.
+ */
+function groupIntoTurns(messages: Message[]): { messages: Message[]; startIndex: number }[] {
+ const groups: { messages: Message[]; startIndex: number }[] = [];
+ let current: { messages: Message[]; startIndex: number } | null = null;
+ messages.forEach((message, i) => {
+ if (message.role === "assistant" || message.role === "tool") {
+ if (!current) {
+ current = { messages: [], startIndex: i };
+ groups.push(current);
+ }
+ current.messages.push(message);
+ } else {
+ current = null;
+ groups.push({ messages: [message], startIndex: i });
+ }
+ });
+ return groups;
+}
+
+/**
+ * A whole turn as one unit. Owned here rather than per-message
+ * so the tray is a single element keyed by the turn's first segment ({@link Messages})
+ */
+const InterleavedTurn = ({
+ segments,
+ allMessages,
+ assistantMessage: CustomAssistantMessage,
+ className,
+ isRunning,
+ lastAssistantId,
+}: {
+ segments: AssistantMessage[];
+ allMessages: Message[];
+ assistantMessage?: AssistantMessageComponent;
+ className?: string;
+ isRunning: boolean;
+ lastAssistantId: string | null;
+}) => {
+ const last = segments[segments.length - 1]!;
+ const turnLive = isRunning && lastAssistantId === last.id;
+
+ // One id-keyed pairing across every segment's tool calls (synthetic message).
+ const turnMessage = useMemo(
+ () => ({ ...segments[0]!, toolCalls: segments.flatMap((s) => s.toolCalls ?? []) }),
+ [segments],
+ );
+ const turnActivities = useToolActivities(turnMessage, allMessages);
+
+ const lastContent = separateContentAndContext(last.content ?? "").content;
+ const answer =
+ !turnLive || turnActivities.length === 0 || hasLangSyntax(lastContent) ? last : null;
+ const answerMessage = useMemo(() => (answer ? { ...answer, toolCalls: [] } : null), [answer]);
+
+ // Rows in run order: each non-answer segment's thinking prose, then its tools.
+ const steps = useMemo<TimelineStep[]>(() => {
+ const byCallId = new Map(turnActivities.map((a) => [a.toolCall.id, a]));
+ const rows: TimelineStep[] = [];
+ for (const seg of segments) {
+ if (seg.id !== answer?.id) {
+ const prose = separateContentAndContext(seg.content ?? "").content;
+ if (prose) rows.push({ type: "text", id: seg.id, text: prose });
+ }
+ for (const tc of seg.toolCalls ?? []) {
+ const activity = byCallId.get(tc.id);
+ if (activity) rows.push({ type: "activity", activity });
+ }
+ }
+ return rows;
+ }, [segments, turnActivities, answer?.id]);
+
+ // Matched renderers (artifact/search previews) render OUTSIDE the tray so
+ // they stay visible after it collapses.
+ const registry = useArtifactRendererRegistry();
+ const matched = getMatchedRendererActivities(registry, turnActivities);
+
+ // Hold the tray open until the answer's first tokens arrive. `answer` is
+ // `last` or null, so reuse the already-parsed `lastContent`.
+ const answerStarted = !!answer && lastContent.length > 0;
+
+ return (
+ <>
+ {turnActivities.length > 0 && (
+ <ToolCallTimeline
+ activities={turnActivities}
+ steps={steps}
+ isLast={turnLive}
+ forceDefault
+ awaitingResponse={turnLive && !answerStarted}
+ />
+ )}
+ {matched.map((activity) => (
+ <TimelineEntry
+ key={activity.id}
+ activity={activity}
+ isLast={turnLive}
+ fallbackToDefault={false}
+ />
+ ))}
+ {answer && answerMessage && (
+ <MessageProvider key={answer.id} message={answerMessage}>
+ {CustomAssistantMessage ? (
+ <CustomAssistantMessage
+ message={answerMessage}
+ isStreaming={isRunning && lastAssistantId === answer.id}
+ />
+ ) : (
+ <AssistantMessageContainer className={className}>
+ <AssistantMessageContent
+ message={answerMessage}
+ allMessages={allMessages}
+ isLast={isRunning && lastAssistantId === answer.id}
+ />
+ </AssistantMessageContainer>
+ )}
+ </MessageProvider>
+ )}
+ </>
+ );
+};
+
+/** Renders one turn (a group from {@link groupIntoTurns}). */
+const RenderGroup = ({
+ group,
+ allMessages,
+ assistantMessage: CustomAssistantMessage,
+ userMessage,
+ className,
+ isRunning,
+ lastAssistantId,
+}: {
+ group: Message[];
+ allMessages: Message[];
+ assistantMessage?: AssistantMessageComponent;
+ userMessage?: UserMessageComponent;
+ className?: string;
+ isRunning: boolean;
+ lastAssistantId: string | null;
+}) => {
+ // A group is either a run of assistant/tool messages or one standalone
+ // non-assistant message (user/system/…). The former is always one interleaved
+ // turn, which owns the tool-call timeline (it reads `last` for the answer, so
+ // a length-one assistant group works too); the latter renders on its own.
+ const assistants = group.filter((m): m is AssistantMessage => m.role === "assistant");
+ const message = group[0]!;
+
+ return assistants.length > 0 ? (
+ <InterleavedTurn
+ segments={assistants}
+ allMessages={allMessages}
+ assistantMessage={CustomAssistantMessage}
+ className={className}
+ isRunning={isRunning}
+ lastAssistantId={lastAssistantId}
+ />
+ ) : (
+ <MessageProvider key={message.id} message={message}>
+ <RenderMessage
+ message={message}
+ allMessages={allMessages}
+ assistantMessage={CustomAssistantMessage}
+ userMessage={userMessage}
+ isStreaming={isRunning && message.id === lastAssistantId}
+ isLast={message.id === lastAssistantId}
+ className={className}
+ />
+ </MessageProvider>
+ );
+};
+
export const Messages = ({
className,
loader,
@@ -336,32 +513,28 @@ export const Messages = ({
const isRunning = useThread((s) => s.isRunning);
const threadError = useThread((s) => s.threadError);
- // Scan for the last *assistant* message (not the last message index) so the
- // running shimmer survives trailing tool messages.
- let lastAssistantIndex = -1;
- for (let i = messages.length - 1; i >= 0; i--) {
- if (messages[i]?.role === "assistant") {
- lastAssistantIndex = i;
- break;
- }
- }
+ // Group the flat message list into turns ONCE per change; the arrays keep
+ // their identity across unrelated re-renders.
+ const groups = useMemo(() => groupIntoTurns(messages), [messages]);
+
+ // Id of the last *assistant* message (not the last message) so the running
+ // shimmer survives trailing tool messages.
+ const lastAssistantId = useMemo(() => getLastAssistantMessageId(messages), [messages]);
return (
<div className={clsx("openui-agent-thread-messages", className)}>
- {messages.map((message, i) => {
- return (
- <MessageProvider key={message.id} message={message}>
- <RenderMessage
- message={message}
- allMessages={messages}
- assistantMessage={assistantMessage}
- userMessage={userMessage}
- isStreaming={isRunning && i === lastAssistantIndex}
- isLast={i === lastAssistantIndex}
- />
- </MessageProvider>
- );
- })}
+ {groups.map((group) => (
+ <RenderGroup
+ key={group.messages[0]!.id}
+ group={group.messages}
+ allMessages={messages}
+ assistantMessage={assistantMessage}
+ userMessage={userMessage}
+ className={className}
+ isRunning={isRunning}
+ lastAssistantId={lastAssistantId}
+ />
+ ))}
{isRunning && <div>{loader}</div>}
{!isRunning && threadError && <ThreadError />}
</div>
diff --git a/packages/react-ui/src/components/AgentInterface/thread.scss b/packages/react-ui/src/components/AgentInterface/thread.scss
index 4394f28c0..58a7ff1e1 100644
--- a/packages/react-ui/src/components/AgentInterface/thread.scss
+++ b/packages/react-ui/src/components/AgentInterface/thread.scss
@@ -176,6 +176,7 @@ $thread-content-max-width: calc(
width: 100%;
height: 100%;
overflow: auto;
+ scrollbar-gutter: stable;
padding: cssUtils.$space-m 0 calc($bottom-mask-height + cssUtils.$space-m);
scroll-padding-top: calc($top-mask-height + cssUtils.$space-3xs);
scroll-padding-bottom: calc($bottom-mask-height + cssUtils.$space-m);
diff --git a/packages/react-ui/src/components/OpenUIChat/GenUIAssistantMessage.tsx b/packages/react-ui/src/components/OpenUIChat/GenUIAssistantMessage.tsx
index 1bd95c6c3..f36907ac6 100644
--- a/packages/react-ui/src/components/OpenUIChat/GenUIAssistantMessage.tsx
+++ b/packages/react-ui/src/components/OpenUIChat/GenUIAssistantMessage.tsx
@@ -1,25 +1,20 @@
"use client";
-import type { AssistantMessage, ToolActivity } from "@openuidev/react-headless";
-import {
- lookupArtifactRenderer,
- useArtifactRendererRegistry,
- useThread,
- useToolActivities,
-} from "@openuidev/react-headless";
+import type { AssistantMessage } from "@openuidev/react-headless";
+import { useThread } from "@openuidev/react-headless";
import type { ActionEvent, Library } from "@openuidev/react-lang";
import { BuiltinActionType, Renderer } from "@openuidev/react-lang";
import { useCallback, useMemo } from "react";
+import { getLastAssistantMessageId } from "../../utils/messages";
import {
separateContentAndContext,
wrapContent,
wrapContentWithHeader,
wrapContext,
} from "../../utils/sentinelParser";
-import { ToolCallTimeline } from "../ToolCall";
-import { TimelineEntry } from "../_shared/tool-renderer";
import { AssistantMessageContainer } from "./AssistantMessageContainer";
+/** Renders the OpenUI-Lang response for one assistant message. */
export const GenUIAssistantMessage = ({
message,
library,
@@ -32,25 +27,17 @@ export const GenUIAssistantMessage = ({
const processMessage = useThread((s) => s.processMessage);
const updateMessage = useThread((s) => s.updateMessage);
- const isStreaming = useMemo(() => {
- if (!isRunning) return false;
- for (let i = messages.length - 1; i >= 0; i--) {
- if (messages[i]?.role === "assistant") {
- return messages[i]?.id === message.id;
- }
- }
- return false;
- }, [isRunning, messages, message.id]);
+ const lastAssistantId = useMemo(() => getLastAssistantMessageId(messages), [messages]);
+ const isStreaming = isRunning && lastAssistantId === message.id;
- // Separate openui-lang code from persisted form state
- const {
- content: openuiCode,
- contextString,
- contentHeader,
- } = useMemo(() => {
- if (!message.content) return { content: null, contextString: null, contentHeader: undefined };
- return separateContentAndContext(message.content);
- }, [message.content]);
+ // Strip the inline sentinels and separate any persisted form-state.
+ const { content, contextString, contentHeader } = useMemo(
+ () =>
+ message.content
+ ? separateContentAndContext(message.content)
+ : { content: null, contextString: null, contentHeader: undefined },
+ [message.content],
+ );
const initialState = useMemo(() => {
if (!contextString) return undefined;
@@ -64,34 +51,19 @@ export const GenUIAssistantMessage = ({
}
}, [contextString]);
- // One id-keyed pairing of calls↔results with real status (streaming /
- // executing / complete / error).
- const activities = useToolActivities(message, messages);
-
- // The "Behind the scenes" timeline shows the RAW request/response for EVERY
- // tool call (forceDefault), so matched tools (artifacts, web search) stay
- // inspectable there. Matched renderers additionally render their rich preview
- // OUTSIDE the timeline so it's always visible and its detailed-view panel
- // stays mounted even after the message completes.
- const registry = useArtifactRendererRegistry();
- const isMatched = (a: ToolActivity) =>
- !!(registry && lookupArtifactRenderer(registry, a.toolName));
- const matchedActivities = activities.filter(isMatched);
-
// Persist form state into the inline-wrapped message content. The original
// header line (which may include `libraryVersion` and telemetry tags emitted
// by the backend) is reused so attrs survive the persist round-trip.
const handleStateUpdate = useCallback(
(state: Record<string, any>) => {
- const code = openuiCode ?? "";
const hasState = Object.keys(state).length > 0;
- const contentPart = wrapContentWithHeader(code, contentHeader);
+ const contentPart = wrapContentWithHeader(content ?? "", contentHeader);
const fullMessage = hasState
? contentPart + wrapContext(JSON.stringify([state]))
: contentPart;
updateMessage({ ...message, content: fullMessage });
},
- [updateMessage, message, openuiCode, contentHeader],
+ [updateMessage, message, content, contentHeader],
);
// Build LLM-friendly message from action + form state, then dispatch
@@ -124,34 +96,16 @@ export const GenUIAssistantMessage = ({
return (
<AssistantMessageContainer>
- {activities.length > 0 && (
- // Raw request/response for ALL tool calls, collapsed by default.
- <ToolCallTimeline
- activities={activities}
- isLast={isStreaming}
- forceDefault
- awaitingResponse={isStreaming && !message.content}
+ {content && (
+ <Renderer
+ response={content}
+ library={library}
+ isStreaming={isStreaming}
+ onAction={handleAction}
+ onStateUpdate={handleStateUpdate}
+ initialState={initialState}
/>
)}
- {matchedActivities.map((activity) => (
- // Matched renderers (artifact previews, web search) — always visible.
- // No raw fallback here: the forceDefault timeline above already shows the
- // raw card, so a null-parser renderer shouldn't double it.
- <TimelineEntry
- key={activity.id}
- activity={activity}
- isLast={isStreaming}
- fallbackToDefault={false}
- />
- ))}
- <Renderer
- response={openuiCode}
- library={library}
- isStreaming={isStreaming}
- onAction={handleAction}
- onStateUpdate={handleStateUpdate}
- initialState={initialState}
- />
</AssistantMessageContainer>
);
};
diff --git a/packages/react-ui/src/components/ToolCall/TimelineToolCard.tsx b/packages/react-ui/src/components/ToolCall/TimelineToolCard.tsx
index 1e3478f49..14b0cdf79 100644
--- a/packages/react-ui/src/components/ToolCall/TimelineToolCard.tsx
+++ b/packages/react-ui/src/components/ToolCall/TimelineToolCard.tsx
@@ -1,15 +1,42 @@
import type { ToolActivity } from "@openuidev/react-headless";
-import { CircleDot } from "lucide-react";
+import { ChevronDown } from "lucide-react";
import { memo } from "react";
-import { Collapsible } from "../_shared/Collapsible";
-import { ToolCall } from "./ToolCallPrimitives";
+import { SourceIcon } from "./SourceIcon";
+import { ToolCall, toolIcon } from "./ToolCallPrimitives";
+import { extractToolSources, type ToolResultSource } from "./toolSources";
+
+/** Favicon + title rows for the links a tool's result carries (see
+ * {@link extractToolSources} — per-tool formats live in one registry). */
+const ToolSources = ({ sources }: { sources: ToolResultSource[] }) => {
+ return (
+ <div className="openui-tool-call__sources">
+ {sources.map((source) => (
+ <a
+ key={source.url}
+ href={source.url}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="openui-tool-call__source"
+ >
+ <span className="openui-tool-call__source-left">
+ <SourceIcon src={`https://www.google.com/s2/favicons?domain=${source.host}&sz=64`} />
+ <span className="openui-tool-call__source-title">{source.title}</span>
+ </span>
+ <span className="openui-tool-call__source-desc">{source.siteName}</span>
+ </a>
+ ))}
+ </div>
+ );
+};
/**
- * Timeline-shaped composition of the compound {@link ToolCall} parts — the
- * molded `StatusStep` + `TimelineItem` (dot + connector). The running shimmer
- * is `(streaming|executing) && isLast`, derived from the lifecycle status via
- * the parts' `data-spin`, not a separate `isThinking` flag. `ToolCall.Root` is
- * the single `.openui-tool-call` container, so we compose *inside* it.
+ * Timeline-shaped composition of the compound {@link ToolCall} parts: one row —
+ * tool glyph, status label, chevron — that expands into either the result's
+ * sources or a SINGLE block holding the request and the response together. The
+ * running affordances (glyph blink, label shimmer) are
+ * `(streaming|executing) && isLast`, derived from the lifecycle status rather
+ * than a separate `isThinking` flag. `ToolCall.Root` is the single
+ * `.openui-tool-call` container, so we compose *inside* it.
*
* @category Components
*/
@@ -24,9 +51,24 @@ export const TimelineToolCard = memo(function TimelineToolCard({
* so a closed-args call with no result doesn't animate forever after the run ends. */
isRunning?: boolean;
}) {
+ const Icon = toolIcon(activity.toolName, activity.status);
+ const running =
+ (activity.status === "streaming" || activity.status === "executing") && isLast && isRunning;
+ // Links speak for themselves; the raw block would only repeat them. A failure
+ // always falls back to it, since that's where the error text lives.
+ const sources =
+ typeof activity.result === "string" && !activity.isError
+ ? extractToolSources(activity.toolName, activity.result)
+ : [];
+
return (
- <ToolCall.Root activity={activity} isLast={isLast} running={isRunning}>
- <div className="openui-tool-call__title-row">
+ <ToolCall.Root
+ activity={activity}
+ isLast={isLast}
+ running={isRunning}
+ defaultOpen={activity.isError}
+ >
+ <ToolCall.Trigger className="openui-tool-call__title-row">
<ToolCall.StatusIcon
render={(_state, props) => (
<span
@@ -35,12 +77,12 @@ export const TimelineToolCard = memo(function TimelineToolCard({
}`}
data-status={props["data-status"] as string}
>
- <CircleDot size={14} className="openui-tool-call__icon" />
+ <Icon size={14} className="openui-tool-call__icon" />
</span>
)}
/>
<ToolCall.StatusText
- render={(state, props) => (
+ render={(_state, props) => (
<span
// Announce tool-call status transitions (Calling → Running →
// Called/failed) to assistive tech; only changes are spoken, so
@@ -48,58 +90,34 @@ export const TimelineToolCard = memo(function TimelineToolCard({
role="status"
aria-live="polite"
className={`openui-tool-call__name${
- (state.status === "streaming" || state.status === "executing") &&
- isLast &&
- isRunning
- ? " openui-tool-call__name--shimmer"
- : ""
+ running ? " openui-tool-call__name--shimmer" : ""
}`}
>
{props["children"] as string}
</span>
)}
/>
- </div>
+ <ChevronDown size={14} className="openui-tool-call__chevron" />
+ </ToolCall.Trigger>
- <div
- className={`openui-tool-call__connector${
- isLast ? " openui-tool-call__connector--last" : ""
- }`}
- >
- <div className="openui-tool-call__args-block">
- {/* request → typed input, response → paired result, both collapsible */}
- <Collapsible
- label="Tool Request"
- labelLoading={`Sending request to ${activity.toolName}...`}
- loading={isRunning && isLast && activity.status === "streaming"}
- >
- <ToolCall.Parameters
- render={(_s, p) => (
- <pre className="openui-tool-code-block__code">{p["children"] as string}</pre>
+ <ToolCall.Content className="openui-tool-call__content">
+ {sources.length > 0 ? (
+ <ToolSources sources={sources} />
+ ) : (
+ // Request and response share one block; ToolCall.Result renders
+ // nothing until a result or error lands.
+ <pre className="openui-tool-call__block openui-tool-code-block__code">
+ <ToolCall.Parameters render={(_s, p) => <code>{p["children"] as string}</code>} />
+ <ToolCall.Result
+ render={(s, p) => (
+ <code
+ className={s.isError ? "openui-tool-code-block__code--error" : undefined}
+ >{`\n\n${p["children"] as string}`}</code>
)}
/>
- </Collapsible>
- {/* ToolCall.Result returns null until a result/error lands, so the
- response collapsible only appears once it does. */}
- <ToolCall.Result
- render={(s, p) => (
- <Collapsible
- label="Tool Response"
- labelLoading={`Awaiting response from ${activity.toolName}...`}
- loading={isRunning && isLast && activity.status === "executing"}
- >
- <pre
- className={`openui-tool-code-block__code${
- s.isError ? " openui-tool-code-block__code--error" : ""
- }`}
- >
- {p["children"] as string}
- </pre>
- </Collapsible>
- )}
- />
- </div>
- </div>
+ </pre>
+ )}
+ </ToolCall.Content>
</ToolCall.Root>
);
});
diff --git a/packages/react-ui/src/components/ToolCall/ToolCallPrimitives.tsx b/packages/react-ui/src/components/ToolCall/ToolCallPrimitives.tsx
index c49347f0f..06fb72332 100644
--- a/packages/react-ui/src/components/ToolCall/ToolCallPrimitives.tsx
+++ b/packages/react-ui/src/components/ToolCall/ToolCallPrimitives.tsx
@@ -1,6 +1,6 @@
import type { ToolActivity, ToolCallStatus } from "@openuidev/react-headless";
import clsx from "clsx";
-import { AlertCircle, Loader2, SquareCode } from "lucide-react";
+import { AlertCircle, Blocks, Globe, ImageIcon, SquareCode } from "lucide-react";
import { createContext, createElement, useContext, useId, useState, type ReactNode } from "react";
/**
@@ -138,12 +138,17 @@ function resolveLegacyResponse(activity: ToolActivity): unknown {
return value != null ? value : undefined;
}
-const STATUS_ICON: Record<ToolCallStatus, typeof SquareCode> = {
- streaming: Loader2,
- executing: Loader2,
- complete: SquareCode,
- error: AlertCircle,
-};
+// Built-in tool families that get their own glyph. Matched on the name
+const TOOL_ICONS: { match: RegExp; icon: typeof SquareCode }[] = [
+ { match: /image[_-]?search/i, icon: ImageIcon },
+ { match: /web[_-]?search/i, icon: Globe },
+ { match: /artifact|generate[_-]?report/i, icon: Blocks },
+];
+
+export function toolIcon(toolName: string, status: ToolCallStatus): typeof SquareCode {
+ if (status === "error") return AlertCircle;
+ return TOOL_ICONS.find((entry) => entry.match.test(toolName))?.icon ?? SquareCode;
+}
// ── Parts ──
@@ -189,7 +194,7 @@ function Root({
const StatusIcon = ({ render, className }: PartProps<{ status: ToolCallStatus }>) => {
const { activity, isLast, running } = useToolCall();
const spin = isRunning(activity.status) && isLast && running;
- const Icon = STATUS_ICON[activity.status];
+ const Icon = toolIcon(activity.toolName, activity.status);
return renderPart(
render,
"span",
diff --git a/packages/react-ui/src/components/ToolCall/ToolCallTimeline.tsx b/packages/react-ui/src/components/ToolCall/ToolCallTimeline.tsx
index 405330f06..980ee84f4 100644
--- a/packages/react-ui/src/components/ToolCall/ToolCallTimeline.tsx
+++ b/packages/react-ui/src/components/ToolCall/ToolCallTimeline.tsx
@@ -1,13 +1,64 @@
import { useThread, type ToolActivity } from "@openuidev/react-headless";
import clsx from "clsx";
import { ChevronDown, ChevronUp } from "lucide-react";
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { MarkDownRenderer } from "../MarkDownRenderer";
import { TimelineEntry } from "../_shared/tool-renderer/TimelineEntry";
import type { ToolDetailedViewPanel } from "../_shared/tool-renderer/ToolActivityRenderer";
import { defaultLabel } from "./ToolCallPrimitives";
+/**
+ * One display row of the timeline: a tool activity, or a thinking-text step
+ * (prose the model emitted alongside its tool calls), in run order.
+ */
+export type TimelineStep =
+ { type: "text"; id: string; text: string } | { type: "activity"; activity: ToolActivity };
+
+const stepKey = (step: TimelineStep) =>
+ step.type === "text" ? `text-${step.id}` : step.activity.id;
+
+const TimelineStepRow = ({
+ step,
+ isLast,
+ detailedViewPanel,
+ forceDefault,
+}: {
+ step: TimelineStep;
+ isLast: boolean;
+ detailedViewPanel?: ToolDetailedViewPanel;
+ forceDefault: boolean;
+}) => {
+ if (step.type === "text") {
+ return (
+ <div className="openui-tool-call-timeline__text-step">
+ <MarkDownRenderer
+ textMarkdown={step.text}
+ className="openui-tool-call-timeline__text-step-body"
+ />
+ </div>
+ );
+ }
+ return (
+ <TimelineEntry
+ activity={step.activity}
+ isLast={isLast}
+ detailedViewPanel={detailedViewPanel}
+ forceDefault={forceDefault}
+ />
+ );
+};
+
const REVEAL_INTERVAL = 600;
+const NO_FADE: { top: boolean; bottom: boolean } = { top: false, bottom: false };
+
+// scrollHeight and clientHeight are both rounded, and rows have fractional
+// heights (line-height on a 14px body), so a list that fits can still report a
+// pixel or two of overflow. Only a gap wider than that — and, per edge, a real
+// scroll offset — counts, or a short run fades an edge it never scrolls past.
+const OVERFLOW_SLACK = 8;
+const EDGE_SLACK = 4;
+
/** Visually hidden but available to screen readers; inline so we don't depend on
* scss (a sibling agent owns the stylesheet). */
const VISUALLY_HIDDEN = {
@@ -25,11 +76,12 @@ const VISUALLY_HIDDEN = {
const isRunning = (a: ToolActivity) => a.status === "streaming" || a.status === "executing";
/**
- * The "Working… / Behind the scenes" timeline wrapper, driven by
- * {@link ToolActivity}[] from `useToolActivities`. Reveals the run's activities
- * one-by-one, holds the compact card open across the tool-result → first-token
- * gap (`awaitingResponse`), and lets a manual close stick for the rest of the
- * run. "Running" is read from each activity's status, not an `isThinking` prop.
+ * The "Working / Behind the scenes" timeline wrapper, driven by
+ * {@link ToolActivity}[] from `useToolActivities`. Reveals the run's steps
+ * one-by-one and keeps every revealed one on screen, holds the tray open across
+ * the tool-result → first-token gap (`awaitingResponse`), and lets a manual
+ * close stick for the rest of the run. "Running" is read from each activity's
+ * status, not an `isThinking` prop.
*
* (Animations are CSS-only — framer-motion is intentionally not a dependency.)
*
@@ -37,12 +89,15 @@ const isRunning = (a: ToolActivity) => a.status === "streaming" || a.status ===
*/
export function ToolCallTimeline({
activities,
+ steps,
isLast = false,
detailedViewPanel,
forceDefault = false,
awaitingResponse = false,
}: {
activities: ToolActivity[];
+ /** Ordered display rows interleaving thinking text with tool activities */
+ steps?: TimelineStep[];
isLast?: boolean;
detailedViewPanel?: ToolDetailedViewPanel;
/** Render every row as the raw default card (e.g. so matched tools' raw
@@ -52,6 +107,8 @@ export function ToolCallTimeline({
* gap instead of collapsing the instant the last result lands. */
awaitingResponse?: boolean;
}) {
+ const displaySteps: TimelineStep[] =
+ steps ?? activities.map((activity) => ({ type: "activity", activity }));
// "Thinking" while the last activity is still running (or its results are in
// but the response hasn't started), on the live message, and the thread is
// actually running — so a closed-args call with no result stops showing
@@ -66,10 +123,10 @@ export function ToolCallTimeline({
const [expanded, setExpanded] = useState(false);
// A user close mid-run sticks until the next run.
const [userCollapsed, setUserCollapsed] = useState(false);
- // Live message reveals from the first activity; historical reveals them all so
+ // Live message reveals from the first step; historical reveals them all so
// it never animates "Working…" on mount.
const [revealedCount, setRevealedCount] = useState(() =>
- isLast ? 1 : Math.max(activities.length, 1),
+ isLast ? 1 : Math.max(displaySteps.length, 1),
);
// Reset on each run edge: a rising `thinking` restarts the reveal and clears
@@ -80,47 +137,134 @@ export function ToolCallTimeline({
setRevealedCount(1);
setExpanded(false);
setUserCollapsed(false);
+ followRef.current = true;
} else if (prevThinking.current && !thinking) {
setExpanded(false);
- setRevealedCount(activities.length);
+ setRevealedCount(displaySteps.length);
}
prevThinking.current = thinking;
- }, [thinking, activities.length]);
+ }, [thinking, displaySteps.length]);
- // Advance the reveal once the current activity's args have closed (left
- // "streaming"); only the live message reveals incrementally.
- const revealingActivity = activities[revealedCount - 1];
- const currentReady = revealingActivity ? revealingActivity.status !== "streaming" : true;
+ // The items list is height-capped (see toolCall.scss) and scrolls
+ // internally. While the run is live, SMOOTHLY follow the newest row as
+ // content streams in — unless the user scrolled up to read an earlier one.
+ const itemsRef = useRef<HTMLDivElement | null>(null);
+ const followRef = useRef(true);
+ const distanceFromBottom = (el: HTMLElement) => el.scrollHeight - el.scrollTop - el.clientHeight;
+
+ const [fade, setFade] = useState(NO_FADE);
+ const measureEdges = useCallback(() => {
+ const el = itemsRef.current;
+ const next =
+ el && el.scrollHeight - el.clientHeight > OVERFLOW_SLACK
+ ? { top: el.scrollTop > EDGE_SLACK, bottom: distanceFromBottom(el) > EDGE_SLACK }
+ : NO_FADE;
+ setFade((prev) => (prev.top === next.top && prev.bottom === next.bottom ? prev : next));
+ }, []);
+ // Measured on every render of THIS component, which covers rows streaming in —
+ // but a row expanding or collapsing is the child's own state, so the list can
+ // grow past its cap and drop back under it without the timeline re-rendering
+ // at all. Observing the element covers that: its box is content-sized until
+ // the cap, so it changes on the way in and on the way back out.
+ const observerRef = useRef<ResizeObserver | null>(null);
+ const attachItems = useCallback(
+ (el: HTMLDivElement | null) => {
+ itemsRef.current = el;
+ observerRef.current?.disconnect();
+ observerRef.current = null;
+ if (!el || typeof ResizeObserver === "undefined") return;
+ const observer = new ResizeObserver(() => measureEdges());
+ observer.observe(el);
+ observerRef.current = observer;
+ },
+ [measureEdges],
+ );
+ useEffect(() => () => observerRef.current?.disconnect(), []);
+ useLayoutEffect(() => {
+ measureEdges();
+ });
+
+ const itemsClassName = clsx("openui-behind-the-scenes__items", {
+ "openui-behind-the-scenes__items--fade-top": fade.top,
+ "openui-behind-the-scenes__items--fade-bottom": fade.bottom,
+ });
+
+ const handleItemsScroll = useCallback(() => {
+ const el = itemsRef.current;
+ if (el && distanceFromBottom(el) < 24) followRef.current = true;
+ measureEdges();
+ }, [measureEdges]);
+ const handleItemsWheel = useCallback((e: React.WheelEvent) => {
+ if (e.deltaY < 0) followRef.current = false;
+ }, []);
+ const handleItemsTouchMove = useCallback(() => {
+ const el = itemsRef.current;
+ if (el && distanceFromBottom(el) >= 24) followRef.current = false;
+ }, []);
+
+ useLayoutEffect(() => {
+ if (!thinking || !followRef.current) return;
+ const el = itemsRef.current;
+ if (!el || distanceFromBottom(el) < 1) return;
+ const reduceMotion =
+ typeof window !== "undefined" &&
+ window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+ el.scrollTo({ top: el.scrollHeight, behavior: reduceMotion ? "auto" : "smooth" });
+ });
+
+ // Advance the reveal once the current step is ready — an activity whose args
+ // have closed (left "streaming"); text steps are always ready. Only the live
+ // message reveals incrementally.
+ const revealingStep = displaySteps[revealedCount - 1];
+ const currentReady =
+ !revealingStep || revealingStep.type === "text"
+ ? true
+ : revealingStep.activity.status !== "streaming";
useEffect(() => {
- if (isLast && revealedCount < activities.length && currentReady) {
+ if (isLast && revealedCount < displaySteps.length && currentReady) {
const t = setTimeout(() => setRevealedCount((c) => c + 1), REVEAL_INTERVAL);
return () => clearTimeout(t);
}
return undefined;
- }, [isLast, activities.length, revealedCount, currentReady]);
+ }, [isLast, displaySteps.length, revealedCount, currentReady]);
+
+ // Robustness: once the thread stops running, reveal everything. The
+ // incremental reveal only advances while `isLast`, so a run that ends
+ // mid-reveal (or a tray that mounted after `thinking` already fell) would
+ // otherwise stay stuck showing "Working…". This is independent of the
+ // rising/falling `thinking` edge, so it settles regardless of mount timing.
+ useEffect(() => {
+ if (!isThreadRunning && revealedCount < displaySteps.length) {
+ setRevealedCount(displaySteps.length);
+ }
+ }, [isThreadRunning, revealedCount, displaySteps.length]);
if (activities.length === 0) return null;
- const revealing = revealedCount < activities.length;
+ const revealing = revealedCount < displaySteps.length;
const showCompact = (thinking || revealing) && !expanded && !userCollapsed;
const isOpen = expanded || showCompact;
- const current = activities[Math.min(revealedCount - 1, activities.length - 1)]!;
+ const current = displaySteps[Math.min(revealedCount - 1, displaySteps.length - 1)]!;
// Persistent live announcement reflecting the current step's status — driven by
// the same fallback the primitives use so SRs hear status changes as content
// updates (the keyed reveal wrapper remounts and never announces on its own).
- const liveLabel = current.statusMessage ?? defaultLabel(current.status, current.toolName);
+ const liveLabel =
+ current.type === "text"
+ ? current.text
+ : (current.activity.statusMessage ??
+ defaultLabel(current.activity.status, current.activity.toolName));
// Once settled, surface a failure count on the toggle so errors aren't hidden
// behind a collapsed "Behind the scenes".
const settled = !thinking && !revealing;
const failedCount = settled ? activities.filter((a) => a.status === "error").length : 0;
- const toggleLabel =
- thinking || revealing
- ? "Working..."
- : failedCount > 0
- ? `Behind the scenes · ${failedCount} failed`
- : "Behind the scenes";
+ const working = thinking || revealing;
+ const toggleLabel = working
+ ? "Working"
+ : failedCount > 0
+ ? `Behind the scenes · ${failedCount} failed`
+ : "Behind the scenes";
return (
<div className="openui-behind-the-scenes">
@@ -143,12 +287,20 @@ export function ToolCallTimeline({
}
}}
>
+ <span
+ className={clsx("openui-behind-the-scenes__toggle-label", {
+ // While the run is live the label itself shimmers, matching the
+ // running tool rows below it.
+ "openui-behind-the-scenes__toggle-label--shimmer": working,
+ })}
+ >
+ {toggleLabel}
+ </span>
{isOpen ? (
<ChevronUp size={14} className="openui-behind-the-scenes__toggle-icon" />
) : (
<ChevronDown size={14} className="openui-behind-the-scenes__toggle-icon" />
)}
- {toggleLabel}
</button>
{isLast && !expanded && (
@@ -159,32 +311,52 @@ export function ToolCallTimeline({
inert={!showCompact}
>
<div className="openui-behind-the-scenes__compact-inner">
- <div className="openui-behind-the-scenes__items">
- {/* key changes per reveal → remounts → re-triggers the CSS fade-in */}
- <div
- key={revealedCount}
- className="openui-behind-the-scenes__reveal-item"
- style={{ width: "100%" }}
- >
- <TimelineEntry
- activity={current}
- isLast
- detailedViewPanel={detailedViewPanel}
- forceDefault={forceDefault}
- />
- </div>
+ {/* All revealed steps ACCUMULATE (scrollable past the cap) — each
+ new step appends and only IT animates in (keyed by stepKey, so
+ prior rows stay mounted). Showing one card at a time here made
+ the tray look like it reopened on every step. */}
+ <div
+ className={itemsClassName}
+ ref={attachItems}
+ onScroll={handleItemsScroll}
+ onWheel={handleItemsWheel}
+ onTouchMove={handleItemsTouchMove}
+ >
+ {/* The run accumulates: every revealed step stays on screen and only
+ the newest is `isLast`, so just that one shimmers and blinks.
+ Keyed per step, so each row plays the fade-in once, on mount. */}
+ {displaySteps.slice(0, revealedCount).map((step, idx) => (
+ <div
+ key={stepKey(step)}
+ className="openui-behind-the-scenes__reveal-item"
+ style={{ width: "100%" }}
+ >
+ <TimelineStepRow
+ step={step}
+ isLast={idx === revealedCount - 1}
+ detailedViewPanel={detailedViewPanel}
+ forceDefault={forceDefault}
+ />
+ </div>
+ ))}
</div>
</div>
</div>
)}
{expanded && (
- <div className="openui-behind-the-scenes__items">
- {activities.map((a, idx) => (
- <div key={a.id} style={{ width: "100%" }}>
- <TimelineEntry
- activity={a}
- isLast={isLast && idx === activities.length - 1}
+ <div
+ className={itemsClassName}
+ ref={attachItems}
+ onScroll={handleItemsScroll}
+ onWheel={handleItemsWheel}
+ onTouchMove={handleItemsTouchMove}
+ >
+ {displaySteps.map((step, idx) => (
+ <div key={stepKey(step)} style={{ width: "100%" }}>
+ <TimelineStepRow
+ step={step}
+ isLast={isLast && idx === displaySteps.length - 1}
detailedViewPanel={detailedViewPanel}
forceDefault={forceDefault}
/>
diff --git a/packages/react-ui/src/components/ToolCall/index.ts b/packages/react-ui/src/components/ToolCall/index.ts
index 75c6f44f0..450bf8978 100644
--- a/packages/react-ui/src/components/ToolCall/index.ts
+++ b/packages/react-ui/src/components/ToolCall/index.ts
@@ -6,5 +6,6 @@ export { ToolCallComponent, type ToolCallProps } from "./ToolCall";
export { DefaultToolCard } from "./DefaultToolCard";
export { SourceIcon } from "./SourceIcon";
export { TimelineToolCard } from "./TimelineToolCard";
-export { ToolCall, defaultLabel, prettyResult, useToolCall } from "./ToolCallPrimitives";
-export { ToolCallTimeline } from "./ToolCallTimeline";
+export { ToolCall, defaultLabel, prettyResult, toolIcon, useToolCall } from "./ToolCallPrimitives";
+export { ToolCallTimeline, type TimelineStep } from "./ToolCallTimeline";
+export { extractToolSources, type ToolResultSource } from "./toolSources";
diff --git a/packages/react-ui/src/components/ToolCall/toolCall.scss b/packages/react-ui/src/components/ToolCall/toolCall.scss
index 1d730d324..b9e9f9535 100644
--- a/packages/react-ui/src/components/ToolCall/toolCall.scss
+++ b/packages/react-ui/src/components/ToolCall/toolCall.scss
@@ -1,39 +1,74 @@
@use "../../cssUtils" as cssUtils;
+// A $bright highlight sweeping across a $base bed of text, both clipped to the
+// glyphs. The transparent fill is required: `background-clip: text` only clips
+// the background, so an opaque -webkit-text-fill-color hides it entirely.
+@mixin text-shimmer($base, $bright, $duration: 3s) {
+ display: inline-block;
+ background-image:
+ linear-gradient(90deg, transparent 40%, $bright 50%, transparent 60%),
+ linear-gradient($base, $base);
+ // Keep these relative to the label: at 3x, the 20%-wide band is 60% of it at
+ // any length and clears both edges at the ends of its travel — a band still
+ // on screen when the animation loops reads as a jump.
+ background-size:
+ 300% 100%,
+ 100% 100%;
+ background-repeat: no-repeat, no-repeat;
+ -webkit-background-clip: text;
+ background-clip: text;
+ -webkit-text-fill-color: transparent;
+ animation: openui-tool-code-shimmer $duration linear infinite;
+}
+
+// Keyboard focus ring for the button-reset elements (which strip UA chrome).
+@mixin focus-ring {
+ &:focus-visible {
+ outline: 2px solid cssUtils.$border-interactive-emphasis;
+ outline-offset: cssUtils.$space-3xs;
+ }
+}
+
// ── "Behind the scenes" wrapper ──
.openui-behind-the-scenes {
display: flex;
flex-direction: column;
align-items: flex-start;
- gap: cssUtils.$space-m;
+ gap: cssUtils.$space-s;
width: 100%;
+ // Closes the whole run off from the answer that follows it.
+ padding-block-end: cssUtils.$space-m;
+ margin-block-end: cssUtils.$space-m;
+ border-block-end: 1px solid cssUtils.$border-default;
&__toggle {
@include cssUtils.button-reset;
display: flex;
align-items: center;
- gap: cssUtils.$space-m;
- padding: cssUtils.$space-2xs cssUtils.$space-s;
- border-radius: cssUtils.$radius-m;
- @include cssUtils.typography(label, small-heavy);
- color: cssUtils.$text-neutral-primary;
+ gap: cssUtils.$space-s;
+ // Flush with the message content — the tray carries no chrome of its own.
+ padding: 0;
+ @include cssUtils.typography(body, small);
+ color: cssUtils.$text-neutral-secondary;
cursor: pointer;
background-color: transparent;
+ text-align: start;
- &:not(:disabled):hover {
- background-color: cssUtils.$sunk;
- }
+ // button-reset strips chrome, so restore a visible keyboard focus ring.
+ @include focus-ring;
- &:not(:disabled):active {
- background-color: cssUtils.$sunk;
+ &:hover .openui-behind-the-scenes__toggle-label {
+ color: cssUtils.$text-neutral-primary;
}
+ }
- // button-reset strips chrome, so restore a visible keyboard focus ring.
- &:focus-visible {
- outline: 2px solid cssUtils.$border-interactive-emphasis;
- outline-offset: cssUtils.$space-3xs;
- }
+ &__toggle-label {
+ -webkit-text-fill-color: currentColor;
+ }
+
+ &__toggle-label--shimmer {
+ @include text-shimmer(cssUtils.$text-neutral-tertiary, cssUtils.$text-neutral-secondary);
}
&__toggle-icon {
@@ -46,7 +81,45 @@
display: flex;
flex-direction: column;
align-items: flex-start;
+ gap: cssUtils.$space-xs;
width: 100%;
+ // Long runs must not push the conversation far down the page: past this
+ // height the timeline scrolls internally. Overridable per app via the
+ // custom property.
+ max-height: var(--openui-tool-timeline-max-height, 24rem);
+ overflow-y: auto;
+ overscroll-behavior: contain;
+ // Scrolls silently — the edge fades already signal there's more.
+ scrollbar-width: none;
+ -ms-overflow-style: none;
+
+ &::-webkit-scrollbar {
+ display: none;
+ }
+
+ padding-inline-end: cssUtils.$space-s;
+
+ // Each edge dissolves only while a row is hidden behind it. Widths come from
+ // JS (CSS can't ask about scroll position); at 0 the mask is a no-op.
+ --openui-timeline-fade-top: 0px;
+ --openui-timeline-fade-bottom: 0px;
+ $edges: linear-gradient(
+ to bottom,
+ transparent 0,
+ #000 var(--openui-timeline-fade-top),
+ #000 calc(100% - var(--openui-timeline-fade-bottom)),
+ transparent 100%
+ );
+ -webkit-mask-image: $edges;
+ mask-image: $edges;
+ }
+
+ &__items--fade-top {
+ --openui-timeline-fade-top: 1.5rem;
+ }
+
+ &__items--fade-bottom {
+ --openui-timeline-fade-bottom: 2rem;
}
// Graceful auto-close of the compact "Working…" tray
@@ -69,20 +142,19 @@
min-height: 0;
}
- // Compact staggered reveal (CSS fade-in; remounted per step via React key).
+ // Opacity only: the list already slides as it follows the newest row, and a
+ // rise on top of that reads as two competing motions.
&__reveal-item {
- animation: openui-behind-the-scenes-reveal 0.2s ease;
+ animation: openui-behind-the-scenes-reveal 0.25s ease;
}
}
@keyframes openui-behind-the-scenes-reveal {
from {
opacity: 0;
- transform: translateY(8px);
}
to {
opacity: 1;
- transform: translateY(0);
}
}
@@ -92,15 +164,54 @@
display: flex;
flex-direction: column;
width: 100%;
- padding-inline-start: cssUtils.$space-l;
+ padding-inline-start: 0;
&__title-row {
+ @include cssUtils.button-reset;
display: flex;
align-items: center;
- gap: cssUtils.$space-m;
+ gap: cssUtils.$space-s;
+ padding: cssUtils.$space-3xs 0;
+ width: 100%;
color: cssUtils.$text-neutral-secondary;
+ background-color: transparent;
+ cursor: pointer;
+ // The row is a <button>, whose UA default centers the stretched label.
+ text-align: start;
// Allow the name to shrink/ellipsize instead of overflowing the row.
min-width: 0;
+
+ @include focus-ring;
+
+ &:hover .openui-tool-call__name {
+ color: cssUtils.$text-neutral-primary;
+ }
+
+ &[aria-expanded="true"] .openui-tool-call__chevron {
+ transform: rotate(180deg);
+ }
+ }
+
+ // No explicit width: the flex column stretches it, so the indent eats into
+ // its own width instead of pushing it past the container's edge.
+ &__content {
+ display: flex;
+ flex-direction: column;
+ gap: cssUtils.$space-xs;
+ margin-block: cssUtils.$space-2xs;
+ margin-inline-start: cssUtils.$space-s;
+ }
+
+ &__block {
+ padding: cssUtils.$space-s cssUtils.$space-m;
+ // Same frame as __sources: a row expands into one or the other, so they
+ // can't read as different kinds of container. The tint separates raw
+ // payloads from the sources list, which stays on the plain surface.
+ border: 1px solid cssUtils.$border-default;
+ border-radius: cssUtils.$radius-xl;
+ background-color: cssUtils.$highlight-subtle;
+ max-height: 250px;
+ overflow: auto;
}
&__icon-wrapper {
@@ -108,11 +219,12 @@
display: flex;
align-items: center;
justify-content: center;
+ opacity: 0.3;
}
&__icon {
flex-shrink: 0;
- color: cssUtils.$text-neutral-secondary;
+ color: cssUtils.$text-neutral-primary;
}
&__icon--blinking {
@@ -120,8 +232,8 @@
}
&__name {
- @include cssUtils.typography(body, default);
- color: cssUtils.$text-neutral-primary;
+ @include cssUtils.typography(body, small);
+ color: cssUtils.$text-neutral-secondary;
-webkit-text-fill-color: currentColor;
white-space: nowrap;
overflow: hidden;
@@ -132,23 +244,7 @@
}
&__name--shimmer {
- display: inline-block;
- background-image:
- linear-gradient(
- 90deg,
- transparent calc(50% - 50px),
- cssUtils.$text-neutral-primary,
- transparent calc(50% + 50px)
- ),
- linear-gradient(cssUtils.$text-neutral-secondary, cssUtils.$text-neutral-secondary);
- background-size:
- 250% 100%,
- auto;
- background-repeat: no-repeat, padding-box;
- -webkit-background-clip: text;
- -webkit-text-fill-color: cssUtils.$text-neutral-primary;
- background-clip: text;
- animation: openui-tool-code-shimmer 2s linear infinite;
+ @include text-shimmer(cssUtils.$text-neutral-tertiary, cssUtils.$text-neutral-secondary);
}
&__connector {
@@ -190,7 +286,7 @@
flex-direction: column;
width: 100%;
border: 1px solid cssUtils.$border-default;
- border-radius: cssUtils.$radius-l;
+ border-radius: cssUtils.$radius-xl;
background-color: cssUtils.$foreground;
padding: cssUtils.$space-2xs;
}
@@ -199,6 +295,7 @@
display: flex;
align-items: center;
justify-content: space-between;
+ gap: cssUtils.$space-m;
padding: cssUtils.$space-2xs cssUtils.$space-s;
padding-left: cssUtils.$space-2xs;
border-radius: cssUtils.$radius-m;
@@ -211,10 +308,7 @@
background-color: cssUtils.$sunk;
}
- &:focus-visible {
- outline: 2px solid cssUtils.$border-interactive-emphasis;
- outline-offset: cssUtils.$space-3xs;
- }
+ @include focus-ring;
}
&__source-left {
@@ -222,6 +316,7 @@
align-items: center;
gap: cssUtils.$space-s;
min-width: 0;
+ flex: 0 1 75%;
}
&__source-logo {
@@ -233,7 +328,7 @@
&__source-title {
@include cssUtils.typography(label, small);
- color: cssUtils.$text-neutral-primary;
+ color: cssUtils.$text-neutral-secondary;
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
@@ -241,10 +336,12 @@
&__source-desc {
@include cssUtils.typography(label, small);
- color: cssUtils.$text-neutral-secondary;
+ color: cssUtils.$text-neutral-tertiary;
// Let the description shrink + truncate so it never squeezes the title.
+ flex: 1 1 25%;
min-width: 0;
- flex-shrink: 1;
+ text-align: end;
+ white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
}
@@ -272,10 +369,7 @@
}
// button-reset strips chrome, so restore a visible keyboard focus ring.
- &:focus-visible {
- outline: 2px solid cssUtils.$border-interactive-emphasis;
- outline-offset: cssUtils.$space-3xs;
- }
+ @include focus-ring;
}
&__chevron {
@@ -310,20 +404,13 @@
color: cssUtils.$text-danger-primary;
}
- // ── Status tints (subtle; driven by the Root `--{status}` modifier) ──
- // Complete vs running look near-identical otherwise — tint the glyph only.
- &--complete {
- .openui-tool-call__icon {
- color: cssUtils.$text-success-primary;
- }
- }
-
- // A failed call should read as failed at a glance: tint the glyph + name and
- // give the card a restrained danger left-border + faint background.
+ // ── Status tints (driven by the Root `--{status}` modifier) ──
+ // Glyph + label alone, no border or fill. The one status to skip the muted
+ // icon — a failure has to be legible.
&--error {
- border-inline-start: 2px solid cssUtils.$text-danger-primary;
- background-color: cssUtils.$danger-background;
- border-radius: cssUtils.$radius-m;
+ .openui-tool-call__icon-wrapper {
+ opacity: 1;
+ }
.openui-tool-call__icon {
color: cssUtils.$text-danger-primary;
@@ -338,11 +425,11 @@
// ── Expandable code block (request / response) ──
.openui-tool-code-block {
- border: 1px solid cssUtils.$border-interactive;
- border-radius: cssUtils.$radius-m;
+ border: 1px solid cssUtils.$border-default;
+ border-radius: cssUtils.$radius-xl;
overflow: hidden;
width: 100%;
- background-color: cssUtils.$foreground;
+ background-color: cssUtils.$highlight-subtle;
transition: border-color 0.15s ease;
&:hover {
@@ -361,10 +448,7 @@
background-color: transparent;
// button-reset strips chrome, so restore a visible keyboard focus ring.
- &:focus-visible {
- outline: 2px solid cssUtils.$border-interactive-emphasis;
- outline-offset: cssUtils.$space-3xs;
- }
+ @include focus-ring;
}
&__label {
@@ -379,23 +463,7 @@
&__label--loading {
@include cssUtils.typography(label, small);
- display: inline-block;
- background-image:
- linear-gradient(
- 90deg,
- transparent calc(50% - 40px),
- cssUtils.$text-neutral-primary,
- transparent calc(50% + 40px)
- ),
- linear-gradient(cssUtils.$text-neutral-secondary, cssUtils.$text-neutral-secondary);
- background-size:
- 250% 100%,
- auto;
- background-repeat: no-repeat, padding-box;
- -webkit-background-clip: text;
- -webkit-text-fill-color: cssUtils.$text-neutral-primary;
- background-clip: text;
- animation: openui-tool-code-shimmer 2s linear infinite;
+ @include text-shimmer(cssUtils.$text-neutral-secondary, cssUtils.$text-neutral-primary);
}
&__chevron {
@@ -459,10 +527,12 @@
}
}
+// Shares an element with the wrapper's resting 0.3, so it replaces that rather
+// than compounding — these are the running glyph's real opacity.
@keyframes openui-tool-call-icon-blink {
0%,
100% {
- opacity: 1;
+ opacity: 0.6;
}
50% {
opacity: 0.2;
@@ -478,6 +548,41 @@
}
}
+// ── Timeline thinking steps ──
+// Prose the model emitted alongside its tool calls, rendered as a timeline
+// step so it reads as part of the run instead of a loose paragraph. Geometry
+// mirrors .openui-tool-call's title row: same start padding, 14px glyph, same
+// gap — the text column lines up with tool names.
+.openui-tool-call-timeline {
+ &__text-step {
+ display: flex;
+ align-items: flex-start;
+ gap: cssUtils.$space-s;
+ // Flush with the tool rows: prose is their peer, not an indented aside.
+ padding-inline-start: 0;
+ // Breathing room against the neighboring timeline entries.
+ margin-block: cssUtils.$space-s;
+ width: 100%;
+ }
+
+ // Doubled-up selector so these rules WIN over `.openui-markdown-renderer`'s
+ // own class and tag rules (body/default typography, primary color on
+ // p/strong/…) regardless of which stylesheet lands later in the build.
+ &__text-step &__text-step-body {
+ @include cssUtils.typography(body, small);
+ color: cssUtils.$text-neutral-primary;
+ min-width: 0;
+ flex: 1;
+
+ * {
+ margin: 0;
+ font: inherit;
+ color: inherit !important;
+ line-height: inherit;
+ }
+ }
+}
+
// ── Reduced motion ──
// Honor `prefers-reduced-motion: reduce`: stop the infinite icon blink + text
// shimmer (the shimmer also paints text via a clipped gradient, so reset it to a
@@ -490,6 +595,7 @@
}
.openui-tool-call__name--shimmer,
+ .openui-behind-the-scenes__toggle-label--shimmer,
.openui-tool-code-block__label--loading {
animation: none;
background-image: none;
diff --git a/packages/react-ui/src/components/ToolCall/toolSources.ts b/packages/react-ui/src/components/ToolCall/toolSources.ts
new file mode 100644
index 000000000..d076c634c
--- /dev/null
+++ b/packages/react-ui/src/components/ToolCall/toolSources.ts
@@ -0,0 +1,95 @@
+/**
+ * Extraction of link "sources" from tool RESULT text, powering the
+ * favicon + title rows on tool cards.
+ */
+
+export interface ToolResultSource {
+ title: string;
+ url: string;
+ /** Domain used for the favicon lookup (e.g. `en.wikipedia.org`). */
+ host: string;
+ /** Human-ish site name derived from the host (e.g. `Wikipedia`). */
+ siteName: string;
+}
+
+interface SourceExtractor {
+ /** Which tools this extractor understands (e.g. name suffix or exact match). */
+ matches: (toolName: string) => boolean;
+ extract: (result: string) => ToolResultSource[];
+}
+
+const stripWww = (host: string) => host.replace(/^www\./, "");
+
+// Registrable-name heuristic: drop the TLD and
+// any subdomains, capitalize what remains
+const TWO_PART_TLD = /\.(co|com|org|net|gov|ac|edu)\.[a-z]{2}$/;
+
+function siteNameFromHost(host: string): string {
+ const base = TWO_PART_TLD.test(host)
+ ? host.replace(TWO_PART_TLD, "")
+ : host.replace(/\.[a-z]+$/i, "");
+ const label = base.split(".").pop() || host;
+ return label.charAt(0).toUpperCase() + label.slice(1);
+}
+
+// ── Format: numbered link list ───────────────────────────────────────────────
+// `[n] Title` followed by a URL line, optionally a `Source:` domain line:
+// web: `[n] Title\nURL: <page url>`
+// image: `[n] Title\nImage URL: <image file>\nSource: <page domain>`
+const NUMBERED_LINKS = /^\[\d+\]\s*([^\n]*)\n(?:\w+ )?URL:\s*(\S+)(?:\nSource:\s*(\S+))?/gm;
+
+// Readable stand-in when a result entry has no title line: the URL's last
+// path segment ("/guides/what-is-thesys-c1" → "What is thesys c1"), else the
+// site name. Fetching the real <title> client-side is CORS-blocked.
+function titleFromUrl(parsed: URL, host: string): string {
+ const slug = parsed.pathname.split("/").filter(Boolean).pop();
+ const words = slug
+ ? decodeURIComponent(slug)
+ .replace(/\.[a-z0-9]+$/i, "") // file extensions
+ .replace(/[-_+]+/g, " ")
+ .trim()
+ : "";
+ if (!words) return siteNameFromHost(host);
+ return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+function extractNumberedLinks(result: string): ToolResultSource[] {
+ const sources: ToolResultSource[] = [];
+ for (const match of result.matchAll(NUMBERED_LINKS)) {
+ const url = match[2]!;
+ try {
+ const parsed = new URL(url);
+ const host = stripWww(match[3] ?? parsed.hostname);
+ sources.push({
+ title: match[1]!.trim() || titleFromUrl(parsed, host),
+ url,
+ host,
+ siteName: siteNameFromHost(host),
+ });
+ } catch {
+ // Not a valid absolute URL — skip the row, keep the rest.
+ }
+ }
+ return sources;
+}
+
+// ── Registry ─────────────────────────────────────────────────────────────────
+
+const EXTRACTORS: SourceExtractor[] = [
+ { matches: (toolName) => /_search$/.test(toolName), extract: extractNumberedLinks },
+];
+
+/**
+ * Link sources of a tool result, deduped by URL. `[]` when no extractor
+ * claims the tool or nothing in the result parses.
+ */
+export function extractToolSources(toolName: string, result: string): ToolResultSource[] {
+ const extractor = EXTRACTORS.find((e) => e.matches(toolName));
+ if (!extractor) return [];
+ const seen = new Set<string>();
+ return extractor.extract(result).filter((source) => {
+ if (seen.has(source.url)) return false;
+ seen.add(source.url);
+ return true;
+ });
+}
diff --git a/packages/react-ui/src/utils/messages.ts b/packages/react-ui/src/utils/messages.ts
new file mode 100644
index 000000000..396ccd8d5
--- /dev/null
+++ b/packages/react-ui/src/utils/messages.ts
@@ -0,0 +1,26 @@
+import {
+ lookupArtifactRenderer,
+ useArtifactRendererRegistry,
+ type Message,
+ type ToolActivity,
+} from "@openuidev/react-headless";
+
+type ArtifactRendererRegistry = ReturnType<typeof useArtifactRendererRegistry>;
+
+/** Id of the last assistant message in a thread, or null. Shared by the thread
+ * and the assistant component to decide which message is "live". */
+export function getLastAssistantMessageId(messages: Message[]): string | null {
+ for (let i = messages.length - 1; i >= 0; i--) {
+ if (messages[i]?.role === "assistant") return messages[i]!.id;
+ }
+ return null;
+}
+
+/** Activities whose tool has a matched artifact/search renderer — the ones that
+ * render a rich preview outside the raw timeline. */
+export function getMatchedRendererActivities(
+ registry: ArtifactRendererRegistry,
+ activities: ToolActivity[],
+): ToolActivity[] {
+ return activities.filter((a) => !!(registry && lookupArtifactRenderer(registry, a.toolName)));
+}
diff --git a/packages/react-ui/src/utils/sentinelParser.ts b/packages/react-ui/src/utils/sentinelParser.ts
index 45edd3529..11c6d660c 100644
--- a/packages/react-ui/src/utils/sentinelParser.ts
+++ b/packages/react-ui/src/utils/sentinelParser.ts
@@ -45,6 +45,15 @@ export function separateContentAndContext(raw: string): ParsedMessageContent {
return { ...sections, content, ...(end ? { end: true } : {}) };
}
+/**
+ * Whether the content carries recognizable OpenUI-lang syntax — the
+ * ```openui-lang ``` fence, or a top-level `root =` binding when emitted
+ * unfenced.
+ */
+export function hasLangSyntax(content: string | null | undefined): boolean {
+ return !!content && (content.includes("```openui-lang") || /(^|\n)\s*root\s*=/.test(content));
+}
+
// The ordered section walk over the inline-sentinel format.
function splitSections(raw: string): {
content: string;