@assistant-ui/core 0.2.10 → 0.2.12

package/src/runtime/api/composer-runtime.ts

@@ -3,6 +3,7 @@ import type { MessageRole } from "../../types/message";
 import type { QuoteInfo } from "../../types/quote";
 import type { Unsubscribe } from "../../types/unsubscribe";
 import type { RunConfig } from "../../types/message";
+import type { QueueItemState } from "../../store/scopes/queue-item";
 import {
   LazyMemoizeSubject,
   EventSubscriptionSubject,
@@ -63,6 +64,9 @@ type BaseComposerState = {
    * Undefined when no quote is set.
    */
   readonly quote: QuoteInfo | undefined;
+
+  /** Messages waiting to be processed. Empty unless the `queue` capability is set. */
+  readonly queue: readonly QueueItemState[];
 };
 
 export type ThreadComposerState = BaseComposerState & {
@@ -97,6 +101,7 @@ const getThreadComposerState = (
     attachmentAccept: runtime?.attachmentAccept ?? "",
     dictation: runtime?.dictation,
     quote: runtime?.quote,
+    queue: runtime?.queue ?? EMPTY_ARRAY,
 
     value: runtime?.text ?? "",
   });
@@ -120,6 +125,7 @@ const getEditComposerState = (
     attachmentAccept: runtime?.attachmentAccept ?? "",
     dictation: runtime?.dictation,
     quote: runtime?.quote,
+    queue: runtime?.queue ?? EMPTY_ARRAY,
 
     parentId: runtime?.parentId ?? null,
     sourceId: runtime?.sourceId ?? null,
@@ -194,6 +200,12 @@ export type ComposerRuntime = {
    */
   cancel(): void;
 
+  /** Promote a queued message so it processes next. */
+  steerQueueItem(queueItemId: string): void;
+
+  /** Remove a queued message. */
+  removeQueueItem(queueItemId: string): void;
+
   /**
    * Listens for changes to the composer state.
    * @param callback The callback to call when the composer state changes.
@@ -251,6 +263,8 @@ export abstract class ComposerRuntimeImpl implements ComposerRuntime {
     this.clearAttachments = this.clearAttachments.bind(this);
     this.send = this.send.bind(this);
     this.cancel = this.cancel.bind(this);
+    this.steerQueueItem = this.steerQueueItem.bind(this);
+    this.removeQueueItem = this.removeQueueItem.bind(this);
     this.setRole = this.setRole.bind(this);
     this.getAttachmentByIndex = this.getAttachmentByIndex.bind(this);
     this.startDictation = this.startDictation.bind(this);
@@ -303,6 +317,18 @@ export abstract class ComposerRuntimeImpl implements ComposerRuntime {
     core.cancel();
   }
 
+  public steerQueueItem(queueItemId: string) {
+    const core = this._core.getState();
+    if (!core) throw new Error("Composer is not available");
+    core.steerQueueItem(queueItemId);
+  }
+
+  public removeQueueItem(queueItemId: string) {
+    const core = this._core.getState();
+    if (!core) throw new Error("Composer is not available");
+    core.removeQueueItem(queueItemId);
+  }
+
   public setRole(role: MessageRole) {
     const core = this._core.getState();
     if (!core) throw new Error("Composer is not available");

package/src/runtime/base/base-composer-runtime-core.ts

@@ -23,6 +23,10 @@ import type {
   SendOptions,
 } from "../interfaces/composer-runtime-core";
 import type { DictationAdapter } from "../../adapters/speech";
+import {
+  EMPTY_QUEUE_ITEMS,
+  type QueueItemState,
+} from "../../store/scopes/queue-item";
 import { generateId } from "../../utils/id";
 
 const isAttachmentComplete = (a: Attachment): a is CompleteAttachment =>
@@ -200,6 +204,13 @@ export abstract class BaseComposerRuntimeCore
     this.handleCancel();
   }
 
+  public get queue(): readonly QueueItemState[] {
+    return EMPTY_QUEUE_ITEMS;
+  }
+
+  public steerQueueItem(_queueItemId: string): void {}
+  public removeQueueItem(_queueItemId: string): void {}
+
   protected abstract handleSend(
     message: Omit<AppendMessage, "parentId" | "sourceId">,
     options?: SendOptions,

package/src/runtime/base/default-thread-composer-runtime-core.ts

@@ -6,6 +6,10 @@ import type {
   ThreadComposerRuntimeCore,
 } from "../interfaces/composer-runtime-core";
 import type { ThreadRuntimeCore } from "../interfaces/thread-runtime-core";
+import {
+  EMPTY_QUEUE_ITEMS,
+  type QueueItemState,
+} from "../../store/scopes/queue-item";
 import { BaseComposerRuntimeCore } from "./base-composer-runtime-core";
 
 export class DefaultThreadComposerRuntimeCore
@@ -21,6 +25,18 @@ export class DefaultThreadComposerRuntimeCore
     return !this.isEmpty && !this.runtime.isSendDisabled;
   }
 
+  public override get queue(): readonly QueueItemState[] {
+    return this.runtime.getQueueItems?.() ?? EMPTY_QUEUE_ITEMS;
+  }
+
+  public override steerQueueItem(queueItemId: string): void {
+    this.runtime.steerQueueItem?.(queueItemId);
+  }
+
+  public override removeQueueItem(queueItemId: string): void {
+    this.runtime.removeQueueItem?.(queueItemId);
+  }
+
   protected getAttachmentAdapter() {
     return this.runtime.adapters?.attachments;
   }
@@ -45,6 +61,7 @@ export class DefaultThreadComposerRuntimeCore
 
   public connect() {
     let lastIsSendDisabled = this.runtime.isSendDisabled;
+    let lastQueue = this.queue;
     return this.runtime.subscribe(() => {
       let changed = false;
       if (this.canCancel !== this.runtime.capabilities.cancel) {
@@ -55,6 +72,10 @@ export class DefaultThreadComposerRuntimeCore
         lastIsSendDisabled = this.runtime.isSendDisabled;
         changed = true;
       }
+      if (lastQueue !== this.queue) {
+        lastQueue = this.queue;
+        changed = true;
+      }
       if (changed) this._notifySubscribers();
     });
   }
@@ -68,6 +89,7 @@ export class DefaultThreadComposerRuntimeCore
       parentId: this.runtime.messages.at(-1)?.id ?? null,
       sourceId: null,
       startRun: options?.startRun,
+      steer: options?.steer,
     });
   }
 

package/src/runtime/interfaces/composer-runtime-core.ts

@@ -4,6 +4,7 @@ import type { Attachment, CreateAttachment } from "../../types/attachment";
 import type { Unsubscribe } from "../../types/unsubscribe";
 import type { RunConfig } from "../../types/message";
 import type { DictationAdapter } from "../../adapters/speech";
+import type { QueueItemState } from "../../store/scopes/queue-item";
 
 export type AttachmentAddErrorReason =
   | "no-adapter"
@@ -45,6 +46,8 @@ export type DictationState = {
 
 export type SendOptions = {
   startRun?: boolean;
+  /** Process this message next; only meaningful with the `queue` capability. */
+  steer?: boolean;
 };
 
 export type ComposerRuntimeCore = Readonly<{
@@ -78,6 +81,10 @@ export type ComposerRuntimeCore = Readonly<{
   send: (options?: SendOptions) => void;
   cancel: () => void;
 
+  queue: readonly QueueItemState[];
+  steerQueueItem: (queueItemId: string) => void;
+  removeQueueItem: (queueItemId: string) => void;
+
   dictation: DictationState | undefined;
   startDictation: () => void;
   stopDictation: () => void;

package/src/runtime/interfaces/thread-runtime-core.ts

@@ -16,6 +16,7 @@ import type {
   EditComposerRuntimeCore,
   ThreadComposerRuntimeCore,
 } from "./composer-runtime-core";
+import type { QueueItemState } from "../../store/scopes/queue-item";
 
 export type RuntimeCapabilities = {
   readonly switchToBranch: boolean;
@@ -169,6 +170,10 @@ export type ThreadRuntimeCore = Readonly<{
   getEditComposer: (messageId: string) => EditComposerRuntimeCore | undefined;
   beginEdit: (messageId: string) => void;
 
+  getQueueItems?: () => readonly QueueItemState[];
+  steerQueueItem?: (queueItemId: string) => void;
+  removeQueueItem?: (queueItemId: string) => void;
+
   speech: SpeechState | undefined;
   voice: VoiceSessionState | undefined;
 

package/src/runtime/queue/external-thread-queue-adapter.ts

@@ -0,0 +1,14 @@
+import type { AppendMessage } from "../../types/message";
+import type { QueueItemState } from "../../store/scopes/queue-item";
+
+/**
+ * The queue surface a runtime exposes so the composer can stay usable during a
+ * run and render the pending messages.
+ */
+export type ExternalThreadQueueAdapter = {
+  items: readonly QueueItemState[];
+  enqueue: (message: AppendMessage, options: { steer: boolean }) => void;
+  steer: (queueItemId: string) => void;
+  remove: (queueItemId: string) => void;
+  clear: (reason: "edit" | "reload" | "cancel-run") => void;
+};

package/src/runtime/queue/message-queue.ts

@@ -0,0 +1,128 @@
+import type { AppendMessage } from "../../types/message";
+import {
+  EMPTY_QUEUE_ITEMS,
+  type QueueItemState,
+} from "../../store/scopes/queue-item";
+import { generateId } from "../../utils/id";
+import { getThreadMessageText } from "../../utils/text";
+import type { ExternalThreadQueueAdapter } from "./external-thread-queue-adapter";
+
+export type MessageQueueDriver = {
+  run: (message: AppendMessage, options: { steer: boolean }) => void;
+  /** When omitted, `steer` degrades to "process next" instead of interrupting. */
+  cancel?: (() => void) | undefined;
+};
+
+export type MessageQueueController = {
+  readonly adapter: ExternalThreadQueueAdapter;
+  /** Mark a run as in flight so concurrent sends buffer; call on the rising edge. */
+  notifyBusy: () => void;
+  /** Advances to the next pending message; call on the run's falling edge. */
+  notifyIdle: () => void;
+  subscribe: (callback: () => void) => () => void;
+};
+
+export const createMessageQueue = (
+  driver: MessageQueueDriver,
+): MessageQueueController => {
+  let items: readonly QueueItemState[] = EMPTY_QUEUE_ITEMS;
+  const messages = new Map<string, AppendMessage>();
+  const subscribers = new Set<() => void>();
+
+  let running = false;
+  // swallow the cancelled run's settle when steering so it does not double-advance
+  let suppressIdle = 0;
+
+  const notify = () => {
+    for (const callback of subscribers) callback();
+  };
+
+  const setItems = (next: readonly QueueItemState[]) => {
+    items = next;
+    adapter.items = next;
+    notify();
+  };
+
+  const advance = () => {
+    if (running || items.length === 0) return;
+    const head = items[0]!;
+    const message = messages.get(head.id);
+    messages.delete(head.id);
+    setItems(items.slice(1));
+    if (!message) return;
+    running = true;
+    driver.run(message, { steer: false });
+  };
+
+  const enqueue = (message: AppendMessage, { steer }: { steer: boolean }) => {
+    const id = generateId();
+    const prompt = getThreadMessageText(message);
+    messages.set(id, message);
+    setItems([...items, { id, prompt }]);
+    if (steer) {
+      steerItem(id);
+    } else {
+      advance();
+    }
+  };
+
+  const steerItem = (queueItemId: string) => {
+    if (!messages.has(queueItemId)) return;
+
+    if (driver.cancel && running) {
+      const message = messages.get(queueItemId)!;
+      messages.delete(queueItemId);
+      setItems(items.filter((item) => item.id !== queueItemId));
+      suppressIdle++;
+      driver.cancel();
+      running = true;
+      driver.run(message, { steer: true });
+      return;
+    }
+
+    const target = items.find((item) => item.id === queueItemId);
+    if (!target) return;
+    setItems([target, ...items.filter((item) => item.id !== queueItemId)]);
+    advance();
+  };
+
+  const remove = (queueItemId: string) => {
+    if (!messages.delete(queueItemId)) return;
+    setItems(items.filter((item) => item.id !== queueItemId));
+  };
+
+  const clear = () => {
+    if (items.length === 0) return;
+    messages.clear();
+    setItems(EMPTY_QUEUE_ITEMS);
+  };
+
+  const adapter: ExternalThreadQueueAdapter = {
+    items,
+    enqueue,
+    steer: steerItem,
+    remove,
+    clear,
+  };
+
+  return {
+    adapter,
+    notifyBusy: () => {
+      running = true;
+    },
+    notifyIdle: () => {
+      if (suppressIdle > 0) {
+        suppressIdle--;
+        return;
+      }
+      running = false;
+      advance();
+    },
+    subscribe: (callback) => {
+      subscribers.add(callback);
+      return () => {
+        subscribers.delete(callback);
+      };
+    },
+  };
+};

package/src/runtimes/external-store/external-store-adapter.ts

@@ -17,6 +17,7 @@ import type {
 import type { ExportedMessageRepository } from "../../runtime/utils/message-repository";
 import type { ReadonlyJSONValue } from "assistant-stream/utils";
 import type { ToolExecutionStatus } from "../tool-invocations/ToolInvocationTracker";
+import type { ExternalThreadQueueAdapter } from "../../runtime/queue/external-thread-queue-adapter";
 
 export type ExternalStoreThreadData<TState extends "regular" | "archived"> = {
   status: TState;
@@ -105,6 +106,8 @@ type ExternalStoreAdapterBase<T> = {
   onExportExternalState?: (() => any) | undefined;
   onLoadExternalState?: ((state: any) => void) | undefined;
   onNew: (message: AppendMessage) => Promise<void>;
+  /** Opt in to message queuing. Typically produced by `createMessageQueue`. */
+  queue?: ExternalThreadQueueAdapter | undefined;
   onEdit?: ((message: AppendMessage) => Promise<void>) | undefined;
   onReload?: // TODO: remove parentId in 0.12.0
     | ((parentId: string | null, config: StartRunConfig) => Promise<void>)

package/src/runtimes/external-store/external-store-thread-runtime-core.ts

@@ -32,6 +32,7 @@ import {
 } from "../../runtime/utils/message-repository";
 import { generateId } from "../../utils/id";
 import { ToolInvocationTracker } from "../tool-invocations/ToolInvocationTracker";
+import { EMPTY_QUEUE_ITEMS } from "../../store/scopes/queue-item";
 
 const EMPTY_ARRAY: readonly ThreadSuggestion[] = Object.freeze([]);
 
@@ -155,7 +156,7 @@ export class ExternalStoreThreadRuntimeCore
       unstable_copy: this._store.unstable_capabilities?.copy !== false,
       attachments: !!this._store.adapters?.attachments,
       feedback: !!this._store.adapters?.feedback,
-      queue: false,
+      queue: this._store.queue !== undefined,
     };
     if (!shallowEqual(this._capabilities, newCapabilities)) {
       this._capabilities = newCapabilities;
@@ -389,6 +390,15 @@ export class ExternalStoreThreadRuntimeCore
   }
 
   public async append(message: AppendMessage): Promise<void> {
+    const isEdit = message.parentId !== (this.messages.at(-1)?.id ?? null);
+
+    // Buffering does not start a run, so the tool-abort below must wait until
+    // the queue flushes. By then the prior run (and its tools) has settled.
+    if (!isEdit && this._store.queue) {
+      this._store.queue.enqueue(message, { steer: message.steer ?? false });
+      return;
+    }
+
     // Auto-abort in-flight client-side tool executions when a new run is
     // about to start. Without this, a tool that finishes after the new turn
     // begins would feed a stale result into `onAddToolResult`, racing with
@@ -399,19 +409,36 @@ export class ExternalStoreThreadRuntimeCore
       await this._toolInvocations?.abort();
     }
 
-    if (message.parentId !== (this.messages.at(-1)?.id ?? null)) {
+    if (isEdit) {
       if (!this._store.onEdit)
         throw new Error("Runtime does not support editing messages.");
+      this._store.queue?.clear("edit");
       await this._store.onEdit(message);
     } else {
       await this._store.onNew(message);
     }
   }
 
+  public getQueueItems() {
+    // The composer reads this during base-thread construction, before the
+    // constructor assigns `_store`, so guard against the unset field.
+    return this._store?.queue?.items ?? EMPTY_QUEUE_ITEMS;
+  }
+
+  public steerQueueItem(queueItemId: string) {
+    this._store?.queue?.steer(queueItemId);
+  }
+
+  public removeQueueItem(queueItemId: string) {
+    this._store?.queue?.remove(queueItemId);
+  }
+
   public async startRun(config: StartRunConfig): Promise<void> {
     if (!this._store.onReload)
       throw new Error("Runtime does not support reloading messages.");
 
+    this._store.queue?.clear("reload");
+
     // Auto-abort in-flight client-side tool executions when a run reloads;
     // any results that land afterward would target a turn that no longer
     // exists. See `append` above for full rationale.
@@ -457,6 +484,8 @@ export class ExternalStoreThreadRuntimeCore
     if (!this._store.onCancel)
       throw new Error("Runtime does not support cancelling runs.");
 
+    this._store.queue?.clear("cancel-run");
+
     // Abort any in-flight client-side tool executions. Fire-and-forget —
     // the abort resolves once executions settle, but we don't gate the
     // cancel on it.

package/src/runtimes/local/local-runtime-options.ts

@@ -26,4 +26,10 @@ export type LocalRuntimeOptionsBase = {
    * Names of tools that are allowed to interrupt the run in order to wait for human/external approval.
    */
   unstable_humanToolNames?: string[] | undefined;
+
+  /**
+   * Opt in to message queuing: a message sent during a run is held in
+   * `composer.queue` and sent once the run settles. Steering runs it next.
+   */
+  unstable_enableMessageQueue?: boolean | undefined;
 };

package/src/runtimes/local/local-thread-runtime-core.ts

@@ -22,6 +22,14 @@ import type {
 } from "../../types/message";
 import type { RunConfig } from "../../types/message";
 import type { ModelContextProvider } from "../../model-context/types";
+import {
+  createMessageQueue,
+  type MessageQueueController,
+} from "../../runtime/queue/message-queue";
+import {
+  EMPTY_QUEUE_ITEMS,
+  type QueueItemState,
+} from "../../store/scopes/queue-item";
 
 class AbortError extends Error {
   override name = "AbortError";
@@ -54,6 +62,9 @@ export class LocalThreadRuntimeCore
 
   private abortController: AbortController | null = null;
 
+  private _queue: MessageQueueController | null = null;
+  private _queueRunInFlight = false;
+
   public readonly isDisabled = false;
   public readonly isSendDisabled = false;
 
@@ -139,6 +150,31 @@ export class LocalThreadRuntimeCore
       hasUpdates = true;
     }
 
+    const canQueue = options.unstable_enableMessageQueue === true;
+    if (canQueue && !this._queue) {
+      this._queue = createMessageQueue({
+        run: (message) => {
+          // release the queue when the dispatch settles, even if it rejects
+          // before reaching startRun's finally, so a failure can't deadlock it
+          this._queueRunInFlight = true;
+          void this._runAppend(message)
+            .finally(() => {
+              this._queueRunInFlight = false;
+              this._queue?.notifyIdle();
+            })
+            .catch(() => {});
+        },
+      });
+      this._queue.subscribe(() => this._notifySubscribers());
+    } else if (!canQueue && this._queue) {
+      this._queue.adapter.clear("cancel-run");
+      this._queue = null;
+    }
+    if (this.capabilities.queue !== canQueue) {
+      this.capabilities.queue = canQueue;
+      hasUpdates = true;
+    }
+
     if (hasUpdates) this._notifySubscribers();
   }
 
@@ -183,6 +219,31 @@ export class LocalThreadRuntimeCore
   }
 
   public async append(message: AppendMessage): Promise<void> {
+    const isTail = message.parentId === (this.messages.at(-1)?.id ?? null);
+    const willRun = message.startRun ?? message.role === "user";
+    if (this._queue && willRun && isTail) {
+      this._queue.adapter.enqueue(message, { steer: message.steer ?? false });
+      return;
+    }
+    if (this._queue && !isTail) this._queue.adapter.clear("edit");
+    return this._runAppend(message);
+  }
+
+  public getQueueItems(): readonly QueueItemState[] {
+    // Reads can arrive during base-thread construction, before the queue field
+    // is assigned, so guard against the unset field.
+    return this._queue?.adapter.items ?? EMPTY_QUEUE_ITEMS;
+  }
+
+  public steerQueueItem(queueItemId: string): void {
+    this._queue?.adapter.steer(queueItemId);
+  }
+
+  public removeQueueItem(queueItemId: string): void {
+    this._queue?.adapter.remove(queueItemId);
+  }
+
+  private async _runAppend(message: AppendMessage): Promise<void> {
     this.ensureInitialized();
 
     const initPromise = this._getInitializePromise?.();
@@ -254,6 +315,8 @@ export class LocalThreadRuntimeCore
     this._notifyEventSubscribers("runStart", {});
 
     try {
+      // mark busy for runs not started through the queue (regenerate, resume)
+      this._queue?.notifyBusy();
       this._suggestions = [];
       this._suggestionsController?.abort();
       this._suggestionsController = null;
@@ -270,6 +333,11 @@ export class LocalThreadRuntimeCore
       } while (shouldContinue(message, this._options.unstable_humanToolNames));
     } finally {
       this._notifyEventSubscribers("runEnd", {});
+      // queue-driven runs release from the driver settle handler; a direct
+      // run (regenerate, resume) releases here
+      if (!this._queueRunInFlight) {
+        queueMicrotask(() => this._queue?.notifyIdle());
+      }
     }
 
     this._suggestionsController = new AbortController();
@@ -474,12 +542,14 @@ export class LocalThreadRuntimeCore
   }
 
   public detach() {
+    this._queue?.adapter.clear("cancel-run");
     const error = new AbortError(true);
     this.abortController?.abort(error);
     this.abortController = null;
   }
 
   public cancelRun() {
+    this._queue?.adapter.clear("cancel-run");
     const error = new AbortError(false);
     this.abortController?.abort(error);
     this.abortController = null;

package/src/runtimes/readonly/ReadonlyThreadRuntimeCore.ts

@@ -158,6 +158,10 @@ export class ReadonlyThreadRuntimeCore
       // noop
     },
 
+    queue: [] as never[],
+    steerQueueItem() {},
+    removeQueueItem() {},
+
     dictation: undefined,
 
     startDictation() {

package/src/runtimes/remote-thread-list/empty-thread-core.ts

@@ -139,6 +139,10 @@ export const EMPTY_THREAD_CORE: ThreadRuntimeCore = {
       // noop
     },
 
+    queue: [] as never[],
+    steerQueueItem() {},
+    removeQueueItem() {},
+
     dictation: undefined,
 
     startDictation() {

package/src/store/clients/chain-of-thought-client.ts

@@ -1,4 +1,5 @@
-import { resource, tapMemo, tapState } from "@assistant-ui/tap";
+import { useMemo, useState } from "react";
+import { resource } from "@assistant-ui/tap";
 import type { ClientOutput } from "@assistant-ui/store";
 import type {
   ChainOfThoughtState,
@@ -11,30 +12,28 @@ const COMPLETE_STATUS: MessagePartStatus = Object.freeze({
   type: "complete",
 });
 
-export const ChainOfThoughtClient = resource(
-  ({
-    parts,
-    getMessagePart,
-  }: {
-    parts: readonly ChainOfThoughtPart[];
-    getMessagePart: (selector: { index: number }) => PartMethods;
-  }): ClientOutput<"chainOfThought"> => {
-    const [collapsed, setCollapsed] = tapState(true);
+export const ChainOfThoughtClient = resource(function ChainOfThoughtClient({
+  parts,
+  getMessagePart,
+}: {
+  parts: readonly ChainOfThoughtPart[];
+  getMessagePart: (selector: { index: number }) => PartMethods;
+}): ClientOutput<"chainOfThought"> {
+  const [collapsed, setCollapsed] = useState(true);
 
-    const status = tapMemo(() => {
-      const lastPart = parts[parts.length - 1];
-      return lastPart?.status ?? COMPLETE_STATUS;
-    }, [parts]);
+  const status = useMemo(() => {
+    const lastPart = parts[parts.length - 1];
+    return lastPart?.status ?? COMPLETE_STATUS;
+  }, [parts]);
 
-    const state = tapMemo<ChainOfThoughtState>(
-      () => ({ parts, collapsed, status }),
-      [parts, collapsed, status],
-    );
+  const state = useMemo<ChainOfThoughtState>(
+    () => ({ parts, collapsed, status }),
+    [parts, collapsed, status],
+  );
 
-    return {
-      getState: () => state,
-      setCollapsed,
-      part: getMessagePart,
-    };
-  },
-);
+  return {
+    getState: () => state,
+    setCollapsed,
+    part: getMessagePart,
+  };
+});