@assistant-ui/core 0.1.7 → 0.1.8

package/src/store/scopes/composer.ts

@@ -5,6 +5,15 @@ import type { RunConfig } from "../../types/message";
 import type { ComposerRuntime } from "../../runtime/api/composer-runtime";
 import type { DictationState } from "../../runtime/interfaces/composer-runtime-core";
 import type { AttachmentMethods } from "./attachment";
+import type { QueueItemState, QueueItemMethods } from "./queue-item";
+
+export type ComposerSendOptions = {
+  /**
+   * Whether to steer (interrupt the current run and process this message immediately).
+   * When false (default), the message is queued and processed in order.
+   */
+  steer?: boolean;
+};
 
 export type ComposerState = {
   readonly text: string;
@@ -28,6 +37,12 @@ export type ComposerState = {
    * Undefined when no quote is set.
    */
   readonly quote: QuoteInfo | undefined;
+
+  /**
+   * The queue of messages waiting to be processed.
+   * Empty when no messages are queued.
+   */
+  readonly queue: readonly QueueItemState[];
 };
 
 export type ComposerMethods = {
@@ -39,7 +54,7 @@ export type ComposerMethods = {
   clearAttachments(): Promise<void>;
   attachment(selector: { index: number } | { id: string }): AttachmentMethods;
   reset(): Promise<void>;
-  send(): void;
+  send(opts?: ComposerSendOptions): void;
   cancel(): void;
   beginEdit(): void;
 
@@ -59,6 +74,11 @@ export type ComposerMethods = {
    */
   setQuote(quote: QuoteInfo | undefined): void;
 
+  /**
+   * Access a queue item by index.
+   */
+  queueItem(selector: { index: number }): QueueItemMethods;
+
   __internal_getRuntime?(): ComposerRuntime;
 };
 

package/src/store/scopes/queue-item.ts

@@ -0,0 +1,20 @@
+export type QueueItemState = {
+  readonly id: string;
+  readonly prompt: string;
+};
+
+export type QueueItemMethods = {
+  getState(): QueueItemState;
+  steer(): void;
+  remove(): void;
+};
+
+export type QueueItemMeta = {
+  source: "composer";
+  query: { index: number };
+};
+
+export type QueueItemClientSchema = {
+  methods: QueueItemMethods;
+  meta: QueueItemMeta;
+};

package/src/tests/OptimisticState-list-race.test.ts

@@ -0,0 +1,256 @@
+import { describe, it, expect } from "vitest";
+import { OptimisticState } from "../runtimes/remote-thread-list/optimistic-state";
+import {
+  type RemoteThreadState,
+  type RemoteThreadData,
+  type THREAD_MAPPING_ID,
+  createThreadMappingId,
+  updateStatusReducer,
+} from "../runtimes/remote-thread-list/remote-thread-state";
+
+/**
+ * Reproduces the race condition where a stale list() response
+ * re-introduces a thread that was deleted/archived while the list
+ * was in flight.
+ *
+ * Root cause (before fix): OptimisticState's `then` callback could
+ * overwrite `_baseValue`, erasing effects from transforms that had
+ * already completed. The fix re-applies completed `optimistic`
+ * callbacks after every `then`.
+ */
+
+const EMPTY_STATE: RemoteThreadState = {
+  isLoading: false,
+  newThreadId: undefined,
+  threadIds: [],
+  archivedThreadIds: [],
+  threadIdMap: {},
+  threadData: {},
+};
+
+type ListResult = {
+  threads: {
+    remoteId: string;
+    status: "regular" | "archived";
+    title?: string;
+    externalId?: string | undefined;
+  }[];
+};
+
+/** Simulates getLoadThreadsPromise's then callback (plain version, no workarounds). */
+const applyListResult = (
+  state: RemoteThreadState,
+  l: ListResult,
+): RemoteThreadState => {
+  const newThreadIds: string[] = [];
+  const newArchivedThreadIds: string[] = [];
+  const newThreadIdMap = {} as Record<string, THREAD_MAPPING_ID>;
+  const newThreadData = {} as Record<THREAD_MAPPING_ID, RemoteThreadData>;
+
+  for (const thread of l.threads) {
+    if (thread.status === "regular") newThreadIds.push(thread.remoteId);
+    else newArchivedThreadIds.push(thread.remoteId);
+
+    const mappingId = createThreadMappingId(thread.remoteId);
+    newThreadIdMap[thread.remoteId] = mappingId;
+    newThreadData[mappingId] = {
+      id: thread.remoteId,
+      remoteId: thread.remoteId,
+      externalId: thread.externalId,
+      status: thread.status,
+      title: thread.title,
+      initializeTask: Promise.resolve({
+        remoteId: thread.remoteId,
+        externalId: thread.externalId,
+      }),
+    };
+  }
+
+  return {
+    ...state,
+    threadIds: newThreadIds,
+    archivedThreadIds: newArchivedThreadIds,
+    threadIdMap: { ...state.threadIdMap, ...newThreadIdMap },
+    threadData: { ...state.threadData, ...newThreadData },
+  };
+};
+
+/** Creates a deferred promise for controlling resolution order. */
+function deferred<T>() {
+  let resolve!: (v: T) => void;
+  const promise = new Promise<T>((r) => {
+    resolve = r;
+  });
+  return { promise, resolve };
+}
+
+describe("list + delete race condition", () => {
+  it("stale list() does not re-add a thread deleted while list was in flight", async () => {
+    const state = new OptimisticState<RemoteThreadState>(EMPTY_STATE);
+
+    const listDeferred = deferred<ListResult>();
+    const deleteDeferred = deferred<void>();
+
+    // 1. list() starts
+    const listPromise = state.optimisticUpdate({
+      execute: () => listDeferred.promise,
+      loading: (s) => ({ ...s, isLoading: true }),
+      then: applyListResult,
+    });
+
+    // 2. delete starts (while list is in flight)
+    const deletePromise = state.optimisticUpdate({
+      execute: () => deleteDeferred.promise,
+      optimistic: (s) => updateStatusReducer(s, "thread-A", "deleted"),
+    });
+
+    // 3. DELETE resolves first
+    deleteDeferred.resolve();
+    await deletePromise;
+
+    // 4. list resolves with stale data that includes deleted thread
+    listDeferred.resolve({
+      threads: [{ remoteId: "thread-A", status: "regular", title: "A" }],
+    });
+    await listPromise;
+
+    // Thread A must NOT reappear
+    expect(state.value.threadIds).not.toContain("thread-A");
+    expect(
+      state.value.threadData[createThreadMappingId("thread-A")],
+    ).toBeUndefined();
+  });
+
+  it("stale list() does not revert archive back to regular", async () => {
+    // Start with thread A already in state
+    const mappingId = createThreadMappingId("thread-A");
+    const initial: RemoteThreadState = {
+      ...EMPTY_STATE,
+      threadIds: ["thread-A"],
+      threadIdMap: { "thread-A": mappingId },
+      threadData: {
+        [mappingId]: {
+          id: "thread-A",
+          remoteId: "thread-A",
+          externalId: undefined,
+          status: "regular",
+          title: "A",
+          initializeTask: Promise.resolve({
+            remoteId: "thread-A",
+            externalId: undefined,
+          }),
+        },
+      },
+    };
+
+    const state = new OptimisticState<RemoteThreadState>(initial);
+
+    const listDeferred = deferred<ListResult>();
+    const archiveDeferred = deferred<void>();
+
+    // 1. list() starts
+    const listPromise = state.optimisticUpdate({
+      execute: () => listDeferred.promise,
+      loading: (s) => ({ ...s, isLoading: true }),
+      then: applyListResult,
+    });
+
+    // 2. archive starts
+    const archivePromise = state.optimisticUpdate({
+      execute: () => archiveDeferred.promise,
+      optimistic: (s) => updateStatusReducer(s, "thread-A", "archived"),
+    });
+
+    // 3. archive resolves first
+    archiveDeferred.resolve();
+    await archivePromise;
+
+    // 4. list resolves with stale data (thread-A as regular)
+    listDeferred.resolve({
+      threads: [{ remoteId: "thread-A", status: "regular", title: "A" }],
+    });
+    await listPromise;
+
+    // Thread A should remain archived, NOT be reverted to regular
+    expect(state.value.threadIds).not.toContain("thread-A");
+    expect(state.value.archivedThreadIds).toContain("thread-A");
+    expect(
+      state.value.threadData[createThreadMappingId("thread-A")]?.status,
+    ).toBe("archived");
+  });
+
+  it("threads NOT modified during list() are loaded normally", async () => {
+    const state = new OptimisticState<RemoteThreadState>(EMPTY_STATE);
+
+    const listDeferred = deferred<ListResult>();
+    const deleteDeferred = deferred<void>();
+
+    // 1. list() starts
+    const listPromise = state.optimisticUpdate({
+      execute: () => listDeferred.promise,
+      loading: (s) => ({ ...s, isLoading: true }),
+      then: applyListResult,
+    });
+
+    // 2. delete thread A (while list is in flight)
+    const deletePromise = state.optimisticUpdate({
+      execute: () => deleteDeferred.promise,
+      optimistic: (s) => updateStatusReducer(s, "thread-A", "deleted"),
+    });
+
+    deleteDeferred.resolve();
+    await deletePromise;
+
+    // 3. list resolves with [A, B] — A should be filtered, B should load
+    listDeferred.resolve({
+      threads: [
+        { remoteId: "thread-A", status: "regular", title: "A" },
+        { remoteId: "thread-B", status: "regular", title: "B" },
+      ],
+    });
+    await listPromise;
+
+    expect(state.value.threadIds).toEqual(["thread-B"]);
+    expect(state.value.threadIds).not.toContain("thread-A");
+    expect(
+      state.value.threadData[createThreadMappingId("thread-B")],
+    ).toBeDefined();
+  });
+
+  it("list resolves before delete — no race, both work correctly", async () => {
+    const state = new OptimisticState<RemoteThreadState>(EMPTY_STATE);
+
+    const listDeferred = deferred<ListResult>();
+    const deleteDeferred = deferred<void>();
+
+    const listPromise = state.optimisticUpdate({
+      execute: () => listDeferred.promise,
+      loading: (s) => ({ ...s, isLoading: true }),
+      then: applyListResult,
+    });
+
+    const deletePromise = state.optimisticUpdate({
+      execute: () => deleteDeferred.promise,
+      optimistic: (s) => updateStatusReducer(s, "thread-A", "deleted"),
+    });
+
+    // list resolves FIRST this time
+    listDeferred.resolve({
+      threads: [{ remoteId: "thread-A", status: "regular", title: "A" }],
+    });
+    await listPromise;
+
+    // thread A is in base state now, but delete's optimistic still hides it
+    expect(state.value.threadIds).not.toContain("thread-A");
+
+    // delete resolves
+    deleteDeferred.resolve();
+    await deletePromise;
+
+    // thread A is gone from both base and cached
+    expect(state.value.threadIds).not.toContain("thread-A");
+    expect(
+      state.value.threadData[createThreadMappingId("thread-A")],
+    ).toBeUndefined();
+  });
+});

package/src/tests/mention-formatter.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from "vitest";
+import { unstable_defaultDirectiveFormatter } from "../adapters/mention";
+
+describe("unstable_defaultDirectiveFormatter", () => {
+  describe("serialize", () => {
+    it("serializes with id === label (no name attr)", () => {
+      expect(
+        unstable_defaultDirectiveFormatter.serialize({
+          id: "weather",
+          type: "tool",
+          label: "weather",
+        }),
+      ).toBe(":tool[weather]");
+    });
+
+    it("serializes with id !== label (includes name attr)", () => {
+      expect(
+        unstable_defaultDirectiveFormatter.serialize({
+          id: "get_weather",
+          type: "tool",
+          label: "Weather",
+        }),
+      ).toBe(":tool[Weather]{name=get_weather}");
+    });
+  });
+
+  describe("parse", () => {
+    it("parses plain text", () => {
+      expect(unstable_defaultDirectiveFormatter.parse("hello world")).toEqual([
+        { kind: "text", text: "hello world" },
+      ]);
+    });
+
+    it("parses a single directive without name attr", () => {
+      expect(
+        unstable_defaultDirectiveFormatter.parse("use :tool[weather] please"),
+      ).toEqual([
+        { kind: "text", text: "use " },
+        { kind: "mention", type: "tool", label: "weather", id: "weather" },
+        { kind: "text", text: " please" },
+      ]);
+    });
+
+    it("parses a directive with name attr", () => {
+      expect(
+        unstable_defaultDirectiveFormatter.parse(
+          ":tool[Weather]{name=get_weather}",
+        ),
+      ).toEqual([
+        {
+          kind: "mention",
+          type: "tool",
+          label: "Weather",
+          id: "get_weather",
+        },
+      ]);
+    });
+
+    it("parses multiple directives in text", () => {
+      const result = unstable_defaultDirectiveFormatter.parse(
+        ":tool[a] and :tool[b]{name=bb}",
+      );
+      expect(result).toHaveLength(3);
+      expect(result[0]).toEqual({
+        kind: "mention",
+        type: "tool",
+        label: "a",
+        id: "a",
+      });
+      expect(result[1]).toEqual({ kind: "text", text: " and " });
+      expect(result[2]).toEqual({
+        kind: "mention",
+        type: "tool",
+        label: "b",
+        id: "bb",
+      });
+    });
+
+    it("parses hyphenated types", () => {
+      expect(
+        unstable_defaultDirectiveFormatter.parse(
+          ":data-source[My DB]{name=db_1}",
+        ),
+      ).toEqual([
+        {
+          kind: "mention",
+          type: "data-source",
+          label: "My DB",
+          id: "db_1",
+        },
+      ]);
+    });
+
+    it("roundtrips serialize → parse", () => {
+      const item = {
+        id: "get_weather",
+        type: "tool",
+        label: "Weather",
+      };
+      const serialized = unstable_defaultDirectiveFormatter.serialize(item);
+      const parsed = unstable_defaultDirectiveFormatter.parse(serialized);
+      expect(parsed).toEqual([
+        {
+          kind: "mention",
+          type: "tool",
+          label: "Weather",
+          id: "get_weather",
+        },
+      ]);
+    });
+  });
+});

package/src/types/index.ts

@@ -0,0 +1,47 @@
+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,
+  CreateAttachment,
+} from "./attachment";
+
+export type { Unsubscribe } from "./unsubscribe";
+
+export type { QuoteInfo } from "./quote";
+
+export type {
+  Unstable_MentionItem,
+  Unstable_MentionCategory,
+  Unstable_DirectiveSegment,
+  Unstable_DirectiveFormatter,
+} from "./mention";

package/src/types/mention.ts

@@ -0,0 +1,50 @@
+import type { ReadonlyJSONObject } from "assistant-stream/utils";
+
+// =============================================================================
+// Mention Item (user-facing definition for items that can be @-mentioned)
+// =============================================================================
+
+export type Unstable_MentionItem = {
+  readonly id: string;
+  readonly type: string;
+  readonly label: string;
+  readonly icon?: string | undefined;
+  readonly description?: string | undefined;
+  readonly metadata?: ReadonlyJSONObject | undefined;
+};
+
+// =============================================================================
+// Mention Category (for hierarchical navigation)
+// =============================================================================
+
+export type Unstable_MentionCategory = {
+  readonly id: string;
+  readonly label: string;
+  readonly icon?: string | undefined;
+};
+
+// =============================================================================
+// Directive Segment (parsed representation of mention directives in text)
+// =============================================================================
+
+/** Parsed segment from directive text */
+export type Unstable_DirectiveSegment =
+  | { readonly kind: "text"; readonly text: string }
+  | {
+      readonly kind: "mention";
+      readonly type: string;
+      readonly label: string;
+      readonly id: string;
+    };
+
+// =============================================================================
+// Directive Formatter (configurable serialization/parsing for mentions)
+// =============================================================================
+
+/** Configurable formatter for mention directive serialization/parsing */
+export type Unstable_DirectiveFormatter = {
+  /** Serialize a mention item to directive text */
+  serialize(item: Unstable_MentionItem): string;
+  /** Parse text into alternating text and mention segments */
+  parse(text: string): readonly Unstable_DirectiveSegment[];
+};