Skip to content

The Open Standard for Generative UI

fix(react-headless): order LangGraph multi-step tool loops correctly (#1060)

ABaab21cebbc33
diff --git a/packages/langchain/package.json b/packages/langchain/package.json
index 32db5c8e1..5f435b5ad 100644
--- a/packages/langchain/package.json
+++ b/packages/langchain/package.json
@@ -1,6 +1,6 @@
{
"name": "@openuidev/langchain",
- "version": "0.0.2",
+ "version": "0.0.3",
"description": "LangChain and LangGraph integration primitives for streaming OpenUI generative interfaces",
"license": "MIT",
"engines": {
diff --git a/packages/langchain/src/__tests__/transformer.test.ts b/packages/langchain/src/__tests__/transformer.test.ts
index cb10c3a31..3dd0465ab 100644
--- a/packages/langchain/src/__tests__/transformer.test.ts
+++ b/packages/langchain/src/__tests__/transformer.test.ts
@@ -130,6 +130,107 @@ describe("openUIStreamTransformer", () => {
]);
});
+ it("diffs ChatOpenAI Responses snapshot-style tool args into append deltas", () => {
+ const transformer = openUIStreamTransformer();
+ const { openui } = transformer.init();
+
+ transformer.process(messageEvent({ event: "message-start", id: "message-snap", role: "ai" }));
+ transformer.process(
+ messageEvent({
+ event: "content-block-start",
+ index: 0,
+ content: {
+ type: "tool_call_chunk",
+ id: "call-snap",
+ name: "thesys_generate_report",
+ args: "",
+ },
+ }),
+ );
+ // Responses stream re-sends the full accumulated args string each delta.
+ transformer.process(
+ messageEvent({
+ event: "content-block-delta",
+ index: 0,
+ delta: {
+ type: "block-delta",
+ fields: {
+ type: "tool_call_chunk",
+ id: "call-snap",
+ name: "thesys_generate_report",
+ args: '{"artifact_id":"art-1","type":"report","artifact_content":"',
+ },
+ },
+ }),
+ );
+ transformer.process(
+ messageEvent({
+ event: "content-block-delta",
+ index: 0,
+ delta: {
+ type: "block-delta",
+ fields: {
+ type: "tool_call_chunk",
+ id: "call-snap",
+ name: "thesys_generate_report",
+ args: '{"artifact_id":"art-1","type":"report","artifact_content":"root = ReportView()"}',
+ },
+ },
+ }),
+ );
+ // Identical snapshot must not emit another args event.
+ transformer.process(
+ messageEvent({
+ event: "content-block-delta",
+ index: 0,
+ delta: {
+ type: "block-delta",
+ fields: {
+ type: "tool_call_chunk",
+ id: "call-snap",
+ name: "thesys_generate_report",
+ args: '{"artifact_id":"art-1","type":"report","artifact_content":"root = ReportView()"}',
+ },
+ },
+ }),
+ );
+ transformer.process(
+ messageEvent({
+ event: "content-block-finish",
+ index: 0,
+ content: {
+ type: "tool_call",
+ id: "call-snap",
+ name: "thesys_generate_report",
+ args: {
+ artifact_id: "art-1",
+ type: "report",
+ artifact_content: "root = ReportView()",
+ },
+ },
+ }),
+ );
+
+ expect(channelItems(openui)).toEqual([
+ {
+ type: EventType.TOOL_CALL_START,
+ toolCallId: "call-snap",
+ toolCallName: "thesys_generate_report",
+ },
+ {
+ type: EventType.TOOL_CALL_ARGS,
+ toolCallId: "call-snap",
+ delta: '{"artifact_id":"art-1","type":"report","artifact_content":"',
+ },
+ {
+ type: EventType.TOOL_CALL_ARGS,
+ toolCallId: "call-snap",
+ delta: 'root = ReportView()"}',
+ },
+ { type: EventType.TOOL_CALL_END, toolCallId: "call-snap" },
+ ]);
+ });
+
it("ends an active tool call before an early result and ignores a later message end", () => {
const transformer = openUIStreamTransformer();
const { openui } = transformer.init();
@@ -274,6 +375,148 @@ describe("openUIStreamTransformer", () => {
{ type: EventType.RUN_ERROR, message: "model unavailable" },
]);
});
+
+ it("maps Cloud function_call_output provider events to tool results", () => {
+ const transformer = openUIStreamTransformer();
+ const { openui } = transformer.init();
+ const sentinel =
+ ']]>openui:artifact {"artifact_id":"art-1","type":"report","name":"Q4"}\nroot = ReportView()';
+
+ transformer.process(messageEvent({ event: "message-start", id: "message-cloud", role: "ai" }));
+ transformer.process(
+ messageEvent({
+ event: "content-block-start",
+ index: 0,
+ content: {
+ type: "tool_call_chunk",
+ id: "call-artifact",
+ name: "thesys_generate_report",
+ args: '{"type":"report"}',
+ },
+ }),
+ );
+ transformer.process(
+ messageEvent({
+ event: "content-block-finish",
+ index: 0,
+ content: {
+ type: "tool_call",
+ id: "call-artifact",
+ name: "thesys_generate_report",
+ args: { type: "report" },
+ },
+ }),
+ );
+ // ChatOpenAI Responses stream: Cloud's function_call_output is a provider
+ // passthrough — not a LangGraph tools-channel event.
+ transformer.process(
+ runtimeMessageEvent({
+ event: "provider",
+ provider: "openai",
+ name: "response.output_item.done",
+ payload: {
+ type: "response.output_item.done",
+ item: {
+ type: "function_call_output",
+ id: "fco-1",
+ call_id: "call-artifact",
+ output: sentinel,
+ },
+ },
+ }),
+ );
+ // added + done must not double-emit
+ transformer.process(
+ runtimeMessageEvent({
+ event: "provider",
+ provider: "openai",
+ name: "response.output_item.added",
+ payload: {
+ type: "response.output_item.added",
+ item: {
+ type: "function_call_output",
+ id: "fco-1",
+ call_id: "call-artifact",
+ output: sentinel,
+ },
+ },
+ }),
+ );
+ transformer.process(messageEvent({ event: "message-finish" }));
+
+ expect(channelItems(openui)).toEqual([
+ {
+ type: EventType.TOOL_CALL_START,
+ toolCallId: "call-artifact",
+ toolCallName: "thesys_generate_report",
+ },
+ {
+ type: EventType.TOOL_CALL_ARGS,
+ toolCallId: "call-artifact",
+ delta: '{"type":"report"}',
+ },
+ { type: EventType.TOOL_CALL_END, toolCallId: "call-artifact" },
+ {
+ type: EventType.TOOL_CALL_RESULT,
+ messageId: "fco-1",
+ toolCallId: "call-artifact",
+ content: sentinel,
+ role: "tool",
+ },
+ ]);
+ });
+
+ it("maps server_tool_call_result content blocks to tool results", () => {
+ const transformer = openUIStreamTransformer();
+ const { openui } = transformer.init();
+
+ transformer.process(messageEvent({ event: "message-start", id: "message-server", role: "ai" }));
+ transformer.process(
+ messageEvent({
+ event: "content-block-start",
+ index: 0,
+ content: {
+ type: "server_tool_call",
+ id: "call-search",
+ name: "web_search",
+ args: { query: "openui" },
+ },
+ }),
+ );
+ transformer.process(
+ messageEvent({
+ event: "content-block-finish",
+ index: 1,
+ content: {
+ type: "server_tool_call_result",
+ toolCallId: "call-search",
+ status: "success",
+ output: { results: ["hit"] },
+ },
+ }),
+ );
+
+ expect(channelItems(openui)).toEqual([
+ {
+ type: EventType.TOOL_CALL_START,
+ toolCallId: "call-search",
+ toolCallName: "web_search",
+ },
+ {
+ type: EventType.TOOL_CALL_ARGS,
+ toolCallId: "call-search",
+ delta: '{"query":"openui"}',
+ },
+ { type: EventType.TOOL_CALL_END, toolCallId: "call-search" },
+ {
+ type: EventType.TOOL_CALL_RESULT,
+ messageId: "tool-result-call-search",
+ toolCallId: "call-search",
+ content: '{"results":["hit"]}',
+ role: "tool",
+ },
+ ]);
+ });
});
function messageEvent(data: MessagesData): ProtocolEvent {
diff --git a/packages/langchain/src/transformer.ts b/packages/langchain/src/transformer.ts
index 28b779b32..b0c843db3 100644
--- a/packages/langchain/src/transformer.ts
+++ b/packages/langchain/src/transformer.ts
@@ -15,12 +15,17 @@ const TOOL_BLOCK_TYPES = new Set([
"server_tool_call_chunk",
]);
+/** Provider-executed tool results (Cloud artifacts, search, MCP). */
+const TOOL_RESULT_BLOCK_TYPES = new Set(["server_tool_call_result", "server_tool_result"]);
+
interface ToolCallState {
id: string;
name: string;
started: boolean;
ended: boolean;
argsEmitted: boolean;
+ /** Args already emitted as AG-UI deltas — used to diff snapshot-style updates. */
+ argsEmittedSoFar: string;
}
/**
@@ -31,6 +36,12 @@ interface ToolCallState {
* clients can then subscribe to `custom:openui`, or use {@link streamOpenUI}
* and {@link createLangChainStreamResponse} to relay that channel as AG-UI
* Server-Sent Events.
+ *
+ * Provider-executed Cloud tools (artifacts, search, MCP) never hit LangGraph's
+ * `tools` channel. ChatOpenAI surfaces their `function_call_output` as
+ * passthrough `provider` events (or occasionally as `server_tool_*_result`
+ * content blocks). Those are mapped to `TOOL_CALL_RESULT` here so the browser
+ * can render artifact previews live — without waiting for a storage reload.
*/
export function openUIStreamTransformer(): StreamTransformer<{
openui: StreamChannel<AGUIEvent>;
@@ -46,6 +57,8 @@ export function openUIStreamTransformer(): StreamTransformer<{
const toolCallsByIndex = new Map<string, ToolCallState>();
const toolOutputByCallId = new Map<string, string>();
+ // Dedup across tools-channel + provider `added`/`done` + content-block paths.
+ const emittedToolResultIds = new Set<string>();
const emit = (event: AGUIEvent) => channel.push(event);
@@ -94,6 +107,7 @@ export function openUIStreamTransformer(): StreamTransformer<{
started: false,
ended: false,
argsEmitted: false,
+ argsEmittedSoFar: "",
};
toolCallsByIndex.set(key, state);
} else if (!state.started) {
@@ -114,12 +128,24 @@ export function openUIStreamTransformer(): StreamTransformer<{
const args = getArgsString(block);
if (emitArgs && args && state.started) {
- emit({
- type: EventType.TOOL_CALL_ARGS,
- toolCallId: state.id,
- delta: args,
- });
- state.argsEmitted = true;
+ // ChatOpenAI Responses stream sends the FULL accumulated args string on
+ // every block-delta. AG-UI TOOL_CALL_ARGS deltas are append-only, so
+ // re-emitting the snapshot would corrupt JSON (and blank Cloud artifact
+ // previews that parse artifact_content from args). Emit only the suffix.
+ const delta = args.startsWith(state.argsEmittedSoFar)
+ ? args.slice(state.argsEmittedSoFar.length)
+ : args;
+ if (delta) {
+ emit({
+ type: EventType.TOOL_CALL_ARGS,
+ toolCallId: state.id,
+ delta,
+ });
+ state.argsEmittedSoFar = args.startsWith(state.argsEmittedSoFar)
+ ? args
+ : state.argsEmittedSoFar + args;
+ state.argsEmitted = true;
+ }
}
return state;
@@ -140,6 +166,42 @@ export function openUIStreamTransformer(): StreamTransformer<{
if (state) endToolCall(state);
};
+ const emitToolResult = (
+ toolCallId: string,
+ content: string,
+ options?: { isError?: boolean; error?: string; messageId?: string },
+ ) => {
+ if (!toolCallId || emittedToolResultIds.has(toolCallId)) return;
+ emittedToolResultIds.add(toolCallId);
+ endToolCallById(toolCallId);
+ emit({
+ type: EventType.TOOL_CALL_RESULT,
+ messageId: options?.messageId ?? `tool-result-${toolCallId}`,
+ toolCallId,
+ content,
+ role: "tool",
+ ...(options?.isError ? { isError: true, error: options.error ?? content } : {}),
+ });
+ };
+
+ const emitServerToolResultBlock = (block: Partial<ContentBlock> & Record<string, unknown>) => {
+ const toolCallId = getServerToolResultCallId(block);
+ if (!toolCallId) return;
+ const isError = block.status === "error";
+ emitToolResult(toolCallId, serializeToolOutput(block.output), {
+ isError,
+ ...(isError ? { error: serializeToolOutput(block.output) } : {}),
+ });
+ };
+
+ const emitProviderFunctionCallOutput = (payload: unknown) => {
+ const item = getFunctionCallOutputItem(payload);
+ if (!item) return;
+ emitToolResult(item.call_id, serializeToolOutput(item.output), {
+ messageId: item.id ?? `tool-result-${item.call_id}`,
+ });
+ };
+
const resetMessage = (data: Extract<MessagesData, { event: "message-start" }>) => {
endAllToolCalls();
endText();
@@ -163,7 +225,7 @@ export function openUIStreamTransformer(): StreamTransformer<{
toolCallsByIndex.clear();
};
- const processMessages = (data: MessagesData) => {
+ const processMessages = (data: MessagesData | ProviderMessageEvent) => {
if (data.event === "message-start") {
resetMessage(data);
return;
@@ -177,6 +239,8 @@ export function openUIStreamTransformer(): StreamTransformer<{
if (isTextBlock(block)) {
ensureTextStart();
emitTextDelta(typeof block.text === "string" ? block.text : "");
+ } else if (isToolResultBlock(block)) {
+ emitServerToolResultBlock(block);
} else if (isToolBlock(block)) {
syncToolCall(data.index, block, true);
}
@@ -198,7 +262,9 @@ export function openUIStreamTransformer(): StreamTransformer<{
case "content-block-finish": {
const block = data.content;
- if (isToolBlock(block)) {
+ if (isToolResultBlock(block)) {
+ emitServerToolResultBlock(block);
+ } else if (isToolBlock(block)) {
const state = syncToolCall(data.index, block, false);
if (!state.argsEmitted) {
syncToolCall(data.index, block, true);
@@ -219,6 +285,17 @@ export function openUIStreamTransformer(): StreamTransformer<{
runErrorEmitted = true;
return;
+ case "provider":
+ // ChatOpenAI's Responses stream maps unknown items (including Cloud
+ // function_call_output) to provider passthrough events.
+ if (
+ data.name === "response.output_item.added" ||
+ data.name === "response.output_item.done"
+ ) {
+ emitProviderFunctionCallOutput(data.payload);
+ }
+ return;
+
default:
return;
}
@@ -235,26 +312,13 @@ export function openUIStreamTransformer(): StreamTransformer<{
case "tool-finished": {
const streamedOutput = toolOutputByCallId.get(toolCallId);
toolOutputByCallId.delete(toolCallId);
- endToolCallById(toolCallId);
- emit({
- type: EventType.TOOL_CALL_RESULT,
- messageId: `tool-result-${toolCallId}`,
- toolCallId,
- content: serializeToolOutput(data.output, streamedOutput),
- role: "tool",
- });
+ emitToolResult(toolCallId, serializeToolOutput(data.output, streamedOutput));
return;
}
case "tool-error":
toolOutputByCallId.delete(toolCallId);
- endToolCallById(toolCallId);
- emit({
- type: EventType.TOOL_CALL_RESULT,
- messageId: `tool-result-${toolCallId}`,
- toolCallId,
- content: data.message,
- role: "tool",
+ emitToolResult(toolCallId, data.message, {
isError: true,
error: data.message,
});
@@ -274,7 +338,7 @@ export function openUIStreamTransformer(): StreamTransformer<{
// Do not filter by namespace: DeepAgents emits model and tool events
// from nested `model_request:*` and `tools:*` namespaces.
if (event.method === "messages") {
- processMessages(event.params.data as MessagesData);
+ processMessages(event.params.data as MessagesData | ProviderMessageEvent);
} else if (event.method === "tools") {
processTools(event.params.data as ToolsEventData);
}
@@ -297,6 +361,14 @@ export function openUIStreamTransformer(): StreamTransformer<{
};
}
+/** ChatOpenAI Responses passthrough — not in MessagesData, but forwarded live. */
+interface ProviderMessageEvent {
+ event: "provider";
+ provider?: string;
+ name: string;
+ payload: unknown;
+}
+
function serializeToolOutput(output: unknown, streamedOutput?: string): string {
if (typeof output === "string") return output;
if (output === undefined && streamedOutput !== undefined) return streamedOutput;
@@ -317,6 +389,10 @@ function isToolBlock(block: Partial<ContentBlock> & Record<string, unknown>): bo
return typeof block.type === "string" && TOOL_BLOCK_TYPES.has(block.type);
}
+function isToolResultBlock(block: Partial<ContentBlock> & Record<string, unknown>): boolean {
+ return typeof block.type === "string" && TOOL_RESULT_BLOCK_TYPES.has(block.type);
+}
+
function getToolCallId(block: Partial<ContentBlock> & Record<string, unknown>): string | undefined {
return typeof block.id === "string" && block.id.length > 0 ? block.id : undefined;
}
@@ -327,8 +403,35 @@ function getToolCallName(
return typeof block.name === "string" && block.name.length > 0 ? block.name : undefined;
}
+function getServerToolResultCallId(
+ block: Partial<ContentBlock> & Record<string, unknown>,
+): string | undefined {
+ // LangChain core uses camelCase; protocol-v2 uses snake_case.
+ const camel = block["toolCallId"];
+ if (typeof camel === "string" && camel.length > 0) return camel;
+ const snake = block["tool_call_id"];
+ if (typeof snake === "string" && snake.length > 0) return snake;
+ return undefined;
+}
+
function getArgsString(block: Partial<ContentBlock> & Record<string, unknown>): string {
if (typeof block.args === "string") return block.args;
if (block.args != null && typeof block.args === "object") return JSON.stringify(block.args);
return "";
}
+
+function getFunctionCallOutputItem(
+ payload: unknown,
+): { call_id: string; output: unknown; id?: string } | null {
+ if (typeof payload !== "object" || payload === null) return null;
+ const item = (payload as { item?: unknown }).item;
+ if (typeof item !== "object" || item === null) return null;
+ const record = item as { type?: unknown; call_id?: unknown; output?: unknown; id?: unknown };
+ if (record.type !== "function_call_output") return null;
+ if (typeof record.call_id !== "string" || record.call_id.length === 0) return null;
+ return {
+ call_id: record.call_id,
+ output: record.output,
+ ...(typeof record.id === "string" && record.id.length > 0 ? { id: record.id } : {}),
+ };
+}
diff --git a/packages/react-headless/package.json b/packages/react-headless/package.json
index 7772ffd10..c70250ffb 100644
--- a/packages/react-headless/package.json
+++ b/packages/react-headless/package.json
@@ -1,6 +1,6 @@
{
"name": "@openuidev/react-headless",
- "version": "0.9.11",
+ "version": "0.9.12",
"description": "Headless React primitives for AI chat — state management, streaming adapters for OpenAI, Vercel AI SDK, 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__/langgraph.integration.test.ts b/packages/react-headless/src/stream/__tests__/langgraph.integration.test.ts
new file mode 100644
index 000000000..e93c78d5e
--- /dev/null
+++ b/packages/react-headless/src/stream/__tests__/langgraph.integration.test.ts
@@ -0,0 +1,90 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import type { Message } from "../../types";
+import { langGraphAdapter } from "../adapters/langgraph";
+import { langGraphMessageFormat } from "../formats/langgraph-message-format";
+import { processStreamedMessage } from "../processStreamedMessage";
+
+beforeAll(() => {
+ const globalWithAnimationFrame = globalThis as unknown as {
+ requestAnimationFrame?: (callback: FrameRequestCallback) => number;
+ cancelAnimationFrame?: (id: number) => void;
+ };
+
+ if (typeof globalWithAnimationFrame.requestAnimationFrame !== "function") {
+ globalWithAnimationFrame.requestAnimationFrame = (callback: FrameRequestCallback) =>
+ setTimeout(() => callback(performance.now()), 0) as unknown as number;
+ globalWithAnimationFrame.cancelAnimationFrame = (id: number) => clearTimeout(id);
+ }
+});
+
+function sse(event: string, data: unknown): string {
+ return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+
+describe("LangGraph stream integration", () => {
+ it("keeps a tool-loop turn ordered and valid for the next request", async () => {
+ const messages: Message[] = [];
+ const response = new Response(
+ sse("messages", [
+ {
+ type: "ai",
+ id: "ai-call",
+ content: "",
+ tool_calls: [{ id: "call-1", name: "get_weather", args: { location: "Berlin" } }],
+ },
+ { langgraph_node: "model", langgraph_step: 1 },
+ ]) +
+ sse("messages", [
+ {
+ type: "tool",
+ id: "tool-result",
+ content: '{"temperature_c":21}',
+ tool_call_id: "call-1",
+ status: "success",
+ },
+ { langgraph_node: "tools", langgraph_step: 2 },
+ ]) +
+ sse("messages", [
+ { type: "ai", id: "ai-final", content: "It is 21°C." },
+ { langgraph_node: "model", langgraph_step: 3 },
+ ]) +
+ sse("end", null),
+ { headers: { "Content-Type": "text/event-stream" } },
+ );
+
+ await processStreamedMessage({
+ response,
+ adapter: langGraphAdapter(),
+ createMessage: (message) => messages.push(message),
+ updateMessage: (message) => {
+ const index = messages.findIndex((candidate) => candidate.id === message.id);
+ if (index !== -1) messages[index] = message;
+ },
+ });
+
+ expect(messages.map((message) => message.role)).toEqual(["assistant", "tool", "assistant"]);
+ expect(messages[0]).toMatchObject({
+ role: "assistant",
+ content: "",
+ toolCalls: [
+ {
+ id: "call-1",
+ function: { name: "get_weather", arguments: '{"location":"Berlin"}' },
+ },
+ ],
+ });
+ expect(messages[1]).toMatchObject({
+ role: "tool",
+ toolCallId: "call-1",
+ content: '{"temperature_c":21}',
+ });
+ expect(messages[2]).toMatchObject({ role: "assistant", content: "It is 21°C." });
+
+ messages.push({ id: "next-user", role: "user", content: "How about Paris?" });
+ expect(
+ (langGraphMessageFormat.toApi(messages) as Array<{ type: string }>).map(
+ (message) => message.type,
+ ),
+ ).toEqual(["ai", "tool", "ai", "human"]);
+ });
+});
diff --git a/packages/react-headless/src/stream/__tests__/processStreamedMessage.test.ts b/packages/react-headless/src/stream/__tests__/processStreamedMessage.test.ts
index 466b42368..38ef34696 100644
--- a/packages/react-headless/src/stream/__tests__/processStreamedMessage.test.ts
+++ b/packages/react-headless/src/stream/__tests__/processStreamedMessage.test.ts
@@ -176,4 +176,110 @@ describe("processStreamedMessage — interleaved output message items", () => {
expect(created.filter((m) => m.role === "assistant")).toHaveLength(1);
});
+
+ it("splits text after tools even when the wire messageId stays the same", async () => {
+ // LangGraph + ChatOpenAI Responses collapses interleaved message items into
+ // one AG-UI messageId; processStreamedMessage still segments on text→tools→text.
+ const adapter = adapterFromEvents([
+ { type: EventType.TEXT_MESSAGE_START, messageId: "run-1", role: "assistant" },
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "run-1", delta: "Let me search." },
+ { type: EventType.TOOL_CALL_START, toolCallId: "tc-1", toolCallName: "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_CONTENT, messageId: "run-1", delta: "Found it." },
+ ]);
+
+ 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();
+
+ 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.");
+ expect(finalSeg2.toolCalls ?? []).toHaveLength(0);
+ });
+
+ it("keeps parallel tool calls on one segment and does not create a blank trailing assistant", async () => {
+ // Responses opens a new message item (START) after parallel tools; content
+ // may arrive later. An empty assistant must not be committed — it would
+ // become `last` and blank the answer until remount.
+ const adapter = adapterFromEvents([
+ { type: EventType.TEXT_MESSAGE_START, messageId: "item-1", role: "assistant" },
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "item-1", delta: "Calling both." },
+ { type: EventType.TOOL_CALL_START, toolCallId: "tc-1", toolCallName: "get_weather" },
+ { type: EventType.TOOL_CALL_ARGS, toolCallId: "tc-1", delta: '{"city":"NYC"}' },
+ { type: EventType.TOOL_CALL_END, toolCallId: "tc-1" },
+ { type: EventType.TOOL_CALL_START, toolCallId: "tc-2", toolCallName: "get_weather" },
+ { type: EventType.TOOL_CALL_ARGS, toolCallId: "tc-2", delta: '{"city":"SF"}' },
+ { type: EventType.TOOL_CALL_END, toolCallId: "tc-2" },
+ {
+ type: EventType.TOOL_CALL_RESULT,
+ toolCallId: "tc-1",
+ content: '{"temp":20}',
+ messageId: "out-1",
+ role: "tool",
+ },
+ {
+ type: EventType.TOOL_CALL_RESULT,
+ toolCallId: "tc-2",
+ content: '{"temp":18}',
+ messageId: "out-2",
+ role: "tool",
+ },
+ // New message item after tools — no content yet on this event.
+ { type: EventType.TEXT_MESSAGE_START, messageId: "item-2", role: "assistant" },
+ { type: EventType.TEXT_MESSAGE_CONTENT, messageId: "item-2", delta: "" },
+ {
+ type: EventType.TEXT_MESSAGE_CONTENT,
+ messageId: "item-2",
+ delta: "NYC is 20°C and SF is 18°C.",
+ },
+ ]);
+
+ 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();
+
+ const assistants = created.filter((m) => m.role === "assistant");
+ expect(assistants).toHaveLength(2);
+ expect(created.map((m) => m.role)).toEqual(["assistant", "tool", "tool", "assistant"]);
+
+ const seg1 = assistants[0] as Message & { content?: string; toolCalls?: unknown[] };
+ const seg2 = assistants[1] 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("Calling both.");
+ expect(finalSeg1.toolCalls).toHaveLength(2);
+ expect(finalSeg2.content).toBe("NYC is 20°C and SF is 18°C.");
+ expect(finalSeg2.toolCalls ?? []).toHaveLength(0);
+ });
});
diff --git a/packages/react-headless/src/stream/__tests__/vercel-ai-sdk.integration.test.ts b/packages/react-headless/src/stream/__tests__/vercel-ai-sdk.integration.test.ts
index d7010ef22..6ebfe29c4 100644
--- a/packages/react-headless/src/stream/__tests__/vercel-ai-sdk.integration.test.ts
+++ b/packages/react-headless/src/stream/__tests__/vercel-ai-sdk.integration.test.ts
@@ -69,6 +69,82 @@ describe("Vercel AI SDK stream integration", () => {
).toEqual([{ id: "assistant-1", role: "assistant", content: "onetwo" }]);
});
+ it("keeps pre-tool commentary on its own assistant message when answer text follows", async () => {
+ const messages: Message[] = [];
+
+ await processStreamedMessage({
+ response: responseFromChunks(
+ { type: "start-step" },
+ { type: "text-start", id: "text-1" },
+ { type: "text-delta", id: "text-1", delta: "Let me do this" },
+ { type: "text-end", id: "text-1" },
+ {
+ type: "tool-input-available",
+ toolCallId: "call-1",
+ toolName: "get_weather",
+ input: { location: "Berlin" },
+ },
+ { type: "tool-output-available", toolCallId: "call-1", output: { temp: 21 } },
+ { type: "text-start", id: "text-2" },
+ { type: "text-delta", id: "text-2", delta: "root = Card()" },
+ { type: "text-end", id: "text-2" },
+ { type: "finish-step" },
+ ),
+ adapter: vercelAIAdapter(),
+ createMessage: (message) => messages.push(message),
+ updateMessage: (message) => {
+ const index = messages.findIndex((candidate) => candidate.id === message.id);
+ if (index !== -1) messages[index] = message;
+ },
+ });
+
+ const assistants = messages.filter((message) => message.role === "assistant");
+ expect(assistants).toHaveLength(2);
+ expect(assistants[0]).toMatchObject({
+ role: "assistant",
+ content: "Let me do this",
+ });
+ expect(assistants[1]).toMatchObject({ role: "assistant", content: "root = Card()" });
+
+ expect(
+ vercelAIMessageFormat
+ .fromApi([
+ {
+ id: "assistant-1",
+ role: "assistant",
+ parts: [
+ { type: "step-start" },
+ { type: "text", text: "Let me do this" },
+ {
+ type: "dynamic-tool",
+ toolName: "get_weather",
+ toolCallId: "call-1",
+ state: "output-available",
+ input: { location: "Berlin" },
+ output: { temp: 21 },
+ },
+ { type: "text", text: "root = Card()" },
+ ],
+ },
+ ])
+ .filter((message) => message.role === "assistant"),
+ ).toEqual([
+ {
+ id: "assistant-1",
+ role: "assistant",
+ content: "Let me do this",
+ toolCalls: [
+ {
+ id: "call-1",
+ type: "function",
+ function: { name: "get_weather", arguments: '{"location":"Berlin"}' },
+ },
+ ],
+ },
+ { id: "assistant-1-segment-2", role: "assistant", content: "root = Card()" },
+ ]);
+ });
+
it("preserves tool-only step order and emits no empty model text blocks", async () => {
const messages: Message[] = [];
diff --git a/packages/react-headless/src/stream/adapters/__tests__/langgraph.test.ts b/packages/react-headless/src/stream/adapters/__tests__/langgraph.test.ts
index ac142d338..d7af0bea9 100644
--- a/packages/react-headless/src/stream/adapters/__tests__/langgraph.test.ts
+++ b/packages/react-headless/src/stream/adapters/__tests__/langgraph.test.ts
@@ -105,6 +105,67 @@ describe("langGraphAdapter", () => {
});
});
+ it("splits text that follows tool calls onto a new AG-UI message", async () => {
+ const body =
+ sse("messages", [
+ {
+ type: "AIMessageChunk",
+ content: "Let me do this",
+ id: "msg-1",
+ tool_call_chunks: [{ id: "tc-1", name: "get_weather", args: "{}", index: 0 }],
+ },
+ { langgraph_node: "agent" },
+ ]) +
+ sse("messages", [
+ {
+ type: "AIMessageChunk",
+ content: "root = Card()",
+ id: "msg-1",
+ },
+ { langgraph_node: "agent" },
+ ]) +
+ sse("end", null);
+
+ const events = await collect(langGraphAdapter().parse(makeSSEResponse(body)));
+ const textEvents = events.filter(
+ (event: any) =>
+ event.type === EventType.TEXT_MESSAGE_START ||
+ event.type === EventType.TEXT_MESSAGE_CONTENT ||
+ event.type === EventType.TEXT_MESSAGE_END,
+ );
+
+ expect(textEvents).toEqual([
+ {
+ type: EventType.TEXT_MESSAGE_START,
+ messageId: "msg-1",
+ role: "assistant",
+ },
+ {
+ type: EventType.TEXT_MESSAGE_CONTENT,
+ messageId: "msg-1",
+ delta: "Let me do this",
+ },
+ {
+ type: EventType.TEXT_MESSAGE_END,
+ messageId: "msg-1",
+ },
+ {
+ type: EventType.TEXT_MESSAGE_START,
+ messageId: "msg-1#1",
+ role: "assistant",
+ },
+ {
+ type: EventType.TEXT_MESSAGE_CONTENT,
+ messageId: "msg-1#1",
+ delta: "root = Card()",
+ },
+ {
+ type: EventType.TEXT_MESSAGE_END,
+ messageId: "msg-1#1",
+ },
+ ]);
+ });
+
it("handles non-tuple message format (plain object)", async () => {
const body =
sse("messages", { type: "ai", content: "plain", id: "msg-1" }) + sse("end", null);
@@ -196,8 +257,132 @@ describe("langGraphAdapter", () => {
expect((toolArgs as any).delta).toBe('{"query":"test"}');
const toolEnd = events.filter((e: any) => e.type === EventType.TOOL_CALL_END);
- // One from the complete tool_calls handling + one from the "end" event cleanup
- expect(toolEnd.length).toBeGreaterThanOrEqual(1);
+ expect(toolEnd).toHaveLength(1);
+ });
+
+ it("preserves model → tool result → model ordering across graph steps", async () => {
+ const body =
+ sse("messages", [
+ {
+ type: "ai",
+ id: "ai-call",
+ content: "",
+ tool_calls: [{ id: "call-1", name: "get_weather", args: { location: "Berlin" } }],
+ },
+ { langgraph_node: "model", langgraph_step: 1 },
+ ]) +
+ sse("messages", [
+ {
+ type: "tool",
+ id: "tool-result",
+ content: '{"temperature_c":21}',
+ tool_call_id: "call-1",
+ status: "success",
+ },
+ { langgraph_node: "tools", langgraph_step: 2 },
+ ]) +
+ sse("messages", [
+ { type: "ai", id: "ai-final", content: "It is 21°C." },
+ { langgraph_node: "model", langgraph_step: 3 },
+ ]) +
+ sse("end", null);
+
+ const events = await collect(langGraphAdapter().parse(makeSSEResponse(body)));
+
+ expect(events.map((event: any) => event.type)).toEqual([
+ EventType.TEXT_MESSAGE_START,
+ EventType.TOOL_CALL_START,
+ EventType.TOOL_CALL_ARGS,
+ EventType.TOOL_CALL_END,
+ EventType.TEXT_MESSAGE_END,
+ EventType.TOOL_CALL_RESULT,
+ EventType.TEXT_MESSAGE_START,
+ EventType.TEXT_MESSAGE_CONTENT,
+ EventType.TEXT_MESSAGE_END,
+ ]);
+ expect(events.filter((event: any) => event.type === EventType.TEXT_MESSAGE_START)).toEqual([
+ expect.objectContaining({ messageId: "ai-call" }),
+ expect.objectContaining({ messageId: "ai-final" }),
+ ]);
+ expect(events.find((event: any) => event.type === EventType.TOOL_CALL_RESULT)).toMatchObject({
+ messageId: "tool-result",
+ toolCallId: "call-1",
+ content: '{"temperature_c":21}',
+ });
+ });
+
+ it("closes a streamed tool call once when its ToolMessage arrives", async () => {
+ const body =
+ sse("messages", [
+ {
+ type: "AIMessageChunk",
+ id: "ai-call",
+ content: "",
+ tool_call_chunks: [{ id: "call-1", name: "get_weather", args: '{"', index: 0 }],
+ // LangChain projects partial chunks here too. The projection is
+ // incomplete and must not be consumed alongside the chunks.
+ tool_calls: [{ id: "call-1", name: "get_weather", args: {} }],
+ },
+ { langgraph_node: "model", langgraph_step: 1 },
+ ]) +
+ sse("messages", [
+ {
+ type: "AIMessageChunk",
+ id: "ai-call",
+ content: "",
+ tool_call_chunks: [{ args: 'location":"Berlin"}', index: 0 }],
+ },
+ { langgraph_node: "model", langgraph_step: 1 },
+ ]) +
+ sse("messages", [
+ {
+ type: "ToolMessage",
+ id: "tool-result",
+ content: "done",
+ tool_call_id: "call-1",
+ status: "success",
+ },
+ { langgraph_node: "tools", langgraph_step: 2 },
+ ]) +
+ sse("end", null);
+
+ const events = await collect(langGraphAdapter().parse(makeSSEResponse(body)));
+
+ expect(events.filter((event: any) => event.type === EventType.TOOL_CALL_END)).toHaveLength(1);
+ expect(events.filter((event: any) => event.type === EventType.TOOL_CALL_RESULT)).toHaveLength(
+ 1,
+ );
+ expect(
+ events
+ .filter((event: any) => event.type === EventType.TOOL_CALL_ARGS)
+ .map((event: any) => event.delta)
+ .join(""),
+ ).toBe('{"location":"Berlin"}');
+ });
+
+ it("surfaces an errored ToolMessage as an errored tool result", async () => {
+ const body = sse("messages", [
+ {
+ type: "tool",
+ id: "tool-result",
+ content: "lookup failed",
+ tool_call_id: "call-1",
+ status: "error",
+ },
+ { langgraph_node: "tools", langgraph_step: 2 },
+ ]);
+
+ const events = await collect(langGraphAdapter().parse(makeSSEResponse(body)));
+
+ expect(events).toEqual([
+ expect.objectContaining({
+ type: EventType.TOOL_CALL_RESULT,
+ toolCallId: "call-1",
+ content: "lookup failed",
+ isError: true,
+ error: "lookup failed",
+ }),
+ ]);
});
});
diff --git a/packages/react-headless/src/stream/adapters/__tests__/vercel-ai-sdk.test.ts b/packages/react-headless/src/stream/adapters/__tests__/vercel-ai-sdk.test.ts
index 6014eddb4..6687b5d3f 100644
--- a/packages/react-headless/src/stream/adapters/__tests__/vercel-ai-sdk.test.ts
+++ b/packages/react-headless/src/stream/adapters/__tests__/vercel-ai-sdk.test.ts
@@ -154,6 +154,116 @@ describe("vercelAIAdapter", () => {
]);
});
+ it("splits regular text that follows tool calls onto a new AG-UI message", async () => {
+ const events = await parse(
+ sse({ type: "start-step" }) +
+ sse({ type: "text-start", id: "text-1" }) +
+ sse({ type: "text-delta", id: "text-1", delta: "Let me do this" }) +
+ sse({ type: "text-end", id: "text-1" }) +
+ sse({
+ type: "tool-input-available",
+ toolCallId: "call-1",
+ toolName: "get_weather",
+ input: { location: "Berlin" },
+ }) +
+ sse({ type: "tool-output-available", toolCallId: "call-1", output: { temp: 21 } }) +
+ sse({ type: "text-start", id: "text-2" }) +
+ sse({ type: "text-delta", id: "text-2", delta: "root = Card()" }) +
+ sse({ type: "text-end", id: "text-2" }) +
+ sse({ type: "finish-step" }),
+ );
+
+ expect(
+ events.filter(
+ (event) =>
+ event.type === EventType.TEXT_MESSAGE_START ||
+ event.type === EventType.TEXT_MESSAGE_CONTENT ||
+ event.type === EventType.TEXT_MESSAGE_END,
+ ),
+ ).toEqual([
+ {
+ type: EventType.TEXT_MESSAGE_START,
+ messageId: "text-1",
+ role: "assistant",
+ },
+ {
+ type: EventType.TEXT_MESSAGE_CONTENT,
+ messageId: "text-1",
+ delta: "Let me do this",
+ },
+ {
+ type: EventType.TEXT_MESSAGE_END,
+ messageId: "text-1",
+ },
+ {
+ type: EventType.TEXT_MESSAGE_START,
+ messageId: "text-2",
+ role: "assistant",
+ },
+ {
+ type: EventType.TEXT_MESSAGE_CONTENT,
+ messageId: "text-2",
+ delta: "root = Card()",
+ },
+ {
+ type: EventType.TEXT_MESSAGE_END,
+ messageId: "text-2",
+ },
+ ]);
+ });
+
+ it("splits text around a server-executed dynamic tool inside one model step", async () => {
+ // Cloud-run tools (artifacts, image/web search, MCP) don't end the AI SDK
+ // step, so commentary and the answer land in the same step. They reach the
+ // client as ordinary dynamic tool chunks, so the split is tool-type agnostic.
+ const events = await parse(
+ sse({ type: "start-step" }) +
+ sse({ type: "text-start", id: "text-1" }) +
+ sse({ type: "text-delta", id: "text-1", delta: "Let me look that up" }) +
+ sse({ type: "text-end", id: "text-1" }) +
+ sse({
+ type: "tool-input-start",
+ toolCallId: "mcp-1",
+ toolName: "deepwiki_search",
+ dynamic: true,
+ }) +
+ sse({
+ type: "tool-input-available",
+ toolCallId: "mcp-1",
+ toolName: "deepwiki_search",
+ input: { query: "OpenUI" },
+ dynamic: true,
+ }) +
+ sse({
+ type: "tool-output-available",
+ toolCallId: "mcp-1",
+ output: { hits: 2 },
+ dynamic: true,
+ }) +
+ sse({ type: "text-start", id: "text-2" }) +
+ sse({ type: "text-delta", id: "text-2", delta: "root = Card()" }) +
+ sse({ type: "text-end", id: "text-2" }) +
+ sse({ type: "finish-step" }),
+ );
+
+ expect(
+ events
+ .filter((event) => "messageId" in event && event.type !== EventType.TOOL_CALL_RESULT)
+ .map((event) => [event.type, (event as { messageId: string }).messageId]),
+ ).toEqual([
+ [EventType.TEXT_MESSAGE_START, "text-1"],
+ [EventType.TEXT_MESSAGE_CONTENT, "text-1"],
+ [EventType.TEXT_MESSAGE_END, "text-1"],
+ [EventType.TEXT_MESSAGE_START, "text-2"],
+ [EventType.TEXT_MESSAGE_CONTENT, "text-2"],
+ [EventType.TEXT_MESSAGE_END, "text-2"],
+ ]);
+ expect(events.find((event) => event.type === EventType.TOOL_CALL_START)).toMatchObject({
+ toolCallId: "mcp-1",
+ parentMessageId: "text-1",
+ });
+ });
+
it("maps text start, delta, and end chunks", async () => {
const events = await parse(
sse({ type: "text-start", id: "text-1" }) +
diff --git a/packages/react-headless/src/stream/adapters/langgraph.ts b/packages/react-headless/src/stream/adapters/langgraph.ts
index 3e3f91fdc..3dacd0920 100644
--- a/packages/react-headless/src/stream/adapters/langgraph.ts
+++ b/packages/react-headless/src/stream/adapters/langgraph.ts
@@ -1,17 +1,16 @@
import { AGUIEvent, EventType, StreamProtocolAdapter } from "../../types";
-/**
- * Represents a LangGraph AI message (or chunk) as received in the
- * `messages` stream mode.
- */
+type LangGraphContent = string | Array<{ type: string; text?: string }>;
+
+/** LangGraph AI message (or chunk) received in `messages` stream mode. */
interface LangGraphAIMessage {
id?: string;
type: "ai" | "AIMessageChunk" | "AIMessage";
- content: string | Array<{ type: string; text?: string }>;
+ content: LangGraphContent;
tool_calls?: Array<{
id: string;
name: string;
- args: Record<string, unknown>;
+ args: Record<string, unknown> | string;
}>;
tool_call_chunks?: Array<{
id?: string;
@@ -21,6 +20,17 @@ interface LangGraphAIMessage {
}>;
}
+/** LangGraph tool result (or chunk) received between model invocations. */
+interface LangGraphToolMessage {
+ id?: string;
+ type: "tool" | "ToolMessage" | "ToolMessageChunk";
+ content: LangGraphContent;
+ tool_call_id: string;
+ status?: "success" | "error";
+}
+
+type LangGraphMessage = LangGraphAIMessage | LangGraphToolMessage;
+
/**
* Metadata attached to each message tuple in the `messages` stream mode.
*/
@@ -50,7 +60,7 @@ export interface LangGraphAdapterOptions {
* LangGraph uses named SSE events (`event: <type>\ndata: <json>\n\n`)
* rather than the `data:`-only format used by OpenAI. The adapter handles
* the `messages`, `metadata`, `updates`, and `error` event types and maps
- * them to AG-UI events.
+ * model steps and tool results to ordered AG-UI events.
*
* Usage:
* ```tsx
@@ -66,9 +76,19 @@ export const langGraphAdapter = (options?: LangGraphAdapterOptions): StreamProto
if (!reader) throw new Error("No response body");
const decoder = new TextDecoder();
- const messageId = crypto.randomUUID();
- const toolCallIds: Record<number, string> = {};
+ let fallbackMessageId = crypto.randomUUID();
+ let currentMessageId: string | null = null;
+ let currentGraphStep: number | undefined;
+ const toolCallIdsByIndex = new Map<number, string>();
+ const startedToolCallIds = new Set<string>();
+ const openToolCallIds = new Set<string>();
+ const toolCallArgsSeen = new Set<string>();
+ // Every id already spent on an assistant segment, so a repeated wire id can
+ // be given a distinct one (see the segment-opening branch below).
+ const usedMessageIds = new Set<string>();
+ let duplicateMessageIds = 0;
let messageStarted = false;
+ let sawToolsOnCurrentMessage = false;
let buffer = "";
while (true) {
@@ -112,32 +132,101 @@ export const langGraphAdapter = (options?: LangGraphAdapterOptions): StreamProto
case "messages": {
// Payload is a tuple: [message_chunk, metadata]
// or just a message object depending on the stream version.
- const tuple = parsed as
- [LangGraphAIMessage, LangGraphMessageMetadata] | LangGraphAIMessage;
+ const tuple = parsed as [LangGraphMessage, LangGraphMessageMetadata] | LangGraphMessage;
+ const msg = Array.isArray(tuple) ? tuple[0] : tuple;
+ const metadata = Array.isArray(tuple) ? tuple[1] : undefined;
+
+ if (isToolMessage(msg)) {
+ // A ToolMessage marks the end of the model step that requested
+ // the tool. Close both the call and assistant segment before
+ // emitting its result so live history remains ai → tool → ai.
+ if (openToolCallIds.delete(msg.tool_call_id)) {
+ yield {
+ type: EventType.TOOL_CALL_END,
+ toolCallId: msg.tool_call_id,
+ };
+ }
+ if (messageStarted && currentMessageId) {
+ yield {
+ type: EventType.TEXT_MESSAGE_END,
+ messageId: currentMessageId,
+ };
+ }
+ messageStarted = false;
+ currentMessageId = null;
+ sawToolsOnCurrentMessage = false;
+ currentGraphStep = undefined;
+ fallbackMessageId = crypto.randomUUID();
+ toolCallIdsByIndex.clear();
+
+ const content = serializeToolContent(msg.content);
+ yield {
+ type: EventType.TOOL_CALL_RESULT,
+ messageId: msg.id ?? `tool-result-${msg.tool_call_id}`,
+ toolCallId: msg.tool_call_id,
+ content,
+ role: "tool",
+ ...(msg.status === "error" ? { isError: true, error: content } : {}),
+ } as AGUIEvent;
+ break;
+ }
- const msg: LangGraphAIMessage = Array.isArray(tuple) ? tuple[0] : tuple;
+ if (!isAIMessage(msg)) break;
- // Only handle AI messages
- if (msg.type !== "ai" && msg.type !== "AIMessageChunk" && msg.type !== "AIMessage") {
- break;
+ const graphStep = metadata?.langgraph_step;
+ const graphStepChanged =
+ graphStep !== undefined &&
+ currentGraphStep !== undefined &&
+ graphStep !== currentGraphStep;
+ let nextMessageId =
+ msg.id ??
+ (graphStep === undefined ? fallbackMessageId : `langgraph-step-${graphStep}`);
+
+ const textContent = extractTextContent(msg.content);
+ // Text after tool calls is a new assistant item so commentary like
+ // "Let me do this" stays on the tool-bearing message and the answer
+ // text after it is not concatenated onto the same message.
+ const splitAfterTools = !!textContent && sawToolsOnCurrentMessage && messageStarted;
+
+ const isNewModelStep =
+ !messageStarted ||
+ nextMessageId !== currentMessageId ||
+ graphStepChanged ||
+ splitAfterTools;
+
+ // LangGraph repeats a wire id across segment boundaries — both when
+ // the graph step advances and after a tool call — so an id already
+ // spent on a closed segment needs a fresh one for consumers to keep
+ // both. Only when opening a segment: mid-message chunks must keep
+ // streaming into currentMessageId.
+ if (isNewModelStep && usedMessageIds.has(nextMessageId)) {
+ nextMessageId = `${nextMessageId}#${++duplicateMessageIds}`;
}
- // Emit TEXT_MESSAGE_START on first AI message chunk
- if (!messageStarted) {
+ if (isNewModelStep) {
+ if (messageStarted && currentMessageId) {
+ yield {
+ type: EventType.TEXT_MESSAGE_END,
+ messageId: currentMessageId,
+ };
+ }
+ currentMessageId = nextMessageId;
+ usedMessageIds.add(nextMessageId);
+ currentGraphStep = graphStep;
+ sawToolsOnCurrentMessage = false;
+ toolCallIdsByIndex.clear();
yield {
type: EventType.TEXT_MESSAGE_START,
- messageId,
+ messageId: currentMessageId,
role: "assistant",
};
messageStarted = true;
}
- // Handle text content
- const textContent = extractTextContent(msg.content);
if (textContent) {
yield {
type: EventType.TEXT_MESSAGE_CONTENT,
- messageId,
+ messageId: currentMessageId!,
delta: textContent,
};
}
@@ -147,52 +236,64 @@ export const langGraphAdapter = (options?: LangGraphAdapterOptions): StreamProto
for (const chunk of msg.tool_call_chunks) {
const index = chunk.index ?? 0;
- if (chunk.id && !toolCallIds[index]) {
- toolCallIds[index] = chunk.id;
+ if (chunk.id) toolCallIdsByIndex.set(index, chunk.id);
+ const toolCallId = chunk.id ?? toolCallIdsByIndex.get(index);
+
+ if (toolCallId && !startedToolCallIds.has(toolCallId)) {
+ startedToolCallIds.add(toolCallId);
+ openToolCallIds.add(toolCallId);
+ sawToolsOnCurrentMessage = true;
yield {
type: EventType.TOOL_CALL_START,
- toolCallId: chunk.id,
+ toolCallId,
toolCallName: chunk.name || "",
};
}
- if (chunk.args) {
- const toolCallId = toolCallIds[index];
- if (toolCallId) {
- yield {
- type: EventType.TOOL_CALL_ARGS,
- toolCallId,
- delta: chunk.args,
- };
- }
+ if (chunk.args && toolCallId) {
+ toolCallArgsSeen.add(toolCallId);
+ yield {
+ type: EventType.TOOL_CALL_ARGS,
+ toolCallId,
+ delta: chunk.args,
+ };
}
}
}
- // Handle complete tool calls (non-streaming, full args at once)
- if (msg.tool_calls && msg.tool_calls.length > 0) {
+ // Handle complete tool calls only for non-streaming messages.
+ // LangChain chunks can also carry a provisional tool_calls
+ // projection (often with args: {}). tool_call_chunks is the
+ // authoritative source whenever that field is present.
+ if (msg.tool_call_chunks === undefined && msg.tool_calls && msg.tool_calls.length > 0) {
for (let i = 0; i < msg.tool_calls.length; i++) {
const tc = msg.tool_calls[i];
if (!tc) continue;
const toolCallId = tc.id || crypto.randomUUID();
- // Only emit if we haven't already started this tool call
- // via tool_call_chunks
- if (!Object.values(toolCallIds).includes(toolCallId)) {
+ if (!startedToolCallIds.has(toolCallId)) {
+ startedToolCallIds.add(toolCallId);
+ openToolCallIds.add(toolCallId);
+ sawToolsOnCurrentMessage = true;
yield {
type: EventType.TOOL_CALL_START,
toolCallId,
toolCallName: tc.name,
};
+ }
+ if (!toolCallArgsSeen.has(toolCallId)) {
const argsStr = typeof tc.args === "string" ? tc.args : JSON.stringify(tc.args);
+ toolCallArgsSeen.add(toolCallId);
yield {
type: EventType.TOOL_CALL_ARGS,
toolCallId,
delta: argsStr,
};
+ }
+ if (openToolCallIds.delete(toolCallId)) {
yield {
type: EventType.TOOL_CALL_END,
toolCallId,
@@ -229,16 +330,17 @@ export const langGraphAdapter = (options?: LangGraphAdapterOptions): StreamProto
// Stream has ended — close out any open message/tool calls.
if (messageStarted) {
// End any open streaming tool calls
- for (const toolCallId of Object.values(toolCallIds)) {
+ for (const toolCallId of openToolCallIds) {
yield {
type: EventType.TOOL_CALL_END,
toolCallId,
};
}
+ openToolCallIds.clear();
yield {
type: EventType.TEXT_MESSAGE_END,
- messageId,
+ messageId: currentMessageId!,
};
messageStarted = false; // Prevent duplicate end in fallback
}
@@ -256,15 +358,16 @@ export const langGraphAdapter = (options?: LangGraphAdapterOptions): StreamProto
// If stream ended without an explicit "end" event, close out.
if (messageStarted) {
- for (const toolCallId of Object.values(toolCallIds)) {
+ for (const toolCallId of openToolCallIds) {
yield {
type: EventType.TOOL_CALL_END,
toolCallId,
};
}
+ openToolCallIds.clear();
yield {
type: EventType.TEXT_MESSAGE_END,
- messageId,
+ messageId: currentMessageId!,
};
}
},
@@ -307,3 +410,17 @@ function extractTextContent(content: string | Array<{ type: string; text?: strin
.map((block) => block.text!)
.join("");
}
+
+function serializeToolContent(content: LangGraphContent): string {
+ return typeof content === "string" ? content : JSON.stringify(content);
+}
+
+function isAIMessage(message: LangGraphMessage): message is LangGraphAIMessage {
+ return message.type === "ai" || message.type === "AIMessage" || message.type === "AIMessageChunk";
+}
+
+function isToolMessage(message: LangGraphMessage): message is LangGraphToolMessage {
+ return (
+ message.type === "tool" || message.type === "ToolMessage" || message.type === "ToolMessageChunk"
+ );
+}
diff --git a/packages/react-headless/src/stream/adapters/vercel-ai-sdk.ts b/packages/react-headless/src/stream/adapters/vercel-ai-sdk.ts
index b52d749a1..353c448bb 100644
--- a/packages/react-headless/src/stream/adapters/vercel-ai-sdk.ts
+++ b/packages/react-headless/src/stream/adapters/vercel-ai-sdk.ts
@@ -90,6 +90,9 @@ export const vercelAIAdapter = (): StreamProtocolAdapter => ({
stepName: string;
messageId?: string;
messageStarted: boolean;
+ // Per-step, so a new step resets it without an explicit assignment.
+ // Only ever read while a step message is open (see beginText).
+ sawTools: boolean;
}
| undefined;
@@ -105,6 +108,29 @@ export const vercelAIAdapter = (): StreamProtocolAdapter => ({
};
};
+ // Single entry point for "a text chunk arrived": opens the step's message,
+ // or closes it and opens a new one when the text follows tool calls.
+ //
+ // Text that follows tool calls is a new assistant item: commentary like
+ // "Let me do this" stays on the tool-bearing message and the answer text
+ // after it gets its own message id, so a consumer splitting on
+ // TEXT_MESSAGE_START keeps both. Streams without `start-step` already give
+ // each text part a distinct id, so only the step-scoped message needs this.
+ const beginText = (partId: string): AGUIEvent[] => {
+ if (activeStep?.messageStarted && activeStep.sawTools) {
+ const previousId = activeStep.messageId!;
+ activeStep.messageId = partId;
+ activeStep.sawTools = false;
+ return [
+ { type: EventType.TEXT_MESSAGE_END, messageId: previousId },
+ { type: EventType.TEXT_MESSAGE_START, messageId: partId, role: "assistant" },
+ ];
+ }
+
+ const event = startStepMessage(partId);
+ return event ? [event] : [];
+ };
+
const toolParent = () =>
activeStep?.messageId ? { parentMessageId: activeStep.messageId } : {};
@@ -116,7 +142,7 @@ export const vercelAIAdapter = (): StreamProtocolAdapter => ({
switch (chunk.type) {
case "start-step": {
const stepName = `vercel-ai-step-${++stepIndex}`;
- activeStep = { stepName, messageStarted: false };
+ activeStep = { stepName, messageStarted: false, sawTools: false };
yield {
type: EventType.STEP_STARTED,
stepName,
@@ -141,8 +167,7 @@ export const vercelAIAdapter = (): StreamProtocolAdapter => ({
}
case "text-start": {
- const event = startStepMessage(chunk.id);
- if (event) yield event;
+ for (const event of beginText(chunk.id)) yield event;
if (!activeStep) {
yield {
type: EventType.TEXT_MESSAGE_START,
@@ -154,8 +179,7 @@ export const vercelAIAdapter = (): StreamProtocolAdapter => ({
}
case "text-delta": {
- const event = startStepMessage(chunk.id);
- if (event) yield event;
+ for (const event of beginText(chunk.id)) yield event;
yield {
type: EventType.TEXT_MESSAGE_CONTENT,
messageId: activeStep?.messageId ?? chunk.id,
@@ -178,6 +202,7 @@ export const vercelAIAdapter = (): StreamProtocolAdapter => ({
const event = startStepMessage();
if (event) yield event;
startedTools.add(chunk.toolCallId);
+ if (activeStep) activeStep.sawTools = true;
yield {
type: EventType.TOOL_CALL_START,
toolCallId: chunk.toolCallId,
@@ -204,6 +229,7 @@ export const vercelAIAdapter = (): StreamProtocolAdapter => ({
const event = startStepMessage();
if (event) yield event;
startedTools.add(chunk.toolCallId);
+ if (activeStep) activeStep.sawTools = true;
yield {
type: EventType.TOOL_CALL_START,
toolCallId: chunk.toolCallId,
diff --git a/packages/react-headless/src/stream/formats/vercel-ai-message-format.ts b/packages/react-headless/src/stream/formats/vercel-ai-message-format.ts
index dd82b7c76..02cf95655 100644
--- a/packages/react-headless/src/stream/formats/vercel-ai-message-format.ts
+++ b/packages/react-headless/src/stream/formats/vercel-ai-message-format.ts
@@ -378,7 +378,9 @@ function appendAssistantSegments(message: ValidUIMessage, result: Message[]): vo
if (value.type === "text" && typeof value.text === "string") {
// AI SDK step markers are authoritative. Older/custom UIMessage data may
// omit them, so retain the previous text-part boundary behavior there.
- if (!hasStepMarkers && hasBody()) flush();
+ // Text after tool calls is always a new item (commentary between calls,
+ // then the answer), matching the live adapter.
+ if (toolCalls.length > 0 || (!hasStepMarkers && hasBody())) flush();
segmentStarted = true;
text += value.text;
continue;
diff --git a/packages/react-headless/src/stream/processStreamedMessage.ts b/packages/react-headless/src/stream/processStreamedMessage.ts
index e22f46291..ed1235bd9 100644
--- a/packages/react-headless/src/stream/processStreamedMessage.ts
+++ b/packages/react-headless/src/stream/processStreamedMessage.ts
@@ -62,18 +62,61 @@ export const processStreamedMessage = async ({
});
};
+ /** Flush the open assistant and start a fresh one (interleaved segments). */
+ const startNewAssistantSegment = () => {
+ if (rafId !== null) {
+ cancelAnimationFrame(rafId);
+ rafId = null;
+ if (!isFirst) updateMessage(currentMessage);
+ }
+ currentMessage = {
+ id: crypto.randomUUID(),
+ role: "assistant",
+ content: "",
+ toolCalls: [],
+ };
+ isFirst = true;
+ currentTextItemId = null;
+ };
+
+ const messageHasBody = (msg: AssistantMessage) =>
+ (msg.content?.length ?? 0) > 0 || (msg.toolCalls?.length ?? 0) > 0;
+
+ /** Publish the open assistant only once it has text or tool calls — never an empty shell. */
+ const commitCurrentMessage = () => {
+ if (isFirst) {
+ if (!messageHasBody(currentMessage)) return;
+ createMessage(currentMessage);
+ isFirst = false;
+ } else {
+ debouncedUpdate(currentMessage);
+ }
+ };
+
for await (const event of adapter.parse(response)) {
switch (event.type) {
// TEXT_MESSAGE_CHUNK and TEXT_MESSAGE_CONTENT are very similar events but TEXT_MESSAGE_CHUNK
// optionally allows for a role change. Since we don't support role changes in processMessage
// right now, we treat both the same.
case EventType.TEXT_MESSAGE_CHUNK:
- case EventType.TEXT_MESSAGE_CONTENT:
+ case EventType.TEXT_MESSAGE_CONTENT: {
+ // Ignore empty deltas — a zero-length content event after tools would
+ // otherwise open a blank assistant segment that shadows the real answer
+ // (common around parallel tool calls when a new message item is opened).
+ if (!event.delta) break;
+ // Some adapters (LangGraph / ChatOpenAI Responses) keep one wire
+ // messageId for a whole model step even when Responses interleaved
+ // several message items. Text after tools means a new segment — same
+ // split Responses adapters express via a new TEXT_MESSAGE_START id.
+ if ((currentMessage.toolCalls?.length ?? 0) > 0) {
+ startNewAssistantSegment();
+ }
currentMessage = {
...currentMessage,
content: (currentMessage.content || "") + event.delta,
};
break;
+ }
case EventType.TOOL_CALL_START:
inFlightToolCallIds.add(event.toolCallId);
@@ -166,20 +209,7 @@ export const processStreamedMessage = async ({
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;
+ startNewAssistantSegment();
}
currentTextItemId = startId;
break;
@@ -248,19 +278,16 @@ export const processStreamedMessage = async ({
}
}
- if (isFirst) {
- createMessage(currentMessage);
- isFirst = false;
- } else {
- // debounce the message update using raf
- debouncedUpdate(currentMessage);
- }
+ commitCurrentMessage();
}
if (rafId !== null) {
// flush any update
cancelAnimationFrame(rafId);
updateMessage(currentMessage);
+ } else if (isFirst && messageHasBody(currentMessage)) {
+ // Last event was a no-op (e.g. empty delta) after body landed in memory only.
+ createMessage(currentMessage);
}
return currentMessage;
diff --git a/packages/react-ui/package.json b/packages/react-ui/package.json
index 0d2a3fcd9..ed0b7ef0a 100644
--- a/packages/react-ui/package.json
+++ b/packages/react-ui/package.json
@@ -2,7 +2,7 @@
"type": "module",
"name": "@openuidev/react-ui",
"license": "MIT",
- "version": "0.13.8",
+ "version": "0.13.9",
"description": "Component library for Generative UI SDK",
"main": "dist/index.cjs",
"module": "dist/index.mjs",
diff --git a/packages/react-ui/src/components/AgentInterface/Thread.tsx b/packages/react-ui/src/components/AgentInterface/Thread.tsx
index ee509ecfa..f6bb2ea04 100644
--- a/packages/react-ui/src/components/AgentInterface/Thread.tsx
+++ b/packages/react-ui/src/components/AgentInterface/Thread.tsx
@@ -367,13 +367,23 @@ const InterleavedTurn = ({
isRunning: boolean;
lastAssistantId: string | null;
}) => {
- const last = segments[segments.length - 1]!;
+ // Ignore trailing empty assistants (e.g. TEXT_MESSAGE_START after parallel
+ // tools with no content yet / never). Those would become `last` and blank the
+ // answer slot until a chat remount rebuilds from storage.
+ const activeSegments = useMemo(() => {
+ const withBody = segments.filter(
+ (s) => (s.content?.length ?? 0) > 0 || (s.toolCalls?.length ?? 0) > 0,
+ );
+ return withBody.length > 0 ? withBody : segments;
+ }, [segments]);
+
+ const last = activeSegments[activeSegments.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],
+ () => ({ ...activeSegments[0]!, toolCalls: activeSegments.flatMap((s) => s.toolCalls ?? []) }),
+ [activeSegments],
);
const turnActivities = useToolActivities(turnMessage, allMessages);
@@ -387,18 +397,30 @@ const InterleavedTurn = ({
const steps = useMemo<TimelineStep[]>(() => {
const byCallId = new Map(turnActivities.map((a) => [a.toolCall.id, a]));
const rows: TimelineStep[] = [];
- for (const seg of segments) {
+ const claimed = new Set<string>();
+ for (const seg of activeSegments) {
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 });
+ if (activity) {
+ rows.push({ type: "activity", activity });
+ claimed.add(tc.id);
+ }
}
}
+ // Provider-executed tools (OpenUI Cloud reports, search, MCP) arrive as tool
+ // results whose call sits on no assistant message, so `pairToolActivity`
+ // synthesizes them as orphans. No segment claims those, and dropping them
+ // both hid the activity and could leave `rows` empty while `turnActivities`
+ // was not — which crashed the timeline. Append them in arrival order.
+ for (const activity of turnActivities) {
+ if (!claimed.has(activity.toolCall.id)) rows.push({ type: "activity", activity });
+ }
return rows;
- }, [segments, turnActivities, answer?.id]);
+ }, [activeSegments, turnActivities, answer?.id]);
// Matched renderers (artifact/search previews) render OUTSIDE the tray so
// they stay visible after it collapses.
diff --git a/packages/react-ui/src/components/ToolCall/ToolCallTimeline.tsx b/packages/react-ui/src/components/ToolCall/ToolCallTimeline.tsx
index 980ee84f4..bde46e296 100644
--- a/packages/react-ui/src/components/ToolCall/ToolCallTimeline.tsx
+++ b/packages/react-ui/src/components/ToolCall/ToolCallTimeline.tsx
@@ -239,7 +239,10 @@ export function ToolCallTimeline({
}
}, [isThreadRunning, revealedCount, displaySteps.length]);
- if (activities.length === 0) return null;
+ // Guard the array that is actually indexed below. `steps` is caller-supplied
+ // and can be empty even when `activities` is not, and `??` keeps an empty
+ // array rather than falling back to `activities`.
+ if (activities.length === 0 || displaySteps.length === 0) return null;
const revealing = revealedCount < displaySteps.length;
const showCompact = (thinking || revealing) && !expanded && !userCollapsed;