@assistant-ui/react 0.11.5 → 0.11.7

package/src/legacy-runtime/client/MessagePartRuntimeClient.ts

@@ -7,21 +7,20 @@ export const MessagePartClient = resource(
   ({ runtime }: { runtime: MessagePartRuntime }) => {
     const runtimeState = tapSubscribable(runtime);
 
-    const api = tapApi<MessagePartClientApi>({
-      getState: () => runtimeState,
+    return tapApi<MessagePartClientApi>(
+      {
+        getState: () => runtimeState,
 
-      addToolResult: (result) => runtime.addToolResult(result),
+        addToolResult: (result) => runtime.addToolResult(result),
 
-      __internal_getRuntime: () => runtime,
-    });
-
-    return {
-      key:
-        runtimeState.type === "tool-call"
-          ? "toolCallId-" + runtimeState.toolCallId
-          : undefined,
-      state: runtimeState,
-      api,
-    };
+        __internal_getRuntime: () => runtime,
+      },
+      {
+        key:
+          runtimeState.type === "tool-call"
+            ? "toolCallId-" + runtimeState.toolCallId
+            : undefined,
+      },
+    );
   },
 );

package/src/legacy-runtime/client/MessageRuntimeClient.ts

@@ -99,44 +99,43 @@ export const MessageClient = resource(
       isHoveringState,
     ]);
 
-    const api = tapApi<MessageClientApi>({
-      getState: () => state,
-
-      composer: composer.api,
-
-      reload: (config) => runtime.reload(config),
-      speak: () => runtime.speak(),
-      stopSpeaking: () => runtime.stopSpeaking(),
-      submitFeedback: (feedback) => runtime.submitFeedback(feedback),
-      switchToBranch: (options) => runtime.switchToBranch(options),
-      getCopyText: () => runtime.unstable_getCopyText(),
-
-      part: (selector) => {
-        if ("index" in selector) {
-          return parts.api({ index: selector.index });
-        } else {
-          return parts.api({ key: "toolCallId-" + selector.toolCallId });
-        }
-      },
-
-      attachment: (selector) => {
-        if ("id" in selector) {
-          return attachments.api({ key: selector.id });
-        } else {
-          return attachments.api(selector);
-        }
-      },
+    return tapApi<MessageClientApi>(
+      {
+        getState: () => state,
+
+        composer: composer.api,
+
+        reload: (config) => runtime.reload(config),
+        speak: () => runtime.speak(),
+        stopSpeaking: () => runtime.stopSpeaking(),
+        submitFeedback: (feedback) => runtime.submitFeedback(feedback),
+        switchToBranch: (options) => runtime.switchToBranch(options),
+        getCopyText: () => runtime.unstable_getCopyText(),
+
+        part: (selector) => {
+          if ("index" in selector) {
+            return parts.api({ index: selector.index });
+          } else {
+            return parts.api({ key: "toolCallId-" + selector.toolCallId });
+          }
+        },
 
-      setIsCopied,
-      setIsHovering,
+        attachment: (selector) => {
+          if ("id" in selector) {
+            return attachments.api({ key: selector.id });
+          } else {
+            return attachments.api(selector);
+          }
+        },
 
-      __internal_getRuntime: () => runtime,
-    });
+        setIsCopied,
+        setIsHovering,
 
-    return {
-      key: runtimeState.id,
-      state,
-      api,
-    };
+        __internal_getRuntime: () => runtime,
+      },
+      {
+        key: runtimeState.id,
+      },
+    );
   },
 );

package/src/legacy-runtime/client/ThreadListItemRuntimeClient.ts

@@ -38,23 +38,22 @@ export const ThreadListItemClient = resource(
       };
     }, [runtime, events]);
 
-    const api = tapApi<ThreadListItemClientApi>({
-      getState: () => runtimeState,
-      switchTo: runtime.switchTo,
-      rename: runtime.rename,
-      archive: runtime.archive,
-      unarchive: runtime.unarchive,
-      delete: runtime.delete,
-      generateTitle: runtime.generateTitle,
-      initialize: runtime.initialize,
-      detach: runtime.detach,
-      __internal_getRuntime: () => runtime,
-    });
-
-    return {
-      state: runtimeState,
-      api,
-      key: runtimeState.id,
-    };
+    return tapApi<ThreadListItemClientApi>(
+      {
+        getState: () => runtimeState,
+        switchTo: runtime.switchTo,
+        rename: runtime.rename,
+        archive: runtime.archive,
+        unarchive: runtime.unarchive,
+        delete: runtime.delete,
+        generateTitle: runtime.generateTitle,
+        initialize: runtime.initialize,
+        detach: runtime.detach,
+        __internal_getRuntime: () => runtime,
+      },
+      {
+        key: runtimeState.id,
+      },
+    );
   },
 );

package/src/legacy-runtime/client/ThreadListRuntimeClient.ts

@@ -53,7 +53,7 @@ export const ThreadListClient = resource(
       };
     }, [runtimeState, threadItems.state, main.state]);
 
