@assistant-ui/core 0.2.20 → 0.2.22

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

@@ -0,0 +1,205 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  ThreadComposerRuntimeImpl,
+  type ThreadComposerRuntimeCoreBinding,
+} from "../runtime/api/composer-runtime";
+import {
+  ThreadRuntimeImpl,
+  type ThreadListItemRuntimeBinding,
+  type ThreadRuntimeCoreBinding,
+} from "../runtime/api/thread-runtime";
+import { ThreadListItemRuntimeImpl } from "../runtime/api/thread-list-item-runtime";
+import type { ThreadListRuntimeCoreBinding } from "../runtime/api/thread-list-runtime";
+import { ReadonlyThreadRuntimeCore } from "../runtimes/readonly/ReadonlyThreadRuntimeCore";
+import type { Unsubscribe } from "../types/unsubscribe";
+
+type EventListener = (payload?: unknown) => unknown;
+
+class GuardedEventSource {
+  private listeners = new Set<EventListener>();
+
+  public unstable_on = (
+    _event: string,
+    listener: EventListener,
+  ): Unsubscribe => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  public emit(payload?: unknown) {
+    for (const listener of this.listeners) {
+      try {
+        const result = listener(payload);
+        if (
+          typeof result === "object" &&
+          result !== null &&
+          "then" in result &&
+          typeof result.then === "function"
+        ) {
+          void Promise.resolve(result).catch((error) => {
+            console.error("[test source] listener error", error);
+          });
+        }
+      } catch (error) {
+        console.error("[test source] listener error", error);
+      }
+    }
+  }
+}
+
+type RuntimeHarness = {
+  subscribe: (listener: EventListener) => Unsubscribe;
+  emit: () => void;
+  errorContext: string;
+};
+
+const makeComposerHarness = (): RuntimeHarness => {
+  const source = new GuardedEventSource();
+  const binding = {
+    path: {
+      ref: "test.composer",
+      threadSelector: { type: "main" },
+      composerSource: "thread",
+    },
+    getState: () => ({ unstable_on: source.unstable_on }),
+    subscribe: () => () => {},
+  } as unknown as ThreadComposerRuntimeCoreBinding;
+  const runtime = new ThreadComposerRuntimeImpl(binding);
+
+  return {
+    subscribe: (listener) =>
+      runtime.unstable_on("attachmentAdd", listener as never),
+    emit: () => source.emit({}),
+    errorContext: 'Runtime event "attachmentAdd"',
+  };
+};
+
+const makeThreadHarness = (): RuntimeHarness => {
+  const source = new GuardedEventSource();
+  const core = new ReadonlyThreadRuntimeCore();
+  core.unstable_on = source.unstable_on as typeof core.unstable_on;
+
+  const path = {
+    ref: "test.thread",
+    threadSelector: { type: "main" as const },
+  };
+  const threadBinding: ThreadRuntimeCoreBinding = {
+    path,
+    getState: () => core,
+    subscribe: (listener) => core.subscribe(listener),
+    outerSubscribe: (listener) => core.subscribe(listener),
+  };
+  const threadListItemBinding: ThreadListItemRuntimeBinding = {
+    path,
+    getState: () => ({
+      id: "test",
+      remoteId: undefined,
+      externalId: undefined,
+      isMain: true,
+      status: "regular",
+      title: undefined,
+    }),
+    subscribe: () => () => {},
+  };
+  const runtime = new ThreadRuntimeImpl(threadBinding, threadListItemBinding);
+
+  return {
+    subscribe: (listener) => runtime.unstable_on("initialize", listener),
+    emit: () => source.emit({}),
+    errorContext: 'Runtime event "initialize"',
+  };
+};
+
+const makeThreadListItemHarness = (): RuntimeHarness => {
+  let isMain = true;
+  const stateListeners = new Set<() => void>();
+  const binding = {
+    path: {
+      ref: "test.threadListItem",
+      threadSelector: { type: "main" as const },
+    },
+    getState: () => ({
+      id: "test",
+      remoteId: undefined,
+      externalId: undefined,
+      isMain,
+      status: "regular" as const,
+      title: undefined,
+    }),
+    subscribe: (listener: () => void) => {
+      stateListeners.add(listener);
+      return () => stateListeners.delete(listener);
+    },
+  } as unknown as ThreadListItemRuntimeBinding;
+  const runtime = new ThreadListItemRuntimeImpl(
+    binding,
+    {} as ThreadListRuntimeCoreBinding,
+  );
+
+  return {
+    subscribe: (listener) =>
+      runtime.unstable_on("switchedAway", listener as never),
+    emit: () => {
+      isMain = !isMain;
+      for (const listener of [...stateListeners]) listener();
+    },
+    errorContext: 'Thread list item "switchedAway"',
+  };
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe.each([
+  ["composer", makeComposerHarness],
+  ["thread", makeThreadHarness],
+  ["thread list item", makeThreadListItemHarness],
+] as const)("%s public unstable_on", (_name, makeHarness) => {
+  it("continues notifying sibling listeners after a synchronous error", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const harness = makeHarness();
+    const sibling = vi.fn();
+
+    harness.subscribe(() => {
+      throw new Error("listener failed");
+    });
+    harness.subscribe(sibling);
+
+    harness.emit();
+
+    expect(sibling).toHaveBeenCalledOnce();
+  });
+
+  it.each(["object", "function"] as const)(
+    "handles rejected %s thenables returned by listeners",
+    async (thenableType) => {
+      const consoleError = vi
+        .spyOn(console, "error")
+        .mockImplementation(() => {});
+      const harness = makeHarness();
+      const listenerError = new Error("async listener failed");
+      const then = vi.fn(
+        (
+          _resolve: (value?: unknown) => void,
+          reject: (reason?: unknown) => void,
+        ) => reject(listenerError),
+      );
+      const thenable =
+        thenableType === "function"
+          ? Object.assign(() => {}, { then })
+          : { then };
+
+      harness.subscribe(() => thenable);
+      harness.emit();
+
+      await vi.waitFor(() => {
+        expect(then).toHaveBeenCalledOnce();
+        expect(consoleError).toHaveBeenCalledWith(
+          expect.stringContaining(harness.errorContext),
+          listenerError,
+        );
+      });
+    },
+  );
+});

