assistant-stream 0.3.13 → 0.3.15

package/src/core/AssistantStreamChunk.ts

@@ -1,6 +1,13 @@
 import type { ReadonlyJSONValue } from "../utils/json/json-value";
 import type { ObjectStreamOperation } from "./object/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" | "reasoning";
@@ -33,34 +40,49 @@ export type PartInit =
       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";
     }
   | {
+      /** Marks streamed tool-call argument text as complete. */
       readonly type: "tool-call-args-text-finish";
     }
   | {
+      /** Appends text to a text, reasoning, or tool-call argument part. */
       readonly type: "text-delta";
       readonly textDelta: string;
     }
   | {
+      /** 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"
@@ -77,6 +99,7 @@ export type AssistantStreamChunk = { readonly path: readonly number[] } & (
       readonly isContinued: boolean;
     }
   | {
+      /** Finishes the assistant message and reports final usage. */
       readonly type: "message-finish";
       readonly finishReason:
         | "stop"
@@ -92,17 +115,26 @@ export type AssistantStreamChunk = { readonly path: readonly 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 modelContent?: readonly ToolModelContentPart[];
       readonly messages?: ReadonlyJSONValue;
     }
   | {
+      /** Emits a stream-level error message. */
       readonly type: "error";
       readonly error: string;
     }
   | {
+      /** Applies object-stream operations to state carried by this stream. */
       readonly type: "update-state";
       readonly operations: ObjectStreamOperation[];
     }

package/src/core/accumulators/assistant-message-accumulator.ts

@@ -216,6 +216,9 @@ const handleResult = (
         ...(chunk.artifact !== undefined ? { artifact: chunk.artifact } : {}),
         result: chunk.result,
         isError: chunk.isError ?? false,
+        ...(chunk.modelContent !== undefined
+          ? { modelContent: chunk.modelContent }
+          : {}),
         ...(chunk.messages !== undefined ? { messages: chunk.messages } : {}),
         status: { type: "complete", reason: "stop" },
       };

package/src/core/modules/assistant-stream.ts

@@ -29,18 +29,63 @@ type ToolCallPartInit = {
   response?: ToolResponseLike<ReadonlyJSONValue>;
 };
 
+/**
+ * Imperative writer for constructing an {@link AssistantStream}.
+ *
+ * The controller handles part boundaries for common streaming operations. Use
+ * `appendText` and `appendReasoning` for simple token streams, or open explicit
+ * parts with `addTextPart` and `addToolCallPart` when you need direct control.
+ */
 export type AssistantStreamController = {
+  /** Appends text to the current text part, opening one if needed. */
   appendText(textDelta: string): void;
+  /** Appends reasoning text to the current reasoning part, opening one if needed. */
   appendReasoning(reasoningDelta: string): void;
+  /** Appends a source citation part to the stream. */
   appendSource(options: SourcePart): void;
+  /** Appends a file part to the stream. */
   appendFile(options: FilePart): void;
+  /** Appends a named data part to the stream. */
   appendData(options: DataPart): void;
+  /**
+   * Opens a text part and returns its writer.
+   *
+   * Close the returned controller when the text part is complete. Opening a new
+   * part through this controller closes any implicit text or reasoning append
+   * part first.
+   */
   addTextPart(): TextStreamController;
+  /**
+   * Opens a tool-call part by tool name and returns its writer.
+   *
+   * A tool call id is generated automatically. Use the object overload when the
+   * caller already has an id, initial args, args text, or response.
+   */
   addToolCallPart(options: string): ToolCallStreamController;
+  /**
+   * Opens a tool-call part and returns its writer.
+   *
+   * Use this overload to provide a stable `toolCallId`, initial arguments,
+   * streamed argument text, or an immediate {@link ToolResponseLike}.
+   */
   addToolCallPart(options: ToolCallPartInit): ToolCallStreamController;
+  /** Enqueues a raw protocol chunk. Prefer higher-level helpers when possible. */
   enqueue(chunk: AssistantStreamChunk): void;
+  /**
+   * Merges another assistant stream into this stream.
+   *
+   * Paths from the merged stream are remapped so its parts appear at the next
+   * available position in this controller's output.
+   */
   merge(stream: AssistantStream): void;
+  /** Closes any active part and finishes the stream. */
   close(): void;
+  /**
+   * Returns a controller that writes child parts with `parentId` attached.
+   *
+   * Use this for nested or related parts that should be associated with an
+   * existing message or part in downstream renderers.
+   */
   withParentId(parentId: string): AssistantStreamController;
 };
 
@@ -226,6 +271,15 @@ class AssistantStreamControllerImpl implements AssistantStreamController {
   }
 }
 
