@assistant-ui/core 0.1.5 → 0.1.8

package/src/store/scope-registration.ts

@@ -9,6 +9,7 @@ import type { ModelContextClientSchema } from "./scopes/model-context";
 import type { SuggestionsClientSchema } from "./scopes/suggestions";
 import type { SuggestionClientSchema } from "./scopes/suggestion";
 import type { ChainOfThoughtClientSchema } from "./scopes/chain-of-thought";
+import type { QueueItemClientSchema } from "./scopes/queue-item";
 
 declare module "@assistant-ui/store" {
   interface ScopeRegistry {
@@ -23,5 +24,6 @@ declare module "@assistant-ui/store" {
     suggestions: SuggestionsClientSchema;
     suggestion: SuggestionClientSchema;
     chainOfThought: ChainOfThoughtClientSchema;
+    queueItem: QueueItemClientSchema;
   }
 }

package/src/store/scopes/attachment.ts

@@ -1,5 +1,5 @@
-import type { Attachment } from "../../types";
-import type { AttachmentRuntime } from "../../runtime";
+import type { Attachment } from "../../types/attachment";
+import type { AttachmentRuntime } from "../../runtime/api/attachment-runtime";
 
 export type AttachmentState = Attachment;
 

package/src/store/scopes/chain-of-thought.ts

@@ -1,4 +1,5 @@
-import type { MessagePartStatus, ToolCallMessagePartStatus } from "../../types";
+import type { ToolCallMessagePartStatus } from "../../types/message";
+import type { MessagePartStatus } from "../../types/message";
 import type { PartMethods, PartState } from "./part";
 
 export type ChainOfThoughtPart = Extract<

package/src/store/scopes/composer.ts

@@ -1,12 +1,19 @@
-import type {
-  Attachment,
-  CreateAttachment,
-  MessageRole,
-  RunConfig,
-  QuoteInfo,
-} from "../../types";
-import type { ComposerRuntime, DictationState } from "../../runtime";
+import type { Attachment, CreateAttachment } from "../../types/attachment";
+import type { MessageRole } from "../../types/message";
+import type { QuoteInfo } from "../../types/quote";
+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;
@@ -30,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 = {
@@ -41,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;
 
@@ -61,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/message.ts

@@ -1,9 +1,10 @@
-import type { ThreadMessage, RunConfig } from "../../types";
+import type { ThreadMessage } from "../../types/message";
+import type { RunConfig } from "../../types/message";
 import type {
   SpeechState,
   SubmittedFeedback,
-  MessageRuntime,
-} from "../../runtime";
+} from "../../runtime/interfaces/thread-runtime-core";
+import type { MessageRuntime } from "../../runtime/api/message-runtime";
 import type { ComposerMethods, ComposerState } from "./composer";
 import type { PartMethods, PartState } from "./part";
 import type { AttachmentMethods } from "./attachment";

package/src/store/scopes/model-context.ts

@@ -1,5 +1,5 @@
-import type { Unsubscribe } from "../../types";
-import type { ModelContextProvider } from "../../model-context";
+import type { Unsubscribe } from "../../types/unsubscribe";
+import type { ModelContextProvider } from "../../model-context/types";
 
 export type ModelContextState = Record<string, never>;
 

package/src/store/scopes/part.ts

@@ -2,10 +2,10 @@ import type { ToolResponse } from "assistant-stream";
 import type {
   ThreadUserMessagePart,
   ThreadAssistantMessagePart,
-  MessagePartStatus,
   ToolCallMessagePartStatus,
-} from "../../types";
-import type { MessagePartRuntime } from "../../runtime";
+} from "../../types/message";
+import type { MessagePartStatus } from "../../types/message";
+import type { MessagePartRuntime } from "../../runtime/api/message-part-runtime";
 
 export type PartState = (ThreadUserMessagePart | ThreadAssistantMessagePart) & {
   readonly status: MessagePartStatus | ToolCallMessagePartStatus;

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/store/scopes/thread-list-item.ts

@@ -1,7 +1,5 @@
-import type {
-  ThreadListItemRuntime,
-  ThreadListItemStatus,
-} from "../../runtime";
+import type { ThreadListItemRuntime } from "../../runtime/api/thread-list-item-runtime";
+import type { ThreadListItemStatus } from "../../runtime/interfaces/thread-list-runtime-core";
 
 export type ThreadListItemState = {
   readonly id: string;

package/src/store/scopes/thread.ts

@@ -3,14 +3,16 @@ import type {
   RuntimeCapabilities,
   SpeechState,
   ThreadSuggestion,
-  ExportedMessageRepository,
-  ThreadMessageLike,
+} from "../../runtime/interfaces/thread-runtime-core";
+import type { ExportedMessageRepository } from "../../runtime/utils/message-repository";
+import type { ThreadMessageLike } from "../../runtime/utils/thread-message-like";
+import type {
   CreateAppendMessage,
   CreateStartRunConfig,
   CreateResumeRunConfig,
   ThreadRuntime,
-} from "../../runtime";
-import type { ModelContext } from "../../model-context";
+} from "../../runtime/api/thread-runtime";
+import type { ModelContext } from "../../model-context/types";
 import type { MessageMethods, MessageState } from "./message";
 import type { ComposerMethods, ComposerState } from "./composer";
 
@@ -92,6 +94,11 @@ export type ThreadMethods = {
    * Resume a run with the given configuration.
    * @param config The configuration for resuming the run
    */
+  resumeRun(config: CreateResumeRunConfig): void;
+
+  /**
+   * @deprecated Use `resumeRun` instead.
+   */
   unstable_resumeRun(config: CreateResumeRunConfig): void;
   cancelRun(): void;
   getModelContext(): ModelContext;

package/src/store/scopes/threads.ts

@@ -1,4 +1,4 @@
-import type { AssistantRuntime } from "../../runtime";
+import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 import type {
   ThreadListItemMethods,
   ThreadListItemState,

package/src/subscribable/subscribable.ts

@@ -1,4 +1,4 @@
-import type { Unsubscribe } from "../types";
+import type { Unsubscribe } from "../types/unsubscribe";
 
 // =============================================================================
 // Sentinel

package/src/tests/MessageRepository.test.ts

@@ -3,7 +3,8 @@ import {
   MessageRepository,
   ExportedMessageRepository,
 } from "../runtime/utils/message-repository";
-import type { ThreadMessage, TextMessagePart } from "../types";
+import type { ThreadMessage } from "../types/message";
+import type { TextMessagePart } from "../types/message";
 import type { ThreadMessageLike } from "../runtime/utils/thread-message-like";
 
 // Mock generateId and generateOptimisticId to make tests deterministic

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/external-store-thread-runtime-core.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import { ExternalStoreThreadRuntimeCore } from "../runtimes/external-store/external-store-thread-runtime-core";
 import type { ExternalStoreAdapter } from "../runtimes/external-store/external-store-adapter";
-import type { ModelContextProvider } from "../model-context";
+import type { ModelContextProvider } from "../model-context/types";
 
 const mockContextProvider: ModelContextProvider = {
   getModelContext: () => ({}),

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

@@ -38,3 +38,10 @@ export type {
 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[];
+};

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

@@ -1,7 +1,7 @@
 import {
   type ModelContextProvider,
   mergeModelContexts,
-} from "../model-context";
+} from "../model-context/types";
 
 export class CompositeContextProvider implements ModelContextProvider {
   private _providers = new Set<ModelContextProvider>();