@assistant-ui/core 0.1.0

package/src/tests/OptimisticState-delete-crash.test.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect, vi } from "vitest";
+import { OptimisticState } from "../runtimes/remote-thread-list/optimistic-state";
+import {
+  type RemoteThreadState,
+  createThreadMappingId,
+  updateStatusReducer,
+  getThreadData,
+} from "../runtimes/remote-thread-list/remote-thread-state";
+
+/**
+ * This test reproduces the crash from issue #3346:
+ * "Entry not available in the store" when deleting the active thread.
+ *
+ * Root cause: optimisticUpdate's `optimistic` callback runs synchronously
+ * and removes the thread from threadData, but mainThreadId still points to
+ * the deleted thread. Subscribers that fire during _notifySubscribers() see
+ * this inconsistent state and crash.
+ */
+
+const createThreadState = (
+  threadId: string,
+  status: "regular" | "archived" = "regular",
+): RemoteThreadState => {
+  const mappingId = createThreadMappingId(threadId);
+  return {
+    isLoading: false,
+    newThreadId: undefined,
+    threadIds: status === "regular" ? [threadId] : [],
+    archivedThreadIds: status === "archived" ? [threadId] : [],
+    threadIdMap: { [threadId]: mappingId },
+    threadData: {
+      [mappingId]: {
+        id: threadId,
+        remoteId: threadId,
+        externalId: undefined,
+        status,
+        title: undefined,
+        initializeTask: Promise.resolve({
+          remoteId: threadId,
+          externalId: undefined,
+        }),
+      },
+    },
+  };
+};
+
+describe("OptimisticState delete crash (#3346)", () => {
+  it("optimistic callback runs synchronously before execute completes", async () => {
+    const state = new OptimisticState(createThreadState("thread-1"));
+    const events: string[] = [];
+
+    state.subscribe(() => {
+      events.push("subscriber-notified");
+    });
+
+    const executeStarted = vi.fn();
+    const executeCompleted = vi.fn();
+
+    const promise = state.optimisticUpdate({
+      execute: async () => {
+        executeStarted();
+        // simulate async work like _ensureThreadIsNotMain
+        await Promise.resolve();
+        executeCompleted();
+      },
+      optimistic: (s) => {
+        events.push("optimistic-ran");
+        return updateStatusReducer(s, "thread-1", "deleted");
+      },
+    });
+
+    // After calling optimisticUpdate but before awaiting:
+    // - optimistic callback has already run (synchronous)
+    // - execute has started but not completed (async)
+    expect(events).toEqual(["optimistic-ran", "subscriber-notified"]);
+    expect(executeStarted).toHaveBeenCalled();
+    expect(executeCompleted).not.toHaveBeenCalled();
+
+    // Thread data is already gone from the optimistic value
+    expect(getThreadData(state.value, "thread-1")).toBeUndefined();
+
+    await promise;
+  });
+
+  it("BUG SCENARIO: subscriber sees deleted thread data while mainThreadId still references it", async () => {
+    const state = new OptimisticState(createThreadState("thread-1"));
+
+    // Simulate what happens in the real code:
+    // mainThreadId is external state that _ensureThreadIsNotMain would update
+    let mainThreadId = "thread-1";
+    let subscriberSawInconsistentState = false;
+
+    state.subscribe(() => {
+      // This fires synchronously during optimisticUpdate.
+      // In the real code, React components would re-render here and try to
+      // access the main thread's data.
+      const threadData = getThreadData(state.value, mainThreadId);
+      if (threadData === undefined && mainThreadId === "thread-1") {
+        // mainThreadId points to a deleted thread — this is the crash condition
+        subscriberSawInconsistentState = true;
+      }
+    });
+
+    // OLD CODE: _ensureThreadIsNotMain inside execute
+    // The optimistic callback deletes thread data BEFORE execute can update mainThreadId
+    const promise = state.optimisticUpdate({
+      execute: async () => {
+        // In old code, _ensureThreadIsNotMain was here.
+        // It would switch mainThreadId, but this runs AFTER optimistic callback
+        await Promise.resolve();
+        mainThreadId = "thread-2"; // too late — subscriber already fired
+      },
+      optimistic: (s) => {
+        return updateStatusReducer(s, "thread-1", "deleted");
+      },
+    });
+
+    // The subscriber saw inconsistent state — mainThreadId points to deleted thread
+    expect(subscriberSawInconsistentState).toBe(true);
+
+    await promise;
+  });
+
+  it("FIX: switching mainThreadId before optimisticUpdate prevents inconsistency", async () => {
+    const state = new OptimisticState(createThreadState("thread-1"));
+
+    let mainThreadId = "thread-1";
+    let subscriberSawInconsistentState = false;
+
+    state.subscribe(() => {
+      const threadData = getThreadData(state.value, mainThreadId);
+      if (threadData === undefined) {
+        subscriberSawInconsistentState = true;
+      }
+    });
+
+    // FIX: _ensureThreadIsNotMain runs BEFORE optimisticUpdate.
+    // switchToNewThread() both creates the new thread in state AND updates mainThreadId.
+    const newThreadId = "thread-2";
+    const mappingId = createThreadMappingId(newThreadId);
+    const currentState = state.value;
+    state.update({
+      ...currentState,
+      newThreadId: newThreadId,
+      threadIdMap: {
+        ...currentState.threadIdMap,
+        [newThreadId]: mappingId,
+      },
+      threadData: {
+        ...currentState.threadData,
+        [mappingId]: {
+          status: "new" as const,
+          id: newThreadId,
+          remoteId: undefined,
+          externalId: undefined,
+          title: undefined,
+        },
+      },
+    });
+    mainThreadId = newThreadId;
+
+    // Reset flag — the state.update above triggered the subscriber
+    subscriberSawInconsistentState = false;
+
+    const promise = state.optimisticUpdate({
+      execute: async () => {
+        // _ensureThreadIsNotMain no longer here
+        return undefined;
+      },
+      optimistic: (s) => {
+        return updateStatusReducer(s, "thread-1", "deleted");
+      },
+    });
+
+    // mainThreadId was already switched to thread-2 which exists in state
+    // — subscriber sees consistent state, no crash
+    expect(subscriberSawInconsistentState).toBe(false);
+
+    await promise;
+  });
+
+  it("archive does NOT remove threadData (no crash even without fix)", async () => {
+    const state = new OptimisticState(createThreadState("thread-1"));
+
+    let threadDataMissingDuringNotify = false;
+
+    state.subscribe(() => {
+      const threadData = getThreadData(state.value, "thread-1");
+      if (threadData === undefined) {
+        threadDataMissingDuringNotify = true;
+      }
+    });
+
+    await state.optimisticUpdate({
+      execute: async () => undefined,
+      optimistic: (s) => {
+        return updateStatusReducer(s, "thread-1", "archived");
+      },
+    });
+
+    // Archive keeps threadData — no SKIP_UPDATE, no crash
+    expect(threadDataMissingDuringNotify).toBe(false);
+    expect(getThreadData(state.value, "thread-1")).toBeDefined();
+    expect(getThreadData(state.value, "thread-1")?.status).toBe("archived");
+  });
+});

