@assistant-ui/core 0.3.2 → 0.3.4

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/index.ts

@@ -18,6 +18,7 @@ export type {
   ThreadAssistantMessagePart,
   // Message status
   MessagePartStatus,
+  MessagePartStreamStatus,
   ToolCallMessagePartStatus,
   MessageStatus,
   // Thread messages

package/src/types/message.ts

@@ -14,6 +14,7 @@ export type PartProviderMetadata = {
 export type TextMessagePart = {
   readonly type: "text";
   readonly text: string;
+  readonly status?: MessagePartStreamStatus;
   readonly providerMetadata?: PartProviderMetadata;
   readonly parentId?: string;
 };
@@ -21,6 +22,7 @@ export type TextMessagePart = {
 export type ReasoningMessagePart = {
   readonly type: "reasoning";
   readonly text: string;
+  readonly status?: MessagePartStreamStatus;
   readonly providerMetadata?: PartProviderMetadata;
   readonly parentId?: string;
 };
@@ -60,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: {
@@ -266,6 +279,23 @@ export type MessagePartStatus =
       readonly error?: unknown;
     };
 
+export type MessagePartStreamStatus =
+  | {
+      readonly type: "running";
+    }
+  | {
+      readonly type: "complete";
+    }
+  | {
+      readonly type: "incomplete";
+      readonly reason:
+        | "cancelled"
+        | "length"
+        | "content-filter"
+        | "other"
+        | "error";
+    };
+
 export type ToolCallMessagePartStatus =
   | {
       /** The tool call is waiting for UI or human input before continuing. */

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/getGroupStatus.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { getGroupStatus } from "./getGroupStatus";
+
+describe("getGroupStatus", () => {
+  it("reports running when the first member is running and the last is complete", () => {
+    const parts = [
+      { status: { type: "running" as const } },
+      { status: { type: "complete" as const } },
+    ];
+    const status = getGroupStatus(parts);
+
+    expect(status).toEqual({ type: "running" });
+    expect(getGroupStatus(parts, [0, 1])).toBe(status);
+    expect(status).toBe(getGroupStatus([{ status: { type: "running" } }]));
+    expect(Object.isFrozen(status)).toBe(true);
+  });
+
+  it("reports the last status when every member is complete", () => {
+    const status = { type: "complete" } as const;
+
+    expect(getGroupStatus([{ status }, { status }])).toBe(status);
+  });
+
+  it("reports complete for an empty group", () => {
+    expect(getGroupStatus([])).toEqual({ type: "complete" });
+  });
+
+  it("matches the positional outcome for statusless adapters", () => {
+    expect(
+      getGroupStatus(
+        [{ status: { type: "complete" } }, { status: { type: "running" } }],
+        [0, 1],
+      ),
+    ).toEqual({ type: "running" });
+  });
+});

package/src/utils/getGroupStatus.ts

@@ -0,0 +1,31 @@
+import type {
+  MessagePartStatus,
+  ToolCallMessagePartStatus,
+} from "../types/message";
+import { COMPLETE_STATUS, RUNNING_STATUS } from "./normalizePartStatus";
+
+type PartWithStatus = {
+  readonly status: MessagePartStatus | ToolCallMessagePartStatus;
+};
+
+export const getGroupStatus = (
+  parts: readonly (PartWithStatus | undefined)[],
+  indices?: readonly number[],
+): MessagePartStatus | ToolCallMessagePartStatus => {
+  if (indices) {
+    for (const index of indices) {
+      if (parts[index]?.status.type === "running") return RUNNING_STATUS;
+    }
+
+    const lastIndex = indices.at(-1);
+    return lastIndex === undefined
+      ? COMPLETE_STATUS
+      : (parts[lastIndex]?.status ?? COMPLETE_STATUS);
+  }
+
+  for (const part of parts) {
+    if (part?.status.type === "running") return RUNNING_STATUS;
+  }
+
+  return parts.at(-1)?.status ?? COMPLETE_STATUS;
+};

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);
+  });
+});