@illuma-ai/agents 1.5.1 → 2.1.1

package/src/tools/search/test.ts

@@ -0,0 +1,159 @@
+/* eslint-disable no-console */
+// processWikipedia.ts
+import * as fs from 'fs';
+import * as path from 'path';
+import { processContent } from './content';
+
+/**
+ * Process a Wikipedia article (HTML and Markdown) and create a referenced version
+ */
+async function processWikipediaArticle(): Promise<void> {
+  try {
+    console.log('Starting Wikipedia article processing...');
+
+    // Define file paths - adapt these to your specific file locations
+    const htmlPath = path.resolve('./test.html');
+    const markdownPath = path.resolve('./test.md');
+    const outputPath = path.resolve('./output.md');
+
+    // Check if input files exist
+    if (!fs.existsSync(htmlPath)) {
+      throw new Error(`Wikipedia HTML file not found at ${htmlPath}`);
+    }
+
+    if (!fs.existsSync(markdownPath)) {
+      throw new Error(`Wikipedia Markdown file not found at ${markdownPath}`);
+    }
+
+    console.log('Reading Wikipedia article files...');
+    const html = fs.readFileSync(htmlPath, 'utf-8');
+    const markdown = fs.readFileSync(markdownPath, 'utf-8');
+
+    // Extract article title for logging
+    const titleMatch = /<h1[^>]*>([^<]+)<\/h1>/i.exec(html);
+    const articleTitle = titleMatch
+      ? titleMatch[1].trim()
+      : 'Wikipedia article';
+
+    console.log(`Processing "${articleTitle}"...`);
+
+    // Measure processing time
+    const startTime = process.hrtime();
+
+    // Process content
+    const result = processContent(html, markdown);
+
+    // Calculate processing time
+    const elapsed = process.hrtime(startTime);
+    const timeInMs = elapsed[0] * 1000 + elapsed[1] / 1000000;
+
+    // Generate reference appendix
+    const appendix = generateReferenceAppendix(result);
+
+    // Create complete output with the processed content and appendix
+    const completeOutput = result.markdown + appendix;
+
+    // Write to output file
+    fs.writeFileSync(outputPath, completeOutput);
+
+    // Print processing statistics
+    console.log('\nWikipedia article processing complete! ✓');
+    console.log('-'.repeat(60));
+    console.log(`Article: ${articleTitle}`);
+    console.log(`Processing time: ${timeInMs.toFixed(2)}ms`);
+    console.log('Media references replaced:');
+    console.log(`  - Links: ${result.links.length}`);
+    console.log(`  - Images: ${result.images.length}`);
+    console.log(`  - Videos: ${result.videos.length}`);
+    console.log(
+      `  - Total: ${result.links.length + result.images.length + result.videos.length}`
+    );
+    console.log(`Output saved to: ${outputPath}`);
+    console.log('-'.repeat(60));
+
+    // Print sample of the transformation
+    const sampleLines = result.markdown.split('\n').slice(0, 10).join('\n');
+    console.log('\nSample of transformed content:');
+    console.log('-'.repeat(30));
+    console.log(sampleLines);
+    console.log('-'.repeat(30));
+    console.log('... (continued in output file)');
+  } catch (error) {
+    console.error('Error processing Wikipedia article:', error);
+    process.exit(1);
+  }
+}
+
+/**
+ * Generate a comprehensive reference appendix with all media links
+ */
+function generateReferenceAppendix(result: {
+  links: Array<{ originalUrl: string; title?: string; text?: string }>;
+  images: Array<{ originalUrl: string; title?: string }>;
+  videos: Array<{ originalUrl: string; title?: string }>;
+}): string {
+  let appendix = '\n\n' + '---'.repeat(10) + '\n\n';
+  appendix += '# References\n\n';
+
+  if (result.links.length > 0) {
+    appendix += '## Links\n\n';
+    result.links.forEach((link, index) => {
+      // Clean and format text for display
+      let displayText = '';
+      if (link.text != null && link.text.trim()) {
+        // Limit length for very long link text
+        let cleanText = link.text.trim();
+        if (cleanText.length > 50) {
+          cleanText = cleanText.substring(0, 47) + '...';
+        }
+        displayText = ` - "${cleanText}"`;
+      }
+
+      appendix += `**link#${index + 1}**: ${link.originalUrl}${displayText}\n\n`;
+    });
+  }
+
+  if (result.images.length > 0) {
+    appendix += '## Images\n\n';
+    result.images.forEach((image, index) => {
+      const displayTitle =
+        image.title != null && image.title.trim()
+          ? ` - ${image.title.trim()}`
+          : '';
+      appendix += `**image#${index + 1}**: ${image.originalUrl}${displayTitle}\n\n`;
+    });
+  }
+
+  if (result.videos.length > 0) {
+    appendix += '## Videos\n\n';
+    result.videos.forEach((video, index) => {
+      const displayTitle =
+        video.title != null && video.title.trim()
+          ? ` - ${video.title.trim()}`
+          : '';
+      appendix += `**video#${index + 1}**: ${video.originalUrl}${displayTitle}\n\n`;
+    });
+  }
+
+  // Add a category breakdown to show what types of links were found
+  const totalRefs =
+    result.links.length + result.images.length + result.videos.length;
+
+  appendix += '## Summary\n\n';
+  appendix += `Total references: **${totalRefs}**\n\n`;
+  appendix += `- Links: ${result.links.length}\n`;
+  appendix += `- Images: ${result.images.length}\n`;
+  appendix += `- Videos: ${result.videos.length}\n`;
+
+  return appendix;
+}
+
+// Using async IIFE to allow for better error handling
+(async (): Promise<void> => {
+  try {
+    await processWikipediaArticle();
+  } catch (error) {
+    console.error('Unhandled error:', error);
+    process.exit(1);
+  }
+})();