package/src/tests/remote-thread-list-test-helpers.ts

@@ -18,6 +18,19 @@ export const contextProvider: ModelContextProvider = {
   subscribe: () => () => {},
 };
 
+export function setStartThreadRuntime(
+  core: RemoteThreadListThreadListRuntimeCore,
+  startThreadRuntime: (id: string) => Promise<unknown>,
+) {
+  (
+    core as unknown as {
+      _hookManager: {
+        startThreadRuntime: (id: string) => Promise<unknown>;
+      };
+    }
+  )._hookManager.startThreadRuntime = startThreadRuntime;
+}
+
 export function makeAdapter(
   overrides: Partial<RemoteThreadListAdapter> = {},
 ): RemoteThreadListAdapter {
@@ -60,12 +73,6 @@ export function createCore(
   );
   // `startThreadRuntime` blocks until a React component attaches a runtime;
   // stub it so non-React unit tests don't hang.
-  (
-    core as unknown as {
-      _hookManager: {
-        startThreadRuntime: (id: string) => Promise<unknown>;
-      };
-    }
-  )._hookManager.startThreadRuntime = async () => ({});
+  setStartThreadRuntime(core, async () => ({}));
   return core;
 }

package/src/tests/thread-message-like.test.ts

@@ -160,4 +160,101 @@ describe("fromThreadMessageLike", () => {
       expect(result.content).toEqual([]);
     });
   });
