@assistant-ui/react 0.14.27 → 0.14.29

package/src/legacy-runtime/cloud/auiV0.ts

@@ -7,6 +7,7 @@ import type {
   SourceProviderMetadata,
   ThreadMessage,
   TextMessagePart,
+  ToolApprovalOption,
   Unstable_AudioMessagePart,
 } from "@assistant-ui/core";
 import { fromThreadMessageLike } from "../runtime-cores/external-store/ThreadMessageLike";
@@ -18,6 +19,16 @@ import type {
 } from "assistant-stream/utils";
 import type { ExportedMessageRepositoryItem } from "../runtime-cores/utils/MessageRepository";
 
+type AuiV0ToolApproval = {
+  readonly id: string;
+  readonly approved?: boolean;
+  readonly reason?: string;
+  readonly isAutomatic?: boolean;
+  readonly options?: readonly ToolApprovalOption[];
+  readonly optionId?: string;
+  readonly resolution?: "cancelled" | "expired";
+};
+
 type AuiV0MessagePart =
   | {
       readonly type: "text";
@@ -51,6 +62,7 @@ type AuiV0MessagePart =
       readonly args: ReadonlyJSONObject;
       readonly result?: ReadonlyJSONValue;
       readonly isError?: true;
+      readonly approval?: AuiV0ToolApproval;
     }
   | {
       readonly type: "tool-call";
@@ -59,6 +71,7 @@ type AuiV0MessagePart =
       readonly argsText: string;
       readonly result?: ReadonlyJSONValue;
       readonly isError?: true;
+      readonly approval?: AuiV0ToolApproval;
     }
   | {
       readonly type: "image";
@@ -216,6 +229,7 @@ export function auiV0Encode(message: ThreadMessage): AuiV0Message {
               ? { result: part.result as ReadonlyJSONValue }
               : undefined),
             ...(part.isError ? { isError: true } : undefined),
+            ...(part.approval ? { approval: part.approval } : undefined),
           };
         }
 

package/src/legacy-runtime/runtime-cores/assistant-transport/commandQueue.ts

