@assistant-ui/core 0.3.18 → 0.3.20

package/src/runtime/queue/message-queue.ts

@@ -13,6 +13,11 @@ import type {
 } from "./external-thread-queue-adapter";
 
 export type MessageQueueDriver = {
+  /**
+   * A synchronous throw is treated as a run that never started and restores
+   * the message. A driver that already started work must call `notifyBusy`
+   * before throwing.
+   */
   run: (message: AppendMessage, options: { steer: boolean }) => void;
   /** When omitted, steering degrades to "process next" instead of interrupting. */
   cancel?: (() => void) | undefined;
@@ -20,6 +25,8 @@ export type MessageQueueDriver = {
 
 export type MessageQueueController = {
   readonly adapter: ExternalThreadQueueAdapter;
+  hold: () => void;
+  release: () => void;
   /** Mark a run as in flight so concurrent sends buffer; call on the rising edge. */
   notifyBusy: () => void;
   /** Advances to the next pending message; call on the run's falling edge. */
@@ -38,6 +45,12 @@ export type MessageQueueController = {
 
 type Lane = "queue" | "steer";
 
+type DispatchItem = {
+  id: string;
+  item: QueueItemState;
+  message: AppendMessage;
+};
+
 const getQueueItemParts = (
   message: AppendMessage,
 ): readonly (FileMessagePart | TextMessagePart)[] => {
@@ -77,12 +90,14 @@ export const createMessageQueue = (
 
   let running = false;
   let paused = false;
+  let held = false;
   let dispatchTransform: (message: AppendMessage) => AppendMessage = (m) => m;
   // swallow the cancelled run's settle when steering so it does not double-advance
   let suppressIdle = 0;
   // settles from cancelled runs that must drop `running` without advancing
   let cancelSettles = 0;
   let interrupting = false;
+  let busyEdges = 0;
 
   const notify = () => {
     notifyEventListeners(subscribers, undefined, "Message queue");
@@ -101,6 +116,19 @@ export const createMessageQueue = (
     parts: getQueueItemParts(message),
   });
 
+  const restore = (lane: Lane, dispatch: DispatchItem, index = 0) => {
+    paused = true;
+    messages.set(dispatch.id, dispatch.message);
+    setLanes({
+      ...lanes,
+      [lane]: [
+        ...lanes[lane].slice(0, index),
+        dispatch.item,
+        ...lanes[lane].slice(index),
+      ],
+    });
+  };
+
   const laneOf = (queueItemId: string): Lane | undefined => {
     if (lanes.steer.some((item) => item.id === queueItemId)) return "steer";
     if (lanes.queue.some((item) => item.id === queueItemId)) return "queue";
@@ -108,7 +136,7 @@ export const createMessageQueue = (
   };
 
   const advance = () => {
-    if (running || paused) return;
+    if (running || paused || held) return;
     const lane: Lane = lanes.steer.length > 0 ? "steer" : "queue";
     const head = lanes[lane][0];
     if (!head) return;
@@ -116,27 +144,61 @@ export const createMessageQueue = (
     messages.delete(head.id);
     setLanes({ ...lanes, [lane]: lanes[lane].slice(1) });
     if (!message) return;
+    const dispatch = { id: head.id, item: head, message };
     running = true;
-    driver.run(dispatchTransform(message), { steer: false });
+    const busyEdgesBeforeRun = busyEdges;
+    try {
+      driver.run(dispatchTransform(message), { steer: false });
+    } catch (error) {
+      if (busyEdges === busyEdgesBeforeRun) {
+        running = false;
+        restore(lane, dispatch);
+      }
+      throw error;
+    }
   };
 
-  const interrupt = (message: AppendMessage) => {
+  const interrupt = (
+    dispatch: DispatchItem,
+    restoreLane: Lane = "steer",
+    restoreIndex = 0,
+  ) => {
     paused = false;
     // the interrupted run settles exactly once, whether or not it was
     // already cancel-notified
     suppressIdle += Math.max(cancelSettles, 1);
     cancelSettles = 0;
+    const restoreInterrupted = (replacementStarted = false) => {
+      if (replacementStarted) return;
+      // The live count distinguishes an outstanding cancellation settle
+      // from one delivered synchronously by cancel().
+      const pendingSettles = suppressIdle;
+      suppressIdle = Math.max(pendingSettles - 1, 0);
+      cancelSettles = pendingSettles > 0 ? 1 : 0;
+      running = pendingSettles > 0;
+      restore(restoreLane, dispatch, restoreIndex);
+    };
     // a driver whose cancel routes through the runtime notifies this queue
     // back; the interrupt already accounted for that settle and is dispatching
     // in its place
     interrupting = true;
     try {
       driver.cancel!();
+    } catch (error) {
+      restoreInterrupted();
+      throw error;
     } finally {
       interrupting = false;
     }
     running = true;
-    driver.run(dispatchTransform(message), { steer: true });
+    const busyEdgesBeforeRun = busyEdges;
+    try {
+      driver.run(dispatchTransform(dispatch.message), { steer: true });
+    } catch (error) {
+      const replacementStarted = busyEdges !== busyEdgesBeforeRun;
+      restoreInterrupted(replacementStarted);
+      throw error;
+    }
   };
 
   const push = (lane: Lane, message: AppendMessage) => {
@@ -153,7 +215,8 @@ export const createMessageQueue = (
 
   const steer = (message: AppendMessage) => {
     if (running && driver.cancel) {
-      interrupt(message);
+      const id = generateId();
+      interrupt({ id, item: toItem(id, message), message });
       return;
     }
     push("steer", message);
@@ -164,7 +227,8 @@ export const createMessageQueue = (
     if (!fromLane) throw new Error(`Unknown queue item "${queueItemId}".`);
     const toLane = placement.lane ?? fromLane;
 
-    const item = lanes[fromLane].find((i) => i.id === queueItemId)!;
+    const fromIndex = lanes[fromLane].findIndex((i) => i.id === queueItemId);
+    const item = lanes[fromLane][fromIndex]!;
     const dest = (toLane === fromLane ? lanes[fromLane] : lanes[toLane]).filter(
       (i) => i.id !== queueItemId,
     );
@@ -217,7 +281,7 @@ export const createMessageQueue = (
         queue: lanes.queue.filter((i) => i.id !== queueItemId),
         steer: lanes.steer,
       });
-      interrupt(message);
+      interrupt({ id: queueItemId, item, message }, fromLane, fromIndex);
       return;
     }
 
@@ -273,6 +337,13 @@ export const createMessageQueue = (
 
   return {
     adapter,
+    hold: () => {
+      held = true;
+    },
+    release: () => {
+      held = false;
+      advance();
+    },
     notifyBusy: () => {
       paused = false;
       // a cancelled run's settle that is still outstanding belongs to a run
@@ -280,6 +351,7 @@ export const createMessageQueue = (
       suppressIdle += cancelSettles;
       cancelSettles = 0;
       running = true;
+      busyEdges++;
     },
     notifyIdle: () => {
       if (suppressIdle > 0) {

package/src/runtime/utils/auto-status.test.ts

@@ -1,5 +1,33 @@
 import { describe, expect, it } from "vitest";
-import { getAutoStatus } from "./auto-status";
+import type { MessageStatus, ThreadMessage } from "../../types/message";
+import {
+  getAutoStatus,
+  getContentAutoStatus,
+  isBackgroundToolCall,
+} from "./auto-status";
+
+const nestedAssistantMessage = (status: MessageStatus): ThreadMessage => ({
+  id: "nested-assistant",
+  createdAt: new Date(0),
+  role: "assistant",
+  content: [],
+  status,
+  metadata: {
+    unstable_state: {},
+    unstable_annotations: [],
+    unstable_data: [],
+    steps: [],
+    custom: {},
+  },
+});
+
+const pendingToolCall = (messages?: readonly ThreadMessage[]) => ({
+  type: "tool-call" as const,
+  toolName: "delegate",
+  args: {},
+  argsText: "",
+  messages,
+});
 
 describe("getAutoStatus", () => {
   it("reports a cancelled message as incomplete", () => {
@@ -54,4 +82,87 @@ describe("getAutoStatus", () => {
       ).toMatchObject(expected);
     },
   );
+
+  it.each([true, false])(
+    "keeps a background tool call running when isLast is %s",
+    (isLast) => {
+      expect(
+        getContentAutoStatus(
+          [pendingToolCall([nestedAssistantMessage({ type: "running" })])],
+          isLast,
+          false,
+        ),
+      ).toMatchObject({ type: "running" });
+    },
+  );
+
+  it("reads the trailing nested message, not an earlier running one", () => {
+    expect(
+      isBackgroundToolCall(
+        pendingToolCall([
+          nestedAssistantMessage({ type: "running" }),
+          nestedAssistantMessage({ type: "complete", reason: "unknown" }),
+        ]),
+      ),
+    ).toBe(false);
+  });
+
+  it("lets cancellation clear a background tool call", () => {
+    expect(
+      getAutoStatus(true, false, false, true, undefined, true, true),
+    ).toMatchObject({ type: "requires-action", reason: "tool-calls" });
+  });
+
+  it("keeps a settled nested tool call pending", () => {
+    expect(
+      getContentAutoStatus(
+        [
+          pendingToolCall([
+            nestedAssistantMessage({ type: "complete", reason: "unknown" }),
+          ]),
+        ],
+        true,
+        false,
+      ),
+    ).toMatchObject({ type: "requires-action", reason: "tool-calls" });
+  });
+
+  it("keeps an interrupted tool call ahead of a background tool call", () => {
+    expect(
+      getContentAutoStatus(
+        [
+          {
+            ...pendingToolCall(),
+            interrupt: { type: "human", payload: {} },
+          },
+          pendingToolCall([nestedAssistantMessage({ type: "running" })]),
+        ],
+        false,
+        false,
+      ),
+    ).toMatchObject({ type: "requires-action", reason: "interrupt" });
+  });
+
+  it.each([
+    ["a result", { ...pendingToolCall(), result: {} }],
+    ["no nested messages", pendingToolCall()],
+    [
+      "only a user nested message",
+      pendingToolCall([
+        {
+          id: "nested-user",
+          createdAt: new Date(0),
+          role: "user",
+          content: [],
+          attachments: [],
+          metadata: { custom: {} },
+        },
+      ]),
+    ],
+  ])(
+    "does not treat a tool call with %s as a background call",
+    (_label, call) => {
+      expect(isBackgroundToolCall(call)).toBe(false);
+    },
+  );
 });

package/src/runtime/utils/auto-status.ts

@@ -10,6 +10,15 @@ type ThreadMessageLikeContentItem = Exclude<
 export const isPendingToolCall = (c: ThreadMessageLikeContentItem): boolean =>
   c.type === "tool-call" && c.result === undefined;
 
+/** A pending tool call whose nested conversation is still streaming; the outer message stays running until the nested run settles. */
+export const isBackgroundToolCall = (
+  c: ThreadMessageLikeContentItem,
+): boolean => {
+  if (c.type !== "tool-call" || c.result !== undefined) return false;
+  const last = c.messages?.at(-1);
+  return last?.role === "assistant" && last.status.type === "running";
+};
+
 export const isInterruptedToolCall = (
   c: ThreadMessageLikeContentItem,
 ): boolean => {
@@ -76,6 +85,7 @@ export const getAutoStatus = (
   hasPendingToolCalls: boolean,
   error?: ReadonlyJSONValue,
   isCancelled?: boolean,
+  hasBackgroundToolCalls?: boolean,
 ): MessageStatus => {
   if (isLast && error) {
     return Object.assign(
@@ -92,13 +102,26 @@ export const getAutoStatus = (
     ? AUTO_STATUS_RUNNING
     : hasInterruptedToolCalls
       ? AUTO_STATUS_INTERRUPT
-      : hasPendingToolCalls
-        ? AUTO_STATUS_PENDING
-        : isCancelled
-          ? AUTO_STATUS_CANCELLED
-          : AUTO_STATUS_COMPLETE;
+      : hasBackgroundToolCalls && !isCancelled
+        ? AUTO_STATUS_RUNNING
+        : hasPendingToolCalls
+          ? AUTO_STATUS_PENDING
+          : isCancelled
+            ? AUTO_STATUS_CANCELLED
+            : AUTO_STATUS_COMPLETE;
 };
 
+/** Status for a message entering the repository: the nested conversation is not being fed here, so it never keeps the message running. */
+export const getRepositoryContentAutoStatus = (
+  content: ThreadMessageLike["content"],
+): MessageStatus =>
+  getAutoStatus(
+    false,
+    false,
+    typeof content !== "string" && content.some(isInterruptedToolCall),
+    typeof content !== "string" && content.some(isPendingToolCall),
+  );
+
 export const getContentAutoStatus = (
   content: ThreadMessageLike["content"],
   isLast: boolean,
@@ -109,4 +132,7 @@ export const getContentAutoStatus = (
     isRunning,
     typeof content !== "string" && content.some(isInterruptedToolCall),
     typeof content !== "string" && content.some(isPendingToolCall),
+    undefined,
+    undefined,
+    typeof content !== "string" && content.some(isBackgroundToolCall),
   );

package/src/runtime/utils/external-message-conversion.test.ts

@@ -1,10 +1,13 @@
 import { describe, expect, it, vi } from "vitest";
+import type { ThreadMessage } from "../../types/message";
 import {
   chunkExternalMessages,
   convertExternalMessageCallback,
   convertExternalMessageChunk,
+  joinExternalMessages,
   type ExternalMessageConverterCallback,
   type ExternalMessageConverterCallbackResult,
+  type ExternalMessageConverterMessage,
 } from "./external-message-conversion";
 
 describe("convertExternalMessageCallback", () => {
@@ -30,6 +33,75 @@ describe("convertExternalMessageCallback", () => {
   });
 });
 
+describe("joinExternalMessages", () => {
+  it("preserves strict equality for malformed numeric tool-call IDs", () => {
+    const messages = [
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "tool-call",
+            toolCallId: 1,
+            toolName: "search",
+            args: { query: "old" },
+          },
+        ],
+      },
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "tool-call",
+            toolCallId: 1,
+            toolName: "search",
+            args: { query: "new" },
+          },
+        ],
+      },
+    ] as unknown as ExternalMessageConverterMessage[];
+
+    expect(joinExternalMessages(messages).content).toMatchObject([
+      {
+        type: "tool-call",
+        toolCallId: 1,
+        args: { query: "new" },
+      },
+    ]);
+  });
+
+  it("does not merge malformed NaN tool-call IDs", () => {
+    const messages = [
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "tool-call",
+            toolCallId: Number.NaN,
+            toolName: "search",
+            args: { query: "first" },
+          },
+          {
+            type: "tool-call",
+            toolCallId: Number.NaN,
+            toolName: "search",
+            args: { query: "second" },
+          },
+        ],
+      },
+      { role: "tool", toolCallId: Number.NaN, result: "found" },
+    ] as unknown as ExternalMessageConverterMessage[];
+
+    const result = joinExternalMessages(messages);
+
+    expect(result.content).toMatchObject([
+      { type: "tool-call", args: { query: "first" } },
+      { type: "tool-call", args: { query: "second" } },
+    ]);
+    expect(result.content[0]).not.toHaveProperty("result");
+    expect(result.content[1]).not.toHaveProperty("result");
+  });
+});
+
 describe("chunkExternalMessages", () => {
   it("keeps a tool result with a non-joining assistant before starting the next chunk", () => {
     const toolCall = {};
@@ -80,9 +152,114 @@ describe("chunkExternalMessages", () => {
     ]);
     expect(chunks[1]?.inputs).toEqual([answer]);
   });
+
+  it("keeps a voice assistant transcript out of the neighbouring assistant chunks", () => {
+    const typed = {};
+    const spoken = {};
+    const spokenAgain = {};
+    const typedAgain = {};
+    const callbackResults: ExternalMessageConverterCallbackResult<object>[] = [
+      { input: typed, outputs: [{ role: "assistant", content: "typed" }] },
+      {
+        input: spoken,
+        outputs: [
+          {
+            role: "assistant",
+            content: "spoken",
+            metadata: { modality: "voice" },
+          },
+        ],
+      },
+      {
+        input: spokenAgain,
+        outputs: [
+          {
+            role: "assistant",
+            content: "spoken again",
+            metadata: { modality: "voice" },
+          },
+        ],
+      },
+      {
+        input: typedAgain,
+        outputs: [{ role: "assistant", content: "typed again" }],
+      },
+    ];
+
+    const chunks = chunkExternalMessages(callbackResults);
+
+    expect(chunks.map((chunk) => chunk.inputs)).toEqual([
+      [typed],
+      [spoken],
+      [spokenAgain],
+      [typedAgain],
+    ]);
+  });
 });
 
 describe("convertExternalMessageChunk", () => {
+  it("keeps an ended outer run running for a background tool call", () => {
+    const nestedAssistant: ThreadMessage = {
+      id: "nested-assistant",
+      createdAt: new Date(0),
+      role: "assistant",
+      content: [],
+      status: { type: "running" },
+      metadata: {
+        unstable_state: {},
+        unstable_annotations: [],
+        unstable_data: [],
+        steps: [],
+        custom: {},
+      },
+    };
+    const result = convertExternalMessageChunk(
+      {
+        inputs: [{}],
+        outputs: [
+          {
+            role: "assistant",
+            content: [
+              {
+                type: "tool-call",
+                toolName: "delegate",
+                args: {},
+                messages: [nestedAssistant],
+              },
+            ],
+          },
+        ],
+      },
+      0,
+      1,
+      false,
+      undefined,
+    );
+
+    expect(result.status).toMatchObject({ type: "running" });
+  });
+
+  it("preserves assistant message modality", () => {
+    const result = convertExternalMessageChunk(
+      {
+        inputs: [{}],
+        outputs: [
+          {
+            role: "assistant",
+            content: "Spoken reply",
+            metadata: { modality: "voice" },
+          },
+        ],
+      },
+      0,
+      1,
+      false,
+      undefined,
+    );
+
+    expect(result.metadata.modality).toBe("voice");
+  });
+
   it("keeps separate tool calls without IDs", () => {
     const result = convertExternalMessageChunk(
       {