@assistant-ui/core 0.3.18 → 0.3.20

package/src/tests/external-thread-parity.test.tsx

@@ -203,6 +203,40 @@ describe("ExternalThread part status", () => {
   });
 });
 
+describe("ExternalThread tasks", () => {
+  it("derives nested conversations and resolves their task scope", () => {
+    const { aui } = renderThread({
+      messages: [
+        assistantMessageWithContent({ type: "running" }, [
+          {
+            type: "tool-call",
+            toolCallId: "delegate-1",
+            toolName: "delegate",
+            args: {},
+            argsText: "{}",
+            messages: [
+              assistantMessageWithContent(
+                { type: "running" },
+                [],
+                "nested-message-1",
+              ),
+            ],
+          },
+        ]),
+      ],
+      isRunning: true,
+    });
+
+    const [task] = aui().thread.getState().tasks;
+    expect(task).toMatchObject({
+      id: "delegate-1",
+      toolName: "delegate",
+      messageId: "a1",
+    });
+    expect(aui().thread.task({ id: "delegate-1" }).getState()).toBe(task);
+  });
+});
+
 describe("ExternalThread unset optional callbacks", () => {
   it("throws a capability error when the callback prop is not set", () => {
     const { aui } = renderThread({
@@ -220,7 +254,7 @@ describe("ExternalThread unset optional callbacks", () => {
     expect(() => part().resumeToolCall(undefined)).toThrow(
       "Runtime does not support resuming tool calls (onResumeToolCall is not set).",
     );
-    expect(() => aui().thread.resumeRun()).toThrow(
+    expect(() => aui().thread.resumeRun({ parentId: null })).toThrow(
       "Runtime does not support resuming runs (onResume is not set).",
     );
     expect(() => aui().thread.importExternalState({})).toThrow(

package/src/tests/groupParts.test.ts

@@ -114,6 +114,53 @@ describe("groupPartByType", () => {
     ]);
   });
 
+  it("routes a tool call by name through its tool-call:<name> entry", () => {
+    const fn = groupPartByType({
+      "tool-call:task": ["group-subagents"],
+      "tool-call": ["group-tool"],
+    });
+
+    expect(
+      fn(
+        part({
+          type: "tool-call",
+          toolName: "task",
+        } as Partial<PartState>),
+      ),
+    ).toEqual(["group-subagents"]);
+  });
+
+  it("falls back to the plain tool-call entry for other tool names", () => {
+    const fn = groupPartByType({
+      "tool-call:task": ["group-subagents"],
+      "tool-call": ["group-tool"],
+    });
+
+    expect(
+      fn(
+        part({
+          type: "tool-call",
+          toolName: "search",
+        } as Partial<PartState>),
+      ),
+    ).toEqual(["group-tool"]);
+  });
+
+  it("routes standalone tool calls before matching a tool name entry", () => {
+    const fn = groupPartByType({
+      "standalone-tool-call": ["group-standalone"],
+      "tool-call:task": ["group-subagents"],
+      "tool-call": ["group-tool"],
+    });
+    const standaloneTask = part({
+      type: "tool-call",
+      toolName: "task",
+      mcp: { app: { resourceUri: "ui://task" } },
+    } as Partial<PartState>);
+
+    expect(fn(standaloneTask)).toEqual(["group-standalone"]);
+  });
+
   it("returns [] for part types not in the map", () => {
     const fn = groupPartByType({ reasoning: ["group-r"] });
     expect(fn(part({ type: "text" }))).toEqual([]);
@@ -254,6 +301,30 @@ describe("groupPartByType", () => {
     ];
     expect(keyA).not.toBe(keyB);
   });
+
+  it("includes tool-call name entries in an order-insensitive fingerprint", () => {
+    const withoutName = groupPartByType({ "tool-call": ["group-tool"] });
+    const a = groupPartByType({
+      "tool-call:task": ["group-subagents"],
+      "tool-call": ["group-tool"],
+    });
+    const b = groupPartByType({
+      "tool-call": ["group-tool"],
+      "tool-call:task": ["group-subagents"],
+    });
+    const withoutNameKey = (
+      withoutName as unknown as { [GROUPBY_MEMO_KEY]: string }
+    )[GROUPBY_MEMO_KEY];
+    const keyA = (a as unknown as { [GROUPBY_MEMO_KEY]: string })[
+      GROUPBY_MEMO_KEY
+    ];
+    const keyB = (b as unknown as { [GROUPBY_MEMO_KEY]: string })[
+      GROUPBY_MEMO_KEY
+    ];
+
+    expect(keyA).not.toBe(withoutNameKey);
+    expect(keyA).toBe(keyB);
+  });
 });
 
 describe("buildGroupTree idKey", () => {

package/src/tests/message-queue.test.ts

@@ -1,5 +1,8 @@
 import { describe, it, expect, vi } from "vitest";
-import { createMessageQueue } from "../runtime/queue/message-queue";
+import {
+  createMessageQueue,
+  type MessageQueueDriver,
+} from "../runtime/queue/message-queue";
 import type { AppendMessage } from "../types/message";
 
 const msg = (text: string, extra?: Partial<AppendMessage>): AppendMessage => ({
@@ -35,6 +38,32 @@ describe("createMessageQueue", () => {
     expect(adapter.items).toHaveLength(0);
   });
 
+  it("does not advance a held queue when a run settles", () => {
+    const run = vi.fn();
+    const { adapter, hold, notifyIdle } = createMessageQueue({ run });
+
+    adapter.enqueue(msg("first"));
+    adapter.enqueue(msg("second"));
+    hold();
+    notifyIdle();
+
+    expect(run).toHaveBeenCalledOnce();
+    expect(prompts(adapter.items)).toEqual(["second"]);
+  });
+
+  it("advances a held queue once when released", () => {
+    const run = vi.fn();
+    const { adapter, hold, release } = createMessageQueue({ run });
+
+    hold();
+    adapter.enqueue(msg("first"));
+    release();
+    release();
+
+    expect(run).toHaveBeenCalledOnce();
+    expect(adapter.items).toHaveLength(0);
+  });
+
   it("drains FIFO across multiple queued messages", () => {
     const order: string[] = [];
     const run = vi.fn((m: AppendMessage) =>
@@ -435,6 +464,265 @@ describe("createMessageQueue", () => {
     });
   });
 
+  describe("synchronous dispatch failures", () => {
+    it("restores a message when the driver throws", () => {
+      const error = new Error("dispatch failed");
+      const run = vi.fn<MessageQueueDriver["run"]>(() => {
+        throw error;
+      });
+      const { adapter } = createMessageQueue({ run });
+
+      expect(() => adapter.enqueue(msg("first"))).toThrow(error);
+      expect(prompts(adapter.items)).toEqual(["first"]);
+
+      run.mockImplementation(() => {});
+      adapter.enqueue(msg("second"));
+
+      expect(run).toHaveBeenCalledTimes(2);
+      expect(run).toHaveBeenLastCalledWith(
+        expect.objectContaining({ content: [{ type: "text", text: "first" }] }),
+        { steer: false },
+      );
+      expect(prompts(adapter.items)).toEqual(["second"]);
+    });
+
+    it("does not restore work after the driver starts its run", () => {
+      const error = new Error("dispatch failed");
+      let fail = true;
+      let controller!: ReturnType<typeof createMessageQueue>;
+      const run = vi.fn(() => {
+        if (!fail) return;
+        controller.notifyBusy();
+        throw error;
+      });
+      controller = createMessageQueue({ run });
+
+      expect(() => controller.adapter.enqueue(msg("first"))).toThrow(error);
+      expect(prompts(controller.adapter.items)).toEqual([]);
+
+      fail = false;
+      controller.adapter.enqueue(msg("second"));
+      expect(run).toHaveBeenCalledOnce();
+
+      controller.notifyIdle();
+      expect(run).toHaveBeenCalledTimes(2);
+      expect(run).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          content: [{ type: "text", text: "second" }],
+        }),
+        { steer: false },
+      );
+      expect(prompts(controller.adapter.items)).toEqual([]);
+    });
+
+    it("restores a message when its dispatch transform throws", () => {
+      const error = new Error("transform failed");
+      const run = vi.fn();
+      const { adapter } = createMessageQueue({ run });
+      const setDispatchTransform = adapter.__internal_setDispatchTransform;
+      if (setDispatchTransform === undefined)
+        throw new Error("expected dispatch transform support");
+      setDispatchTransform(() => {
+        throw error;
+      });
+
+      expect(() => adapter.enqueue(msg("first"))).toThrow(error);
+      expect(run).not.toHaveBeenCalled();
+      expect(prompts(adapter.items)).toEqual(["first"]);
+
+      setDispatchTransform((message) => message);
+      adapter.enqueue(msg("second"));
+
+      expect(run).toHaveBeenCalledWith(
+        expect.objectContaining({ content: [{ type: "text", text: "first" }] }),
+        { steer: false },
+      );
+      expect(prompts(adapter.items)).toEqual(["second"]);
+    });
+
+    it("restores a steer when cancellation throws", () => {
+      const error = new Error("cancel failed");
+      const run = vi.fn();
+      const cancel = vi.fn<NonNullable<MessageQueueDriver["cancel"]>>(() => {
+        throw error;
+      });
+      const { adapter, notifyIdle } = createMessageQueue({ run, cancel });
+
+      adapter.enqueue(msg("active"));
+      expect(() => adapter.steer(msg("urgent"))).toThrow(error);
+      expect(prompts(adapter.steerItems)).toEqual(["urgent"]);
+
+      notifyIdle();
+      expect(run).toHaveBeenCalledOnce();
+
+      cancel.mockImplementation(() => {});
+      adapter.enqueue(msg("later"));
+      expect(run).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          content: [{ type: "text", text: "urgent" }],
+        }),
+        { steer: false },
+      );
+      expect(prompts(adapter.items)).toEqual(["later"]);
+    });
+
+    it("restores a steer when its dispatch transform throws", () => {
+      const error = new Error("transform failed");
+      const run = vi.fn();
+      const cancel = vi.fn();
+      const { adapter, notifyIdle } = createMessageQueue({ run, cancel });
+
+      adapter.enqueue(msg("active"));
+      const setDispatchTransform = adapter.__internal_setDispatchTransform;
+      if (setDispatchTransform === undefined)
+        throw new Error("expected dispatch transform support");
+      setDispatchTransform(() => {
+        throw error;
+      });
+
+      expect(() => adapter.steer(msg("urgent"))).toThrow(error);
+      expect(cancel).toHaveBeenCalledOnce();
+      expect(prompts(adapter.steerItems)).toEqual(["urgent"]);
+
+      notifyIdle();
+      setDispatchTransform((message) => message);
+      adapter.enqueue(msg("later"));
+
+      expect(run).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          content: [{ type: "text", text: "urgent" }],
+        }),
+        { steer: false },
+      );
+      expect(prompts(adapter.items)).toEqual(["later"]);
+    });
+
+    it("restores a steer when its replacement run throws", () => {
+      const error = new Error("steer failed");
+      let failSteer = true;
+      const run = vi.fn(
+        (_message: AppendMessage, options: { steer: boolean }) => {
+          if (options.steer && failSteer) throw error;
+        },
+      );
+      const { adapter, notifyIdle } = createMessageQueue({
+        run,
+        cancel: vi.fn(),
+      });
+
+      adapter.enqueue(msg("active"));
+      expect(() => adapter.steer(msg("urgent"))).toThrow(error);
+      expect(prompts(adapter.steerItems)).toEqual(["urgent"]);
+
+      failSteer = false;
+      notifyIdle();
+      expect(run).toHaveBeenCalledTimes(2);
+
+      adapter.enqueue(msg("later"));
+      expect(run).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          content: [{ type: "text", text: "urgent" }],
+        }),
+        { steer: false },
+      );
+      expect(prompts(adapter.items)).toEqual(["later"]);
+    });
+
+    it("recovers when cancellation settles before the replacement throws", () => {
+      const error = new Error("steer failed");
+      let failSteer = true;
+      let controller!: ReturnType<typeof createMessageQueue>;
+      controller = createMessageQueue({
+        run: (_message, options) => {
+          if (options.steer && failSteer) throw error;
+        },
+        cancel: () => controller.notifyIdle(),
+      });
+
+      controller.adapter.enqueue(msg("active"));
+      expect(() => controller.adapter.steer(msg("urgent"))).toThrow(error);
+      expect(prompts(controller.adapter.steerItems)).toEqual(["urgent"]);
+
+      failSteer = false;
+      controller.adapter.enqueue(msg("later"));
+
+      expect(prompts(controller.adapter.steerItems)).toEqual([]);
+      expect(prompts(controller.adapter.items)).toEqual(["later"]);
+    });
+
+    it("does not restore a steer after its replacement run starts", () => {
+      const error = new Error("steer failed");
+      let failSteer = true;
+      let controller!: ReturnType<typeof createMessageQueue>;
+      const run = vi.fn(
+        (_message: AppendMessage, options: { steer: boolean }) => {
+          if (!options.steer || !failSteer) return;
+          controller.notifyBusy();
+          throw error;
+        },
+      );
+      controller = createMessageQueue({
+        run,
+        cancel: () => controller.notifyIdle(),
+      });
+
+      controller.adapter.enqueue(msg("active"));
+      expect(() => controller.adapter.steer(msg("urgent"))).toThrow(error);
+      expect(prompts(controller.adapter.steerItems)).toEqual([]);
+
+      failSteer = false;
+      controller.adapter.enqueue(msg("later"));
+      expect(run).toHaveBeenCalledTimes(2);
+
+      controller.notifyIdle();
+      expect(run).toHaveBeenCalledTimes(3);
+      expect(run).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          content: [{ type: "text", text: "later" }],
+        }),
+        { steer: false },
+      );
+      expect(prompts(controller.adapter.items)).toEqual([]);
+    });
+
+    it("restores an unanchored move when its replacement run throws", () => {
+      const error = new Error("steer failed");
+      let failSteer = true;
+      const run = vi.fn(
+        (_message: AppendMessage, options: { steer: boolean }) => {
+          if (options.steer && failSteer) throw error;
+        },
+      );
+      const { adapter, notifyIdle } = createMessageQueue({
+        run,
+        cancel: vi.fn(),
+      });
+
+      adapter.enqueue(msg("active"));
+      adapter.enqueue(msg("first"));
+      adapter.enqueue(msg("second"));
+      adapter.enqueue(msg("moved"));
+      const movedId = adapter.items[2]!.id;
+
+      expect(() => adapter.move(movedId, { lane: "steer" })).toThrow(error);
+      expect(adapter.steerItems).toHaveLength(0);
+      expect(prompts(adapter.items)).toEqual(["first", "second", "moved"]);
+      expect(adapter.items[2]?.id).toBe(movedId);
+
+      failSteer = false;
+      notifyIdle();
+      adapter.enqueue(msg("later"));
+
+      expect(run).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          content: [{ type: "text", text: "first" }],
+        }),
+        { steer: false },
+      );
+      expect(prompts(adapter.items)).toEqual(["second", "moved", "later"]);
+    });
+  });
+
   it("notifyCancelled keeps items and pauses advance until the next send", () => {
     const run = vi.fn();
     const { adapter, notifyIdle, notifyCancelled } = createMessageQueue({
@@ -627,7 +915,7 @@ describe("createMessageQueue", () => {
     subscribe(laterSubscriber);
 
     try {
-      expect(() => adapter.enqueue(msg("a"), { steer: false })).not.toThrow();
+      expect(() => adapter.enqueue(msg("a"))).not.toThrow();
       expect(run).toHaveBeenCalledTimes(1);
       expect(adapter.items).toHaveLength(0);
       expect(laterSubscriber).toHaveBeenCalledTimes(2);

package/src/tests/remote-thread-list-reactive-threadId.test.ts

@@ -88,4 +88,55 @@ describe("onThreadIdChange", () => {
       expect(emitted).not.toBe(localId);
     }
   });
+
+  it("does not reject a completed switch when the callback throws", async () => {
+    const callbackError = new Error("host callback failed");
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const cb = vi.fn(() => {
+        throw callbackError;
+      });
+      const { core } = createCoreWithCallback(cb);
+      await flush();
+
+      await expect(core.switchToThread("existing-1")).resolves.toBeUndefined();
+
+      expect(core.mainThreadId).toBe("existing-1");
+      expect(cb).toHaveBeenCalledExactlyOnceWith("existing-1");
+      expect(errorSpy).toHaveBeenCalledWith(
+        "[assistant-ui] onThreadIdChange callback threw an error",
+        callbackError,
+      );
+
+      await expect(core.switchToThread("existing-2")).resolves.toBeUndefined();
+      expect(core.mainThreadId).toBe("existing-2");
+      expect(cb).toHaveBeenLastCalledWith("existing-2");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("contains a rejected callback promise", async () => {
+    const callbackError = new Error("async host callback failed");
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const cb = vi.fn(async () => {
+        throw callbackError;
+      });
+      const { core } = createCoreWithCallback(cb);
+      await flush();
+
+      await expect(core.switchToThread("existing-1")).resolves.toBeUndefined();
+      await vi.waitFor(() => {
+        expect(errorSpy).toHaveBeenCalledWith(
+          "[assistant-ui] onThreadIdChange callback threw an error",
+          callbackError,
+        );
+      });
+
+      expect(core.mainThreadId).toBe("existing-1");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
 });

package/src/tests/thread-switch-events.test.tsx

@@ -15,13 +15,14 @@ import {
 } from "../runtime/api/assistant-runtime";
 import { ExternalStoreRuntimeCore } from "../runtimes/external-store/external-store-runtime-core";
 import type { ExternalStoreAdapter } from "../runtimes/external-store/external-store-adapter";
+import type { ThreadMessage } from "../types/message";
 
 type DemoMessage = { id: string; role: "user" | "assistant"; text: string };
 
 const EMPTY_MESSAGES: readonly never[] = [];
 
 const useTestThreadRuntime = () =>
-  useExternalStoreRuntime({
+  useExternalStoreRuntime<ThreadMessage>({
     messages: EMPTY_MESSAGES,
     isRunning: false,
     onNew: async () => {},
@@ -129,7 +130,10 @@ describe("thread switch events", () => {
 
   it("delivers threads.selectionChanged with the new and previous thread ids", async () => {
     const runtime = createRuntime();
-    const selectionChanged = vi.fn();
+    const selectionChanged =
+      vi.fn<
+        (payload: { threadId: string; previousThreadId: string }) => void
+      >();
     const auiOn = vi.fn();
     let aui!: ReturnType<typeof useAui>;
     const Consumer = () => {
@@ -208,7 +212,10 @@ describe("thread switch events", () => {
 
   it("emits when a deep-linked initial thread resolves after mount", async () => {
     const adapter = makeAdapter();
-    const selectionChanged = vi.fn();
+    const selectionChanged =
+      vi.fn<
+        (payload: { threadId: string; previousThreadId: string }) => void
+      >();
     const Listener = () => {
       useAuiEvent("threads.selectionChanged", selectionChanged);
       return null;
@@ -228,10 +235,7 @@ describe("thread switch events", () => {
     render(<Harness />);
 
     await waitFor(() => expect(selectionChanged).toHaveBeenCalledTimes(1));
-    const payload = selectionChanged.mock.calls[0]![0] as {
-      threadId: string;
-      previousThreadId: string;
-    };
+    const payload = selectionChanged.mock.calls[0]![0];
     expect(payload.threadId).toBe("thread-a");
     expect(payload.previousThreadId).toMatch(/^__LOCALID_/);
   });

package/src/tests/useRemoteThreadListRuntime-controlled.test.tsx

@@ -7,6 +7,7 @@ import { AssistantRuntimeProvider } from "../react/AssistantRuntimeProvider";
 import { useExternalStoreRuntime } from "../react/runtimes/useExternalStoreRuntime";
 import { useRemoteThreadListRuntime } from "../react/runtimes/useRemoteThreadListRuntime";
 import type { AssistantRuntime } from "../runtime/api/assistant-runtime";
+import type { ThreadMessage } from "../types/message";
 import type {
   RemoteThreadListAdapter,
   RemoteThreadMetadata,
@@ -23,7 +24,7 @@ const makeThreadMetadata = (remoteId: string): RemoteThreadMetadata => ({
 });
 
 const useTestThreadRuntime = () =>
-  useExternalStoreRuntime({
+  useExternalStoreRuntime<ThreadMessage>({
     messages: EMPTY_MESSAGES,
     isRunning: false,
     onNew: async () => {},
@@ -269,6 +270,49 @@ describe("useRemoteThreadListRuntime controlled threadId", () => {
     expect(onThreadIdChange).toHaveBeenLastCalledWith(undefined);
   });
 
+  it("contains rejected callback promises on runtime-initiated switches", async () => {
+    const callbackError = new Error("async host callback failed");
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const adapter = makeAdapter();
+    const onThreadIdChange = vi.fn(async () => {
+      throw callbackError;
+    });
+    const runtimeRef: RuntimeRef = { current: null };
+
+    const { unmount } = render(
+      <ControlledRuntime
+        adapter={adapter}
+        threadId="thread-a"
+        onThreadIdChange={onThreadIdChange}
+        runtimeRef={runtimeRef}
+      />,
+    );
+
+    try {
+      await waitForRemoteThread(runtimeRef, "thread-a");
+
+      await act(async () => {
+        await expect(
+          runtimeRef.current!.threads.switchToThread("thread-b"),
+        ).resolves.toBeUndefined();
+      });
+
+      await waitFor(() => {
+        expect(errorSpy).toHaveBeenCalledWith(
+          "[assistant-ui] onThreadIdChange callback threw an error",
+          callbackError,
+        );
+      });
+      expect(onThreadIdChange).toHaveBeenCalledExactlyOnceWith("thread-b");
+      expect(runtimeRef.current!.threads.mainItem.getState().remoteId).toBe(
+        "thread-b",
+      );
+    } finally {
+      unmount();
+      errorSpy.mockRestore();
+    }
+  });
+
   it("does not retain suppression after an initial switch fails", async () => {
     let threadAFetchCount = 0;
     const adapter = makeAdapter({

package/src/types/index.ts

@@ -23,6 +23,7 @@ export type {
   MessageStatus,
   // Thread messages
   MessageTiming,
+  MessageModality,
   ThreadStep,
   ThreadSystemMessage,
   ThreadUserMessage,

package/src/types/message.test.ts

@@ -0,0 +1,19 @@
+import { expectTypeOf, it } from "vitest";
+import type { ThreadMessageLike } from "../runtime/utils/thread-message-like";
+import type {
+  AppendMessage,
+  ThreadAssistantMessage,
+  ThreadMessage,
+  ThreadSystemMessage,
+  ThreadUserMessage,
+} from "./message";
+
+it("keeps every role variant assignable to ThreadMessage", () => {
+  expectTypeOf<ThreadUserMessage>().toExtend<ThreadMessage>();
+  expectTypeOf<ThreadSystemMessage>().toExtend<ThreadMessage>();
+  expectTypeOf<ThreadAssistantMessage>().toExtend<ThreadMessage>();
+});
+
+it("keeps AppendMessage assignable to ThreadMessageLike", () => {
+  expectTypeOf<AppendMessage>().toExtend<ThreadMessageLike>();
+});