+
+  describe("providerMetadata passthrough", () => {
+    it("keeps providerMetadata on text, reasoning, and tool-call parts", () => {
+      const providerMetadata = { acme: { agentName: "researcher" } };
+      const result = fromThreadMessageLike(
+        {
+          role: "assistant",
+          content: [
+            { type: "text", text: "hi", providerMetadata },
+            { type: "reasoning", text: "thinking", providerMetadata },
+            {
+              type: "tool-call",
+              toolCallId: "tc-1",
+              toolName: "search",
+              args: { query: "hi" },
+              providerMetadata,
+            },
+          ],
+        },
+        fallbackId,
+        fallbackStatus,
+      );
+
+      expect(result.content[0]).toMatchObject({
+        type: "text",
+        text: "hi",
+        providerMetadata,
+      });
+      expect(result.content[1]).toMatchObject({
+        type: "reasoning",
+        text: "thinking",
+        providerMetadata,
+      });
+      expect(result.content[2]).toMatchObject({
+        type: "tool-call",
+        toolCallId: "tc-1",
+        providerMetadata,
+      });
+    });
+  });
+
+  describe("metadata.isOptimistic", () => {
+    it("preserves isOptimistic on user messages", () => {
+      const result = fromThreadMessageLike(
+        {
+          role: "user",
+          content: [{ type: "text", text: "hello" }],
+          metadata: { isOptimistic: true },
+        },
+        fallbackId,
+        fallbackStatus,
+      );
+
+      expect(result.metadata.isOptimistic).toBe(true);
+    });
+
+    it("preserves isOptimistic on assistant messages", () => {
+      const result = fromThreadMessageLike(
+        {
+          role: "assistant",
+          content: [{ type: "text", text: "hello" }],
+          metadata: { isOptimistic: true },
+        },
+        fallbackId,
+        fallbackStatus,
+      );
+
+      expect(result.metadata.isOptimistic).toBe(true);
+    });
+
+    it("omits isOptimistic when false", () => {
+      const result = fromThreadMessageLike(
+        {
+          role: "user",
+          content: [{ type: "text", text: "hello" }],
+          metadata: { isOptimistic: false },
+        },
+        fallbackId,
+        fallbackStatus,
+      );
+
+      expect(result.metadata).not.toHaveProperty("isOptimistic");
+    });
+
+    it("omits isOptimistic when not set", () => {
+      const result = fromThreadMessageLike(
+        {
+          role: "user",
+          content: [{ type: "text", text: "hello" }],
+        },
+        fallbackId,
+        fallbackStatus,
+      );
+
+      expect(result.metadata).not.toHaveProperty("isOptimistic");
+    });
+  });
 });

package/src/types/attachment.ts

@@ -13,6 +13,7 @@ export type PendingAttachmentStatus =
   | {
       type: "incomplete";
       reason: "error" | "upload-paused";
+      message?: string;
     };
 
 export type CompleteAttachmentStatus = {
@@ -51,3 +52,8 @@ export type CreateAttachment = {
   contentType?: string;
   content: ThreadUserMessagePart[];
 };
+
+export const isCreateAttachment = (
+  attachment: File | CreateAttachment,
+): attachment is CreateAttachment =>
+  "content" in attachment && !("lastModified" in attachment);

package/src/types/error.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect } from "vitest";
+import {
+  toAssistantError,
+  isAssistantError,
+  type AssistantError,
+} from "./error";
+
+describe("toAssistantError", () => {
+  it("converts an Error instance", () => {
+    expect(toAssistantError(new Error("boom"))).toEqual({
+      code: "unknown",
+      message: "boom",
+    });
+  });
+
+  it("converts a string", () => {
+    expect(toAssistantError("plain failure")).toEqual({
+      code: "unknown",
+      message: "plain failure",
+    });
+  });
+
+  it("converts a plain object", () => {
+    const value = { foo: 1 };
+    expect(toAssistantError(value)).toEqual({
+      code: "unknown",
+      message: `[object] ${String(value)}`,
+    });
+  });
+
+  it("converts a thrown Symbol", () => {
+    const value = Symbol("x");
+    expect(toAssistantError(value)).toEqual({
+      code: "unknown",
+      message: `[symbol] ${String(value)}`,
+    });
+  });
+
+  it("converts a thrown number", () => {
+    expect(toAssistantError(42)).toEqual({
+      code: "unknown",
+      message: "[number] 42",
+    });
+  });
+
+  it("converts a thrown null", () => {
+    expect(toAssistantError(null)).toEqual({
+      code: "unknown",
+      message: "[object] null",
+    });
+  });
+
+  it("converts an object whose toString throws", () => {
+    const value = {
+      toString() {
+        throw new Error("toString failed");
+      },
+    };
+    expect(toAssistantError(value)).toEqual({
+      code: "unknown",
+      message: "[object]",
+    });
+  });
+
+  it("passes an AssistantError through unchanged", () => {
+    const error: AssistantError = {
+      code: "network",
+      message: "offline",
+      severity: "warning",
+      display: "toast",
+    };
+    expect(toAssistantError(error)).toBe(error);
+  });
+});
+
+describe("isAssistantError", () => {
+  it("accepts a minimal valid value", () => {
+    expect(isAssistantError({ code: "unknown", message: "x" })).toBe(true);
+  });
+
+  it("accepts optional severity and display literals", () => {
+    expect(
+      isAssistantError({
+        code: "provider",
+        message: "rate limited",
+        severity: "info",
+        display: "silent",
+      }),
+    ).toBe(true);
+  });
+
+  it("rejects non-objects", () => {
+    expect(isAssistantError("fail")).toBe(false);
+    expect(isAssistantError(null)).toBe(false);
+    expect(isAssistantError(undefined)).toBe(false);
+  });
+
+  it("rejects missing code or message", () => {
+    expect(isAssistantError({ code: "unknown" })).toBe(false);
+    expect(isAssistantError({ message: "x" })).toBe(false);
+  });
+
+  it("rejects a bad severity literal", () => {
+    expect(
+      isAssistantError({
+        code: "unknown",
+        message: "x",
+        severity: "fatal",
+      }),
+    ).toBe(false);
+  });
+
+  it("rejects a bad display literal", () => {
+    expect(
+      isAssistantError({
+        code: "unknown",
+        message: "x",
+        display: "modal",
+      }),
+    ).toBe(false);
+  });
+});

