@assistant-ui/react 0.11.6 → 0.11.7

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

@@ -0,0 +1,67 @@
+import { useCallback, useRef, useState } from "react";
+import { useLatestRef } from "./useLatestRef";
+
+export type RunManager = Readonly<{
+  isRunning: boolean;
+  schedule: () => void;
+  cancel: () => void;
+}>;
+
+export function useRunManager(config: {
+  onRun: (signal: AbortSignal) => Promise<void>;
+  onFinish?: (() => void) | undefined;
+  onError?: ((error: Error) => void) | undefined;
+}): RunManager {
+  const [isRunning, setIsRunning] = useState(false);
+  const stateRef = useRef({
+    pending: false,
+    abortController: null as AbortController | null,
+  });
+  const onRunRef = useLatestRef(config.onRun);
+  const onFinishRef = useLatestRef(config.onFinish);
+  const onErrorRef = useLatestRef(config.onError);
+
+  const startRun = useCallback(() => {
+    setIsRunning(true);
+    stateRef.current.pending = false;
+    const ac = new AbortController();
+    stateRef.current.abortController = ac;
+
+    queueMicrotask(async () => {
+      try {
+        await onRunRef.current(ac.signal);
+      } catch (error) {
+        stateRef.current.pending = false;
+        onErrorRef.current?.(error as Error);
+      } finally {
+        onFinishRef.current?.();
+        if (stateRef.current.pending) {
+          startRun();
+        } else {
+          setIsRunning(false);
+          stateRef.current.abortController = null;
+        }
+      }
+    });
+  }, [onRunRef, onFinishRef]);
+
+  const schedule = useCallback(() => {
+    if (stateRef.current.abortController) {
+      // Coalesce multiple schedules while running into a single follow-up run.
+      stateRef.current.pending = true;
+      return;
+    }
+    startRun();
+  }, [startRun]);
+
+  const cancel = useCallback(() => {
+    stateRef.current.pending = false;
+    stateRef.current.abortController?.abort();
+  }, []);
+
+  return {
+    isRunning,
+    schedule,
+    cancel,
+  };
+}

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

@@ -0,0 +1,96 @@
+import { ReadonlyJSONValue } from "assistant-stream/utils";
+import { ThreadMessage } from "../../../types";
+import { AttachmentAdapter, ThreadHistoryAdapter } from "..";
+
+// Message part types
+export type TextPart = {
+  readonly type: "text";
+  readonly text: string;
+};
+
+export type ImagePart = {
+  readonly type: "image";
+  readonly image: string;
+};
+
+export type UserMessagePart = TextPart | ImagePart;
+
+// Command types
+export type AddMessageCommand = {
+  readonly type: "add-message";
+  readonly message: {
+    readonly role: "user";
+    readonly parts: readonly UserMessagePart[];
+  };
+};
+
+export type AddToolResultCommand = {
+  readonly type: "add-tool-result";
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly result: ReadonlyJSONValue;
+  readonly isError: boolean;
+  readonly artifact?: ReadonlyJSONValue;
+};
+
+export type AssistantTransportCommand =
+  | AddMessageCommand
+  | AddToolResultCommand;
+
+// State types
+export type AssistantTransportState = {
+  readonly messages: readonly ThreadMessage[];
+  readonly isRunning: boolean;
+};
+
+export type AssistantTransportConnectionMetadata = {
+  pendingCommands: AssistantTransportCommand[];
+  isSending: boolean;
+};
+
+export type AssistantTransportStateConverter<T> = (
+  state: T,
+  connectionMetadata: AssistantTransportConnectionMetadata,
+) => AssistantTransportState;
+
+// Queue types
+export type CommandQueueState = {
+  queued: AssistantTransportCommand[];
+  inTransit: AssistantTransportCommand[];
+};
+
+// For now, queued items are plain commands (runConfig not supported)
+export type QueuedCommand = AssistantTransportCommand;
+
+// Task types
+
+// Options types
+export type HeadersValue = Record<string, string> | Headers;
+
+export type AssistantTransportOptions<T> = {
+  initialState: T;
+  api: string;
+  resumeApi?: string;
+  converter: AssistantTransportStateConverter<T>;
+  headers: HeadersValue | (() => Promise<HeadersValue>);
+  body?: object;
+  onResponse?: (response: Response) => void;
+  onFinish?: () => void;
+  onError?: (
+    error: Error,
+    params: {
+      commands: AssistantTransportCommand[];
+      updateState: (updater: (state: T) => T) => void;
+    },
+  ) => void;
+  onCancel?: (params: {
+    commands: AssistantTransportCommand[];
+    updateState: (updater: (state: T) => T) => void;
+  }) => void;
+  adapters?: {
+    attachments?: AttachmentAdapter | undefined;
+    history?: ThreadHistoryAdapter | undefined;
+  };
+};
+
+// (no task or stream-specific types needed in this module)

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

