assistant-stream 0.3.14 → 0.3.15

package/dist/core/tool/tool-types.d.ts

@@ -4,17 +4,54 @@ import type { AsyncIterableStream } from "../../utils.js";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { ToolResponse } from "./ToolResponse.js";
 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[]>;
 /**
@@ -62,17 +99,27 @@ export interface ToolCallReader<TArgs extends Record<string, unknown> = Record<s
     args: ToolCallArgsReader<TArgs>;
     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>;
     };
 }
 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) => TResult | Promise<TResult>;
 export type ToolStreamCallFunction<TArgs extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> = (reader: ToolCallReader<TArgs, TResult>, context: ToolExecutionContext) => void;
 type OnSchemaValidationErrorFunction<TResult> = ToolExecuteFunction<unknown, TResult>;
@@ -83,6 +130,7 @@ type ToolBase<TArgs extends Record<string, unknown> = Record<string, unknown>, T
     streamCall?: ToolStreamCallFunction<TArgs, TResult>;
 };
 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;
@@ -92,26 +140,78 @@ type BackendTool<TArgs extends Record<string, unknown> = Record<string, unknown>
     experimental_onSchemaValidationError?: undefined;
 };
 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>;
 };
 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> = FrontendTool<TArgs, TResult> | BackendTool<TArgs, TResult> | HumanTool<TArgs, TResult> | 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>, TResult = unknown> = (Omit<FrontendTool<TArgs, TResult>, "type"> | Omit<BackendTool<TArgs, TResult>, "type"> | Omit<HumanTool<TArgs, TResult>, "type">) & {
     type?: undefined;

package/dist/core/tool/tool-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-types.d.ts","sourceRoot":"","sources":["../../../src/core/tool/tool-types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-types.d.ts","sourceRoot":"","sources":["../../../src/core/tool/tool-types.ts"],"names":[],"mappings":"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"}

package/dist/core/tool/toolResultStream.d.ts

@@ -3,8 +3,23 @@ import { ToolExecutionStream } from "./ToolExecutionStream.js";
 import type { AssistantMessage } from "../utils/types.js";
 export declare function unstable_runPendingTools(message: AssistantMessage, tools: Record<string, Tool> | undefined, abortSignal: AbortSignal, human: (toolCallId: string, payload: unknown) => Promise<unknown>): Promise<AssistantMessage>;
 export type ToolResultStreamOptions = {
+    /** Called immediately before a frontend tool's `execute` function runs. */
     onExecutionStart?: (toolCallId: string, toolName: string) => void;
+    /** Called after frontend tool execution finishes or fails. */
     onExecutionEnd?: (toolCallId: string, toolName: string) => void;
 };
+/**
+ * Transform stream that executes frontend tools and appends tool results.
+ *
+ * The transform watches streamed tool-call arguments, runs the matching
+ * frontend tool once its arguments are complete, and emits a result chunk for
+ * the tool call. Backend and human tools pass through according to their tool
+ * definition.
+ *
+ * @param tools Tool registry or function returning the current registry.
+ * @param abortSignal Signal, or signal getter, used for the current run.
+ * @param human Callback used to resolve human-tool requests from UI input.
+ * @param options Optional execution lifecycle callbacks.
+ */
 export declare function toolResultStream(tools: Record<string, Tool> | (() => Record<string, Tool> | undefined) | undefined, abortSignal: AbortSignal | (() => AbortSignal), human: (toolCallId: string, payload: unknown) => Promise<unknown>, options?: ToolResultStreamOptions): ToolExecutionStream;
 //# sourceMappingURL=toolResultStream.d.ts.map

package/dist/core/tool/toolResultStream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolResultStream.d.ts","sourceRoot":"","sources":["../../../src/core/tool/toolResultStream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAuC,wBAAqB;AAG9E,OAAO,EAAE,mBAAmB,EAAE,iCAA8B;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,0BAAuB;AAyIvD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,SAAS,EACvC,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,6BAoElE;AAED,MAAM,MAAM,uBAAuB,GAAG;IACpC,gBAAgB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAClE,cAAc,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACjE,CAAC;AAEF,wBAAgB,gBAAgB,CAC9B,KAAK,EACD,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GACpB,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,SAAS,CAAC,GACxC,SAAS,EACb,WAAW,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,EAC9C,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,EACjE,OAAO,CAAC,EAAE,uBAAuB,uBAalC"}
+{"version":3,"file":"toolResultStream.d.ts","sourceRoot":"","sources":["../../../src/core/tool/toolResultStream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAuC,wBAAqB;AAG9E,OAAO,EAAE,mBAAmB,EAAE,iCAA8B;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,0BAAuB;AAyIvD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,SAAS,EACvC,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,6BAoElE;AAED,MAAM,MAAM,uBAAuB,GAAG;IACpC,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAClE,8DAA8D;IAC9D,cAAc,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACjE,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EACD,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GACpB,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,SAAS,CAAC,GACxC,SAAS,EACb,WAAW,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,EAC9C,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,EACjE,OAAO,CAAC,EAAE,uBAAuB,uBAalC"}

package/dist/core/tool/toolResultStream.js

@@ -143,6 +143,19 @@ export async function unstable_runPendingTools(message, tools, abortSignal, huma
         content: updatedParts,
     };
 }
