@assistant-ui/core 0.3.3 → 0.3.4

package/src/tests/auiV0Encode.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { auiV0Decode, auiV0Encode } from "../react/runtimes/cloud/auiV0";
 
 describe("auiV0Encode", () => {
@@ -127,6 +127,61 @@ describe("auiV0Encode", () => {
     ]);
   });
 
+  it("preserves file sourceType in the core cloud encoder", () => {
+    const encoded = auiV0Encode({
+      id: "m1",
+      createdAt: new Date("2026-03-15T00:00:00.000Z"),
+      role: "user",
+      metadata: { custom: {} },
+      content: [
+        {
+          type: "file",
+          data: "file-abc123",
+          mimeType: "application/pdf",
+          filename: "a.pdf",
+          sourceType: "id",
+        },
+      ],
+      attachments: [
+        {
+          id: "att-1",
+          type: "document",
+          name: "a.pdf",
+          contentType: "application/pdf",
+          status: { type: "complete" },
+          content: [
+            {
+              type: "file",
+              data: "file-abc123",
+              mimeType: "application/pdf",
+              filename: "a.pdf",
+              sourceType: "id",
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(encoded.content).toEqual([
+      {
+        type: "file",
+        data: "file-abc123",
+        mimeType: "application/pdf",
+        filename: "a.pdf",
+        sourceType: "id",
+      },
+    ]);
+    expect(encoded.attachments?.[0]?.content).toEqual([
+      {
+        type: "file",
+        data: "file-abc123",
+        mimeType: "application/pdf",
+        filename: "a.pdf",
+        sourceType: "id",
+      },
+    ]);
+  });
+
   it("omits missing attachment contentType in the core cloud encoder", () => {
     const encoded = auiV0Encode({
       id: "m1",
@@ -352,4 +407,73 @@ describe("auiV0Decode", () => {
       },
     ]);
   });
+
+  const toolCallMessage = (
+    part: Record<string, unknown>,
+  ): Parameters<typeof auiV0Encode>[0] => ({
+    id: "m1",
+    createdAt: new Date("2026-03-15T00:00:00.000Z"),
+    role: "assistant",
+    status: { type: "complete", reason: "stop" },
+    metadata: {
+      unstable_state: null,
+      unstable_annotations: [],
+      unstable_data: [],
+      steps: [],
+      custom: {},
+    },
+    content: [
+      {
+        type: "tool-call",
+        toolCallId: "call-1",
+        toolName: "check_flag",
+        args: {},
+        argsText: "{}",
+        ...part,
+      },
+    ],
+  });
+
+  it.each([
+    ["false", false],
+    ["zero", 0],
+    ["an empty string", ""],
+    ["null", null],
+  ])("preserves %s as a tool-call result", (_label, result) => {
+    const encoded = auiV0Encode(toolCallMessage({ result }));
+
+    const toolCall = encoded.content.find((p) => p.type === "tool-call");
+    expect(toolCall).toHaveProperty("result", result);
+  });
+
+  it("omits the result of a tool call that has not settled", () => {
+    const encoded = auiV0Encode(toolCallMessage({}));
+
+    const toolCall = encoded.content.find((p) => p.type === "tool-call");
+    expect(toolCall).not.toHaveProperty("result");
+  });
+
+  it("does not warn about a tool call that has not settled", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      auiV0Encode(toolCallMessage({}));
+      expect(warn).not.toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("carries a falsy tool-call result through a decode round trip", () => {
+    const encoded = auiV0Encode(toolCallMessage({ result: false }));
+    const { message } = auiV0Decode({
+      id: "m1",
+      parent_id: null,
+      format: "aui/v0",
+      content: encoded,
+      created_at: new Date("2026-03-15T00:00:00.000Z"),
+    } as unknown as Parameters<typeof auiV0Decode>[0]);
+
+    const toolCall = message.content.find((p) => p.type === "tool-call");
+    expect(toolCall).toHaveProperty("result", false);
+  });
 });

package/src/tests/base-composer-runtime-core-addAttachment.test.ts

@@ -38,6 +38,22 @@ const makeComposer = (adapter?: AttachmentAdapter) => {
   return new DefaultThreadComposerRuntimeCore(runtime);
 };
 
+const makeUploadingAttachment = (
+  file: File,
+  id: string,
+): PendingAttachment => ({
+  id,
+  type: "image",
+  name: file.name,
+  contentType: file.type,
+  file,
+  status: {
+    type: "running",
+    reason: "uploading",
+    progress: 0,
+  },
+});
+
 describe("BaseComposerRuntimeCore.addAttachment error events", () => {
   it("emits attachmentAddError when no adapter is configured", async () => {
     const composer = makeComposer();
@@ -128,6 +144,286 @@ describe("BaseComposerRuntimeCore.addAttachment error events", () => {
     expect(onError).not.toHaveBeenCalled();
   });
 
+  it("does not restore an attachment removed while add is still running", async () => {
+    let finishUpload!: () => void;
+    const uploadPending = new Promise<void>((resolve) => {
+      finishUpload = resolve;
+    });
+    let finishRemoval!: () => void;
+    const removalPending = new Promise<void>((resolve) => {
+      finishRemoval = resolve;
+    });
+    const remove = vi.fn(() => removalPending);
+    const continueUpload = vi.fn();
+    const cleanUpUpload = vi.fn();
+    const composer = makeComposer(
+      makeAdapter({
+        remove,
+        async *add({ file }: { file: File }) {
+          const attachment = makeUploadingAttachment(file, "att-1");
+          try {
+            yield attachment;
+            await uploadPending;
+            yield {
+              ...attachment,
+              status: { type: "requires-action", reason: "composer-send" },
+            };
+            continueUpload();
+            yield attachment;
+          } finally {
+            cleanUpUpload();
+          }
+        },
+      }),
+    );
+    const onAdd = vi.fn();
+    composer.unstable_on("attachmentAdd", onAdd);
+
+    const addTask = composer.addAttachment(
+      new File(["x"], "f.png", { type: "image/png" }),
+    );
+    await vi.waitFor(() => {
+      expect(composer.attachments).toHaveLength(1);
+    });
+
+    const removeTask = composer.removeAttachment("att-1");
+    finishUpload();
+    await addTask;
+
+    expect(remove).toHaveBeenCalledTimes(1);
+    expect(onAdd).not.toHaveBeenCalled();
+    expect(continueUpload).not.toHaveBeenCalled();
+    expect(cleanUpUpload).toHaveBeenCalledTimes(1);
+
+    finishRemoval();
+    await removeTask;
+    expect(composer.attachments).toHaveLength(0);
+  });
+
+  it("settles a pending attachment when adapter removal fails", async () => {
+    let finishUpload!: () => void;
+    const uploadPending = new Promise<void>((resolve) => {
+      finishUpload = resolve;
+    });
+    const cleanUpUpload = vi.fn();
+    const composer = makeComposer(
+      makeAdapter({
+        remove: vi.fn().mockRejectedValue(new Error("remove failed")),
+        async *add({ file }: { file: File }) {
+          const attachment = makeUploadingAttachment(file, "att-1");
+          try {
+            yield attachment;
+            await uploadPending;
+            yield {
+              ...attachment,
+              status: { type: "requires-action", reason: "composer-send" },
+            };
+          } finally {
+            cleanUpUpload();
+          }
+        },
+      }),
+    );
+    const onAdd = vi.fn();
+    composer.unstable_on("attachmentAdd", onAdd);
+
+    const addTask = composer.addAttachment(
+      new File(["x"], "f.png", { type: "image/png" }),
+    );
+    await vi.waitFor(() => {
+      expect(composer.attachments).toHaveLength(1);
+    });
+
+    await expect(composer.removeAttachment("att-1")).rejects.toThrow(
+      "remove failed",
+    );
+    expect(composer.attachments[0]?.status).toEqual({
+      type: "incomplete",
+      reason: "error",
+      message: "remove failed",
+    });
+
+    finishUpload();
+    await addTask;
+
+    expect(composer.attachments[0]?.status.type).toBe("incomplete");
+    expect(cleanUpUpload).toHaveBeenCalledTimes(1);
+    expect(onAdd).not.toHaveBeenCalled();
+  });
+
+  it("keeps a concurrent add registered before its first yield", async () => {
+    let startSlowUpload!: () => void;
+    const slowUploadStarted = new Promise<void>((resolve) => {
+      startSlowUpload = resolve;
+    });
+    let finishSlowUpload!: () => void;
+    const slowUploadPending = new Promise<void>((resolve) => {
+      finishSlowUpload = resolve;
+    });
+    const composer = makeComposer(
+      makeAdapter({
+        async *add({ file }: { file: File }) {
+          const attachment = makeUploadingAttachment(file, `att-${file.name}`);
+          if (file.name === "slow.png") await slowUploadStarted;
+          yield attachment;
+          if (file.name === "slow.png") await slowUploadPending;
+          yield {
+            ...attachment,
+            status: { type: "requires-action", reason: "composer-send" },
+          };
+        },
+      }),
+    );
+    const onAdd = vi.fn();
+    composer.unstable_on("attachmentAdd", onAdd);
+
+    const slowAddTask = composer.addAttachment(
+      new File(["slow"], "slow.png", { type: "image/png" }),
+    );
+    await composer.addAttachment(
+      new File(["fast"], "fast.png", { type: "image/png" }),
+    );
+
+    startSlowUpload();
+    await vi.waitFor(() => {
+      expect(
+        composer.attachments.some(
+          (attachment) => attachment.id === "att-slow.png",
+        ),
+      ).toBe(true);
+    });
+    await composer.removeAttachment("att-slow.png");
+    finishSlowUpload();
+    await slowAddTask;
+
+    expect(
+      composer.attachments.some(
+        (attachment) => attachment.id === "att-slow.png",
+      ),
+    ).toBe(false);
+    expect(onAdd).toHaveBeenCalledTimes(1);
+  });
+
+  it("cancels an add cleared before its first yield", async () => {
+    let startUpload!: () => void;
+    const uploadPending = new Promise<void>((resolve) => {
+      startUpload = resolve;
+    });
+    const composer = makeComposer(
+      makeAdapter({
+        async *add({ file }: { file: File }) {
+          await uploadPending;
+          yield makeUploadingAttachment(file, "att-1");
+        },
+      }),
+    );
+    const onAdd = vi.fn();
+    composer.unstable_on("attachmentAdd", onAdd);
+
+    const addTask = composer.addAttachment(
+      new File(["x"], "f.png", { type: "image/png" }),
+    );
+    await composer.clearAttachments();
+    startUpload();
+    await addTask;
+
+    expect(composer.attachments).toHaveLength(0);
+    expect(onAdd).not.toHaveBeenCalled();
+  });
+
+  it("cancels a promise add cleared before it resolves", async () => {
+    let finishUpload!: () => void;
+    const uploadPending = new Promise<void>((resolve) => {
+      finishUpload = resolve;
+    });
+    const composer = makeComposer(
+      makeAdapter({
+        add: async ({ file }: { file: File }) => {
+          await uploadPending;
+          return makeUploadingAttachment(file, "att-1");
+        },
+      }),
+    );
+    const onAdd = vi.fn();
+    composer.unstable_on("attachmentAdd", onAdd);
+
+    const addTask = composer.addAttachment(
+      new File(["x"], "f.png", { type: "image/png" }),
+    );
+    await composer.clearAttachments();
+    finishUpload();
+    await addTask;
+
+    expect(composer.attachments).toHaveLength(0);
+    expect(onAdd).not.toHaveBeenCalled();
+  });
+
+  it("cancels an add reset before its first yield", async () => {
+    let startUpload!: () => void;
+    const uploadPending = new Promise<void>((resolve) => {
+      startUpload = resolve;
+    });
+    const composer = makeComposer(
+      makeAdapter({
+        async *add({ file }: { file: File }) {
+          await uploadPending;
+          yield makeUploadingAttachment(file, "att-1");
+        },
+      }),
+    );
+    const onAdd = vi.fn();
+    composer.unstable_on("attachmentAdd", onAdd);
+
+    const addTask = composer.addAttachment(
+      new File(["x"], "f.png", { type: "image/png" }),
+    );
+    await composer.reset();
+    startUpload();
+    await addTask;
+
+    expect(composer.attachments).toHaveLength(0);
+    expect(onAdd).not.toHaveBeenCalled();
+  });
+
+  it("cancels every concurrent add sharing an attachment id", async () => {
+    let finishUploads!: () => void;
+    const uploadsPending = new Promise<void>((resolve) => {
+      finishUploads = resolve;
+    });
+    const firstYieldsConsumed = vi.fn();
+    const composer = makeComposer(
+      makeAdapter({
+        async *add({ file }: { file: File }) {
+          const attachment = makeUploadingAttachment(file, "shared");
+          yield attachment;
+          firstYieldsConsumed();
+          await uploadsPending;
+          yield {
+            ...attachment,
+            status: { type: "requires-action", reason: "composer-send" },
+          };
+        },
+      }),
+    );
+    const onAdd = vi.fn();
+    composer.unstable_on("attachmentAdd", onAdd);
+
+    const addTasks = [
+      composer.addAttachment(new File(["a"], "a.png", { type: "image/png" })),
+      composer.addAttachment(new File(["b"], "b.png", { type: "image/png" })),
+    ];
+    await vi.waitFor(() => {
+      expect(firstYieldsConsumed).toHaveBeenCalledTimes(2);
+    });
+
+    await composer.removeAttachment("shared");
+    finishUploads();
+    await Promise.all(addTasks);
+
+    expect(composer.attachments).toHaveLength(0);
+    expect(onAdd).not.toHaveBeenCalled();
+  });
+
   it("adds prepared attachments when File is unavailable", async () => {
     const composer = makeComposer();
     const fileConstructor = globalThis.File;

package/src/tests/event-subscription-listener-errors.test.ts

@@ -96,6 +96,7 @@ const makeThreadHarness = (): RuntimeHarness => {
       remoteId: undefined,
       externalId: undefined,
       isMain: true,
+      isRunning: false,
       status: "regular",
       title: undefined,
     }),

package/src/tests/external-store-thread-list-runtime-core.test.ts

@@ -4,11 +4,13 @@ import type { ExternalStoreThreadRuntimeCore } from "../runtimes/external-store/
 import type { ExternalStoreThreadListAdapter } from "../runtimes/external-store/external-store-adapter";
 import { ThreadListRuntimeImpl } from "../runtime/api/thread-list-runtime";
 
-const makeFactory = () =>
+const makeFactory = (overrides: Record<string, unknown> = {}) =>
   vi.fn(
     () =>
       ({
         subscribe: () => () => {},
+        capabilities: { cancel: false },
+        ...overrides,
       }) as unknown as ExternalStoreThreadRuntimeCore,
   );
 
@@ -244,3 +246,39 @@ describe("ExternalStoreThreadListRuntimeCore - switchToThread", () => {
     expect(onSwitchToThread).not.toHaveBeenCalled();
   });
 });
+
+describe("ExternalStoreThreadListRuntimeCore.reloadMainThread", () => {
+  it("dispatches to the main thread's refetch capability", async () => {
+    const refetch = vi.fn(async () => {});
+    const core = new ExternalStoreThreadListRuntimeCore(
+      makeAdapter(),
+      makeFactory({ unstable_refetchThread: refetch }),
+    );
+
+    await core.reloadMainThread();
+
+    expect(refetch).toHaveBeenCalledOnce();
+  });
+
+  it("resolves quietly when the adapter declares no refetch capability", async () => {
+    const core = new ExternalStoreThreadListRuntimeCore(
+      makeAdapter(),
+      makeFactory(),
+    );
+
+    await expect(core.reloadMainThread()).resolves.toBeUndefined();
+  });
+
+  it("propagates a refetch failure", async () => {
+    const core = new ExternalStoreThreadListRuntimeCore(
+      makeAdapter(),
+      makeFactory({
+        unstable_refetchThread: async () => {
+          throw new Error("refetch failed");
+        },
+      }),
+    );
+
+    await expect(core.reloadMainThread()).rejects.toThrow("refetch failed");
+  });
+});

package/src/types/message.ts

@@ -62,9 +62,20 @@ export type FileMessagePart = {
   readonly filename?: string;
   readonly data: string;
   readonly mimeType: string;
+  /** How `data` goes on the wire: a url or id reference; omitted = inferred (http(s) → url, else base64). "url" is honored by the LangChain-family, A2A, AG-UI, and Google ADK runtimes; "id" by the LangChain family only. */
+  readonly sourceType?: "url" | "id";
   readonly parentId?: string;
 };
 
+/**
+ * @deprecated Use {@link FileMessagePart} with an `audio/*` mime type. `file`
+ * is the carrier for every non-image binary modality: it is a member of both
+ * the user and assistant unions, carries a filename, and can declare how its
+ * payload goes on the wire, none of which this shape can express. The payload
+ * form a `file` part needs is still adapter specific; see the Part Types
+ * section of the message primitive docs. Honored everywhere it is accepted; it
+ * will not gain fields.
+ */
 export type Unstable_AudioMessagePart = {
   readonly type: "audio";
   readonly audio: {

package/src/utils/data-url.ts

@@ -7,3 +7,27 @@ export function parseDataUrl(
   if (!match) return null;
   return { mimeType: match[1]!.toLowerCase(), data: match[2]! };
 }
+
+/**
+ * Whether a payload is something `new URL()` accepts. Adapters that place a
+ * `FileMessagePart` payload into a url-typed wire field use this to decide
+ * whether it has to be wrapped in a data URL envelope first; base64 cannot
+ * contain a colon, so a real payload is never misread as a url.
+ */
+export function isParsableUrl(value: string): boolean {
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The media type a data URL declares, whether or not its payload is base64.
+ * `parseDataUrl` only matches base64 payloads because it also returns the
+ * bytes; this reads the declaration alone.
+ */
+export function dataUrlMediaType(value: string): string | undefined {
+  return /^data:([^;,]+)(?:[;,])/i.exec(value)?.[1]?.toLowerCase();
+}

package/src/utils/image-media-type.test.ts

@@ -0,0 +1,96 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { detectImageMediaType } from "./image-media-type";
+
+const toBase64 = (bytes: number[]) =>
+  Buffer.from(Uint8Array.from(bytes)).toString("base64");
+
+describe("detectImageMediaType", () => {
+  it.each([
+    {
+      label: "gif",
+      bytes: [0x47, 0x49, 0x46, 0x38, 0x39, 0x61],
+      type: "image/gif",
+    },
+    {
+      label: "png",
+      bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],
+      type: "image/png",
+    },
+    { label: "jpeg", bytes: [0xff, 0xd8, 0xff, 0xe0], type: "image/jpeg" },
+    { label: "bmp", bytes: [0x42, 0x4d, 0x00, 0x00], type: "image/bmp" },
+    {
+      label: "tiff little endian",
+      bytes: [0x49, 0x49, 0x2a, 0x00],
+      type: "image/tiff",
+    },
+    {
+      label: "tiff big endian",
+      bytes: [0x4d, 0x4d, 0x00, 0x2a],
+      type: "image/tiff",
+    },
+  ])("detects $label", ({ bytes, type }) => {
+    expect(detectImageMediaType(toBase64(bytes))).toBe(type);
+  });
+
+  it("detects webp across its variable size bytes", () => {
+    const bytes = [
+      0x52, 0x49, 0x46, 0x46, 0xde, 0xad, 0xbe, 0xef, 0x57, 0x45, 0x42, 0x50,
+    ];
+    expect(detectImageMediaType(toBase64(bytes))).toBe("image/webp");
+  });
+
+  it.each([
+    { label: "avif", eighth: [0x61, 0x76, 0x69, 0x66], type: "image/avif" },
+    { label: "heic", eighth: [0x68, 0x65, 0x69, 0x63], type: "image/heic" },
+  ])("detects $label whatever its ftyp box size", ({ eighth, type }) => {
+    for (const size of [0x20, 0x18, 0x1c]) {
+      const bytes = [0x00, 0x00, 0x00, size, 0x66, 0x74, 0x79, 0x70, ...eighth];
+      expect(detectImageMediaType(toBase64(bytes))).toBe(type);
+    }
+  });
+
+  describe("without Buffer, as in a browser", () => {
+    afterEach(() => {
+      vi.unstubAllGlobals();
+    });
+
+    it("decodes through atob", () => {
+      // encoded before the stub, since the helper itself uses Buffer
+      const jpeg = toBase64([0xff, 0xd8, 0xff, 0xe0]);
+      const webp = toBase64([
+        0x52, 0x49, 0x46, 0x46, 0xde, 0xad, 0xbe, 0xef, 0x57, 0x45, 0x42, 0x50,
+      ]);
+      vi.stubGlobal("Buffer", undefined);
+
+      expect(detectImageMediaType(jpeg)).toBe("image/jpeg");
+      expect(detectImageMediaType(webp)).toBe("image/webp");
+    });
+
+    it("returns undefined when atob rejects the input", () => {
+      vi.stubGlobal("Buffer", undefined);
+
+      expect(detectImageMediaType("$$$$")).toBe(undefined);
+    });
+  });
+
+  it("returns undefined for bytes matching no signature", () => {
+    expect(detectImageMediaType(toBase64([0x01, 0x02, 0x03, 0x04]))).toBe(
+      undefined,
+    );
+  });
+
+  it("does not throw on input that is not base64", () => {
+    for (const value of [
+      "not base64 at all!!",
+      "",
+      "$$$$",
+      "https://x.example",
+    ]) {
+      expect(() => detectImageMediaType(value)).not.toThrow();
+    }
+  });
+
+  it("returns undefined for a payload shorter than any signature", () => {
+    expect(detectImageMediaType("/w==")).toBe(undefined);
+  });
+});