assistant-stream 0.3.14 → 0.3.15

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

@@ -6,19 +6,56 @@ 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[]
@@ -90,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>;
@@ -98,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,
@@ -135,6 +182,7 @@ 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;
@@ -149,13 +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>;
 };
 
@@ -163,16 +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,
@@ -183,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>,

package/src/core/tool/toolResultStream.ts

@@ -214,10 +214,25 @@ export async function unstable_runPendingTools(
 }
 
 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 function toolResultStream(
   tools:
     | Record<string, Tool>