@assistant-ui/core 0.3.5 → 0.3.7

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/runtime-extras-brand.ts

@@ -0,0 +1,47 @@
+/** @deprecated Internal API for external-store adapter authors. Not part of the public API; may change or be removed without notice. */
+export type RuntimeExtrasBrand<T extends object> = {
+  provide: (value: T) => T;
+  is: (extras: unknown) => extras is T;
+  tryGet: (extras: unknown) => T | undefined;
+  assert: (extras: unknown) => T;
+};
+
+/**
+ * Creates the framework-neutral half of a runtime extras channel: the brand
+ * symbol with its provide/read primitives. A runtime factory provides extras
+ * through the brand on any framework; the React entry wraps the same brand
+ * with a `use()` hook. The symbol is per-instance, so the adapter package
+ * creates the brand once and every binding imports that instance.
+ *
+ * @deprecated Internal API for external-store adapter authors. Not part of the public API; may change or be removed without notice.
+ */
+export const createRuntimeExtrasBrand = <T extends object>(
+  runtimeName: string,
+): RuntimeExtrasBrand<T> => {
+  const brand = Symbol(`${runtimeName} extras`);
+
+  const is = (extras: unknown): extras is T =>
+    typeof extras === "object" && extras !== null && brand in extras;
+
+  const assert = (extras: unknown): T => {
+    if (!is(extras))
+      throw new Error(
+        `The current thread is not backed by the ${runtimeName} runtime.`,
+      );
+    return extras;
+  };
+
+  const provide = (value: T): T => {
+    Object.defineProperty(value, brand, {
+      value: true,
+      enumerable: false,
+      configurable: true,
+    });
+    return value;
+  };
+
+  const tryGet = (extras: unknown): T | undefined =>
+    is(extras) ? extras : undefined;
+
+  return { provide, is, tryGet, assert };
+};

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;
 };

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

@@ -958,6 +958,49 @@ describe("LocalThreadRuntimeCore tool approval persistence", () => {
     });
   });
 
+  it("does not persist an existing falsy tool result again", async () => {
+    const { history, updated } = createHistory();
+    const twoHumanTools: ChatModelRunResult = {
+      content: [
+        {
+          ...toolCallPart("send_email"),
+          toolCallId: "call-1",
+        },
+        {
+          ...toolCallPart("send_email"),
+          toolCallId: "call-2",
+        },
+      ],
+      status: { type: "requires-action", reason: "tool-calls" },
+    };
+    const thread = createThread(
+      {
+        async run() {
+          return twoHumanTools;
+        },
+      },
+      { history },
+    );
+
+    await thread.append(userMessage("send two emails"));
+    await flush();
+
+    const options = {
+      messageId: thread.messages.at(-1)!.id,
+      toolName: "send_email",
+      toolCallId: "call-1",
+      result: false,
+      isError: false,
+    };
+    thread.addToolResult(options);
+    await flush();
+    expect(updated).toHaveLength(1);
+
+    thread.addToolResult(options);
+    await flush();
+    expect(updated).toHaveLength(1);
+  });
+
   it("persists a multi-step run once instead of writing intermediate steps", async () => {
     const { history, appended, updated } = createHistory();
     const runs: ChatModelRunOptions[] = [];

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

@@ -28,6 +28,7 @@ import {
   createMessageQueue,
   type MessageQueueController,
 } from "../../runtime/queue/message-queue";
+import type { QueuePlacement } from "../../runtime/queue/external-thread-queue-adapter";
 import {
   EMPTY_QUEUE_ITEMS,
   type QueueItemState,
@@ -68,6 +69,8 @@ export class LocalThreadRuntimeCore
 
   private _queue: MessageQueueController | null = null;
   private _queueRunInFlight = false;
+  private _activeRun: { cancelled: boolean } | null = null;
+  private _runGeneration = 0;
 
   private _historyWrites = new Map<string, Promise<void>>();
 
@@ -206,17 +209,23 @@ export class LocalThreadRuntimeCore
           // 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)
+          const generation = this._runGeneration;
+          // the tail may have moved since the message was enqueued
+          void this._runAppend({
+            ...message,
+            parentId: this.messages.at(-1)?.id ?? null,
+          })
             .finally(() => {
               this._queueRunInFlight = false;
-              this._queue?.notifyIdle();
+              // a dispatch that failed before starting a run settles here;
+              // runs that did start release from _runLoop
+              if (this._runGeneration === generation) 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) {
@@ -271,10 +280,17 @@ export class LocalThreadRuntimeCore
     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 });
+      if (message.steer ?? this._queueRunInFlight)
+        this._queue.adapter.steer(message);
+      else this._queue.adapter.enqueue(message);
       return;
     }
-    if (this._queue && !isTail) this._queue.adapter.clear("edit");
+    if (
+      this._queue &&
+      !isTail &&
+      (this._options.unstable_queueClearOnRewind ?? true)
+    )
+      this._queue.clear();
     return this._runAppend(message);
   }
 
@@ -284,8 +300,12 @@ export class LocalThreadRuntimeCore
     return this._queue?.adapter.items ?? EMPTY_QUEUE_ITEMS;
   }
 
