@assistant-ui/core 0.3.20 → 0.3.21

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

@@ -48,6 +48,21 @@ describe("getAutoStatus", () => {
     ).toMatchObject({ type: "complete", reason: "unknown" });
   });
 
+  it.each([false, 0, ""])("preserves the falsy error payload %j", (error) => {
+    expect(getAutoStatus(true, false, false, false, error)).toMatchObject({
+      type: "incomplete",
+      reason: "error",
+      error,
+    });
+  });
+
+  it("treats a null error as no error", () => {
+    expect(getAutoStatus(true, false, false, false, null)).toMatchObject({
+      type: "complete",
+      reason: "unknown",
+    });
+  });
+
   it.each([
     ["running", { type: "running" }, true, false, false, undefined],
     [
@@ -143,6 +158,45 @@ describe("getAutoStatus", () => {
     ).toMatchObject({ type: "requires-action", reason: "interrupt" });
   });
 
+  it.each([
+    ["approval", { approval: { id: "approval-1" } }],
+    ["interrupt", { interrupt: { type: "human" as const, payload: {} } }],
+  ] as const)(
+    "keeps a tool call with a pending %s interrupted beside its result",
+    (_label, action) => {
+      expect(
+        getContentAutoStatus(
+          [{ ...pendingToolCall(), result: "partial output", ...action }],
+          true,
+          false,
+        ),
+      ).toMatchObject({ type: "requires-action", reason: "interrupt" });
+    },
+  );
+
+  it.each([
+    ["a decision", { approved: true }],
+    ["a rejection", { approved: false }],
+    ["a resolution", { resolution: "cancelled" as const }],
+  ])(
+    "settles a tool call whose approval carries %s beside its result",
+    (_label, settled) => {
+      expect(
+        getContentAutoStatus(
+          [
+            {
+              ...pendingToolCall(),
+              result: "sunny",
+              approval: { id: "approval-1", ...settled },
+            },
+          ],
+          true,
+          false,
+        ),
+      ).toMatchObject({ type: "complete" });
+    },
+  );
+
   it.each([
     ["a result", { ...pendingToolCall(), result: {} }],
     ["no nested messages", pendingToolCall()],

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

@@ -1,6 +1,7 @@
 import type { MessageStatus } from "../../types/message";
 import type { ReadonlyJSONValue } from "assistant-stream/utils";
 import type { ThreadMessageLike } from "./thread-message-like";
+import { hasPendingToolAction } from "../../utils/normalizePartStatus";
 
 type ThreadMessageLikeContentItem = Exclude<
   ThreadMessageLike["content"],
@@ -21,15 +22,7 @@ export const isBackgroundToolCall = (
 
 export const isInterruptedToolCall = (
   c: ThreadMessageLikeContentItem,
-): boolean => {
-  if (c.type !== "tool-call" || c.result !== undefined) return false;
-  return (
-    c.interrupt != null ||
-    (c.approval != null &&
-      c.approval.approved === undefined &&
-      c.approval.resolution === undefined)
-  );
-};
+): boolean => c.type === "tool-call" && hasPendingToolAction(c);
 
 const symbolAutoStatus = Symbol("autoStatus");
 
@@ -87,7 +80,7 @@ export const getAutoStatus = (
   isCancelled?: boolean,
   hasBackgroundToolCalls?: boolean,
 ): MessageStatus => {
-  if (isLast && error) {
+  if (isLast && error !== undefined && error !== null) {
     return Object.assign(
       {
         type: "incomplete" as const,

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

@@ -2,6 +2,7 @@ import { describe, expect, it, vi } from "vitest";
 import type { ThreadMessage } from "../../types/message";
 import {
   chunkExternalMessages,
+  completeExternalMessageConversion,
   convertExternalMessageCallback,
   convertExternalMessageChunk,
   joinExternalMessages,
@@ -10,6 +11,25 @@ import {
   type ExternalMessageConverterMessage,
 } from "./external-message-conversion";
 
+describe("completeExternalMessageConversion", () => {
+  it.each([false, 0, ""])(
+    "adds an assistant message for the falsy error payload %j",
+    (error) => {
+      const result = completeExternalMessageConversion([], error);
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toMatchObject({
+        role: "assistant",
+        status: { type: "incomplete", reason: "error", error },
+      });
+    },
+  );
+
+  it("adds no assistant message for a null error", () => {
+    expect(completeExternalMessageConversion([], null)).toHaveLength(0);
+  });
+});
+
 describe("convertExternalMessageCallback", () => {
   it.each([
     ["a missing toolCallId", { role: "tool", result: "ok" }],
@@ -69,6 +89,34 @@ describe("joinExternalMessages", () => {
     ]);
   });
 
+  it("settles a preliminary tool call when its tool message lands", () => {
+    const messages = [
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "tool-call",
+            toolCallId: "call-1",
+            toolName: "bash",
+            args: {},
+            result: "partial output",
+            isPreliminary: true,
+          },
+        ],
+      },
+      {
+        role: "tool",
+        toolCallId: "call-1",
+        toolName: "bash",
+        result: "final output",
+      },
+    ] as unknown as ExternalMessageConverterMessage[];
+
+    const [part] = joinExternalMessages(messages).content;
+    expect(part).toMatchObject({ type: "tool-call", result: "final output" });
+    expect(part).not.toHaveProperty("isPreliminary");
+  });
+
   it("does not merge malformed NaN tool-call IDs", () => {
     const messages = [
       {

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

@@ -157,9 +157,8 @@ export const joinExternalMessages = (
       // Ignore orphaned tool results so one bad tool message does not
       // prevent rendering the rest of the conversation.
       if (toolCallIdx !== -1) {
-        const toolCall = assistantMessage.content[
-          toolCallIdx
-        ]! as ToolCallMessagePart;
+        const { isPreliminary: _isPreliminary, ...toolCall } = assistantMessage
+          .content[toolCallIdx]! as ToolCallMessagePart;
         if (output.toolName != null) {
           if (toolCall.toolName !== output.toolName)
             throw new Error(
@@ -529,7 +528,7 @@ export const completeExternalMessageConversion = (
   messages: ThreadMessage[],
   error: ReadonlyJSONValue | undefined,
 ) => {
-  if (error) {
+  if (error !== undefined && error !== null) {
     const lastMessage = messages.at(-1);
     if (!lastMessage || lastMessage.role !== "assistant") {
       messages.push(createErrorAssistantMessage(error));

package/src/runtime/utils/message-repository.test.ts

@@ -1,6 +1,9 @@
 import { describe, expect, it } from "vitest";
 import type { ThreadMessage } from "../../types/message";
-import { ExportedMessageRepository } from "./message-repository";
+import {
+  ExportedMessageRepository,
+  MessageRepository,
+} from "./message-repository";
 
 const nestedRunningAssistant: ThreadMessage = {
   id: "nested-assistant",
@@ -47,3 +50,68 @@ describe("ExportedMessageRepository", () => {
     }
   });
 });
+
+const message = (id: string, text = id): ThreadMessage => ({
+  id,
+  createdAt: new Date(0),
+  role: "user",
+  content: [{ type: "text", text }],
+  attachments: [],
+  metadata: { custom: {} },
+});
+
+const snapshot = (repository: MessageRepository) => ({
+  headId: repository.headId,
+  visible: repository.getMessages(),
+  exported: repository.export(),
+});
+
+describe("MessageRepository rejected operations", () => {
+  it("keeps the old content when an update is rejected as a cycle", () => {
+    const repository = new MessageRepository();
+    const original = message("a");
+    repository.addOrUpdateMessage(null, original);
+    const before = snapshot(repository);
+
+    expect(() =>
+      repository.addOrUpdateMessage("a", message("a", "edited")),
+    ).toThrow(/same id already exists in the parent tree/);
+
+    expect(snapshot(repository)).toEqual(before);
+    expect(repository.getMessage("a").message).toBe(original);
+  });
+
+  it("moves no child when the replacement is a descendant of the deleted message", () => {
+    const repository = new MessageRepository();
+    repository.addOrUpdateMessage(null, message("a"));
+    repository.addOrUpdateMessage("a", message("b"));
+    repository.addOrUpdateMessage("a", message("c"));
+    repository.addOrUpdateMessage("c", message("d"));
+    const before = snapshot(repository);
+
+    expect(() => repository.deleteMessage("a", "c")).toThrow(
+      /Replacement is the deleted message or one of its descendants/,
+    );
+    expect(snapshot(repository)).toEqual(before);
+
+    expect(() => repository.deleteMessage("a", "d")).toThrow(
+      /Replacement is the deleted message or one of its descendants/,
+    );
+    expect(snapshot(repository)).toEqual(before);
+    expect(repository.getMessage("b").parentId).toBe("a");
+    expect(repository.getBranches("b")).toEqual(["b", "c"]);
+  });
+
+  it("rejects a message as its own replacement instead of leaving the head on it", () => {
+    const repository = new MessageRepository();
+    repository.addOrUpdateMessage(null, message("a"));
+    const before = snapshot(repository);
+
+    expect(() => repository.deleteMessage("a", "a")).toThrow(
+      /Replacement is the deleted message or one of its descendants/,
+    );
+
+    expect(snapshot(repository)).toEqual(before);
+    expect(repository.getMessage("a").message.id).toBe("a");
+  });
+});

package/src/runtime/utils/message-repository.ts

@@ -262,8 +262,8 @@ export class MessageRepository {
       );
 
     if (existingItem) {
-      existingItem.current = message;
       this.performOp(prev, existingItem, "relink");
+      existingItem.current = message;
       this._messages.dirty();
       return;
     }
@@ -319,6 +319,13 @@ export class MessageRepository {
         "MessageRepository(deleteMessage): Replacement not found. This is likely an internal bug in assistant-ui.",
       );
 
+    for (let current = replacement; current; current = current.prev) {
+      if (current === message)
+        throw new Error(
+          "MessageRepository(deleteMessage): Replacement is the deleted message or one of its descendants. This is likely an internal bug in assistant-ui.",
+        );
+    }
+
     for (const child of message.children) {
       const childMessage = this.messages.get(child);
       if (!childMessage)
@@ -350,12 +357,12 @@ export class MessageRepository {
   }
 
   /**
-   * Evicts optimistic messages (`metadata.isOptimistic`) the head just moved
-   * away from. Since eviction runs on every head move, the only optimistic
-   * messages in the repository live on the branch the head previously pointed
-   * at — so we walk just that branch rather than the whole repository. Keeps a
-   * client→server id swap from leaving a phantom sibling, and drops off-branch
-   * placeholders.
+   * Evicts optimistic messages (`metadata.isOptimistic`) on the branch the head
+   * just moved away from. Only that branch is walked, so an optimistic message
+   * added off the head branch (such as the server-id copy that replaces a
+   * client-id placeholder before the head moves to it) is kept until a
+   * `switchToBranch` or `resetHead` moves the head off the branch it is on.
+   * Keeps a client→server id swap from leaving a phantom sibling.
    */
   private evictOffBranchOptimisticMessages(
     previousHead: RepositoryMessage | null,

package/src/runtime/utils/stored-message-parts.ts

@@ -1,10 +1,12 @@
 import type { CompleteAttachment } from "../../types/attachment";
 import type {
+  MessageStatus,
   ThreadAssistantMessagePart,
   ThreadMessage,
+  ThreadStep,
   ThreadUserMessagePart,
 } from "../../types/message";
-import { isRecord } from "../../utils/json/is-json";
+import { isJSONValue, isRecord } from "../../utils/json/is-json";
 
 export const MAX_STORED_MESSAGE_DEPTH = 100;
 
@@ -25,6 +27,46 @@ export const isStoredMessageRole = (
 ): value is ThreadMessage["role"] =>
   value === "system" || value === "user" || value === "assistant";
 
+type StoredStatusGuard = (status: Record<string, unknown>) => boolean;
+
+const storedMessageStatusGuards = {
+  running: () => true,
+  "requires-action": (status) => typeof status.reason === "string",
+  complete: (status) => typeof status.reason === "string",
+  incomplete: (status) =>
+    (status.reason === undefined || typeof status.reason === "string") &&
+    (status.error === undefined || isJSONValue(status.error)),
+} satisfies Record<MessageStatus["type"], StoredStatusGuard>;
+
+const storedMessageStatusGuardsByType: Record<string, StoredStatusGuard> =
+  storedMessageStatusGuards;
+
+export const isStoredMessageStatus = (value: unknown): value is MessageStatus =>
+  isRecord(value) &&
+  typeof value.type === "string" &&
+  Object.hasOwn(storedMessageStatusGuardsByType, value.type) &&
+  storedMessageStatusGuardsByType[value.type]!(value) === true;
+
+const parseStoredThreadStep = (value: unknown): ThreadStep | undefined => {
+  if (!isRecord(value)) return undefined;
+  if (value.messageId !== undefined && typeof value.messageId !== "string") {
+    const { messageId: _, ...step } = value;
+    return parseStoredThreadStep(step);
+  }
+  if (value.usage !== undefined && !isRecord(value.usage)) {
+    const { usage: _, ...step } = value;
+    return step as ThreadStep;
+  }
+  return value as ThreadStep;
+};
+
+export const parseStoredThreadSteps = (value: unknown): ThreadStep[] =>
+  Array.isArray(value)
+    ? value
+        .map(parseStoredThreadStep)
+        .filter((step): step is ThreadStep => step !== undefined)
+    : [];
+
 /**
  * Builds the readability predicate for a persistence boundary. A stored part is
  * readable when it passes the guard for its known type, or when its type is

package/src/runtime/utils/thread-message-like.test.ts

@@ -49,4 +49,62 @@ describe("fromThreadMessageLike", () => {
 
     expect(message.metadata).not.toHaveProperty("modality");
   });
+
+  it("keeps readable tool-call interactions", () => {
+    const message = fromThreadMessageLike(
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "tool-call",
+            toolCallId: "call-1",
+            toolName: "confirm",
+            args: {},
+            unstable_interactions: {
+              entries: [
+                {
+                  type: "action",
+                  occurredAt: 10,
+                  payload: { $input: "approve" },
+                },
+              ],
+            },
+          },
+        ],
+      },
+      "assistant-id",
+      { type: "complete", reason: "unknown" },
+    );
+
+    expect(message.content[0]).toHaveProperty("unstable_interactions", {
+      entries: [
+        {
+          type: "action",
+          occurredAt: 10,
+          payload: { $input: "approve" },
+        },
+      ],
+    });
+  });
+
+  it("omits unreadable tool-call interactions", () => {
+    const message = fromThreadMessageLike(
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "tool-call",
+            toolCallId: "call-1",
+            toolName: "confirm",
+            args: {},
+            unstable_interactions: { entries: [{ type: "unknown" }] },
+          },
+        ],
+      } as never,
+      "assistant-id",
+      { type: "complete", reason: "unknown" },
+    );
+
+    expect(message.content[0]).not.toHaveProperty("unstable_interactions");
+  });
 });

package/src/runtime/utils/thread-message-like.ts

@@ -2,8 +2,6 @@ import { parsePartialJsonObject } from "assistant-stream/utils";
 import { generateId } from "../../utils/id";
 import { parseDataUrl } from "../../utils/data-url";
 import type {
-  ReasoningMessagePart,
-  SourceMessagePart,
   ThreadStep,
   MessageStatus,
   ImageMessagePart,
@@ -13,10 +11,7 @@ import type {
   ThreadUserMessagePart,
   ThreadUserMessage,
   ThreadSystemMessage,
-  FileMessagePart,
   DataMessagePart,
-  GenerativeUIMessagePart,
-  Unstable_AudioMessagePart,
 } from "../../types/message";
 import type { CompleteAttachment } from "../../types/attachment";
 import type {
@@ -27,49 +22,48 @@ import type {
   ToolCallTiming,
   ToolCallMessagePart,
   ToolCallMessagePartMcpMetadata,
+  ToolModelContentPart,
+  Unstable_ToolInteractionLog,
 } from "../../types/message";
 import type {
   ReadonlyJSONObject,
   ReadonlyJSONValue,
 } from "assistant-stream/utils";
+import { readToolInteractionLog } from "./tool-interactions";
 
 type DataPrefixedPart = {
   readonly type: `data-${string}`;
   readonly data: any;
 };
 
+type ThreadMessageLikePart =
+  | ThreadUserMessagePart
+  | ThreadAssistantMessagePart
+  | DataPrefixedPart
+  | {
+      readonly type: "tool-call";
+      readonly toolCallId?: string;
+      readonly toolName: string;
+      readonly args?: ReadonlyJSONObject;
+      readonly argsText?: string;
+      readonly artifact?: any;
+      readonly modelContent?: readonly ToolModelContentPart[] | undefined;
+      readonly result?: any | undefined;
+      readonly isError?: boolean | undefined;
+      readonly isPreliminary?: boolean | undefined;
+      readonly parentId?: string | undefined;
+      readonly messages?: readonly ThreadMessage[] | undefined;
+      readonly interrupt?: { type: "human"; payload: unknown };
+      readonly timing?: ToolCallTiming;
+      readonly mcp?: ToolCallMessagePartMcpMetadata;
+      readonly providerMetadata?: PartProviderMetadata;
+      readonly approval?: NonNullable<ToolCallMessagePart["approval"]>;
+      readonly unstable_interactions?: Unstable_ToolInteractionLog;
+    };
+
 export type ThreadMessageLike = {
   readonly role: "assistant" | "user" | "system";
-  readonly content:
-    | string
-    | readonly (
-        | TextMessagePart
-        | ReasoningMessagePart
-        | SourceMessagePart
-        | ImageMessagePart
-        | FileMessagePart
-        | DataMessagePart
-        | GenerativeUIMessagePart
-        | Unstable_AudioMessagePart
-        | DataPrefixedPart
-        | {
-            readonly type: "tool-call";
-            readonly toolCallId?: string;
-            readonly toolName: string;
-            readonly args?: ReadonlyJSONObject;
-            readonly argsText?: string;
-            readonly artifact?: any;
-            readonly result?: any | undefined;
-            readonly isError?: boolean | undefined;
-            readonly parentId?: string | undefined;
-            readonly messages?: readonly ThreadMessage[] | undefined;
-            readonly interrupt?: { type: "human"; payload: unknown };
-            readonly timing?: ToolCallTiming;
-            readonly mcp?: ToolCallMessagePartMcpMetadata;
-            readonly providerMetadata?: PartProviderMetadata;
-            readonly approval?: NonNullable<ToolCallMessagePart["approval"]>;
-          }
-      )[];
+  readonly content: string | readonly ThreadMessageLikePart[];
   readonly id?: string | undefined;
   readonly createdAt?: Date | undefined;
   readonly status?: MessageStatus | undefined;
@@ -183,12 +177,23 @@ export const fromThreadMessageLike = (
                 return part;
 
               case "tool-call": {
-                const { parentId, messages, ...basePart } = part;
+                const {
+                  parentId,
+                  messages,
+                  unstable_interactions,
+                  ...basePart
+                } = part;
+                const interactions = readToolInteractionLog(
+                  unstable_interactions,
+                );
                 const commonProps = {
                   ...basePart,
                   toolCallId: part.toolCallId || `tool-${generateId()}`,
                   ...(parentId !== undefined && { parentId }),
                   ...(messages !== undefined && { messages }),
+                  ...(interactions !== undefined && {
+                    unstable_interactions: interactions,
+                  }),
                 };
 
                 if (part.args) {
@@ -205,14 +210,22 @@ export const fromThreadMessageLike = (
                 };
               }
 
-              default: {
-                const converted = convertDataPrefixedPart(
-                  type,
-                  (part as DataPrefixedPart).data,
+              case "audio": {
+                const userOnlyType: Exclude<
+                  typeof type,
+                  ThreadAssistantMessagePart["type"]
+                > = type;
+                throw new Error(
+                  `Unsupported assistant message part type: ${userOnlyType}`,
                 );
+              }
+
+              default: {
+                const dataType: `data-${string}` = type;
+                const converted = convertDataPrefixedPart(dataType, part.data);
                 if (converted) return converted;
                 throw new Error(
-                  `Unsupported assistant message part type: ${type}`,
+                  `Unsupported assistant message part type: ${dataType}`,
                 );
               }
             }
@@ -248,13 +261,26 @@ export const fromThreadMessageLike = (
             case "data":
               return part;
 
-            default: {
-              const converted = convertDataPrefixedPart(
-                type,
-                (part as DataPrefixedPart).data,
+            case "reasoning":
+            case "source":
+            case "generative-ui":
+            case "tool-call": {
+              const assistantOnlyType: Exclude<
+                typeof type,
+                ThreadUserMessagePart["type"]
+              > = type;
+              throw new Error(
+                `Unsupported user message part type: ${assistantOnlyType}`,
               );
+            }
+
+            default: {
+              const dataType: `data-${string}` = type;
+              const converted = convertDataPrefixedPart(dataType, part.data);
               if (converted) return converted;
-              throw new Error(`Unsupported user message part type: ${type}`);
+              throw new Error(
+                `Unsupported user message part type: ${dataType}`,
+              );
             }
           }
         }),

package/src/runtime/utils/thread-runtime-lifecycle.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it, onTestFinished, vi } from "vitest";
+import type { ThreadRuntimeCore } from "../interfaces/thread-runtime-core";
+import {
+  captureThreadRuntimeGeneration,
+  disposeThreadRuntime,
+  invalidateThreadRuntime,
+  supersedeThreadRuntime,
+} from "./thread-runtime-lifecycle";
+
+const createRuntime = (disconnectVoice: () => void = vi.fn()) =>
+  ({
+    voice: { status: { type: "running" } },
+    disconnectVoice,
+  }) as unknown as ThreadRuntimeCore;
+
+describe("thread runtime lifecycle", () => {
+  it("starts a fresh generation after invalidation", () => {
+    const runtime = createRuntime();
+    const generation = captureThreadRuntimeGeneration(runtime);
+
+    invalidateThreadRuntime(runtime);
+
+    expect(generation.aborted).toBe(true);
+    expect(captureThreadRuntimeGeneration(runtime).aborted).toBe(false);
+  });
+
+  it("ends the call of a superseded runtime without disposing it", () => {
+    const disconnectVoice = vi.fn();
+    const runtime = createRuntime(disconnectVoice);
+    const generation = captureThreadRuntimeGeneration(runtime);
+
+    supersedeThreadRuntime(runtime);
+
+    expect(disconnectVoice).toHaveBeenCalledOnce();
+    expect(generation.aborted).toBe(true);
+    expect(captureThreadRuntimeGeneration(runtime).aborted).toBe(false);
+  });
+
+  it("keeps a disposed runtime aborted through a later invalidation", () => {
+    const disconnectVoice = vi.fn();
+    const runtime = createRuntime(disconnectVoice);
+
+    disposeThreadRuntime(runtime);
+    invalidateThreadRuntime(runtime);
+
+    expect(captureThreadRuntimeGeneration(runtime).aborted).toBe(true);
+    expect(disconnectVoice).toHaveBeenCalledOnce();
+  });
+
+  it("reports a voice disconnect that throws instead of rethrowing it", () => {
+    const error = new Error("disconnect failed");
+    const runtime = createRuntime(() => {
+      throw error;
+    });
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    onTestFinished(() => consoleError.mockRestore());
+
+    expect(() => disposeThreadRuntime(runtime)).not.toThrow();
+    expect(consoleError).toHaveBeenCalledExactlyOnceWith(
+      "[assistant-ui] Voice cleanup threw while discarding a thread runtime",
+      error,
+    );
+    expect(captureThreadRuntimeGeneration(runtime).aborted).toBe(true);
+  });
+});