@librechat/agents 3.3.4 → 3.3.5

package/dist/esm/tools/search/keenable-scraper.mjs

@@ -0,0 +1,88 @@
+import { createDefaultLogger } from "./utils.mjs";
+import axios from "axios";
+//#region src/tools/search/keenable-scraper.ts
+const DEFAULT_KEENABLE_SCRAPE_TIMEOUT = 15e3;
+/** Keyed and keyless fetch endpoints. Keenable reads any URL as clean markdown
+* without a key via the public endpoint; a key only lifts rate limits. */
+const KEENABLE_FETCH_API_URL = "https://api.keenable.ai/v1/fetch";
+const KEENABLE_FETCH_PUBLIC_URL = "https://api.keenable.ai/v1/fetch/public";
+var KeenableScraper = class {
+	apiKey;
+	apiUrl;
+	timeout;
+	attributionTitle;
+	logger;
+	constructor(config = {}) {
+		const resolvedKey = config.apiKey ?? process.env.KEENABLE_API_KEY;
+		this.apiKey = resolvedKey != null && resolvedKey !== "" ? resolvedKey : void 0;
+		this.apiUrl = config.apiUrl ?? process.env.KEENABLE_FETCH_URL ?? (this.apiKey != null ? KEENABLE_FETCH_API_URL : KEENABLE_FETCH_PUBLIC_URL);
+		this.timeout = config.timeout ?? DEFAULT_KEENABLE_SCRAPE_TIMEOUT;
+		this.attributionTitle = config.attributionTitle ?? "LibreChat";
+		this.logger = config.logger || createDefaultLogger();
+	}
+	buildHeaders() {
+		/** X-Keenable-Title is used for traffic attribution and required on the
+		* keyless endpoint; the key only lifts rate limits, so it is sent only when
+		* present. */
+		const headers = { "X-Keenable-Title": this.attributionTitle };
+		if (this.apiKey != null) headers["X-API-Key"] = this.apiKey;
+		return headers;
+	}
+	async scrapeUrl(url, options = {}) {
+		if (!url || !url.trim()) return [url, {
+			success: false,
+			error: "URL cannot be empty"
+		}];
+		try {
+			const data = (await axios.get(this.apiUrl, {
+				params: { url },
+				headers: this.buildHeaders(),
+				timeout: options.timeout ?? this.timeout
+			})).data;
+			const content = data.content ?? "";
+			if (!content) return [url, {
+				success: false,
+				error: "Keenable Fetch returned no content"
+			}];
+			return [url, {
+				success: true,
+				data: {
+					content,
+					title: data.title,
+					description: data.description,
+					url: data.url ?? url
+				}
+			}];
+		} catch (error) {
+			return [url, {
+				success: false,
+				error: `Keenable Fetch API request failed: ${error instanceof Error ? error.message : String(error)}`
+			}];
+		}
+	}
+	async scrapeUrls(urls, options = {}) {
+		/** Keenable fetch is single-URL; run the batch concurrently. */
+		return Promise.all(urls.map((url) => this.scrapeUrl(url, options)));
+	}
+	extractContent(response) {
+		if (!response.success || !response.data) return ["", void 0];
+		/** Keenable returns clean markdown with no separate media arrays, so there
+		* are no structured references to surface. */
+		return [response.data.content, void 0];
+	}
+	extractMetadata(response) {
+		if (!response.success || !response.data) return {};
+		const metadata = {};
+		if (response.data.title != null) metadata.title = response.data.title;
+		if (response.data.description != null && response.data.description !== "") metadata.description = response.data.description;
+		if (response.data.url != null) metadata.url = response.data.url;
+		return metadata;
+	}
+};
+const createKeenableScraper = (config = {}) => {
+	return new KeenableScraper(config);
+};
+//#endregion
+export { createKeenableScraper };
+
+//# sourceMappingURL=keenable-scraper.mjs.map

package/dist/esm/tools/search/keenable-scraper.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"keenable-scraper.mjs","names":[],"sources":["../../../../src/tools/search/keenable-scraper.ts"],"sourcesContent":["import axios from 'axios';\nimport type * as t from './types';\nimport { createDefaultLogger } from './utils';\n\nconst DEFAULT_KEENABLE_SCRAPE_TIMEOUT = 15000;\n\n/** Keyed and keyless fetch endpoints. Keenable reads any URL as clean markdown\n * without a key via the public endpoint; a key only lifts rate limits. */\nconst KEENABLE_FETCH_API_URL = 'https://api.keenable.ai/v1/fetch';\nconst KEENABLE_FETCH_PUBLIC_URL = 'https://api.keenable.ai/v1/fetch/public';\n\nexport class KeenableScraper implements t.BaseScraper {\n  private apiKey: string | undefined;\n  private apiUrl: string;\n  private timeout: number;\n  private attributionTitle: string;\n  private logger: t.Logger;\n\n  constructor(config: t.KeenableScraperConfig = {}) {\n    const resolvedKey = config.apiKey ?? process.env.KEENABLE_API_KEY;\n    this.apiKey =\n      resolvedKey != null && resolvedKey !== '' ? resolvedKey : undefined;\n    this.apiUrl =\n      config.apiUrl ??\n      process.env.KEENABLE_FETCH_URL ??\n      (this.apiKey != null\n        ? KEENABLE_FETCH_API_URL\n        : KEENABLE_FETCH_PUBLIC_URL);\n    this.timeout = config.timeout ?? DEFAULT_KEENABLE_SCRAPE_TIMEOUT;\n    this.attributionTitle = config.attributionTitle ?? 'LibreChat';\n    this.logger = config.logger || createDefaultLogger();\n  }\n\n  private buildHeaders(): Record<string, string> {\n    /** X-Keenable-Title is used for traffic attribution and required on the\n     * keyless endpoint; the key only lifts rate limits, so it is sent only when\n     * present. */\n    const headers: Record<string, string> = {\n      'X-Keenable-Title': this.attributionTitle,\n    };\n    if (this.apiKey != null) {\n      headers['X-API-Key'] = this.apiKey;\n    }\n    return headers;\n  }\n\n  async scrapeUrl(\n    url: string,\n    options: t.KeenableScrapeOptions = {}\n  ): Promise<[string, t.KeenableScrapeResponse]> {\n    if (!url || !url.trim()) {\n      return [url, { success: false, error: 'URL cannot be empty' }];\n    }\n\n    try {\n      const response = await axios.get<t.KeenableFetchResult>(this.apiUrl, {\n        params: { url },\n        headers: this.buildHeaders(),\n        timeout: options.timeout ?? this.timeout,\n      });\n\n      const data = response.data;\n      const content = data.content ?? '';\n      if (!content) {\n        return [\n          url,\n          { success: false, error: 'Keenable Fetch returned no content' },\n        ];\n      }\n\n      return [\n        url,\n        {\n          success: true,\n          data: {\n            content,\n            title: data.title,\n            description: data.description,\n            url: data.url ?? url,\n          },\n        },\n      ];\n    } catch (error) {\n      const errorMessage =\n        error instanceof Error ? error.message : String(error);\n      return [\n        url,\n        {\n          success: false,\n          error: `Keenable Fetch API request failed: ${errorMessage}`,\n        },\n      ];\n    }\n  }\n\n  async scrapeUrls(\n    urls: string[],\n    options: t.KeenableScrapeOptions = {}\n  ): Promise<Array<[string, t.KeenableScrapeResponse]>> {\n    /** Keenable fetch is single-URL; run the batch concurrently. */\n    return Promise.all(urls.map((url) => this.scrapeUrl(url, options)));\n  }\n\n  extractContent(\n    response: t.KeenableScrapeResponse\n  ): [string, undefined | t.References] {\n    if (!response.success || !response.data) {\n      return ['', undefined];\n    }\n    /** Keenable returns clean markdown with no separate media arrays, so there\n     * are no structured references to surface. */\n    return [response.data.content, undefined];\n  }\n\n  extractMetadata(response: t.KeenableScrapeResponse): t.GenericScrapeMetadata {\n    if (!response.success || !response.data) {\n      return {};\n    }\n    const metadata: t.GenericScrapeMetadata = {};\n    if (response.data.title != null) {\n      metadata.title = response.data.title;\n    }\n    if (response.data.description != null && response.data.description !== '') {\n      metadata.description = response.data.description;\n    }\n    if (response.data.url != null) {\n      metadata.url = response.data.url;\n    }\n    return metadata;\n  }\n}\n\nexport const createKeenableScraper = (\n  config: t.KeenableScraperConfig = {}\n): KeenableScraper => {\n  return new KeenableScraper(config);\n};\n"],"mappings":";;;AAIA,MAAM,kCAAkC;;;AAIxC,MAAM,yBAAyB;AAC/B,MAAM,4BAA4B;AAElC,IAAa,kBAAb,MAAsD;CACpD;CACA;CACA;CACA;CACA;CAEA,YAAY,SAAkC,CAAC,GAAG;EAChD,MAAM,cAAc,OAAO,UAAU,QAAQ,IAAI;EACjD,KAAK,SACH,eAAe,QAAQ,gBAAgB,KAAK,cAAc,KAAA;EAC5D,KAAK,SACH,OAAO,UACP,QAAQ,IAAI,uBACX,KAAK,UAAU,OACZ,yBACA;EACN,KAAK,UAAU,OAAO,WAAW;EACjC,KAAK,mBAAmB,OAAO,oBAAoB;EACnD,KAAK,SAAS,OAAO,UAAU,oBAAoB;CACrD;CAEA,eAA+C;;;;EAI7C,MAAM,UAAkC,EACtC,oBAAoB,KAAK,iBAC3B;EACA,IAAI,KAAK,UAAU,MACjB,QAAQ,eAAe,KAAK;EAE9B,OAAO;CACT;CAEA,MAAM,UACJ,KACA,UAAmC,CAAC,GACS;EAC7C,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,GACpB,OAAO,CAAC,KAAK;GAAE,SAAS;GAAO,OAAO;EAAsB,CAAC;EAG/D,IAAI;GAOF,MAAM,QAAO,MANU,MAAM,IAA2B,KAAK,QAAQ;IACnE,QAAQ,EAAE,IAAI;IACd,SAAS,KAAK,aAAa;IAC3B,SAAS,QAAQ,WAAW,KAAK;GACnC,CAAC,EAAA,CAEqB;GACtB,MAAM,UAAU,KAAK,WAAW;GAChC,IAAI,CAAC,SACH,OAAO,CACL,KACA;IAAE,SAAS;IAAO,OAAO;GAAqC,CAChE;GAGF,OAAO,CACL,KACA;IACE,SAAS;IACT,MAAM;KACJ;KACA,OAAO,KAAK;KACZ,aAAa,KAAK;KAClB,KAAK,KAAK,OAAO;IACnB;GACF,CACF;EACF,SAAS,OAAO;GAGd,OAAO,CACL,KACA;IACE,SAAS;IACT,OAAO,sCALT,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;GAMrD,CACF;EACF;CACF;CAEA,MAAM,WACJ,MACA,UAAmC,CAAC,GACgB;;EAEpD,OAAO,QAAQ,IAAI,KAAK,KAAK,QAAQ,KAAK,UAAU,KAAK,OAAO,CAAC,CAAC;CACpE;CAEA,eACE,UACoC;EACpC,IAAI,CAAC,SAAS,WAAW,CAAC,SAAS,MACjC,OAAO,CAAC,IAAI,KAAA,CAAS;;;EAIvB,OAAO,CAAC,SAAS,KAAK,SAAS,KAAA,CAAS;CAC1C;CAEA,gBAAgB,UAA6D;EAC3E,IAAI,CAAC,SAAS,WAAW,CAAC,SAAS,MACjC,OAAO,CAAC;EAEV,MAAM,WAAoC,CAAC;EAC3C,IAAI,SAAS,KAAK,SAAS,MACzB,SAAS,QAAQ,SAAS,KAAK;EAEjC,IAAI,SAAS,KAAK,eAAe,QAAQ,SAAS,KAAK,gBAAgB,IACrE,SAAS,cAAc,SAAS,KAAK;EAEvC,IAAI,SAAS,KAAK,OAAO,MACvB,SAAS,MAAM,SAAS,KAAK;EAE/B,OAAO;CACT;AACF;AAEA,MAAa,yBACX,SAAkC,CAAC,MACf;CACpB,OAAO,IAAI,gBAAgB,MAAM;AACnC"}

