@assistant-ui/react 0.15.3 → 0.15.5

package/src/legacy-runtime/runtime-cores/assistant-transport/types.ts

@@ -92,7 +92,9 @@ export type AssistantTransportProtocol = "data-stream" | "assistant-transport";
 
 export type SendCommandsRequestBody = {
   commands: QueuedCommand[];
-  state: unknown;
+  /** Absent on a resume with `resumeStateApi`; the server replays from its retained snapshot. */
+  state?: unknown;
+  runId?: string;
   system: string | undefined;
   tools: Record<string, unknown> | undefined;
   callSettings: LanguageModelV1CallSettings | undefined;
@@ -109,7 +111,15 @@ export type AssistantTransportOptions<T> = {
   initialState: T;
   api: string;
   resumeApi?: string;
+  /** Endpoint that returns the retained initial state and run ID for a resume stream. A 204 response means no run is active and the resume is skipped. */
+  resumeStateApi?: string;
   protocol?: AssistantTransportProtocol;
+  /**
+   * When `false`, stream decoding and state reconciliation tolerate malformed
+   * input (invalid chunks are dropped with a console log) instead of throwing.
+   * Resume runs always decode leniently. Defaults to `true`.
+   */
+  strict?: boolean;
   converter: AssistantTransportStateConverter<T>;
   headers: HeadersValue | (() => Promise<HeadersValue>);
   body?: object | (() => Promise<object | undefined>);

package/src/legacy-runtime/runtime-cores/assistant-transport/useAssistantTransport.spec.md

@@ -16,6 +16,13 @@ Command Scheduling
   - If no run is in progress: start a run immediately and flush commands to the server.
 - A follow-up run that finds an empty queue is a no-op: no request is sent and no error is surfaced.
 - A resume run sends no commands; commands enqueued while it is pending or active are flushed in a follow-up run after it settles.
+
+Resume State
+
+- With `resumeStateApi` configured, a resume first posts `{ threadId }` there; the endpoint returns `{ runId, state }`, the state that started the active run.
+- The resume request carries `runId` and no `state`: the server replays from the snapshot it retained for that run, so neither `body` overrides nor a `prepareSendCommandsRequest` rebuild can substitute a different base. `runId` takes precedence over `body` fields and is re-attached after `prepareSendCommandsRequest` so a rebuilt body cannot drop it. The local base is replaced by the snapshot only after the resume stream responds OK, so a rejected resume keeps the local state.
+- A 204 response means no active run: the resume is skipped without error, and queued commands are flushed in a follow-up run.
+- A malformed snapshot response fails the resume before the replay request is sent.
 - Runs execute on a `queueMicrotask`, so multiple synchronous enqueues coalesce into a single request: the first run's flush takes all of them, and the coalesced follow-up run no-ops.
 
 Command Queue

package/src/legacy-runtime/runtime-cores/assistant-transport/useAssistantTransportRuntime.test.tsx

@@ -112,6 +112,7 @@ const mountRuntime = (
 
 afterEach(() => {
   vi.unstubAllGlobals();
+  vi.restoreAllMocks();
 });
 
 describe("useAssistantTransportRuntime", () => {
@@ -136,6 +137,7 @@ describe("useAssistantTransportRuntime", () => {
     expect(
       fetchMock.requests[0]!.body["commands"].map((c: any) => c.type),
     ).toEqual(["add-message", "add-message"]);
+    expect(fetchMock.requests[0]!.body["state"]).toEqual({});
 
     act(() => fetchMock.servers[0]!.close());
 
@@ -145,6 +147,36 @@ describe("useAssistantTransportRuntime", () => {
     expect(fetchMock.requests).toHaveLength(1);
   });
 
+  it("skips add-message commands with no supported parts", async () => {
+    const fetchMock = installFetch();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { aui, sendCommand } = mountRuntime();
+    await waitFor(() =>
+      expect(
+        (aui().thread.getState().extras as { sendCommand?: unknown })
+          ?.sendCommand,
+      ).toBeTypeOf("function"),
+    );
+
+    act(() =>
+      aui().thread.append({
+        role: "user",
+        content: [{ type: "audio", audio: { data: "", format: "mp3" } }],
+      }),
+    );
+
+    await act(async () => {});
+    expect(warn).toHaveBeenCalledWith(
+      "[assistant-ui] Skipped add-message command with no supported parts",
+    );
+    expect(fetchMock.requests).toHaveLength(0);
+
+    // The skipped message must not leak its parentId into later batches.
+    act(() => sendCommand(createMessageCommand("follow-up")));
+    await waitFor(() => expect(fetchMock.requests).toHaveLength(1));
+    expect(fetchMock.requests[0]!.body).not.toHaveProperty("parentId");
+  });
+
   it("flushes commands enqueued during a resume run in a follow-up run", async () => {
     const fetchMock = installFetch();
     const { aui, sendCommand } = mountRuntime({
@@ -170,6 +202,7 @@ describe("useAssistantTransportRuntime", () => {
     await waitFor(() => expect(fetchMock.requests).toHaveLength(2));
     expect(fetchMock.requests[1]!.url).toBe("https://example.com/resume");
     expect(fetchMock.requests[1]!.body["commands"]).toEqual([]);
+    expect(fetchMock.requests[1]!.body).toHaveProperty("state");
 
     // "b" coalesced into the resume run and must not starve in the queue.
     act(() => fetchMock.servers[1]!.close());
@@ -182,4 +215,292 @@ describe("useAssistantTransportRuntime", () => {
     act(() => fetchMock.servers[2]!.close());
     await waitFor(() => expect(aui().thread.getState().isRunning).toBe(false));
   });
+
+  it("applies resumed operations to the retained initial state", async () => {
+    const requests: RecordedRequest[] = [];
+    vi.stubGlobal(
+      "fetch",
+      async (url: RequestInfo | URL, init: RequestInit = {}) => {
+        requests.push({
+          url: String(url),
+          init,
+          body: JSON.parse(init.body as string),
+        });
+
+        if (String(url) === "https://example.com/resume-state") {
+          return Response.json({
+            runId: "run-1",
+            state: { message: "Hello" },
+          });
+        }
+
+        return new Response(
+          'aui-state:[{"type":"append-text","path":["message"],"value":" world"}]\n',
+          { status: 200 },
+        );
+      },
+    );
+    const { aui } = mountRuntime({
+      resumeApi: "https://example.com/resume",
+      resumeStateApi: "https://example.com/resume-state",
+    });
+    await waitFor(() =>
+      expect(
+        (aui().thread.getState().extras as { sendCommand?: unknown })
+          ?.sendCommand,
+      ).toBeTypeOf("function"),
+    );
+
+    act(() => {
+      aui().thread.importExternalState({ message: "Wrong" });
+    });
+    await act(async () => {
+      await aui().thread.resumeRun({ parentId: null });
+    });
+
+    await waitFor(() =>
+      expect(
+        (aui().thread.getState().extras as { state: unknown }).state,
+      ).toEqual({ message: "Hello world" }),
+    );
+    expect(requests.map((request) => request.url)).toEqual([
+      "https://example.com/resume-state",
+      "https://example.com/resume",
+    ]);
+    expect(requests[1]!.body).toMatchObject({ runId: "run-1" });
+    expect(requests[1]!.body).not.toHaveProperty("state");
+  });
+
+  it("rejects malformed resume state responses before replay", async () => {
+    const fetchMock = vi.fn(async () => Response.json({ state: {} }));
+    vi.stubGlobal("fetch", fetchMock);
+    const onError = vi.fn();
+    const { aui } = mountRuntime({
+      resumeApi: "https://example.com/resume",
+      resumeStateApi: "https://example.com/resume-state",
+      onError,
+    });
+    await waitFor(() =>
+      expect(
+        (aui().thread.getState().extras as { sendCommand?: unknown })
+          ?.sendCommand,
+      ).toBeTypeOf("function"),
+    );
+
+    await act(async () => {
+      await aui().thread.resumeRun({ parentId: null });
+    });
+
+    await waitFor(() =>
+      expect(onError).toHaveBeenCalledWith(
+        expect.objectContaining({
+          message: "Resume state response must contain state and runId",
+        }),
+        expect.anything(),
+      ),
+    );
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("commits a retained null state locally and omits state from the resume request", async () => {
+    const requests: RecordedRequest[] = [];
+    vi.stubGlobal(
+      "fetch",
+      async (url: RequestInfo | URL, init: RequestInit = {}) => {
+        requests.push({
+          url: String(url),
+          init,
+          body: JSON.parse(init.body as string),
+        });
+
+        if (String(url) === "https://example.com/resume-state") {
+          return Response.json({ runId: "run-1", state: null });
+        }
+
+        return new Response("", { status: 200 });
+      },
+    );
+    const { aui } = mountRuntime({
+      resumeApi: "https://example.com/resume",
+      resumeStateApi: "https://example.com/resume-state",
+    });
+    await waitFor(() =>
+      expect(
+        (aui().thread.getState().extras as { sendCommand?: unknown })
+          ?.sendCommand,
+      ).toBeTypeOf("function"),
+    );
+
+    act(() => {
+      aui().thread.importExternalState({ message: "Wrong" });
+    });
+    await act(async () => {
+      await aui().thread.resumeRun({ parentId: null });
+    });
+
+    expect(requests[1]!.body).toMatchObject({ runId: "run-1" });
+    expect(requests[1]!.body).not.toHaveProperty("state");
+    await waitFor(() =>
+      expect(
+        (aui().thread.getState().extras as { state: unknown }).state,
+      ).toBeNull(),
+    );
+  });
+
+  it("skips the resume without error when the state endpoint reports no active run", async () => {
+    const fetchMock = vi.fn(async () => new Response(null, { status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const onError = vi.fn();
+    const { aui } = mountRuntime({
+      resumeApi: "https://example.com/resume",
+      resumeStateApi: "https://example.com/resume-state",
+      onError,
+    });
+    await waitFor(() =>
+      expect(
+        (aui().thread.getState().extras as { sendCommand?: unknown })
+          ?.sendCommand,
+      ).toBeTypeOf("function"),
+    );
+
+    act(() => {
+      aui().thread.importExternalState({ message: "Kept" });
+    });
+    await act(async () => {
+      await aui().thread.resumeRun({ parentId: null });
+    });
+
+    await waitFor(() => expect(aui().thread.getState().isRunning).toBe(false));
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(onError).not.toHaveBeenCalled();
+    expect(
+      (aui().thread.getState().extras as { state: unknown }).state,
+    ).toEqual({ message: "Kept" });
+  });
+
+  it("keeps the retained runId over body overrides in the resume request", async () => {
+    const requests: RecordedRequest[] = [];
+    vi.stubGlobal(
+      "fetch",
+      async (url: RequestInfo | URL, init: RequestInit = {}) => {
+        requests.push({
+          url: String(url),
+          init,
+          body: JSON.parse(init.body as string),
+        });
+
+        if (String(url) === "https://example.com/resume-state") {
+          return Response.json({
+            runId: "run-1",
+            state: { message: "Hello" },
+          });
+        }
+
+        return new Response("", { status: 200 });
+      },
+    );
+    const { aui } = mountRuntime({
+      resumeApi: "https://example.com/resume",
+      resumeStateApi: "https://example.com/resume-state",
+      body: { state: { message: "Injected" }, runId: "bogus" },
+    });
+    await waitFor(() =>
+      expect(
+        (aui().thread.getState().extras as { sendCommand?: unknown })
+          ?.sendCommand,
+      ).toBeTypeOf("function"),
+    );
+
+    await act(async () => {
+      await aui().thread.resumeRun({ parentId: null });
+    });
+
+    expect(requests[1]!.body["runId"]).toBe("run-1");
+    expect(requests[1]!.body).not.toHaveProperty("state");
+  });
+
+  it("re-attaches runId and strips substituted state when prepareSendCommandsRequest rebuilds the body", async () => {
+    const requests: RecordedRequest[] = [];
+    vi.stubGlobal(
+      "fetch",
+      async (url: RequestInfo | URL, init: RequestInit = {}) => {
+        requests.push({
+          url: String(url),
+          init,
+          body: JSON.parse(init.body as string),
+        });
+
+        if (String(url) === "https://example.com/resume-state") {
+          return Response.json({
+            runId: "run-1",
+            state: { message: "Hello" },
+          });
+        }
+
+        return new Response("", { status: 200 });
+      },
+    );
+    const { aui } = mountRuntime({
+      resumeApi: "https://example.com/resume",
+      resumeStateApi: "https://example.com/resume-state",
+      prepareSendCommandsRequest: (body) => ({
+        commands: body.commands,
+        state: { message: "Substituted" },
+        rebuilt: true,
+      }),
+    });
+    await waitFor(() =>
+      expect(
+        (aui().thread.getState().extras as { sendCommand?: unknown })
+          ?.sendCommand,
+      ).toBeTypeOf("function"),
+    );
+
+    await act(async () => {
+      await aui().thread.resumeRun({ parentId: null });
+    });
+
+    expect(requests[1]!.body).toMatchObject({ runId: "run-1", rebuilt: true });
+    expect(requests[1]!.body).not.toHaveProperty("state");
+  });
+
+  it("keeps local state when the matching resume stream is rejected", async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(
+        Response.json({ runId: "run-1", state: { message: "Hello" } }),
+      )
+      .mockResolvedValueOnce(new Response("run mismatch", { status: 409 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const onError = vi.fn();
+    const { aui } = mountRuntime({
+      resumeApi: "https://example.com/resume",
+      resumeStateApi: "https://example.com/resume-state",
+      onError,
+    });
+    await waitFor(() =>
+      expect(
+        (aui().thread.getState().extras as { sendCommand?: unknown })
+          ?.sendCommand,
+      ).toBeTypeOf("function"),
+    );
+
+    act(() => {
+      aui().thread.importExternalState({ message: "Wrong" });
+    });
+    await act(async () => {
+      await aui().thread.resumeRun({ parentId: null });
+    });
+
+    await waitFor(() =>
+      expect(onError).toHaveBeenCalledWith(
+        expect.objectContaining({ message: "Status 409: run mismatch" }),
+        expect.anything(),
+      ),
+    );
+    expect(
+      (aui().thread.getState().extras as { state: unknown }).state,
+    ).toEqual({ message: "Wrong" });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
 });

package/src/legacy-runtime/runtime-cores/assistant-transport/useAssistantTransportRuntime.ts

@@ -42,7 +42,7 @@ import type { UserExternalState } from "../../../augmentations";
 
 const convertAppendMessageToCommand = (
   message: AppendMessage,
-): AddMessageCommand => {
+): AddMessageCommand | null => {
   if (message.role !== "user")
     throw new Error("Only user messages are supported");
 
@@ -59,6 +59,8 @@ const convertAppendMessageToCommand = (
     }
   }
 
+  if (parts.length === 0) return null;
+
   return {
     type: "add-message",
     message: {
@@ -70,6 +72,36 @@ const convertAppendMessageToCommand = (
   };
 };
 
+const readResumeState = async <T>(
+  response: Response,
+): Promise<{ runId: string; state: T } | null> => {
+  if (response.status === 204) return null;
+  if (!response.ok) {
+    throw new Error(
+      `Resume state request failed with status ${response.status}: ${await response.text()}`,
+    );
+  }
+
+  let value: unknown;
+  try {
+    value = await response.json();
+  } catch {
+    throw new Error("Resume state response was not valid JSON");
+  }
+
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    !("state" in value) ||
+    !("runId" in value) ||
+    typeof value.runId !== "string"
+  ) {
+    throw new Error("Resume state response must contain state and runId");
+  }
+
+  return { runId: value.runId, state: value.state as T };
+};
+
 const symbolAssistantTransportExtras = Symbol("assistant-transport-extras");
 type AssistantTransportExtras = {
   [symbolAssistantTransportExtras]: true;
@@ -127,6 +159,20 @@ const useAssistantTransportThreadRuntime = <T>(
     onQueue: () => runManager.schedule(),
   });
 
+  const enqueueAppendMessage = (message: AppendMessage) => {
+    const command = convertAppendMessageToCommand(message);
+    if (!command) {
+      console.warn(
+        "[assistant-ui] Skipped add-message command with no supported parts",
+      );
+      return;
+    }
+    parentIdRef.current = message.parentId;
+    commandQueue.enqueue(command, {
+      schedule: message.startRun ?? message.role === "user",
+    });
+  };
+
   const threadId = useAuiState((s) => s.threadListItem.remoteId);
 
   const runManager = useRunManager({
@@ -144,6 +190,24 @@ const useAssistantTransportThreadRuntime = <T>(
       if (!isResume) parentIdRef.current = undefined;
 
       const headers = await createRequestHeaders(options.headers);
+      let resumeState: { runId: string; state: T } | undefined;
+      if (isResume && options.resumeStateApi) {
+        const resumeStateResponse = await fetch(options.resumeStateApi, {
+          method: "POST",
+          headers,
+          body: JSON.stringify({ threadId }),
+          signal,
+        });
+        const retained = await readResumeState<T>(resumeStateResponse);
+        if (retained === null) {
+          if (commandQueue.state.queued.length > 0) {
+            runManager.schedule();
+          }
+          return;
+        }
+        resumeState = retained;
+      }
+
       const bodyValue =
         typeof options.body === "function"
           ? await options.body()
@@ -152,7 +216,7 @@ const useAssistantTransportThreadRuntime = <T>(
 
       let requestBody: Record<string, unknown> = {
         commands,
-        state: agentStateRef.current,
+        ...(resumeState === undefined && { state: agentStateRef.current }),
         system: context.system,
         tools: context.tools ? toToolsJSONSchema(context.tools) : undefined,
         threadId,
@@ -174,6 +238,14 @@ const useAssistantTransportThreadRuntime = <T>(
         );
       }
 
+      if (resumeState !== undefined) {
+        // The server replays a resume from the snapshot it retained for this
+        // runId. Body overrides and prepare hooks can neither substitute a
+        // state nor drop the ID the server validates against.
+        requestBody = { ...requestBody, runId: resumeState.runId };
+        delete requestBody["state"];
+      }
+
       const response = await fetch(
         isResume ? options.resumeApi! : options.api,
         {
@@ -194,6 +266,11 @@ const useAssistantTransportThreadRuntime = <T>(
         throw new Error("Response body is null");
       }
 
+      if (resumeState !== undefined) {
+        agentStateRef.current = resumeState.state;
+        rerender((prev) => prev + 1);
+      }
+
       const body = await createReplayBoundaryStream(response, {
         setReplaying: setIsReplaying,
         waitForRender: waitForReplayRender,
@@ -201,10 +278,12 @@ const useAssistantTransportThreadRuntime = <T>(
 
       // Select decoder based on protocol option
       const protocol = options.protocol ?? "data-stream";
+      // Resume replays a best-effort buffer; always reconcile leniently.
+      const strict = isResume ? false : (options.strict ?? true);
       const decoder =
         protocol === "assistant-transport"
-          ? new AssistantTransportDecoder()
-          : new DataStreamDecoder();
+          ? new AssistantTransportDecoder({ strict })
+          : new DataStreamDecoder({ strict });
 
       let err: string | undefined;
       const stream = body.pipeThrough(decoder).pipeThrough(
@@ -214,6 +293,7 @@ const useAssistantTransportThreadRuntime = <T>(
               (agentStateRef.current as ReadonlyJSONValue) ?? null,
           }),
           throttle: isResume,
+          strict,
           onError: (error) => {
             err = error;
           },
@@ -329,21 +409,11 @@ const useAssistantTransportThreadRuntime = <T>(
       },
       state: agentStateRef.current as UserExternalState,
     } satisfies AssistantTransportExtras,
-    onNew: async (message: AppendMessage): Promise<void> => {
-      parentIdRef.current = message.parentId;
-      const command = convertAppendMessageToCommand(message);
-      commandQueue.enqueue(command, {
-        schedule: message.startRun ?? message.role === "user",
-      });
-    },
+    onNew: async (message: AppendMessage): Promise<void> =>
+      enqueueAppendMessage(message),
     ...(options.capabilities?.edit && {
-      onEdit: async (message: AppendMessage): Promise<void> => {
-        parentIdRef.current = message.parentId;
-        const command = convertAppendMessageToCommand(message);
-        commandQueue.enqueue(command, {
-          schedule: message.startRun ?? message.role === "user",
-        });
-      },
+      onEdit: async (message: AppendMessage): Promise<void> =>
+        enqueueAppendMessage(message),
     }),
     ...(commandQueue.state.queued.length > 0 && {
       onReload: async (parentId: string | null) => {

package/src/primitives/actionBar/ActionBarExportMarkdown.tsx

@@ -37,7 +37,7 @@ const useActionBarExportMarkdown = ({
     a.href = url;
     a.download = filename ?? `message-${Date.now()}.md`;
     a.click();
-    URL.revokeObjectURL(url);
+    setTimeout(() => URL.revokeObjectURL(url), 40_000);
   }, [aui, filename, onExport]);
 
   if (!hasExportableContent) return null;

package/src/primitives/attachment/AttachmentThumb.test.tsx

@@ -0,0 +1,70 @@
+import { describe, expect, it, vi } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import type * as AssistantStore from "@assistant-ui/store";
+import { AttachmentPrimitiveThumb } from "./AttachmentThumb";
+
+const mockUseAuiState = vi.fn();
+type UseAuiStateSelector = Parameters<
+  (typeof AssistantStore)["useAuiState"]
+>[0];
+
+vi.mock("@assistant-ui/store", async (importOriginal) => {
+  const actual = await importOriginal<typeof AssistantStore>();
+  return {
+    ...actual,
+    useAuiState: (selector: UseAuiStateSelector) => mockUseAuiState(selector),
+  };
+});
+
+const renderThumb = (
+  name: string,
+  type = "file",
+  props?: AttachmentPrimitiveThumb.Props,
+) => {
+  mockUseAuiState.mockImplementation((selector: UseAuiStateSelector) =>
+    selector({ attachment: { name, type } } as never),
+  );
+
+  return renderToStaticMarkup(<AttachmentPrimitiveThumb {...props} />);
+};
+
+describe("AttachmentPrimitiveThumb", () => {
+  it("renders the dotted extension for a single-extension name", () => {
+    expect(renderThumb("photo.png")).toBe("<div>.png</div>");
+  });
+
+  it("takes only the last segment for a multi-extension name", () => {
+    expect(renderThumb("archive.tar.gz")).toBe("<div>.gz</div>");
+  });
+
+  it("falls back to the attachment type when the name has no extension", () => {
+    expect(renderThumb("noext", "document")).toBe("<div>document</div>");
+  });
+
+  it("falls back to the attachment type for an empty name", () => {
+    expect(renderThumb("", "image")).toBe("<div>image</div>");
+  });
+
+  it("treats a leading-dot name as extensionless", () => {
+    expect(renderThumb(".gitignore")).toBe("<div>file</div>");
+  });
+
+  it("falls back to the attachment type for a trailing-dot name", () => {
+    expect(renderThumb("report.", "image")).toBe("<div>image</div>");
+  });
+
+  it("renders custom children instead of the label", () => {
+    expect(renderThumb("report.pdf", "file", { children: <em>PDF</em> })).toBe(
+      "<div><em>PDF</em></div>",
+    );
+  });
+
+  it("renders the child element when asChild is set", () => {
+    expect(
+      renderThumb("report.pdf", "file", {
+        asChild: true,
+        children: <span>custom</span>,
+      }),
+    ).toBe("<span>custom</span>");
+  });
+});

package/src/primitives/attachment/AttachmentThumb.tsx

@@ -19,13 +19,17 @@ export const AttachmentPrimitiveThumb = forwardRef<
   AttachmentPrimitiveThumb.Element,
   AttachmentPrimitiveThumb.Props
 >((props, ref) => {
-  const ext = useAuiState((s) => {
-    const parts = s.attachment.name.split(".");
-    return parts.length > 1 ? parts.pop()! : "";
+  const label = useAuiState((s) => {
+    const name = s.attachment.name;
+    const dot = name.lastIndexOf(".");
+    if (dot > 0 && dot < name.length - 1) {
+      return `.${name.slice(dot + 1)}`;
+    }
+    return s.attachment.type;
   });
   return (
     <Primitive.div {...props} ref={ref}>
-      .{ext}
+      {props.children ?? label}
     </Primitive.div>
   );
 });