package/src/tools/search/tool.ts

@@ -12,7 +12,6 @@ import {
 } from './schema';
 import { createSearchAPI, createSourceProcessor } from './search';
 import { createSerperScraper } from './serper-scraper';
-import { createTavilyScraper } from './tavily-scraper';
 import { createFirecrawlScraper } from './firecrawl';
 import { expandHighlights } from './highlights';
 import { formatResultsForLLM } from './format';
@@ -310,16 +309,12 @@ async function executeParallelSearches({
 function createSearchProcessor({
   searchAPI,
   safeSearch,
-  supportsVideos,
   sourceProcessor,
   scraper,
   onGetHighlights,
   logger,
 }: {
   safeSearch: t.SearchToolConfig['safeSearch'];
-  /* Tavily search API does not return videos. Other providers (Serper)
-   * do — this flag short-circuits the videos request when unsupported. */
-  supportsVideos: boolean;
   searchAPI: ReturnType<typeof createSearchAPI>;
   sourceProcessor: ReturnType<typeof createSourceProcessor>;
   scraper: t.BaseScraper;
@@ -371,7 +366,7 @@ function createSearchProcessor({
           country,
           safeSearch,
           images,
-          videos: supportsVideos && videos,
+          videos,
           news,
           logger,
         });
@@ -554,10 +549,6 @@ export const createSearchTool = (
     serperApiKey,
     searxngInstanceUrl,
     searxngApiKey,
-    tavilyApiKey,
-    tavilySearchUrl,
-    tavilyExtractUrl,
-    tavilySearchOptions,
     domainBlocklist,
     countryBlocklist,
     rerankerType = 'cohere',
@@ -571,7 +562,6 @@ export const createSearchTool = (
     firecrawlVersion,
     firecrawlOptions,
     serperScraperOptions,
-    tavilyScraperOptions,
     scraperTimeout,
     jinaApiKey,
     jinaApiUrl,
@@ -581,15 +571,6 @@ export const createSearchTool = (
   } = config;
 
   const logger = config.logger || createDefaultLogger();
-  /* Tavily search API exposes a `safe_search` boolean derived from the
-   * tool's existing safeSearch level (0 = off, ≥1 = on). Bridge the two. */
-  const effectiveTavilySearchOptions =
-    searchProvider === 'tavily' && config.safeSearch != null
-      ? {
-        ...tavilySearchOptions,
-        safeSearch: config.safeSearch !== 0,
-      }
-      : tavilySearchOptions;
 
   const schemaProperties: Record<string, unknown> = {
     query: querySchema,
@@ -599,7 +580,7 @@ export const createSearchTool = (
     news: newsSchema,
   };
 
-  if (searchProvider === 'serper' || searchProvider === 'tavily') {
+  if (searchProvider === 'serper') {
     schemaProperties.country = countrySchema;
   }
 
@@ -614,9 +595,6 @@ export const createSearchTool = (
     serperApiKey,
     searxngInstanceUrl,
     searxngApiKey,
-    tavilyApiKey,
-    tavilySearchUrl,
-    tavilySearchOptions: effectiveTavilySearchOptions,
     domainBlocklist,
     countryBlocklist,
   });
@@ -631,17 +609,6 @@ export const createSearchTool = (
       timeout: scraperTimeout ?? serperScraperOptions?.timeout,
       logger,
     });
-  } else if (scraperProvider === 'tavily') {
-    scraperInstance = createTavilyScraper({
-      ...tavilyScraperOptions,
-      apiKey:
-        tavilyScraperOptions?.apiKey ??
-        tavilyApiKey ??
-        process.env.TAVILY_API_KEY,
-      apiUrl: tavilyScraperOptions?.apiUrl ?? tavilyExtractUrl,
-      timeout: scraperTimeout ?? tavilyScraperOptions?.timeout,
-      logger,
-    });
   } else {
     scraperInstance = createFirecrawlScraper({
       ...firecrawlOptions,
@@ -680,7 +647,6 @@ export const createSearchTool = (
   const search = createSearchProcessor({
     searchAPI,
     safeSearch,
-    supportsVideos: searchProvider !== 'tavily',
     sourceProcessor,
     scraper: scraperInstance,
     onGetHighlights,

package/src/tools/search/types.ts

@@ -3,8 +3,8 @@ import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseReranker } from './rerankers';
 import { DATE_RANGE } from './schema';
 
-export type SearchProvider = 'serper' | 'searxng' | 'tavily';
-export type ScraperProvider = 'firecrawl' | 'serper' | 'tavily';
+export type SearchProvider = 'serper' | 'searxng';
+export type ScraperProvider = 'firecrawl' | 'serper';
 export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'none';
 
 export interface Highlight {
@@ -62,59 +62,11 @@ export interface Source {
   date?: string;
 }
 
-export type TavilyTimeRange = 'day' | 'week' | 'month' | 'year';
-export type TavilyTimeRangeInput =
-  | TavilyTimeRange
-  | 'h'
-  | 'd'
-  | 'w'
-  | 'm'
-  | 'y';
-
-export interface TavilySearchOptions {
-  searchDepth?: 'basic' | 'advanced' | 'fast' | 'ultra-fast';
-  maxResults?: number;
-  includeImages?: boolean;
-  includeAnswer?: boolean | 'basic' | 'advanced';
-  includeRawContent?: boolean | 'markdown' | 'text';
-  includeDomains?: string[];
-  excludeDomains?: string[];
-  topic?: 'general' | 'news' | 'finance';
-  timeRange?: TavilyTimeRangeInput;
-  includeImageDescriptions?: boolean;
-  includeFavicon?: boolean;
-  chunksPerSource?: number;
-  safeSearch?: boolean;
-  timeout?: number;
-}
-
-export interface TavilySearchPayload {
-  query: string;
-  search_depth: NonNullable<TavilySearchOptions['searchDepth']>;
-  topic: NonNullable<TavilySearchOptions['topic']>;
-  max_results: number;
-  safe_search?: boolean;
-  time_range?: TavilyTimeRange;
-  country?: string;
-  include_images?: boolean;
-  include_answer?: NonNullable<TavilySearchOptions['includeAnswer']>;
-  include_raw_content?: NonNullable<TavilySearchOptions['includeRawContent']>;
-  include_domains?: string[];
-  exclude_domains?: string[];
-  include_image_descriptions?: boolean;
-  include_favicon?: boolean;
-  chunks_per_source?: number;
-}
-
 export interface SearchConfig {
   searchProvider?: SearchProvider;
   serperApiKey?: string;
   searxngInstanceUrl?: string;
   searxngApiKey?: string;
-  tavilyApiKey?: string;
-  tavilySearchUrl?: string;
-  tavilyExtractUrl?: string;
-  tavilySearchOptions?: TavilySearchOptions;
   /** Domains to exclude from search results (e.g., 'reddit.com', 'twitter.com').
    *  Appended as -site: operators to the search query. */
   domainBlocklist?: string[];
@@ -160,17 +112,6 @@ export interface SerperScraperConfig {
   includeMarkdown?: boolean;
 }
 
-export interface TavilyScraperConfig {
-  apiKey?: string;
-  apiUrl?: string;
-  timeout?: number;
-  logger?: Logger;
-  extractDepth?: 'basic' | 'advanced';
-  includeImages?: boolean;
-  includeFavicon?: boolean;
-  format?: 'markdown' | 'text';
-}
-
 export interface ScraperContentResult {
   content: string;
 }
@@ -219,7 +160,6 @@ export interface SearchToolConfig
   extends SearchConfig,
     ProcessSourcesConfig,
     FirecrawlConfig {
-  tavilyScraperOptions?: TavilyScraperConfig;
   logger?: Logger;
   safeSearch?: SafeSearchLevel;
   jinaApiKey?: string;
@@ -247,27 +187,20 @@ export type UsedReferences = {
   reference: MediaReference;
 }[];
 
-export type AnyScraperResponse =
-  | FirecrawlScrapeResponse
-  | SerperScrapeResponse
-  | TavilyScrapeResponse;
-
 /** Base Scraper Interface */
 export interface BaseScraper {
   scrapeUrl(
     url: string,
     options?: unknown
-  ): Promise<[string, AnyScraperResponse]>;
-  scrapeUrls?(
-    urls: string[],
-    options?: unknown
-  ): Promise<Array<[string, AnyScraperResponse]>>;
+  ): Promise<[string, FirecrawlScrapeResponse | SerperScrapeResponse]>;
   extractContent(
-    response: AnyScraperResponse
+    response: FirecrawlScrapeResponse | SerperScrapeResponse
   ): [string, undefined | References];
   extractMetadata(
-    response: AnyScraperResponse
-  ): ScrapeMetadata | GenericScrapeMetadata;
+    response: FirecrawlScrapeResponse | SerperScrapeResponse
+  ):
+    | ScrapeMetadata
+    | Record<string, string | number | boolean | null | undefined>;
 }
 
 /** Firecrawl */
@@ -281,25 +214,6 @@ export type SerperScrapeOptions = Omit<
   'apiKey' | 'apiUrl' | 'logger'
 >;
 
-export type TavilyScrapeOptions = Omit<
-  TavilyScraperConfig,
-  'apiKey' | 'apiUrl' | 'logger'
->;
-
-export interface TavilyExtractPayload {
-  urls: string[];
-  extract_depth: NonNullable<TavilyScraperConfig['extractDepth']>;
-  include_images: boolean;
-  include_favicon?: boolean;
-  format?: NonNullable<TavilyScraperConfig['format']>;
-  timeout?: number;
-}
-
-export type GenericScrapeMetadata = Record<
-  string,
-  string | number | boolean | null | undefined
->;
-
 export interface ScrapeMetadata {
   // Core source information
   sourceURL?: string;
@@ -386,45 +300,6 @@ export interface SerperScrapeResponse {
   error?: string;
 }
 
-export interface TavilyScrapeResponse {
-  success: boolean;
-  data?: {
-    rawContent?: string;
-    images?: string[];
-    favicon?: string;
-  };
-  error?: string;
-}
-
-export interface TavilySearchResult {
-  title?: string;
-  url?: string;
-  content?: string;
-  score?: number;
-  published_date?: string;
-}
-
-export type TavilyImageResult =
-  | string
-  | {
-      url?: string;
-      description?: string;
-    };
-
-export interface TavilySearchResponse {
-  answer?: string;
-  images?: TavilyImageResult[];
-  results?: TavilySearchResult[];
-}
-
-export interface TavilyExtractResult {
-  url: string;
-  raw_content?: string;
-  images?: string[];
-  favicon?: string;
-  error?: string;
-}
-
 export interface FirecrawlScraperConfig {
   apiKey?: string;
   apiUrl?: string;

package/src/tools/search/utils.ts

@@ -29,18 +29,11 @@ export const fileExtRegex =
 
 export const getDomainName = (
   link: string,
-  metadata?: t.ScrapeMetadata | t.GenericScrapeMetadata,
+  metadata?: t.ScrapeMetadata,
   logger?: t.Logger
 ): string | undefined => {
   try {
-    const sourceUrl = metadata?.sourceURL;
-    const metadataUrl = metadata?.url;
-    const url =
-      typeof sourceUrl === 'string'
-        ? sourceUrl
-        : typeof metadataUrl === 'string'
-          ? metadataUrl
-          : link || '';
+    const url = metadata?.sourceURL ?? metadata?.url ?? (link || '');
     const domain = new URL(url).hostname.replace(/^www\./, '');
     if (domain) {
       return domain;
@@ -59,7 +52,7 @@ export const getDomainName = (
 
 export function getAttribution(
   link: string,
-  metadata?: t.ScrapeMetadata | t.GenericScrapeMetadata,
+  metadata?: t.ScrapeMetadata,
   logger?: t.Logger
 ): string | undefined {
   if (!metadata) return getDomainName(link, metadata, logger);
@@ -67,17 +60,16 @@ export function getAttribution(
   const twitterSite = metadata['twitter:site'];
   const twitterSiteFormatted =
     typeof twitterSite === 'string' ? twitterSite.replace(/^@/, '') : undefined;
-  const title = metadata.title;
 
   const possibleAttributions = [
     metadata.ogSiteName,
     metadata['og:site_name'],
-    typeof title === 'string' ? title.split('|').pop()?.trim() : undefined,
+    metadata.title?.split('|').pop()?.trim(),
     twitterSiteFormatted,
   ];
 
   const attribution = possibleAttributions.find(
-    (attr): attr is string => typeof attr === 'string' && attr.trim() !== ''
+    (attr) => attr != null && typeof attr === 'string' && attr.trim() !== ''
   );
   if (attribution != null) {
     return attribution;

package/src/tools/subagent/SubagentExecutor.ts

@@ -40,6 +40,35 @@ export type SubagentExecuteParams = {
    * without relying on event ordering heuristics.
    */
   parentToolCallId?: string;
+  /**
+   * Snapshot of the parent invocation's `config.configurable` at the
+   * spawn-tool call site. Inherited verbatim into the child workflow's
+   * `configurable` so host-set fields (`requestBody`, `user`,
+   * `userMCPAuthMap`, etc.) propagate — fixing MCP body-placeholder
+   * substitution and per-user lookups for subagent tool calls.
+   *
+   * Inheritance details (verified empirically against LangGraph):
+   *   - host-set keys propagate as-is into the child's tool dispatches;
+   *   - `thread_id` propagates (with `childRunId` as a fallback when
+   *     parent did not supply one) — matches the "subagent is part of
+   *     the same conversation" mental model and aligns with the
+   *     `sessionId: this.parentRunId` convention this executor already
+   *     uses for `SubagentStart` / `SubagentStop` hooks;
+   *   - `parent_run_id` propagates when the host put it on parent's
+   *     configurable;
+   *   - `run_id` is *overwritten by the LangGraph runtime* at child
+   *     invoke time regardless of what we forward — child's tool
+   *     dispatches see the child graph's runtime runId in
+   *     `configurable.run_id`, not the parent's. Hosts that need
+   *     parent-scoped run identity for downstream consumers should
+   *     plumb it via a host-defined key (e.g. `requestBody.messageId`),
+   *     not `run_id`.
+   *
+   * A future revision will likely make this inheritance configurable
+   * per spawn type — background / async subagents may want isolation
+   * rather than sharing parent's host context.
+   */
+  parentConfigurable?: Record<string, unknown>;
 };
 
 export type SubagentExecuteResult = {
@@ -246,6 +275,52 @@ export class SubagentExecutor {
        * nested trace pollution).
        */
       const callbacks: Callbacks = forwarder ? [forwarder] : [];
+      /**
+       * Inherit the parent's `configurable` verbatim — host-set fields
+       * (`requestBody`, `user`, `userMCPAuthMap`, etc.) AND the run-
+       * identity fields (`run_id`, `parent_run_id`, `thread_id`) all
+       * propagate.
+       *
+       * Run-identity propagation is intentional and matches the
+       * convention this executor itself already uses for `SubagentStart`
+       * / `SubagentStop` hooks (`sessionId: this.parentRunId`): the
+       * subagent runs under the parent's session scope, not its own.
+       * Forwarding `run_id` / `parent_run_id` / `thread_id` makes
+       * `ToolNode`'s hook lookups (`hasHookFor(eventName, runId)`),
+       * `ToolOutputReferenceRegistry` keying, and trace lineage all
+       * resolve to the parent's session for tools dispatched from the
+       * subagent — so `PreToolUse` / `PostToolUse` hooks the host
+       * registered against the parent's run fire for subagent tool
+       * calls too. "Same run" matches the user-perceptual mental model.
+       *
+       * `thread_id` falls back to `childRunId` only when the parent
+       * didn't supply one (legacy behavior preserved for hosts that
+       * never set thread_id).
+       *
+       * NOTE: a future revision will likely make this configurable per
+       * spawn type — e.g. a background / async subagent that runs after
+       * the parent's run completes wants isolation, not inheritance.
+       * For now the inheritance path matches LibreChat's primary use
+       * case (synchronous subagents within a single user turn).
+       */
+      const inheritedConfigurable: Record<string, unknown> =
+        params.parentConfigurable ?? {};
+      /**
+       * Surface the parent's `subagent` tool_call.id to the child's run
+       * metadata so host-side artifact handlers (e.g. ranger's
+       * `resolveUiToolCallId`) can re-key child-emitted attachments to
+       * the parent's bubble. Without this, files produced by tools
+       * inside a subagent (execute_code .docx, image_gen, etc.) get
+       * attached to the child's inner tool_call_id — which the parent
+       * message has no record of — and orphan in the chat UI.
+       */
+      const inheritedMetadata: Record<string, unknown> = {
+        ...((inheritedConfigurable as { metadata?: Record<string, unknown> })
+          .metadata ?? {}),
+        parentToolCallId,
+        subagentAgentId: childAgentId,
+        subagentType,
+      };
       result = await workflow.invoke(
         { messages: [new HumanMessage(description)] },
         {
@@ -255,7 +330,10 @@ export class SubagentExecutor {
           runName: `subagent:${subagentType}`,
           configurable: {
             thread_id: childRunId,
+            ...inheritedConfigurable,
+            parentToolCallId,
           },
+          metadata: inheritedMetadata,
         }
       );
     } catch (error) {