package/src/types/attachment.ts

@@ -0,0 +1,45 @@
+import type { ThreadUserMessagePart } from "./message";
+
+export type PendingAttachmentStatus =
+  | {
+      type: "running";
+      reason: "uploading";
+      progress: number;
+    }
+  | {
+      type: "requires-action";
+      reason: "composer-send";
+    }
+  | {
+      type: "incomplete";
+      reason: "error" | "upload-paused";
+    };
+
+export type CompleteAttachmentStatus = {
+  type: "complete";
+};
+
+export type AttachmentStatus =
+  | PendingAttachmentStatus
+  | CompleteAttachmentStatus;
+
+type BaseAttachment = {
+  id: string;
+  type: "image" | "document" | "file";
+  name: string;
+  contentType: string;
+  file?: File;
+  content?: ThreadUserMessagePart[];
+};
+
+export type PendingAttachment = BaseAttachment & {
+  status: PendingAttachmentStatus;
+  file: File;
+};
+
+export type CompleteAttachment = BaseAttachment & {
+  status: CompleteAttachmentStatus;
+  content: ThreadUserMessagePart[];
+};
+
+export type Attachment = PendingAttachment | CompleteAttachment;

package/src/types/index.ts

@@ -0,0 +1,39 @@
+export type {
+  // Message parts
+  TextMessagePart,
+  ReasoningMessagePart,
+  SourceMessagePart,
+  ImageMessagePart,
+  FileMessagePart,
+  DataMessagePart,
+  Unstable_AudioMessagePart,
+  ToolCallMessagePart,
+  ThreadUserMessagePart,
+  ThreadAssistantMessagePart,
+  // Message status
+  MessagePartStatus,
+  ToolCallMessagePartStatus,
+  MessageStatus,
+  // Thread messages
+  MessageTiming,
+  ThreadStep,
+  ThreadSystemMessage,
+  ThreadUserMessage,
+  ThreadAssistantMessage,
+  ThreadMessage,
+  MessageRole,
+  // Config
+  RunConfig,
+  AppendMessage,
+} from "./message";
+
+export type {
+  Attachment,
+  PendingAttachment,
+  CompleteAttachment,
+  AttachmentStatus,
+} from "./attachment";
+
+export type { Unsubscribe } from "./unsubscribe";
+
+export type { QuoteInfo } from "./quote";