+/**
+ * Transform stream that executes frontend tools and appends tool results.
+ *
+ * The transform watches streamed tool-call arguments, runs the matching
+ * frontend tool once its arguments are complete, and emits a result chunk for
+ * the tool call. Backend and human tools pass through according to their tool
+ * definition.
+ *
+ * @param tools Tool registry or function returning the current registry.
+ * @param abortSignal Signal, or signal getter, used for the current run.
+ * @param human Callback used to resolve human-tool requests from UI input.
+ * @param options Optional execution lifecycle callbacks.
+ */
 export function toolResultStream(tools, abortSignal, human, options) {
     const toolsFn = typeof tools === "function" ? tools : () => tools;
     const abortSignalFn = typeof abortSignal === "function" ? abortSignal : () => abortSignal;

package/dist/core/tool/toolResultStream.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolResultStream.js","sourceRoot":"","sources":["../../../src/core/tool/toolResultStream.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"toolResultStream.js","sourceRoot":"","sources":["../../../src/core/tool/toolResultStream.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assistant-stream",
-  "version": "0.3.14",
+  "version": "0.3.15",
   "description": "Streaming utilities for AI assistants",
   "keywords": [
     "ai",
@@ -67,10 +67,11 @@
     "ioredis": "^5.10.1",
     "redis": "^5.12.1",
     "vitest": "^4.1.5",
-    "@assistant-ui/x-buildutils": "0.0.7"
+    "@assistant-ui/x-buildutils": "0.0.8"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "homepage": "https://www.assistant-ui.com/",
   "repository": {

package/src/core/AssistantStream.ts

@@ -1,7 +1,22 @@
 import type { AssistantStreamChunk } from "./AssistantStreamChunk";
 
+/**
+ * Stream of assistant-ui protocol chunks.
+ *
+ * `AssistantStream` is the normalized internal stream format used by
+ * encoders, decoders, accumulators, and tool execution transforms. Use an
+ * encoder such as `DataStreamEncoder` when returning it from an HTTP route,
+ * and the matching decoder when reading it back from a response.
+ */
 export type AssistantStream = ReadableStream<AssistantStreamChunk>;
 
+/**
+ * Encoder that converts an {@link AssistantStream} into bytes suitable for an
+ * HTTP response body.
+ *
+ * Encoders may expose response headers, such as content type or protocol
+ * markers, through `headers`.
+ */
 export type AssistantStreamEncoder = ReadableWritablePair<
   Uint8Array<ArrayBuffer>,
   AssistantStreamChunk
@@ -10,12 +25,26 @@ export type AssistantStreamEncoder = ReadableWritablePair<
 };
 
 export const AssistantStream = {
+  /**
+   * Converts an {@link AssistantStream} into a `Response` using the supplied
+   * encoder.
+   *
+   * The encoder's `headers` are copied onto the response. Pair this with the
+   * decoder for the same wire format when consuming the response.
+   */
   toResponse(stream: AssistantStream, transformer: AssistantStreamEncoder) {
     return new Response(AssistantStream.toByteStream(stream, transformer), {
       headers: transformer.headers ?? {},
     });
   },
 
+  /**
+   * Reads an assistant stream from a `Response` body using the supplied
+   * decoder.
+   *
+   * The response body must be present and encoded with the matching assistant
+   * stream wire format.
+   */
   fromResponse(
     response: Response,
     transformer: ReadableWritablePair<
@@ -26,6 +55,10 @@ export const AssistantStream = {
     return AssistantStream.fromByteStream(response.body!, transformer);
   },
 
+  /**
+   * Pipes an {@link AssistantStream} through an encoder and returns the
+   * resulting byte stream.
+   */
   toByteStream(
     stream: AssistantStream,
     transformer: ReadableWritablePair<
@@ -36,6 +69,10 @@ export const AssistantStream = {
     return stream.pipeThrough(transformer);
   },
 
+  /**
+   * Pipes a byte stream through a decoder and returns normalized
+   * {@link AssistantStreamChunk} values.
+   */
   fromByteStream(
     readable: ReadableStream<Uint8Array<ArrayBuffer>>,
     transformer: ReadableWritablePair<

package/src/core/AssistantStreamChunk.ts

@@ -2,6 +2,12 @@ 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";
@@ -34,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"
@@ -78,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"
@@ -93,6 +115,12 @@ 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;
@@ -101,10 +129,12 @@ export type AssistantStreamChunk = { readonly path: readonly number[] } & (
       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/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/tool/ToolResponse.ts

@@ -1,16 +1,53 @@
 import type { ReadonlyJSONValue } from "../../utils/json/json-value";
-import type { ToolModelContentPart } from "./tool-types";
+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;
@@ -44,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;