@assistant-ui/core 0.3.19 → 0.3.21

package/src/subscribable/subscribable.ts

@@ -31,6 +31,13 @@ export type EventSubscribable<TEvent extends string> = {
     | undefined,
     unknown
   >;
+  /**
+   * Notifies subscribers with an empty payload when the binding swaps to a
+   * different source. For an event that reports a change to a value read off
+   * the source rather than an occurrence in time, the swap is itself such a
+   * change, and the previous source never announces it.
+   */
+  notifyOnRebind?: boolean;
 };
 
 export const notifySubscribers = <TArgs extends unknown[]>(
@@ -62,6 +69,21 @@ export const runCleanups = (cleanups: Iterable<Unsubscribe>): void => {
   notifySubscribers(cleanups);
 };
 
+const rollbackSubscription = (
+  cleanup: Unsubscribe,
+  connectionError: unknown,
+): never => {
+  try {
+    cleanup();
+  } catch (cleanupError) {
+    console.error(
+      "[assistant-ui] Subscription rollback cleanup threw",
+      cleanupError,
+    );
+  }
+  throw connectionError;
+};
+
 const shallowEqualOrUndefined = <T extends object>(
   a: T | undefined,
   b: T | undefined,
@@ -148,7 +170,12 @@ export abstract class BaseSubject {
 
   public subscribe(callback: (payload?: unknown) => void) {
     this._subscriptions.add(callback);
-    this._updateConnection();
+    try {
+      this._updateConnection();
+    } catch (error) {
+      this._subscriptions.delete(callback);
+      throw error;
+    }
 
     return () => {
       this._subscriptions.delete(callback);
@@ -198,8 +225,12 @@ export class ShallowMemoizeSubject<TState extends object, TPath>
     };
 
     const unsubscribe = this.binding.subscribe(callback);
-    this._syncState();
-    return unsubscribe;
+    try {
+      this._syncState();
+      return unsubscribe;
+    } catch (error) {
+      throw rollbackSubscription(unsubscribe, error);
+    }
   }
 }
 
@@ -299,9 +330,14 @@ export class NestedSubscriptionSubject<
       }
     };
 
-    const outerUnsubscribe = this.outerSubscribe(onRuntimeUpdate);
+    let outerUnsubscribe: Unsubscribe;
+    try {
+      outerUnsubscribe = this.outerSubscribe(onRuntimeUpdate);
+    } catch (error) {
+      throw rollbackSubscription(() => innerUnsubscribe?.(), error);
+    }
     return () =>
-      runCleanups([() => outerUnsubscribe?.(), () => innerUnsubscribe?.()]);
+      runCleanups([() => outerUnsubscribe(), () => innerUnsubscribe?.()]);
   }
 }
 
@@ -342,11 +378,17 @@ export class EventSubscriptionSubject<
         previousInner?.();
       } finally {
         innerUnsubscribe = newState?.unstable_on(this.config.event, callback);
+        if (this.config.notifyOnRebind) callback({});
       }
     };
 
-    const outerUnsubscribe = this.outerSubscribe(onRuntimeUpdate);
+    let outerUnsubscribe: Unsubscribe;
+    try {
+      outerUnsubscribe = this.outerSubscribe(onRuntimeUpdate);
+    } catch (error) {
+      throw rollbackSubscription(() => innerUnsubscribe?.(), error);
+    }
     return () =>
-      runCleanups([() => outerUnsubscribe?.(), () => innerUnsubscribe?.()]);
+      runCleanups([() => outerUnsubscribe(), () => innerUnsubscribe?.()]);
   }
 }

package/src/tests/RemoteThreadListThreadListRuntimeCore-errors.test.ts

@@ -1,5 +1,12 @@
 import { describe, it, expect, vi } from "vitest";