package/dist/esm/tools/search/tool.mjs

@@ -4,6 +4,7 @@ import { createDefaultLogger } from "./utils.mjs";
 import { formatResultsForLLM } from "./format.mjs";
 import { WebSearchToolDescription, WebSearchToolName, countrySchema, dateSchema, imagesSchema, newsSchema, querySchema, videosSchema } from "./schema.mjs";
 import { createSearchAPI, createSourceProcessor } from "./search.mjs";
+import { createKeenableScraper } from "./keenable-scraper.mjs";
 import { createSerperScraper } from "./serper-scraper.mjs";
 import { createTavilyScraper } from "./tavily-scraper.mjs";
 import { createFirecrawlScraper } from "./firecrawl.mjs";
@@ -181,7 +182,7 @@ function createTool({ schema, search, maxOutputChars, onSearchResults: _onSearch
 	});
 }
 const createSearchTool = (config = {}) => {
-	const { searchProvider = "serper", serperApiKey, searxngInstanceUrl, searxngApiKey, tavilyApiKey, tavilySearchUrl, tavilyExtractUrl, tavilySearchOptions, keenableApiKey, keenableApiUrl, keenableSearchOptions, rerankerType = "cohere", rerankerTimeout, topResults = 5, maxContentLength, chunkSize, chunkOverlap, mainExpandBy, separatorExpandBy, maxOutputChars, strategies = ["no_extraction"], filterContent = true, safeSearch = 1, scraperProvider = "firecrawl", firecrawlApiKey, firecrawlApiUrl, firecrawlVersion, firecrawlOptions, serperScraperOptions, tavilyScraperOptions, crwApiKey, crwApiUrl, crwSearchOptions, crwScraperOptions, scraperTimeout, jinaApiKey, jinaApiUrl, cohereApiKey, onSearchResults: _onSearchResults, onGetHighlights } = config;
+	const { searchProvider = "serper", serperApiKey, searxngInstanceUrl, searxngApiKey, tavilyApiKey, tavilySearchUrl, tavilyExtractUrl, tavilySearchOptions, keenableApiKey, keenableApiUrl, keenableSearchOptions, keenableScraperOptions, rerankerType = "cohere", rerankerTimeout, topResults = 5, maxContentLength, chunkSize, chunkOverlap, mainExpandBy, separatorExpandBy, maxOutputChars, strategies = ["no_extraction"], filterContent = true, safeSearch = 1, scraperProvider = "firecrawl", firecrawlApiKey, firecrawlApiUrl, firecrawlVersion, firecrawlOptions, serperScraperOptions, tavilyScraperOptions, crwApiKey, crwApiUrl, crwSearchOptions, crwScraperOptions, scraperTimeout, jinaApiKey, jinaApiUrl, cohereApiKey, onSearchResults: _onSearchResults, onGetHighlights } = config;
 	const logger = config.logger || createDefaultLogger();
 	const effectiveTavilySearchOptions = searchProvider === "tavily" && config.safeSearch != null ? {
 		...tavilySearchOptions,
@@ -238,6 +239,13 @@ const createSearchTool = (config = {}) => {
 		formats: crwScraperOptions?.formats ?? ["markdown", "rawHtml"],
 		logger
 	});
+	else if (scraperProvider === "keenable") scraperInstance = createKeenableScraper({
+		...keenableScraperOptions,
+		apiKey: keenableScraperOptions?.apiKey ?? keenableApiKey,
+		timeout: scraperTimeout ?? keenableScraperOptions?.timeout,
+		attributionTitle: keenableScraperOptions?.attributionTitle ?? keenableSearchOptions?.attributionTitle,
+		logger
+	});
 	else scraperInstance = createFirecrawlScraper({
 		...firecrawlOptions,
 		apiKey: firecrawlApiKey ?? process.env.FIRECRAWL_API_KEY,

package/dist/esm/tools/search/tool.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"tool.mjs","names":["params"],"sources":["../../../../src/tools/search/tool.ts"],"sourcesContent":["import { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport type { RunnableConfig } from '@langchain/core/runnables';\nimport type * as t from './types';\nimport {\n  WebSearchToolDescription,\n  WebSearchToolName,\n  countrySchema,\n  imagesSchema,\n  videosSchema,\n  querySchema,\n  dateSchema,\n  newsSchema,\n  DATE_RANGE,\n} from './schema';\nimport { createSearchAPI, createSourceProcessor } from './search';\nimport { createSerperScraper } from './serper-scraper';\nimport { createTavilyScraper } from './tavily-scraper';\nimport { createFirecrawlScraper } from './firecrawl';\nimport { createCrwScraper } from './crw-scraper';\nimport { expandHighlights } from './highlights';\nimport { formatResultsForLLM } from './format';\nimport { createDefaultLogger } from './utils';\nimport { createReranker } from './rerankers';\nimport { Constants } from '@/common';\n\n/**\n * Executes parallel searches and merges the results,\n * deduplicating top stories by link\n */\nexport async function executeParallelSearches({\n  searchAPI,\n  query,\n  date,\n  country,\n  safeSearch,\n  images,\n  videos,\n  news,\n  logger,\n}: {\n  searchAPI: ReturnType<typeof createSearchAPI>;\n  query: string;\n  date?: DATE_RANGE;\n  country?: string;\n  safeSearch: t.SearchToolConfig['safeSearch'];\n  images: boolean;\n  videos: boolean;\n  news: boolean;\n  logger: t.Logger;\n}): Promise<t.SearchResult> {\n  // Prepare all search tasks to run in parallel\n  const searchTasks: Promise<t.SearchResult>[] = [\n    // Main search\n    searchAPI.getSources({\n      query,\n      date,\n      country,\n      safeSearch,\n    }),\n  ];\n\n  if (images) {\n    searchTasks.push(\n      searchAPI\n        .getSources({\n          query,\n          date,\n          country,\n          safeSearch,\n          type: 'images',\n        })\n        .catch((error) => {\n          logger.error('Error fetching images:', error);\n          return {\n            success: false,\n            error: `Images search failed: ${error instanceof Error ? error.message : String(error)}`,\n          };\n        })\n    );\n  }\n  if (videos) {\n    searchTasks.push(\n      searchAPI\n        .getSources({\n          query,\n          date,\n          country,\n          safeSearch,\n          type: 'videos',\n        })\n        .catch((error) => {\n          logger.error('Error fetching videos:', error);\n          return {\n            success: false,\n            error: `Videos search failed: ${error instanceof Error ? error.message : String(error)}`,\n          };\n        })\n    );\n  }\n  if (news) {\n    searchTasks.push(\n      searchAPI\n        .getSources({\n          query,\n          date,\n          country,\n          safeSearch,\n          type: 'news',\n        })\n        .catch((error) => {\n          logger.error('Error fetching news:', error);\n          return {\n            success: false,\n            error: `News search failed: ${error instanceof Error ? error.message : String(error)}`,\n          };\n        })\n    );\n  }\n\n  // Run all searches in parallel\n  const results = await Promise.all(searchTasks);\n\n  // Get the main search result (first result)\n  const mainResult = results[0];\n  if (!mainResult.success) {\n    throw new Error(mainResult.error ?? 'Search failed');\n  }\n\n  // Merge additional results with the main results\n  const mergedResults = { ...mainResult.data };\n\n  // Convert existing news to topStories if present\n  if (mergedResults.news !== undefined && mergedResults.news.length > 0) {\n    const existingNewsAsTopStories = mergedResults.news\n      .filter((newsItem) => newsItem.link !== undefined && newsItem.link !== '')\n      .map((newsItem) => ({\n        title: newsItem.title ?? '',\n        link: newsItem.link ?? '',\n        source: newsItem.source ?? '',\n        date: newsItem.date ?? '',\n        imageUrl: newsItem.imageUrl ?? '',\n        processed: false,\n      }));\n    mergedResults.topStories = [\n      ...(mergedResults.topStories ?? []),\n      ...existingNewsAsTopStories,\n    ];\n    delete mergedResults.news;\n  }\n\n  results.slice(1).forEach((result) => {\n    if (result.success && result.data !== undefined) {\n      if (result.data.images !== undefined && result.data.images.length > 0) {\n        mergedResults.images = [\n          ...(mergedResults.images ?? []),\n          ...result.data.images,\n        ];\n      }\n      if (result.data.videos !== undefined && result.data.videos.length > 0) {\n        mergedResults.videos = [\n          ...(mergedResults.videos ?? []),\n          ...result.data.videos,\n        ];\n      }\n      if (result.data.news !== undefined && result.data.news.length > 0) {\n        const newsAsTopStories = result.data.news.map((newsItem) => ({\n          ...newsItem,\n          link: newsItem.link ?? '',\n        }));\n        mergedResults.topStories = [\n          ...(mergedResults.topStories ?? []),\n          ...newsAsTopStories,\n        ];\n      }\n    }\n  });\n\n  if (\n    mergedResults.topStories !== undefined &&\n    mergedResults.topStories.length > 1\n  ) {\n    /** The main search's own news results and the parallel news sub-search\n     * frequently return the same stories — keep the first occurrence of each\n     * link so duplicates aren't scraped, reranked, and formatted repeatedly */\n    const seenLinks = new Set<string>();\n    mergedResults.topStories = mergedResults.topStories.filter((story) => {\n      if (!story.link || seenLinks.has(story.link)) {\n        return false;\n      }\n      seenLinks.add(story.link);\n      return true;\n    });\n  }\n\n  return { success: true, data: mergedResults };\n}\n\nfunction createSearchProcessor({\n  searchAPI,\n  safeSearch,\n  supportsImages,\n  supportsVideos,\n  supportsNews,\n  sourceProcessor,\n  onGetHighlights,\n  mainExpandBy,\n  separatorExpandBy,\n  logger,\n}: {\n  safeSearch: t.SearchToolConfig['safeSearch'];\n  supportsImages: boolean;\n  supportsVideos: boolean;\n  supportsNews: boolean;\n  searchAPI: ReturnType<typeof createSearchAPI>;\n  sourceProcessor: ReturnType<typeof createSourceProcessor>;\n  onGetHighlights: t.SearchToolConfig['onGetHighlights'];\n  mainExpandBy: t.SearchToolConfig['mainExpandBy'];\n  separatorExpandBy: t.SearchToolConfig['separatorExpandBy'];\n  logger: t.Logger;\n}) {\n  return async function ({\n    query,\n    date,\n    country,\n    proMode = true,\n    maxSources = 5,\n    onSearchResults,\n    images = false,\n    videos = false,\n    news = false,\n  }: {\n    query: string;\n    country?: string;\n    date?: DATE_RANGE;\n    proMode?: boolean;\n    maxSources?: number;\n    onSearchResults: t.SearchToolConfig['onSearchResults'];\n    images?: boolean;\n    videos?: boolean;\n    news?: boolean;\n  }): Promise<t.SearchResultData> {\n    try {\n      // Execute parallel searches and merge results\n      const searchResult = await executeParallelSearches({\n        searchAPI,\n        query,\n        date,\n        country,\n        safeSearch,\n        images: supportsImages && images,\n        videos: supportsVideos && videos,\n        news: supportsNews && news,\n        logger,\n      });\n\n      onSearchResults?.(searchResult);\n\n      const processedSources = await sourceProcessor.processSources({\n        query,\n        news,\n        result: searchResult,\n        proMode,\n        onGetHighlights,\n        numElements: maxSources,\n      });\n\n      return expandHighlights(\n        processedSources,\n        mainExpandBy,\n        separatorExpandBy\n      );\n    } catch (error) {\n      logger.error('Error in search:', error);\n      return {\n        organic: [],\n        topStories: [],\n        images: [],\n        videos: [],\n        news: [],\n        relatedSearches: [],\n        error: error instanceof Error ? error.message : String(error),\n      };\n    }\n  };\n}\n\nfunction createOnSearchResults({\n  runnableConfig,\n  onSearchResults,\n}: {\n  runnableConfig: RunnableConfig;\n  onSearchResults: t.SearchToolConfig['onSearchResults'];\n}) {\n  return function (results: t.SearchResult): void {\n    if (!onSearchResults) {\n      return;\n    }\n    onSearchResults(results, runnableConfig);\n  };\n}\n\nfunction createTool({\n  schema,\n  search,\n  maxOutputChars,\n  onSearchResults: _onSearchResults,\n}: {\n  schema: Record<string, unknown>;\n  search: ReturnType<typeof createSearchProcessor>;\n  maxOutputChars?: number;\n  onSearchResults: t.SearchToolConfig['onSearchResults'];\n}): DynamicStructuredTool {\n  return tool(\n    async (rawParams, runnableConfig) => {\n      const params = rawParams as SearchToolParams;\n      const { query, date, country: _c, images, videos, news } = params;\n      const country = typeof _c === 'string' && _c ? _c : undefined;\n      const searchResult = await search({\n        query,\n        date,\n        country,\n        images,\n        videos,\n        news,\n        onSearchResults: createOnSearchResults({\n          runnableConfig,\n          onSearchResults: _onSearchResults,\n        }),\n      });\n      const turn = runnableConfig.toolCall?.turn ?? 0;\n      const { output, references } = formatResultsForLLM(\n        turn,\n        searchResult,\n        maxOutputChars\n      );\n      const data: t.SearchResultData = { turn, ...searchResult, references };\n      return [output, { [Constants.WEB_SEARCH]: data }];\n    },\n    {\n      name: WebSearchToolName,\n      description: WebSearchToolDescription,\n      schema: schema,\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n\n/**\n * Creates a search tool with configurable search and scraper providers.\n *\n * Search providers: Serper (Google results), SearXNG (self-hosted meta-search), Tavily (AI-optimized), fastCRW (Firecrawl-compatible, self-host or cloud).\n * Scraper providers: Firecrawl (default, full-featured), Serper (lightweight), Tavily (batch extraction), fastCRW (Firecrawl-compatible, self-host or cloud).\n *\n * The country schema field is exposed to the LLM for providers that support localized results.\n */\n/** Input params type for search tool */\ninterface SearchToolParams {\n  query: string;\n  date?: DATE_RANGE;\n  country?: string;\n  images?: boolean;\n  videos?: boolean;\n  news?: boolean;\n}\n\nexport const createSearchTool = (\n  config: t.SearchToolConfig = {}\n): DynamicStructuredTool => {\n  const {\n    searchProvider = 'serper',\n    serperApiKey,\n    searxngInstanceUrl,\n    searxngApiKey,\n    tavilyApiKey,\n    tavilySearchUrl,\n    tavilyExtractUrl,\n    tavilySearchOptions,\n    keenableApiKey,\n    keenableApiUrl,\n    keenableSearchOptions,\n    rerankerType = 'cohere',\n    rerankerTimeout,\n    topResults = 5,\n    maxContentLength,\n    chunkSize,\n    chunkOverlap,\n    mainExpandBy,\n    separatorExpandBy,\n    maxOutputChars,\n    strategies = ['no_extraction'],\n    filterContent = true,\n    safeSearch = 1,\n    scraperProvider = 'firecrawl',\n    firecrawlApiKey,\n    firecrawlApiUrl,\n    firecrawlVersion,\n    firecrawlOptions,\n    serperScraperOptions,\n    tavilyScraperOptions,\n    crwApiKey,\n    crwApiUrl,\n    crwSearchOptions,\n    crwScraperOptions,\n    scraperTimeout,\n    jinaApiKey,\n    jinaApiUrl,\n    cohereApiKey,\n    onSearchResults: _onSearchResults,\n    onGetHighlights,\n  } = config;\n\n  const logger = config.logger || createDefaultLogger();\n  const effectiveTavilySearchOptions =\n    searchProvider === 'tavily' && config.safeSearch != null\n      ? {\n        ...tavilySearchOptions,\n        safeSearch: config.safeSearch !== 0,\n      }\n      : tavilySearchOptions;\n\n  const schemaProperties: Record<string, unknown> = {\n    query: querySchema,\n    date: dateSchema,\n    images: imagesSchema,\n    videos: videosSchema,\n    news: newsSchema,\n  };\n\n  if (searchProvider === 'serper' || searchProvider === 'tavily') {\n    schemaProperties.country = countrySchema;\n  }\n\n  const toolSchema = {\n    type: 'object',\n    properties: schemaProperties,\n    required: ['query'],\n  };\n\n  const searchAPI = createSearchAPI({\n    searchProvider,\n    serperApiKey,\n    searxngInstanceUrl,\n    searxngApiKey,\n    tavilyApiKey,\n    tavilySearchUrl,\n    tavilySearchOptions: effectiveTavilySearchOptions,\n    keenableApiKey,\n    keenableApiUrl,\n    keenableSearchOptions,\n    crwApiKey,\n    crwApiUrl,\n    crwSearchOptions,\n  });\n\n  /** Create scraper based on scraperProvider */\n  let scraperInstance: t.BaseScraper;\n\n  if (scraperProvider === 'serper') {\n    scraperInstance = createSerperScraper({\n      ...serperScraperOptions,\n      apiKey: serperApiKey,\n      timeout: scraperTimeout ?? serperScraperOptions?.timeout,\n      logger,\n    });\n  } else if (scraperProvider === 'tavily') {\n    scraperInstance = createTavilyScraper({\n      ...tavilyScraperOptions,\n      apiKey:\n        tavilyScraperOptions?.apiKey ??\n        tavilyApiKey ??\n        process.env.TAVILY_API_KEY,\n      apiUrl: tavilyScraperOptions?.apiUrl ?? tavilyExtractUrl,\n      timeout: scraperTimeout ?? tavilyScraperOptions?.timeout,\n      logger,\n    });\n  } else if (scraperProvider === 'crw') {\n    scraperInstance = createCrwScraper({\n      ...crwScraperOptions,\n      apiKey:\n        crwScraperOptions?.apiKey ?? crwApiKey ?? process.env.CRW_API_KEY,\n      apiUrl: crwScraperOptions?.apiUrl ?? crwApiUrl,\n      timeout: scraperTimeout ?? crwScraperOptions?.timeout,\n      formats: crwScraperOptions?.formats ?? ['markdown', 'rawHtml'],\n      logger,\n    });\n  } else {\n    scraperInstance = createFirecrawlScraper({\n      ...firecrawlOptions,\n      apiKey: firecrawlApiKey ?? process.env.FIRECRAWL_API_KEY,\n      apiUrl: firecrawlApiUrl,\n      version: firecrawlVersion,\n      timeout: scraperTimeout ?? firecrawlOptions?.timeout,\n      formats: firecrawlOptions?.formats ?? ['markdown', 'rawHtml'],\n      logger,\n    });\n  }\n\n  const selectedReranker = createReranker({\n    rerankerType,\n    jinaApiKey,\n    jinaApiUrl,\n    cohereApiKey,\n    rerankerTimeout,\n    logger,\n  });\n\n  if (!selectedReranker) {\n    logger.warn('No reranker selected. Using default ranking.');\n  }\n\n  const sourceProcessor = createSourceProcessor(\n    {\n      reranker: selectedReranker,\n      topResults,\n      maxContentLength,\n      chunkSize,\n      chunkOverlap,\n      strategies,\n      filterContent,\n      logger,\n    },\n    scraperInstance\n  );\n\n  const search = createSearchProcessor({\n    searchAPI,\n    safeSearch,\n    // Keenable is organic-only: its API ignores `type`, so image/news\n    // sub-searches would spend rate limit and merge nothing.\n    supportsImages: searchProvider !== 'keenable',\n    supportsVideos:\n      searchProvider !== 'tavily' &&\n      searchProvider !== 'keenable' &&\n      searchProvider !== 'crw',\n    supportsNews: searchProvider !== 'keenable',\n    sourceProcessor,\n    onGetHighlights,\n    mainExpandBy,\n    separatorExpandBy,\n    logger,\n  });\n\n  return createTool({\n    search,\n    schema: toolSchema,\n    maxOutputChars,\n    onSearchResults: _onSearchResults,\n  });\n};\n"],"mappings":"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"}
+{"version":3,"file":"tool.mjs","names":["params"],"sources":["../../../../src/tools/search/tool.ts"],"sourcesContent":["import { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport type { RunnableConfig } from '@langchain/core/runnables';\nimport type * as t from './types';\nimport {\n  WebSearchToolDescription,\n  WebSearchToolName,\n  countrySchema,\n  imagesSchema,\n  videosSchema,\n  querySchema,\n  dateSchema,\n  newsSchema,\n  DATE_RANGE,\n} from './schema';\nimport { createSearchAPI, createSourceProcessor } from './search';\nimport { createKeenableScraper } from './keenable-scraper';\nimport { createSerperScraper } from './serper-scraper';\nimport { createTavilyScraper } from './tavily-scraper';\nimport { createFirecrawlScraper } from './firecrawl';\nimport { createCrwScraper } from './crw-scraper';\nimport { expandHighlights } from './highlights';\nimport { formatResultsForLLM } from './format';\nimport { createDefaultLogger } from './utils';\nimport { createReranker } from './rerankers';\nimport { Constants } from '@/common';\n\n/**\n * Executes parallel searches and merges the results,\n * deduplicating top stories by link\n */\nexport async function executeParallelSearches({\n  searchAPI,\n  query,\n  date,\n  country,\n  safeSearch,\n  images,\n  videos,\n  news,\n  logger,\n}: {\n  searchAPI: ReturnType<typeof createSearchAPI>;\n  query: string;\n  date?: DATE_RANGE;\n  country?: string;\n  safeSearch: t.SearchToolConfig['safeSearch'];\n  images: boolean;\n  videos: boolean;\n  news: boolean;\n  logger: t.Logger;\n}): Promise<t.SearchResult> {\n  // Prepare all search tasks to run in parallel\n  const searchTasks: Promise<t.SearchResult>[] = [\n    // Main search\n    searchAPI.getSources({\n      query,\n      date,\n      country,\n      safeSearch,\n    }),\n  ];\n\n  if (images) {\n    searchTasks.push(\n      searchAPI\n        .getSources({\n          query,\n          date,\n          country,\n          safeSearch,\n          type: 'images',\n        })\n        .catch((error) => {\n          logger.error('Error fetching images:', error);\n          return {\n            success: false,\n            error: `Images search failed: ${error instanceof Error ? error.message : String(error)}`,\n          };\n        })\n    );\n  }\n  if (videos) {\n    searchTasks.push(\n      searchAPI\n        .getSources({\n          query,\n          date,\n          country,\n          safeSearch,\n          type: 'videos',\n        })\n        .catch((error) => {\n          logger.error('Error fetching videos:', error);\n          return {\n            success: false,\n            error: `Videos search failed: ${error instanceof Error ? error.message : String(error)}`,\n          };\n        })\n    );\n  }\n  if (news) {\n    searchTasks.push(\n      searchAPI\n        .getSources({\n          query,\n          date,\n          country,\n          safeSearch,\n          type: 'news',\n        })\n        .catch((error) => {\n          logger.error('Error fetching news:', error);\n          return {\n            success: false,\n            error: `News search failed: ${error instanceof Error ? error.message : String(error)}`,\n          };\n        })\n    );\n  }\n\n  // Run all searches in parallel\n  const results = await Promise.all(searchTasks);\n\n  // Get the main search result (first result)\n  const mainResult = results[0];\n  if (!mainResult.success) {\n    throw new Error(mainResult.error ?? 'Search failed');\n  }\n\n  // Merge additional results with the main results\n  const mergedResults = { ...mainResult.data };\n\n  // Convert existing news to topStories if present\n  if (mergedResults.news !== undefined && mergedResults.news.length > 0) {\n    const existingNewsAsTopStories = mergedResults.news\n      .filter((newsItem) => newsItem.link !== undefined && newsItem.link !== '')\n      .map((newsItem) => ({\n        title: newsItem.title ?? '',\n        link: newsItem.link ?? '',\n        source: newsItem.source ?? '',\n        date: newsItem.date ?? '',\n        imageUrl: newsItem.imageUrl ?? '',\n        processed: false,\n      }));\n    mergedResults.topStories = [\n      ...(mergedResults.topStories ?? []),\n      ...existingNewsAsTopStories,\n    ];\n    delete mergedResults.news;\n  }\n\n  results.slice(1).forEach((result) => {\n    if (result.success && result.data !== undefined) {\n      if (result.data.images !== undefined && result.data.images.length > 0) {\n        mergedResults.images = [\n          ...(mergedResults.images ?? []),\n          ...result.data.images,\n        ];\n      }\n      if (result.data.videos !== undefined && result.data.videos.length > 0) {\n        mergedResults.videos = [\n          ...(mergedResults.videos ?? []),\n          ...result.data.videos,\n        ];\n      }\n      if (result.data.news !== undefined && result.data.news.length > 0) {\n        const newsAsTopStories = result.data.news.map((newsItem) => ({\n          ...newsItem,\n          link: newsItem.link ?? '',\n        }));\n        mergedResults.topStories = [\n          ...(mergedResults.topStories ?? []),\n          ...newsAsTopStories,\n        ];\n      }\n    }\n  });\n\n  if (\n    mergedResults.topStories !== undefined &&\n    mergedResults.topStories.length > 1\n  ) {\n    /** The main search's own news results and the parallel news sub-search\n     * frequently return the same stories — keep the first occurrence of each\n     * link so duplicates aren't scraped, reranked, and formatted repeatedly */\n    const seenLinks = new Set<string>();\n    mergedResults.topStories = mergedResults.topStories.filter((story) => {\n      if (!story.link || seenLinks.has(story.link)) {\n        return false;\n      }\n      seenLinks.add(story.link);\n      return true;\n    });\n  }\n\n  return { success: true, data: mergedResults };\n}\n\nfunction createSearchProcessor({\n  searchAPI,\n  safeSearch,\n  supportsImages,\n  supportsVideos,\n  supportsNews,\n  sourceProcessor,\n  onGetHighlights,\n  mainExpandBy,\n  separatorExpandBy,\n  logger,\n}: {\n  safeSearch: t.SearchToolConfig['safeSearch'];\n  supportsImages: boolean;\n  supportsVideos: boolean;\n  supportsNews: boolean;\n  searchAPI: ReturnType<typeof createSearchAPI>;\n  sourceProcessor: ReturnType<typeof createSourceProcessor>;\n  onGetHighlights: t.SearchToolConfig['onGetHighlights'];\n  mainExpandBy: t.SearchToolConfig['mainExpandBy'];\n  separatorExpandBy: t.SearchToolConfig['separatorExpandBy'];\n  logger: t.Logger;\n}) {\n  return async function ({\n    query,\n    date,\n    country,\n    proMode = true,\n    maxSources = 5,\n    onSearchResults,\n    images = false,\n    videos = false,\n    news = false,\n  }: {\n    query: string;\n    country?: string;\n    date?: DATE_RANGE;\n    proMode?: boolean;\n    maxSources?: number;\n    onSearchResults: t.SearchToolConfig['onSearchResults'];\n    images?: boolean;\n    videos?: boolean;\n    news?: boolean;\n  }): Promise<t.SearchResultData> {\n    try {\n      // Execute parallel searches and merge results\n      const searchResult = await executeParallelSearches({\n        searchAPI,\n        query,\n        date,\n        country,\n        safeSearch,\n        images: supportsImages && images,\n        videos: supportsVideos && videos,\n        news: supportsNews && news,\n        logger,\n      });\n\n      onSearchResults?.(searchResult);\n\n      const processedSources = await sourceProcessor.processSources({\n        query,\n        news,\n        result: searchResult,\n        proMode,\n        onGetHighlights,\n        numElements: maxSources,\n      });\n\n      return expandHighlights(\n        processedSources,\n        mainExpandBy,\n        separatorExpandBy\n      );\n    } catch (error) {\n      logger.error('Error in search:', error);\n      return {\n        organic: [],\n        topStories: [],\n        images: [],\n        videos: [],\n        news: [],\n        relatedSearches: [],\n        error: error instanceof Error ? error.message : String(error),\n      };\n    }\n  };\n}\n\nfunction createOnSearchResults({\n  runnableConfig,\n  onSearchResults,\n}: {\n  runnableConfig: RunnableConfig;\n  onSearchResults: t.SearchToolConfig['onSearchResults'];\n}) {\n  return function (results: t.SearchResult): void {\n    if (!onSearchResults) {\n      return;\n    }\n    onSearchResults(results, runnableConfig);\n  };\n}\n\nfunction createTool({\n  schema,\n  search,\n  maxOutputChars,\n  onSearchResults: _onSearchResults,\n}: {\n  schema: Record<string, unknown>;\n  search: ReturnType<typeof createSearchProcessor>;\n  maxOutputChars?: number;\n  onSearchResults: t.SearchToolConfig['onSearchResults'];\n}): DynamicStructuredTool {\n  return tool(\n    async (rawParams, runnableConfig) => {\n      const params = rawParams as SearchToolParams;\n      const { query, date, country: _c, images, videos, news } = params;\n      const country = typeof _c === 'string' && _c ? _c : undefined;\n      const searchResult = await search({\n        query,\n        date,\n        country,\n        images,\n        videos,\n        news,\n        onSearchResults: createOnSearchResults({\n          runnableConfig,\n          onSearchResults: _onSearchResults,\n        }),\n      });\n      const turn = runnableConfig.toolCall?.turn ?? 0;\n      const { output, references } = formatResultsForLLM(\n        turn,\n        searchResult,\n        maxOutputChars\n      );\n      const data: t.SearchResultData = { turn, ...searchResult, references };\n      return [output, { [Constants.WEB_SEARCH]: data }];\n    },\n    {\n      name: WebSearchToolName,\n      description: WebSearchToolDescription,\n      schema: schema,\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n\n/**\n * Creates a search tool with configurable search and scraper providers.\n *\n * Search providers: Serper (Google results), SearXNG (self-hosted meta-search), Tavily (AI-optimized), fastCRW (Firecrawl-compatible, self-host or cloud).\n * Scraper providers: Firecrawl (default, full-featured), Serper (lightweight), Tavily (batch extraction), fastCRW (Firecrawl-compatible, self-host or cloud).\n *\n * The country schema field is exposed to the LLM for providers that support localized results.\n */\n/** Input params type for search tool */\ninterface SearchToolParams {\n  query: string;\n  date?: DATE_RANGE;\n  country?: string;\n  images?: boolean;\n  videos?: boolean;\n  news?: boolean;\n}\n\nexport const createSearchTool = (\n  config: t.SearchToolConfig = {}\n): DynamicStructuredTool => {\n  const {\n    searchProvider = 'serper',\n    serperApiKey,\n    searxngInstanceUrl,\n    searxngApiKey,\n    tavilyApiKey,\n    tavilySearchUrl,\n    tavilyExtractUrl,\n    tavilySearchOptions,\n    keenableApiKey,\n    keenableApiUrl,\n    keenableSearchOptions,\n    keenableScraperOptions,\n    rerankerType = 'cohere',\n    rerankerTimeout,\n    topResults = 5,\n    maxContentLength,\n    chunkSize,\n    chunkOverlap,\n    mainExpandBy,\n    separatorExpandBy,\n    maxOutputChars,\n    strategies = ['no_extraction'],\n    filterContent = true,\n    safeSearch = 1,\n    scraperProvider = 'firecrawl',\n    firecrawlApiKey,\n    firecrawlApiUrl,\n    firecrawlVersion,\n    firecrawlOptions,\n    serperScraperOptions,\n    tavilyScraperOptions,\n    crwApiKey,\n    crwApiUrl,\n    crwSearchOptions,\n    crwScraperOptions,\n    scraperTimeout,\n    jinaApiKey,\n    jinaApiUrl,\n    cohereApiKey,\n    onSearchResults: _onSearchResults,\n    onGetHighlights,\n  } = config;\n\n  const logger = config.logger || createDefaultLogger();\n  const effectiveTavilySearchOptions =\n    searchProvider === 'tavily' && config.safeSearch != null\n      ? {\n        ...tavilySearchOptions,\n        safeSearch: config.safeSearch !== 0,\n      }\n      : tavilySearchOptions;\n\n  const schemaProperties: Record<string, unknown> = {\n    query: querySchema,\n    date: dateSchema,\n    images: imagesSchema,\n    videos: videosSchema,\n    news: newsSchema,\n  };\n\n  if (searchProvider === 'serper' || searchProvider === 'tavily') {\n    schemaProperties.country = countrySchema;\n  }\n\n  const toolSchema = {\n    type: 'object',\n    properties: schemaProperties,\n    required: ['query'],\n  };\n\n  const searchAPI = createSearchAPI({\n    searchProvider,\n    serperApiKey,\n    searxngInstanceUrl,\n    searxngApiKey,\n    tavilyApiKey,\n    tavilySearchUrl,\n    tavilySearchOptions: effectiveTavilySearchOptions,\n    keenableApiKey,\n    keenableApiUrl,\n    keenableSearchOptions,\n    crwApiKey,\n    crwApiUrl,\n    crwSearchOptions,\n  });\n\n  /** Create scraper based on scraperProvider */\n  let scraperInstance: t.BaseScraper;\n\n  if (scraperProvider === 'serper') {\n    scraperInstance = createSerperScraper({\n      ...serperScraperOptions,\n      apiKey: serperApiKey,\n      timeout: scraperTimeout ?? serperScraperOptions?.timeout,\n      logger,\n    });\n  } else if (scraperProvider === 'tavily') {\n    scraperInstance = createTavilyScraper({\n      ...tavilyScraperOptions,\n      apiKey:\n        tavilyScraperOptions?.apiKey ??\n        tavilyApiKey ??\n        process.env.TAVILY_API_KEY,\n      apiUrl: tavilyScraperOptions?.apiUrl ?? tavilyExtractUrl,\n      timeout: scraperTimeout ?? tavilyScraperOptions?.timeout,\n      logger,\n    });\n  } else if (scraperProvider === 'crw') {\n    scraperInstance = createCrwScraper({\n      ...crwScraperOptions,\n      apiKey: crwScraperOptions?.apiKey ?? crwApiKey ?? process.env.CRW_API_KEY,\n      apiUrl: crwScraperOptions?.apiUrl ?? crwApiUrl,\n      timeout: scraperTimeout ?? crwScraperOptions?.timeout,\n      formats: crwScraperOptions?.formats ?? ['markdown', 'rawHtml'],\n      logger,\n    });\n  } else if (scraperProvider === 'keenable') {\n    scraperInstance = createKeenableScraper({\n      ...keenableScraperOptions,\n      apiKey: keenableScraperOptions?.apiKey ?? keenableApiKey,\n      timeout: scraperTimeout ?? keenableScraperOptions?.timeout,\n      attributionTitle:\n        keenableScraperOptions?.attributionTitle ??\n        keenableSearchOptions?.attributionTitle,\n      logger,\n    });\n  } else {\n    scraperInstance = createFirecrawlScraper({\n      ...firecrawlOptions,\n      apiKey: firecrawlApiKey ?? process.env.FIRECRAWL_API_KEY,\n      apiUrl: firecrawlApiUrl,\n      version: firecrawlVersion,\n      timeout: scraperTimeout ?? firecrawlOptions?.timeout,\n      formats: firecrawlOptions?.formats ?? ['markdown', 'rawHtml'],\n      logger,\n    });\n  }\n\n  const selectedReranker = createReranker({\n    rerankerType,\n    jinaApiKey,\n    jinaApiUrl,\n    cohereApiKey,\n    rerankerTimeout,\n    logger,\n  });\n\n  if (!selectedReranker) {\n    logger.warn('No reranker selected. Using default ranking.');\n  }\n\n  const sourceProcessor = createSourceProcessor(\n    {\n      reranker: selectedReranker,\n      topResults,\n      maxContentLength,\n      chunkSize,\n      chunkOverlap,\n      strategies,\n      filterContent,\n      logger,\n    },\n    scraperInstance\n  );\n\n  const search = createSearchProcessor({\n    searchAPI,\n    safeSearch,\n    // Keenable is organic-only: its API ignores `type`, so image/news\n    // sub-searches would spend rate limit and merge nothing.\n    supportsImages: searchProvider !== 'keenable',\n    supportsVideos:\n      searchProvider !== 'tavily' &&\n      searchProvider !== 'keenable' &&\n      searchProvider !== 'crw',\n    supportsNews: searchProvider !== 'keenable',\n    sourceProcessor,\n    onGetHighlights,\n    mainExpandBy,\n    separatorExpandBy,\n    logger,\n  });\n\n  return createTool({\n    search,\n    schema: toolSchema,\n    maxOutputChars,\n    onSearchResults: _onSearchResults,\n  });\n};\n"],"mappings":"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"}

package/dist/types/common/constants.d.ts

@@ -11,3 +11,21 @@ export declare const ANTHROPIC_TOOL_TOKEN_MULTIPLIER = 2.6;
  * Empirically calibrated at ~1.4× the raw JSON token count.
  */
 export declare const DEFAULT_TOOL_TOKEN_MULTIPLIER = 1.4;
+/**
+ * Default ceiling on cooperative stream seals per run. Each seal costs one
+ * extra superstep, so this also sizes the recursion-limit headroom a
+ * preemption-enabled run reserves.
+ */
+export declare const DEFAULT_MAX_SEALS = 8;
+/**
+ * Per-hook timeout for `PreemptBoundary`, deliberately far above
+ * `DEFAULT_HOOK_TIMEOUT_MS`. A host drain has already popped its queue and
+ * persisted content by the time this fires, so a timeout does not cancel the
+ * work — it only loses the messages the run was about to inject.
+ */
+export declare const PREEMPT_BOUNDARY_HOOK_TIMEOUT_MS = 120000;
+/**
+ * Default LangGraph recursion limit for a run. Callers may override it via
+ * the stream config; a preemption-enabled run adds its seal budget on top.
+ */
+export declare const DEFAULT_RECURSION_LIMIT = 50;

package/dist/types/graphs/Graph.d.ts

@@ -46,6 +46,20 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
     reasoningStepHasDeltas: Set<string>;
     protected handlerDispatchedEventCounts: Map<string, number>;
     signal?: AbortSignal;
+    /**
+     * The abort signal the CALLER handed to the current `processStream` call,
+     * assigned unconditionally — including back to `undefined` — on every call.
+     *
+     * Kept separate from {@link signal} on purpose. That field is construction
+     * state with its own consumers (model-call config, subagent parentSignal),
+     * so adopting a per-call signal into it would leak one call's controller
+     * into the next — `clearHeavyState()` is skipped on HITL interrupts, so a
+     * host that aborts a finished request's controller would poison the resumed
+     * run's model calls and boundary drains with an already-aborted signal.
+     * Boundary dispatch composes the two instead; see
+     * `StandardGraph.dispatchPreemptBoundary`.
+     */
+    callerSignal?: AbortSignal;
     /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
     invokedToolIds?: Set<string>;
     handlerRegistry: HandlerRegistry | undefined;
@@ -178,6 +192,8 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     messages: BaseMessage[];
     /** Cached run messages preserved before clearHeavyState() so getRunMessages() works after cleanup. */
     private cachedRunMessages?;
+    /** Ids of AI turns the agent node returned THIS run; see isRunProducedMessage. */
+    protected runProducedAiMessageIds: Set<string>;
     /** Checkpoint scope whose messages match index-keyed tool snapshots. */
     private originalToolContentCheckpointScope?;
     runId: string | undefined;
@@ -203,9 +219,105 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     subagentUsageSink?: t.SubagentUsageSink;
     /** See {@link t.StandardGraphInput.subagentScope}. */
     subagentScope: boolean;
-    constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, subagentUsageSink, subagentScope, }: t.StandardGraphInput);
+    /** See {@link t.StandardGraphInput.preemption}. */
+    preemption?: t.StreamPreemption;
+    /**
+     * Seals charged against `preemption.maxSeals`. Per-turn: cleared by both
+     * reset paths so a fresh turn gets a fresh budget, while a HITL resume —
+     * which skips `resetValues` — keeps what it had left.
+     */
+    private preemptSealBudgetUsed;
+    /**
+     * Seals honored over the graph's lifetime. Reported by
+     * {@link getPreemptStats}, so it deliberately SURVIVES `clearHeavyState()`
+     * — a host reads it after `processStream` returns, which is strictly after
+     * cleanup runs.
+     */
+    preemptSealCount: number;
+    /** Boundaries that produced nothing to inject, so the turn stopped early. */
+    preemptEmptyBoundaries: number;
+    /**
+     * Set between claiming a seal and resolving its boundary. `MultiAgentGraph`
+     * fans parallel agents through this one instance against a single host
+     * request, so without a one-at-a-time gate several streams would each seal
+     * for the same queued message and every loser would take the
+     * nothing-to-inject path and cut its answer short.
+     */
+    private preemptSealInFlight;
+    /**
+     * True when a seal ended the turn without a resume. The assistant turn is
+     * real and kept, but it is not the answer the model intended to finish —
+     * hosts persist it as unfinished rather than complete.
+     */
+    preemptIncomplete: boolean;
+    /**
+     * `stopReason` from a `PreemptBoundary` hook that halted the turn.
+     *
+     * Clearing the registry halt is what keeps the sealed turn alive, but the
+     * registry held the only copy of the reason — so it is captured here first.
+     * Without it `getHaltReason()` returns undefined and a host records a
+     * hook-halted turn as an ordinary completion.
+     */
+    preemptHaltReason: string | undefined;
+    /**
+     * Agent IDs whose next superstep must return to the agent node. Keyed by
+     * agent because `MultiAgentGraph` routes every parallel agent through this
+     * same instance, and a single field would let one agent's boundary resume
+     * another's turn.
+     */
+    pendingPreemptReturn: Set<string>;
+    constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, subagentUsageSink, subagentScope, preemption, }: t.StandardGraphInput);
     resetValues(keepContent?: boolean, checkpointScope?: string): void;
     clearHeavyState(): void;