package/src/types/error.ts

@@ -0,0 +1,74 @@
+export type ErrorSeverity = "critical" | "warning" | "info";
+
+export type ErrorDisplay = "inline" | "toast" | "silent" | "dev-only";
+
+export type AssistantErrorCode =
+  | "unknown"
+  | "network"
+  | "provider"
+  | (string & {});
+
+export type AssistantError = {
+  readonly code: AssistantErrorCode;
+  readonly message: string;
+  readonly severity?: ErrorSeverity;
+  readonly display?: ErrorDisplay;
+};
+
+const ERROR_SEVERITIES: readonly string[] = ["critical", "warning", "info"];
+
+const ERROR_DISPLAYS: readonly string[] = [
+  "inline",
+  "toast",
+  "silent",
+  "dev-only",
+];
+
+export const isAssistantError = (value: unknown): value is AssistantError => {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Record<string, unknown>;
+  if (
+    typeof candidate.code !== "string" ||
+    typeof candidate.message !== "string"
+  ) {
+    return false;
+  }
+  if (
+    "severity" in candidate &&
+    candidate.severity !== undefined &&
+    (typeof candidate.severity !== "string" ||
+      !ERROR_SEVERITIES.includes(candidate.severity))
+  ) {
+    return false;
+  }
+  if (
+    "display" in candidate &&
+    candidate.display !== undefined &&
+    (typeof candidate.display !== "string" ||
+      !ERROR_DISPLAYS.includes(candidate.display))
+  ) {
+    return false;
+  }
+  return true;
+};
+
+export const toAssistantError = (error: unknown): AssistantError => {
+  if (isAssistantError(error)) return error;
+  if (error instanceof Error) {
+    return { code: "unknown", message: error.message };
+  }
+  if (typeof error === "string") {
+    return { code: "unknown", message: error };
+  }
+  try {
+    return {
+      code: "unknown",
+      message: `[${typeof error}] ${String(error)}`,
+    };
+  } catch {
+    return {
+      code: "unknown",
+      message: `[${typeof error}]`,
+    };
+  }
+};

package/src/types/index.ts

