@assistant-ui/core 0.2.19 → 0.2.21

package/src/adapters/attachment.test.ts

@@ -0,0 +1,107 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { getFileDataURL, SimpleImageAttachmentAdapter } from "./attachment";
+
+const originalFileReader = globalThis.FileReader;
+const originalBuffer = globalThis.Buffer;
+
+afterEach(() => {
+  globalThis.FileReader = originalFileReader;
+  globalThis.Buffer = originalBuffer;
+});
+
+describe("getFileDataURL", () => {
+  it("uses FileReader when available", async () => {
+    class FakeFileReader {
+      result: string | null = null;
+      onload: (() => void) | null = null;
+      onerror: ((error: unknown) => void) | null = null;
+      readAsDataURL(file: File) {
+        file
+          .arrayBuffer()
+          .then((buf) => {
+            this.result = `data:${file.type};base64,${originalBuffer.from(buf).toString("base64")}`;
+            this.onload?.();
+          })
+          .catch((error) => this.onerror?.(error));
+      }
+    }
+    globalThis.FileReader = FakeFileReader as unknown as typeof FileReader;
+
+    const file = new File(["hello"], "a.txt", { type: "text/plain" });
+    expect(await getFileDataURL(file)).toBe(
+      `data:text/plain;base64,${originalBuffer.from("hello").toString("base64")}`,
+    );
+  });
+
+  it("falls back to Buffer when FileReader is absent", async () => {
+    globalThis.FileReader = undefined as unknown as typeof FileReader;
+
+    const file = new File(["hello"], "a.txt", { type: "text/plain" });
+    expect(await getFileDataURL(file)).toBe(
+      `data:text/plain;base64,${originalBuffer.from("hello").toString("base64")}`,
+    );
+  });
+
+  it("defaults to application/octet-stream when the file has no type", async () => {
+    globalThis.FileReader = undefined as unknown as typeof FileReader;
+
+    const file = new File(["hello"], "a.bin", { type: "" });
+    expect(await getFileDataURL(file)).toBe(
+      `data:application/octet-stream;base64,${originalBuffer.from("hello").toString("base64")}`,
+    );
+  });
+
+  it("falls back to chunked btoa when neither FileReader nor Buffer exist", async () => {
+    globalThis.FileReader = undefined as unknown as typeof FileReader;
+    globalThis.Buffer = undefined as unknown as typeof Buffer;
+
+    const file = new File(["hello"], "a.txt", { type: "text/plain" });
+    expect(await getFileDataURL(file)).toBe(
+      `data:text/plain;base64,${originalBuffer.from("hello").toString("base64")}`,
+    );
+  });
+
+  it("encodes large inputs without RangeError on the btoa path", async () => {
+    globalThis.FileReader = undefined as unknown as typeof FileReader;
+    globalThis.Buffer = undefined as unknown as typeof Buffer;
+
+    const bytes = new Uint8Array(100_000);
+    for (let i = 0; i < bytes.length; i++) bytes[i] = i % 256;
+    const file = new File([bytes], "big.bin", {
+      type: "application/octet-stream",
+    });
+
+    expect(await getFileDataURL(file)).toBe(
+      `data:application/octet-stream;base64,${originalBuffer.from(bytes).toString("base64")}`,
+    );
+  });
+});
+
+describe("SimpleImageAttachmentAdapter", () => {
+  it("assigns unique IDs to files with the same name", async () => {
+    const adapter = new SimpleImageAttachmentAdapter();
+    const first = await adapter.add({
+      file: new File(["first"], "image.png", { type: "image/png" }),
+    });
+    const second = await adapter.add({
+      file: new File(["second"], "image.png", { type: "image/png" }),
+    });
+
+    expect(first.id).not.toBe(second.id);
+    expect(first.name).toBe("image.png");
+    expect(second.name).toBe("image.png");
+  });
+
+  it("sends an image as a data URL", async () => {
+    globalThis.FileReader = undefined as unknown as typeof FileReader;
+
+    const file = new File(["img"], "a.png", { type: "image/png" });
+    const adapter = new SimpleImageAttachmentAdapter();
+    const result = await adapter.send(await adapter.add({ file }));
+    const part = result.content[0];
+    if (part?.type !== "image") throw new Error("expected image content part");
+    expect(part.image).toBe(
+      `data:image/png;base64,${originalBuffer.from("img").toString("base64")}`,
+    );
+  });
+});