package/src/types/message.ts

@@ -0,0 +1,248 @@
+import type {
+  ReadonlyJSONObject,
+  ReadonlyJSONValue,
+} from "assistant-stream/utils";
+import type { CompleteAttachment } from "./attachment";
+
+// =============================================================================
+// Message Parts
+// =============================================================================
+
+export type TextMessagePart = {
+  readonly type: "text";
+  readonly text: string;
+  readonly parentId?: string;
+};
+
+export type ReasoningMessagePart = {
+  readonly type: "reasoning";
+  readonly text: string;
+  readonly parentId?: string;
+};
+
+export type SourceMessagePart = {
+  readonly type: "source";
+  readonly sourceType: "url";
+  readonly id: string;
+  readonly url: string;
+  readonly title?: string;
+  readonly parentId?: string;
+};
+
+export type ImageMessagePart = {
+  readonly type: "image";
+  readonly image: string;
+  readonly filename?: string;
+};
+
+export type FileMessagePart = {
+  readonly type: "file";
+  readonly filename?: string;
+  readonly data: string;
+  readonly mimeType: string;
+};
+
+export type Unstable_AudioMessagePart = {
+  readonly type: "audio";
+  readonly audio: {
+    readonly data: string;
+    readonly format: "mp3" | "wav";
+  };
+};
+
+export type DataMessagePart<T = any> = {
+  readonly type: "data";
+  readonly name: string;
+  readonly data: T;
+};
+
+export type ToolCallMessagePart<
+  TArgs = ReadonlyJSONObject,
+  TResult = unknown,
+> = {
+  readonly type: "tool-call";
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly args: TArgs;
+  readonly result?: TResult | undefined;
+  readonly isError?: boolean | undefined;
+  readonly argsText: string;
+  readonly artifact?: unknown;
+  readonly interrupt?: { type: "human"; payload: unknown };
+  readonly parentId?: string;
+  readonly messages?: readonly ThreadMessage[];
+};
+
+export type ThreadUserMessagePart =
+  | TextMessagePart
+  | ImageMessagePart
+  | FileMessagePart
+  | DataMessagePart
+  | Unstable_AudioMessagePart;
+
+export type ThreadAssistantMessagePart =
+  | TextMessagePart
+  | ReasoningMessagePart
+  | ToolCallMessagePart
+  | SourceMessagePart
+  | FileMessagePart
+  | ImageMessagePart
+  | DataMessagePart;
+
+// =============================================================================
+// Message Status
+// =============================================================================
+
+export type MessagePartStatus =
+  | {
+      readonly type: "running";
+    }
+  | {
+      readonly type: "complete";
+    }
+  | {
+      readonly type: "incomplete";
+      readonly reason:
+        | "cancelled"
+        | "length"
+        | "content-filter"
+        | "other"
+        | "error";
+      readonly error?: unknown;
+    };
+
+export type ToolCallMessagePartStatus =
+  | {
+      readonly type: "requires-action";
+      readonly reason: "interrupt";
+    }
+  | MessagePartStatus;
+
+export type MessageStatus =
+  | {
+      readonly type: "running";
+    }
+  | {
+      readonly type: "requires-action";
+      readonly reason: "tool-calls" | "interrupt";
+    }
+  | {
+      readonly type: "complete";
+      readonly reason: "stop" | "unknown";
+    }
+  | {
+      readonly type: "incomplete";
+      readonly reason:
+        | "cancelled"
+        | "tool-calls"
+        | "length"
+        | "content-filter"
+        | "other"
+        | "error";
+      readonly error?: ReadonlyJSONValue;
+    };
+
+// =============================================================================
+// Thread Messages
+// =============================================================================
+
+export type MessageTiming = {
+  readonly streamStartTime: number;
+  readonly firstTokenTime?: number;
+  readonly totalStreamTime?: number;
+  readonly tokenCount?: number;
+  readonly tokensPerSecond?: number;
+  readonly totalChunks: number;
+  readonly toolCallCount: number;
+};
+
+export type ThreadStep = {
+  readonly messageId?: string;
+  readonly usage?:
+    | {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+      }
+    | undefined;
+};
+
+type MessageCommonProps = {
+  readonly id: string;
+  readonly createdAt: Date;
+};
+
+export type ThreadSystemMessage = MessageCommonProps & {
+  readonly role: "system";
+  readonly content: readonly [TextMessagePart];
+  readonly metadata: {
+    readonly unstable_state?: undefined;
+    readonly unstable_annotations?: undefined;
+    readonly unstable_data?: undefined;
+    readonly steps?: undefined;
+    readonly submittedFeedback?: undefined;
+    readonly timing?: undefined;
+    readonly custom: Record<string, unknown>;
+  };
+};
+
+export type ThreadUserMessage = MessageCommonProps & {
+  readonly role: "user";
+  readonly content: readonly ThreadUserMessagePart[];
+  readonly attachments: readonly CompleteAttachment[];
+  readonly metadata: {
+    readonly unstable_state?: undefined;
+    readonly unstable_annotations?: undefined;
+    readonly unstable_data?: undefined;
+    readonly steps?: undefined;
+    readonly submittedFeedback?: undefined;
+    readonly timing?: undefined;
+    readonly custom: Record<string, unknown>;
+  };
+};
+
+export type ThreadAssistantMessage = MessageCommonProps & {
+  readonly role: "assistant";
+  readonly content: readonly ThreadAssistantMessagePart[];
+  readonly status: MessageStatus;
+  readonly metadata: {
+    readonly unstable_state: ReadonlyJSONValue;
+    readonly unstable_annotations: readonly ReadonlyJSONValue[];
+    readonly unstable_data: readonly ReadonlyJSONValue[];
+    readonly steps: readonly ThreadStep[];
+    readonly submittedFeedback?: { readonly type: "positive" | "negative" };
+    readonly timing?: MessageTiming;
+    readonly custom: Record<string, unknown>;
+  };
+};
+
+type BaseThreadMessage = {
+  readonly status?: ThreadAssistantMessage["status"];
+  readonly metadata: {
+    readonly unstable_state?: ReadonlyJSONValue;
+    readonly unstable_annotations?: readonly ReadonlyJSONValue[];
+    readonly unstable_data?: readonly ReadonlyJSONValue[];
+    readonly steps?: readonly ThreadStep[];
+    readonly submittedFeedback?: { readonly type: "positive" | "negative" };
+    readonly timing?: MessageTiming;
+    readonly custom: Record<string, unknown>;
+  };
+  readonly attachments?: ThreadUserMessage["attachments"];
+};
+
+export type ThreadMessage = BaseThreadMessage &
+  (ThreadSystemMessage | ThreadUserMessage | ThreadAssistantMessage);
+
+export type MessageRole = ThreadMessage["role"];
+
+export type RunConfig = {
+  readonly custom?: Record<string, unknown>;
+};
+
+export type AppendMessage = Omit<ThreadMessage, "id"> & {
+  parentId: string | null;
+
+  /** The ID of the message that was edited or undefined. */
+  sourceId: string | null;
+  runConfig: RunConfig | undefined;
+  startRun?: boolean | undefined;
+};