+/**
+ * Creates an {@link AssistantStream} and writes to it with an
+ * {@link AssistantStreamController}.
+ *
+ * The callback may write synchronously or asynchronously. If it throws, an
+ * `error` chunk is emitted before the error is rethrown; when the callback
+ * settles, the stream is closed automatically unless the controller was
+ * already closed.
+ */
 export function createAssistantStream(
   callback: (controller: AssistantStreamController) => PromiseLike<void> | void,
 ): AssistantStream {
@@ -254,6 +308,13 @@ export function createAssistantStream(
   return controller.__internal_getReadable();
 }
 
+/**
+ * Creates an {@link AssistantStream} together with the controller used to
+ * write into it.
+ *
+ * Use this when the stream needs to be returned before all writers are known.
+ * Closing the returned controller finishes the paired stream.
+ */
 export function createAssistantStreamController() {
   const { resolve, promise } = promiseWithResolvers<void>();
   let controller!: AssistantStreamController;
@@ -269,6 +330,13 @@ export function createAssistantStreamController() {
   return [stream, controller] as const;
 }
 
+/**
+ * Creates a `Response` whose body is an encoded {@link AssistantStream}.
+ *
+ * This is the HTTP-route convenience form of {@link createAssistantStream}; it
+ * uses {@link DataStreamEncoder} so the response can be consumed by matching
+ * assistant-ui data stream decoders.
+ */
 export function createAssistantStreamResponse(
   callback: (controller: AssistantStreamController) => PromiseLike<void> | void,
 ) {

package/src/core/modules/tool-call.ts

@@ -76,6 +76,9 @@ class ToolCallStreamControllerImpl implements ToolCallStreamController {
         : {}),
       result: response.result,
       isError: response.isError ?? false,
+      ...(response.modelContent !== undefined
+        ? { modelContent: response.modelContent }
+        : {}),
       ...(response.messages !== undefined
         ? { messages: response.messages }
         : {}),

package/src/core/tool/ToolExecutionStream.ts

@@ -104,6 +104,7 @@ export class ToolExecutionStream extends PipeableTransformStream<
                   result: chunk.result,
                   artifact: chunk.artifact,
                   isError: chunk.isError,
+                  modelContent: chunk.modelContent,
                 }),
               );
               break;
@@ -156,6 +157,8 @@ export class ToolExecutionStream extends PipeableTransformStream<
                     artifact: c.artifact,
                     result: c.result,
                     isError: c.isError,