+    /**
+     * Per-turn seal budget and routing markers. Cleared by both reset paths so
+     * a new turn starts with a full budget and no stale resume marker.
+     *
+     * The REPORTED counters are deliberately not touched here — see
+     * {@link resetPreemptTotals}.
+     */
+    private resetPreemptTurnState;
+    /**
+     * Lifetime seal totals, cleared only when a genuinely new run starts.
+     * `clearHeavyState()` must NOT call this: it runs in `processStream`'s
+     * `finally`, so zeroing here would make {@link getPreemptStats} and
+     * `preemptIncomplete` unreadable for every caller of the method that just
+     * produced them.
+     */
+    private resetPreemptTotals;
+    /**
+     * True when the host has requested a cooperative seal AND this graph may
+     * honor it. Read once per streamed chunk, so it stays property reads plus
+     * one host callback — no I/O, no allocation.
+     *
+     * Non-mutating: a true result only means a seal is worth evaluating. The
+     * budget is taken by {@link claimPreemptSeal} once the accumulated chunk is
+     * known to be safe, so a chunk that cannot seal never spends budget.
+     *
+     * Subagent scopes never seal: a steer targets the top-level conversation,
+     * and a child run must finish so its parent sees a complete result.
+     */
+    /** Internal seal preconditions only — no host callback, no side effects. */
+    private canClaimPreemptSeal;
+    shouldPreemptStream(): boolean;
+    /**
+     * Takes the seal slot, or returns false if another stream already holds it.
+     *
+     * Assumes the caller already polled `shouldPreemptStream()` for THIS chunk,
+     * and deliberately does not poll the host again — `StreamPreemption`
+     * documents `shouldPreempt` as once per chunk, and a host that consumes a
+     * pending flag on read would lose the request to a second call.
+     *
+     * The guard and both mutations remain one synchronous body, which is what
+     * makes this safe under a parallel `MultiAgentGraph`: several agents share
+     * one graph and can each see the poll as true, but no `await` can split the
+     * claim, so only one takes the slot. The loser keeps streaming normally
+     * rather than sealing for a message it would never receive.
+     */
+    claimPreemptSeal(): boolean;
+    /** Releases the seal slot once its boundary has resolved, win or lose. */
+    releasePreemptSeal(): void;
+    getPreemptStats(): t.PreemptStats;
     getRunStep(stepId: string): t.RunStep | undefined;
     getAgentContext(metadata: Record<string, unknown> | undefined): AgentContext;
     getStepBaseKey(metadata: Record<string, unknown> | undefined): string;
