@assistant-ui/react 0.15.14 → 0.15.16

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

@@ -1,170 +0,0 @@
-import type { ToolModelContentPart } from "assistant-stream";
-import type { ThreadMessage } from "@assistant-ui/core";
-import type { ReadonlyJSONValue } from "assistant-stream/utils";
-import type {
-  AttachmentAdapter,
-  ThreadHistoryAdapter,
-  LanguageModelV1CallSettings,
-  LanguageModelConfig,
-} from "@assistant-ui/core";
-import type { UserCommands } from "../../../augmentations";
-import type { ToolExecutionStatus } from "@assistant-ui/core";
-
-// 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;
-
-export type UserMessage = {
-  readonly role: "user";
-  readonly parts: readonly UserMessagePart[];
-};
-
-export type AssistantMessage = {
-  readonly role: "assistant";
-  readonly parts: readonly TextPart[];
-};
-
-// Command types
-export type AddMessageCommand = {
-  readonly type: "add-message";
-  readonly message: UserMessage | AssistantMessage;
-  readonly parentId: string | null;
-  readonly sourceId: string | null;
-};
-
-export type AddToolResultCommand = {
-  readonly type: "add-tool-result";
-  readonly toolCallId: string;
-  readonly toolName: string;
-  readonly result: ReadonlyJSONValue;
-  readonly isError: boolean;
-  readonly artifact?: ReadonlyJSONValue;
-  readonly modelContent?: readonly ToolModelContentPart[];
-};
-
-export type AssistantTransportCommand =
-  | AddMessageCommand
-  | AddToolResultCommand
-  | UserCommands;
-
-// State types
-export type AssistantTransportState = {
-  readonly messages: readonly ThreadMessage[];
-  readonly state?: ReadonlyJSONValue;
-  readonly isRunning: boolean;
-};
-
-export type AssistantTransportConnectionMetadata = {
-  pendingCommands: AssistantTransportCommand[];
-  isSending: boolean;
-  toolStatuses: Record<string, ToolExecutionStatus>;
-};
-
-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 AssistantTransportProtocol = "data-stream" | "assistant-transport";
-
-export type SendCommandsRequestBody = {
-  commands: QueuedCommand[];
-  /** Absent on a resume with `resumeStateApi`; the server replays from its retained snapshot. */
-  state?: unknown;
-  runId?: string;
-  system: string | undefined;
-  tools: Record<string, unknown> | undefined;
-  callSettings: LanguageModelV1CallSettings | undefined;
-  config: LanguageModelConfig | undefined;
-  threadId: string | null;
-  parentId?: string | null;
-  // `callSettings` and `config` fields are also spread at the top level for
-  // backward compatibility (e.g. `body.modelName`). Use the nested objects
-  // instead. The top-level fields will be removed in a future version.
-  [key: string]: unknown;
-};
-
-export type AssistantTransportOptions<T> = {
-  initialState: T;
-  api: string;
-  resumeApi?: string;
-  /** Endpoint that returns the retained initial state and run ID for a resume stream. A 204 response means no run is active and the resume is skipped. */
-  resumeStateApi?: string;
-  protocol?: AssistantTransportProtocol;
-  /**
-   * When `false`, stream decoding and state reconciliation tolerate malformed
-   * input (invalid chunks are dropped with a console log) instead of throwing.
-   * Resume runs always decode leniently. Defaults to `true`.
-   */
-  strict?: boolean;
-  converter: AssistantTransportStateConverter<T>;
-  headers: HeadersValue | (() => Promise<HeadersValue>);
-  body?: object | (() => Promise<object | undefined>);
-  /**
-   * Transform the request body before it is sent to the API.
-   * Receives the fully assembled body and returns the (potentially transformed) body.
-   *
-   * @example
-   * ```ts
-   * prepareSendCommandsRequest: (body) => ({
-   *   ...body,
-   *   trackingId: crypto.randomUUID(),
-   * })
-   * ```
-   */
-  prepareSendCommandsRequest?: (
-    body: SendCommandsRequestBody,
-  ) => Record<string, unknown> | Promise<Record<string, unknown>>;
-  onResponse?: (response: Response) => void;
-  onFinish?: () => void;
-  onError?: (
-    error: Error,
-    params: {
-      commands: AssistantTransportCommand[];
-      updateState: (updater: (state: T) => T) => void;
-    },
-  ) => void | Promise<void>;
-  /**
-   * Called when commands are cancelled.
-   *
-   * When an error occurs, queued commands are automatically cancelled after `onError` settles.
-   * In this case, the `error` parameter contains the error that caused the cancellation.
-   */
-  onCancel?: (params: {
-    commands: AssistantTransportCommand[];
-    updateState: (updater: (state: T) => T) => void;
-    error?: Error;
-  }) => void;
-  capabilities?: {
-    edit?: boolean;
-  };
-  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

@@ -1,141 +0,0 @@
-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.
-- 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.
-
-Resume State
-
-- With `resumeStateApi` configured, a resume first posts `{ threadId }` there; the endpoint returns `{ runId, state }`, the state that started the active run.
-- The resume request carries `runId` and no `state`: the server replays from the snapshot it retained for that run, so neither `body` overrides nor a `prepareSendCommandsRequest` rebuild can substitute a different base. `runId` takes precedence over `body` fields and is re-attached after `prepareSendCommandsRequest` so a rebuilt body cannot drop it. The local base is replaced by the snapshot only after the resume stream responds OK, so a rejected resume keeps the local state.
-- A 204 response means no active run: the resume is skipped without error, and queued commands are flushed in a follow-up run.
-- A malformed snapshot response fails the resume before the replay request is sent.
-- If a pending resume is dropped by an error or cancellation, later commands start normal runs.
-- 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, { 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[]`.
-
-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);
-      }
-
-      // 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?.({
-        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.
-- 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.
-- 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.