@assistant-ui/react-ag-ui 0.0.65 → 0.0.67

package/src/runtime/adapter/conversions.content.test.ts

@@ -40,6 +40,47 @@ const appendMessage = (): AppendMessage => ({
   metadata: { custom: {} },
 });
 
+describe("toAgUiMessages data URLs", () => {
+  it.each(["application/pdf", ""])(
+    "unwraps a media-less data URL while retaining the adapter's %j MIME fallback",
+    (mimeType) => {
+      expect(
+        contentOf(
+          userMessage([
+            { type: "file", data: "data:;base64,SGVsbG8=", mimeType },
+          ]),
+        ),
+      ).toEqual([
+        {
+          type: "document",
+          source: {
+            type: "data",
+            value: "SGVsbG8=",
+            mimeType: mimeType || "application/octet-stream",
+          },
+        },
+      ]);
+    },
+  );
+
+  it("sniffs a media-less image data URL", () => {
+    expect(
+      contentOf(
+        userMessage([{ type: "image", image: "data:;base64,iVBORw0KGgo=" }]),
+      ),
+    ).toEqual([
+      {
+        type: "image",
+        source: {
+          type: "data",
+          value: "iVBORw0KGgo=",
+          mimeType: "image/png",
+        },
+      },
+    ]);
+  });
+});
+
 describe("toAgUiMessages content metadata", () => {
   it("emits AgUiMessage values assignable to AG-UI Message", () => {
     expectTypeOf<AgUiMessage>().toExtend<AgUiWireMessage>();

package/src/runtime/adapter/conversions.ts

@@ -11,6 +11,7 @@ import {
   getAutoStatus,
   parseDataUrl,
   resolveFilePartSource,
+  resolveImageMediaType,
   walkToolCallTree,
 } from "@assistant-ui/core/internal";
 import { type Tool, toToolsJSONSchema } from "assistant-stream";
@@ -21,14 +22,13 @@ import {
   MCP_APPS_ACTIVITY_TYPE,
   type AgUiCustomMetadata,
   type AgUiOpaqueReasoning,
-} from "./run-aggregator";
+} from "../types";
 import {
   applyA2uiOperations,
-  convertSurfaceToUISpec,
-  surfaceToOperations,
+  surfaceToPresentToolCall,
   type A2uiState,
   type A2uiSurfaceState,
-} from "@assistant-ui/react-generative-ui/a2ui";
+} from "@assistant-ui/generative-ui/a2ui";
 import type { AgUiInterrupt } from "../types";
 import { projectAgUiToolApprovals } from "./tool-approval";
 import {
@@ -105,6 +105,7 @@ type CoreToolCallPart = Extract<
 type ToolCallPart = Omit<CoreToolCallPart, "result" | "isError"> & {
   result?: unknown;
   isError?: boolean | undefined;
+  /** @deprecated Experimental since 2026-03-08. Not scheduled for removal; the API may change in any release. */
   unstable_toolMessageId?: string;
 };
 
@@ -276,9 +277,16 @@ function toInputContent(
     const image = getString(part, "image");
     if (image === undefined) return null;
     const metadata = buildInputMetadata(part, getString(part, "filename"));
+    const source = buildInputSource(image, fallbackMimeType);
     return {
       type: "image",
-      source: buildInputSource(image, fallbackMimeType),
+      source:
+        source.type === "data"
+          ? {
+              ...source,
+              mimeType: resolveImageMediaType(image, fallbackMimeType),
+            }
+          : source,
       ...(metadata && { metadata }),
     };
   }
@@ -502,7 +510,6 @@ function toToolCallPart(value: unknown): ToolCallPart | null {
       : isObject(value.args) && !Array.isArray(value.args)
         ? (value.args as ReadonlyJSONObject)
         : undefined;
-
   const part: ToolCallPart = {
     type: "tool-call",
     ...(toolCallId !== undefined ? { toolCallId } : {}),
@@ -693,27 +700,17 @@ function toUserOrSystemSnapshotMessage(
   };
 }
 
-// Rebuilds the a2ui:<surfaceId> "present" tool-call parts for one owning
-// assistant message from a bucket of rebuilt surface state, mirroring the
-// live RunAggregator.synthesizeA2uiToolCalls shape. Non-a2ui parts (text,
-// other tool calls) are preserved; existing a2ui parts are replaced wholesale
-// so create/update/delete within the bucket all converge on the rebuilt set.
 function attachA2uiSurfaces(
   message: CoreThreadMessageLike,
   state: A2uiState,
 ): CoreThreadMessageLike {
   const a2uiParts: ToolCallPart[] = [];
   for (const [surfaceId, surface] of state) {
-    const { spec } = convertSurfaceToUISpec(surface);
-    if (!spec) continue;
+    const { toolCall } = surfaceToPresentToolCall(surfaceId, surface);
+    if (!toolCall) continue;
     a2uiParts.push({
       type: "tool-call",
-      toolCallId: `a2ui:${surfaceId}`,
-      toolName: "present",
-      args: spec as unknown as ReadonlyJSONObject,
-      argsText: JSON.stringify(spec),
-      result: {},
-      artifact: { a2ui: surfaceToOperations(surface) },
+      ...toolCall,
     });
   }
 

package/src/runtime/adapter/run-aggregator.reasoning.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it } from "vitest";
+import type { ChatModelRunResult } from "@assistant-ui/core";
+import { RunAggregator } from "./run-aggregator";
+import type { AgUiCustomMetadata } from "../types";
+import { toAgUiMessages } from "./conversions";
+
+describe.each([true, false])(
+  "reasoning ownership (showThinking=%s)",
+  (showThinking) => {
+    it.each([
+      { parentText: "", nextReasoning: false },
+      { parentText: "", nextReasoning: true },
+      { parentText: "Looking it up.", nextReasoning: false },
+      { parentText: "Looking it up.", nextReasoning: true },
+    ])(
+      "keeps pre-tool reasoning on its parent ($parentText, nextReasoning=$nextReasoning)",
+      ({ parentText, nextReasoning }) => {
+        let latest: ChatModelRunResult = {};
+        let previous: ChatModelRunResult | undefined;
+        const aggregator = new RunAggregator({
+          showThinking,
+          logger: { debug: () => {}, error: () => {} },
+          emit: (update) => {
+            latest = update;
+          },
+          onTextMessageStart: () => {
+            previous = latest;
+          },
+        });
+        const reason = (messageId: string, delta: string) => {
+          aggregator.handle({ type: "REASONING_MESSAGE_START", messageId });
+          aggregator.handle({
+            type: "REASONING_MESSAGE_CONTENT",
+            messageId,
+            delta,
+          });
+          aggregator.handle({ type: "REASONING_MESSAGE_END", messageId });
+          aggregator.handle({
+            type: "REASONING_ENCRYPTED_VALUE",
+            subtype: "message",
+            entityId: messageId,
+            encryptedValue: `sig-${messageId}`,
+          });
+        };
+        const reasoningOf = (result: ChatModelRunResult | undefined) =>
+          result?.content?.flatMap((part) =>
+            part.type === "reasoning" ? [part.text] : [],
+          );
+        const opaqueOf = (result: ChatModelRunResult | undefined) =>
+          (result?.metadata?.custom?.agui as AgUiCustomMetadata | undefined)
+            ?.opaqueReasoning ?? [];
+
+        aggregator.handle({ type: "RUN_STARTED", runId: "run-1" });
+        aggregator.handle({
+          type: "TEXT_MESSAGE_START",
+          messageId: "assistant-1",
+        });
+        if (parentText)
+          aggregator.handle({
+            type: "TEXT_MESSAGE_CONTENT",
+            messageId: "assistant-1",
+            delta: parentText,
+          });
+        reason("r-1", "plan the call");
+        aggregator.handle({
+          type: "TOOL_CALL_START",
+          toolCallId: "call-1",
+          toolCallName: "lookup",
+          parentMessageId: "assistant-1",
+        });
+        aggregator.handle({ type: "TOOL_CALL_END", toolCallId: "call-1" });
+        aggregator.handle({
+          type: "TOOL_CALL_RESULT",
+          toolCallId: "call-1",
+          messageId: "tool-1",
+          content: "ok",
+        });
+        if (nextReasoning) reason("r-2", "write the answer");
+        aggregator.handle({
+          type: "TEXT_MESSAGE_START",
+          messageId: "assistant-2",
+        });
+        aggregator.handle({
+          type: "TEXT_MESSAGE_CONTENT",
+          messageId: "assistant-2",
+          delta: "Done.",
+        });
+        aggregator.handle({ type: "RUN_FINISHED", runId: "run-1" });
+
+        expect(
+          previous?.content?.filter((part) => part.type === "tool-call"),
+        ).toHaveLength(1);
+        expect(
+          latest.content?.filter((part) => part.type === "tool-call"),
+        ).toHaveLength(0);
+        if (showThinking) {
+          expect(reasoningOf(previous)).toEqual(["plan the call"]);
+          expect(reasoningOf(latest)).toEqual(
+            nextReasoning ? ["write the answer"] : [],
+          );
+        } else {
+          expect(opaqueOf(previous)).toEqual([
+            { id: "r-1", encryptedValue: "sig-r-1" },
+          ]);
+          expect(opaqueOf(latest)).toEqual(
+            nextReasoning ? [{ id: "r-2", encryptedValue: "sig-r-2" }] : [],
+          );
+        }
+        const exported = toAgUiMessages([
+          {
+            id: "assistant-1",
+            role: "assistant",
+            content: previous?.content ?? [],
+            metadata: previous?.metadata,
+          },
+          {
+            id: "assistant-2",
+            role: "assistant",
+            content: latest.content ?? [],
+            metadata: latest.metadata,
+          },
+        ]);
+        expect(exported.map((message) => message.id)).toEqual([
+          "r-1",
+          "assistant-1",
+          "tool-1",
+          ...(nextReasoning ? ["r-2"] : []),
+          "assistant-2",
+        ]);
+        expect(
+          exported.flatMap((message) =>
+            message.role === "reasoning"
+              ? [[message.id, message.encryptedValue]]
+              : [],
+          ),
+        ).toEqual([
+          ["r-1", "sig-r-1"],
+          ...(nextReasoning ? [["r-2", "sig-r-2"]] : []),
+        ]);
+      },
+    );
+  },
+);

package/src/runtime/adapter/run-aggregator.ts

@@ -13,19 +13,24 @@ import {
 } from "@assistant-ui/core";
 import {
   applyA2uiOperations,
-  convertSurfaceToUISpec,
-  surfaceToOperations,
+  surfaceToPresentToolCall,
   type A2uiState,
   type A2uiSurfaceState,
-} from "@assistant-ui/react-generative-ui/a2ui";
+} from "@assistant-ui/generative-ui/a2ui";
 import jsonpatch, { type Operation } from "fast-json-patch";
 import { readMcpAppResourceUri } from "../mcp-tool-result";
 import { projectAgUiToolApprovals } from "./tool-approval";
-import type { AgUiEvent, AgUiInterrupt } from "../types";
+import {
+  AG_UI_METADATA_NAMESPACE,
+  A2UI_SURFACE_ACTIVITY_TYPE,
+  MCP_APPS_ACTIVITY_TYPE,
+  type AgUiCustomMetadata,
+  type AgUiEvent,
+  type AgUiInterrupt,
+  type AgUiOpaqueReasoning,
+} from "../types";
 import type { Logger } from "../logger";
 
-export const AG_UI_METADATA_NAMESPACE = "agui";
-
 const ROOT_SCOPE = "";
 
 // Defensive guard against a malformed or cyclic parentToolCallId /
@@ -70,20 +75,6 @@ type BuildContext = {
   };
 };
 
-export type AgUiOpaqueReasoning = {
-  id: string;
-  encryptedValue: string;
-  after?: boolean;
-};
-
-export type AgUiCustomMetadata = {
-  /** Wire role restored on export for messages the internal model cannot
-   * represent (a developer record rides as a system message). */
-  role?: "developer";
-  interrupts?: AgUiInterrupt[];
-  opaqueReasoning?: AgUiOpaqueReasoning[];
-};
-
 type Emit = (update: ChatModelRunResult) => void;
 
 type ToolCallState = {
@@ -178,10 +169,6 @@ const scanJSONContainerDelta = (
   return completed && scanner.state === "complete";
 };
 
-export const MCP_APPS_ACTIVITY_TYPE = "mcp-apps";
-
-export const A2UI_SURFACE_ACTIVITY_TYPE = "a2ui-surface";
-
 export const isPlainObject = (
   value: unknown,
 ): value is Record<string, unknown> =>
@@ -259,6 +246,7 @@ export class RunAggregator {
   >();
   private readonly lastResolvedToolCallIdByScope = new Map<string, string>();
   private readonly partOrder: PartOrderEntry[] = [];
+  private lastReasoningBeforeToolCall: PartOrderEntry | undefined;
   private textPartCounter = 0;
   private serverMessageIdReported = false;
   private reportedServerMessageId: string | undefined;
@@ -748,23 +736,27 @@ export class RunAggregator {
 
     const activeToolCallIds = new Set<string>();
     for (const [surfaceId, surface] of surfaces) {
-      const toolCallId = `a2ui:${surfaceId}`;
-      const { spec, warnings } = convertSurfaceToUISpec(surface);
+      const { toolCall, warnings } = surfaceToPresentToolCall(
+        surfaceId,
+        surface,
+      );
       for (const warning of warnings) {
         this.logger.debug("[agui] a2ui surface conversion warning", warning);
       }
-      if (!spec) continue;
+      if (!toolCall) continue;
+
+      const { toolCallId } = toolCall;
 
       activeToolCallIds.add(toolCallId);
 
       const entry: ToolCallState = {
-        toolCallId,
-        toolCallName: "present",
-        argsText: JSON.stringify(spec),
-        parsedArgs: spec,
-        result: {},
+        toolCallId: toolCall.toolCallId,
+        toolCallName: toolCall.toolName,
+        argsText: toolCall.argsText,
+        parsedArgs: toolCall.args,
+        result: toolCall.result,
         isError: undefined,
-        artifact: { a2ui: surfaceToOperations(surface) },
+        artifact: toolCall.artifact,
         snapshotResultApplied: false,
       };
       if (!this.toolCalls.has(toolCallId)) {
@@ -826,6 +818,7 @@ export class RunAggregator {
     this.activityParts.clear();
     this.lastResolvedToolCallIdByScope.clear();
     this.partOrder.length = 0;
+    this.lastReasoningBeforeToolCall = undefined;
     this.textPartCounter = 0;
     this.activeTextMessageIdByScope.clear();
     this.reportedServerMessageId = undefined;
@@ -859,8 +852,103 @@ export class RunAggregator {
     ) {
       return;
     }
+    const carried = this.takeTrailingReasoning();
+    if (carried.parts.length > 0 || carried.hiddenSignatures.length > 0) {
+      this.emit();
+    }
+    const reasoningPartCounter = this.reasoningPartCounter;
     this.resetMessageParts();
     this.onTextMessageStart(messageId);
+    this.reasoningPartCounter = reasoningPartCounter;
+    this.restoreReasoning(carried);
+  }
+
+  private takeTrailingReasoning() {
+    const parts: {
+      key: string;
+      entry: { buffer: string; timing?: MessagePartTiming };
+      signature: string | undefined;
+      signatureId: string | undefined;
+      reasoningId: string | undefined;
+      anonymous: boolean;
+    }[] = [];
+    let last = this.partOrder.at(-1);
+    while (
+      last?.kind === "reasoning" &&
+      last.subagentRunId === undefined &&
+      last !== this.lastReasoningBeforeToolCall
+    ) {
+      this.partOrder.pop();
+      parts.unshift({
+        key: last.key,
+        entry: this.reasoningParts.get(last.key) ?? { buffer: "" },
+        signature: this.reasoningSignatures.get(last.key),
+        signatureId: this.reasoningSignatureIds.get(last.key),
+        reasoningId: this.reasoningMessageIds.get(last.key),
+        anonymous: this.anonymousReasoningKeys.has(last.key),
+      });
+      last = this.partOrder.at(-1);
+    }
+    const cut = this.partOrder.length;
+    const hiddenSignatures = Array.from(this.hiddenSignatures).filter(
+      ([id]) => this.hiddenSignatureAnchors.get(id)! >= cut,
+    );
+    for (const [id] of hiddenSignatures) {
+      this.hiddenSignatures.delete(id);
+      this.hiddenSignatureAnchors.delete(id);
+    }
+    const hiddenBlockIds = Array.from(this.hiddenBlockAnchors)
+      .filter(([, anchor]) => anchor >= cut)
+      .map(([id]) => id);
+    const hiddenAnonymous =
+      this.hiddenAnonymousAnchor !== undefined &&
+      this.hiddenAnonymousAnchor >= cut;
+    const activeCarried =
+      (this.hiddenActiveReasoning === "identified" &&
+        hiddenBlockIds.length > 0) ||
+      (this.hiddenActiveReasoning === "anonymous" && hiddenAnonymous);
+    return {
+      parts,
+      activeKey: this.activeReasoningKeyByScope.get(ROOT_SCOPE),
+      hiddenSignatures,
+      hiddenBlockIds,
+      hiddenAnonymous,
+      hiddenActiveReasoning: activeCarried
+        ? this.hiddenActiveReasoning
+        : ("none" as const),
+    };
+  }
+
+  private restoreReasoning(
+    carried: ReturnType<RunAggregator["takeTrailingReasoning"]>,
+  ): void {
+    for (const part of carried.parts) {
+      this.partOrder.push({ kind: "reasoning", key: part.key });
+      this.reasoningParts.set(part.key, part.entry);
+      if (part.signature !== undefined)
+        this.reasoningSignatures.set(part.key, part.signature);
+      if (part.signatureId !== undefined)
+        this.reasoningSignatureIds.set(part.key, part.signatureId);
+      if (part.reasoningId !== undefined)
+        this.reasoningMessageIds.set(part.key, part.reasoningId);
+      if (part.anonymous) this.anonymousReasoningKeys.add(part.key);
+    }
+    if (
+      carried.activeKey !== undefined &&
+      this.reasoningParts.has(carried.activeKey)
+    ) {
+      this.activeReasoningKeyByScope.set(ROOT_SCOPE, carried.activeKey);
+    }
+    for (const [id, encryptedValue] of carried.hiddenSignatures) {
+      this.hiddenSignatures.set(id, encryptedValue);
+      this.hiddenSignatureAnchors.set(id, 0);
+    }
+    for (const id of carried.hiddenBlockIds) {
+      this.hiddenReasoningIds.add(id);
+      this.hiddenBlockAnchors.set(id, 0);
+    }
+    if (carried.hiddenAnonymous) this.hiddenAnonymousAnchor = 0;
+    this.hiddenActiveReasoning = carried.hiddenActiveReasoning;
   }
 
   private generateTextKey(): string {
@@ -932,6 +1020,13 @@ export class RunAggregator {
         (part) => part.kind === "tool-call" && part.toolCallId === id,
       )
     ) {
+      // Tool insertion can precede existing reasoning in display order.
+      if (scope === ROOT_SCOPE) {
+        this.lastReasoningBeforeToolCall = this.partOrder.findLast(
+          (part) =>
+            part.kind === "reasoning" && part.subagentRunId === undefined,
+        );
+      }
       this.insertToolPart(scope, id, parentMessageId);
     }
     const state: ToolCallState = {

package/src/runtime/types.ts

@@ -15,11 +15,29 @@ import type { Logger } from "./logger";
 import type { ReadonlyJSONValue } from "assistant-stream/utils";
 import type { McpToolCallResult } from "./mcp-tool-result";
 
+export const AG_UI_METADATA_NAMESPACE = "agui";
+export const MCP_APPS_ACTIVITY_TYPE = "mcp-apps";
+export const A2UI_SURFACE_ACTIVITY_TYPE = "a2ui-surface";
+
+export type AgUiOpaqueReasoning = {
+  id: string;
+  encryptedValue: string;
+  after?: boolean;
+};
+
+export type AgUiCustomMetadata = {
+  /** Wire role restored on export for messages the internal model cannot
+   * represent (a developer record rides as a system message). */
+  role?: "developer";
+  interrupts?: AgUiInterrupt[];
+  opaqueReasoning?: AgUiOpaqueReasoning[];
+};
+
 /**
- * @experimental This API is still under active development and might change without notice.
- *
  * Same as ExternalStoreThreadListAdapter, except `onSwitchToThread` returns
  * the messages (and optional state) to hydrate the thread with.
+ *
+ * @deprecated Experimental since 2026-06-13. Not scheduled for removal; the API may change in any release.
  */
 type SwitchToThreadResult = {
   messages: readonly ThreadMessage[];
@@ -28,6 +46,8 @@ type SwitchToThreadResult = {
    * Set when the thread has a run in flight. The runtime resumes the run
    * after hydrating, the same way `ThreadHistoryAdapter.load()` does when it
    * returns `unstable_resume: true`.
+   *
+   * @deprecated Experimental since 2025-03-31. Not scheduled for removal; the API may change in any release.
    */
   unstable_resume?: boolean;
 };
@@ -50,9 +70,7 @@ export type UseAgUiRuntimeAdapters = {
   voice?: RealtimeVoiceAdapter;
   feedback?: FeedbackAdapter;
   history?: ThreadHistoryAdapter;
-  /**
-   * @experimental This API is still under active development and might change without notice.
-   */
+  /** @deprecated Experimental since 2026-01-28. Not scheduled for removal; the API may change in any release. */
   threadList?: UseAgUiThreadListAdapter;
 };
 
@@ -102,6 +120,8 @@ export type UseAgUiRuntimeOptions = ExternalStoreSharedOptions & {
    * settles, exposing it on `composer.queue` for `ComposerPrimitive.Queue`.
    * The runtime owns the queue lifecycle because flushing needs the agent's
    * send path and the run's own busy and idle edges.
+   *
+   * @deprecated Experimental since 2026-06-04. Not scheduled for removal; the API may change in any release.
    */
   unstable_enableMessageQueue?: boolean | undefined;
   onError?: (e: Error) => void;

package/src/useAgUiRuntime.external-store.test.tsx

@@ -0,0 +1,51 @@
+// @vitest-environment jsdom
+
+import { act, cleanup, renderHook } from "@testing-library/react";
+import type { HttpAgent } from "@ag-ui/client";
+import { afterEach, expect, it, vi } from "vitest";
+import { useAgUiRuntime } from "./useAgUiRuntime";
+
+afterEach(cleanup);
+
+it("exposes the deprecated interrupt methods on the runtime facade", () => {
+  const agent = {
+    runAgent: vi.fn(),
+    abortRun: vi.fn(),
+  } as unknown as HttpAgent;
+  const { result } = renderHook(() => useAgUiRuntime({ agent }));
+
+  expect(Object.hasOwn(result.current, "unstable_getPendingInterrupts")).toBe(
+    true,
+  );
+  expect(
+    Object.hasOwn(result.current, "unstable_submitInterruptResponses"),
+  ).toBe(true);
+  expect(result.current.unstable_getPendingInterrupts()).toEqual([]);
+  expect(result.current.unstable_submitInterruptResponses).toEqual(
+    expect.any(Function),
+  );
+});
+
+it("re-renders when the core publishes a state change", () => {
+  const agent = {
+    runAgent: vi.fn(),
+    abortRun: vi.fn(),
+  } as unknown as HttpAgent;
+  let renders = 0;
+  const { result } = renderHook(() => {
+    renders++;
+    return useAgUiRuntime({ agent });
+  });
+  const initialRenders = renders;
+
+  act(() => {
+    result.current.thread.append({
+      role: "user",
+      content: [{ type: "text", text: "hello" }],
+      startRun: false,
+    });
+  });
+
+  expect(renders).toBeGreaterThan(initialRenders);
+  expect(result.current.thread.getState().messages).toHaveLength(1);
+});