@assistant-ui/core 0.3.14 → 0.3.16

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

@@ -2,6 +2,7 @@ import type {
   RemoteThreadInitializeResponse,
   RemoteThreadMetadata,
 } from "./types";
+import { generateId } from "../../utils/id";
 
 export type RemoteThreadData =
   | {
@@ -11,6 +12,7 @@ export type RemoteThreadData =
       readonly status: "new";
       readonly title: undefined;
       readonly custom: undefined;
+      readonly localOrigin?: true;
     }
   | {
       readonly id: string;
@@ -20,6 +22,7 @@ export type RemoteThreadData =
       readonly status: "regular" | "archived";
       readonly title?: string | undefined;
       readonly custom: undefined;
+      readonly localOrigin?: true;
     }
   | {
       readonly id: string;
@@ -30,6 +33,7 @@ export type RemoteThreadData =
       readonly title?: string | undefined;
       readonly lastMessageAt?: Date | undefined;
       readonly custom?: Record<string, unknown> | undefined;
+      readonly localOrigin?: true;
     };
 
 export type THREAD_MAPPING_ID = string & { __brand: "THREAD_MAPPING_ID" };
@@ -38,6 +42,8 @@ export function createThreadMappingId(id: string): THREAD_MAPPING_ID {
   return id as THREAD_MAPPING_ID;
 }
 
+export const LOCAL_THREAD_ID_PREFIX = "__LOCALID_";
+
 export const normalizeCursor = (c: string | undefined): string | undefined =>
   c || undefined;
 
@@ -98,6 +104,123 @@ export type RemoteThreadState = {
   readonly threadData: Readonly<Record<THREAD_MAPPING_ID, RemoteThreadData>>;
 };
 
