pi-web-providers 3.4.0 → 3.5.1

package/dist/index.js

@@ -1276,6 +1276,12 @@ function literalUnion(values, options) {
     options
   );
 }
+function boolOrConfig(options) {
+  return Type2.Union(
+    [Type2.Boolean(), Type2.Record(Type2.String(), Type2.Any())],
+    options
+  );
+}
 
 // src/providers/claude.ts
 var SEARCH_OUTPUT_SCHEMA = {
@@ -1358,6 +1364,11 @@ var claudeOptionsSchema = Type3.Object(
   },
   { description: "Claude options." }
 );
+var claudeSearchPromptGuidelines = [
+  "Use Claude search when Claude Code's agentic web-browsing and synthesis are useful for finding likely sources.",
+  "Increase effort or maxTurns only for difficult, ambiguous, or multi-step source discovery; keep defaults for simple searches.",
+  "Prefer web_contents after Claude search when the task requires direct inspection of a small set of selected URLs."
+];
 var claudeImplementation = {
   id: "claude",
   label: "Claude",
@@ -1615,6 +1626,7 @@ var claudeProvider = defineProvider({
   capabilities: {
     search: defineCapability({
       options: claudeImplementation.getToolOptionsSchema?.("search"),
+      promptGuidelines: claudeSearchPromptGuidelines,
       async execute(input, ctx) {
         const { query: query2, maxResults, options } = input;
         return await claudeImplementation.search(
@@ -1833,6 +1845,11 @@ var codexSearchOptionsSchema = Type5.Object(
   },
   { description: "Codex search options." }
 );
+var codexSearchPromptGuidelines = [
+  "Use Codex search when the local Codex SDK should perform web-backed source discovery, especially for coding or developer-oriented investigations.",
+  "Use webSearchMode='live' for current information and 'cached' when freshness is less important; do not set 'disabled' for normal web_search calls.",
+  "Increase modelReasoningEffort only for difficult or ambiguous searches where deeper reasoning is worth the extra latency."
+];
 var codexImplementation = {
   id: "codex",
   label: "Codex",
@@ -2013,6 +2030,7 @@ var codexProvider = defineProvider({
   capabilities: {
     search: defineCapability({
       options: codexImplementation.getToolOptionsSchema?.("search"),
+      promptGuidelines: codexSearchPromptGuidelines,
       async execute(input, ctx) {
         const { query: query2, maxResults, options } = input;
         return await codexImplementation.search(
@@ -2806,9 +2824,9 @@ var exaSearchOptionsSchema = Type6.Object(
           "hybrid",
           "fast",
           "instant",
+          "deep-lite",
           "deep",
-          "deep-reasoning",
-          "deep-max"
+          "deep-reasoning"
         ],
         { description: "Exa search mode." }
       )
@@ -2826,6 +2844,14 @@ var exaSearchOptionsSchema = Type6.Object(
     excludeDomains: Type6.Optional(
       Type6.Array(Type6.String(), { description: "Exclude these domains." })
     ),
+    startCrawlDate: Type6.Optional(
+      Type6.String({
+        description: "ISO date string for earliest crawl date."
+      })
+    ),
+    endCrawlDate: Type6.Optional(
+      Type6.String({ description: "ISO date string for latest crawl date." })
+    ),
     startPublishedDate: Type6.Optional(
       Type6.String({
         description: "ISO date string for earliest publish date."
@@ -2834,48 +2860,173 @@ var exaSearchOptionsSchema = Type6.Object(
     endPublishedDate: Type6.Optional(
       Type6.String({ description: "ISO date string for latest publish date." })
     ),
+    includeText: Type6.Optional(
+      Type6.Array(Type6.String(), {
+        description: "Require result page text to contain these terms. Exa currently supports one short phrase."
+      })
+    ),
+    excludeText: Type6.Optional(
+      Type6.Array(Type6.String(), {
+        description: "Require result page text not to contain these terms. Exa currently supports one short phrase."
+      })
+    ),
+    systemPrompt: Type6.Optional(
+      Type6.String({
+        description: "Additional Exa instructions for deep search source selection and synthesis."
+      })
+    ),
+    additionalQueries: Type6.Optional(
+      Type6.Array(Type6.String(), {
+        maxItems: 5,
+        description: "Alternative query formulations for Exa deep search variants."
+      })
+    ),
     userLocation: Type6.Optional(
-      Type6.Object(
-        {
-          country: Type6.Optional(
-            Type6.String({ description: "Country hint for the user location." })
-          ),
-          region: Type6.Optional(
-            Type6.String({ description: "Region hint for the user location." })
-          ),
-          city: Type6.Optional(
-            Type6.String({ description: "City hint for the user location." })
-          ),
-          timezone: Type6.Optional(
-            Type6.String({
-              description: "Timezone hint for the user location."
-            })
-          )
-        },
-        {
-          description: "User location hint passed through to the Exa SDK."
-        }
-      )
+      Type6.String({
+        description: "Two-letter ISO country code for the user location, such as 'US'."
+      })
     ),
     contents: Type6.Optional(
       Type6.Object(
         {
           text: Type6.Optional(
-            Type6.Boolean({ description: "Include text content." })
+            Type6.Union(
+              [
+                Type6.Boolean(),
+                Type6.Object(
+                  {
+                    maxCharacters: Type6.Optional(
+                      Type6.Integer({
+                        minimum: 1,
+                        description: "Maximum text characters per result."
+                      })
+                    ),
+                    includeHtmlTags: Type6.Optional(
+                      Type6.Boolean({
+                        description: "Include HTML tags in returned text."
+                      })
+                    ),
+                    verbosity: Type6.Optional(
+                      literalUnion(["compact", "standard", "full"], {
+                        description: "Verbosity level for returned text."
+                      })
+                    )
+                  },
+                  { additionalProperties: false }
+                )
+              ],
+              { description: "Include text content." }
+            )
           ),
           highlights: Type6.Optional(
-            Type6.Boolean({ description: "Include highlighted excerpts." })
+            Type6.Union(
+              [
+                Type6.Boolean(),
+                Type6.Object(
+                  {
+                    query: Type6.Optional(
+                      Type6.String({
+                        description: "Query to use for highlights."
+                      })
+                    ),
+                    maxCharacters: Type6.Optional(
+                      Type6.Integer({
+                        minimum: 1,
+                        description: "Maximum highlight characters."
+                      })
+                    )
+                  },
+                  { additionalProperties: false }
+                )
+              ],
+              { description: "Include highlighted excerpts." }
+            )
           ),
           summary: Type6.Optional(
-            Type6.Boolean({ description: "Include AI-generated summary." })
+            Type6.Union(
+              [
+                Type6.Boolean(),
+                Type6.Object(
+                  {
+                    query: Type6.Optional(
+                      Type6.String({
+                        description: "Query to guide summary generation."
+                      })
+                    )
+                  },
+                  { additionalProperties: false }
+                )
+              ],
+              { description: "Include AI-generated summary." }
+            )
+          ),
+          livecrawl: Type6.Optional(
+            literalUnion(["never", "fallback", "always", "auto", "preferred"], {
+              description: "Livecrawl mode for fetching fresh content."
+            })
+          ),
+          livecrawlTimeout: Type6.Optional(
+            Type6.Integer({
+              minimum: 0,
+              description: "Livecrawl timeout in milliseconds."
+            })
+          ),
+          maxAgeHours: Type6.Optional(
+            Type6.Number({
+              description: "Maximum age of cached content in hours. Use 0 to always fetch fresh content."
+            })
+          ),
+          filterEmptyResults: Type6.Optional(
+            Type6.Boolean({ description: "Filter results with no contents." })
+          ),
+          subpages: Type6.Optional(
+            Type6.Integer({
+              minimum: 0,
+              description: "Number of subpages to return for each result."
+            })
+          ),
+          subpageTarget: Type6.Optional(
+            Type6.Union([Type6.String(), Type6.Array(Type6.String())], {
+              description: "Text used to match/rank returned subpages."
+            })
+          ),
+          extras: Type6.Optional(
+            Type6.Object(
+              {
+                links: Type6.Optional(
+                  Type6.Integer({
+                    minimum: 0,
+                    description: "Number of page links to include."
+                  })
+                ),
+                imageLinks: Type6.Optional(
+                  Type6.Integer({
+                    minimum: 0,
+                    description: "Number of image links to include."
+                  })
+                )
+              },
+              { additionalProperties: false }
+            )
           )
         },
-        { description: "What content to include in results." }
+        {
+          additionalProperties: false,
+          description: "What content to include in results."
+        }
       )
     )
   },
   { description: "Exa search options." }
 );
+var exaSearchPromptGuidelines = [
+  "Use Exa's neural/auto search modes for semantic source discovery where exact keywords are uncertain; use keyword mode when exact terms, names, or identifiers matter.",
+  "Use Exa category filters such as 'research paper' or 'company' when the user asks for a specific source type.",
+  "Set includeDomains or excludeDomains when the task names preferred sources, requires primary sources, or needs noisy domains filtered out.",
+  "Use startCrawlDate/endCrawlDate or contents.maxAgeHours when freshness of Exa's crawled content matters.",
+  "Use includeText/excludeText for short required or forbidden phrases in page text.",
+  "Request contents.text, contents.highlights, or contents.summary only when snippets are insufficient and richer source context is needed directly in search results."
+];
 var exaImplementation = {
   id: "exa",
   label: "Exa",
@@ -3046,6 +3197,7 @@ var exaProvider = defineProvider({
   capabilities: {
     search: defineCapability({
       options: exaImplementation.getToolOptionsSchema?.("search"),
+      promptGuidelines: exaSearchPromptGuidelines,
       async execute(input, ctx) {
         const { query: query2, maxResults, options } = input;
         return await exaImplementation.search(
@@ -3121,6 +3273,26 @@ var firecrawlSearchOptionsSchema = Type7.Object(
         description: "Search categories to include."
       })
     ),
+    includeDomains: Type7.Optional(
+      Type7.Array(Type7.String(), {
+        description: "Restrict results to these domains."
+      })
+    ),
+    excludeDomains: Type7.Optional(
+      Type7.Array(Type7.String(), {
+        description: "Exclude these domains."
+      })
+    ),
+    tbs: Type7.Optional(
+      Type7.String({
+        description: "Google-style time-based search filter."
+      })
+    ),
+    ignoreInvalidURLs: Type7.Optional(
+      Type7.Boolean({
+        description: "Ignore invalid result URLs returned by search."
+      })
+    ),
     location: Type7.Optional(
       Type7.Object(
         {
@@ -3141,9 +3313,22 @@ var firecrawlSearchOptionsSchema = Type7.Object(
       Type7.Object(
         {
           formats: Type7.Optional(
-            Type7.Array(literalUnion(["markdown", "html", "rawHtml"]), {
-              description: "Output formats."
-            })
+            Type7.Array(
+              literalUnion([
+                "markdown",
+                "html",
+                "rawHtml",
+                "links",
+                "images",
+                "screenshot",
+                "summary",
+                "json",
+                "attributes"
+              ]),
+              {
+                description: "Output formats."
+              }
+            )
           ),
           onlyMainContent: Type7.Optional(
             Type7.Boolean({ description: "Extract only the main content." })
@@ -3157,51 +3342,133 @@ var firecrawlSearchOptionsSchema = Type7.Object(
   },
   { description: "Firecrawl search options." }
 );
+var firecrawlSearchPromptGuidelines = [
+  "Use Firecrawl search when the task benefits from searchable results that can also include scraped page content through scrapeOptions.",
+  "Set scrapeOptions.formats=['markdown'] and onlyMainContent=true when source snippets are not enough and the user needs extracted page context in the search results.",
+  "Use includeDomains/excludeDomains when search should stay within or avoid specific sites.",
+  "Use lang, country, or location when the user asks for language-specific, country-specific, or local results.",
+  "Prefer web_contents with Firecrawl scrape options after search when only a small set of known URLs needs full extraction."
+];
+var firecrawlScrapeTuningProperties = {
+  onlyMainContent: Type7.Optional(
+    Type7.Boolean({ description: "Extract only the main content." })
+  ),
+  includeTags: Type7.Optional(
+    Type7.Array(Type7.String(), { description: "CSS selectors to include." })
+  ),
+  excludeTags: Type7.Optional(
+    Type7.Array(Type7.String(), { description: "CSS selectors to exclude." })
+  ),
+  waitFor: Type7.Optional(
+    Type7.Integer({
+      minimum: 0,
+      description: "Milliseconds to wait before scraping."
+    })
+  ),
+  headers: Type7.Optional(
+    Type7.Record(Type7.String(), Type7.String(), {
+      description: "Headers to send when scraping."
+    })
+  ),
+  location: Type7.Optional(
+    Type7.Object(
+      {
+        country: Type7.Optional(Type7.String({ description: "Country hint." })),
+        region: Type7.Optional(Type7.String({ description: "Region hint." })),
+        city: Type7.Optional(Type7.String({ description: "City hint." }))
+      },
+      { description: "Location hint for scraping." }
+    )
+  ),
+  mobile: Type7.Optional(
+    Type7.Boolean({ description: "Use a mobile browser profile." })
+  ),
+  proxy: Type7.Optional(
+    Type7.String({
+      description: "Proxy mode passed through to the Firecrawl SDK."
+    })
+  ),
+  fastMode: Type7.Optional(
+    Type7.Boolean({ description: "Use Firecrawl fast mode." })
+  ),
+  blockAds: Type7.Optional(
+    Type7.Boolean({ description: "Block ads while scraping." })
+  ),
+  removeBase64Images: Type7.Optional(
+    Type7.Boolean({
+      description: "Remove base64 image data from scraped output."
+    })
+  ),
+  redactPII: Type7.Optional(
+    Type7.Union(
+      [
+        Type7.Boolean(),
+        Type7.Object(
+          {
+            entities: Type7.Optional(
+              Type7.Array(
+                literalUnion([
+                  "PERSON",
+                  "EMAIL",
+                  "PHONE",
+                  "LOCATION",
+                  "FINANCIAL",
+                  "SECRET"
+                ])
+              )
+            )
+          },
+          { additionalProperties: false }
+        )
+      ],
+      { description: "Redact personal or sensitive data from output." }
+    )
+  ),
+  maxAge: Type7.Optional(
+    Type7.Number({
+      description: "Maximum age of cached scrape data in milliseconds."
+    })
+  ),
+  minAge: Type7.Optional(
+    Type7.Number({
+      description: "Minimum age of cached scrape data in milliseconds."
+    })
+  ),
+  storeInCache: Type7.Optional(
+    Type7.Boolean({ description: "Store scrape result in Firecrawl cache." })
+  ),
+  skipTlsVerification: Type7.Optional(
+    Type7.Boolean({ description: "Skip TLS certificate verification." })
+  )
+};
 var firecrawlScrapeOptionsSchema = Type7.Object(
   {
     formats: Type7.Optional(
-      Type7.Array(literalUnion(["markdown", "html", "rawHtml"]), {
-        description: "Output formats for scraping."
-      })
-    ),
-    onlyMainContent: Type7.Optional(
-      Type7.Boolean({ description: "Extract only the main content." })
-    ),
-    includeTags: Type7.Optional(
-      Type7.Array(Type7.String(), { description: "CSS selectors to include." })
-    ),
-    excludeTags: Type7.Optional(
-      Type7.Array(Type7.String(), { description: "CSS selectors to exclude." })
+      Type7.Array(
+        literalUnion([
+          "markdown",
+          "html",
+          "rawHtml",
+          "links",
+          "images",
+          "screenshot",
+          "summary",
+          "json",
+          "attributes",
+          "changeTracking"
+        ]),
+        {
+          description: "Output formats for scraping."
+        }
+      )
     ),
-    waitFor: Type7.Optional(
+    timeout: Type7.Optional(
       Type7.Integer({
         minimum: 0,
-        description: "Milliseconds to wait before scraping."
-      })
-    ),
-    headers: Type7.Optional(
-      Type7.Record(Type7.String(), Type7.String(), {
-        description: "Headers to send when scraping."
+        description: "Request timeout in milliseconds."
       })
     ),
-    location: Type7.Optional(
-      Type7.Object(
-        {
-          country: Type7.Optional(Type7.String({ description: "Country hint." })),
-          region: Type7.Optional(Type7.String({ description: "Region hint." })),
-          city: Type7.Optional(Type7.String({ description: "City hint." }))
-        },
-        { description: "Location hint for scraping." }
-      )
-    ),
-    mobile: Type7.Optional(
-      Type7.Boolean({ description: "Use a mobile browser profile." })
-    ),
-    proxy: Type7.Optional(
-      Type7.String({
-        description: "Proxy mode passed through to the Firecrawl SDK."
-      })
-    )
+    ...firecrawlScrapeTuningProperties
   },
   { description: "Firecrawl scrape options." }
 );
@@ -3211,44 +3478,7 @@ var firecrawlAnswerOptionsSchema = Type7.Object(
       minLength: 1,
       description: "URL of the page to ask about."
     }),
-    onlyMainContent: Type7.Optional(
-      Type7.Boolean({ description: "Extract only the main content." })
-    ),
-    includeTags: Type7.Optional(
-      Type7.Array(Type7.String(), { description: "CSS selectors to include." })
-    ),
-    excludeTags: Type7.Optional(
-      Type7.Array(Type7.String(), { description: "CSS selectors to exclude." })
-    ),
-    waitFor: Type7.Optional(
-      Type7.Integer({
-        minimum: 0,
-        description: "Milliseconds to wait before scraping."
-      })
-    ),
-    headers: Type7.Optional(
-      Type7.Record(Type7.String(), Type7.String(), {
-        description: "Headers to send when scraping."
-      })
-    ),
-    location: Type7.Optional(
-      Type7.Object(
-        {
-          country: Type7.Optional(Type7.String({ description: "Country hint." })),
-          region: Type7.Optional(Type7.String({ description: "Region hint." })),
-          city: Type7.Optional(Type7.String({ description: "City hint." }))
-        },
-        { description: "Location hint for scraping." }
-      )
-    ),
-    mobile: Type7.Optional(
-      Type7.Boolean({ description: "Use a mobile browser profile." })
-    ),
-    proxy: Type7.Optional(
-      Type7.String({
-        description: "Proxy mode passed through to Firecrawl."
-      })
-    )
+    ...firecrawlScrapeTuningProperties
   },
   {
     description: "Firecrawl page-question options. The URL is required; the question comes from the web_answer query."
@@ -3531,6 +3761,7 @@ var firecrawlProvider = defineProvider({
   capabilities: {
     search: defineCapability({
       options: firecrawlImplementation.getToolOptionsSchema?.("search"),
+      promptGuidelines: firecrawlSearchPromptGuidelines,
       async execute(input, ctx) {
         const { query: query2, maxResults, options } = input;
         return await firecrawlImplementation.search(
@@ -3653,6 +3884,12 @@ var geminiSearchOptionsSchema = Type8.Object(
   },
   { description: "Gemini search options." }
 );
+var geminiSearchPromptGuidelines = [
+  "Use Gemini search when a grounded model should perform web-backed source discovery and return likely sources.",
+  "Change model only when the user requests a specific Gemini model or when project configuration requires it.",
+  "Tune generation_config only for explicit output-control needs; avoid disabling tool use for search tasks.",
+  "Prefer web_contents after Gemini search when selected sources need direct extraction or closer reading."
+];
 var geminiAnswerOptionsSchema = Type8.Object(
   {
     model: Type8.Optional(
@@ -4341,6 +4578,7 @@ var geminiProvider = defineProvider({
   capabilities: {
     search: defineCapability({
       options: geminiImplementation.getToolOptionsSchema?.("search"),
+      promptGuidelines: geminiSearchPromptGuidelines,
       async execute(input, ctx) {
         const { query: query2, maxResults, options } = input;
         return await geminiImplementation.search(
@@ -4409,6 +4647,12 @@ var linkupSearchOptionsSchema = Type9.Object(
   },
   { description: "Linkup search options." }
 );
+var linkupSearchPromptGuidelines = [
+  "Use Linkup depth='deep' for exploratory or high-recall source discovery, and 'standard' for quick direct searches.",
+  "Use includeDomains or excludeDomains when the user names source constraints or when limiting the search space improves precision.",
+  "Use fromDate and toDate when the user asks for recent, historical, or bounded-by-date results.",
+  "Enable includeImages only when images are directly useful; otherwise keep search focused on textual source discovery."
+];
 var linkupContentsOptionsSchema = Type9.Object(
   {
     renderJs: Type9.Optional(
@@ -4778,6 +5022,7 @@ var linkupProvider = defineProvider({
   capabilities: {
     search: defineCapability({
       options: linkupImplementation.getToolOptionsSchema?.("search"),
+      promptGuidelines: linkupSearchPromptGuidelines,
       async execute(input, ctx) {
         const { query: query2, maxResults, options } = input;
         return await linkupImplementation.search(
@@ -4987,11 +5232,40 @@ function buildFetchMetadata(data) {
 }
 
 // src/providers/openai.ts
-import { Type as Type10 } from "typebox";
 import OpenAI from "openai";
+import { Type as Type10 } from "typebox";
 var DEFAULT_SEARCH_MODEL2 = "gpt-4.1";
 var DEFAULT_ANSWER_MODEL2 = "gpt-4.1";
 var DEFAULT_RESEARCH_MODEL = "o4-mini-deep-research";
+var openaiWebSearchToolProperties = {
+  searchContextSize: Type10.Optional(
+    literalUnion(["low", "medium", "high"], {
+      description: "Amount of context OpenAI web search should retrieve per search."
+    })
+  ),
+  allowedDomains: Type10.Optional(
+    Type10.Array(Type10.String(), {
+      description: "Restrict OpenAI web search to these domains."
+    })
+  ),
+  userLocation: Type10.Optional(
+    Type10.Object(
+      {
+        city: Type10.Optional(Type10.String({ description: "User city hint." })),
+        country: Type10.Optional(
+          Type10.String({ description: "Two-letter user country code." })
+        ),
+        region: Type10.Optional(
+          Type10.String({ description: "User region hint." })
+        ),
+        timezone: Type10.Optional(
+          Type10.String({ description: "IANA timezone hint." })
+        )
+      },
+      { description: "Approximate user location for OpenAI web search." }
+    )
+  )
+};
 var openaiSearchOptionsSchema = Type10.Object(
   {
     model: Type10.Optional(
@@ -5003,10 +5277,19 @@ var openaiSearchOptionsSchema = Type10.Object(
       Type10.String({
         description: "Optional instructions that shape source selection and result style."
       })
-    )
+    ),
+    ...openaiWebSearchToolProperties
   },
   { description: "OpenAI search options." }
 );
+var openaiSearchPromptGuidelines = [
+  "Use OpenAI web search when an LLM-mediated search pass should identify likely sources from the live web.",
+  "Use instructions to constrain source selection, freshness, geography, or output style only when the user explicitly needs that control.",
+  "Use allowedDomains when the user asks to search only specific sites or primary-source domains.",
+  "Use searchContextSize='high' only when the query needs richer source context; use 'low' for quick source discovery.",
+  "Use userLocation for local, regional, or jurisdiction-specific searches.",
+  "Prefer web_contents after OpenAI search when the task requires direct inspection of selected primary sources."
+];
 var openaiAnswerOptionsSchema = Type10.Object(
   {
     model: Type10.Optional(
@@ -5018,7 +5301,8 @@ var openaiAnswerOptionsSchema = Type10.Object(
       Type10.String({
         description: "Optional instructions that shape the answer structure, tone, and source selection."
       })
-    )
+    ),
+    ...openaiWebSearchToolProperties
   },
   { description: "OpenAI answer options." }
 );
@@ -5039,7 +5323,8 @@ var openaiResearchOptionsSchema = Type10.Object(
         minimum: 1,
         description: "Maximum number of built-in tool calls the model may make during the research run."
       })
-    )
+    ),
+    ...openaiWebSearchToolProperties
   },
   { description: "OpenAI deep research options." }
 );
@@ -5200,7 +5485,7 @@ function buildOpenAISearchRequest(query2, maxResults, config, options) {
       "",
       `User query: ${query2}`
     ].join("\n"),
-    tools: [{ type: "web_search_preview" }],
+    tools: [buildOpenAIWebSearchTool(mergedOptions)],
     text: {
       format: {
         type: "json_schema",
@@ -5219,7 +5504,7 @@ function buildOpenAIAnswerRequest(query2, config, options) {
   return {
     model,
     input: query2,
-    tools: [{ type: "web_search_preview" }],
+    tools: [buildOpenAIWebSearchTool(mergedOptions)],
     ...instructions ? { instructions } : {}
   };
 }
@@ -5232,11 +5517,41 @@ function buildOpenAIResearchRequest(input, config, options) {
     model,
     input,
     background: true,
-    tools: [{ type: "web_search_preview" }],
+    tools: [buildOpenAIWebSearchTool(mergedOptions)],
     ...instructions ? { instructions } : {},
     ...maxToolCalls ? { max_tool_calls: maxToolCalls } : {}
   };
 }
+function buildOpenAIWebSearchTool(options) {
+  const tool = { type: "web_search" };
+  if (options.searchContextSize) {
+    tool.search_context_size = options.searchContextSize;
+  }
+  if (options.allowedDomains && options.allowedDomains.length > 0) {
+    tool.filters = { allowed_domains: options.allowedDomains };
+  }
+  if (options.userLocation) {
+    tool.user_location = {
+      type: "approximate",
+      ...options.userLocation
+    };
+  }
+  return tool;
+}
+function resolveOpenAIWebSearchToolOptions(merged) {
+  const searchContextSize = readStringUnion(merged.searchContextSize, [
+    "low",
+    "medium",
+    "high"
+  ]);
+  const allowedDomains = readStringArray(merged.allowedDomains);
+  const userLocation = readUserLocation(merged.userLocation);
+  return {
+    ...searchContextSize ? { searchContextSize } : {},
+    ...allowedDomains ? { allowedDomains } : {},
+    ...userLocation ? { userLocation } : {}
+  };
+}
 function resolveOpenAISearchOptions(config, options) {
   const mergedOptions = {
     ...config.options?.search ?? {},
@@ -5246,7 +5561,8 @@ function resolveOpenAISearchOptions(config, options) {
   const instructions = readNonEmptyString4(mergedOptions.instructions);
   return {
     ...model ? { model } : {},
-    ...instructions ? { instructions } : {}
+    ...instructions ? { instructions } : {},
+    ...resolveOpenAIWebSearchToolOptions(mergedOptions)
   };
 }
 function resolveOpenAIAnswerOptions(config, options) {
@@ -5258,7 +5574,8 @@ function resolveOpenAIAnswerOptions(config, options) {
   const instructions = readNonEmptyString4(mergedOptions.instructions);
   return {
     ...model ? { model } : {},
-    ...instructions ? { instructions } : {}
+    ...instructions ? { instructions } : {},
+    ...resolveOpenAIWebSearchToolOptions(mergedOptions)
   };
 }
 function resolveOpenAIResearchOptions(config, options) {
@@ -5272,7 +5589,8 @@ function resolveOpenAIResearchOptions(config, options) {
   return {
     ...model ? { model } : {},
     ...instructions ? { instructions } : {},
-    ...maxToolCalls ? { max_tool_calls: maxToolCalls } : {}
+    ...maxToolCalls ? { max_tool_calls: maxToolCalls } : {},
+    ...resolveOpenAIWebSearchToolOptions(mergedOptions)
   };
 }
 function buildRequestOptions2(signal, idempotencyKey) {
@@ -5437,6 +5755,35 @@ function formatIncompleteError(response, operation) {
 function readNonEmptyString4(value) {
   return typeof value === "string" && value.trim().length > 0 ? value : void 0;
 }
+function readStringArray(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const strings = value.filter(
+    (item) => typeof item === "string" && item.trim() !== ""
+  );
+  return strings.length > 0 ? strings : void 0;
+}
+function readStringUnion(value, values) {
+  return typeof value === "string" && values.includes(value) ? value : void 0;
+}
+function readUserLocation(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  const location = value;
+  const city = readNonEmptyString4(location.city);
+  const country = readNonEmptyString4(location.country);
+  const region = readNonEmptyString4(location.region);
+  const timezone = readNonEmptyString4(location.timezone);
+  const result = {
+    ...city ? { city } : {},
+    ...country ? { country } : {},
+    ...region ? { region } : {},
+    ...timezone ? { timezone } : {}
+  };
+  return Object.keys(result).length > 0 ? result : void 0;
+}
 function readPositiveInteger2(value) {
   return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : void 0;
 }
@@ -5461,6 +5808,7 @@ var openaiProvider = defineProvider({
   capabilities: {
     search: defineCapability({
       options: openaiImplementation.getToolOptionsSchema?.("search"),
+      promptGuidelines: openaiSearchPromptGuidelines,
       async execute(input, ctx) {
         const { query: query2, maxResults, options } = input;
         return await openaiImplementation.search(
@@ -5503,13 +5851,19 @@ import { Type as Type11 } from "typebox";
 var parallelSearchOptionsSchema = Type11.Object(
   {
     mode: Type11.Optional(
-      literalUnion(["agentic", "one-shot"], {
-        description: "Parallel search mode. Use 'agentic' for exploratory or multi-step source discovery and 'one-shot' for direct, simple searches."
+      literalUnion(["advanced", "basic", "turbo"], {
+        description: "Parallel search mode. Use 'advanced' for higher quality, 'basic' for lower latency, or 'turbo' for the fastest responses."
       })
     )
   },
   { description: "Parallel search options." }
 );
+var parallelSearchPromptGuidelines = [
+  "Use Parallel mode='advanced' for exploratory, ambiguous, or multi-hop source discovery where the provider should plan the search.",
+  "Use Parallel mode='basic' for direct factual lookups and simple source finding where low latency is preferred.",
+  "Use Parallel mode='turbo' only when fastest responses matter more than recall or depth.",
+  "Prefer web_contents with Parallel extraction when a URL set is already known and the task needs full page content rather than more source discovery."
+];
 var parallelExtractOptionsSchema = Type11.Object(
   {
     excerpts: Type11.Optional(
@@ -5542,7 +5896,7 @@ var parallelImplementation = {
       credentials: { api: "PARALLEL_API_KEY" },
       options: {
         search: {
-          mode: "agentic"
+          mode: "advanced"
         },
         extract: {
           excerpts: false,
@@ -5557,13 +5911,11 @@ var parallelImplementation = {
   async search(query2, maxResults, config, context, options) {
     const client = createClient6(config);
     const defaults = asJsonObject(config.options?.search) ?? {};
-    const response = await client.beta.search(
-      {
+    const response = await client.search(
+      buildParallelSearchParams(query2, maxResults, {
         ...defaults,
-        ...options ?? {},
-        objective: query2,
-        max_results: maxResults
-      },
+        ...options ?? {}
+      }),
       buildRequestOptions3(context)
     );
     return {
@@ -5578,12 +5930,11 @@ var parallelImplementation = {
   async contents(urls, config, context, options) {
     const client = createClient6(config);
     const defaults = asJsonObject(config.options?.extract) ?? {};
-    const response = await client.beta.extract(
-      {
+    const response = await client.extract(
+      buildParallelExtractParams(urls, {
         ...defaults,
-        ...options ?? {},
-        urls
-      },
+        ...options ?? {}
+      }),
       buildRequestOptions3(context)
     );
     const resultsByUrl = new Map(
@@ -5615,6 +5966,62 @@ var parallelImplementation = {
     };
   }
 };
+function buildParallelSearchParams(query2, maxResults, options) {
+  const {
+    advanced_settings: advancedSettingsValue,
+    max_results: _legacyMaxResults,
+    mode: modeValue,
+    objective: objectiveValue,
+    search_queries: _searchQueries,
+    ...rest
+  } = options;
+  const advancedSettings = readObjectOption(advancedSettingsValue);
+  const mode = normalizeParallelSearchMode(modeValue);
+  const objective = typeof objectiveValue === "string" && objectiveValue.trim() ? objectiveValue.trim() : query2;
+  return {
+    ...rest,
+    search_queries: [query2],
+    objective,
+    ...mode ? { mode } : {},
+    advanced_settings: {
+      ...advancedSettings,
+      max_results: maxResults
+    }
+  };
+}
+function buildParallelExtractParams(urls, options) {
+  const {
+    advanced_settings: advancedSettingsValue,
+    excerpts: excerptsValue,
+    full_content: fullContentValue,
+    ...rest
+  } = options;
+  const advancedSettings = readObjectOption(advancedSettingsValue);
+  if (typeof fullContentValue === "boolean") {
+    advancedSettings.full_content = fullContentValue;
+  }
+  if (typeof excerptsValue === "boolean" && advancedSettings.excerpt_settings === void 0) {
+    advancedSettings.excerpt_settings = excerptsValue ? {} : { max_chars_per_result: 0 };
+  }
+  return {
+    ...rest,
+    urls,
+    advanced_settings: advancedSettings
+  };
+}
+function normalizeParallelSearchMode(value) {
+  switch (value) {
+    case "advanced":
+    case "basic":
+    case "turbo":
+      return value;
+    default:
+      return void 0;
+  }
+}
+function readObjectOption(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? { ...value } : {};
+}
 function createClient6(config) {
   const apiKey = resolveConfigValue(config.credentials?.api);
   if (!apiKey) {
@@ -5645,6 +6052,7 @@ var parallelProvider = defineProvider({
   capabilities: {
     search: defineCapability({
       options: parallelImplementation.getToolOptionsSchema?.("search"),
+      promptGuidelines: parallelSearchPromptGuidelines,
       async execute(input, ctx) {
         const { query: query2, maxResults, options } = input;
         return await parallelImplementation.search(
@@ -5696,6 +6104,12 @@ var perplexitySearchOptionsSchema = Type12.Object(
   },
   { description: "Perplexity search options." }
 );
+var perplexitySearchPromptGuidelines = [
+  "Use Perplexity search for concise web result retrieval with recency and domain filters, not for synthesized answers.",
+  "Set search_recency_filter when freshness matters, such as breaking news, recently updated documentation, prices, or current events.",
+  "Set search_domain_filter when the user asks for primary sources, official documentation, or domain-scoped retrieval.",
+  "Use web_answer or web_research with Perplexity when the user wants synthesis rather than a list of candidate sources."
+];
 var perplexityAnswerOptionsSchema = Type12.Object(
   {
     model: Type12.Optional(
@@ -5965,6 +6379,7 @@ var perplexityProvider = defineProvider({
   capabilities: {
     search: defineCapability({
       options: perplexityImplementation.getToolOptionsSchema?.("search"),
+      promptGuidelines: perplexitySearchPromptGuidelines,
       async execute(input, ctx) {
         const { query: query2, maxResults, options } = input;
         return await perplexityImplementation.search(
@@ -6693,6 +7108,12 @@ var tavilySearchOptionsSchema = Type14.Object(
   },
   { description: "Tavily search options." }
 );
+var tavilySearchPromptGuidelines = [
+  "Use Tavily topic='news' for recent journalism or current events and topic='finance' for market or company-finance research; otherwise leave topic as general.",
+  "Use searchDepth='advanced' for broader or higher-recall source discovery, and 'basic' for quick direct lookups.",
+  "Set timeRange, days, or country when the user asks for freshness, recency, or geography-specific results.",
+  "Set includeRawContent or includeAnswer only when the search response itself should carry more context; prefer web_contents for selected source inspection."
+];
 var tavilyExtractOptionsSchema = Type14.Object(
   {
     extractDepth: Type14.Optional(
@@ -6854,6 +7275,7 @@ var tavilyProvider = defineProvider({
   capabilities: {
     search: defineCapability({
       options: tavilyImplementation.getToolOptionsSchema?.("search"),
+      promptGuidelines: tavilySearchPromptGuidelines,
       async execute(input, ctx) {
         const { query: query2, maxResults, options } = input;
         return await tavilyImplementation.search(
@@ -6896,32 +7318,230 @@ var valyuSearchOptionsSchema = Type15.Object(
     ),
     countryCode: Type15.Optional(
       Type15.String({ description: "Country code to scope search results." })
+    ),
+    maxPrice: Type15.Optional(
+      Type15.Number({
+        minimum: 0,
+        description: "Maximum price per thousand characters (CPM)."
+      })
+    ),
+    relevanceThreshold: Type15.Optional(
+      Type15.Number({
+        minimum: 0,
+        maximum: 1,
+        description: "Minimum result relevance score."
+      })
+    ),
+    includedSources: Type15.Optional(
+      Type15.Array(Type15.String(), {
+        description: "Restrict retrieval to these Valyu sources."
+      })
+    ),
+    excludeSources: Type15.Optional(
+      Type15.Array(Type15.String(), {
+        description: "Exclude these Valyu sources."
+      })
+    ),
+    sourceBiases: Type15.Optional(
+      Type15.Record(Type15.String(), Type15.Number(), {
+        description: "Per-source relevance bias weights."
+      })
+    ),
+    category: Type15.Optional(
+      Type15.String({ description: "Valyu source category to search." })
+    ),
+    startDate: Type15.Optional(
+      Type15.String({ description: "ISO date string for earliest result date." })
+    ),
+    endDate: Type15.Optional(
+      Type15.String({ description: "ISO date string for latest result date." })
+    ),
+    historicalCache: Type15.Optional(
+      Type15.Boolean({
+        description: "Allow Valyu historical cache usage when supported."
+      })
+    ),
+    fastMode: Type15.Optional(
+      Type15.Boolean({
+        description: "Use Valyu fast mode when lower latency is preferred."
+      })
+    ),
+    urlOnly: Type15.Optional(
+      Type15.Boolean({
+        description: "Return URL-focused results with less content."
+      })
+    ),
+    instructions: Type15.Optional(
+      Type15.String({
+        description: "Provider instructions for retrieval and result selection."
+      })
     )
   },
   { description: "Valyu search options." }
 );
-var valyuAnswerOptionsSchema = Type15.Object(
+var valyuSearchPromptGuidelines = [
+  "Use Valyu searchType='news' for recent journalism or current events, 'web' for public web results, and 'proprietary' when proprietary Valyu sources are required.",
+  "Use includedSources, excludeSources, category, or source biases from configuration when the user asks for source-specific retrieval.",
+  "Use startDate/endDate and countryCode when the task requires temporal or geographic scoping.",
+  "Set responseLength higher only when search results need richer inline context; otherwise prefer concise results and follow up with web_contents."
+];
+var valyuContentsOptionsSchema = Type15.Object(
   {
+    summary: Type15.Optional(
+      Type15.Union(
+        [Type15.Boolean(), Type15.String(), Type15.Record(Type15.String(), Type15.Any())],
+        {
+          description: "Whether to include a summary, or instructions for the summary."
+        }
+      )
+    ),
+    extractEffort: Type15.Optional(
+      literalUnion(["normal", "high", "auto"], {
+        description: "Extraction effort. Use 'high' for difficult pages and 'normal' for faster extraction."
+      })
+    ),
     responseLength: Type15.Optional(
-      literalUnion(["short", "medium", "large", "max"], {
-        description: "Response length for answers."
+      Type15.Union(
+        [
+          literalUnion(["short", "medium", "large", "max"]),
+          Type15.Number({ minimum: 0 })
+        ],
+        {
+          description: "Content response length."
+        }
+      )
+    ),
+    maxPriceDollars: Type15.Optional(
+      Type15.Number({
+        minimum: 0,
+        description: "Maximum extraction cost in USD."
+      })
+    ),
+    screenshot: Type15.Optional(
+      Type15.Boolean({
+        description: "Include screenshot capture when supported."
+      })
+    ),
+    startDate: Type15.Optional(
+      Type15.String({
+        description: "ISO date string for earliest content date."
+      })
+    ),
+    endDate: Type15.Optional(
+      Type15.String({ description: "ISO date string for latest content date." })
+    ),
+    historicalCache: Type15.Optional(
+      Type15.Boolean({
+        description: "Allow Valyu historical cache usage when supported."
+      })
+    )
+  },
+  { description: "Valyu contents options." }
+);
+var valyuAnswerOptionsSchema = Type15.Object(
+  {
+    structuredOutput: Type15.Optional(
+      Type15.Record(Type15.String(), Type15.Any(), {
+        description: "JSON schema-like structured output specification."
+      })
+    ),
+    systemInstructions: Type15.Optional(
+      Type15.String({
+        description: "System instructions that guide Valyu answer generation."
+      })
+    ),
+    searchType: Type15.Optional(
+      literalUnion(["all", "web", "proprietary", "news"], {
+        description: "Valyu search type for answer grounding."
+      })
+    ),
+    dataMaxPrice: Type15.Optional(
+      Type15.Number({
+        minimum: 0,
+        description: "Maximum data retrieval price for answer grounding."
       })
     ),
     countryCode: Type15.Optional(
       Type15.String({ description: "Country code to scope answer results." })
+    ),
+    includedSources: Type15.Optional(
+      Type15.Array(Type15.String(), {
+        description: "Restrict answer grounding to these Valyu sources."
+      })
+    ),
+    excludedSources: Type15.Optional(
+      Type15.Array(Type15.String(), {
+        description: "Exclude these Valyu sources from answer grounding."
+      })
+    ),
+    startDate: Type15.Optional(
+      Type15.String({ description: "ISO date string for earliest source date." })
+    ),
+    endDate: Type15.Optional(
+      Type15.String({ description: "ISO date string for latest source date." })
+    ),
+    fastMode: Type15.Optional(
+      Type15.Boolean({
+        description: "Use Valyu fast mode when lower latency is preferred."
+      })
     )
   },
   { description: "Valyu answer options." }
 );
 var valyuResearchOptionsSchema = Type15.Object(
   {
-    responseLength: Type15.Optional(
-      literalUnion(["short", "medium", "large", "max"], {
-        description: "Response length for research."
+    mode: Type15.Optional(
+      literalUnion(["fast", "standard", "lite", "heavy", "max"], {
+        description: "Valyu deep research mode."
       })
     ),
-    countryCode: Type15.Optional(
-      Type15.String({ description: "Country code to scope research results." })
+    outputFormats: Type15.Optional(
+      Type15.Array(
+        Type15.Union([
+          literalUnion(["markdown", "pdf", "toon"]),
+          Type15.Record(Type15.String(), Type15.Any())
+        ]),
+        { description: "Requested Valyu research output formats." }
+      )
+    ),
+    search: Type15.Optional(
+      Type15.Object(
+        {
+          searchType: Type15.Optional(
+            literalUnion(["all", "web", "proprietary"], {
+              description: "Valyu source pool for research."
+            })
+          ),
+          includedSources: Type15.Optional(Type15.Array(Type15.String())),
+          excludedSources: Type15.Optional(Type15.Array(Type15.String())),
+          sourceBiases: Type15.Optional(
+            Type15.Record(Type15.String(), Type15.Number())
+          ),
+          startDate: Type15.Optional(Type15.String()),
+          endDate: Type15.Optional(Type15.String()),
+          historicalCache: Type15.Optional(Type15.Boolean()),
+          category: Type15.Optional(Type15.String()),
+          countryCode: Type15.Optional(Type15.String())
+        },
+        {
+          additionalProperties: false,
+          description: "Valyu deep research search configuration."
+        }
+      )
+    ),
+    tools: Type15.Optional(
+      Type15.Object(
+        {
+          code_execution: Type15.Optional(boolOrConfig()),
+          screenshots: Type15.Optional(boolOrConfig()),
+          browser_use: Type15.Optional(boolOrConfig()),
+          charts: Type15.Optional(boolOrConfig())
+        },
+        {
+          additionalProperties: false,
+          description: "Valyu deep research tool configuration."
+        }
+      )
     )
   },
   { description: "Valyu research options." }
@@ -6934,6 +7554,8 @@ var valyuImplementation = {
     switch (capability) {
       case "search":
         return valyuSearchOptionsSchema;
+      case "contents":
+        return valyuContentsOptionsSchema;
       case "answer":
         return valyuAnswerOptionsSchema;
       case "research":
@@ -6981,7 +7603,10 @@ var valyuImplementation = {
   },
   async contents(urls, config, _context, options) {
     const client = createClient9(config);
-    const response = await client.contents(urls, options);
+    const response = await client.contents(urls, {
+      ...asJsonObject(config.options?.contents) ?? {},
+      ...options ?? {}
+    });
     const finalResponse = "jobId" in response ? await client.waitForJob(response.jobId, {}) : response;
     if (!finalResponse.success) {
       throw new Error(finalResponse.error || "contents failed");
@@ -7127,7 +7752,7 @@ var valyuProvider = defineProvider({
   config: {
     createTemplate: () => valyuImplementation.createTemplate(),
     fields: ["credentials", "baseUrl", "options", "settings"],
-    optionCapabilities: ["search", "answer", "research"]
+    optionCapabilities: ["search", "contents", "answer", "research"]
   },
   getCapabilityStatus: (config, cwd, tool, options) => valyuImplementation.getCapabilityStatus(
     config,
@@ -7138,6 +7763,7 @@ var valyuProvider = defineProvider({
   capabilities: {
     search: defineCapability({
       options: valyuImplementation.getToolOptionsSchema?.("search"),
+      promptGuidelines: valyuSearchPromptGuidelines,
       async execute(input, ctx) {
         const { query: query2, maxResults, options } = input;
         return await valyuImplementation.search(
@@ -9062,9 +9688,9 @@ var PROVIDER_SETTINGS = {
           "hybrid",
           "fast",
           "instant",
+          "deep-lite",
           "deep",
-          "deep-reasoning",
-          "deep-max"
+          "deep-reasoning"
         ],
         getValue: (config) => readString5(getExaSearchOptions(config)?.type) ?? "default",
         setValue: (config, value) => {
@@ -9292,7 +9918,7 @@ var PROVIDER_SETTINGS = {
         id: "parallelSearchMode",
         label: "Search mode",
         help: "Parallel search mode. 'default' uses the SDK default.",
-        values: ["default", "agentic", "one-shot"],
+        values: ["default", "advanced", "basic", "turbo"],
         getValue: (config) => readString5(getParallelOptions(config)?.search?.mode) ?? "default",
         setValue: (config, value) => {
           const options = ensureParallelOptions(config);
@@ -9386,27 +10012,19 @@ var PROVIDER_SETTINGS = {
         }
       }),
       valuesSetting({
-        id: "valyuAnswerResponseLength",
-        label: "Answer response length",
-        help: "Valyu answer response length. 'default' uses the SDK default.",
-        values: ["default", "short", "medium", "large", "max"],
-        getValue: (config) => readString5(
-          getValyuCapabilityOptions(config, "answer")?.responseLength
-        ) ?? "default",
-        setValue: (config, value) => {
-          setValyuResponseLength(config, "answer", value);
-        }
-      }),
-      valuesSetting({
-        id: "valyuResearchResponseLength",
-        label: "Research response length",
-        help: "Valyu research response length. 'default' uses the SDK default.",
-        values: ["default", "short", "medium", "large", "max"],
-        getValue: (config) => readString5(
-          getValyuCapabilityOptions(config, "research")?.responseLength
-        ) ?? "default",
+        id: "valyuResearchMode",
+        label: "Research mode",
+        help: "Valyu research mode. 'default' uses the SDK default.",
+        values: ["default", "fast", "standard", "lite", "heavy", "max"],
+        getValue: (config) => readString5(getValyuCapabilityOptions(config, "research")?.mode) ?? "default",
         setValue: (config, value) => {
-          setValyuResponseLength(config, "research", value);
+          const options = ensureValyuCapabilityOptions(config, "research");
+          if (value === "default") {
+            delete options.mode;
+          } else {
+            options.mode = value;
+          }
+          cleanupCapabilityOptions(config, ["search", "answer", "research"]);
         }
       })
     ]