@@ -0,0 +1,125 @@
+useAssistantTransport
+
+Overview
+
+- Similar API as `useDataStreamRuntime`.
+- Built on an external-store runtime; the external store issues "commands".
+- Exactly one run is active at a time (single-flight).
+- Runs take queued commands as input and consume an assistant stream that yields state snapshots.
+- Every run flushes the entire command queue; a single run processes all pending commands.
+
+Command Scheduling
+
+- When commands are enqueued:
+  - 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.
+
+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`).
+- `flush(): Command[]`: Returns all queued commands, moves them into `inTransit`, and clears the queue.
+- Internal state tracks `inTransit: Command[]` and `queued: Command[]`.
+
+Run Manager
+
+`useRunManager({
+async onRun(signal) {
+const commands = commandQueue.flush();
+setInTransitCommands(commands);
+
+    try {
+      const response = await fetch(backendUrl, { signal });
+      const stream = response.body
+        .pipeThrough(new DataStreamDecoder())
+        .pipeThrough(
+          new AssistantMessageAccumulator({
+            initialMessage: createInitialMessage({
+              unstable_state: (state.state as ReadonlyJSONValue) ?? null,
+            }),
+          }),
+        );
+
+      for await (const snapshot of stream) {
+        // Clear in-transit commands after the first response chunk.
+        // Use a stable empty array to avoid unnecessary re-renders.
+        setInTransitCommands(EMPTY_ARRAY);
+        setSnapshot(snapshot);
+      }
+    } catch (error) {
+      // Do not restore commands. Surface error to onError for state update.
+      callbacks.onError?.({
+        error,
+        commands: getCurrentInTransitCommands(),
+        updateState(updater) {
+          setSnapshot((prev) => updater(prev));
+        },
+      });
+    }
+
+},
+})`
+
+- `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.
+- `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.
+- RunConfig is not supported for now; any provided run configuration is ignored.
+
+Converter
+
+`useConverter({
+  converter,
+  agentState,
+  queuedCommands,
+  inTransitCommands,
+})`
+
+- Reactive pattern: do not imperatively set converted state. Maintain an `agentState` snapshot variable (updated via stream), and compute the converted UI state with a memoized converter.
+  - Example: `const pending = [...inTransitCommands, ...queuedCommands]; const converted = useMemo(() => converter(agentState, { pendingCommands: pending, isSending }), [agentState, pending, isSending])`
+  - `isSending` should be sourced from the run manager’s `isRunning` flag.
+- Returns `AssistantTransportState` with `{ messages, isRunning }` derived from inputs via `converter`.
+- The converter controls UI `isRunning`. Typical mapping: `isRunning = isSending`. Advanced policies are allowed (e.g., extend running while reconciling, or suppress during background tool results).
+- Assistant stream deltas are applied by `AssistantMessageAccumulator`, which emits immutable full-state snapshots; no additional delta handling is required in the converter.
+
+Tool Invocations
+
+`useToolInvocations({
+  messages,
+  onResult(result) { commandQueue.enqueue(result); },
+})`
+
+- Uses a ToolCall differ to diff tool calls across successive snapshots (e.g., ToolCallDiffer).
+- When a tool call’s argsText transitions from incomplete → complete and `result` is undefined, synthesize a tool-execution event and enqueue an `add-tool-result` command via `onResult`.
+- `onResult` is for frontend function calling (client-side tool calls producing results to enqueue).
+- No return value.
+
+External Store Runtime Bridge
+
+`useExternalStoreRuntime({
+  isRunning,
+  messages,
+  onNew(command) { commandQueue.enqueue(command); },
+  onCancel() { runManager.cancel(); },
+  onAddToolResult(result) { commandQueue.enqueue(result); },
+})`
+
+- `onAddToolResult` typically reflects userland-triggered results (e.g., human/tool calling) coming from the external store runtime.
+
+Notes
+
+- Use a stable `EMPTY_ARRAY` when clearing in-transit commands to minimize re-renders via referential equality.
+- "Assistant stream" refers to the incremental response stream that yields state snapshots.
+
+Callbacks
+
+- `onError({ error, commands, updateState })`: invoked on network/stream errors. Commands are not restored; use `updateState(state => newState)` to reflect the error in state and/or messages. `commands` reflects the current in-transit commands at the moment of error (often `[]` after the first snapshot).
+- `onCancel({ commands, updateState })`: invoked after a cancellation. Commands are not restored. `commands` contains all pending work at cancel time (`inTransitCommands` plus queued). Use `updateState` to reflect cancellation in state and/or messages. The last received snapshot remains committed.
+
+Return Value
+
+- `useAssistantTransport` returns the runtime object from `useExternalStoreRuntime` (e.g., `{ isRunning, messages, ... }`), rather than a custom wrapper shape.

package/src/legacy-runtime/runtime-cores/assistant-transport/useAssistantTransportRuntime.tsx

@@ -0,0 +1,232 @@
+"use client";
+
+import {
+  ReadonlyJSONObject,
+  ReadonlyJSONValue,
+  asAsyncIterableStream,
+} from "assistant-stream/utils";
+import { AppendMessage } from "../../../types";
+import { useExternalStoreRuntime } from "../external-store/useExternalStoreRuntime";
+import { AssistantRuntime } from "../../runtime/AssistantRuntime";
+import { AddToolResultOptions } from "../core";
+import { useState, useRef, useMemo } from "react";
+import {
+  AssistantMessageAccumulator,
+  DataStreamDecoder,
+  unstable_createInitialMessage as createInitialMessage,
+} from "assistant-stream";
+import {
+  AssistantTransportOptions,
+  AddMessageCommand,
+  AddToolResultCommand,
+  UserMessagePart,
+  QueuedCommand,
+} from "./types";
+import { useCommandQueue } from "./commandQueue";
+import { useRunManager } from "./runManager";
+import { useConvertedState } from "./useConvertedState";
+import { useToolInvocations } from "./useToolInvocations";
+import { toAISDKTools, getEnabledTools, createRequestHeaders } from "./utils";
+import { useRemoteThreadListRuntime } from "../remote-thread-list/useRemoteThreadListRuntime";
+import { InMemoryThreadListAdapter } from "../remote-thread-list/adapter/in-memory";
+
+const useAssistantTransportThreadRuntime = <T,>(
+  options: AssistantTransportOptions<T>,
+): AssistantRuntime => {
+  const agentStateRef = useRef(options.initialState);
+  const [, rerender] = useState(0);
+  const resumeFlagRef = useRef(false);
+  const commandQueue = useCommandQueue({
+    onQueue: () => runManager.schedule(),
+  });
+
+  const runManager = useRunManager({
+    onRun: async (signal: AbortSignal) => {
+      const isResume = resumeFlagRef.current;
+      resumeFlagRef.current = false;
+      const commands: QueuedCommand[] = isResume ? [] : commandQueue.flush();
+      if (commands.length === 0 && !isResume)
+        throw new Error("No commands to send");
+
+      const headers = await createRequestHeaders(options.headers);
+      const context = runtime.thread.getModelContext();
+
+      const response = await fetch(
+        isResume ? options.resumeApi! : options.api,
+        {
+          method: "POST",
+          headers,
+          body: JSON.stringify({
+            commands,
+            state: agentStateRef.current,
+            system: context.system,
+            tools: context.tools
+              ? toAISDKTools(getEnabledTools(context.tools))
+              : undefined,
+            ...context.callSettings,
+            ...context.config,
+            ...options.body,
+          }),
+          signal,
+        },
+      );
+
+      options.onResponse?.(response);
+
+      if (!response.ok) {
+        throw new Error(`Status ${response.status}: ${await response.text()}`);
+      }
+
+      if (!response.body) {
+        throw new Error("Response body is null");
+      }
+
+      const stream = response.body
+        .pipeThrough(new DataStreamDecoder())
+        .pipeThrough(
+          new AssistantMessageAccumulator({
+            initialMessage: createInitialMessage({
+              unstable_state:
+                (agentStateRef.current as ReadonlyJSONValue) ?? null,
+            }),
+          }),
+        );
+
+      let markedDelivered = false;
+
+      for await (const chunk of asAsyncIterableStream(stream)) {
+        if (chunk.metadata.unstable_state === agentStateRef.current) continue;
+
+        if (!markedDelivered) {
+          commandQueue.markDelivered();
+          markedDelivered = true;
+        }
+
+        agentStateRef.current = chunk.metadata.unstable_state as T;
+        rerender((prev) => prev + 1);
+      }
+    },
+    onFinish: options.onFinish,
+    onError: (error) => {
+      if (error instanceof Error && error.name === "AbortError") {
+        const cmds = [
+          ...commandQueue.state.inTransit,
+          ...commandQueue.state.queued,
+        ];
+        options.onCancel?.({
+          commands: cmds,
+          updateState: (updater) => {
+            agentStateRef.current = updater(agentStateRef.current);
+            rerender((prev) => prev + 1);
+          },
+        });
+
+        commandQueue.reset();
+      } else {
+        const cmds = [...commandQueue.state.inTransit];
+        options.onError?.(error as Error, {
+          commands: cmds,
+          updateState: (updater) => {
+            agentStateRef.current = updater(agentStateRef.current);
+            rerender((prev) => prev + 1);
+          },
+        });
+        commandQueue.markDelivered();
+      }
+    },
+  });
+
+  // Reactive conversion of agent state + connection metadata → UI state
+  const pendingCommands = useMemo(
+    () => [...commandQueue.state.inTransit, ...commandQueue.state.queued],
+    [commandQueue.state],
+  );
+  const converted = useConvertedState(
+    options.converter,
+    agentStateRef.current,
+    pendingCommands,
+    runManager.isRunning,
+  );
+
+  // Create runtime
+  const runtime = useExternalStoreRuntime({
+    isRunning: converted.isRunning,
+    messages: converted.messages,
+    adapters: options.adapters,
+    onNew: async (message: AppendMessage): Promise<void> => {
+      // Convert AppendMessage to AddMessageCommand
+      const parts: UserMessagePart[] = [];
+
+      for (const content of message.content) {
+        if (content.type === "text") {
+          parts.push({ type: "text", text: content.text });
+        } else if (content.type === "image") {
+          parts.push({ type: "image", image: content.image });
+        }
+      }
+
+      const command: AddMessageCommand = {
+        type: "add-message",
+        message: {
+          role: "user",
+          parts,
+        },
+      };
+
+      commandQueue.enqueue(command);
+    },
+    onCancel: async () => {
+      runManager.cancel();
+      toolInvocations.abort();
+    },
+    onResume: async () => {
+      if (!options.resumeApi)
+        throw new Error("Must pass resumeApi to options to resume runs");
+
+      resumeFlagRef.current = true;
+      runManager.schedule();
+    },
+    onAddToolResult: async (
+      toolOptions: AddToolResultOptions,
+    ): Promise<void> => {
+      const command: AddToolResultCommand = {
+        type: "add-tool-result",
+        toolCallId: toolOptions.toolCallId,
+        result: toolOptions.result as ReadonlyJSONObject,
+        toolName: toolOptions.toolName,
+        isError: toolOptions.isError,
+        ...(toolOptions.artifact && { artifact: toolOptions.artifact }),
+      };
+
+      commandQueue.enqueue(command);
+    },
+    onLoadExternalState: async (state) => {
+      agentStateRef.current = state as T;
+      toolInvocations.reset();
+      rerender((prev) => prev + 1);
+    },
+  });
+
+  const toolInvocations = useToolInvocations({
+    state: converted,
+    getTools: () => runtime.thread.getModelContext().tools,
+    onResult: commandQueue.enqueue,
+  });
+
+  return runtime;
+};
+
+/**
+ * @alpha This is an experimental API that is subject to change.
+ */
+export const useAssistantTransportRuntime = <T,>(
+  options: AssistantTransportOptions<T>,
+): AssistantRuntime => {
+  const runtime = useRemoteThreadListRuntime({
+    runtimeHook: function RuntimeHook() {
+      return useAssistantTransportThreadRuntime(options);
+    },
+    adapter: new InMemoryThreadListAdapter(),
+  });
+  return runtime;
+};

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

@@ -0,0 +1,18 @@
+import { useMemo } from "react";
+import type {
+  AssistantTransportCommand,
+  AssistantTransportState,
+  AssistantTransportStateConverter,
+} from "./types";
+
+export function useConvertedState<T>(
+  converter: AssistantTransportStateConverter<T>,
+  agentState: T,
+  pendingCommands: AssistantTransportCommand[],
+  isSending: boolean,
+): AssistantTransportState {
+  return useMemo(
+    () => converter(agentState, { pendingCommands, isSending }),
+    [converter, agentState, pendingCommands, isSending],
+  );
+}

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

@@ -0,0 +1,9 @@
+import { useEffect, useRef } from "react";
+
+export function useLatestRef<T>(value: T) {
+  const ref = useRef(value);
+  useEffect(() => {
+    ref.current = value;
+  }, [value]);
+  return ref as { current: T };
+}