package/src/adapters/attachment.ts

@@ -20,7 +20,7 @@ export class SimpleImageAttachmentAdapter implements AttachmentAdapter {
 
   public async add(state: { file: File }): Promise<PendingAttachment> {
     return {
-      id: state.file.name,
+      id: generateId(),
       type: "image",
       name: state.file.name,
       contentType: state.file.type,
@@ -49,21 +49,31 @@ export class SimpleImageAttachmentAdapter implements AttachmentAdapter {
   }
 }
 
-const bytesToBase64 = (bytes: Uint8Array): string =>
-  (
+const bytesToBase64 = (bytes: Uint8Array): string => {
+  const nodeBuffer = (
     globalThis as {
-      Buffer: {
+      Buffer?: {
         from(bytes: Uint8Array): { toString(encoding: string): string };
       };
     }
-  ).Buffer.from(bytes).toString("base64");
+  ).Buffer;
+  if (nodeBuffer) {
+    return nodeBuffer.from(bytes).toString("base64");
+  }
+  let binary = "";
+  const chunkSize = 0x8000;
+  for (let i = 0; i < bytes.length; i += chunkSize) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunkSize));
+  }
+  return btoa(binary);
+};
 
 // React Native's Blob polyfill has FileReader but not file.text()/arrayBuffer(); Node has
 // the reverse. Prefer FileReader when present, falling back to the Blob methods otherwise.
