assistant-stream 0.3.19 → 0.3.21

package/src/core/tool/schema-utils.ts

@@ -15,6 +15,8 @@ export type ToToolsJSONSchemaOptions = {
   /**
    * Filter to determine which tools to include.
    * Defaults to excluding disabled tools and backend tools.
+   *
+   * Tools with backend-default parameters are always excluded.
    */
   filter?: (name: string, tool: Tool) => boolean;
 };
@@ -130,7 +132,19 @@ export function toPartialJSONSchema(schema: JSONSchema7): JSONSchema7 {
 }
 
 function defaultToolFilter(_name: string, tool: Tool): boolean {
-  return !tool.disabled && tool.type !== "backend";
+  return (
+    !tool.disabled &&
+    tool.type !== "backend" &&
+    (tool.type !== "frontend" || tool.execute !== undefined)
+  );
+}
+
+function toolHasUploadableParameters(
+  tool: Tool,
+): tool is Tool & { parameters: NonNullable<Tool["parameters"]> } {
+  return (
+    tool.parameters !== undefined && !tool.unstable_backendDefault?.parameters
+  );
 }
 
 /**
@@ -152,13 +166,21 @@ export function toToolsJSONSchema(
 
   return Object.fromEntries(
     Object.entries(tools)
-      .filter(([name, tool]) => filter(name, tool) && tool.parameters)
+      .filter(([name, tool]) => filter(name, tool))
+      .filter(
+        (
+          entry,
+        ): entry is [
+          string,
+          Tool & { parameters: NonNullable<Tool["parameters"]> },
+        ] => toolHasUploadableParameters(entry[1]),
+      )
       .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
       .map(([name, tool]) => [
         name,
         {
           ...(tool.description && { description: tool.description }),
-          parameters: toJSONSchema(tool.parameters!),
+          parameters: toJSONSchema(tool.parameters),
           ...(tool.providerOptions && {
             providerOptions: tool.providerOptions,
           }),

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

@@ -216,6 +216,16 @@ type ToolBase<
    * @see ToolDisplay
    */
   display?: ToolDisplay;
+
+  /**
+   * @internal Defaults already known by the backend for this tool. Client
+   * transports omit matching fields and only upload overrides.
+   *
+   * This is only meaningful for frontend and human tools.
+   */
+  unstable_backendDefault?: {
+    parameters?: boolean;
+  };
 };
 
 type BackendTool<
@@ -276,7 +286,7 @@ type FrontendTool<
   /** 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>;
+  execute?: ToolExecuteFunction<TArgs, TResult>;
   /** Converts the execution result into model-visible output. */
   toModelOutput?: ToolModelOutputFunction<TArgs, TResult>;
   /** Handles invalid tool arguments when schema validation fails. */
@@ -305,6 +315,63 @@ type HumanTool<
   providerOptions?: ProviderOptions;
 };
 
+type ProviderTool<
+  TArgs extends Record<string, unknown> = Record<string, unknown>,
+  TResult = unknown,
+> = ToolBase<TArgs, TResult> & {
+  /** Tool executed by the LLM provider rather than assistant-ui. */
+  type: "provider";
+
+  /** Provider-defined tool identifier, e.g. `openai.web_search_preview`. */
+  providerId: `${string}.${string}`;
+  /** Schema used by adapters for validation and type plumbing. */
+  parameters?: StandardSchemaV1<TArgs> | JSONSchema7 | undefined;
+  /** Provider-specific configuration for this tool. */
+  args: Record<string, unknown>;
+  /**
+   * Whether provider results may arrive after the originating response turn.
+   */
+  supportsDeferredResults?: boolean;
+
+  description?: undefined;
+  disabled?: boolean;
+  execute?: undefined;
+  toModelOutput?: undefined;
+  experimental_onSchemaValidationError?: undefined;
+  providerOptions?: ProviderOptions;
+};
+
+export type McpServerConfig =
+  | {
+      /** Connect to an MCP server over Streamable HTTP or server-sent events. */
+      type: "http" | "sse";
+      url: string;
+      headers?: Record<string, string>;
+      redirect?: "follow" | "error";
+    }
+  | {
+      /** Start and connect to a local MCP server over stdio. */
+      type: "stdio";
+      command: string;
+      args?: readonly string[];
+      env?: Record<string, string>;
+      cwd?: string;
+    };
+
+type McpTool = ToolBase<Record<string, unknown>, unknown> & {
+  /** Tools loaded from an MCP server by a server adapter. */
+  type: "mcp";
+  server: McpServerConfig;
+
+  description?: undefined;
+  parameters?: undefined;
+  disabled?: boolean;
+  execute?: undefined;
+  toModelOutput?: undefined;
+  experimental_onSchemaValidationError?: undefined;
+  providerOptions?: undefined;
+};
+
 /**
  * Definition for a tool that can be exposed to the assistant model.
  *
@@ -353,6 +420,8 @@ export type Tool<
   | FrontendTool<TArgs, TResult>
   | BackendTool<TArgs, TResult>
   | HumanTool<TArgs, TResult>
+  | ProviderTool<TArgs, TResult>
+  | McpTool
   | ToolWithoutType<TArgs, TResult>;
 
 /**
@@ -368,6 +437,8 @@ export type ToolDeclaration<
   | FrontendTool<TArgs, TResult>
   | BackendToolDeclaration<TArgs, TResult>
   | HumanTool<TArgs, TResult>
+  | ProviderTool<TArgs, TResult>
+  | McpTool
   | ToolWithoutType<TArgs, TResult>;
 
 /**
@@ -380,4 +451,5 @@ export type ToolWithoutType<
   | Omit<FrontendTool<TArgs, TResult>, "type">
   | Omit<BackendTool<TArgs, TResult>, "type">
   | Omit<HumanTool<TArgs, TResult>, "type">
+  | Omit<ProviderTool<TArgs, TResult>, "type">
 ) & { type?: undefined };

package/src/index.ts

@@ -38,6 +38,7 @@ export type {
 export type {
   Tool,
   ToolDeclaration,
+  McpServerConfig,
   ToolModelContentPart,
   ToolModelOutputFunction,
 } from "./core/tool/tool-types";