assistant-stream 0.3.16 → 0.3.18

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

@@ -98,7 +98,7 @@ export interface ToolCallArgsReader<TArgs extends Record<string, unknown>> {
    */
   streamText<PathT extends TypePath<TArgs>>(
     ...fieldPath: PathT
-  ): TypeAtPath<TArgs, PathT> extends string & infer U
+  ): TypeAtPath<TArgs, PathT> extends string & (infer U)
     ? AsyncIterableStream<U>
     : never;
 
@@ -168,6 +168,35 @@ type OnSchemaValidationErrorFunction<TResult> = ToolExecuteFunction<
   TResult
 >;
 
+/**
+ * Per-provider metadata forwarded into the wire request body verbatim.
+ * assistant-ui does not interpret these values; downstream adapters (AI SDK,
+ * custom routes) pass them to the model provider as-is.
+ *
+ * The outer key is the provider name (`anthropic`, `openai`, ...); the inner
+ * object is whatever shape that provider's SDK expects under
+ * `tool.providerOptions[providerName]`. Use this to enable provider-specific
+ * tool behaviors such as Anthropic's `defer_loading`
+ * (`{ anthropic: { deferLoading: true } }`) without adding provider-aware
+ * code in assistant-ui.
+ */
+export type ProviderOptions = Record<string, Record<string, unknown>>;
+
+/**
+ * Controls how a tool call's UI is presented relative to the assistant's
+ * chain-of-thought trace.
+ *
+ * - `"inline"` — the tool call is part of the reasoning trace and is folded
+ *   into the chain-of-thought grouping alongside other routine tool calls.
+ * - `"standalone"` — the tool call is surfaced on its own, outside the
+ *   chain-of-thought grouping (e.g. a human-in-the-loop prompt, a generative
+ *   UI surface, or an important action UI worth showing prominently).
+ *
+ * This is a client-side presentation hint only; it does not affect how the
+ * tool is exposed to or executed by the model.
+ */
+type ToolDisplay = "standalone" | "inline";
+
 type ToolBase<
   TArgs extends Record<string, unknown> = Record<string, unknown>,
   TResult = unknown,
@@ -176,6 +205,17 @@ type ToolBase<
    * @deprecated Experimental, API may change.
    */
   streamCall?: ToolStreamCallFunction<TArgs, TResult>;
+
+  /**
+   * How this tool's UI is presented relative to the chain-of-thought trace.
+   *
+   * Defaults to `"inline"` (folded into the chain-of-thought grouping).
+   * Set `"standalone"` to surface the tool call on its own. `human` tools are
+   * always `"standalone"` and cannot opt out.
+   *
+   * @see ToolDisplay
+   */
+  display?: ToolDisplay;
 };
 
 type BackendTool<
@@ -191,6 +231,35 @@ type BackendTool<
   execute?: undefined;
   toModelOutput?: undefined;
   experimental_onSchemaValidationError?: undefined;
+  providerOptions?: undefined;
+};
+
+/**
+ * Backend tool as *authored* (a {@link ToolDeclaration}), before the build
+ * splits it: it may declare a `description`, `parameters`, and a server-side
+ * `execute`. The canonical {@link BackendTool} keeps these `undefined` because,
+ * once split, the client never sees them and the server consumes them through a
+ * server adapter rather than the shared {@link Tool} shape.
+ */
+type BackendToolDeclaration<
+  TArgs extends Record<string, unknown> = Record<string, unknown>,
+  TResult = unknown,
+> = ToolBase<TArgs, TResult> & {
+  type: "backend";
+
+  /** 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 | undefined;
+  /** Prevents the tool from being exposed to the model while true. */
+  disabled?: boolean;
+  /** Executes the tool on the server 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>;
+  providerOptions?: ProviderOptions;
 };
 
 type FrontendTool<
@@ -212,6 +281,7 @@ type FrontendTool<
   toModelOutput?: ToolModelOutputFunction<TArgs, TResult>;
   /** Handles invalid tool arguments when schema validation fails. */
   experimental_onSchemaValidationError?: OnSchemaValidationErrorFunction<TResult>;
+  providerOptions?: ProviderOptions;
 };
 
 type HumanTool<
@@ -227,9 +297,12 @@ type HumanTool<
   parameters: StandardSchemaV1<TArgs> | JSONSchema7;
   /** Prevents the tool from being exposed to the model while true. */
   disabled?: boolean;
+  /** Human tools are always surfaced standalone and cannot opt out. */
+  display?: "standalone";
   execute?: undefined;
   toModelOutput?: undefined;
   experimental_onSchemaValidationError?: undefined;
+  providerOptions?: ProviderOptions;
 };
 
 /**
@@ -282,6 +355,21 @@ export type Tool<
   | HumanTool<TArgs, TResult>
   | ToolWithoutType<TArgs, TResult>;
 
+/**
+ * A tool as *authored* — the permissive counterpart to {@link Tool}. Unlike
+ * {@link Tool}, a `backend` entry may declare `description`, `parameters`, and a
+ * server-side `execute`. Use this for the input of authoring helpers (e.g.
+ * `defineToolkit`); the canonical {@link Tool} is the output.
+ */
+export type ToolDeclaration<
+  TArgs extends Record<string, unknown> = Record<string, unknown>,
+  TResult = unknown,
+> =
+  | FrontendTool<TArgs, TResult>
+  | BackendToolDeclaration<TArgs, TResult>
+  | HumanTool<TArgs, TResult>
+  | ToolWithoutType<TArgs, TResult>;
+
 /**
  * @deprecated Use {@link Tool} with an explicit `type` field instead.
  */

package/src/index.ts

@@ -37,12 +37,13 @@ export type {
 
 export type {
   Tool,
+  ToolDeclaration,
   ToolModelContentPart,
   ToolModelOutputFunction,
 } from "./core/tool/tool-types";
 export { ToolResponse, type ToolResponseLike } from "./core/tool/ToolResponse";
 export { ToolExecutionStream } from "./core/tool/ToolExecutionStream";
-export type { ToolCallReader } from "./core/tool/tool-types";
+export type { ProviderOptions, ToolCallReader } from "./core/tool/tool-types";
 export {
   toolResultStream as unstable_toolResultStream,
   unstable_runPendingTools,

package/src/resumable/index.ts

@@ -6,10 +6,7 @@ export type {
   ResumableStreamAcquireOptions,
 } from "./types";
 
-export {
-  ResumableStreamError,
-  type ResumableStreamErrorCode,
-} from "./errors";
+export { ResumableStreamError, type ResumableStreamErrorCode } from "./errors";
 
 export {
   createResumableStreamContext,