@@ -217,6 +329,17 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     private getBaseKeyList;
     checkKeyList(keyList: (string | number | undefined)[]): boolean;
     getRunMessages(): BaseMessage[] | undefined;
+    /**
+     * True when THIS RUN produced `message` — the provenance the handoff cue
+     * gate needs. Tracked as an id set rather than inferred from `startIndex`
+     * arithmetic: summarization's remove-all compaction rewrites the live
+     * array and leaves `startIndex` stale, so index-based run/host
+     * discrimination silently breaks right after a mid-run summarize. Ids
+     * survive compaction (retained messages keep theirs), host-supplied
+     * prefill messages are never in the set, and membership is O(1) per
+     * model call.
+     */
+    isRunProducedMessage(message: BaseMessage): boolean;
     getContentParts(): t.MessageContentComplex[] | undefined;
     getCalibrationRatio(): number;
     getResolvedInstructionOverhead(): number | undefined;
@@ -256,6 +379,20 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
      */
     private beginOverflowRecovery;
     createCallModel(agentId?: string): (state: t.AgentSubgraphState, config?: RunnableConfig) => Promise<Partial<t.AgentSubgraphState>>;
+    /**
+     * Fires `PreemptBoundary` after a sealed turn and returns whatever the
+     * hooks asked to inject, converted through the same `convertInjectedMessages`
+     * the tool boundary uses so the two sites cannot emit different shapes.
+     *
+     * Never throws: a drain that fails or times out costs the injection, not the
+     * run. The caller treats an empty result as "nothing to resume with".
+     *
+     * `preventContinuation` is surfaced alongside the messages rather than left
+     * to the registry halt signal, which `processStream` only polls between
+     * stream events — by then the self-loop it was meant to prevent has already
+     * issued another model call, and a direct graph consumer never polls it.
+     */
+    private dispatchPreemptBoundary;
     createAgentNode(agentId: string): t.CompiledAgentWorfklow;
     createWorkflow(): t.CompiledStateWorkflow;
     /**

package/dist/types/hooks/HookRegistry.d.ts

@@ -120,5 +120,20 @@ export declare class HookRegistry {
     hasResultAlteringHooks(sessionId?: string): boolean;
     /** True if at least one matcher exists for `event` (global + session). */
     hasHookFor(event: HookEvent, sessionId?: string): boolean;