-import { createCore, makeAdapter } from "./remote-thread-list-test-helpers";
+import {
+  contextProvider,
+  createCore,
+  deferred,
+  makeAdapter,
+  setStartThreadRuntime,
+} from "./remote-thread-list-test-helpers";
+import { RemoteThreadListThreadListRuntimeCore } from "../react/runtimes/RemoteThreadListThreadListRuntimeCore";
 import { InMemoryThreadListAdapter } from "../runtimes/remote-thread-list/adapter/in-memory";
 
 describe("RemoteThreadListThreadListRuntimeCore errors", () => {
@@ -32,6 +39,61 @@ describe("RemoteThreadListThreadListRuntimeCore errors", () => {
     );
   });
 
+  it("logs a controlled threadId switch that fails when the list mounts", async () => {
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const fetchError = new Error("fetch failed");
+    const core = createCore(
+      makeAdapter({
+        fetch: vi.fn(async () => {
+          throw fetchError;
+        }),
+      }),
+      "missing-thread",
+    );
+
+    core.__internal_load();
+    await new Promise((resolve) => setTimeout(resolve));
+
+    expect(error).toHaveBeenCalledWith(
+      "[assistant-ui] thread list switch failed:",
+      fetchError,
+    );
+    error.mockRestore();
+  });
+
+  it("logs a controlled threadId switch that fails when the threadId prop changes", async () => {
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const fetchError = new Error("fetch failed");
+    const adapter = makeAdapter({
+      fetch: vi.fn(async () => {
+        throw fetchError;
+      }),
+    });
+    const runtimeHook = () => ({}) as never;
+    const core = new RemoteThreadListThreadListRuntimeCore(
+      { adapter, runtimeHook, threadId: undefined },
+      contextProvider,
+    );
+    setStartThreadRuntime(core, async () => ({}));
+    core.__internal_load();
+    await core.getLoadThreadsPromise();
+    const mainThreadId = core.mainThreadId;
+
+    core.__internal_setOptions({
+      adapter,
+      runtimeHook,
+      threadId: "missing-thread",
+    });
+    await new Promise((resolve) => setTimeout(resolve));
+
+    expect(error).toHaveBeenCalledWith(
+      "[assistant-ui] thread list switch failed:",
+      fetchError,
+    );
+    expect(core.mainThreadId).toBe(mainThreadId);
+    error.mockRestore();
+  });
+
   it("includes the requested thread id when the in-memory adapter cannot fetch it", async () => {
     const adapter = new InMemoryThreadListAdapter();
 
@@ -39,4 +101,36 @@ describe("RemoteThreadListThreadListRuntimeCore errors", () => {
       'Thread "missing-thread" not found in in-memory thread list.',
     );
   });
+
+  it.each(["archive", "delete", "detach"] as const)(
+    "rejects %s of the main thread when its initialize fails instead of looping",
+    async (operation) => {
+      const initialization = deferred<{
+        remoteId: string;
+        externalId: string;
+      }>();
+      const core = createCore(
+        makeAdapter({ initialize: vi.fn(() => initialization.promise) }),
+      );
+      await core.getLoadThreadsPromise();
+      const localId = core.newThreadId!;
+      const initializing = core.initialize(localId).catch(() => {});
+
+      let fallbackSwitches = 0;
+      const switchToNewThread = core.switchToNewThread.bind(core);
+      core.switchToNewThread = () => {
+        if (++fallbackSwitches > 50) throw new Error("livelock");
+        return switchToNewThread();
+      };
+
+      const operating = core[operation](localId);
+      initialization.reject(new Error("initialize failed"));
+      await initializing;
+
+      await expect(operating).rejects.toThrow(
+        "Cannot ensure new thread is not main",
+      );
+      expect(core.mainThreadId).toBe(localId);
+    },
+  );
 });

package/src/tests/attachment-adapters.test.ts

@@ -63,7 +63,22 @@ describe("SimpleTextAttachmentAdapter", () => {
     expect(complete.content).toEqual([
       {
         type: "text",
-        text: "<attachment name=notes.md>\n- retry with backoff\n- cap attempts at 3\n</attachment>",
+        text: '<attachment name="notes.md">\n- retry with backoff\n- cap attempts at 3\n</attachment>',
+      },
+    ]);
+  });
+
+  it("quotes and escapes filenames in the attachment wrapper", async () => {
+    const adapter = new SimpleTextAttachmentAdapter();
+    const pending = (await adapter.add({
+      file: makeFile("hello", `my "notes" & <draft>'s.md`),
+    })) as PendingAttachment;
+    const complete = await adapter.send(pending);
+
+    expect(complete.content).toEqual([
+      {
+        type: "text",
+        text: '<attachment name="my &quot;notes&quot; &amp; &lt;draft&gt;\'s.md">\nhello\n</attachment>',
       },
     ]);
   });