+export const createEmptyRemoteThreadState = (): RemoteThreadState => ({
+  isLoading: true,
+  isLoadingMore: false,
+  cursor: undefined,
+  newThreadId: undefined,
+  threadIds: [],
+  archivedThreadIds: [],
+  threadIdMap: {},
+  threadData: {},
+});
+
+export const seedNewThread = (
+  state: RemoteThreadState,
+): { id: string; state: RemoteThreadState } => {
+  let id: string;
+  do {
+    id = `${LOCAL_THREAD_ID_PREFIX}${generateId()}`;
+  } while (state.threadIdMap[id]);
+  const mappingId = createThreadMappingId(id);
+  return {
+    id,
+    state: {
+      ...state,
+      newThreadId: id,
+      threadIdMap: {
+        ...state.threadIdMap,
+        [id]: mappingId,
+      },
+      threadData: {
+        ...state.threadData,
+        [mappingId]: {
+          status: "new",
+          id,
+          remoteId: undefined,
+          externalId: undefined,
+          title: undefined,
+          custom: undefined,
+          localOrigin: true,
+        } satisfies RemoteThreadData,
+      },
+    },
+  };
+};
+
+// A list() response predating a mid-flight local transition (a thread
+// initialized while the request was running) omits that thread, and the
+// completed-optimistic replay cannot re-add it because the merged threadData
+// already carries the final status. Threads whose status moved from new (or
+// nonexistent) at request time to regular/archived are re-inserted at the
+// top, in the order the pre-response lists carried them: updateStatusReducer
+// prepends as transitions happen, so the pre-response lists hold newest
+// first, which threadData insertion order need not match. Threads the server already knew stay governed by the response, so
+// a server-side deletion is not resurrected — and a thread unknown to the
+// snapshot is only rescued when it carries the localOrigin marker stamped at
+// draft creation, so a deep-linked thread the fetch path deliberately
+// appended at the tail is not hoisted, whatever its remote id looks like.
+export const preserveMidLoadTransitions = (
+  state: RemoteThreadState,
+  priorOrder: Pick<RemoteThreadState, "threadIds" | "archivedThreadIds">,
+  statusAtRequest: ReadonlyMap<string, RemoteThreadData["status"]>,
+): RemoteThreadState => {
+  const regular = new Set(state.threadIds);
+  const archived = new Set(state.archivedThreadIds);
+  const rescuedRegular: RemoteThreadData[] = [];
+  const rescuedArchived: RemoteThreadData[] = [];
+
+  const contains = (ids: ReadonlySet<string>, data: RemoteThreadData) =>
+    ids.has(data.id) || (data.remoteId !== undefined && ids.has(data.remoteId));
+
+  for (const data of Object.values(state.threadData)) {
+    const before = statusAtRequest.get(data.id);
+    if (before !== undefined && before !== "new") continue;
+    if (before === undefined && data.localOrigin !== true) continue;
+
+    if (data.status === "regular" && !contains(regular, data)) {
+      rescuedRegular.push(data);
+      regular.add(data.id);
+    } else if (data.status === "archived" && !contains(archived, data)) {
+      rescuedArchived.push(data);
+      archived.add(data.id);
+    }
+  }
+
+  if (rescuedRegular.length === 0 && rescuedArchived.length === 0) return state;
+
+  const position = (ids: readonly string[], data: RemoteThreadData) => {
+    const byId = ids.indexOf(data.id);
+    if (byId !== -1) return byId;
+    const byRemoteId =
+      data.remoteId !== undefined ? ids.indexOf(data.remoteId) : -1;
+    return byRemoteId !== -1 ? byRemoteId : Number.MAX_SAFE_INTEGER;
+  };
+  rescuedRegular.sort(
+    (a, b) =>
+      position(priorOrder.threadIds, a) - position(priorOrder.threadIds, b),
+  );
+  rescuedArchived.sort(
+    (a, b) =>
+      position(priorOrder.archivedThreadIds, a) -
+      position(priorOrder.archivedThreadIds, b),
+  );
+
+  return {
+    ...state,
+    threadIds: [...rescuedRegular.map((d) => d.id), ...state.threadIds],
+    archivedThreadIds: [
+      ...rescuedArchived.map((d) => d.id),
+      ...state.archivedThreadIds,
+    ],
+  };
+};
+
+export const statusSnapshot = (
+  state: RemoteThreadState,
+): ReadonlyMap<string, RemoteThreadData["status"]> =>
+  new Map(Object.values(state.threadData).map((d) => [d.id, d.status]));
+
 export const getThreadData = (
   state: RemoteThreadState,
   threadIdOrRemoteId: string,

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

@@ -96,6 +96,10 @@ export type RemoteThreadListAdapter = {
 
 export type RemoteThreadListOptions = {
   runtimeHook: () => AssistantRuntime;
+
+  /**
+   * The adapter reference should remain stable across renders. Replacing it reloads the list and drops cached threads that are not in the replacement page. In-flight mutations from the previous adapter are cancelled.
+   */
   adapter: RemoteThreadListAdapter;
 
   /**

package/src/runtimes/tool-invocations/EDGE_CASES.md

@@ -78,6 +78,23 @@ sees only the first result.
 ### A.7. Previously-resolved tool loses its `result` (back to undefined)
 Silently ignored. The entry stays in the resolved phase internally.
 
+### A.8. Tool call carries a provider `approval`
+The entry is marked `skipExecute`, exactly like a call observed with
+a `result`, whether the gate is present when the call is first observed
+or lands on an already-active entry. A gate belongs to the provider:
+`approved === true` means the provider is producing the result, `false`
+means it records the denial, so the frontend `execute` never fires for
+that `toolCallId` once the gate is present. `streamCall` still fires
+once and the backend result flows through A.5 when it lands.
+
+If the gate lands after the args stream has closed but before an
+in-flight `execute` resolves, the execute runs to completion (its side
+effects happen) but its result chunk is dropped: `onResult` never fires,
+and the `executing` status, plus any `human()` interrupt the execution
+parked, stays up until the promise settles. Only a gate that lands after
+the result chunk has already been emitted is fully too late; the adapter
+must project the gate before that (#6285).
+
 ## B. Tool call disappears from snapshot
 
 ### B.1. Tool call removed entirely (rollback, branch switch)

package/src/runtimes/tool-invocations/ToolInvocationTracker.test.ts

@@ -47,6 +47,7 @@ const createAssistantMessage = (
     toolCallId?: string;
     toolName?: string;
     nestedMessages?: ThreadAssistantMessage[];
+    approval?: { id: string; approved?: boolean };
   },
 ): ThreadAssistantMessage => ({
   id: "m-1",
@@ -70,6 +71,7 @@ const createAssistantMessage = (
       ...(options?.result !== undefined && { result: options.result }),
       ...(options?.isError !== undefined && { isError: options.isError }),
       ...(options?.nestedMessages && { messages: options.nestedMessages }),
+      ...(options?.approval && { approval: options.approval }),
     },
   ],
 });
@@ -370,6 +372,144 @@ describe("ToolInvocationTracker", () => {
     });
   });
 
+  it("never executes a tool call that carries a provider approval", async () => {
+    const execute = vi.fn(async () => ({ deleted: true }));
+    const getTools = () => ({
+      deleteFile: {
+        parameters: { type: "object", properties: {} },
+        execute,
+      } satisfies Tool,
+    });
+    const onResult = vi.fn();
+    const tracker = new ToolInvocationTracker(getTools, {
+      onResult,
+      onStatusesChange: () => {},
+    });
+    tracker.setState(createState([]));
+
+    const gated = (approval: { id: string; approved?: boolean }) =>
+      createAssistantMessage(
+        '{"path":"/tmp/a"}',
+        { path: "/tmp/a" },
+        { toolName: "deleteFile", approval },
+      );
+
+    tracker.setState(createState([gated({ id: "approval-1" })], false));
+    await new Promise((r) => setTimeout(r, 0));
+    expect(execute).not.toHaveBeenCalled();
+
+    tracker.setState(
+      createState([gated({ id: "approval-1", approved: true })], true),
+    );
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(execute).not.toHaveBeenCalled();
+    expect(onResult).not.toHaveBeenCalled();
+  });
+
+  it("stops executing a live tool call once a provider approval lands", async () => {
+    const execute = vi.fn(async () => ({ deleted: true }));
+    const getTools = () => ({
+      deleteFile: {
+        parameters: { type: "object", properties: {} },
+        execute,
+      } satisfies Tool,
+    });
+    const onResult = vi.fn();
+    const tracker = new ToolInvocationTracker(getTools, {
+      onResult,
+      onStatusesChange: () => {},
+    });
+    tracker.setState(createState([]));
+
+    tracker.setState(
+      createState(
+        [
+          createAssistantMessage(
+            '{"path":"/tmp',
+            {},
+            { toolName: "deleteFile" },
+          ),
+        ],
+        true,
+      ),
+    );
+    tracker.setState(
+      createState(
+        [
+          createAssistantMessage(
+            '{"path":"/tmp/a"}',
+            { path: "/tmp/a" },
+            { toolName: "deleteFile", approval: { id: "approval-1" } },
+          ),
+        ],
+        true,
+      ),
+    );
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(execute).not.toHaveBeenCalled();
+    expect(onResult).not.toHaveBeenCalled();
+  });
+
+  it("drops the result of an in-flight execute once a provider approval lands", async () => {
+    let resolveExecute!: (value: { deleted: boolean }) => void;
+    const execute = vi.fn(
+      () =>
+        new Promise<{ deleted: boolean }>((r) => {
+          resolveExecute = r;
+        }),
+    );
+    const getTools = () => ({
+      deleteFile: {
+        parameters: { type: "object", properties: {} },
+        execute,
+      } satisfies Tool,
+    });
+    const onResult = vi.fn();
+    const tracker = new ToolInvocationTracker(getTools, {
+      onResult,
+      onStatusesChange: () => {},
+    });
+    tracker.setState(createState([]));
+
+    tracker.setState(
+      createState(
+        [
+          createAssistantMessage(
+            '{"path":"/tmp/a"}',
+            { path: "/tmp/a" },
+            {
+              toolName: "deleteFile",
+            },
+          ),
+        ],
+        true,
+      ),
+    );
+    await waitFor(() => expect(execute).toHaveBeenCalledTimes(1));
+
+    tracker.setState(
+      createState(
+        [
+          createAssistantMessage(
+            '{"path":"/tmp/a"}',
+            { path: "/tmp/a" },
+            {
+              toolName: "deleteFile",
+              approval: { id: "approval-1" },
+            },
+          ),
+        ],
+        true,
+      ),
+    );
+    resolveExecute({ deleted: true });
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(onResult).not.toHaveBeenCalled();
+  });
+
   it("does not re-execute asynchronously loaded resolved tool calls after reset", async () => {
     const execute = vi.fn(async () => ({ forecast: "ok" }));
     const getTools = () => ({

package/src/runtimes/tool-invocations/ToolInvocationTracker.ts

@@ -519,6 +519,7 @@ export class ToolInvocationTracker {
     // The host already set the result (via the live snapshot's
     // `setResponse` path). Suppress the executor's redundant emit.
     if (entry?.hasResult) return;
+    if (entry.skipExecute) return;
 
     this._invokeOnResult({
       type: "add-tool-result",
@@ -794,6 +795,8 @@ export class ToolInvocationTracker {
           );
         }
 
+        if (content.approval !== undefined) entry.skipExecute = true;
+
         this._processArgsText(entry, content);
 
         if (content.result !== undefined && !entry.hasResult) {

package/src/store/clients/external-thread.ts

@@ -44,6 +44,10 @@ import type { ComposerSendOptions } from "../scopes/composer";
 import { fileMatchesAccept } from "../../adapters/attachment";
 import { getThreadMessageText } from "../../utils/text";
 import { resolveToolApprovalResponse } from "../../runtime/utils/resolveToolApprovalResponse";
+import {
+  AttachmentAddOperations,
+  drainAttachmentAdd,
+} from "../../runtime/utils/attachment-add-operations";
 import { toMessagePartStatus } from "../../utils/normalizePartStatus";
 import { ModelContext } from "./model-context-client";
 import { ThreadSuggestions } from "./suggestions";
@@ -420,53 +424,6 @@ type ComposerClientResourceProps = {
   attachmentAdapter?: AttachmentAdapter | undefined;
 };
 
-type AttachmentAddOperation = {
-  cancelled: boolean;
-  attachmentIds: Set<string>;
-};
-
-class AttachmentAddOperations {
-  private readonly operations = new Set<AttachmentAddOperation>();
-
-  start() {
-    const operation: AttachmentAddOperation = {
-      cancelled: false,
-      attachmentIds: new Set(),
-    };
-    this.operations.add(operation);
-    return operation;
-  }
-
-  accept(operation: AttachmentAddOperation, attachmentId: string) {
-    if (operation.cancelled) return false;
-    operation.attachmentIds.add(attachmentId);
-    return true;
-  }
-
-  finish(operation: AttachmentAddOperation) {
-    this.operations.delete(operation);
-  }
-
-  isCancelled(operation: AttachmentAddOperation) {
-    return operation.cancelled;
-  }
-
-  cancel(attachmentId: string) {
-    for (const operation of [...this.operations]) {
-      if (!operation.attachmentIds.has(attachmentId)) continue;
-      operation.cancelled = true;
-      this.operations.delete(operation);
-    }
-  }
-
-  cancelAll() {
-    for (const operation of this.operations) {
-      operation.cancelled = true;
-    }
-    this.operations.clear();
-  }
-}
-
 const useQueueItemClient = ({
   item,
   onMove,
@@ -486,19 +443,6 @@ const useQueueItemClient = ({
 
 const QueueItemClient = resource(useQueueItemClient);
 
-const drainAdapterAdd = async (
-  result: ReturnType<AttachmentAdapter["add"]>,
-  upsert: (attachment: Attachment) => boolean,
-) => {
-  if (Symbol.asyncIterator in result) {
-    for await (const attachment of result) {
-      if (!upsert(attachment)) break;
-    }
-  } else {
-    upsert(await result);
-  }
-};
-
 // State whose setter tracks the latest value in a ref, so imperative
 // call sequences (setText immediately followed by send) observe the write
 // before React re-renders — legacy composer parity.
@@ -672,7 +616,7 @@ const useComposerClientResource = ({
       if (!isCreateAttachment(fileOrAttachment) && attachmentAdapter) {
         const operation = attachmentAddOperations.start();
         try {
-          await drainAdapterAdd(
+          await drainAttachmentAdd(
             attachmentAdapter.add({ file: fileOrAttachment }),
             (attachment) => {
               if (!attachmentAddOperations.accept(operation, attachment.id))
@@ -795,6 +739,17 @@ const useComposerClientResource = ({
       }
     },
     cancel: () => {
+      // An edit session ends here, so its in-flight adapter adds must not
+      // land in a later session; the thread composer's cancel stops the run
+      // and leaves the draft (and its pending adds) alone.
+      if (type === "edit") {
+        attachmentAddOperations.cancelAll();
+        const removed = attachmentsRef.current;
+        setAttachments([]);
+        removePendingAttachments(removed).catch((error) => {
+          console.error("Failed to remove cancelled edit attachments", error);
+        });
+      }
       onCancel?.();
       if (type === "edit") setIsEditing(false);
     },
@@ -1085,7 +1040,7 @@ const useExternalThread = ({
     }));
 
     return {
-      isEmpty: messages.length === 0,
+      isEmpty: messages.length === 0 && !isLoading,
       isDisabled: false,
       isLoading,
       isRunning,

package/src/store/clients/single-thread-list.ts

@@ -93,7 +93,10 @@ const useSingleThreadList = ({
         !(
           typeof selector === "object" &&
           "index" in selector &&
-          selector.index === 0
+          selector.index === 0 &&
+          // Index selectors address their archived/regular subset, and the
+          // archived subset here is always empty.
+          !selector.archived
         )
       ) {
         throw new Error(

package/src/store/clients/suggestions.test.ts

@@ -0,0 +1,31 @@
+import { useState } from "react";
+import { createTapRoot, flushTapSync, useResource } from "@assistant-ui/tap";
+import { describe, expect, it } from "vitest";
+import { Suggestions, type SuggestionConfig } from "./suggestions";
+
+describe("Suggestions", () => {
+  it("updates when the configured suggestions change", () => {
+    let setSuggestions!: (suggestions: SuggestionConfig[]) => void;
+    const root = createTapRoot(function SuggestionsRoot() {
+      const [suggestions, setValue] = useState<SuggestionConfig[]>([
+        "account-a",
+      ]);
+      setSuggestions = setValue;
+      return useResource(Suggestions(suggestions));
+    });
+
+    try {
+      expect(root.getValue().getState().suggestions[0]?.prompt).toBe(
+        "account-a",
+      );
+
+      flushTapSync(() => setSuggestions(["account-b"]));
+
+      expect(root.getValue().getState().suggestions[0]?.prompt).toBe(
+        "account-b",
+      );
+    } finally {
+      root.unmount();
+    }
+  });
+});

package/src/store/clients/suggestions.ts

@@ -1,4 +1,4 @@
-import { useMemo, useState } from "react";
+import { useMemo } from "react";
 import { resource, withKey } from "@assistant-ui/tap";
 import type { ClientOutput } from "@assistant-ui/store";
 import { useClientLookup } from "@assistant-ui/store/client";
@@ -40,26 +40,25 @@ const useSuggestionsClient = (
 const useStaticSuggestions = (
   suggestions?: SuggestionConfig[],
 ): ClientOutput<"suggestions"> => {
-  const [state] = useState<SuggestionsState>(() => {
-    const normalizedSuggestions = (suggestions ?? []).map((s) => {
-      if (typeof s === "string") {
+  const state = useMemo<SuggestionsState>(
+    () => ({
+      suggestions: (suggestions ?? []).map((s) => {
+        if (typeof s === "string") {
+          return {
+            title: s,
+            label: "",
+            prompt: s,
+          };
+        }
         return {
-          title: s,
-          label: "",
-          prompt: s,
+          title: s.title,
+          label: s.label,
+          prompt: s.prompt,
         };
-      }
-      return {
-        title: s.title,
-        label: s.label,
-        prompt: s.prompt,
-      };
-    });
-
-    return {
-      suggestions: normalizedSuggestions,
-    };
-  });
+      }),
+    }),
+    [suggestions],
+  );
 
   return useSuggestionsClient(state);
 };

package/src/store/runtime-clients/handle-runtime-action.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it, vi } from "vitest";
+import { ThreadListAdapterChangedError } from "../../runtimes/remote-thread-list/adapter-changed";
+import { handleRuntimeAction } from "./handle-runtime-action";
+
+describe("handleRuntimeAction", () => {
+  it("does not log a silent adapter-change cancellation", async () => {
+    const error = new ThreadListAdapterChangedError();
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    try {
+      await expect(
+        handleRuntimeAction("thread list archive", () => Promise.reject(error)),
+      ).rejects.toBe(error);
+      expect(consoleError).not.toHaveBeenCalled();
+    } finally {
+      consoleError.mockRestore();
+    }
+  });
+
+  it("logs an ordinary rejection", async () => {
+    const error = new Error("archive failed");
+    const consoleError = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    try {
+      await expect(
+        handleRuntimeAction("thread list archive", () => Promise.reject(error)),
+      ).rejects.toBe(error);
+      expect(consoleError).toHaveBeenCalledExactlyOnceWith(
+        "[assistant-ui] thread list archive failed:",
+        error,
+      );
+    } finally {
+      consoleError.mockRestore();
+    }
+  });
+});

package/src/store/runtime-clients/handle-runtime-action.ts

@@ -1,3 +1,5 @@
+import { isSilentRuntimeAction } from "../../utils/silent-runtime-action";
+
 export const handleRuntimeAction = (
   label: string,
   execute: () => Promise<void>,
@@ -5,6 +7,7 @@ export const handleRuntimeAction = (
   const task = execute();
 
   void task.catch((error: unknown) => {
+    if (isSilentRuntimeAction(error)) return;
     console.error(`[assistant-ui] ${label} failed:`, error);
   });
   return task;

package/src/store/scopes/message.ts

@@ -19,7 +19,7 @@ export type MessageState = ThreadMessage & {
    * @example
    * ```ts
    * import { WebSpeechSynthesisAdapter } from "@assistant-ui/react";
-   * import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+   * import { useChatRuntime } from "@assistant-ui/ai-sdk";
    *
    * const runtime = useChatRuntime({
    *   adapters: {

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

@@ -1,14 +1,7 @@
-import type { FileMessagePart, TextMessagePart } from "../../types/message";
 import type { QueuePlacement } from "../../runtime/queue/external-thread-queue-adapter";
+import type { QueueItemState } from "../../runtime/queue/queue-item";
 
-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 { QueueItemState };
 
 export type QueueItemMethods = {
   getState(): QueueItemState;