package/src/types/quote.ts

@@ -0,0 +1,4 @@
+export type QuoteInfo = {
+  readonly text: string;
+  readonly messageId: string;
+};

package/src/types/unsubscribe.ts

@@ -0,0 +1 @@
+export type Unsubscribe = () => void;

package/src/utils/composite-context-provider.ts

@@ -0,0 +1,36 @@
+import {
+  type ModelContextProvider,
+  mergeModelContexts,
+} from "../model-context";
+
+export class CompositeContextProvider implements ModelContextProvider {
+  private _providers = new Set<ModelContextProvider>();
+
+  getModelContext() {
+    return mergeModelContexts(this._providers);
+  }
+
+  registerModelContextProvider(provider: ModelContextProvider) {
+    this._providers.add(provider);
+    const unsubscribe = provider.subscribe?.(() => {
+      this.notifySubscribers();
+    });
+    this.notifySubscribers();
+    return () => {
+      this._providers.delete(provider);
+      unsubscribe?.();
+      this.notifySubscribers();
+    };
+  }
+
+  private _subscribers = new Set<() => void>();
+
+  notifySubscribers() {
+    for (const callback of this._subscribers) callback();
+  }
+
+  subscribe(callback: () => void) {
+    this._subscribers.add(callback);
+    return () => this._subscribers.delete(callback);
+  }
+}

