@ai-sdk/gateway 3.0.26 → 3.0.28

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @ai-sdk/gateway
 
+## 3.0.28
+
+### Patch Changes
+
+- 1524271: chore: add skill information to README files
+
+## 3.0.27
+
+### Patch Changes
+
+- 0acff64: feat (provider/gateway): add parallel search tool
+
 ## 3.0.26
 
 ### Patch Changes

package/README.md

@@ -10,6 +10,14 @@ The Gateway provider is available in the `@ai-sdk/gateway` module. You can insta
 npm i @ai-sdk/gateway
 ```
 
+## Skill for Coding Agents
+
+If you use coding agents such as Claude Code or Cursor, we highly recommend adding the AI SDK skill to your repository:
+
+```shell
+npx skills add vercel/ai
+```
+
 ## Provider Instance
 
 You can import the default provider instance `gateway` from `@ai-sdk/gateway`:

package/dist/index.d.mts

@@ -194,10 +194,152 @@ interface PerplexitySearchInput {
 type PerplexitySearchOutput = PerplexitySearchResponse | PerplexitySearchError;
 declare const perplexitySearchToolFactory: _ai_sdk_provider_utils.ProviderToolFactoryWithOutputSchema<PerplexitySearchInput, PerplexitySearchOutput, PerplexitySearchConfig>;
 
+interface ParallelSearchSourcePolicy {
+    /**
+     * List of domains to include in search results.
+     * Example: ['wikipedia.org', 'nature.com']
+     */
+    includeDomains?: string[];
+    /**
+     * List of domains to exclude from search results.
+     * Example: ['reddit.com', 'twitter.com']
+     */
+    excludeDomains?: string[];
+    /**
+     * Only include results published after this date (ISO 8601 format).
+     * Example: '2024-01-01'
+     */
+    afterDate?: string;
+}
+interface ParallelSearchExcerpts {
+    /**
+     * Maximum characters per result.
+     */
+    maxCharsPerResult?: number;
+    /**
+     * Maximum total characters across all results.
+     */
+    maxCharsTotal?: number;
+}
+interface ParallelSearchFetchPolicy {
+    /**
+     * Maximum age in seconds for cached content.
+     * Set to 0 to always fetch fresh content.
+     */
+    maxAgeSeconds?: number;
+}
+interface ParallelSearchConfig {
+    /**
+     * Mode preset for different use cases:
+     * - "one-shot": Comprehensive results with longer excerpts for single-response answers (default)
+     * - "agentic": Concise, token-efficient results for multi-step agentic workflows
+     */
+    mode?: 'one-shot' | 'agentic';
+    /**
+     * Default maximum number of results to return (1-20).
+     * Defaults to 10 if not specified.
+     */
+    maxResults?: number;
+    /**
+     * Default source policy for controlling which domains to include/exclude.
+     */
+    sourcePolicy?: ParallelSearchSourcePolicy;
+    /**
+     * Default excerpt configuration for controlling result length.
+     */
+    excerpts?: ParallelSearchExcerpts;
+    /**
+     * Default fetch policy for controlling content freshness.
+     */
+    fetchPolicy?: ParallelSearchFetchPolicy;
+}
+interface ParallelSearchResult {
+    /** URL of the search result */
+    url: string;
+    /** Title of the search result */
+    title: string;
+    /** Extracted text excerpt/content from the page */
+    excerpt: string;
+    /** Publication date of the content (may be null) */
+    publishDate?: string | null;
+    /** Relevance score for the result */
+    relevanceScore?: number;
+}
+interface ParallelSearchResponse {
+    /** Unique identifier for this search request */
+    searchId: string;
+    /** Array of search results */
+    results: ParallelSearchResult[];
+}
+interface ParallelSearchError {
+    /** Error type */
+    error: 'api_error' | 'rate_limit' | 'timeout' | 'invalid_input' | 'configuration_error' | 'unknown';
+    /** HTTP status code if applicable */
+    statusCode?: number;
+    /** Human-readable error message */
+    message: string;
+}
+interface ParallelSearchInput {
+    /**
+     * Natural-language description of the web research goal.
+     * Include source or freshness guidance and broader context from the task.
+     * Maximum 5000 characters.
+     */
+    objective: string;
+    /**
+     * Optional search queries to supplement the objective.
+     * Maximum 200 characters per query.
+     */
+    search_queries?: string[];
+    /**
+     * Mode preset for different use cases:
+     * - "one-shot": Comprehensive results with longer excerpts
+     * - "agentic": Concise, token-efficient results for multi-step workflows
+     */
+    mode?: 'one-shot' | 'agentic';
+    /**
+     * Maximum number of results to return (1-20).
+     * Defaults to 10 if not specified.
+     */
+    max_results?: number;
+    /**
+     * Source policy for controlling which domains to include/exclude.
+     */
+    source_policy?: {
+        include_domains?: string[];
+        exclude_domains?: string[];
+        after_date?: string;
+    };
+    /**
+     * Excerpt configuration for controlling result length.
+     */
+    excerpts?: {
+        max_chars_per_result?: number;
+        max_chars_total?: number;
+    };
+    /**
+     * Fetch policy for controlling content freshness.
+     */
+    fetch_policy?: {
+        max_age_seconds?: number;
+    };
+}
+type ParallelSearchOutput = ParallelSearchResponse | ParallelSearchError;
+declare const parallelSearchToolFactory: _ai_sdk_provider_utils.ProviderToolFactoryWithOutputSchema<ParallelSearchInput, ParallelSearchOutput, ParallelSearchConfig>;
+
 /**
  * Gateway-specific provider-defined tools.
  */
 declare const gatewayTools: {
+    /**
+     * Search the web using Parallel AI's Search API for LLM-optimized excerpts.
+     *
+     * Takes a natural language objective and returns relevant excerpts,
+     * replacing multiple keyword searches with a single call for broad
+     * or complex queries. Supports different search types for depth vs
+     * breadth tradeoffs.
+     */
+    parallelSearch: (config?: ParallelSearchConfig) => ReturnType<typeof parallelSearchToolFactory>;
     /**
      * Search the web using Perplexity's Search API for real-time information,
      * news, research papers, and articles.

package/dist/index.d.ts

@@ -194,10 +194,152 @@ interface PerplexitySearchInput {
 type PerplexitySearchOutput = PerplexitySearchResponse | PerplexitySearchError;
 declare const perplexitySearchToolFactory: _ai_sdk_provider_utils.ProviderToolFactoryWithOutputSchema<PerplexitySearchInput, PerplexitySearchOutput, PerplexitySearchConfig>;
 
+interface ParallelSearchSourcePolicy {
+    /**
+     * List of domains to include in search results.
+     * Example: ['wikipedia.org', 'nature.com']
+     */
+    includeDomains?: string[];
+    /**
+     * List of domains to exclude from search results.
+     * Example: ['reddit.com', 'twitter.com']
+     */
+    excludeDomains?: string[];
+    /**
+     * Only include results published after this date (ISO 8601 format).
+     * Example: '2024-01-01'
+     */
+    afterDate?: string;
+}
+interface ParallelSearchExcerpts {
+    /**
+     * Maximum characters per result.
+     */
+    maxCharsPerResult?: number;
+    /**
+     * Maximum total characters across all results.
+     */
+    maxCharsTotal?: number;
+}
+interface ParallelSearchFetchPolicy {
+    /**
+     * Maximum age in seconds for cached content.
+     * Set to 0 to always fetch fresh content.
+     */
+    maxAgeSeconds?: number;
+}
+interface ParallelSearchConfig {
+    /**
+     * Mode preset for different use cases:
+     * - "one-shot": Comprehensive results with longer excerpts for single-response answers (default)
+     * - "agentic": Concise, token-efficient results for multi-step agentic workflows
+     */
+    mode?: 'one-shot' | 'agentic';
+    /**
+     * Default maximum number of results to return (1-20).
+     * Defaults to 10 if not specified.
+     */
+    maxResults?: number;
+    /**
+     * Default source policy for controlling which domains to include/exclude.
+     */
+    sourcePolicy?: ParallelSearchSourcePolicy;
+    /**
+     * Default excerpt configuration for controlling result length.
+     */
+    excerpts?: ParallelSearchExcerpts;
+    /**
+     * Default fetch policy for controlling content freshness.
+     */
+    fetchPolicy?: ParallelSearchFetchPolicy;
+}
+interface ParallelSearchResult {
+    /** URL of the search result */
+    url: string;
+    /** Title of the search result */
+    title: string;
+    /** Extracted text excerpt/content from the page */
+    excerpt: string;
+    /** Publication date of the content (may be null) */
+    publishDate?: string | null;
+    /** Relevance score for the result */
+    relevanceScore?: number;
+}
+interface ParallelSearchResponse {
+    /** Unique identifier for this search request */
+    searchId: string;
+    /** Array of search results */
+    results: ParallelSearchResult[];
+}
+interface ParallelSearchError {
+    /** Error type */
+    error: 'api_error' | 'rate_limit' | 'timeout' | 'invalid_input' | 'configuration_error' | 'unknown';
+    /** HTTP status code if applicable */
+    statusCode?: number;
+    /** Human-readable error message */
+    message: string;
+}
+interface ParallelSearchInput {
+    /**
+     * Natural-language description of the web research goal.
+     * Include source or freshness guidance and broader context from the task.
+     * Maximum 5000 characters.
+     */
+    objective: string;
+    /**
+     * Optional search queries to supplement the objective.
+     * Maximum 200 characters per query.
+     */
+    search_queries?: string[];
+    /**
+     * Mode preset for different use cases:
+     * - "one-shot": Comprehensive results with longer excerpts
+     * - "agentic": Concise, token-efficient results for multi-step workflows
+     */
+    mode?: 'one-shot' | 'agentic';
+    /**
+     * Maximum number of results to return (1-20).
+     * Defaults to 10 if not specified.
+     */
+    max_results?: number;
+    /**
+     * Source policy for controlling which domains to include/exclude.
+     */
+    source_policy?: {
+        include_domains?: string[];
+        exclude_domains?: string[];
+        after_date?: string;
+    };
+    /**
+     * Excerpt configuration for controlling result length.
+     */
+    excerpts?: {
+        max_chars_per_result?: number;
+        max_chars_total?: number;
+    };
+    /**
+     * Fetch policy for controlling content freshness.
+     */
+    fetch_policy?: {
+        max_age_seconds?: number;
+    };
+}
+type ParallelSearchOutput = ParallelSearchResponse | ParallelSearchError;
+declare const parallelSearchToolFactory: _ai_sdk_provider_utils.ProviderToolFactoryWithOutputSchema<ParallelSearchInput, ParallelSearchOutput, ParallelSearchConfig>;
+
 /**
  * Gateway-specific provider-defined tools.
  */
 declare const gatewayTools: {
+    /**
+     * Search the web using Parallel AI's Search API for LLM-optimized excerpts.
+     *
+     * Takes a natural language objective and returns relevant excerpts,
+     * replacing multiple keyword searches with a single call for broad
+     * or complex queries. Supports different search types for depth vs
+     * breadth tradeoffs.
+     */
+    parallelSearch: (config?: ParallelSearchConfig) => ReturnType<typeof parallelSearchToolFactory>;
     /**
      * Search the web using Perplexity's Search API for real-time information,
      * news, research papers, and articles.

package/dist/index.js

@@ -34,7 +34,7 @@ __export(src_exports, {
 module.exports = __toCommonJS(src_exports);
 
 // src/gateway-provider.ts
-var import_provider_utils9 = require("@ai-sdk/provider-utils");
+var import_provider_utils10 = require("@ai-sdk/provider-utils");
 
 // src/errors/as-gateway-error.ts
 var import_provider = require("@ai-sdk/provider");
@@ -847,83 +847,161 @@ var gatewayImageResponseSchema = import_v47.z.object({
   providerMetadata: import_v47.z.record(import_v47.z.string(), providerMetadataEntrySchema).optional()
 });
 
-// src/tool/perplexity-search.ts
+// src/tool/parallel-search.ts
 var import_provider_utils8 = require("@ai-sdk/provider-utils");
 var import_zod = require("zod");
-var perplexitySearchInputSchema = (0, import_provider_utils8.lazySchema)(
+var parallelSearchInputSchema = (0, import_provider_utils8.lazySchema)(
   () => (0, import_provider_utils8.zodSchema)(
     import_zod.z.object({
-      query: import_zod.z.union([import_zod.z.string(), import_zod.z.array(import_zod.z.string())]).describe(
-        "Search query (string) or multiple queries (array of up to 5 strings). Multi-query searches return combined results from all queries."
+      objective: import_zod.z.string().describe(
+        "Natural-language description of the web research goal, including source or freshness guidance and broader context from the task. Maximum 5000 characters."
+      ),
+      search_queries: import_zod.z.array(import_zod.z.string()).optional().describe(
+        "Optional search queries to supplement the objective. Maximum 200 characters per query."
+      ),
+      mode: import_zod.z.enum(["one-shot", "agentic"]).optional().describe(
+        'Mode preset: "one-shot" for comprehensive results with longer excerpts (default), "agentic" for concise, token-efficient results for multi-step workflows.'
       ),
       max_results: import_zod.z.number().optional().describe(
+        "Maximum number of results to return (1-20). Defaults to 10 if not specified."
+      ),
+      source_policy: import_zod.z.object({
+        include_domains: import_zod.z.array(import_zod.z.string()).optional().describe("List of domains to include in search results."),
+        exclude_domains: import_zod.z.array(import_zod.z.string()).optional().describe("List of domains to exclude from search results."),
+        after_date: import_zod.z.string().optional().describe(
+          "Only include results published after this date (ISO 8601 format)."
+        )
+      }).optional().describe(
+        "Source policy for controlling which domains to include/exclude and freshness."
+      ),
+      excerpts: import_zod.z.object({
+        max_chars_per_result: import_zod.z.number().optional().describe("Maximum characters per result."),
+        max_chars_total: import_zod.z.number().optional().describe("Maximum total characters across all results.")
+      }).optional().describe("Excerpt configuration for controlling result length."),
+      fetch_policy: import_zod.z.object({
+        max_age_seconds: import_zod.z.number().optional().describe(
+          "Maximum age in seconds for cached content. Set to 0 to always fetch fresh content."
+        )
+      }).optional().describe("Fetch policy for controlling content freshness.")
+    })
+  )
+);
+var parallelSearchOutputSchema = (0, import_provider_utils8.lazySchema)(
+  () => (0, import_provider_utils8.zodSchema)(
+    import_zod.z.union([
+      // Success response
+      import_zod.z.object({
+        searchId: import_zod.z.string(),
+        results: import_zod.z.array(
+          import_zod.z.object({
+            url: import_zod.z.string(),
+            title: import_zod.z.string(),
+            excerpt: import_zod.z.string(),
+            publishDate: import_zod.z.string().nullable().optional(),
+            relevanceScore: import_zod.z.number().optional()
+          })
+        )
+      }),
+      // Error response
+      import_zod.z.object({
+        error: import_zod.z.enum([
+          "api_error",
+          "rate_limit",
+          "timeout",
+          "invalid_input",
+          "configuration_error",
+          "unknown"
+        ]),
+        statusCode: import_zod.z.number().optional(),
+        message: import_zod.z.string()
+      })
+    ])
+  )
+);
+var parallelSearchToolFactory = (0, import_provider_utils8.createProviderToolFactoryWithOutputSchema)({
+  id: "gateway.parallel_search",
+  inputSchema: parallelSearchInputSchema,
+  outputSchema: parallelSearchOutputSchema
+});
+var parallelSearch = (config = {}) => parallelSearchToolFactory(config);
+
+// src/tool/perplexity-search.ts
+var import_provider_utils9 = require("@ai-sdk/provider-utils");
+var import_zod2 = require("zod");
+var perplexitySearchInputSchema = (0, import_provider_utils9.lazySchema)(
+  () => (0, import_provider_utils9.zodSchema)(
+    import_zod2.z.object({
+      query: import_zod2.z.union([import_zod2.z.string(), import_zod2.z.array(import_zod2.z.string())]).describe(
+        "Search query (string) or multiple queries (array of up to 5 strings). Multi-query searches return combined results from all queries."
+      ),
+      max_results: import_zod2.z.number().optional().describe(
         "Maximum number of search results to return (1-20, default: 10)"
       ),
-      max_tokens_per_page: import_zod.z.number().optional().describe(
+      max_tokens_per_page: import_zod2.z.number().optional().describe(
         "Maximum number of tokens to extract per search result page (256-2048, default: 2048)"
       ),
-      max_tokens: import_zod.z.number().optional().describe(
+      max_tokens: import_zod2.z.number().optional().describe(
         "Maximum total tokens across all search results (default: 25000, max: 1000000)"
       ),
-      country: import_zod.z.string().optional().describe(
+      country: import_zod2.z.string().optional().describe(
         "Two-letter ISO 3166-1 alpha-2 country code for regional search results (e.g., 'US', 'GB', 'FR')"
       ),
-      search_domain_filter: import_zod.z.array(import_zod.z.string()).optional().describe(
+      search_domain_filter: import_zod2.z.array(import_zod2.z.string()).optional().describe(
         "List of domains to include or exclude from search results (max 20). To include: ['nature.com', 'science.org']. To exclude: ['-example.com', '-spam.net']"
       ),
-      search_language_filter: import_zod.z.array(import_zod.z.string()).optional().describe(
+      search_language_filter: import_zod2.z.array(import_zod2.z.string()).optional().describe(
         "List of ISO 639-1 language codes to filter results (max 10, lowercase). Examples: ['en', 'fr', 'de']"
       ),
-      search_after_date: import_zod.z.string().optional().describe(
+      search_after_date: import_zod2.z.string().optional().describe(
         "Include only results published after this date. Format: 'MM/DD/YYYY' (e.g., '3/1/2025'). Cannot be used with search_recency_filter."
       ),
-      search_before_date: import_zod.z.string().optional().describe(
+      search_before_date: import_zod2.z.string().optional().describe(
         "Include only results published before this date. Format: 'MM/DD/YYYY' (e.g., '3/15/2025'). Cannot be used with search_recency_filter."
       ),
-      last_updated_after_filter: import_zod.z.string().optional().describe(
+      last_updated_after_filter: import_zod2.z.string().optional().describe(
         "Include only results last updated after this date. Format: 'MM/DD/YYYY' (e.g., '3/1/2025'). Cannot be used with search_recency_filter."
       ),
-      last_updated_before_filter: import_zod.z.string().optional().describe(
+      last_updated_before_filter: import_zod2.z.string().optional().describe(
         "Include only results last updated before this date. Format: 'MM/DD/YYYY' (e.g., '3/15/2025'). Cannot be used with search_recency_filter."
       ),
-      search_recency_filter: import_zod.z.enum(["day", "week", "month", "year"]).optional().describe(
+      search_recency_filter: import_zod2.z.enum(["day", "week", "month", "year"]).optional().describe(
         "Filter results by relative time period. Cannot be used with search_after_date or search_before_date."
       )
     })
   )
 );
-var perplexitySearchOutputSchema = (0, import_provider_utils8.lazySchema)(
-  () => (0, import_provider_utils8.zodSchema)(
-    import_zod.z.union([
+var perplexitySearchOutputSchema = (0, import_provider_utils9.lazySchema)(
+  () => (0, import_provider_utils9.zodSchema)(
+    import_zod2.z.union([
       // Success response
-      import_zod.z.object({
-        results: import_zod.z.array(
-          import_zod.z.object({
-            title: import_zod.z.string(),
-            url: import_zod.z.string(),
-            snippet: import_zod.z.string(),
-            date: import_zod.z.string().optional(),
-            lastUpdated: import_zod.z.string().optional()
+      import_zod2.z.object({
+        results: import_zod2.z.array(
+          import_zod2.z.object({
+            title: import_zod2.z.string(),
+            url: import_zod2.z.string(),
+            snippet: import_zod2.z.string(),
+            date: import_zod2.z.string().optional(),
+            lastUpdated: import_zod2.z.string().optional()
           })
         ),
-        id: import_zod.z.string()
+        id: import_zod2.z.string()
       }),
       // Error response
-      import_zod.z.object({
-        error: import_zod.z.enum([
+      import_zod2.z.object({
+        error: import_zod2.z.enum([
           "api_error",
           "rate_limit",
           "timeout",
           "invalid_input",
           "unknown"
         ]),
-        statusCode: import_zod.z.number().optional(),
-        message: import_zod.z.string()
+        statusCode: import_zod2.z.number().optional(),
+        message: import_zod2.z.string()
       })
     ])
   )
 );
-var perplexitySearchToolFactory = (0, import_provider_utils8.createProviderToolFactoryWithOutputSchema)({
+var perplexitySearchToolFactory = (0, import_provider_utils9.createProviderToolFactoryWithOutputSchema)({
   id: "gateway.perplexity_search",
   inputSchema: perplexitySearchInputSchema,
   outputSchema: perplexitySearchOutputSchema
@@ -932,6 +1010,15 @@ var perplexitySearch = (config = {}) => perplexitySearchToolFactory(config);
 
 // src/gateway-tools.ts
 var gatewayTools = {
+  /**
+   * Search the web using Parallel AI's Search API for LLM-optimized excerpts.
+   *
+   * Takes a natural language objective and returns relevant excerpts,
+   * replacing multiple keyword searches with a single call for broad
+   * or complex queries. Supports different search types for depth vs
+   * breadth tradeoffs.
+   */
+  parallelSearch,
   /**
    * Search the web using Perplexity's Search API for real-time information,
    * news, research papers, and articles.
@@ -951,10 +1038,10 @@ async function getVercelRequestId() {
 }
 
 // src/gateway-provider.ts
-var import_provider_utils10 = require("@ai-sdk/provider-utils");
+var import_provider_utils11 = require("@ai-sdk/provider-utils");
 
 // src/version.ts
-var VERSION = true ? "3.0.26" : "0.0.0-test";
+var VERSION = true ? "3.0.28" : "0.0.0-test";
 
 // src/gateway-provider.ts
 var AI_GATEWAY_PROTOCOL_VERSION = "0.0.1";
@@ -964,11 +1051,11 @@ function createGatewayProvider(options = {}) {
   let metadataCache = null;
   const cacheRefreshMillis = (_a8 = options.metadataCacheRefreshMillis) != null ? _a8 : 1e3 * 60 * 5;
   let lastFetchTime = 0;
-  const baseURL = (_b8 = (0, import_provider_utils9.withoutTrailingSlash)(options.baseURL)) != null ? _b8 : "https://ai-gateway.vercel.sh/v3/ai";
+  const baseURL = (_b8 = (0, import_provider_utils10.withoutTrailingSlash)(options.baseURL)) != null ? _b8 : "https://ai-gateway.vercel.sh/v3/ai";
   const getHeaders = async () => {
     try {
       const auth = await getGatewayAuthToken(options);
-      return (0, import_provider_utils10.withUserAgentSuffix)(
+      return (0, import_provider_utils11.withUserAgentSuffix)(
         {
           Authorization: `Bearer ${auth.token}`,
           "ai-gateway-protocol-version": AI_GATEWAY_PROTOCOL_VERSION,
@@ -987,15 +1074,15 @@ function createGatewayProvider(options = {}) {
     }
   };
   const createO11yHeaders = () => {
-    const deploymentId = (0, import_provider_utils9.loadOptionalSetting)({
+    const deploymentId = (0, import_provider_utils10.loadOptionalSetting)({
       settingValue: void 0,
       environmentVariableName: "VERCEL_DEPLOYMENT_ID"
     });
-    const environment = (0, import_provider_utils9.loadOptionalSetting)({
+    const environment = (0, import_provider_utils10.loadOptionalSetting)({
       settingValue: void 0,
       environmentVariableName: "VERCEL_ENV"
     });
-    const region = (0, import_provider_utils9.loadOptionalSetting)({
+    const region = (0, import_provider_utils10.loadOptionalSetting)({
       settingValue: void 0,
       environmentVariableName: "VERCEL_REGION"
     });
@@ -1088,7 +1175,7 @@ function createGatewayProvider(options = {}) {
 }
 var gateway = createGatewayProvider();
 async function getGatewayAuthToken(options) {
-  const apiKey = (0, import_provider_utils9.loadOptionalSetting)({
+  const apiKey = (0, import_provider_utils10.loadOptionalSetting)({
     settingValue: options.apiKey,
     environmentVariableName: "AI_GATEWAY_API_KEY"
   });