@assistant-ui/core 0.3.19 → 0.3.21

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

@@ -0,0 +1,216 @@
+import type { CompleteAttachment } from "../../types/attachment";
+import type {
+  MessageStatus,
+  ThreadAssistantMessagePart,
+  ThreadMessage,
+  ThreadStep,
+  ThreadUserMessagePart,
+} from "../../types/message";
+import { isJSONValue, isRecord } from "../../utils/json/is-json";
+
+export const MAX_STORED_MESSAGE_DEPTH = 100;
+
+type StoredPartGuard = (part: Record<string, unknown>) => boolean;
+
+export type StoredMessagePart = Record<string, unknown> & { type: string };
+
+export const parseStoredDate = (value: unknown): Date | null => {
+  if (value instanceof Date && !Number.isNaN(value.getTime())) return value;
+  if (typeof value !== "string" && typeof value !== "number") return null;
+
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+};
+
+export const isStoredMessageRole = (
+  value: unknown,
+): 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
+ * unknown and the boundary can still read it.
+ *
+ * Unknown types are where the boundaries part: local storage hands its rows to
+ * the runtime untouched, so a type written by a newer release still loads,
+ * while the aui/v0 decoder converts a `data-` prefix and throws on anything
+ * else unknown. Per-type differences ride in `overrides`.
+ */
+const makeIsStoredMessagePart = (
+  overrides: Partial<
+    Record<
+      (ThreadUserMessagePart | ThreadAssistantMessagePart)["type"],
+      StoredPartGuard
+    >
+  >,
+  isReadableUnknownType: (type: string) => boolean,
+) => {
+  const storedPartGuards = {
+    text: (part) => typeof part.text === "string",
+    reasoning: (part) =>
+      typeof part.text === "string" ||
+      typeof part.unstable_summary === "string",
+    image: (part) => typeof part.image === "string",
+    file: (part) =>
+      typeof part.data === "string" && typeof part.mimeType === "string",
+    audio: (part) =>
+      isRecord(part.audio) &&
+      typeof part.audio.data === "string" &&
+      typeof part.audio.format === "string",
+    data: (part) => typeof part.name === "string",
+    source: (part) =>
+      typeof part.id === "string" &&
+      (part.sourceType === "url"
+        ? typeof part.url === "string"
+        : part.sourceType === "document" &&
+          typeof part.title === "string" &&
+          typeof part.mediaType === "string"),
+    "generative-ui": (part) => isRecord(part.spec),
+    "tool-call": (part) =>
+      typeof part.toolCallId === "string" &&
+      typeof part.toolName === "string" &&
+      isRecord(part.args) &&
+      typeof part.argsText === "string",
+  } satisfies Record<
+    (ThreadUserMessagePart | ThreadAssistantMessagePart)["type"],
+    StoredPartGuard
+  >;
+  const guards: Record<string, StoredPartGuard> = {
+    ...storedPartGuards,
+    ...overrides,
+  };
+
+  return (value: unknown): value is StoredMessagePart =>
+    isRecord(value) &&
+    typeof value.type === "string" &&
+    (Object.hasOwn(guards, value.type)
+      ? guards[value.type]!(value)
+      : isReadableUnknownType(value.type));
+};
+
+export const isStoredMessagePart = makeIsStoredMessagePart({}, () => true);
+
+/**
+ * The aui/v0 decoder dereferences each present field rather than reading only
+ * the one it needs, so this boundary checks every field it will touch, while
+ * local storage stays no stricter than what the runtime itself writes.
+ */
+const isStoredAuiV0Part = makeIsStoredMessagePart(
+  {
+    reasoning: (part) =>
+      (part.text === undefined || typeof part.text === "string") &&
+      (part.unstable_summary === undefined ||
+        typeof part.unstable_summary === "string") &&
+      (typeof part.text === "string" ||
+        typeof part.unstable_summary === "string"),
+    "tool-call": (part) =>
+      typeof part.toolCallId === "string" &&
+      typeof part.toolName === "string" &&
+      (part.args === undefined || isRecord(part.args)) &&
+      (part.argsText === undefined || typeof part.argsText === "string") &&
+      (part.args !== undefined || part.argsText !== undefined),
+  },
+  (type) => type.startsWith("data-"),
+);
+
+const rolePartTypes = {
+  user: {
+    text: true,
+    image: true,
+    file: true,
+    data: true,
+    audio: true,
+  } satisfies Record<ThreadUserMessagePart["type"], true>,
+  assistant: {
+    text: true,
+    reasoning: true,
+    "tool-call": true,
+    source: true,
+    file: true,
+    image: true,
+    data: true,
+    "generative-ui": true,
+  } satisfies Record<ThreadAssistantMessagePart["type"], true>,
+};
+
+/**
+ * `fromThreadMessageLike` converts each part through its role's branch and
+ * throws on a part that branch does not carry, which would cost the whole
+ * stored row. The aui/v0 boundary decodes through that converter, so it filters
+ * by role as well as by shape. A part type unknown to this table is left to the
+ * boundary predicate, which keeps the `data-` prefixes the converter handles.
+ */
+export const isStoredAuiV0RolePart = (
+  role: ThreadMessage["role"],
+  value: unknown,
+): value is StoredMessagePart =>
+  isStoredAuiV0Part(value) &&
+  (role === "system"
+    ? value.type === "text"
+    : Object.hasOwn(rolePartTypes.assistant, value.type) ||
+        Object.hasOwn(rolePartTypes.user, value.type)
+      ? Object.hasOwn(rolePartTypes[role], value.type)
+      : true);
+
+export const parseStoredAttachment = (
+  value: unknown,
+  isPart: (value: unknown) => value is StoredMessagePart,
+): CompleteAttachment | null => {
+  if (
+    !isRecord(value) ||
+    typeof value.id !== "string" ||
+    typeof value.type !== "string" ||
+    typeof value.name !== "string" ||
+    !isRecord(value.status) ||
+    value.status.type !== "complete" ||
+    !Array.isArray(value.content)
+  ) {
+    return null;
+  }
+
+  return {
+    ...value,
+    content: value.content.filter(isPart),
+  } as CompleteAttachment;
+};

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;
@@ -80,14 +74,19 @@ export type ThreadMessageLike = {
     | undefined;
   readonly metadata?:
     | {
-        readonly unstable_state?: ReadonlyJSONValue;
+        readonly unstable_state?: ReadonlyJSONValue | undefined;
         readonly unstable_annotations?:
           | readonly ReadonlyJSONValue[]
           | undefined;
         readonly unstable_data?: readonly ReadonlyJSONValue[] | undefined;
         readonly steps?: readonly ThreadStep[] | undefined;
         readonly timing?: MessageTiming | undefined;
-        readonly submittedFeedback?: { readonly type: "positive" | "negative" };
+        readonly submittedFeedback?:
+          | {
+              readonly type: "positive" | "negative";
+              readonly comment?: string;
+            }
+          | undefined;
         readonly isOptimistic?: boolean | undefined;
         readonly modality?: MessageModality | undefined;
         readonly custom?: Record<string, unknown> | undefined;
@@ -178,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) {
@@ -200,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}`,
                 );
               }
             }
@@ -243,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);
+  });
+});

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

@@ -3,16 +3,50 @@ import type { ThreadRuntimeCore } from "../interfaces/thread-runtime-core";
 // Invalidation must stay re-entrant: StrictMode's simulated unmount runs the
 // effect cleanup while the runtime object survives into the next mount, so a
 // permanent disposed mark would swallow every later append.
-const generations = new WeakMap<ThreadRuntimeCore, number>();
+const generations = new WeakMap<ThreadRuntimeCore, AbortController>();
 
-export const captureThreadRuntimeGeneration = (runtime: ThreadRuntimeCore) =>
-  generations.get(runtime) ?? 0;
-
-export const isThreadRuntimeGenerationCurrent = (
+export const captureThreadRuntimeGeneration = (
   runtime: ThreadRuntimeCore,
-  generation: number,
-) => captureThreadRuntimeGeneration(runtime) === generation;
+): AbortSignal => {
+  let generation = generations.get(runtime);
+  if (!generation) {
+    generation = new AbortController();
+    generations.set(runtime, generation);
+  }
+  return generation.signal;
+};
 
 export const invalidateThreadRuntime = (runtime: ThreadRuntimeCore) => {
-  generations.set(runtime, captureThreadRuntimeGeneration(runtime) + 1);
+  const generation = generations.get(runtime);
+  if (generation?.signal.aborted) return;
+  generations.delete(runtime);
+  generation?.abort();
+};
+
+const endVoiceSession = (runtime: ThreadRuntimeCore) => {
+  if (!runtime.voice) return;
+  try {
+    runtime.disconnectVoice();
+  } catch (error) {
+    console.error(
+      "[assistant-ui] Voice cleanup threw while discarding a thread runtime",
+      error,
+    );
+  }
+};
+
+// A successor keeps the same thread: the call ends as if hung up, in-flight work
+// (a commit waiting on a load included) is fenced, and later sends still land.
+export const supersedeThreadRuntime = (runtime: ThreadRuntimeCore) => {
+  endVoiceSession(runtime);
+  invalidateThreadRuntime(runtime);
+};
+
+// Disposal is that permanent mark, so only an owner that drops the runtime for
+// good may call it; tap runs every effect cleanup on a soft unmount as well.
+export const disposeThreadRuntime = (runtime: ThreadRuntimeCore) => {
+  const generation = generations.get(runtime) ?? new AbortController();
+  generations.set(runtime, generation);
+  generation.abort();
+  endVoiceSession(runtime);
 };