-const getFileDataURL = async (file: File): Promise<string> => {
+export const getFileDataURL = async (file: File): Promise<string> => {
   if (typeof FileReader === "undefined") {
     const buffer = await file.arrayBuffer();
-    return `data:${file.type};base64,${bytesToBase64(new Uint8Array(buffer))}`;
+    return `data:${file.type || "application/octet-stream"};base64,${bytesToBase64(new Uint8Array(buffer))}`;
   }
   return new Promise<string>((resolve, reject) => {
     const reader = new FileReader();
@@ -75,11 +85,11 @@ const getFileDataURL = async (file: File): Promise<string> => {
 
 export class SimpleTextAttachmentAdapter implements AttachmentAdapter {
   public accept =
-    "text/plain,text/html,text/markdown,text/csv,text/xml,text/json,text/css";
+    "text/plain,text/html,text/markdown,text/csv,text/xml,text/json,application/json,text/css";
 
   public async add(state: { file: File }): Promise<PendingAttachment> {
     return {
-      id: state.file.name,
+      id: generateId(),
       type: "document",
       name: state.file.name,
       contentType: state.file.type,
@@ -133,7 +143,7 @@ export function fileMatchesAccept(
     .map((type) => type.trim().toLowerCase());
 
   const fileExtension = `.${file.name.split(".").pop()!.toLowerCase()}`;
-  const fileMimeType = file.type.toLowerCase();
+  const fileMimeType = file.type.split(";", 1)[0]!.trim().toLowerCase();
 
   for (const type of allowedTypes) {
     if (type.startsWith(".") && type === fileExtension) {

package/src/adapters/index.ts

@@ -19,7 +19,12 @@ export type { VoiceSessionControls, VoiceSessionHelpers } from "./voice";
 export type { FeedbackAdapter } from "./feedback";
 
 // Suggestion adapter
-export type { SuggestionAdapter } from "./suggestion";
+export type {
+  SuggestionAdapter,
+  SuggestionAdapterGenerateOptions,
+  CreateSuggestionAdapterOptions,
+} from "./suggestion";
+export { createSuggestionAdapter } from "./suggestion";
 
 // Trigger adapter (generic)
 export type { Unstable_TriggerAdapter } from "./trigger";

package/src/adapters/suggestion.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, it, vi } from "vitest";
+import { consumeSuggestionResult, createSuggestionAdapter } from "./suggestion";
+import type { ThreadMessage } from "../types/message";
+import type { ThreadSuggestion } from "../runtime/interfaces/thread-runtime-core";
+
+const message = (
+  role: "user" | "assistant" | "system",
+  text: string,
+  id = `${role}-${text}`,
+): ThreadMessage =>
+  ({
+    id,
+    role,
+    content: text ? [{ type: "text", text }] : [],
+    createdAt: new Date(),
+    status:
+      role === "assistant" ? { type: "complete", reason: "stop" } : undefined,
+    metadata: {
+      unstable_state: null,
+      unstable_annotations: [],
+      unstable_data: [],
+      custom: {},
+    },
+  }) as unknown as ThreadMessage;
+
+describe("createSuggestionAdapter", () => {
+  it("builds a role-labeled transcript from recent messages and honors maxMessages", async () => {
+    const complete = vi.fn().mockResolvedValue(["follow up"]);
+    const adapter = createSuggestionAdapter({ complete, maxMessages: 2 });
+
+    await adapter.generate({
+      messages: [
+        message("user", "first"),
+        message("assistant", "second"),
+        message("user", "third"),
+        message("assistant", "fourth"),
+      ],
+    });
+
+    expect(complete).toHaveBeenCalledTimes(1);
+    const prompt = complete.mock.calls[0]![0].prompt as string;
+    expect(prompt).toContain("user: third");
+    expect(prompt).toContain("assistant: fourth");
+    expect(prompt).not.toContain("user: first");
+    expect(prompt).not.toContain("assistant: second");
+  });
+
+  it("skips messages with empty text in the transcript", async () => {
+    const complete = vi.fn().mockResolvedValue(["follow up"]);
+    const adapter = createSuggestionAdapter({ complete });
+
+    await adapter.generate({
+      messages: [
+        message("user", "hello"),
+        message("assistant", ""),
+        message("user", "again"),
+      ],
+    });
+
+    const prompt = complete.mock.calls[0]![0].prompt as string;
+    expect(prompt).toContain("user: hello");
+    expect(prompt).toContain("user: again");
+    expect(prompt).not.toMatch(/^assistant:/m);
+  });
+
+  it("includes count and instructions in the prompt", async () => {
+    const complete = vi.fn().mockResolvedValue(["a", "b", "c", "d", "e"]);
+    const adapter = createSuggestionAdapter({
+      complete,
+      count: 5,
+      instructions: "Prefer short product questions",
+    });
+
+    await adapter.generate({
+      messages: [message("user", "hello")],
+    });
+
+    const prompt = complete.mock.calls[0]![0].prompt as string;
+    expect(prompt).toContain("exactly 5");
+    expect(prompt).toContain("Prefer short product questions");
+  });
+
+  it("trims, drops empties, and clamps results to count", async () => {
+    const complete = vi
+      .fn()
+      .mockResolvedValue(["  one  ", "", "  ", "two", "three", "four"]);
+    const adapter = createSuggestionAdapter({ complete, count: 2 });
+
+    const result = await adapter.generate({
+      messages: [message("user", "hello")],
+    });
+
+    expect(result).toEqual([{ prompt: "one" }, { prompt: "two" }]);
+  });
+
+  it("forwards the generate signal to complete when defined", async () => {
+    const complete = vi.fn().mockResolvedValue(["ok"]);
+    const adapter = createSuggestionAdapter({ complete });
+    const controller = new AbortController();
+
+    await adapter.generate({
+      messages: [message("user", "hello")],
+      signal: controller.signal,
+    });
+
+    expect(complete).toHaveBeenCalledWith({
+      prompt: expect.any(String),
+      signal: controller.signal,
+    });
+  });
+
+  it("omits signal from complete options when generate has no signal", async () => {
+    const complete = vi.fn().mockResolvedValue(["ok"]);
+    const adapter = createSuggestionAdapter({ complete });
+
+    await adapter.generate({
+      messages: [message("user", "hello")],
+    });
+
+    expect(complete).toHaveBeenCalledWith({
+      prompt: expect.any(String),
+    });
+    expect(complete.mock.calls[0]![0]).not.toHaveProperty("signal");
+  });
+
+  it("treats maxMessages 0 as an empty transcript while still calling complete", async () => {
+    const complete = vi.fn().mockResolvedValue(["follow up"]);
+    const adapter = createSuggestionAdapter({ complete, maxMessages: 0 });
+
+    await adapter.generate({
+      messages: [message("user", "first"), message("assistant", "second")],
+    });
+
+    expect(complete).toHaveBeenCalledTimes(1);
+    const prompt = complete.mock.calls[0]![0].prompt as string;
+    expect(prompt).toContain("Conversation:\n");
+    expect(prompt).not.toContain("user: first");
+    expect(prompt).not.toContain("assistant: second");
+    expect(prompt).toContain("exactly 3");
+  });
+});
+
+describe("consumeSuggestionResult", () => {
+  it("calls onUpdate for each yield and stops after abort mid-stream", async () => {
+    const controller = new AbortController();
+    const updates: ThreadSuggestion[][] = [];
+    const onUpdate = vi.fn((s: readonly ThreadSuggestion[]) => {
+      updates.push([...s]);
+    });
+
+    async function* generate() {
+      yield [{ prompt: "one" }];
+      yield [{ prompt: "two" }];
+      controller.abort();
+      yield [{ prompt: "three" }];
+      yield [{ prompt: "four" }];
+    }
+
+    await consumeSuggestionResult(generate(), {
+      signal: controller.signal,
+      onUpdate,
+    });
+
+    expect(onUpdate).toHaveBeenCalledTimes(2);
+    expect(updates).toEqual([[{ prompt: "one" }], [{ prompt: "two" }]]);
+  });
+
+  it("drops the promise result when aborted before resolve", async () => {
+    const controller = new AbortController();
+    const onUpdate = vi.fn();
+    let resolve!: (value: readonly ThreadSuggestion[]) => void;
+    const promise = new Promise<readonly ThreadSuggestion[]>((r) => {
+      resolve = r;
+    });
+
+    const consumption = consumeSuggestionResult(promise, {
+      signal: controller.signal,
+      onUpdate,
+    });
+
+    controller.abort();
+    resolve([{ prompt: "late" }]);
+    await consumption;
+
+    expect(onUpdate).not.toHaveBeenCalled();
+  });
+});

package/src/adapters/suggestion.ts

@@ -1,8 +1,10 @@
 import type { ThreadMessage } from "../types/message";
 import type { ThreadSuggestion } from "../runtime/interfaces/thread-runtime-core";
+import { getThreadMessageText } from "../utils/text";
 
-type SuggestionAdapterGenerateOptions = {
+export type SuggestionAdapterGenerateOptions = {
   messages: readonly ThreadMessage[];
+  signal?: AbortSignal;
 };
 
 export type SuggestionAdapter = {
@@ -12,3 +14,75 @@ export type SuggestionAdapter = {
     | Promise<readonly ThreadSuggestion[]>
     | AsyncGenerator<readonly ThreadSuggestion[], void>;
 };
+
+export const consumeSuggestionResult = async (
+  result: ReturnType<SuggestionAdapter["generate"]>,
+  options: {
+    signal: AbortSignal;
+    onUpdate: (suggestions: readonly ThreadSuggestion[]) => void;
+  },
+): Promise<void> => {
+  const { signal, onUpdate } = options;
+  if (Symbol.asyncIterator in result) {
+    for await (const r of result) {
+      if (signal.aborted) break;
+      onUpdate(r);
+    }
+  } else {
+    const suggestions = await result;
+    if (signal.aborted) return;
+    onUpdate(suggestions);
+  }
+};
+
+export type CreateSuggestionAdapterOptions = {
+  complete: (options: {
+    prompt: string;
+    signal?: AbortSignal;
+  }) => Promise<readonly string[]>;
+  count?: number | undefined;
+  instructions?: string | undefined;
+  maxMessages?: number | undefined;
+};
+
+export const createSuggestionAdapter = (
+  options: CreateSuggestionAdapterOptions,
+): SuggestionAdapter => {
+  const count = options.count ?? 3;
+  const maxMessages = options.maxMessages ?? 10;
+
+  return {
+    async generate({ messages, signal }) {
+      const limit = Math.max(0, Math.floor(maxMessages));
+      const recent = limit === 0 ? [] : messages.slice(-limit);
+      const transcript = recent
+        .map((message) => {
+          const text = getThreadMessageText(message).trim();
+          if (!text) return null;
+          return `${message.role}: ${text}`;
+        })
+        .filter((line): line is string => line != null)
+        .join("\n");
+
+      let prompt =
+        `Based on the following conversation, suggest exactly ${count} short follow-up prompts that the USER would plausibly send next. ` +
+        `Write each prompt in the user's voice as something they would type. ` +
+        `Return only the prompts, one per line, with no numbering or extra commentary.\n\n` +
+        `Conversation:\n${transcript}`;
+
+      if (options.instructions) {
+        prompt += `\n\nAdditional instructions:\n${options.instructions}`;
+      }
+
+      const results = await options.complete({
+        prompt,
+        ...(signal !== undefined && { signal }),
+      });
+      return results
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0)
+        .slice(0, count)
+        .map((text) => ({ prompt: text }));
+    },
+  };
+};

package/src/index.ts

@@ -12,6 +12,7 @@ export type {
   // Message parts
   TextMessagePart,
   ReasoningMessagePart,
+  PartProviderMetadata,
   SourceProviderMetadata,
   SourceMessagePart,
   ImageMessagePart,
@@ -149,7 +150,12 @@ export type {
 export type { FeedbackAdapter } from "./adapters/feedback";
 
 // Suggestion adapter
-export type { SuggestionAdapter } from "./adapters/suggestion";
+export type {
+  SuggestionAdapter,
+  SuggestionAdapterGenerateOptions,
+  CreateSuggestionAdapterOptions,
+} from "./adapters/suggestion";
+export { createSuggestionAdapter } from "./adapters/suggestion";
 
 // Directive formatter
 export { unstable_defaultDirectiveFormatter } from "./adapters/directive-formatter";
@@ -188,6 +194,14 @@ export type {
   ThreadComposerRuntimeCore,
 } from "./runtime/interfaces/composer-runtime-core";
 
+export type {
+  ErrorSeverity,
+  ErrorDisplay,
+  AssistantErrorCode,
+  AssistantError,
+} from "./types/error";
+export { toAssistantError, isAssistantError } from "./types/error";
+
 export type {
   RuntimeCapabilities,
   AddToolResultOptions,

package/src/internal.ts

@@ -33,10 +33,26 @@ export {
 // Message utilities
 export { getThreadMessageText } from "./utils/text";
 export { resolveToolApprovalResponse } from "./runtime/utils/resolveToolApprovalResponse";
+export { consumeSuggestionResult } from "./adapters/suggestion";
 
 // Composite context provider
 export { CompositeContextProvider } from "./utils/composite-context-provider";
 
+// Shared attachment data-URL encoder, reused by framework adapters so the
+// FileReader fallback lives in one place.
+export { getFileDataURL } from "./adapters/attachment";
+
+// Streaming-stable tool-args stringifier, reused by framework adapters so the
+// key-order stabilization lives in one place.
+export {
+  stableStringifyToolArgs,
+  trackToolArgsKeyOrder,
+} from "./utils/json/stable-stringify-tool-args";
+
+// JSON type guards, reused by framework bindings so the depth-guarded
+// validation lives in one place.
+export { isJSONValue, isRecord } from "./utils/json/is-json";
+
 // Runtime extras helper for external-store adapters. Internal because the
 // tap-native runtime path replaces the `thread.extras` side-channel it wraps.
 export {

package/src/model-context/tool.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+import type { Tool } from "assistant-stream";
+import type { AsyncIterableStream } from "assistant-stream/utils";
+import { tool } from "./tool";
+
+type TestStandardSchema<TInput> = {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: "test";
+    readonly types?: {
+      readonly input: TInput;
+      readonly output: TInput;
+    };
+    readonly validate: (value: unknown) => { readonly value: TInput };
+  };
+};
+
+const checkStandardSchemaInference = () => {
+  const weatherSchema = {} as TestStandardSchema<{
+    city: string;
+    unit?: "c" | "f";
+    tags: string[];
+  }>;
+
+  const getWeather = tool({
+    type: "frontend",
+    parameters: weatherSchema,
+    execute: async (args) => {
+      expectTypeOf(args.city).toEqualTypeOf<string>();
+      expectTypeOf(args.unit).toEqualTypeOf<"c" | "f" | undefined>();
+      expectTypeOf(args.tags).toEqualTypeOf<string[]>();
+      // @ts-expect-error unknown schema fields should not be accepted
+      void args.missing;
+
+      return `Weather in ${args.city}`;
+    },
+    streamCall: async (reader) => {
+      const city = await reader.args.get("city");
+      expectTypeOf(city).toEqualTypeOf<string>();
+      expectTypeOf(reader.args.forEach("tags")).toEqualTypeOf<
+        AsyncIterableStream<string>
+      >();
+      // @ts-expect-error unknown argument paths should not be accepted
+      reader.args.get("missing");
+    },
+    toModelOutput: ({ input }) => {
+      expectTypeOf(input.city).toEqualTypeOf<string>();
+      expectTypeOf(input.unit).toEqualTypeOf<"c" | "f" | undefined>();
+      return [{ type: "text", text: input.city }];
+    },
+  });
+
+  expectTypeOf(getWeather).toEqualTypeOf<
+    Tool<
+      {
+        city: string;
+        unit?: "c" | "f";
+        tags: string[];
+      },
+      string
+    >
+  >();
+};
+expectTypeOf(checkStandardSchemaInference).toEqualTypeOf<() => void>();
+
+const checkUnknownStandardSchemaInputFallsBackToRecord = () => {
+  const unknownSchema = {} as TestStandardSchema<unknown>;
+
+  const passthrough = tool({
+    type: "frontend",
+    parameters: unknownSchema,
+    execute: async (args) => {
+      expectTypeOf(args).toEqualTypeOf<Record<string, unknown>>();
+      return args;
+    },
+  });
+
+  expectTypeOf(passthrough).toEqualTypeOf<
+    Tool<Record<string, unknown>, Record<string, unknown>>
+  >();
+};
+expectTypeOf(checkUnknownStandardSchemaInputFallsBackToRecord).toEqualTypeOf<
+  () => void
+>();
+
+const checkExplicitJsonSchemaTypesStillWork = () => {
+  const getWeather = tool<{ city: string }, string>({
+    type: "frontend",
+    parameters: {
+      type: "object",
+      properties: { city: { type: "string" } },
+      required: ["city"],
+    },
+    execute: async ({ city }) => city,
+  });
+
+  expectTypeOf(getWeather).toEqualTypeOf<Tool<{ city: string }, string>>();
+};
+expectTypeOf(checkExplicitJsonSchemaTypesStillWork).toEqualTypeOf<() => void>();
+
+describe("tool", () => {
+  it("returns the tool definition at runtime", () => {
+    const definition = {
+      type: "frontend" as const,
+      parameters: { type: "object" as const, properties: {} },
+    };
+
+    expect(tool(definition)).toBe(definition);
+  });
+});