assistant-stream/src/core/AssistantStreamChunk.ts

Streaming utilities for AI assistants

import type { ReadonlyJSONValue } from "../utils/json/json-value";
import type { PartProviderMetadata, ToolCallApproval } from "./utils/types";
import type { AssistantTransportStateOperation } from "./gorp/types";
import type { ToolModelContentPart } from "./tool/tool-types";

/**
 * Initial metadata for a stream part.
 *
 * A part starts with `part-start`, receives zero or more chunks at the same
 * path, and ends with `part-finish`.
 */
export type PartInit =
  | {
      readonly type: "text";
      readonly providerMetadata?: PartProviderMetadata;
      readonly parentId?: string;
    }
  | {
      readonly type: "reasoning";
      /** @deprecated Experimental since 2026-08-07. Not scheduled for removal; the API may change in any release. */
      readonly unstable_summary?: string;
      readonly providerMetadata?: PartProviderMetadata;
      readonly parentId?: string;
    }
  | {
      readonly type: "tool-call";
      readonly toolCallId: string;
      readonly toolName: string;
      readonly parentId?: string;
    }
  | {
      readonly type: "source";
      readonly sourceType: "url";
      readonly id: string;
      readonly url: string;
      readonly title?: string;
      readonly parentId?: string;
    }
  | {
      readonly type: "source";
      readonly sourceType: "document";
      readonly id: string;
      readonly url?: undefined;
      readonly title: string;
      readonly mediaType: string;
      readonly filename?: string;
      readonly parentId?: string;
    }
  | {
      readonly type: "file";
      readonly data: string;
      readonly mimeType: string;
      readonly parentId?: string;
    }
  | {
      readonly type: "data";
      readonly name: string;
      readonly data: ReadonlyJSONValue;
      readonly parentId?: string;
    };

/**
 * Normalized assistant-ui streaming protocol chunk.
 *
 * `path` identifies the part or nested position the chunk belongs to. Encoders
 * may translate these chunks into provider-specific wire formats, while
 * accumulators consume them to build assistant messages.
 */
export type AssistantStreamChunk = { readonly path: readonly number[] } & (
  | {
      /** Opens a new content part at `path`. */
      readonly type: "part-start";
      readonly part: PartInit;
    }
  | {
      /** Closes the current part at `path`. */
      readonly type: "part-finish";
      readonly providerMetadata?: PartProviderMetadata;
    }
  | {
      /** Marks streamed tool-call argument text as complete. */
      readonly type: "tool-call-args-text-finish";
    }
  | {
      /** Sets the approval gate of the tool-call part at `path`, replacing any earlier one. */
      readonly type: "tool-call-approval";
      readonly approval: ToolCallApproval;
    }
  | {
      /** Appends text to a text, reasoning, or tool-call argument part. */
      readonly type: "text-delta";
      readonly textDelta: string;
      readonly providerMetadata?: PartProviderMetadata;
    }
  | {
      /** Appends provider or application annotations to the current message. */
      readonly type: "annotations";
      readonly annotations: ReadonlyJSONValue[];
    }
  | {
      /** Emits application data chunks associated with the current message. */
      readonly type: "data";
      readonly data: ReadonlyJSONValue[];
    }
  | {
      /** Starts a model generation step. */
      readonly type: "step-start";
      readonly messageId: string;
    }
  | {
      /** Finishes a model generation step and reports usage for that step. */
      readonly type: "step-finish";
      readonly finishReason:
        | "stop"
        | "length"
        | "content-filter"
        | "tool-calls"
        | "error"
        | "other"
        | "unknown";
      readonly usage: {
        readonly inputTokens: number;
        readonly outputTokens: number;
      };
      readonly isContinued: boolean;
    }
  | {
      /** Finishes the assistant message and reports final usage. */
      readonly type: "message-finish";
      readonly finishReason:
        | "stop"
        | "length"
        | "content-filter"
        | "tool-calls"
        | "error"
        | "other"
        | "unknown";
      readonly usage: {
        readonly inputTokens: number;
        readonly outputTokens: number;
      };
    }
  | {
      /**
       * Emits the result for a tool-call part.
       *
       * `artifact` is UI-visible metadata, while `modelContent` can override
       * what is sent back to the model.
       */
      readonly type: "result";
      readonly artifact?: ReadonlyJSONValue;
      readonly result: ReadonlyJSONValue;
      readonly isError: boolean;
      readonly isPreliminary?: boolean;
      readonly modelContent?: readonly ToolModelContentPart[];
      readonly messages?: ReadonlyJSONValue;
    }
  | {
      /** Emits a stream-level error message. */
      readonly type: "error";
      readonly error: string;
      readonly code?: string;
      readonly severity?: "critical" | "warning" | "info";
    }
  | {
      /** Applies gorp-stream operations to state carried by this stream. */
      readonly type: "update-state";
      readonly operations: AssistantTransportStateOperation[];
    }
);