+                    messages: c.messages,
+                    modelContent: c.modelContent,
                   });
                   streamController.setResponse(result);
                   controller.enqueue({

package/src/core/tool/ToolResponse.ts

@@ -1,14 +1,53 @@
 import type { ReadonlyJSONValue } from "../../utils/json/json-value";
+import type {
+  ToolModelContentPart,
+  ToolModelOutputFunction,
+} from "./tool-types";
 
 const TOOL_RESPONSE_SYMBOL = Symbol.for("aui.tool-response");
 
+/**
+ * Shape accepted anywhere a {@link ToolResponse} can be returned.
+ */
 export type ToolResponseLike<TResult> = {
+  /** UI-visible tool result value. */
   result: TResult;
+  /**
+   * Optional UI-only artifact associated with the result.
+   *
+   * Artifacts are useful for large or structured data that should be available
+   * to renderers without necessarily being sent back to the model.
+   */
   artifact?: ReadonlyJSONValue | undefined;
+  /** Marks the tool result as an error result. */
   isError?: boolean | undefined;
+  /**
+   * Explicit model-visible content to send back after the tool call.
+   *
+   * When omitted, assistant-ui derives model output from `result` or a tool's
+   * {@link ToolModelOutputFunction}.
+   */
+  modelContent?: readonly ToolModelContentPart[] | undefined;
+  /** Optional provider-specific message payload associated with the tool result. */
   messages?: ReadonlyJSONValue | undefined;
 };
 
+/**
+ * Tool result wrapper for separating UI-visible output from model-visible
+ * output.
+ *
+ * Return `ToolResponse` from a tool when you need to attach an artifact, mark
+ * the result as an error, or control the content sent back to the model.
+ *
+ * @example
+ * ```ts
+ * return new ToolResponse({
+ *   result: { title: "Report ready" },
+ *   artifact: { reportId },
+ *   modelContent: [{ type: "text", text: "The report is ready." }],
+ * });
+ * ```
+ */
 export class ToolResponse<TResult> {
   get [TOOL_RESPONSE_SYMBOL]() {
     return true;
@@ -17,6 +56,7 @@ export class ToolResponse<TResult> {
   readonly artifact?: ReadonlyJSONValue;
   readonly result: TResult;
   readonly isError: boolean;
+  readonly modelContent?: readonly ToolModelContentPart[];
   readonly messages?: ReadonlyJSONValue;
 
   constructor(options: ToolResponseLike<TResult>) {
@@ -25,6 +65,9 @@ export class ToolResponse<TResult> {
     }
     this.result = options.result;
     this.isError = options.isError ?? false;
+    if (options.modelContent !== undefined) {
+      this.modelContent = options.modelContent;
+    }
     if (options.messages !== undefined) {
       this.messages = options.messages;
     }
@@ -38,6 +81,13 @@ export class ToolResponse<TResult> {
     );
   }
 
+  /**
+   * Converts a plain tool return value into a {@link ToolResponse}.
+   *
+   * Existing `ToolResponse` instances are returned unchanged. `undefined`
+   * becomes the string `"<no result>"` so downstream protocol chunks always
+   * carry a concrete result.
+   */
   static toResponse(result: any | ToolResponse<any>): ToolResponse<any> {
     if (result instanceof ToolResponse) {
       return result;

package/src/core/tool/tool-types.ts

@@ -4,6 +4,63 @@ import type { AsyncIterableStream } from "../../utils";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { ToolResponse } from "./ToolResponse";
 
+export type ToolModelContentPart =
+  | {
+      /** A text content part returned to the model after a tool call. */
+      readonly type: "text";
+      /** Text that should be included in the model-visible tool result. */
+      readonly text: string;
+    }
+  | {
+      /** A file content part returned to the model after a tool call. */
+      readonly type: "file";
+      /**
+       * File payload encoded as a provider-compatible string, commonly base64
+       * for binary data.
+       */
+      readonly data: string;
+      /** MIME type for the file payload. */
+      readonly mediaType: string;
+      /** Optional display filename for the file payload. */
+      readonly filename?: string;
+    };
+
+/**
+ * Converts a tool's runtime result into content that is sent back to the
+ * model.
+ *
+ * Return this when the value shown in the UI or stored as the tool result
+ * should differ from the model-visible response. When omitted, the successful
+ * tool result is sent back to the model as-is. If a tool returns a
+ * `ToolResponse` with `modelContent`, that explicit content is used instead
+ * of calling this function.
+ *
+ * @example
+ * ```ts
+ * const toModelOutput: ToolModelOutputFunction<
+ *   { documentId: string },
+ *   { summary: string; pdfBase64: string }
+ * > = ({ output }) => [
+ *   { type: "text", text: output.summary },
+ *   {
+ *     type: "file",
+ *     data: output.pdfBase64,
+ *     mediaType: "application/pdf",
+ *   },
+ * ];
+ * ```
+ */
+export type ToolModelOutputFunction<TArgs, TResult> = (options: {
+  /** Stable identifier for the tool call being converted. */
+  toolCallId: string;
+  /** Arguments supplied by the model for this tool call. */
+  input: TArgs;
+  /** Value returned by the tool's {@link ToolExecuteFunction}. */
+  output: TResult;
+}) =>
+  | readonly ToolModelContentPart[]
+  | Promise<readonly ToolModelContentPart[]>;
+
 /**
  * Interface for reading tool call arguments from a stream, which are
  * generated by a language learning model (LLM). Provides methods to
@@ -70,7 +127,8 @@ export interface ToolCallReader<
   response: ToolCallResponseReader<TResult>;
 
   /**
-   * @deprecated Deprecated. Use `response.get().result` instead.
+   * @deprecated Use {@link ToolCallReader.response} and read
+   * `response.get().result` instead.
    */
   result: {
     get: () => Promise<TResult>;
@@ -78,11 +136,20 @@ export interface ToolCallReader<
 }
 
 export type ToolExecutionContext = {
+  /** Stable identifier for the tool call being executed. */
   toolCallId: string;
+  /** Signal that is aborted when the current run is cancelled. */
   abortSignal: AbortSignal;
+  /**
+   * From inside a frontend tool's execute function, request human input from
+   * the UI. Resolves with the payload the UI supplies.
+   */
   human: (payload: unknown) => Promise<unknown>;
 };
 
+/**
+ * Function called when assistant-ui executes a frontend tool.
+ */
 export type ToolExecuteFunction<TArgs, TResult> = (
   args: TArgs,
   context: ToolExecutionContext,
@@ -115,12 +182,14 @@ type BackendTool<
   TArgs extends Record<string, unknown> = Record<string, unknown>,
   TResult = unknown,
 > = ToolBase<TArgs, TResult> & {
+  /** Tool that is executed by the backend rather than in the browser. */
   type: "backend";
 
   description?: undefined;
   parameters?: undefined;
   disabled?: undefined;
   execute?: undefined;
+  toModelOutput?: undefined;
   experimental_onSchemaValidationError?: undefined;
 };
 
@@ -128,12 +197,20 @@ type FrontendTool<
   TArgs extends Record<string, unknown> = Record<string, unknown>,
   TResult = unknown,
 > = ToolBase<TArgs, TResult> & {
+  /** Tool that is executed in the frontend runtime. */
   type: "frontend";
 
+  /** Natural-language description shown to the model when selecting tools. */
   description?: string | undefined;
+  /** Schema for the arguments the model must provide when calling the tool. */
   parameters: StandardSchemaV1<TArgs> | JSONSchema7;
+  /** Prevents the tool from being exposed to the model while true. */
   disabled?: boolean;
+  /** Executes the tool after the model provides valid arguments. */
   execute: ToolExecuteFunction<TArgs, TResult>;
+  /** Converts the execution result into model-visible output. */
+  toModelOutput?: ToolModelOutputFunction<TArgs, TResult>;
+  /** Handles invalid tool arguments when schema validation fails. */
   experimental_onSchemaValidationError?: OnSchemaValidationErrorFunction<TResult>;
 };
 
@@ -141,15 +218,61 @@ type HumanTool<
   TArgs extends Record<string, unknown> = Record<string, unknown>,
   TResult = unknown,
 > = ToolBase<TArgs, TResult> & {
+  /** Tool that pauses the run until a user or UI supplies a result. */
   type: "human";
 
+  /** Natural-language description shown to the model when selecting tools. */
   description?: string | undefined;
+  /** Schema for the arguments the model must provide when requesting input. */
   parameters: StandardSchemaV1<TArgs> | JSONSchema7;
+  /** Prevents the tool from being exposed to the model while true. */
   disabled?: boolean;
   execute?: undefined;
+  toModelOutput?: undefined;
   experimental_onSchemaValidationError?: undefined;
 };
 
+/**
+ * Definition for a tool that can be exposed to the assistant model.
+ *
+ * Use `type: "frontend"` for tools executed in the browser, `type: "backend"`
+ * for tools handled by your server, and `type: "human"` for flows that pause
+ * until the UI supplies a result.
+ *
+ * @example
+ * ```ts
+ * const frontendTool: Tool<{ city: string }, string> = {
+ *   type: "frontend",
+ *   description: "Get the weather for a city.",
+ *   parameters: {
+ *     type: "object",
+ *     properties: { city: { type: "string" } },
+ *     required: ["city"],
+ *   },
+ *   execute: async ({ city }) => `Sunny in ${city}`,
+ * };
+ * ```
+ *
+ * @example
+ * ```ts
+ * const backendTool: Tool = {
+ *   type: "backend",
+ * };
+ * ```
+ *
+ * @example
+ * ```ts
+ * const humanTool: Tool<{ question: string }, string> = {
+ *   type: "human",
+ *   description: "Ask the user a follow-up question.",
+ *   parameters: {
+ *     type: "object",
+ *     properties: { question: { type: "string" } },
+ *     required: ["question"],
+ *   },
+ * };
+ * ```
+ */
 export type Tool<
   TArgs extends Record<string, unknown> = Record<string, unknown>,
   TResult = unknown,
@@ -160,7 +283,7 @@ export type Tool<
   | ToolWithoutType<TArgs, TResult>;
 
 /**
- * @deprecated Use `Tool` with an explicit `type` field instead.
+ * @deprecated Use {@link Tool} with an explicit `type` field instead.
  */
 export type ToolWithoutType<
   TArgs extends Record<string, unknown> = Record<string, unknown>,