@assistant-ui/core 0.3.4 → 0.3.6

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,

package/src/runtimes/remote-thread-list/types.ts

@@ -1,8 +1,15 @@
-import type { ComponentType, PropsWithChildren } from "react";
 import type { ThreadMessage } from "../../types/message";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 import type { AssistantStream } from "assistant-stream";
 
+/* oxlint-disable typescript/no-explicit-any -- structural stand-in for ComponentType without depending on react types */
+type RemoteThreadListProviderProps = { children?: any };
+
+export type RemoteThreadListProviderComponent =
+  | ((props: RemoteThreadListProviderProps) => any)
+  | (new (props: RemoteThreadListProviderProps) => any);
+/* oxlint-enable typescript/no-explicit-any */
+
 export type RemoteThreadInitializeResponse = {
   remoteId: string;
   externalId?: string | undefined;
@@ -54,7 +61,7 @@ export type RemoteThreadListAdapter = {
    * is unsupported and leaves thread context unavailable to downstream
    * consumers. Load data inside an always-mounted child instead.
    */
-  unstable_Provider?: ComponentType<PropsWithChildren> | undefined;
+  unstable_Provider?: RemoteThreadListProviderComponent | undefined;
 };
 
 export type RemoteThreadListOptions = {

package/src/store/runtime-clients/composer-runtime-client.ts

@@ -12,6 +12,7 @@ import type {
 } from "../../runtime/api/composer-runtime";
 import type { ComposerState } from "../scopes/composer";
 import type { QueueItemState } from "../scopes/queue-item";
+import type { QueuePlacement } from "../../runtime/queue/external-thread-queue-adapter";
 import { AttachmentRuntimeClient } from "./attachment-runtime-client";
 import { useSubscribable } from "./useSubscribable";
 
@@ -40,16 +41,17 @@ const ComposerAttachmentClientByIndex = resource(
 
 const useQueueItemClient = ({
   item,
-  onSteer,
+  onMove,
   onRemove,
 }: {
   item: QueueItemState;
-  onSteer: () => void;
+  onMove: (placement: QueuePlacement) => void;
   onRemove: () => void;
 }): ClientOutput<"queueItem"> => {
   return {
     getState: () => item,
-    steer: onSteer,
+    steer: () => onMove({ lane: "steer", insertAfter: null }),
+    move: onMove,
     remove: onRemove,
   };
 };
@@ -121,7 +123,7 @@ const useComposerClient = ({
         item.id,
         QueueItemClient({
           item,
-          onSteer: () => runtime.steerQueueItem(item.id),
+          onMove: (placement) => runtime.moveQueueItem(item.id, placement),
           onRemove: () => runtime.removeQueueItem(item.id),
         }),
       ),
@@ -171,7 +173,13 @@ const useComposerClient = ({
         return attachments.get(selector);
       }
     },
-    queueItem: (selector) => queueItems.get(selector),
+    queueItem: (selector) => {
+      if ("id" in selector) {
+        return queueItems.get({ key: selector.id });
+      } else {
+        return queueItems.get(selector);
+      }
+    },
     __internal_getRuntime: () => runtime,
   };
 };

package/src/store/scopes/composer.ts

@@ -13,8 +13,10 @@ import type { QueueItemState, QueueItemMethods } from "./queue-item";
 
 export type ComposerSendOptions = SendOptions & {
   /**
-   * Whether to steer (interrupt the current run and process this message immediately).
-   * When false (default), the message is queued and processed in order.
+   * Whether to steer (process this message next, interrupting the current run
+   * when the runtime supports it). Defaults to true while a queued run is in
+   * flight and false when idle. Pass false to queue behind the pending
+   * messages.
    */
   steer?: boolean;
 };
@@ -88,9 +90,9 @@ export type ComposerMethods = {
   setQuote(quote: QuoteInfo | undefined): void;
 
   /**
-   * Access a queue item by index.
+   * Access a queue item by index or id.
    */
-  queueItem(selector: { index: number }): QueueItemMethods;
+  queueItem(selector: { index: number } | { id: string }): QueueItemMethods;
 
   __internal_getRuntime?(): ComposerRuntime;
 };

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

@@ -1,19 +1,26 @@
+import type { FileMessagePart, TextMessagePart } from "../../types/message";
+import type { QueuePlacement } from "../../runtime/queue/external-thread-queue-adapter";
+
 export type QueueItemState = {
   readonly id: string;
+  /** @deprecated Derive from the text parts of `parts` instead. Removal after 2026-11-05. */
   readonly prompt: string;
+  readonly parts: readonly (FileMessagePart | TextMessagePart)[];
 };
 
 export const EMPTY_QUEUE_ITEMS: readonly QueueItemState[] = Object.freeze([]);
 
 export type QueueItemMethods = {
   getState(): QueueItemState;
+  /** @deprecated Use `move({ lane: "steer", insertAfter: null })` instead. Removal after 2026-11-05. */
   steer(): void;
+  move(placement: QueuePlacement): void;
   remove(): void;
 };
 
 export type QueueItemMeta = {
   source: "composer";
-  query: { index: number };
+  query: { type: "index"; index: number } | { type: "id"; id: string };
 };
 
 export type QueueItemClientSchema = {

package/src/tests/RemoteThreadListThreadListRuntimeCore-switchToThread-order.test.ts

@@ -64,6 +64,37 @@ describe("RemoteThreadListThreadListRuntimeCore.switchToThread order", () => {
     expect(core.mainThreadId).toBe(core.getItemById("thread-c")?.id);
   });
 
+  it("handles a stopped initial runtime start", async () => {
+    const rejections: unknown[] = [];
+    const onUnhandledRejection = (reason: unknown) => {
+      rejections.push(reason);
+    };
+    const priorListeners = process.listeners("unhandledRejection");
+    process.removeAllListeners("unhandledRejection");
+    process.on("unhandledRejection", onUnhandledRejection);
+    try {
+      const core = createCore(makeAdapter());
+      const newThreadId = core.newThreadId;
+      if (!newThreadId) throw new Error("Expected an initial new thread");
+      const runtimeId = core.getItemById(newThreadId)?.id;
+      if (!runtimeId) throw new Error("Expected an initial runtime id");
+
+      (
+        core as unknown as {
+          _hookManager: { stopThreadRuntime: (id: string) => void };
+        }
+      )._hookManager.stopThreadRuntime(runtimeId);
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    } finally {
+      process.removeListener("unhandledRejection", onUnhandledRejection);
+      for (const listener of priorListeners) {
+        process.on("unhandledRejection", listener);
+      }
+    }
+
+    expect(rejections).toEqual([]);
+  });
+
   it("invalidates an earlier switch while a new thread request is pending", async () => {
     const initializeThread = deferred<{
       remoteId: string;

package/src/tests/external-store-thread-runtime-core.test.ts

@@ -832,10 +832,12 @@ describe("ExternalStoreThreadRuntimeCore - initialize event replay", () => {
 describe("ExternalStoreThreadRuntimeCore - message queue", () => {
   const makeQueue = () => ({
     items: [] as never[],
+    steerItems: [] as never[],
     enqueue: vi.fn(),
     steer: vi.fn(),
+    move: vi.fn(),
+    edit: vi.fn(),
     remove: vi.fn(),
-    clear: vi.fn(),
   });
 
   const appendMessage = (
@@ -866,7 +868,7 @@ describe("ExternalStoreThreadRuntimeCore - message queue", () => {
     expect(withoutQueue.capabilities.queue).toBe(false);
   });
 
-  it("routes a tail append through queue.enqueue instead of onNew", async () => {
+  it("routes a tail append through the queue adapter instead of onNew", async () => {
     const queue = makeQueue();
     const onNew = vi.fn();
     const runtime = new ExternalStoreThreadRuntimeCore(
@@ -877,8 +879,48 @@ describe("ExternalStoreThreadRuntimeCore - message queue", () => {
     await runtime.append(appendMessage({ steer: true }));
 
     expect(onNew).not.toHaveBeenCalled();
+    expect(queue.enqueue).not.toHaveBeenCalled();
+    expect(queue.steer).toHaveBeenCalledTimes(1);
+  });
+
+  it("defaults a mid-run send to steer and an idle send to enqueue", async () => {
+    const queue = makeQueue();
+    const running = new ExternalStoreThreadRuntimeCore(
+      mockContextProvider,
+      makeStore({ queue, onNew: vi.fn(), isRunning: true }),
+    );
+    await running.append(
+      appendMessage({ parentId: running.messages.at(-1)?.id ?? null }),
+    );
+    expect(queue.steer).toHaveBeenCalledTimes(1);
+    expect(queue.enqueue).not.toHaveBeenCalled();
+
+    const idleQueue = makeQueue();
+    const idle = new ExternalStoreThreadRuntimeCore(
+      mockContextProvider,
+      makeStore({ queue: idleQueue, onNew: vi.fn(), isRunning: false }),
+    );
+    await idle.append(
+      appendMessage({ parentId: idle.messages.at(-1)?.id ?? null }),
+    );
+    expect(idleQueue.enqueue).toHaveBeenCalledTimes(1);
+    expect(idleQueue.steer).not.toHaveBeenCalled();
+  });
+
+  it("queues behind pending items when steer is explicitly false mid-run", async () => {
+    const queue = makeQueue();
+    const runtime = new ExternalStoreThreadRuntimeCore(
+      mockContextProvider,
+      makeStore({ queue, onNew: vi.fn(), isRunning: true }),
+    );
+    await runtime.append(
+      appendMessage({
+        steer: false,
+        parentId: runtime.messages.at(-1)?.id ?? null,
+      }),
+    );
     expect(queue.enqueue).toHaveBeenCalledTimes(1);
-    expect(queue.enqueue.mock.calls[0]![1]).toEqual({ steer: true });
+    expect(queue.steer).not.toHaveBeenCalled();
   });
 
   it("does not abort in-flight tools when buffering a queued send", async () => {
@@ -913,7 +955,7 @@ describe("ExternalStoreThreadRuntimeCore - message queue", () => {
     expect(abort).toHaveBeenCalledTimes(1);
   });
 
-  it("clears the queue on cancel, reload, and edit", async () => {
+  it("keeps the queue on cancel, reload, and edit", async () => {
     const queue = makeQueue();
     const runtime = new ExternalStoreThreadRuntimeCore(
       mockContextProvider,
@@ -926,29 +968,30 @@ describe("ExternalStoreThreadRuntimeCore - message queue", () => {
     );
 
     runtime.cancelRun();
-    expect(queue.clear).toHaveBeenCalledWith("cancel-run");
-
     await runtime.startRun({ parentId: null, sourceId: null, runConfig: {} });
-    expect(queue.clear).toHaveBeenCalledWith("reload");
-
     // a non-tail parentId routes to the edit branch
     await runtime.append(appendMessage({ parentId: "not-the-tail" }));
-    expect(queue.clear).toHaveBeenCalledWith("edit");
+
+    expect(queue.remove).not.toHaveBeenCalled();
+    expect(queue.move).not.toHaveBeenCalled();
   });
 
-  it("delegates getQueueItems / steer / remove to the adapter", () => {
+  it("delegates queue reads / move / remove to the adapter", () => {
     const queue = makeQueue();
-    const items = [{ id: "q1", prompt: "queued" }];
+    const items = [{ id: "q1", prompt: "queued", parts: [] }];
+    const steerItems = [{ id: "s1", prompt: "steered", parts: [] }];
     queue.items = items as never;
+    queue.steerItems = steerItems as never;
     const runtime = new ExternalStoreThreadRuntimeCore(
       mockContextProvider,
       makeStore({ queue }),
     );
 
     expect(runtime.getQueueItems()).toBe(items);
-    runtime.steerQueueItem("q1");
+    expect(runtime.getSteerQueueItems()).toBe(steerItems);
+    runtime.moveQueueItem("q1", { lane: "steer" });
     runtime.removeQueueItem("q1");
-    expect(queue.steer).toHaveBeenCalledWith("q1");
+    expect(queue.move).toHaveBeenCalledWith("q1", { lane: "steer" });
     expect(queue.remove).toHaveBeenCalledWith("q1");
   });
 });