-    const api = tapApi<ThreadListClientApi>({
+    return tapApi<ThreadListClientApi>({
       getState: () => state,
 
       thread: () => main.api,
@@ -81,10 +81,5 @@ export const ThreadListClient = resource(
         runtime.switchToNewThread();
       },
     });
-
-    return {
-      state,
-      api,
-    };
   },
 );

package/src/legacy-runtime/client/ThreadRuntimeClient.ts

@@ -111,7 +111,7 @@ export const ThreadClient = resource(
       };
     }, [runtimeState, messages, composer.state]);
 
-    const api = tapApi<ThreadClientApi>({
+    return tapApi<ThreadClientApi>({
       getState: () => state,
 
       composer: composer.api,
@@ -136,10 +136,5 @@ export const ThreadClient = resource(
 
       __internal_getRuntime: () => runtime,
     });
-
-    return {
-      state,
-      api,
-    };
   },
 );

package/src/legacy-runtime/runtime/ThreadRuntime.ts

@@ -43,7 +43,7 @@ export type CreateStartRunConfig = {
 };
 
 export type CreateResumeRunConfig = CreateStartRunConfig & {
-  stream: (
+  stream?: (
     options: ChatModelRunOptions,
   ) => AsyncGenerator<ChatModelRunResult, void, unknown>;
 };
@@ -53,7 +53,7 @@ const toResumeRunConfig = (message: CreateResumeRunConfig): ResumeRunConfig => {
     parentId: message.parentId ?? null,
     sourceId: message.sourceId ?? null,
     runConfig: message.runConfig ?? {},
-    stream: message.stream,
+    ...(message.stream ? { stream: message.stream } : {}),
   };
 };
 
@@ -256,6 +256,12 @@ export type ThreadRuntime = {
    **/
   unstable_resumeRun(config: CreateResumeRunConfig): void;
 
+  /**
+   * Load external state into the thread.
+   * @param state The state to load into the thread
+   */
+  unstable_loadExternalState(state: any): void;
+
   subscribe(callback: () => void): Unsubscribe;
   cancelRun(): void;
   getModelContext(): ModelContext;
@@ -346,6 +352,8 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
   protected __internal_bindMethods() {
     this.append = this.append.bind(this);
     this.unstable_resumeRun = this.unstable_resumeRun.bind(this);
+    this.unstable_loadExternalState =
+      this.unstable_loadExternalState.bind(this);
     this.startRun = this.startRun.bind(this);
     this.cancelRun = this.cancelRun.bind(this);
     this.stopSpeaking = this.stopSpeaking.bind(this);
@@ -399,6 +407,10 @@ export class ThreadRuntimeImpl implements ThreadRuntime {
     return this._threadBinding.getState().resumeRun(toResumeRunConfig(config));
   }
 
+  public unstable_loadExternalState(state: any) {
+    this._threadBinding.getState().unstable_loadExternalState(state);
+  }
+
   public cancelRun() {
     this._threadBinding.getState().cancelRun();
   }

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

@@ -0,0 +1,62 @@
+import { useState, useCallback, useRef, useEffect } from "react";
+import {
+  AssistantTransportCommand,
+  CommandQueueState,
+  QueuedCommand,
+} from "./types";
+
+export const createInitialQueueState = (): CommandQueueState => ({
+  queued: [],
+  inTransit: [],
+});
+
+export const useCommandQueue = (opts: { onQueue: () => void }) => {
+  const onQueueRef = useRef(opts.onQueue);
+  useEffect(() => {
+    onQueueRef.current = opts.onQueue;
+  });
+
+  const [, rerender] = useState(0);
+  const queueStateRef = useRef<CommandQueueState>(createInitialQueueState());
+
+  const enqueue = (command: AssistantTransportCommand) => {
+    queueStateRef.current = {
+      queued: [...queueStateRef.current.queued, command],
+      inTransit: queueStateRef.current.inTransit,
+    };
+    rerender((prev) => prev + 1);
+
+    onQueueRef.current();
+  };
+
+  const flush = (): QueuedCommand[] => {
+    if (queueStateRef.current.queued.length === 0) return [];
+
+    const queued = queueStateRef.current.queued;
+    queueStateRef.current = {
+      queued: [],
+      inTransit: [...queueStateRef.current.inTransit, ...queued],
+    };
+    rerender((prev) => prev + 1);
+
+    return queued;
+  };
+
+  const markDelivered = () => {
+    queueStateRef.current = { ...queueStateRef.current, inTransit: [] };
+    rerender((prev) => prev + 1);
+  };
+
+  const reset = useCallback(() => {
+    queueStateRef.current = createInitialQueueState();
+    rerender((prev) => prev + 1);
+  }, []);
+
+  return {
+    state: queueStateRef.current,
+    enqueue,
+    flush,
+    markDelivered,
+    reset,
+  };
+};

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

@@ -0,0 +1,2 @@
+export { useAssistantTransportRuntime } from "./useAssistantTransportRuntime";
+export type { AssistantTransportConnectionMetadata } from "./types";

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.