@@ -56,7 +56,10 @@ export const useCommandQueue = (opts: { onQueue: () => void }) => {
   }, []);
 
   return {
-    state: queueStateRef.current,
+    // live getter — callbacks firing between renders must not see a stale snapshot
+    get state() {
+      return queueStateRef.current;
+    },
     enqueue,
     flush,
     markDelivered,

package/src/legacy-runtime/runtime-cores/assistant-transport/runManager.ts

@@ -1,4 +1,4 @@
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { useLatestRef } from "./useLatestRef";
 
 export type RunManager = Readonly<{
@@ -7,6 +7,8 @@ export type RunManager = Readonly<{
   cancel: () => void;
 }>;
 
+const disposeReason = Symbol("assistant-transport-dispose");
+
 export function useRunManager(config: {
   onRun: (signal: AbortSignal) => Promise<void>;
   onFinish?: (() => void) | undefined;
@@ -16,6 +18,7 @@ export function useRunManager(config: {
   const [isRunning, setIsRunning] = useState(false);
   const stateRef = useRef({
     pending: false,
+    disposed: false,
     abortController: null as AbortController | null,
   });
   const onRunRef = useLatestRef(config.onRun);
@@ -29,29 +32,42 @@ export function useRunManager(config: {
     const ac = new AbortController();
     stateRef.current.abortController = ac;
 
+    // The dispose marker rides on the abort reason so a settling run detects
+    // its own disposal even after an effect cycle re-arms the manager.
+    const disposeAborted = () => ac.signal.reason === disposeReason;
+
     queueMicrotask(async () => {
       try {
-        await onRunRef.current(ac.signal);
+        if (!disposeAborted()) {
+          await onRunRef.current(ac.signal);
+        }
       } catch (error) {
-        stateRef.current.pending = false;
-        if (ac.signal.aborted) {
-          onCancelRef.current?.();
-        } else {
-          await onErrorRef.current?.(error as Error);
+        if (!disposeAborted() && !stateRef.current.disposed) {
+          stateRef.current.pending = false;
+          if (ac.signal.aborted) {
+            onCancelRef.current?.();
+          } else {
+            await onErrorRef.current?.(error as Error);
+          }
         }
       } finally {
-        onFinishRef.current?.();
-        if (stateRef.current.pending) {
+        if (!disposeAborted() && !stateRef.current.disposed) {
+          onFinishRef.current?.();
+        }
+        if (!stateRef.current.disposed && stateRef.current.pending) {
           startRun();
         } else {
           setIsRunning(false);
-          stateRef.current.abortController = null;
+          if (stateRef.current.abortController === ac) {
+            stateRef.current.abortController = null;
+          }
         }
       }
     });
   }, [onRunRef, onFinishRef, onErrorRef, onCancelRef]);
 
   const schedule = useCallback(() => {
+    if (stateRef.current.disposed) return;
     if (stateRef.current.abortController) {
       // Coalesce multiple schedules while running into a single follow-up run.
       stateRef.current.pending = true;
@@ -60,6 +76,17 @@ export function useRunManager(config: {
     startRun();
   }, [startRun]);
 
+  // Strict-mode effects run setup / cleanup / setup on the same instance;
+  // arming on setup undoes the cleanup's dispose.
+  useEffect(() => {
+    stateRef.current.disposed = false;
+    return () => {
+      stateRef.current.disposed = true;
+      stateRef.current.pending = false;
+      stateRef.current.abortController?.abort(disposeReason);
+    };
+  }, []);
+
   const cancel = useCallback(() => {
     stateRef.current.pending = false;
     stateRef.current.abortController?.abort();

package/src/legacy-runtime/runtime-cores/assistant-transport/transport-delivery.test.tsx

@@ -0,0 +1,79 @@
+// @vitest-environment jsdom
+
+import { act, render, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { FC } from "react";
+import { useAssistantTransportRuntime } from "./useAssistantTransportRuntime";
+import type { AssistantRuntime } from "../../runtime/AssistantRuntime";
+import { AssistantRuntimeProvider } from "../../../context";
+import type {
+  AssistantTransportCommand,
+  AssistantTransportStateConverter,
+} from "./types";
+
+const emptySuccessfulResponse = () =>
+  new Response(
+    new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.close();
+      },
+    }),
+    { status: 200 },
+  );
+
+const setupRuntime = () => {
+  const fetchMock = vi.fn(async () => emptySuccessfulResponse());
+  vi.stubGlobal("fetch", fetchMock);
+
+  const pendingRef: { current: AssistantTransportCommand[] } = { current: [] };
+  const converter: AssistantTransportStateConverter<Record<string, never>> = (
+    _state,
+    { pendingCommands, isSending },
+  ) => {
+    pendingRef.current = pendingCommands;
+    return { messages: [], isRunning: isSending };
+  };
+
+  const runtimeRef: { current: AssistantRuntime | null } = { current: null };
+  const App: FC = () => {
+    const runtime = useAssistantTransportRuntime({
+      initialState: {},
+      api: "http://localhost/api",
+      converter,
+      headers: {},
+    });
+    runtimeRef.current = runtime;
+    return (
+      <AssistantRuntimeProvider runtime={runtime}>
+        {null}
+      </AssistantRuntimeProvider>
+    );
+  };
+
+  return { App, fetchMock, pendingRef, runtimeRef };
+};
+
+describe("assistant transport delivery contracts", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("clears in-transit commands when a run succeeds without state chunks", async () => {
+    const { App, fetchMock, pendingRef, runtimeRef } = setupRuntime();
+
+    await act(async () => {
+      render(<App />);
+    });
+    await waitFor(() => expect(runtimeRef.current).not.toBeNull());
+
+    await act(async () => {
+      runtimeRef.current!.thread.append("m1");
+    });
+
+    await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1));
+    await waitFor(() =>
+      expect(runtimeRef.current!.thread.getState().isRunning).toBe(false),
+    );
+    await waitFor(() => expect(pendingRef.current).toHaveLength(0));
+  });
+});

package/src/legacy-runtime/runtime-cores/assistant-transport/transport-parentid.test.tsx

@@ -0,0 +1,97 @@
+// @vitest-environment jsdom
+
+import { act, render, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { FC } from "react";
+import { useAssistantTransportRuntime } from "./useAssistantTransportRuntime";
+import type { AssistantRuntime } from "../../runtime/AssistantRuntime";
+import { AssistantRuntimeProvider } from "../../../context";
+import type {
+  AssistantTransportCommand,
+  AssistantTransportStateConverter,
+} from "./types";
+
+const emptySuccessfulResponse = () =>
+  new Response(
+    new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.close();
+      },
+    }),
+    { status: 200 },
+  );
+
+const setupRuntime = () => {
+  const requestBodies: Record<string, unknown>[] = [];
+  const fetchMock = vi.fn(
+    async (_url: RequestInfo | URL, init?: RequestInit) => {
+      requestBodies.push(JSON.parse(init!.body as string));
+      return emptySuccessfulResponse();
+    },
+  );
+  vi.stubGlobal("fetch", fetchMock);
+
+  const converter: AssistantTransportStateConverter<Record<string, never>> = (
+    _state,
+    { isSending },
+  ) => ({ messages: [], isRunning: isSending });
+
+  const runtimeRef: { current: AssistantRuntime | null } = { current: null };
+  const App: FC = () => {
+    const runtime = useAssistantTransportRuntime({
+      initialState: {},
+      api: "http://localhost/api",
+      converter,
+      headers: {},
+    });
+    runtimeRef.current = runtime;
+    return (
+      <AssistantRuntimeProvider runtime={runtime}>
+        {null}
+      </AssistantRuntimeProvider>
+    );
+  };
+
+  return { App, fetchMock, requestBodies, runtimeRef };
+};
+
+describe("assistant transport parentId lifetime", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("consumes parentId per run: the append's run carries it, a later sendCommand run omits it", async () => {
+    const { App, fetchMock, requestBodies, runtimeRef } = setupRuntime();
+
+    await act(async () => {
+      render(<App />);
+    });
+    await waitFor(() => expect(runtimeRef.current).not.toBeNull());
+
+    await act(async () => {
+      runtimeRef.current!.thread.append("m1");
+    });
+
+    await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1));
+    await waitFor(() =>
+      expect(runtimeRef.current!.thread.getState().isRunning).toBe(false),
+    );
+    expect(Object.hasOwn(requestBodies[0]!, "parentId")).toBe(true);
+
+    const extras = runtimeRef.current!.thread.getState().extras as {
+      sendCommand: (command: AssistantTransportCommand) => void;
+    };
+    await act(async () => {
+      extras.sendCommand({
+        type: "add-tool-result",
+        toolCallId: "t1",
+        toolName: "tool",
+        result: {},
+        isError: false,
+      });
+    });
+
+    await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
+    expect(Object.hasOwn(requestBodies[1]!, "parentId")).toBe(false);
+  });
+});

package/src/legacy-runtime/runtime-cores/assistant-transport/transport-scheduling.test.ts

@@ -2,7 +2,7 @@
 
 import { act, renderHook, waitFor } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
-import { useRef } from "react";
+import { createElement, StrictMode, useRef } from "react";
 import { useCommandQueue } from "./commandQueue";
 import { useRunManager } from "./runManager";
 import type { AssistantTransportCommand } from "./types";
@@ -29,6 +29,8 @@ const useTransportSchedulingHarness = (
   opts: {
     onRun?: (signal: AbortSignal) => Promise<void> | void;
     onCancel?: (commands: AssistantTransportCommand[]) => void;
+    onError?: (commands: AssistantTransportCommand[]) => void;
+    onFinish?: () => void;
   } = {},
 ) => {
   const commandQueueRef = useRef<ReturnType<typeof useCommandQueue> | null>(
@@ -49,8 +51,10 @@ const useTransportSchedulingHarness = (
       opts.onCancel?.(commands);
     },
     onError: async () => {
-      // not needed for these contract tests
+      const queue = commandQueueRef.current!;
+      opts.onError?.([...queue.state.inTransit]);
     },
+    onFinish: () => opts.onFinish?.(),
   });
 
   const commandQueue = useCommandQueue({
@@ -121,6 +125,27 @@ describe("assistant transport scheduling contracts", () => {
     expect(result.current.runBatchesRef.current[0]).toHaveLength(1);
   });
 
+  it("onError receives the live in-transit commands at error time", async () => {
+    const seen: AssistantTransportCommand[][] = [];
+    const { result } = renderHook(() =>
+      useTransportSchedulingHarness({
+        onRun: () => {
+          throw new Error("network error");
+        },
+        onError: (commands) => seen.push(commands),
+      }),
+    );
+
+    act(() => {
+      result.current.commandQueue.enqueue(createMessageCommand("m1"));
+    });
+
+    // The flush that moved m1 into transit has not re-rendered yet when the
+    // error fires; the queue state must be read live, not from a render snapshot.
+    await waitFor(() => expect(seen).toHaveLength(1));
+    expect(seen[0]).toEqual([createMessageCommand("m1")]);
+  });
+
   it("cancel returns combined in-flight and queued commands", async () => {
     const onCancel = vi.fn();
     const { result } = renderHook(() =>
@@ -155,4 +180,90 @@ describe("assistant transport scheduling contracts", () => {
     });
     expect(onCancel.mock.calls[0]?.[0]).toHaveLength(2);
   });
+
+  it("unmount aborts the in-flight run without invoking callbacks", async () => {
+    let aborted = false;
+    const onCancel = vi.fn();
+    const onError = vi.fn();
+    const onFinish = vi.fn();
+    const { result, unmount } = renderHook(() =>
+      useTransportSchedulingHarness({
+        onRun: (signal) =>
+          new Promise<void>((_resolve, reject) => {
+            signal.addEventListener(
+              "abort",
+              () => {
+                aborted = true;
+                reject(new Error("aborted"));
+              },
+              { once: true },
+            );
+          }),
+        onCancel,
+        onError,
+        onFinish,
+      }),
+    );
+
+    act(() => {
+      result.current.commandQueue.enqueue(createMessageCommand("in-flight"));
+    });
+    await waitFor(() => {
+      expect(result.current.runBatchesRef.current).toHaveLength(1);
+    });
+
+    unmount();
+
+    expect(aborted).toBe(true);
+    await act(async () => {});
+    expect(onCancel).not.toHaveBeenCalled();
+    expect(onError).not.toHaveBeenCalled();
+    expect(onFinish).not.toHaveBeenCalled();
+  });
+
+  it("ignores schedules after unmount", async () => {
+    const { result, unmount } = renderHook(() =>
+      useTransportSchedulingHarness(),
+    );
+
+    unmount();
+    act(() => {
+      result.current.commandQueue.enqueue(createMessageCommand("late"));
+    });
+
+    await act(async () => {});
+    expect(result.current.runBatchesRef.current).toHaveLength(0);
+  });
+
+  it("survives StrictMode double-mounting", async () => {
+    const gate = createDeferred();
+    const onFinish = vi.fn();
+    const { result } = renderHook(
+      () =>
+        useTransportSchedulingHarness({ onRun: () => gate.promise, onFinish }),
+      { wrapper: ({ children }) => createElement(StrictMode, null, children) },
+    );
+
+    act(() => {
+      result.current.commandQueue.enqueue(createMessageCommand("m1"));
+    });
+    await waitFor(() => {
+      expect(result.current.runBatchesRef.current).toHaveLength(1);
+    });
+
+    // enqueued while the first run is in flight — must restart as a follow-up
+    act(() => {
+      result.current.commandQueue.enqueue(createMessageCommand("m2"));
+    });
+
+    gate.resolve();
+    await waitFor(() => {
+      expect(result.current.runBatchesRef.current).toHaveLength(2);
+    });
+    expect(result.current.runBatchesRef.current[1]).toHaveLength(1);
+    expect(onFinish).toHaveBeenCalled();
+    await waitFor(() => {
+      expect(result.current.runManager.isRunning).toBe(false);
+    });
+  });
 });

package/src/legacy-runtime/runtime-cores/assistant-transport/useAssistantTransport.spec.md

@@ -14,13 +14,15 @@ Command Scheduling
   - If a run is in progress: do not start another; mark that a follow-up run is pending.
   - When the current run ends: if commands were scheduled during the run, start a new run and publish them.
   - If no run is in progress: start a run immediately and flush commands to the server.
-- Scheduling uses `queueMicrotask` to coalesce multiple synchronous enqueues into a single run start.
+- A follow-up run that finds an empty queue is a no-op: no request is sent and no error is surfaced.
+- A resume run sends no commands; commands enqueued while it is pending or active are flushed in a follow-up run after it settles.
+- Runs execute on a `queueMicrotask`, so multiple synchronous enqueues coalesce into a single request: the first run's flush takes all of them, and the coalesced follow-up run no-ops.
 
 Command Queue
 
 `useCommandQueue({ onQueue() { runManager.schedule(); } })`
 
-- `enqueue(cmd)`: Adds a command to the queue. Calls `onQueue` when transitioning from empty → non-empty (coalesced via `queueMicrotask`).
+- `enqueue(cmd, { schedule? })`: Adds a command to the queue. Calls `onQueue` unless `schedule: false`.
 - `flush(): Command[]`: Returns all queued commands, moves them into `inTransit`, and clears the queue.
 - Internal state tracks `inTransit: Command[]` and `queued: Command[]`.
 
@@ -49,6 +51,11 @@ setInTransitCommands(commands);
         setInTransitCommands(EMPTY_ARRAY);
         setSnapshot(snapshot);
       }
+
+      // A run that completes successfully confirms delivery even when no
+      // state-changing chunk was observed — clear in-transit commands here
+      // as well.
+      setInTransitCommands(EMPTY_ARRAY);
     } catch (error) {
       // Do not restore commands. Surface error to onError for state update.
       callbacks.onError?.({
@@ -65,6 +72,7 @@ setInTransitCommands(commands);
 
 - `schedule()`: Starts immediately if idle, or schedules at most one follow-up run to start right after the current run.
 - `cancel()`: Aborts the active run via `signal` and clears any scheduled follow-up run. Does not restore commands.
+- Unmount aborts the active run via `signal`; no callbacks (`onCancel`, `onError`, `onFinish`) are invoked. StrictMode's setup/cleanup/setup effect cycle re-arms the manager.
 - `isRunning: boolean`: Indicates whether a run is currently active (internal to scheduling).
   UI-facing `isRunning` is controlled by the converter output (see Converter).
 - On cancellation, invoke `callbacks.onCancel?.({ commands, updateState })` where `commands` contains all pending work at the time of cancel: `[...inTransitCommands, ...queuedCommands]`. Note: after the first snapshot arrives, `inTransitCommands` are cleared to `[]`, so cancels after first byte will not include them.