+    /**
+     * True when at least one matcher for `event` would actually DISPATCH on a
+     * query-less call — a wildcard pattern with a non-empty `hooks` array.
+     *
+     * `hasHookFor` answers "is one registered", which is not the same question:
+     * a matcher carrying a pattern is inert for events that supply no
+     * `matchQuery`, so a caller using registration as a proxy for "something
+     * will run" can act on a hook that never fires. Mirrors the two skips in
+     * `executeHooks` (pattern mismatch, empty `hooks`).
+     *
+     * Non-allocating on purpose — `StandardGraph.canClaimPreemptSeal` reads it
+     * once per streamed chunk, where `getMatchers`' defensive `slice()` would
+     * allocate on every delta.
+     */
+    hasDispatchableHookFor(event: HookEvent, sessionId?: string): boolean;
     private ensureSessionBucket;
 }

package/dist/types/hooks/index.d.ts

@@ -8,11 +8,22 @@ export { executeHooks, DEFAULT_HOOK_TIMEOUT_MS } from './executeHooks';
  * be consumed by an SDK version that would silently drop it.
  */
 export declare const HOOK_INJECTED_MESSAGES_CAPABLE = true;
+/**
+ * Feature probe for hosts: this SDK dispatches `PreemptBoundary`, so a
+ * cooperative mid-generation seal can drain into the run.
+ *
+ * Deliberately separate from {@link HOOK_INJECTED_MESSAGES_CAPABLE} — an SDK
+ * version can support `injectedMessages` at the tool boundary and know
+ * nothing about preemption. A host that probed the wrong flag would arm an
+ * interrupt control whose seal request is silently ignored, which reads to
+ * the user as a dead button rather than as an unsupported feature.
+ */
+export declare const HOOK_PREEMPT_BOUNDARY_CAPABLE = true;
 export { matchesQuery, hasNestedQuantifier, MAX_PATTERN_LENGTH, MAX_CACHE_SIZE, } from './matchers';
 export { createToolPolicyHook } from './createToolPolicyHook';
 export type { ToolPolicyMode, ToolPolicyConfig } from './createToolPolicyHook';
 export { createWorkspacePolicyHook } from './createWorkspacePolicyHook';
 export type { OutsideAccessPolicy, WorkspacePolicyConfig, PathExtractor, } from './createWorkspacePolicyHook';
 export { HOOK_EVENTS } from './types';