package/src/tests/auiV0Encode.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it, vi } from "vitest";
-import { auiV0Decode, auiV0Encode } from "../react/runtimes/cloud/auiV0";
+import {
+  auiV0Decode,
+  auiV0DecodeSafely,
+  auiV0Encode,
+} from "../react/runtimes/cloud/auiV0";
 
 describe("auiV0Encode", () => {
   it("preserves document source parts in the core cloud encoder", () => {
@@ -387,6 +391,40 @@ describe("auiV0Encode", () => {
       { type: "data", name: "PredictState", data: '{"steps":["a","b"]}' },
     ]);
   });
+
+  it("omits absent image filename and provider metadata", () => {
+    const content = auiV0Encode({
+      id: "local",
+      createdAt: new Date("2026-03-15T00:00:00.000Z"),
+      role: "user",
+      metadata: { custom: {} },
+      attachments: [],
+      content: [{ type: "image", image: "data:image/png;base64,iVBORw0KGgo=" }],
+    });
+
+    const image = content.content[0];
+    expect(image).not.toHaveProperty("filename");
+    expect(image).not.toHaveProperty("providerMetadata");
+  });
+
+  it("omits absent text provider metadata", () => {
+    const content = auiV0Encode({
+      id: "local",
+      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: "text", text: "answer" }],
+    });
+
+    expect(content.content[0]).not.toHaveProperty("providerMetadata");
+  });
 });
 
 describe("auiV0Decode", () => {
@@ -588,6 +626,18 @@ describe("auiV0Decode", () => {
     ],
   });
 
+  const artifact = { reportId: "report-1" };
+  const artifactModelContent = [
+    { type: "text" as const, text: "The report is ready." },
+    {
+      type: "file" as const,
+      data: "data:application/pdf;base64,JVBERi0xLjQ=",
+      mediaType: "application/pdf",
+      filename: "report.pdf",
+    },
+  ];
+  const providerMetadata = { openai: { responseId: "resp-1" } };
+
   it.each([
     ["false", false],
     ["zero", 0],
@@ -617,6 +667,157 @@ describe("auiV0Decode", () => {
     }
   });
 
+  it("keeps tool-call artifact, model content, and provider metadata", () => {
+    const encoded = auiV0Encode(
+      toolCallMessage({
+        artifact,
+        modelContent: artifactModelContent,
+        providerMetadata,
+      }),
+    );
+
+    const toolCall = encoded.content.find((p) => p.type === "tool-call");
+    expect(toolCall).toMatchObject({
+      artifact,
+      modelContent: artifactModelContent,
+      providerMetadata,
+    });
+  });
+
+  it("restores tool-call artifact, model content, and provider metadata", () => {
+    const encoded = auiV0Encode(
+      toolCallMessage({
+        artifact,
+        modelContent: artifactModelContent,
+        providerMetadata,
+      }),
+    );
+    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).toMatchObject({
+      artifact,
+      modelContent: artifactModelContent,
+      providerMetadata,
+    });
+  });
+
+  it("omits a non-JSON tool-call artifact without dropping the result", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const encoded = auiV0Encode(
+        toolCallMessage({
+          artifact: { value: 1n },
+          result: { kept: true },
+        }),
+      );
+
+      const toolCall = encoded.content.find((p) => p.type === "tool-call");
+      expect(toolCall).not.toHaveProperty("artifact");
+      expect(toolCall).toHaveProperty("result", { kept: true });
+      expect(warn).toHaveBeenCalledWith(
+        "tool-call artifact is not JSON for call-1",
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("stores a non-finite number in an artifact as JSON does, as null", () => {
+    const encoded = auiV0Encode(
+      toolCallMessage({ artifact: { series: [1, Number.NaN], title: "Q3" } }),
+    );
+
+    const toolCall = encoded.content.find((p) => p.type === "tool-call");
+    expect(toolCall).toHaveProperty("artifact", {
+      series: [1, null],
+      title: "Q3",
+    });
+  });
+
+  it("stores a tool-call artifact as its JSON form, dropping undefined fields", () => {
+    const encoded = auiV0Encode(
+      toolCallMessage({ artifact: { chart: [1, 2], error: undefined } }),
+    );
+
+    const toolCall = encoded.content.find((p) => p.type === "tool-call");
+    expect(toolCall).toHaveProperty("artifact", { chart: [1, 2] });
+    expect(
+      (toolCall as { artifact?: Record<string, unknown> }).artifact,
+    ).not.toHaveProperty("error");
+  });
+
+  it("omits absent tool-call artifact, model content, and provider metadata", () => {
+    const encoded = auiV0Encode(toolCallMessage({}));
+
+    const toolCall = encoded.content.find((p) => p.type === "tool-call");
+    expect(toolCall).not.toHaveProperty("artifact");
+    expect(toolCall).not.toHaveProperty("modelContent");
+    expect(toolCall).not.toHaveProperty("providerMetadata");
+  });
+
+  it("stores and restores readable tool-call interactions", () => {
+    const unstable_interactions = {
+      entries: [
+        {
+          type: "action" as const,
+          occurredAt: 10,
+          payload: { $input: "approve" },
+        },
+        {
+          type: "human-response" as const,
+          occurredAt: 11,
+          payload: false,
+        },
+      ],
+    };
+    const encoded = auiV0Encode(toolCallMessage({ unstable_interactions }));
+
+    expect(encoded.content.find((p) => p.type === "tool-call")).toHaveProperty(
+      "unstable_interactions",
+      unstable_interactions,
+    );
+
+    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]);
+
+    expect(message.content.find((p) => p.type === "tool-call")).toHaveProperty(
+      "unstable_interactions",
+      unstable_interactions,
+    );
+  });
+
+  it("stores only readable tool-call interactions", () => {
+    const encoded = auiV0Encode(
+      toolCallMessage({
+        unstable_interactions: {
+          entries: [
+            { type: "human-response", occurredAt: 10, payload: "kept" },
+            { type: "unknown", occurredAt: 11, payload: "dropped" },
+          ],
+        },
+      }),
+    );
+
+    expect(encoded.content.find((p) => p.type === "tool-call")).toHaveProperty(
+      "unstable_interactions",
+      {
+        entries: [{ type: "human-response", occurredAt: 10, payload: "kept" }],
+      },
+    );
+  });
+
   it("carries a falsy tool-call result through a decode round trip", () => {
     const encoded = auiV0Encode(toolCallMessage({ result: false }));
     const { message } = auiV0Decode({
@@ -631,6 +832,114 @@ describe("auiV0Decode", () => {
     expect(toolCall).toHaveProperty("result", false);
   });
 
+  const modelContent = [
+    { type: "text" as const, text: "The report is ready." },
+    {
+      type: "file" as const,
+      data: "AAAA",
+      mediaType: "application/pdf",
+      filename: "report.pdf",
+    },
+  ];
+
+  it("keeps a tool-call modelContent distinct from its result across a decode round trip", () => {
+    const encoded = auiV0Encode(
+      toolCallMessage({ result: { blob: "x".repeat(16) }, modelContent }),
+    );
+    expect(encoded.content.find((p) => p.type === "tool-call")).toHaveProperty(
+      "modelContent",
+      modelContent,
+    );
+
+    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", { blob: "x".repeat(16) });
+    expect(toolCall).toHaveProperty("modelContent", modelContent);
+  });
+
+  it("keeps a tool-call modelContent through the safe decoder", () => {
+    const encoded = auiV0Encode(
+      toolCallMessage({ result: "ui blob", modelContent }),
+    );
+    const decoded = auiV0DecodeSafely({
+      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 auiV0DecodeSafely>[0]);
+
+    const toolCall = decoded?.message.content.find(
+      (p) => p.type === "tool-call",
+    );
+    expect(toolCall).toHaveProperty("modelContent", modelContent);
+  });
+
+  it("keeps tool-call artifact and provider metadata through the safe decoder", () => {
+    const encoded = auiV0Encode(
+      toolCallMessage({
+        artifact,
+        modelContent: artifactModelContent,
+        providerMetadata,
+      }),
+    );
+    const decoded = auiV0DecodeSafely({
+      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 auiV0DecodeSafely>[0]);
+
+    const toolCall = decoded?.message.content.find(
+      (p) => p.type === "tool-call",
+    );
+    expect(toolCall).toMatchObject({
+      artifact,
+      providerMetadata,
+    });
+  });
+
+  it("omits modelContent for a tool call that does not carry one", () => {
+    const encoded = auiV0Encode(toolCallMessage({ result: "plain" }));
+
+    expect(
+      encoded.content.find((p) => p.type === "tool-call"),
+    ).not.toHaveProperty("modelContent");
+  });
+
+  it("round-trips the preliminary marker on a tool-call result", () => {
+    const encoded = auiV0Encode(
+      toolCallMessage({ result: "interim", isPreliminary: true }),
+    );
+    const encodedToolCall = encoded.content.find((p) => p.type === "tool-call");
+    expect(encodedToolCall).toMatchObject({
+      result: "interim",
+      isPreliminary: true,
+    });
+
+    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 decodedToolCall = message.content.find((p) => p.type === "tool-call");
+    expect(decodedToolCall).toMatchObject({
+      result: "interim",
+      isPreliminary: true,
+    });
+  });
+
   it("round-trips data message parts, keeping repeated names in order", () => {
     const content = auiV0Encode({
       id: "local",
@@ -820,9 +1129,11 @@ describe("auiV0Decode", () => {
     const decoded = auiV0Decode({
       id: "cloud",
       parent_id: null,
+      height: 0,
       format: "aui/v0",
       content: content as never,
       created_at: new Date("2026-03-15T00:00:00.000Z"),
+      updated_at: new Date("2026-03-15T00:00:00.000Z"),
     });
 
     if (decoded.message.role !== "assistant")
@@ -887,6 +1198,104 @@ describe("auiV0Decode", () => {
     ]);
   });
 
+  it("round-trips image filename and provider metadata", () => {
+    const content = auiV0Encode({
+      id: "local",
+      createdAt: new Date("2026-03-15T00:00:00.000Z"),
+      role: "user",
+      metadata: { custom: {} },
+      attachments: [],
+      content: [
+        {
+          type: "image",
+          image: "data:image/png;base64,iVBORw0KGgo=",
+          filename: "screenshot.png",
+          providerMetadata: { openai: { detail: "high" } },
+        },
+      ],
+    });
+
+    expect(content.content).toEqual([
+      {
+        type: "image",
+        image: "data:image/png;base64,iVBORw0KGgo=",
+        filename: "screenshot.png",
+        providerMetadata: { openai: { detail: "high" } },
+      },
+    ]);
+
+    const decoded = auiV0Decode({
+      id: "cloud",
+      parent_id: null,
+      height: 0,
+      format: "aui/v0",
+      content: content as never,
+      created_at: new Date("2026-03-15T00:00:00.000Z"),
+      updated_at: new Date("2026-03-15T00:00:00.000Z"),
+    });
+
+    if (decoded.message.role !== "user") throw new Error("expected user");
+    expect(decoded.message.content).toEqual([
+      {
+        type: "image",
+        image: "data:image/png;base64,iVBORw0KGgo=",
+        filename: "screenshot.png",
+        providerMetadata: { openai: { detail: "high" } },
+      },
+    ]);
+  });
+
+  it("round-trips text provider metadata", () => {
+    const content = auiV0Encode({
+      id: "local",
+      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: "text",
+          text: "answer",
+          providerMetadata: { anthropic: { signature: "sig-1" } },
+        },
+      ],
+    });
+
+    expect(content.content).toEqual([
+      {
+        type: "text",
+        text: "answer",
+        providerMetadata: { anthropic: { signature: "sig-1" } },
+      },
+    ]);
+
+    const decoded = auiV0Decode({
+      id: "cloud",
+      parent_id: null,
+      height: 0,
+      format: "aui/v0",
+      content: content as never,
+      created_at: new Date("2026-03-15T00:00:00.000Z"),
+      updated_at: new Date("2026-03-15T00:00:00.000Z"),
+    });
+
+    if (decoded.message.role !== "assistant")
+      throw new Error("expected assistant");
+    expect(decoded.message.content).toEqual([
+      {
+        type: "text",
+        text: "answer",
+        providerMetadata: { anthropic: { signature: "sig-1" } },
+      },
+    ]);
+  });
+
   it("keeps audio message and attachment parts as audio", () => {
     const content = auiV0Encode({
       id: "local",
@@ -928,9 +1337,11 @@ describe("auiV0Decode", () => {
     const decoded = auiV0Decode({
       id: "cloud",
       parent_id: null,
+      height: 0,
       format: "aui/v0",
       content: content as never,
       created_at: new Date("2026-03-15T00:00:00.000Z"),
+      updated_at: new Date("2026-03-15T00:00:00.000Z"),
     });
 
     if (decoded.message.role !== "user") throw new Error("expected user");