@assistant-ui/core 0.3.12 → 0.3.14

package/src/store/scopes/threads.ts

@@ -35,6 +35,20 @@ export type ThreadsMethods = {
   __internal_getAssistantRuntime?(): AssistantRuntime;
 };
 
+export type ThreadsEvents = {
+  /**
+   * The main thread selection changed. Fires once per switch with the newly
+   * selected thread and the thread that was selected before. Does not fire
+   * for the initially selected thread on mount. Runtimes that resolve a
+   * deep-linked `threadId`/`initialThreadId` after mount (such as
+   * `useRemoteThreadListRuntime`) start on a placeholder new thread, so the
+   * deep link's resolution fires this event with the placeholder as
+   * `previousThreadId`.
+   */
+  "threads.selectionChanged": { threadId: string; previousThreadId: string };
+};
+
 export type ThreadsClientSchema = {
   methods: ThreadsMethods;
+  events: ThreadsEvents;
 };

package/src/subscribable/subscribable.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import type { SubscribableWithState } from "./subscribable";
-import { ShallowMemoizeSubject } from "./subscribable";
+import { LazyMemoizeSubject, ShallowMemoizeSubject } from "./subscribable";
 
 type TestState = {
   status: string;
@@ -26,6 +26,9 @@ const createBinding = (initialState: TestState) => {
       state = nextState;
       for (const callback of subscribers) callback();
     },
+    replace(nextState: TestState) {
+      state = nextState;
+    },
   };
 };
 
@@ -55,4 +58,77 @@ describe("ShallowMemoizeSubject", () => {
 
     expect(subscriber).not.toHaveBeenCalled();
   });
+
+  it("notifies later subscribers when one throws", () => {
+    const source = createBinding({ status: "empty" });
+    const subject = new ShallowMemoizeSubject(source.binding);
+    const error = new Error("subscriber failed");
+    const laterSubscriber = vi.fn();
+    subject.subscribe(() => {
+      throw error;
+    });
+    subject.subscribe(laterSubscriber);
+
+    expect(() => source.update({ status: "ready" })).toThrow(error);
+    expect(laterSubscriber).toHaveBeenCalledOnce();
+    expect(subject.getState()).toEqual({ status: "ready" });
+  });
+
+  it("reads a value that landed while nobody was subscribed", () => {
+    const source = createBinding({ status: "empty" });
+    const subject = new ShallowMemoizeSubject(source.binding);
+    expect(subject.getState()).toEqual({ status: "empty" });
+
+    source.update({ status: "ready" });
+    const subscriber = vi.fn();
+    subject.subscribe(subscriber);
+
+    expect(subject.getState()).toEqual({ status: "ready" });
+    expect(subscriber).not.toHaveBeenCalled();
+  });
+});
+
+describe("LazyMemoizeSubject", () => {
+  it("notifies later subscribers when one throws", () => {
+    const source = createBinding({ status: "empty" });
+    const subject = new LazyMemoizeSubject(source.binding);
+    const error = new Error("subscriber failed");
+    const laterSubscriber = vi.fn();
+    subject.subscribe(() => {
+      throw error;
+    });
+    subject.subscribe(laterSubscriber);
+
+    expect(() => source.update({ status: "ready" })).toThrow(error);
+    expect(laterSubscriber).toHaveBeenCalledOnce();
+    expect(subject.getState()).toEqual({ status: "ready" });
+  });
+
+  it("reads a value replaced before connecting", () => {
+    const source = createBinding({ status: "empty" });
+    const subject = new LazyMemoizeSubject(source.binding);
+    expect(subject.getState()).toEqual({ status: "empty" });
+
+    source.replace({ status: "ready" });
+    const subscriber = vi.fn();
+    const unsubscribe = subject.subscribe(subscriber);
+
+    expect(subject.getState()).toEqual({ status: "ready" });
+    expect(subscriber).not.toHaveBeenCalled();
+    unsubscribe();
+  });
+
+  it("resynchronizes after reconnecting", () => {
+    const source = createBinding({ status: "empty" });
+    const subject = new LazyMemoizeSubject(source.binding);
+    expect(subject.getState()).toEqual({ status: "empty" });
+
+    const unsubscribe = subject.subscribe(() => {});
+    unsubscribe();
+    source.replace({ status: "ready" });
+    const reconnect = subject.subscribe(() => {});
+
+    expect(subject.getState()).toEqual({ status: "ready" });
+    reconnect();
+  });
 });