-export type { HookEvent, HookInput, HookOutput, HookCallback, HookMatcher, HooksByEvent, HookInputByEvent, HookOutputByEvent, BaseHookInput, BaseHookOutput, ToolDecision, StopDecision, AggregatedHookResult, RunStartHookInput, UserPromptSubmitHookInput, PreToolUseHookInput, PostToolUseHookInput, PostToolUseFailureHookInput, PostToolBatchHookInput, PostToolBatchEntry, PermissionDeniedHookInput, SubagentStartHookInput, SubagentStopHookInput, StopHookInput, StopFailureHookInput, PreCompactHookInput, PostCompactHookInput, RunStartHookOutput, UserPromptSubmitHookOutput, PreToolUseHookOutput, PostToolUseHookOutput, PostToolUseFailureHookOutput, PostToolBatchHookOutput, PermissionDeniedHookOutput, SubagentStartHookOutput, SubagentStopHookOutput, StopHookOutput, StopFailureHookOutput, PreCompactHookOutput, PostCompactHookOutput, } from './types';
+export type { HookEvent, HookInput, HookOutput, HookCallback, HookMatcher, HooksByEvent, HookInputByEvent, HookOutputByEvent, BaseHookInput, BaseHookOutput, ToolDecision, StopDecision, AggregatedHookResult, RunStartHookInput, UserPromptSubmitHookInput, PreToolUseHookInput, PostToolUseHookInput, PostToolUseFailureHookInput, PostToolBatchHookInput, PostToolBatchEntry, PreemptBoundaryHookInput, PermissionDeniedHookInput, SubagentStartHookInput, SubagentStopHookInput, StopHookInput, StopFailureHookInput, PreCompactHookInput, PostCompactHookInput, RunStartHookOutput, UserPromptSubmitHookOutput, PreToolUseHookOutput, PostToolUseHookOutput, PostToolUseFailureHookOutput, PostToolBatchHookOutput, PreemptBoundaryHookOutput, PermissionDeniedHookOutput, SubagentStartHookOutput, SubagentStopHookOutput, StopHookOutput, StopFailureHookOutput, PreCompactHookOutput, PostCompactHookOutput, } from './types';
 export type { ExecuteHooksOptions } from './executeHooks';

