@assistant-ui/core 0.3.4 → 0.3.6

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

@@ -4,6 +4,7 @@ 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 type { QueuePlacement } from "../queue/external-thread-queue-adapter";
 import {
   LazyMemoizeSubject,
   EventSubscriptionSubject,
@@ -200,9 +201,12 @@ export type ComposerRuntime = {
    */
   cancel(): void;
 
-  /** Promote a queued message so it processes next. */
+  /** @deprecated Use `moveQueueItem(queueItemId, { lane: "steer", insertAfter: null })` instead. Removal after 2026-11-05. */
   steerQueueItem(queueItemId: string): void;
 
+  /** Move a queued message between lanes or within a lane. */
+  moveQueueItem(queueItemId: string, placement: QueuePlacement): void;
+
   /** Remove a queued message. */
   removeQueueItem(queueItemId: string): void;
 
@@ -268,6 +272,7 @@ export abstract class ComposerRuntimeImpl implements ComposerRuntime {
     this.send = this.send.bind(this);
     this.cancel = this.cancel.bind(this);
     this.steerQueueItem = this.steerQueueItem.bind(this);
+    this.moveQueueItem = this.moveQueueItem.bind(this);
     this.removeQueueItem = this.removeQueueItem.bind(this);
     this.setRole = this.setRole.bind(this);
     this.getAttachmentByIndex = this.getAttachmentByIndex.bind(this);
@@ -322,9 +327,13 @@ export abstract class ComposerRuntimeImpl implements ComposerRuntime {
   }
 
   public steerQueueItem(queueItemId: string) {
+    this.moveQueueItem(queueItemId, { lane: "steer", insertAfter: null });
+  }
+
+  public moveQueueItem(queueItemId: string, placement: QueuePlacement) {
     const core = this._core.getState();
     if (!core) throw new Error("Composer is not available");
-    core.steerQueueItem(queueItemId);
+    core.moveQueueItem(queueItemId, placement);
   }
 
   public removeQueueItem(queueItemId: string) {

package/src/runtime/api/message-runtime.test.ts

@@ -173,6 +173,31 @@ describe("toMessagePartStatus", () => {
     });
   });
 
+  it.each([
+    ["false", false],
+    ["zero", 0],
+    ["an empty string", ""],
+    ["null", null],
+  ])("treats %s tool results as complete", (_label, result) => {
+    const message = createAssistantMessage(
+      [
+        {
+          type: "tool-call",
+          toolCallId: "call-1",
+          toolName: "weather",
+          args: {},
+          argsText: "{}",
+          result,
+        },
+      ],
+      { type: "running" },
+    );
+
+    expect(toMessagePartStatus(message, 0, message.content[0]!)).toEqual({
+      type: "complete",
+    });
+  });
+
   it("normalizes supplied upstream statuses", () => {
     const upstreamComplete = {
       type: "text",

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

@@ -44,7 +44,7 @@ export const toMessagePartStatus = (
   if (message.role !== "assistant") return COMPLETE_STATUS;
 
   if (part.type === "tool-call") {
-    if (!part.result) {
+    if (part.result === undefined) {
       return message.status as ToolCallMessagePartStatus;
     } else {
       return COMPLETE_STATUS;

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

@@ -24,6 +24,7 @@ import type {
   SendOptions,
 } from "../interfaces/composer-runtime-core";
 import type { DictationAdapter } from "../../adapters/speech";
+import type { QueuePlacement } from "../queue/external-thread-queue-adapter";
 import {
   EMPTY_QUEUE_ITEMS,
   type QueueItemState,
@@ -301,7 +302,10 @@ export abstract class BaseComposerRuntimeCore
     return EMPTY_QUEUE_ITEMS;
   }
 
-  public steerQueueItem(_queueItemId: string): void {}
+  public moveQueueItem(
+    _queueItemId: string,
+    _placement: QueuePlacement,
+  ): void {}
   public removeQueueItem(_queueItemId: string): void {}
 
   protected abstract handleSend(

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

@@ -6,6 +6,7 @@ import type {
   ThreadComposerRuntimeCore,
 } from "../interfaces/composer-runtime-core";
 import type { ThreadRuntimeCore } from "../interfaces/thread-runtime-core";
+import type { QueuePlacement } from "../queue/external-thread-queue-adapter";
 import {
   EMPTY_QUEUE_ITEMS,
   type QueueItemState,
@@ -26,12 +27,35 @@ export class DefaultThreadComposerRuntimeCore
     return !this.isEmpty && !this.runtime.isSendDisabled && !this._isSending;
   }
 
+  private _queueCache:
+    | {
+        steer: readonly QueueItemState[];
+        queue: readonly QueueItemState[];
+        flat: readonly QueueItemState[];
+      }
+    | undefined;
+
   public override get queue(): readonly QueueItemState[] {
-    return this.runtime.getQueueItems?.() ?? EMPTY_QUEUE_ITEMS;
+    const steer = this.runtime.getSteerQueueItems?.() ?? EMPTY_QUEUE_ITEMS;
+    const queue = this.runtime.getQueueItems?.() ?? EMPTY_QUEUE_ITEMS;
+    const cache = this._queueCache;
+    if (cache && cache.steer === steer && cache.queue === queue)
+      return cache.flat;
+    const flat =
+      steer.length === 0
+        ? queue
+        : queue.length === 0
+          ? steer
+          : [...steer, ...queue];
+    this._queueCache = { steer, queue, flat };
+    return flat;
   }
 
-  public override steerQueueItem(queueItemId: string): void {
-    this.runtime.steerQueueItem?.(queueItemId);
+  public override moveQueueItem(
+    queueItemId: string,
+    placement: QueuePlacement,
+  ): void {
+    this.runtime.moveQueueItem?.(queueItemId, placement);
   }
 
   public override removeQueueItem(queueItemId: string): void {

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

@@ -5,6 +5,7 @@ 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";
+import type { QueuePlacement } from "../queue/external-thread-queue-adapter";
 
 export type AttachmentAddErrorReason =
   | "no-adapter"
@@ -82,7 +83,7 @@ export type ComposerRuntimeCore = Readonly<{
   cancel: () => void;
 
   queue: readonly QueueItemState[];
-  steerQueueItem: (queueItemId: string) => void;
+  moveQueueItem: (queueItemId: string, placement: QueuePlacement) => void;
   removeQueueItem: (queueItemId: string) => void;
 
   dictation: DictationState | undefined;

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

@@ -17,6 +17,7 @@ import type {
   ThreadComposerRuntimeCore,
 } from "./composer-runtime-core";
 import type { QueueItemState } from "../../store/scopes/queue-item";
+import type { QueuePlacement } from "../queue/external-thread-queue-adapter";
 
 export type RuntimeCapabilities = {
   readonly switchToBranch: boolean;
@@ -177,7 +178,8 @@ export type ThreadRuntimeCore = Readonly<{
   beginEdit: (messageId: string) => void;
 
   getQueueItems?: () => readonly QueueItemState[];
-  steerQueueItem?: (queueItemId: string) => void;
+  getSteerQueueItems?: () => readonly QueueItemState[];
+  moveQueueItem?: (queueItemId: string, placement: QueuePlacement) => void;
   removeQueueItem?: (queueItemId: string) => void;
 
   speech: SpeechState | undefined;

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

@@ -1,14 +1,30 @@
 import type { AppendMessage } from "../../types/message";
 import type { QueueItemState } from "../../store/scopes/queue-item";
 
+export type QueuePlacement = {
+  readonly lane?: "queue" | "steer";
+  readonly insertAfter?: string | null;
+  readonly insertBefore?: string | null;
+};
+
 /**
  * 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;
+  steerItems: readonly QueueItemState[];
+  /** Send a message into the queue lane, processed in order. */
+  enqueue: (message: AppendMessage) => void;
+  /** Send a message into the steer lane, processed next. */
+  steer: (message: AppendMessage) => void;
+  /**
+   * Move a queued message between lanes or within a lane. An unanchored move
+   * into the steer lane mid-run interrupts — cancels the live run and
+   * dispatches the item — when the runtime supports cancellation; a move with
+   * `insertAfter`/`insertBefore` only places the item and never interrupts.
+   */
+  move: (queueItemId: string, placement: QueuePlacement) => void;
+  edit: (queueItemId: string, message: AppendMessage) => void;
   remove: (queueItemId: string) => void;
-  clear: (reason: "edit" | "reload" | "cancel-run") => void;
 };

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

@@ -1,15 +1,22 @@
-import type { AppendMessage } from "../../types/message";
+import type {
+  AppendMessage,
+  FileMessagePart,
+  TextMessagePart,
+} 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";
+import type {
+  ExternalThreadQueueAdapter,
+  QueuePlacement,
+} 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. */
+  /** When omitted, steering degrades to "process next" instead of interrupting. */
   cancel?: (() => void) | undefined;
 };
 
@@ -19,95 +26,239 @@ export type MessageQueueController = {
   notifyBusy: () => void;
   /** Advances to the next pending message; call on the run's falling edge. */
   notifyIdle: () => void;
+  /**
+   * Pauses queue advance for a user-initiated cancel, so the cancelled run's
+   * settle keeps the pending items instead of dispatching the next one; the
+   * next explicit send or run start re-arms draining. Call before aborting
+   * the run.
+   */
+  notifyCancelled: () => void;
+  /** Empties both lanes without dispatching. */
+  clear: () => void;
   subscribe: (callback: () => void) => () => void;
 };
 
+type Lane = "queue" | "steer";
+
+const getQueueItemParts = (
+  message: AppendMessage,
+): readonly (FileMessagePart | TextMessagePart)[] => {
+  // attachment-derived text is the file body, not user-authored prose;
+  // project only the file/image content of attachments
+  const source = [
+    ...message.content,
+    ...(message.attachments ?? []).flatMap((attachment) =>
+      (attachment.content ?? []).filter((part) => part.type !== "text"),
+    ),
+  ];
+  const parts: (FileMessagePart | TextMessagePart)[] = [];
+  for (const part of source) {
+    if (part.type === "file" || part.type === "text") {
+      parts.push(part);
+    } else if (part.type === "image") {
+      parts.push({
+        type: "file",
+        data: part.image,
+        mimeType: "image/*",
+        ...(part.filename !== undefined && { filename: part.filename }),
+      });
+    }
+  }
+  return parts;
+};
+
 export const createMessageQueue = (
   driver: MessageQueueDriver,
 ): MessageQueueController => {
-  let items: readonly QueueItemState[] = EMPTY_QUEUE_ITEMS;
+  let lanes: Record<Lane, readonly QueueItemState[]> = {
+    queue: EMPTY_QUEUE_ITEMS,
+    steer: EMPTY_QUEUE_ITEMS,
+  };
   const messages = new Map<string, AppendMessage>();
   const subscribers = new Set<() => void>();
 
   let running = false;
+  let paused = false;
   // swallow the cancelled run's settle when steering so it does not double-advance
   let suppressIdle = 0;
+  // settles from cancelled runs that must drop `running` without advancing
+  let cancelSettles = 0;
 
   const notify = () => {
     for (const callback of subscribers) callback();
   };
 
-  const setItems = (next: readonly QueueItemState[]) => {
-    items = next;
-    adapter.items = next;
+  const setLanes = (next: Record<Lane, readonly QueueItemState[]>) => {
+    lanes = next;
+    adapter.items = next.queue;
+    adapter.steerItems = next.steer;
     notify();
   };
 
+  const toItem = (id: string, message: AppendMessage): QueueItemState => ({
+    id,
+    prompt: getThreadMessageText(message),
+    parts: getQueueItemParts(message),
+  });
+
+  const laneOf = (queueItemId: string): Lane | undefined => {
+    if (lanes.steer.some((item) => item.id === queueItemId)) return "steer";
+    if (lanes.queue.some((item) => item.id === queueItemId)) return "queue";
+    return undefined;
+  };
+
   const advance = () => {
-    if (running || items.length === 0) return;
-    const head = items[0]!;
+    if (running || paused) return;
+    const lane: Lane = lanes.steer.length > 0 ? "steer" : "queue";
+    const head = lanes[lane][0];
+    if (!head) return;
     const message = messages.get(head.id);
     messages.delete(head.id);
-    setItems(items.slice(1));
+    setLanes({ ...lanes, [lane]: lanes[lane].slice(1) });
     if (!message) return;
     running = true;
     driver.run(message, { steer: false });
   };
 
-  const enqueue = (message: AppendMessage, { steer }: { steer: boolean }) => {
+  const interrupt = (message: AppendMessage) => {
+    paused = false;
+    // the interrupted run settles exactly once, whether or not it was
+    // already cancel-notified
+    suppressIdle += Math.max(cancelSettles, 1);
+    cancelSettles = 0;
+    driver.cancel!();
+    running = true;
+    driver.run(message, { steer: true });
+  };
+
+  const push = (lane: Lane, message: AppendMessage) => {
+    paused = false;
     const id = generateId();
-    const prompt = getThreadMessageText(message);
     messages.set(id, message);
-    setItems([...items, { id, prompt }]);
-    if (steer) {
-      steerItem(id);
-    } else {
-      advance();
+    setLanes({ ...lanes, [lane]: [...lanes[lane], toItem(id, message)] });
+    advance();
+  };
+
+  const enqueue = (message: AppendMessage) => {
+    push("queue", message);
+  };
+
+  const steer = (message: AppendMessage) => {
+    if (running && driver.cancel) {
+      interrupt(message);
+      return;
     }
+    push("steer", message);
   };
 
-  const steerItem = (queueItemId: string) => {
-    if (!messages.has(queueItemId)) return;
+  const move = (queueItemId: string, placement: QueuePlacement) => {
+    const fromLane = laneOf(queueItemId);
+    if (!fromLane) throw new Error(`Unknown queue item "${queueItemId}".`);
+    const toLane = placement.lane ?? fromLane;
+
+    const item = lanes[fromLane].find((i) => i.id === queueItemId)!;
+    const dest = (toLane === fromLane ? lanes[fromLane] : lanes[toLane]).filter(
+      (i) => i.id !== queueItemId,
+    );
+
+    const anchorIndex = (anchor: string) => {
+      if (anchor === queueItemId)
+        throw new Error(`Queue item "${queueItemId}" cannot anchor itself.`);
+      const index = dest.findIndex((i) => i.id === anchor);
+      if (index === -1)
+        throw new Error(`Unknown anchor "${anchor}" in lane "${toLane}".`);
+      return index;
+    };
+
+    const { insertAfter, insertBefore } = placement;
+    let index: number;
+    if (insertAfter === undefined && insertBefore === undefined) {
+      index =
+        toLane === fromLane
+          ? lanes[fromLane].findIndex((i) => i.id === queueItemId)
+          : dest.length;
+    } else if (insertAfter !== undefined && insertBefore !== undefined) {
+      const after = insertAfter === null ? -1 : anchorIndex(insertAfter);
+      const before =
+        insertBefore === null ? dest.length : anchorIndex(insertBefore);
+      if (before !== after + 1)
+        throw new Error(
+          `insertAfter "${insertAfter}" and insertBefore "${insertBefore}" are not adjacent in lane "${toLane}".`,
+        );
+      index = after + 1;
+    } else if (insertAfter !== undefined) {
+      index = insertAfter === null ? 0 : anchorIndex(insertAfter) + 1;
+    } else {
+      index = insertBefore === null ? dest.length : anchorIndex(insertBefore!);
+    }
 
-    if (driver.cancel && running) {
+    // placement and immediate dispatch cannot coexist: an anchored move into
+    // the steer lane places without interrupting; only an unanchored one
+    // cancels the live run and dispatches
+    if (
+      insertAfter === undefined &&
+      insertBefore === undefined &&
+      toLane === "steer" &&
+      fromLane !== "steer" &&
+      running &&
+      driver.cancel
+    ) {
       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 });
+      setLanes({
+        queue: lanes.queue.filter((i) => i.id !== queueItemId),
+        steer: lanes.steer,
+      });
+      interrupt(message);
       return;
     }
 
-    const target = items.find((item) => item.id === queueItemId);
-    if (!target) return;
-    setItems([target, ...items.filter((item) => item.id !== queueItemId)]);
+    const nextDest = [...dest.slice(0, index), item, ...dest.slice(index)];
+    const next = { ...lanes, [toLane]: nextDest };
+    if (toLane !== fromLane)
+      next[fromLane] = lanes[fromLane].filter((i) => i.id !== queueItemId);
+    setLanes(next);
     advance();
   };
 
-  const remove = (queueItemId: string) => {
-    if (!messages.delete(queueItemId)) return;
-    setItems(items.filter((item) => item.id !== queueItemId));
+  const edit = (queueItemId: string, message: AppendMessage) => {
+    const lane = laneOf(queueItemId);
+    if (!lane) throw new Error(`Unknown queue item "${queueItemId}".`);
+    messages.set(queueItemId, message);
+    setLanes({
+      ...lanes,
+      [lane]: lanes[lane].map((item) =>
+        item.id === queueItemId ? toItem(queueItemId, message) : item,
+      ),
+    });
   };
 
-  const clear = () => {
-    if (items.length === 0) return;
-    messages.clear();
-    setItems(EMPTY_QUEUE_ITEMS);
+  const remove = (queueItemId: string) => {
+    if (!messages.delete(queueItemId)) return;
+    setLanes({
+      queue: lanes.queue.filter((item) => item.id !== queueItemId),
+      steer: lanes.steer.filter((item) => item.id !== queueItemId),
+    });
   };
 
   const adapter: ExternalThreadQueueAdapter = {
-    items,
+    items: lanes.queue,
+    steerItems: lanes.steer,
     enqueue,
-    steer: steerItem,
+    steer,
+    move,
+    edit,
     remove,
-    clear,
   };
 
   return {
     adapter,
     notifyBusy: () => {
+      paused = false;
+      // a cancelled run's settle that is still outstanding belongs to a run
+      // this new one replaces; swallow it entirely
+      suppressIdle += cancelSettles;
+      cancelSettles = 0;
       running = true;
     },
     notifyIdle: () => {
@@ -115,9 +266,20 @@ export const createMessageQueue = (
         suppressIdle--;
         return;
       }
+      if (cancelSettles > 0) cancelSettles--;
       running = false;
       advance();
     },
+    notifyCancelled: () => {
+      if (running && cancelSettles === 0) {
+        paused = true;
+        cancelSettles = 1;
+      }
+    },
+    clear: () => {
+      messages.clear();
+      setLanes({ queue: EMPTY_QUEUE_ITEMS, steer: EMPTY_QUEUE_ITEMS });
+    },
     subscribe: (callback) => {
       subscribers.add(callback);
       return () => {

package/src/runtime/utils/thread-message-like.ts

@@ -1,5 +1,6 @@
 import { parsePartialJsonObject } from "assistant-stream/utils";
 import { generateId } from "../../utils/id";
+import { parseDataUrl } from "../../utils/data-url";
 import type {
   ReasoningMessagePart,
   SourceMessagePart,
@@ -130,10 +131,7 @@ export const fromThreadMessageLike = (
     ...rest
   }: ImageMessagePart): ImageMessagePart | null => {
     if (typeof image !== "string") return null;
-    const dataUri = image.match(
-      /^data:image\/(png|jpeg|jpg|gif|webp|svg\+xml);base64,(.*)$/i,
-    );
-    if (dataUri) {
+    if (parseDataUrl(image)?.mimeType.startsWith("image/")) {
       return { ...rest, image };
     }
     if (/^(https:\/\/|blob:)/i.test(image)) {

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

@@ -27,6 +27,7 @@ import type {
   RuntimeCapabilities,
   ThreadRuntimeCore,
 } from "../../runtime/interfaces/thread-runtime-core";
+import type { QueuePlacement } from "../../runtime/queue/external-thread-queue-adapter";
 import { BaseThreadRuntimeCore } from "../../runtime/base/base-thread-runtime-core";
 import type { ModelContextProvider } from "../../model-context/types";
 import {
@@ -470,7 +471,9 @@ export class ExternalStoreThreadRuntimeCore
     // 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 });
+      if (message.steer ?? this._store.isRunning ?? false)
+        this._store.queue.steer(message);
+      else this._store.queue.enqueue(message);
       return;
     }
 
@@ -487,7 +490,6 @@ export class ExternalStoreThreadRuntimeCore
     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);
@@ -520,8 +522,12 @@ export class ExternalStoreThreadRuntimeCore
     return this._store?.queue?.items ?? EMPTY_QUEUE_ITEMS;
   }
 
-  public steerQueueItem(queueItemId: string) {
-    this._store?.queue?.steer(queueItemId);
+  public getSteerQueueItems() {
+    return this._store?.queue?.steerItems ?? EMPTY_QUEUE_ITEMS;
+  }
+
+  public moveQueueItem(queueItemId: string, placement: QueuePlacement) {
+    this._store?.queue?.move(queueItemId, placement);
   }
 
   public removeQueueItem(queueItemId: string) {
@@ -532,8 +538,6 @@ export class ExternalStoreThreadRuntimeCore
     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.
@@ -579,8 +583,6 @@ 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

@@ -32,4 +32,19 @@ export type LocalRuntimeOptionsBase = {
    * `composer.queue` and sent once the run settles. Steering runs it next.
    */
   unstable_enableMessageQueue?: boolean | undefined;
+
+  /**
+   * Auto-clear the message queue when the thread rewinds (message edit).
+   * Defaults to `true`.
+   * @deprecated Removal after 2026-11-05 — the queue will always survive rewinds.
+   */
+  unstable_queueClearOnRewind?: boolean | undefined;
+
+  /**
+   * Auto-clear the message queue when the user cancels the run. Defaults to
+   * `true`. When `false`, cancel pauses the queue and keeps the pending
+   * items; the next send drains them.
+   * @deprecated Removal after 2026-11-05 — cancel will always pause the queue and keep the items.
+   */
+  unstable_queueClearOnCancel?: boolean | undefined;
 };