@assistant-ui/core 0.3.15 → 0.3.17

package/src/react/runtimes/useRemoteThreadListRuntime.concurrent.test.tsx

@@ -0,0 +1,216 @@
+// @vitest-environment jsdom
+
+import { act, render } from "@testing-library/react";
+import { startTransition, Suspense, type ReactNode } from "react";
+import { describe, expect, it, vi } from "vitest";
+import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
+import type { AppendMessage } from "../../types/message";
+import { makeAdapter } from "../../tests/remote-thread-list-test-helpers";
+import { AssistantRuntimeProvider } from "../AssistantRuntimeProvider";
+import { useExternalStoreRuntime } from "./useExternalStoreRuntime";
+import { useRemoteThreadListRuntime } from "./useRemoteThreadListRuntime";
+
+const EMPTY_MESSAGES: readonly never[] = [];
+
+const userMessage = (text: string): AppendMessage => ({
+  parentId: null,
+  sourceId: null,
+  runConfig: {},
+  role: "user",
+  content: [{ type: "text", text }],
+  attachments: [],
+  metadata: { custom: {} },
+  createdAt: new Date(),
+  startRun: true,
+});
+
+const getThreadCore = (runtime: AssistantRuntime) =>
+  (
+    runtime.thread as unknown as {
+      __internal_threadBinding: {
+        getState(): { append(message: AppendMessage): Promise<void> };
+      };
+    }
+  ).__internal_threadBinding.getState();
+
+const createHarness = ({ stableHook = false } = {}) => {
+  const adapter = makeAdapter();
+  const onNewA = vi.fn(async () => {});
+  const onNewB = vi.fn(async () => {});
+  const renderB = vi.fn();
+  const renderThreadRuntime = vi.fn();
+  const runtimeRef: { current: AssistantRuntime | null } = { current: null };
+  const pending = new Promise<never>(() => {});
+  let suspend = false;
+
+  const Blocker = () => {
+    if (suspend) throw pending;
+    return null;
+  };
+  // Every shipped adapter passes a fresh function expression, so a hoisted
+  // variant is the only way to exercise an unchanged published hook.
+  const useHoistedThreadRuntime = () => {
+    renderThreadRuntime();
+    return useExternalStoreRuntime({
+      messages: EMPTY_MESSAGES,
+      onNew: onNewA,
+    });
+  };
+  const App = ({
+    onNew,
+    children,
+  }: {
+    onNew: typeof onNewA;
+    children?: ReactNode;
+  }) => {
+    if (onNew === onNewB) renderB();
+    const useThreadRuntime = stableHook
+      ? useHoistedThreadRuntime
+      : () => {
+          renderThreadRuntime();
+          return useExternalStoreRuntime({ messages: EMPTY_MESSAGES, onNew });
+        };
+    const runtime = useRemoteThreadListRuntime({
+      adapter,
+      runtimeHook: useThreadRuntime,
+    });
+    runtimeRef.current = runtime;
+    return (
+      <AssistantRuntimeProvider runtime={runtime}>
+        {children ?? <Blocker />}
+      </AssistantRuntimeProvider>
+    );
+  };
+
+  return {
+    App,
+    onNewA,
+    onNewB,
+    renderB,
+    renderThreadRuntime,
+    runtimeRef,
+    suspend: () => {
+      suspend = true;
+    },
+  };
+};
+
+describe("useRemoteThreadListRuntime concurrent options", () => {
+  it("keeps new threads on the committed runtime hook", async () => {
+    const { App, onNewA, onNewB, renderB, runtimeRef, suspend } =
+      createHarness();
+    const view = render(
+      <Suspense fallback={null}>
+        <App onNew={onNewA} />
+      </Suspense>,
+    );
+
+    await act(async () => {
+      await getThreadCore(runtimeRef.current!).append(userMessage("first"));
+    });
+
+    act(() => {
+      suspend();
+      startTransition(() =>
+        view.rerender(
+          <Suspense fallback={null}>
+            <App onNew={onNewB} />
+          </Suspense>,
+        ),
+      );
+    });
+    expect(renderB).toHaveBeenCalled();
+
+    await act(async () => {
+      await runtimeRef.current!.threads.switchToNewThread();
+      await getThreadCore(runtimeRef.current!).append(userMessage("second"));
+    });
+
+    expect(onNewA).toHaveBeenCalledTimes(2);
+    expect(onNewB).not.toHaveBeenCalled();
+  });
+
+  it("publishes runtime hook changes after a committed render", async () => {
+    const { App, onNewA, onNewB, runtimeRef } = createHarness();
+    const view = render(<App onNew={onNewA} />);
+
+    await act(async () => {
+      await getThreadCore(runtimeRef.current!).append(userMessage("first"));
+    });
+
+    view.rerender(<App onNew={onNewB} />);
+    await act(async () => {
+      await getThreadCore(runtimeRef.current!).append(userMessage("second"));
+    });
+
+    expect(onNewA).toHaveBeenCalledTimes(1);
+    expect(onNewB).toHaveBeenCalledTimes(1);
+  });
+
+  it("costs two passes per provider commit in the documented shape", async () => {
+    // Fresh children on every render, as the AssistantRuntimeProvider JSDoc
+    // example does, so its memo does not block: the host renders once against
+    // the previously committed hook, then the publish adds the corrective pass.
+    const { App, onNewA, renderThreadRuntime } = createHarness();
+    const view = render(<App onNew={onNewA} />);
+
+    await act(async () => {});
+    renderThreadRuntime.mockClear();
+
+    await act(async () => {
+      view.rerender(<App onNew={onNewA} />);
+    });
+
+    expect(renderThreadRuntime).toHaveBeenCalledTimes(2);
+  });
+
+  it("costs one pass when the provider memo blocks the host render", async () => {
+    const { App, onNewA, renderThreadRuntime } = createHarness();
+    const children = <div />;
+    const view = render(<App onNew={onNewA}>{children}</App>);
+
+    await act(async () => {});
+    renderThreadRuntime.mockClear();
+
+    await act(async () => {
+      view.rerender(<App onNew={onNewA}>{children}</App>);
+    });
+
+    expect(renderThreadRuntime).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not re-run thread runtimes when the published hook is unchanged", async () => {
+    const { App, onNewA, renderThreadRuntime } = createHarness({
+      stableHook: true,
+    });
+    const children = <div />;
+    const view = render(<App onNew={onNewA}>{children}</App>);
+
+    await act(async () => {});
+    renderThreadRuntime.mockClear();
+
+    await act(async () => {
+      view.rerender(<App onNew={onNewA}>{children}</App>);
+    });
+
+    expect(renderThreadRuntime).not.toHaveBeenCalled();
+  });
+
+  it("gives a thread created after an options change the committed hook", async () => {
+    const { App, onNewA, onNewB, runtimeRef } = createHarness();
+    const view = render(<App onNew={onNewA} />);
+    await act(async () => {});
+
+    await act(async () => {
+      view.rerender(<App onNew={onNewB} />);
+    });
+
+    await act(async () => {
+      await runtimeRef.current!.threads.switchToNewThread();
+      await getThreadCore(runtimeRef.current!).append(userMessage("first"));
+    });
+
+    expect(onNewB).toHaveBeenCalledTimes(1);
+    expect(onNewA).not.toHaveBeenCalled();
+  });
+});