package/dist/types/hooks/types.d.ts

@@ -8,7 +8,7 @@ import type { InjectedMessage } from '@/types/tools';
  * `docs/hooks-design-report.md` §3.2 for the mapping to existing
  * `@librechat/agents` emission points.
  */
-export declare const HOOK_EVENTS: readonly ["RunStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "PermissionDenied", "SubagentStart", "SubagentStop", "Stop", "StopFailure", "PreCompact", "PostCompact"];
+export declare const HOOK_EVENTS: readonly ["RunStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "PreemptBoundary", "PermissionDenied", "SubagentStart", "SubagentStop", "Stop", "StopFailure", "PreCompact", "PostCompact"];
 export type HookEvent = (typeof HOOK_EVENTS)[number];
 /** Tool-gating decision; executeHooks folds with `deny > ask > allow` precedence. */
 export type ToolDecision = 'allow' | 'deny' | 'ask';
@@ -117,6 +117,38 @@ export interface PostToolBatchHookInput extends BaseHookInput {
     /** All tool calls (and their outcomes) from this batch, in batch order. */
     entries: PostToolBatchEntry[];
 }
+/**
+ * Fires when a cooperative preemption seals the model stream mid-generation
+ * — the second injection boundary, and the only one that exists during a
+ * long text answer with no tool calls in it.
+ *
+ * Order: fires after the model stream is sealed and BEFORE the next model
+ * call. The `injectedMessages` a hook returns here are appended verbatim and
+ * the agent node self-loops. Returning nothing is a valid outcome (the host's
+ * queue was cancelled or already drained): the run stops honestly rather than
+ * self-looping into an empty turn.
+ *
+ * The sealed turn is NOT yet observable from graph state when this fires.
+ * Dispatch happens inside the agent node, and only the outer graph's reducer
+ * writes `StandardGraph.messages` — which cannot run until the node returns.
+ * A hook calling `Run.getRunMessages()` here sees the state as of the last
+ * completed superstep, so the sealed text is absent. `PostToolBatch` behaves
+ * the same way: a tool-boundary hook cannot see the assistant turn that
+ * requested the tool. This is a property of the single-node outer graph, not
+ * of preemption, and committing first would mean returning from the node and
+ * re-entering — precisely what the self-loop exists to avoid.
+ *
+ * A hook that needs the sealed text should therefore not go looking for it in
+ * graph state. Decide from the host's own queue, or read it after the run.
+ *
+ * Requires `RunConfig.preemption`. This event is deliberately NOT
+ * result-altering, so registering it never disables eager tool execution.
+ */
+export interface PreemptBoundaryHookInput extends BaseHookInput {
+    hook_event_name: 'PreemptBoundary';
+    /** 1-based index of this seal within the run. */
+    sealCount: number;
+}
 export interface PermissionDeniedHookInput extends BaseHookInput {
     hook_event_name: 'PermissionDenied';
     toolName: string;
@@ -170,7 +202,7 @@ export interface PostCompactHookInput extends BaseHookInput {
     messagesAfterCount: number;
 }
 /** Discriminated union of every hook input shape. */
-export type HookInput = RunStartHookInput | UserPromptSubmitHookInput | PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | PostToolBatchHookInput | PermissionDeniedHookInput | SubagentStartHookInput | SubagentStopHookInput | StopHookInput | StopFailureHookInput | PreCompactHookInput | PostCompactHookInput;
+export type HookInput = RunStartHookInput | UserPromptSubmitHookInput | PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | PostToolBatchHookInput | PreemptBoundaryHookInput | PermissionDeniedHookInput | SubagentStartHookInput | SubagentStopHookInput | StopHookInput | StopFailureHookInput | PreCompactHookInput | PostCompactHookInput;
 /** Compile-time map from event name to its input shape. */
 export type HookInputByEvent = {
     RunStart: RunStartHookInput;
@@ -179,6 +211,7 @@ export type HookInputByEvent = {
     PostToolUse: PostToolUseHookInput;
     PostToolUseFailure: PostToolUseFailureHookInput;
     PostToolBatch: PostToolBatchHookInput;
+    PreemptBoundary: PreemptBoundaryHookInput;
     PermissionDenied: PermissionDeniedHookInput;
     SubagentStart: SubagentStartHookInput;
     SubagentStop: SubagentStopHookInput;
@@ -196,14 +229,18 @@ export interface BaseHookOutput {
     additionalContext?: string;
     /**
      * Messages to inject into graph state, one `HumanMessage` per entry
-     * (converted via `ToolNode.convertInjectedMessages`, which preserves
+     * (converted via `convertInjectedMessages`, which preserves
      * `role`/`source`/`isMeta` in `additional_kwargs`). Unlike
      * `additionalContext` — which is consolidated across hooks into a single
      * system-flavored message — each entry keeps its own identity and role,
      * making this the channel for injecting verbatim user speech (e.g. a
      * mid-run steering message). Accumulated across hooks in registration
-     * order. Currently consumed only at the `PostToolBatch` dispatch site;
-     * other events ignore the field.
+     * order.
+     *
+     * Consumed at exactly two dispatch sites, both of which run the same
+     * converter so the emitted shapes cannot drift: `PostToolBatch` (the tool
+     * boundary) and `PreemptBoundary` (a cooperative mid-generation seal).
+     * Every other event ignores the field.
      */
     injectedMessages?: InjectedMessage[];
     /** True to prevent the next model turn. Any hook can set this. */
@@ -305,6 +342,7 @@ export interface PostToolUseHookOutput extends BaseHookOutput {
 }
 export type PostToolUseFailureHookOutput = BaseHookOutput;
 export type PostToolBatchHookOutput = BaseHookOutput;
+export type PreemptBoundaryHookOutput = BaseHookOutput;
 export type PermissionDeniedHookOutput = BaseHookOutput;
 export interface SubagentStartHookOutput extends BaseHookOutput {
     decision?: ToolDecision;
@@ -326,6 +364,7 @@ export type HookOutputByEvent = {
     PostToolUse: PostToolUseHookOutput;
     PostToolUseFailure: PostToolUseFailureHookOutput;
     PostToolBatch: PostToolBatchHookOutput;
+    PreemptBoundary: PreemptBoundaryHookOutput;
     PermissionDenied: PermissionDeniedHookOutput;
     SubagentStart: SubagentStartHookOutput;
     SubagentStop: SubagentStopHookOutput;
@@ -335,7 +374,7 @@ export type HookOutputByEvent = {
     PostCompact: PostCompactHookOutput;
 };
 /** Superset output shape used by the executor's fold loop. */
-export type HookOutput = RunStartHookOutput | UserPromptSubmitHookOutput | PreToolUseHookOutput | PostToolUseHookOutput | PostToolUseFailureHookOutput | PostToolBatchHookOutput | PermissionDeniedHookOutput | SubagentStartHookOutput | SubagentStopHookOutput | StopHookOutput | StopFailureHookOutput | PreCompactHookOutput | PostCompactHookOutput;
+export type HookOutput = RunStartHookOutput | UserPromptSubmitHookOutput | PreToolUseHookOutput | PostToolUseHookOutput | PostToolUseFailureHookOutput | PostToolBatchHookOutput | PreemptBoundaryHookOutput | PermissionDeniedHookOutput | SubagentStartHookOutput | SubagentStopHookOutput | StopHookOutput | StopFailureHookOutput | PreCompactHookOutput | PostCompactHookOutput;
 /**
  * A hook callback is a plain async function registered against a specific
  * event. The `signal` is always supplied by `executeHooks` and combines the

package/dist/types/index.d.ts

@@ -1,6 +1,5 @@
 export * from './run';
 export * from './stream';
-export * from './splitStream';
 export * from './events';
 export * from './messages';
 export * from './graphs';
@@ -45,4 +44,5 @@ export { getChatModelClass } from './llm/providers';
 export { FakeChatModel, createFakeStreamingLLM } from './llm/fake';
 export { initializeModel } from './llm/init';
 export { attemptInvoke, tryFallbackProviders } from './llm/invoke';
+export { canSealPreempt } from './llm/preempt';
 export { isThinkingEnabled, getMaxOutputTokensKey } from './llm/request';

package/dist/types/llm/invoke.d.ts

@@ -54,6 +54,13 @@ export declare function projectMessagesForProvider({ model, messages, provider,
     maxToolResultChars?: number;
     callOptions?: unknown;
 }): BaseMessage[];
+/**
+ * The serving model's id, read through the same wrapper stack
+ * `collectModelCallbackSources` walks — `bindTools` returns a
+ * `RunnableBinding` and a system runnable pipes a `RunnableSequence`, and
+ * neither exposes the chat model's `model` at the top level.
+ */
+export declare function resolveServingModelId(model: unknown): string | undefined;
 /**
  * Invokes a chat model with the given messages, handling both streaming and
  * non-streaming paths.