package/src/subscribable/subscribable.ts

@@ -32,6 +32,31 @@ export type EventSubscribable<TEvent extends string> = {
   >;
 };
 
+export const notifySubscribers = <TArgs extends unknown[]>(
+  subscribers: Iterable<(...args: TArgs) => void>,
+  ...args: TArgs
+): void => {
+  const errors: unknown[] = [];
+  for (const callback of subscribers) {
+    try {
+      callback(...args);
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+
+  if (errors.length === 1) {
+    throw errors[0];
+  }
+
+  if (errors.length > 1) {
+    for (const error of errors) {
+      console.error(error);
+    }
+    throw new AggregateError(errors);
+  }
+};
+
 function shallowEqual<T extends object>(
   objA: T | undefined,
   objB: T | undefined,
@@ -70,25 +95,7 @@ export class BaseSubscribable {
   }
 
   protected _notifySubscribers() {
-    const errors = [];
-    for (const callback of this._subscribers) {
-      try {
-        callback();
-      } catch (error) {
-        errors.push(error);
-      }
-    }
-
-    if (errors.length > 0) {
-      if (errors.length === 1) {
-        throw errors[0];
-      } else {
-        for (const error of errors) {
-          console.error(error);
-        }
-        throw new AggregateError(errors);
-      }
-    }
+    notifySubscribers(this._subscribers);
   }
 }
 
@@ -109,7 +116,7 @@ export abstract class BaseSubject {
       return;
     }
 
-    for (const callback of this._subscriptions) callback(payload);
+    notifySubscribers(this._subscriptions, payload);
   }
 
   private _updateConnection() {
@@ -173,7 +180,9 @@ export class ShallowMemoizeSubject<TState extends object, TPath>
       }
     };
 
-    return this.binding.subscribe(callback);
+    const unsubscribe = this.binding.subscribe(callback);
+    this._syncState();
+    return unsubscribe;
   }
 }
 
@@ -197,7 +206,11 @@ export class LazyMemoizeSubject<TState extends object, TPath>
   public getState = () => {
     if (!this.isConnected || this._previousStateDirty) {
       const newState = this.binding.getState();
-      if (newState !== SKIP_UPDATE) {
+      if (
+        newState !== SKIP_UPDATE &&
+        (this._previousState === undefined ||
+          !shallowEqual(newState, this._previousState))
+      ) {
         this._previousState = newState;
       }
       this._previousStateDirty = false;
@@ -213,7 +226,9 @@ export class LazyMemoizeSubject<TState extends object, TPath>
       this.notifySubscribers();
     };
 
-    return this.binding.subscribe(callback);
+    const unsubscribe = this.binding.subscribe(callback);
+    this._previousStateDirty = true;
+    return unsubscribe;
   }
 }
 

package/src/tests/RemoteThreadListThreadListRuntimeCore-switchToThread-unarchive.test.ts

@@ -63,6 +63,31 @@ describe("RemoteThreadListThreadListRuntimeCore.switchToThread unarchive option"
     expect(core.mainThreadId).toBe(core.getItemById(THREAD_ID)?.id);
   });
 