@@ -2,6 +2,7 @@ export type {
   // Message parts
   TextMessagePart,
   ReasoningMessagePart,
+  PartProviderMetadata,
   SourceProviderMetadata,
   SourceMessagePart,
   ImageMessagePart,

package/src/types/message.ts

@@ -7,21 +7,25 @@ import type { CompleteAttachment } from "./attachment";
 
 export type { ToolCallTiming, ToolModelContentPart };
 
+export type PartProviderMetadata = {
+  readonly [providerName: string]: ReadonlyJSONObject;
+};
+
 export type TextMessagePart = {
   readonly type: "text";
   readonly text: string;
+  readonly providerMetadata?: PartProviderMetadata;
   readonly parentId?: string;
 };
 
 export type ReasoningMessagePart = {
   readonly type: "reasoning";
   readonly text: string;
+  readonly providerMetadata?: PartProviderMetadata;
   readonly parentId?: string;
 };
 
-export type SourceProviderMetadata = {
-  readonly [providerName: string]: ReadonlyJSONObject;
-};
+export type SourceProviderMetadata = PartProviderMetadata;
 
 export type SourceMessagePart =
   | {
@@ -124,6 +128,8 @@ export type McpAppMetadata = {
   readonly resourceUri: string;
   readonly mimeType?: string;
   readonly visibility?: readonly ("model" | "app")[];
+  /** Routable server identity emitted by the agent stack when multiple MCP servers back one agent; for @ag-ui/mcp-apps-middleware this is the configured serverId, falling back to its serverHash. */
+  readonly serverId?: string;
 };
 
 export const MCP_APP_URI_SCHEME = "ui://";
@@ -197,6 +203,8 @@ export type ToolCallMessagePart<
   readonly timing?: ToolCallTiming;
   /** MCP app metadata associated with this tool call, when present. */
   readonly mcp?: ToolCallMessagePartMcpMetadata;
+  /** Provider metadata associated with this tool call, when present. */
+  readonly providerMetadata?: PartProviderMetadata;
   /** Content returned to the model for this tool result. */
   readonly modelContent?: readonly ToolModelContentPart[] | undefined;
   /** Human-input request that must be resolved before the run can continue. */
@@ -341,6 +349,7 @@ export type ThreadUserMessage = MessageCommonProps & {
     readonly steps?: undefined;
     readonly submittedFeedback?: undefined;
     readonly timing?: undefined;
+    readonly isOptimistic?: boolean;
     readonly custom: Record<string, unknown>;
   };
 };

package/src/utils/data-url.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from "vitest";
+import { httpUrlPattern, parseDataUrl } from "./data-url";
+
+describe("parseDataUrl", () => {
+  it("parses a base64 data URL", () => {
+    expect(parseDataUrl("data:image/png;base64,aGVsbG8=")).toEqual({
+      mimeType: "image/png",
+      data: "aGVsbG8=",
+    });
+  });
+
+  it("parses a data URL with extra parameters", () => {
+    expect(parseDataUrl("data:text/plain;charset=utf-8;base64,aGk=")).toEqual({
+      mimeType: "text/plain",
+      data: "aGk=",
+    });
+  });
+
+  it("returns null for non-base64 data URLs", () => {
+    expect(parseDataUrl("data:text/plain,hello")).toBeNull();
+  });
+
+  it("returns null for data URLs with an empty payload", () => {
+    expect(parseDataUrl("data:image/png;base64,")).toBeNull();
+  });
+
+  it("returns null for plain strings", () => {
+    expect(parseDataUrl("aGVsbG8=")).toBeNull();
+  });
+
+  it("returns null for http URLs", () => {
+    expect(parseDataUrl("https://example.com/a.png")).toBeNull();
+  });
+});
+
+describe("httpUrlPattern", () => {
+  it.each(["http://example.com", "https://example.com", "HTTPS://EXAMPLE.COM"])(
+    "matches %s",
+    (value) => {
+      expect(httpUrlPattern.test(value)).toBe(true);
+    },
+  );
+
+  it.each(["ftp://example.com", "data:image/png;base64,aGk=", "/relative"])(
+    "does not match %s",
+    (value) => {
+      expect(httpUrlPattern.test(value)).toBe(false);
+    },
+  );
+});

package/src/utils/data-url.ts

@@ -0,0 +1,9 @@
+export const httpUrlPattern = /^https?:\/\//i;
+
+export function parseDataUrl(
+  value: string,
+): { mimeType: string; data: string } | null {
+  const match = value.match(/^data:([^;,]+)(?:;[^;,]+)*;base64,(.+)$/);
+  if (!match) return null;
+  return { mimeType: match[1]!, data: match[2]! };
+}