package/src/utils/id.ts

@@ -0,0 +1,14 @@
+import { customAlphabet } from "nanoid/non-secure";
+
+export const generateId = customAlphabet(
+  "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
+  7,
+);
+
+const optimisticPrefix = "__optimistic__";
+export const generateOptimisticId = () => `${optimisticPrefix}${generateId()}`;
+export const isOptimisticId = (id: string) => id.startsWith(optimisticPrefix);
+
+const errorPrefix = "__error__";
+export const generateErrorMessageId = () => `${errorPrefix}${generateId()}`;
+export const isErrorMessageId = (id: string) => id.startsWith(errorPrefix);

package/src/utils/index.ts

@@ -0,0 +1,14 @@
+// ID generation
+export {
+  generateId,
+  generateOptimisticId,
+  isOptimisticId,
+  generateErrorMessageId,
+  isErrorMessageId,
+} from "./id";
+
+// Message utilities
+export { getThreadMessageText } from "./text";
+
+// Composite context provider
+export { CompositeContextProvider } from "./composite-context-provider";

package/src/utils/text.ts

@@ -0,0 +1,11 @@
+import type { AppendMessage, TextMessagePart, ThreadMessage } from "../types";
+
+export const getThreadMessageText = (
+  message: ThreadMessage | AppendMessage,
+) => {
+  const textParts = message.content.filter(
+    (part) => part.type === "text",
+  ) as TextMessagePart[];
+
+  return textParts.map((part) => part.text).join("\n\n");
+};