+  it("restores an initialized draft's archived thread when unarchive fails", async () => {
+    const THREAD_ID = "archived-initialized-draft";
+    const error = new Error("unarchive failed");
+    const adapter = makeAdapter({
+      list: vi.fn(async () => ({ threads: [archivedThread(THREAD_ID)] })),
+      unarchive: vi.fn(async () => {
+        throw error;
+      }),
+    });
+
+    const core = createCore(adapter);
+    await core.getLoadThreadsPromise();
+    const draftId = core.newThreadId;
+    if (draftId === undefined) throw new Error("Expected seeded draft");
+    await core.initialize(draftId);
+    expect(core.newThreadId).toBeUndefined();
+    await core.switchToThread(THREAD_ID, { unarchive: false });
+
+    await expect(core.unarchive(THREAD_ID)).rejects.toBe(error);
+    expect(core.mainThreadId).not.toBe(THREAD_ID);
+    expect(core.getItemById(THREAD_ID)?.status).toBe("archived");
+    expect(core.archivedThreadIds).toContain(THREAD_ID);
+    expect(core.threadIds).not.toContain(THREAD_ID);
+  });
+
   it("does not call unarchive when the target is already regular, regardless of option", async () => {
     const THREAD_ID = "regular-target";
     const adapter = makeAdapter({

package/src/tests/append-interactable-snapshots.test.ts

@@ -0,0 +1,350 @@
+import { describe, expect, it, vi } from "vitest";
+import { ExternalStoreRuntimeCore } from "../runtimes/external-store/external-store-runtime-core";
+import { LocalRuntimeCore } from "../runtimes/local/local-runtime-core";
+import { createMessageQueue } from "../runtime/queue/message-queue";
+import { getThreadMessageText } from "../utils/text";
+import type { ChatModelAdapter } from "../runtime/utils/chat-model-adapter";
+import type { AppendMessage, ThreadMessage } from "../types/message";
+
+const live = (state: unknown) => ({
+  interactables: [{ id: "n1", name: "note", state }],
+});
+
+const snapshotMessage = (id: string, state: unknown) =>
+  ({
+    id,
+    role: "user",
+    createdAt: new Date(),
+    content: [{ type: "text", text: "old" }],
+    attachments: [],
+    metadata: {
+      custom: { interactables: [{ id: "n1", name: "note", state }] },
+    },
+  }) as ThreadMessage;
+
+const userMessage = (text: string, parentId: string | null): AppendMessage => ({
+  parentId,
+  sourceId: null,
+  runConfig: {},
+  role: "user",
+  content: [{ type: "text", text }],
+  attachments: [],
+  metadata: { custom: {} },
+  createdAt: new Date(),
+});
+
+const externalThread = (options?: {
+  messages?: ThreadMessage[];
+  composerMetadata?: Record<string, unknown>;
+}) => {
+  const onNew = vi.fn(async () => {});
+  const onEdit = vi.fn(async () => {});
+  const core = new ExternalStoreRuntimeCore({
+    messages: options?.messages ?? [],
+    onNew,
+    onEdit,
+  });
+  if (options?.composerMetadata) {
+    core.registerModelContextProvider({
+      getModelContext: () => ({
+        unstable_composerMetadata: options.composerMetadata,
+      }),
+    });
+  }
+  return { thread: core.threads.getMainThreadRuntimeCore(), onNew, onEdit };
+};
+
+const appendedSnapshots = (sink: ReturnType<typeof vi.fn>) =>
+  (sink.mock.calls[0]![0] as AppendMessage).metadata?.custom?.interactables;
+
+const tailId = (messages: ThreadMessage[]) => messages.at(-1)?.id ?? null;
+
+describe("interactable snapshots on the append seam", () => {
+  it("stamps a baseline on the first send of the thread", async () => {
+    const { thread, onNew } = externalThread({
+      composerMetadata: live({ v: 1 }),
+    });
+    await thread.append(userMessage("hello", null));
+    expect(appendedSnapshots(onNew)).toEqual([
+      { id: "n1", name: "note", state: { v: 1 } },
+    ]);
+  });
+
+  it("stamps nothing when the history already carries the live state", async () => {
+    const messages = [snapshotMessage("msg-1", { v: 1 })];
+    const { thread, onNew } = externalThread({
+      messages,
+      composerMetadata: live({ v: 1 }),
+    });
+    await thread.append(userMessage("hello", tailId(messages)));
+    expect(appendedSnapshots(onNew)).toBeUndefined();
+  });
+
+  it("stamps the new state when it diverged from the latest snapshot", async () => {
+    const messages = [snapshotMessage("msg-1", { v: 1 })];
+    const { thread, onNew } = externalThread({
+      messages,
+      composerMetadata: live({ v: 2 }),
+    });
+    await thread.append(userMessage("hello", tailId(messages)));
+    expect(appendedSnapshots(onNew)).toEqual([
+      { id: "n1", name: "note", state: { v: 2 } },
+    ]);
+  });
+
+  it("stamps a programmatic append, the path suggestions and thread.append() take", async () => {
+    const { thread, onNew } = externalThread({
+      composerMetadata: live({ tasks: [] }),
+    });
+    await thread.append(userMessage("Add 3 tasks for a grocery run", null));
+    expect(appendedSnapshots(onNew)).toEqual([
+      { id: "n1", name: "note", state: { tasks: [] } },
+    ]);
+  });
+
+  it("leaves a non-user append unstamped, since no reader folds those", async () => {
+    const { thread, onNew } = externalThread({
+      composerMetadata: live({ v: 1 }),
+    });
+    await thread.append({
+      ...userMessage("an assistant turn", null),
+      role: "assistant",
+    } as AppendMessage);
+    expect(appendedSnapshots(onNew)).toBeUndefined();
+  });
+
+  it("re-stamps the baseline when the edited message carried the only snapshot", async () => {
+    const messages = [snapshotMessage("msg-1", { v: 1 })];
+    const { thread, onEdit } = externalThread({
+      messages,
+      composerMetadata: live({ v: 1 }),
+    });
+    // An edit branches off the edited message's parent, so the prefix it is
+    // gated against excludes the edited message and its snapshot.
+    await thread.append({ ...userMessage("new", null), sourceId: "msg-1" });
+    expect(appendedSnapshots(onEdit)).toEqual([
+      { id: "n1", name: "note", state: { v: 1 } },
+    ]);
+  });
+
+  it("stamps nothing when the edit's branch prefix already carries the live state", async () => {
+    const messages = [
+      snapshotMessage("parent-1", { v: 1 }),
+      snapshotMessage("msg-1", { v: 1 }),
+    ];
+    const { thread, onEdit } = externalThread({
+      messages,
+      composerMetadata: live({ v: 1 }),
+    });
+    await thread.append({
+      ...userMessage("new", "parent-1"),
+      sourceId: "msg-1",
+    });
+    expect(appendedSnapshots(onEdit)).toBeUndefined();
+  });
+
+  it("stamps on the local runtime core too", async () => {
+    const run = vi.fn(async function* () {
+      yield { content: [{ type: "text" as const, text: "ok" }] };
+    } as unknown as ChatModelAdapter["run"]);
+    const core = new LocalRuntimeCore(
+      { adapters: { chatModel: { run } } },
+      undefined,
+    );
+    core.registerModelContextProvider({
+      getModelContext: () => ({
+        unstable_composerMetadata: live({ v: 1 }),
+      }),
+    });
+    const thread = core.threads.getMainThreadRuntimeCore();
+    await thread.append(userMessage("hello", null));
+    expect(thread.messages[0]!.metadata.custom?.interactables).toEqual([
+      { id: "n1", name: "note", state: { v: 1 } },
+    ]);
+  });
+});
+
+describe("queued sends gate at dispatch, not at enqueue", () => {
+  const queuedExternalThread = () => {
+    const run = vi.fn();
+    const onNew = vi.fn(async () => {});
+    const queue = createMessageQueue({ run });
+    let composerMetadata: Record<string, unknown> = live({ v: 1 });
+    const store = (messages: ThreadMessage[]) => ({
+      messages,
+      onNew,
+      queue: queue.adapter,
+    });
+    const core = new ExternalStoreRuntimeCore(store([]));
+    core.registerModelContextProvider({
+      getModelContext: () => ({ unstable_composerMetadata: composerMetadata }),
+    });
+    return {
+      thread: core.threads.getMainThreadRuntimeCore(),
+      queue,
+      run,
+      advanceRecord: (messages: ThreadMessage[], live: unknown) => {
+        composerMetadata = live as Record<string, unknown>;
+        core.setAdapter(store(messages));
+      },
+    };
+  };
+
+  const dispatched = (run: ReturnType<typeof vi.fn>) =>
+    (run.mock.calls[0]![0] as AppendMessage).metadata?.custom?.interactables;
+
+  it("drops the enqueue-time stamp once the run has told the model that state", async () => {
+    const t = queuedExternalThread();
+    t.queue.notifyBusy();
+    await t.thread.append(userMessage("queued", null));
+    expect(t.run).not.toHaveBeenCalled();
+
+    // the run moved the record to v:2 and the live state matches it
+    t.advanceRecord([snapshotMessage("msg-1", { v: 2 })], live({ v: 2 }));
+    t.queue.notifyIdle();
+
+    expect(t.run).toHaveBeenCalledTimes(1);
+    expect(dispatched(t.run)).toBeUndefined();
+  });
+
+  it("stamps the state as of the flush when it still diverges", async () => {
+    const t = queuedExternalThread();
+    t.queue.notifyBusy();
+    await t.thread.append(userMessage("queued", null));
+
+    // the run moved the record to v:2 while the user edited on to v:3
+    t.advanceRecord([snapshotMessage("msg-1", { v: 2 })], live({ v: 3 }));
+    t.queue.notifyIdle();
+
+    expect(dispatched(t.run)).toEqual([
+      { id: "n1", name: "note", state: { v: 3 } },
+    ]);
+  });
+
+  // interrupt dispatches synchronously inside `append`, so nothing can go
+  // stale in between; what matters is that this second dispatch point stamps
+  // at all, the way advance does.
+  it("stamps on the interrupt path a mid-run steer takes", async () => {
+    const run = vi.fn();
+    const cancel = vi.fn();
+    const onNew = vi.fn(async () => {});
+    const queue = createMessageQueue({ run, cancel });
+    let composerMetadata: Record<string, unknown> = live({ v: 1 });
+    const store = (messages: ThreadMessage[]) => ({
+      messages,
+      onNew,
+      queue: queue.adapter,
+      isRunning: true,
+    });
+    const core = new ExternalStoreRuntimeCore(store([]));
+    core.registerModelContextProvider({
+      getModelContext: () => ({ unstable_composerMetadata: composerMetadata }),
+    });
+    const thread = core.threads.getMainThreadRuntimeCore();
+
+    queue.notifyBusy();
+    composerMetadata = live({ v: 2 });
+    // isRunning routes this to the steer lane, and a cancel-capable driver
+    // makes that an interrupt rather than a buffered enqueue
+    await thread.append(
+      userMessage("steered", thread.messages.at(-1)?.id ?? null),
+    );
+
+    expect(cancel).toHaveBeenCalled();
+    expect(dispatched(run)).toEqual([
+      { id: "n1", name: "note", state: { v: 2 } },
+    ]);
+  });
+
+  it("re-points a flushed message at the tail it was gated against", async () => {
+    const t = queuedExternalThread();
+    t.queue.notifyBusy();
+    await t.thread.append(userMessage("queued", null));
+
+    t.advanceRecord([snapshotMessage("msg-1", { v: 2 })], live({ v: 3 }));
+    t.queue.notifyIdle();
+
+    // routing and gating have to name the same point, or the branch the
+    // message lands on is not the one its snapshot was computed against
+    expect((t.run.mock.calls[0]![0] as AppendMessage).parentId).toBe("msg-1");
+  });
+
+  it("leaves a hand-rolled adapter stamping at enqueue", async () => {
+    const enqueue = vi.fn();
+    const onNew = vi.fn(async () => {});
+    const core = new ExternalStoreRuntimeCore({
+      messages: [],
+      onNew,
+      // no __internal_setDispatchTransform: nothing re-gates on the way out,
+      // so the runtime has to stamp before handing the message over
+      queue: {
+        items: [],
+        steerItems: [],
+        enqueue,
+        steer: vi.fn(),
+        move: vi.fn(),
+        edit: vi.fn(),
+        remove: vi.fn(),
+      },
+    });
+    core.registerModelContextProvider({
+      getModelContext: () => ({ unstable_composerMetadata: live({ v: 1 }) }),
+    });
+    const thread = core.threads.getMainThreadRuntimeCore();
+
+    await thread.append(userMessage("queued", null));
+    expect(dispatched(enqueue)).toEqual([
+      { id: "n1", name: "note", state: { v: 1 } },
+    ]);
+  });
+
+  it("gates a queued local send against the tail it flushes onto", async () => {
+    let composerMetadata: Record<string, unknown> = live({ v: 1 });
+    let releaseFirstRun!: () => void;
+    const firstRunGate = new Promise<void>((resolve) => {
+      releaseFirstRun = resolve;
+    });
+    let runs = 0;
+    const chatModel: ChatModelAdapter = {
+      run: async function* () {
+        if (runs++ === 0) await firstRunGate;
+        yield { content: [{ type: "text" as const, text: "ok" }] };
+      },
+    };
+    const core = new LocalRuntimeCore(
+      { adapters: { chatModel }, unstable_enableMessageQueue: true },
+      undefined,
+    );
+    core.registerModelContextProvider({
+      getModelContext: () => ({ unstable_composerMetadata: composerMetadata }),
+    });
+    const thread = core.threads.getMainThreadRuntimeCore();
+    const settle = () => new Promise((resolve) => setTimeout(resolve, 20));
+
+    void thread.append(userMessage("first", null));
+    await settle();
+
+    // the first run is still open, so this one buffers with the live state at v:1
+    void thread.append(
+      userMessage("second", thread.messages.at(-1)?.id ?? null),
+    );
+    await settle();
+    expect(
+      thread.messages.some(
+        (m) => m.role === "user" && getThreadMessageText(m) === "second",
+      ),
+    ).toBe(false);
+
+    composerMetadata = live({ v: 2 });
+    releaseFirstRun();
+    await settle();
+    await settle();
+
+    const second = thread.messages.find(
+      (m) => m.role === "user" && getThreadMessageText(m) === "second",
+    );
+    expect(second!.metadata.custom?.interactables).toEqual([
+      { id: "n1", name: "note", state: { v: 2 } },
+    ]);
+  });
+});

package/src/tests/auiV0Encode.test.ts

@@ -330,6 +330,33 @@ describe("auiV0Encode", () => {
       { type: "data", name: "telemetry", data: { runs: 3 } },
     ]);
   });
+
+  it("preserves data message parts verbatim in the core cloud encoder", () => {
+    const encoded = auiV0Encode({
+      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: "text", text: "planned" },
+        { type: "data", name: "PredictState", data: { steps: ["a"] } },
+        { type: "data", name: "PredictState", data: '{"steps":["a","b"]}' },
+      ],
+    });
+
+    expect(encoded.content).toEqual([
+      { type: "text", text: "planned" },
+      { type: "data", name: "PredictState", data: { steps: ["a"] } },
+      { type: "data", name: "PredictState", data: '{"steps":["a","b"]}' },
+    ]);
+  });
 });
 
 describe("auiV0Decode", () => {
@@ -573,4 +600,43 @@ describe("auiV0Decode", () => {
     const toolCall = message.content.find((p) => p.type === "tool-call");
     expect(toolCall).toHaveProperty("result", false);
   });
+
+  it("round-trips data message parts, keeping repeated names in order", () => {
+    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: "planned" },
+        { type: "data", name: "PredictState", data: { steps: ["a"] } },
+        { type: "data", name: "PredictState", data: '{"steps":["a","b"]}' },
+      ],
+    });
+
+    const decoded = auiV0Decode({
+      id: "cloud",
+      parent_id: null,
+      height: 0,
+      created_at: new Date("2026-03-15T00:00:00.000Z"),
+      updated_at: new Date("2026-03-15T00:00:00.000Z"),
+      format: "aui/v0",
+      content: content as never,
+    });
+
+    if (decoded.message.role !== "assistant")
+      throw new Error("expected assistant");
+    expect(decoded.message.content).toEqual([
+      { type: "text", text: "planned" },
+      { type: "data", name: "PredictState", data: { steps: ["a"] } },
+      { type: "data", name: "PredictState", data: '{"steps":["a","b"]}' },
+    ]);
+  });
 });