package/src/react/runtimes/useRemoteThreadListRuntime.ts

@@ -12,6 +12,8 @@ import type { RemoteThreadListOptions } from "../../runtimes/remote-thread-list/
 import type { AssistantRuntimeCore } from "../../runtime/interfaces/assistant-runtime-core";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 import { RemoteThreadListThreadListRuntimeCore } from "./RemoteThreadListThreadListRuntimeCore";
+import { WritableSubscribable } from "../../subscribable/subscribable";
+import { useSubscribable } from "../../store/runtime-clients/useSubscribable";
 import { useAui } from "@assistant-ui/store";
 
 class RemoteThreadListRuntimeCore
@@ -48,14 +50,30 @@ const useRemoteThreadListRuntimeImpl = (
 export const useRemoteThreadListRuntime = (
   options: RemoteThreadListOptions,
 ): AssistantRuntime => {
-  const runtimeHookRef = useRef(options.runtimeHook);
-  runtimeHookRef.current = options.runtimeHook;
+  const [runtimeHookStore] = useState(
+    () => new WritableSubscribable(options.runtimeHook),
+  );
+  useEffect(() => {
+    runtimeHookStore.setState(options.runtimeHook);
+  }, [runtimeHookStore, options.runtimeHook]);
 
   const initialThreadIdRef = useRef(options.initialThreadId);
 
-  const stableRuntimeHook = useCallback(() => {
-    return runtimeHookRef.current();
-  }, []);
+  // Thread resources subscribe to the store rather than reading a ref, so a
+  // hook published at commit reaches exactly the resources that use it and an
+  // abandoned render publishes nothing. The store pins its server snapshot to
+  // the constructor value for hydration, which tap reads on any never-mounted
+  // fiber, so the live state serves as the server snapshot here.
+  const stableRuntimeHook = useCallback(
+    function useCommittedRuntimeHook() {
+      return useSubscribable({
+        subscribe: runtimeHookStore.subscribe,
+        getState: runtimeHookStore.getState,
+        getServerSnapshot: runtimeHookStore.getState,
+      })();
+    },
+    [runtimeHookStore],
+  );
 
   const onThreadIdChange = useEffectEvent((threadId: string | undefined) => {
     options.onThreadIdChange?.(threadId);
@@ -91,7 +109,7 @@ export const useRemoteThreadListRuntime = (
 
     // If allowNesting is true and already inside a thread list context,
     // just call the runtimeHook directly (no-op behavior)
-    return stableRuntimeHook();
+    return options.runtimeHook();
   }
 
   const runtime = useRemoteThreadListRuntimeImpl(stableOptions);

package/src/react/types/MessagePartComponentTypes.ts

@@ -83,10 +83,14 @@ export type ToolCallMessagePartProps<
     /**
      * Responds to a server-side tool approval gate. Only valid while
      * `approval` is set on the part, `approval.approved === undefined`, and
-     * no `approval.resolution` is recorded. Accepts a boolean decision or the
-     * id of one of `approval.options`; option kinds resolve to the boolean.
+     * no `approval.resolution` is recorded. Accepts a boolean decision, the
+     * id of one of `approval.options` (option kinds resolve to the boolean),
+     * or a free-form answer when the request accepts one.
+     *
+     * Resolves once the runtime has accepted the response, and rejects when
+     * it could not be recorded, so the controls can stay retryable.
      */
-    respondToApproval: (response: ToolApprovalResponse) => void;
+    respondToApproval: (response: ToolApprovalResponse) => Promise<void>;
   };
 
 /** Component used to render a tool-call message part. */

package/src/react/types/scopes/tools.ts

@@ -1,5 +1,6 @@
 import type { ToolCallMessagePartComponent } from "../MessagePartComponentTypes";
 import type { Unsubscribe } from "../../..";
+import type { ToolCallText } from "../../../model-context/tool-call-text";
 
 export type McpAppResourceOutput = {
   readonly render: ToolCallMessagePartComponent;
@@ -12,6 +13,7 @@ export type McpAppResourceOutput = {
  */
 type ToolRegistration = {
   readonly render: ToolCallMessagePartComponent;
+  readonly renderText?: ToolCallText<any, any, unknown> | undefined;
   /** Whether this UI renders standalone, outside the chain-of-thought trace. */
   readonly standalone: boolean;
 };

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

@@ -3,7 +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 type { QueueItemState } from "../queue/queue-item";
 import type { QueuePlacement } from "../queue/external-thread-queue-adapter";
 import {
   LazyMemoizeSubject,

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

@@ -28,7 +28,7 @@ type MessagePartSnapshotBinding = SubscribableWithState<
 export type MessagePartRuntime = {
   addToolResult(result: any | ToolResponse<any>): void;
   resumeToolCall(payload: unknown): void;
-  respondToToolApproval(response: ToolApprovalResponse): void;
+  respondToToolApproval(response: ToolApprovalResponse): Promise<void>;
 
   readonly path: MessagePartRuntimePath;
   getState(): MessagePartState;
@@ -113,7 +113,7 @@ export class MessagePartRuntimeImpl implements MessagePartRuntime {
     });
   }
 
-  public respondToToolApproval(response: ToolApprovalResponse) {
+  public respondToToolApproval(response: ToolApprovalResponse): Promise<void> {
     const state = this.contentBinding.getState();
     if (!state) throw new Error("Message part is not available");
 
@@ -131,7 +131,7 @@ export class MessagePartRuntimeImpl implements MessagePartRuntime {
 
     if (!this.threadApi) throw new Error("Thread API is not available");
 
-    this.threadApi
+    return this.threadApi
       .getState()
       .respondToToolApproval(
         resolveToolApprovalResponse(state.approval, response),

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

@@ -1,6 +1,9 @@
 import { describe, expect, it } from "vitest";
 import type { CompleteAttachment } from "../../types/attachment";
-import type { ThreadAssistantMessage } from "../../types/message";
+import type {
+  ThreadAssistantMessage,
+  ToolCallMessagePartStatus,
+} from "../../types/message";
 import type { ThreadRuntimeCoreBinding } from "./thread-runtime";
 import {
   MessageRuntimeImpl,
@@ -173,6 +176,30 @@ describe("toMessagePartStatus", () => {
     });
   });
 
+  it("preserves incomplete tool-call status on unresolved tool calls", () => {
+    const incompleteStatus = {
+      type: "incomplete",
+      reason: "tool-calls",
+      error: { message: "Tool execution did not finish" },
+    } satisfies ToolCallMessagePartStatus;
+    const message = createAssistantMessage(
+      [
+        {
+          type: "tool-call",
+          toolCallId: "call-1",
+          toolName: "weather",
+          args: {},
+          argsText: "{}",
+        },
+      ],
+      incompleteStatus,
+    );
+
+    expect(toMessagePartStatus(message, 0, message.content[0]!)).toEqual(
+      incompleteStatus,
+    );
+  });
+
   it.each([
     ["false", false],
     ["zero", 0],

package/src/runtime/api/thread-list-runtime.ts

@@ -7,7 +7,10 @@ import {
   SKIP_UPDATE,
   ShallowMemoizeSubject,
 } from "../../subscribable/subscribable";
-import type { ThreadListRuntimeCore } from "../interfaces/thread-list-runtime-core";
+import type {
+  ThreadListRuntimeCore,
+  ThreadListRuntimeEvent,
+} from "../interfaces/thread-list-runtime-core";
 import {
   type ThreadListItemRuntime,
   ThreadListItemRuntimeImpl,
@@ -21,6 +24,7 @@ import {
 } from "./thread-runtime";
 
 const RESOLVED_PROMISE = Promise.resolve();
+const NOOP_UNSUBSCRIBE = () => {};
 
 export type ThreadListState = {
   readonly mainThreadId: string;
@@ -57,6 +61,16 @@ export type ThreadListRuntime = {
   ): Promise<void>;
   switchToNewThread(): Promise<void>;
 
+  /**
+   * Observes lifecycle events on every thread this list keeps alive, so an
+   * event that fires while its thread is not selected stays observable. Thread
+   * lists that mount only the main thread never emit; their main thread's
+   * runtime is observed directly.
+   */
+  unstable_subscribeThreadEvents(
+    callback: (event: ThreadListRuntimeEvent) => void,
+  ): Unsubscribe;
+
   getLoadThreadsPromise(): Promise<void>;
   reload(): Promise<void>;
   /**
@@ -171,6 +185,8 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
   protected __internal_bindMethods() {
     this.switchToThread = this.switchToThread.bind(this);
     this.switchToNewThread = this.switchToNewThread.bind(this);
+    this.unstable_subscribeThreadEvents =
+      this.unstable_subscribeThreadEvents.bind(this);
     this.getLoadThreadsPromise = this.getLoadThreadsPromise.bind(this);
     this.reload = this.reload.bind(this);
     this.reloadMainThread = this.reloadMainThread.bind(this);
@@ -194,6 +210,14 @@ export class ThreadListRuntimeImpl implements ThreadListRuntime {
     return this._core.switchToNewThread();
   }
 
+  public unstable_subscribeThreadEvents(
+    callback: (event: ThreadListRuntimeEvent) => void,
+  ): Unsubscribe {
+    return (
+      this._core.unstable_subscribeThreadEvents?.(callback) ?? NOOP_UNSUBSCRIBE
+    );
+  }
+
   public getLoadThreadsPromise(): Promise<void> {
     return this._core.getLoadThreadsPromise();
   }

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

@@ -26,21 +26,17 @@ import type {
 } 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,
-} from "../../store/scopes/queue-item";
+import { EMPTY_QUEUE_ITEMS, type QueueItemState } from "../queue/queue-item";
 import { generateId } from "../../utils/id";
 import { notifyEventListeners } from "../../utils/notify-event-listeners";
+import {
+  AttachmentAddOperations,
+  drainAttachmentAdd,
+} from "../utils/attachment-add-operations";
 
 const isAttachmentComplete = (a: Attachment): a is CompleteAttachment =>
   a.status.type === "complete";
 
-type AttachmentAddOperation = {
-  cancelled: boolean;
-  attachmentIds: Set<string>;
-};
-
 export abstract class BaseComposerRuntimeCore
   extends BaseSubscribable
   implements ComposerRuntimeCore
@@ -152,21 +148,14 @@ export abstract class BaseComposerRuntimeCore
   protected _isSending = false;
   private _removedDuringSend = new Set<string>();
   private _sendGeneration = 0;
-  private _attachmentAddOperations = new Set<AttachmentAddOperation>();
+  private _attachmentAddOperations = new AttachmentAddOperations();
 
   private _cancelAttachmentAdd(attachmentId: string) {
-    for (const operation of [...this._attachmentAddOperations]) {
-      if (!operation.attachmentIds.has(attachmentId)) continue;
-      operation.cancelled = true;
-      this._attachmentAddOperations.delete(operation);
-    }
+    this._attachmentAddOperations.cancel(attachmentId);
   }
 
   private _cancelAllAttachmentAdds() {
-    for (const operation of this._attachmentAddOperations) {
-      operation.cancelled = true;
-    }
-    this._attachmentAddOperations.clear();
+    this._attachmentAddOperations.cancelAll();
   }
 
   private _emptyTextAndAttachments() {
@@ -466,16 +455,10 @@ export abstract class BaseComposerRuntimeCore
       throw err;
     }
 
-    const operation: AttachmentAddOperation = {
-      cancelled: false,
-      attachmentIds: new Set(),
-    };
-    const operations = this._attachmentAddOperations;
-    operations.add(operation);
+    const operation = this._attachmentAddOperations.start();
     const upsertAttachment = (a: PendingAttachment) => {
-      if (operation.cancelled) return false;
+      if (!this._attachmentAddOperations.accept(operation, a.id)) return false;
 
-      operation.attachmentIds.add(a.id);
       const idx = this._attachments.findIndex(
         (attachment) => attachment.id === a.id,
       );
@@ -494,18 +477,15 @@ export abstract class BaseComposerRuntimeCore
     };
     let lastAttachment: PendingAttachment | undefined;
     try {
-      const promiseOrGenerator = adapter.add({ file: fileOrAttachment });
-      if (Symbol.asyncIterator in promiseOrGenerator) {
-        for await (const r of promiseOrGenerator) {
-          lastAttachment = r;
-          if (!upsertAttachment(r)) break;
-        }
-      } else {
-        lastAttachment = await promiseOrGenerator;
-        upsertAttachment(lastAttachment);
-      }
+      await drainAttachmentAdd(
+        adapter.add({ file: fileOrAttachment }),
+        (attachment) => {
+          lastAttachment = attachment;
+          return upsertAttachment(attachment);
+        },
+      );
     } catch (e) {
-      if (operation.cancelled) return;
+      if (this._attachmentAddOperations.isCancelled(operation)) return;
       if (lastAttachment) {
         upsertAttachment({
           ...lastAttachment,
@@ -524,10 +504,10 @@ export abstract class BaseComposerRuntimeCore
       );
       throw e;
     } finally {
-      operations.delete(operation);
+      this._attachmentAddOperations.finish(operation);
     }
 
-    if (operation.cancelled) return;
+    if (this._attachmentAddOperations.isCancelled(operation)) return;
     if (
       lastAttachment?.status.type === "incomplete" &&
       lastAttachment.status.reason === "error"