-  public steerQueueItem(queueItemId: string): void {
-    this._queue?.adapter.steer(queueItemId);
+  public getSteerQueueItems(): readonly QueueItemState[] {
+    return this._queue?.adapter.steerItems ?? EMPTY_QUEUE_ITEMS;
+  }
+
+  public moveQueueItem(queueItemId: string, placement: QueuePlacement): void {
+    this._queue?.adapter.move(queueItemId, placement);
   }
 
   public removeQueueItem(queueItemId: string): void {
@@ -397,6 +417,10 @@ export class LocalThreadRuntimeCore
       message.status?.type === "requires-action" &&
       this._options.adapters.history?.update !== undefined;
 
+    const run = { cancelled: false };
+    this._activeRun = run;
+    this._runGeneration++;
+
     try {
       // mark busy for runs not started through the queue (regenerate, resume)
       this._queue?.notifyBusy();
@@ -417,9 +441,12 @@ 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) {
+      // the settle belongs to this run only while it is still the active run
+      // or was cancelled (the engine expects a cancelled run's settle); a run
+      // superseded by a newer one stays silent
+      const active = this._activeRun === run;
+      if (active) this._activeRun = null;
+      if (active || run.cancelled) {
         queueMicrotask(() => this._queue?.notifyIdle());
       }
     }
@@ -644,7 +671,8 @@ export class LocalThreadRuntimeCore
   }
 
   public detach() {
-    this._queue?.adapter.clear("cancel-run");
+    // drop the queue so pending items cannot dispatch on a detached thread
+    this._queue = null;
     const error = new AbortError(true);
     this.abortController?.abort(error);
     this.abortController = null;
@@ -653,7 +681,14 @@ export class LocalThreadRuntimeCore
   }
 
   public cancelRun() {
-    this._queue?.adapter.clear("cancel-run");
+    if (this._queue) {
+      if (this._options.unstable_queueClearOnCancel ?? true) {
+        this._queue.clear();
+      } else {
+        this._queue.notifyCancelled();
+        if (this._activeRun) this._activeRun.cancelled = true;
+      }
+    }
     const error = new AbortError(false);
     this.abortController?.abort(error);
     this.abortController = null;
@@ -681,7 +716,7 @@ export class LocalThreadRuntimeCore
       if (c.type !== "tool-call") return c;
       if (c.toolCallId !== toolCallId) return c;
       found = true;
-      if (!c.result) added = true;
+      if (c.result === undefined) added = true;
       return {
         ...c,
         result,

package/src/runtimes/readonly/ReadonlyThreadRuntimeCore.ts

@@ -163,7 +163,7 @@ export class ReadonlyThreadRuntimeCore
     },
 
     queue: [] as never[],
-    steerQueueItem() {},
+    moveQueueItem() {},
     removeQueueItem() {},
 
     dictation: undefined,

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

@@ -144,7 +144,7 @@ export const EMPTY_THREAD_CORE: ThreadRuntimeCore = {
     },
 
     queue: [] as never[],
-    steerQueueItem() {},
+    moveQueueItem() {},
     removeQueueItem() {},
 
     dictation: undefined,