@librechat/agents 3.3.4 → 3.3.6

package/src/tools/search/keenable-scraper.ts

@@ -0,0 +1,137 @@
+import axios from 'axios';
+import type * as t from './types';
+import { createDefaultLogger } from './utils';
+
+const DEFAULT_KEENABLE_SCRAPE_TIMEOUT = 15000;
+
+/** 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';
+
+export class KeenableScraper implements t.BaseScraper {
+  private apiKey: string | undefined;
+  private apiUrl: string;
+  private timeout: number;
+  private attributionTitle: string;
+  private logger: t.Logger;
+
+  constructor(config: t.KeenableScraperConfig = {}) {
+    const resolvedKey = config.apiKey ?? process.env.KEENABLE_API_KEY;
+    this.apiKey =
+      resolvedKey != null && resolvedKey !== '' ? resolvedKey : undefined;
+    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();
+  }
+
+  private buildHeaders(): Record<string, string> {
+    /** 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: Record<string, string> = {
+      'X-Keenable-Title': this.attributionTitle,
+    };
+    if (this.apiKey != null) {
+      headers['X-API-Key'] = this.apiKey;
+    }
+    return headers;
+  }
+
+  async scrapeUrl(
+    url: string,
+    options: t.KeenableScrapeOptions = {}
+  ): Promise<[string, t.KeenableScrapeResponse]> {
+    if (!url || !url.trim()) {
+      return [url, { success: false, error: 'URL cannot be empty' }];
+    }
+
+    try {
+      const response = await axios.get<t.KeenableFetchResult>(this.apiUrl, {
+        params: { url },
+        headers: this.buildHeaders(),
+        timeout: options.timeout ?? this.timeout,
+      });
+
+      const data = response.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) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      return [
+        url,
+        {
+          success: false,
+          error: `Keenable Fetch API request failed: ${errorMessage}`,
+        },
+      ];
+    }
+  }
+
+  async scrapeUrls(
+    urls: string[],
+    options: t.KeenableScrapeOptions = {}
+  ): Promise<Array<[string, t.KeenableScrapeResponse]>> {
+    /** Keenable fetch is single-URL; run the batch concurrently. */
+    return Promise.all(urls.map((url) => this.scrapeUrl(url, options)));
+  }
+
+  extractContent(
+    response: t.KeenableScrapeResponse
+  ): [string, undefined | t.References] {
+    if (!response.success || !response.data) {
+      return ['', undefined];
+    }
+    /** Keenable returns clean markdown with no separate media arrays, so there
+     * are no structured references to surface. */
+    return [response.data.content, undefined];
+  }
+
+  extractMetadata(response: t.KeenableScrapeResponse): t.GenericScrapeMetadata {
+    if (!response.success || !response.data) {
+      return {};
+    }
+    const metadata: t.GenericScrapeMetadata = {};
+    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;
+  }
+}
+
+export const createKeenableScraper = (
+  config: t.KeenableScraperConfig = {}
+): KeenableScraper => {
+  return new KeenableScraper(config);
+};

package/src/tools/search/outcome.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect } from '@jest/globals';
+import type * as t from './types';
+import { resolveSearchOutcome } from './tool';
+
+const data = (partial: Partial<t.SearchResultData>): t.SearchResultData =>
+  ({ turn: 0, ...partial }) as t.SearchResultData;
+
+describe('resolveSearchOutcome', () => {
+  it('authors a FAILURE label when the processor caught an error', () => {
+    expect(
+      resolveSearchOutcome(
+        data({ error: 'provider timeout', organic: [] }),
+        'oauth handling'
+      )
+    ).toBe('Search failed for "oauth handling"');
+  });
+
+  it('prefers the failure label over any partial results', () => {
+    expect(
+      resolveSearchOutcome(
+        data({
+          error: 'partial failure',
+          organic: [{ link: 'a' }] as t.SearchResultData['organic'],
+        }),
+        'oauth'
+      )
+    ).toBe('Search failed for "oauth"');
+  });
+
+  it('ignores an empty-string error', () => {
+    expect(
+      resolveSearchOutcome(
+        data({
+          error: '',
+          organic: [{ link: 'a' }] as t.SearchResultData['organic'],
+        }),
+        'oauth'
+      )
+    ).toBe('Found 1 result for "oauth"');
+  });
+
+  it('counts every rendered collection kind', () => {
+    expect(
+      resolveSearchOutcome(
+        data({
+          organic: [
+            { link: 'a' },
+            { link: 'b' },
+          ] as t.SearchResultData['organic'],
+          topStories: [{ link: 'c' }] as t.SearchResultData['topStories'],
+          images: [{ imageUrl: 'd' }] as t.SearchResultData['images'],
+          videos: [{ link: 'e' }] as t.SearchResultData['videos'],
+          places: [{ name: 'f' }] as t.SearchResultData['places'],
+          peopleAlsoAsk: [
+            { question: 'g' },
+          ] as t.SearchResultData['peopleAlsoAsk'],
+        }),
+        'oauth'
+      )
+    ).toBe('Found 7 results for "oauth"');
+  });
+
+  it('counts singleton structured results (knowledge graph / answer box)', () => {
+    expect(
+      resolveSearchOutcome(
+        data({
+          knowledgeGraph: {
+            title: 'OAuth',
+          } as t.SearchResultData['knowledgeGraph'],
+        }),
+        'oauth'
+      )
+    ).toBe('Found 1 result for "oauth"');
+    expect(
+      resolveSearchOutcome(
+        data({
+          answerBox: { snippet: 'x' } as t.SearchResultData['answerBox'],
+          knowledgeGraph: {
+            title: 'OAuth',
+          } as t.SearchResultData['knowledgeGraph'],
+        }),
+        'oauth'
+      )
+    ).toBe('Found 2 results for "oauth"');
+  });
+
+  it('leaves a genuine zero-result search to the mechanical transform', () => {
+    expect(resolveSearchOutcome(data({ organic: [] }), 'oauth')).toBeUndefined();
+  });
+});

package/src/tools/search/schema.ts

@@ -1,3 +1,5 @@
+import { INTENT_PROPERTY } from '@/tools/intentArg';
+
 export enum DATE_RANGE {
   PAST_HOUR = 'h',
   PAST_24_HOURS = 'd',
@@ -71,6 +73,7 @@ export const newsSchema = {
 export const WebSearchToolSchema = {
   type: 'object',
   properties: {
+    intent: { ...INTENT_PROPERTY },
     query: querySchema,
     date: dateSchema,
     country: countrySchema,

package/src/tools/search/tool.ts

@@ -13,9 +13,11 @@ import {
   DATE_RANGE,
 } from './schema';
 import { createSearchAPI, createSourceProcessor } from './search';
+import { createKeenableScraper } from './keenable-scraper';
 import { createSerperScraper } from './serper-scraper';
 import { createTavilyScraper } from './tavily-scraper';
 import { createFirecrawlScraper } from './firecrawl';
+import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { createCrwScraper } from './crw-scraper';
 import { expandHighlights } from './highlights';
 import { formatResultsForLLM } from './format';
@@ -23,6 +25,46 @@ import { createDefaultLogger } from './utils';
 import { createReranker } from './rerankers';
 import { Constants } from '@/common';
 
+/**
+ * Settled label for a `web_search` call's intent (see `intentArg.ts`).
+ *
+ * Counts the result kinds `formatResultsForLLM` actually renders —
+ * `references` only tracks links embedded in extracted highlights, so it
+ * undercounts ordinary results and can overcount when one highlight embeds
+ * several links.
+ *
+ * A caught provider or processing failure is reported through `data.error`
+ * while the tool still returns NORMALLY, so that case must author its own
+ * label: the `ToolMessage` carries success status, and a bare intent would
+ * otherwise settle mechanically from "Searching…" to "Searched…" and present
+ * a failed search as a successful one.
+ *
+ * Returns undefined for a genuine zero-result search, leaving the host's
+ * mechanical past-tense transform to label it.
+ */
+export function resolveSearchOutcome(
+  data: t.SearchResultData,
+  query: string
+): string | undefined {
+  if (data.error != null && data.error !== '') {
+    return `Search failed for "${query}"`;
+  }
+  const count =
+    (data.organic?.length ?? 0) +
+    (data.topStories?.length ?? 0) +
+    (data.news?.length ?? 0) +
+    (data.images?.length ?? 0) +
+    (data.videos?.length ?? 0) +
+    (data.places?.length ?? 0) +
+    (data.peopleAlsoAsk?.length ?? 0) +
+    (data.knowledgeGraph != null ? 1 : 0) +
+    (data.answerBox != null ? 1 : 0);
+  if (count === 0) {
+    return undefined;
+  }
+  return `Found ${count} result${count === 1 ? '' : 's'} for "${query}"`;
+}
+
 /**
  * Executes parallel searches and merges the results,
  * deduplicating top stories by link
@@ -334,7 +376,11 @@ function createTool({
         maxOutputChars
       );
       const data: t.SearchResultData = { turn, ...searchResult, references };
-      return [output, { [Constants.WEB_SEARCH]: data }];
+      const outcome = resolveSearchOutcome(data, query);
+      return [
+        output,
+        { [Constants.WEB_SEARCH]: data, ...(outcome != null && { outcome }) },
+      ];
     },
     {
       name: WebSearchToolName,
@@ -378,6 +424,7 @@ export const createSearchTool = (
     keenableApiKey,
     keenableApiUrl,
     keenableSearchOptions,
+    keenableScraperOptions,
     rerankerType = 'cohere',
     rerankerTimeout,
     topResults = 5,
@@ -419,6 +466,7 @@ export const createSearchTool = (
       : tavilySearchOptions;
 
   const schemaProperties: Record<string, unknown> = {
+    intent: { ...INTENT_PROPERTY },
     query: querySchema,
     date: dateSchema,
     images: imagesSchema,
@@ -476,13 +524,22 @@ export const createSearchTool = (
   } else if (scraperProvider === 'crw') {
     scraperInstance = createCrwScraper({
       ...crwScraperOptions,
-      apiKey:
-        crwScraperOptions?.apiKey ?? crwApiKey ?? process.env.CRW_API_KEY,
+      apiKey: crwScraperOptions?.apiKey ?? crwApiKey ?? process.env.CRW_API_KEY,
       apiUrl: crwScraperOptions?.apiUrl ?? crwApiUrl,
       timeout: scraperTimeout ?? crwScraperOptions?.timeout,
       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,

package/src/tools/search/types.ts

@@ -3,8 +3,18 @@ import type { Logger as WinstonLogger } from 'winston';
 import type { BaseReranker } from './rerankers';
 import { DATE_RANGE } from './schema';
 
-export type SearchProvider = 'serper' | 'searxng' | 'tavily' | 'keenable' | 'crw';
-export type ScraperProvider = 'firecrawl' | 'serper' | 'tavily' | 'crw';
+export type SearchProvider =
+  | 'serper'
+  | 'searxng'
+  | 'tavily'
+  | 'keenable'
+  | 'crw';
+export type ScraperProvider =
+  | 'firecrawl'
+  | 'serper'
+  | 'tavily'
+  | 'crw'
+  | 'keenable';
 export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'none';
 
 export interface Highlight {
@@ -198,6 +208,41 @@ export interface KeenableSearchResponse {
   results?: KeenableSearchResult[];
 }
 
+export interface KeenableScraperConfig {
+  apiKey?: string;
+  /** Override the fetch endpoint base (default: public keyless, keyed when a
+   * key is set). Env fallback: KEENABLE_FETCH_URL. */
+  apiUrl?: string;
+  timeout?: number;
+  logger?: Logger;
+  /** Sent as the X-Keenable-Title attribution header. Defaults to "LibreChat". */
+  attributionTitle?: string;
+}
+
+export type KeenableScrapeOptions = Omit<
+  KeenableScraperConfig,
+  'apiKey' | 'apiUrl' | 'logger'
+>;
+
+/** Raw JSON shape returned by GET /v1/fetch{,/public}?url=... */
+export interface KeenableFetchResult {
+  url?: string;
+  title?: string;
+  content?: string;
+  description?: string;
+}
+
+export interface KeenableScrapeResponse {
+  success: boolean;
+  data?: {
+    content: string;
+    title?: string;
+    description?: string;
+    url?: string;
+  };
+  error?: string;
+}
+
 export type References = {
   links: MediaReference[];
   images: MediaReference[];
@@ -311,6 +356,7 @@ export interface SearchToolConfig
     FirecrawlConfig {
   tavilyScraperOptions?: TavilyScraperConfig;
   crwScraperOptions?: CrwScraperConfig;
+  keenableScraperOptions?: KeenableScraperConfig;
   /** Max chars of highlight content this tool feeds the MODEL per search (the
    * dominant, otherwise-unbounded part of the output). Distinct from
    * `maxContentLength`, which caps scraped/reranked content per source — full
@@ -351,7 +397,8 @@ export type AnyScraperResponse =
   | FirecrawlScrapeResponse
   | SerperScrapeResponse
   | TavilyScrapeResponse
-  | CrwScrapeResponse;
+  | CrwScrapeResponse
+  | KeenableScrapeResponse;
 
 /** Base Scraper Interface */
 export interface BaseScraper {

package/src/tools/subagent/SubagentExecutor.ts

@@ -115,7 +115,7 @@ type SanitizedStepCompleted =
     };
 
 type SanitizedProcessedToolCall = Partial<
-  Pick<ProcessedToolCall, 'args' | 'id' | 'name' | 'output' | 'progress'>
+  Pick<ProcessedToolCall, 'args' | 'id' | 'name' | 'output' | 'progress' | 'outcome'>
 >;
 
 type SanitizedRunStepCompleted = {
@@ -1195,6 +1195,7 @@ function sanitizeProcessedToolCall(
     sanitized.args = call.args;
   }
   assignString(sanitized, 'output', call.output);
+  assignString(sanitized, 'outcome', call.outcome);
   assignNumber(sanitized, 'progress', call.progress);
   return sanitized;
 }

package/src/tools/toolOutputReferences.ts

@@ -30,6 +30,25 @@ import {
   HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE,
 } from '@/utils/truncation';
 import { isComputerCallOutputMessage } from '@/utils/toolContent';
+import { INTENT_ARG } from '@/tools/intentArg';
+
+/** Parses a stringified JSON object arg; undefined for anything else. */
+function parseStringifiedArgsObject(
+  value: string
+): Record<string, unknown> | undefined {
+  if (!value.trim().startsWith('{')) {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (parsed != null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
 
 /**
  * Non-global matcher for a single `{{tool<i>turn<n>}}` placeholder.
@@ -89,9 +108,20 @@ export type ResolveResult<T> = {
  * point in time, ignoring any subsequent registrations.
  */
 export interface ToolOutputResolveView {
-  resolve<T>(args: T): ResolveResult<T>;
+  resolve<T>(args: T, options?: ResolveOptions): ResolveResult<T>;
 }
 
+/**
+ * Per-call resolution options. `substituteIntentKey` opts the top-level
+ * `intent` key back INTO placeholder substitution: the exemption protects
+ * the injected display label, but a tool whose own schema declares a
+ * business parameter named `intent` (the injectors skip such tools) still
+ * needs references piped into it like any other argument.
+ */
+export type ResolveOptions = {
+  substituteIntentKey?: boolean;
+};
+
 /**
  * Pre-resolved arg map keyed by `toolCallId`. Used by the mixed
  * direct+event dispatch path to feed event calls' resolved args
@@ -333,12 +363,16 @@ export class ToolOutputReferenceRegistry {
    * the serialized args, the original input is returned without
    * walking the tree.
    */
-  resolve<T>(runId: string | undefined, args: T): ResolveResult<T> {
+  resolve<T>(
+    runId: string | undefined,
+    args: T,
+    options?: ResolveOptions
+  ): ResolveResult<T> {
     if (!hasAnyPlaceholder(args)) {
       return { resolved: args, unresolved: [] };
     }
     const bucket = this.runStates.get(this.keyFor(runId));
-    return this.resolveAgainst(bucket?.entries ?? EMPTY_ENTRIES, args);
+    return this.resolveAgainst(bucket?.entries ?? EMPTY_ENTRIES, args, options);
   }
 
   /**
@@ -358,27 +392,52 @@ export class ToolOutputReferenceRegistry {
       ? new Map(bucket.entries)
       : EMPTY_ENTRIES;
     return {
-      resolve: <T>(args: T): ResolveResult<T> =>
-        this.resolveAgainst(entries, args),
+      resolve: <T>(args: T, options?: ResolveOptions): ResolveResult<T> =>
+        this.resolveAgainst(entries, args, options),
     };
   }
 
   private resolveAgainst<T>(
     entries: ReadonlyMap<string, string>,
-    args: T
+    args: T,
+    options?: ResolveOptions
   ): ResolveResult<T> {
     if (!hasAnyPlaceholder(args)) {
       return { resolved: args, unresolved: [] };
     }
+    const exemptIntentKey = options?.substituteIntentKey !== true;
     const unresolved = new Set<string>();
-    const resolved = this.transform(entries, args, unresolved) as T;
+    /**
+     * Providers may deliver the args OBJECT as a JSON string. A plain
+     * string-root transform would expand placeholders inside the `intent`
+     * label too, bypassing the top-level exclusion below — parse, transform
+     * key-aware, and re-serialize so the label stays verbatim while every
+     * other field still substitutes. Only taken when an `intent` key is
+     * actually present; other strings keep the fast raw-string path.
+     */
+    if (exemptIntentKey && typeof args === 'string') {
+      const parsedRoot = parseStringifiedArgsObject(args);
+      if (parsedRoot != null && INTENT_ARG in parsedRoot) {
+        const resolved = JSON.stringify(
+          this.transform(entries, parsedRoot, unresolved, true)
+        ) as T;
+        return { resolved, unresolved: Array.from(unresolved) };
+      }
+    }
+    const resolved = this.transform(
+      entries,
+      args,
+      unresolved,
+      exemptIntentKey
+    ) as T;
     return { resolved, unresolved: Array.from(unresolved) };
   }
 
   private transform(
     entries: ReadonlyMap<string, string>,
     value: unknown,
-    unresolved: Set<string>
+    unresolved: Set<string>,
+    exemptRootIntent = false
   ): unknown {
     if (typeof value === 'string') {
       return this.replaceInString(entries, value, unresolved);
@@ -390,7 +449,16 @@ export class ToolOutputReferenceRegistry {
       const source = value as Record<string, unknown>;
       const next: Record<string, unknown> = {};
       for (const [key, item] of Object.entries(source)) {
-        next[key] = this.transform(entries, item, unresolved);
+        /**
+         * The top-level `intent` arg is a display label, never a data
+         * channel: expanding a `{{tool<i>turn<n>}}` placeholder there would
+         * dump a stored output (up to the registry cap) into a single-line
+         * UI label and persist it with the message. Left verbatim instead.
+         */
+        next[key] =
+          exemptRootIntent && key === INTENT_ARG
+            ? item
+            : this.transform(entries, item, unresolved);
       }
       return next;
     }

package/src/types/graph.ts

@@ -30,7 +30,11 @@ import type {
   MessageDeltaEvent,
   ReasoningDeltaEvent,
 } from '@/types/stream';
-import type { TokenCounter, TokenBudgetBreakdown } from '@/types/run';
+import type {
+  TokenCounter,
+  StreamPreemption,
+  TokenBudgetBreakdown,
+} from '@/types/run';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
@@ -346,6 +350,13 @@ export type StandardGraphInput = {
    * hook inputs carry only `executingAgentId`.
    */
   subagentScope?: boolean;
+  /**
+   * Cooperative preemption, forwarded from `RunConfig.preemption`. Only ever
+   * set on the top-level graph: a steer targets the conversation, so subagent
+   * children must run to completion and `buildChildInputs` does not propagate
+   * this field.
+   */
+  preemption?: StreamPreemption;
 };
 
 export type GraphEdge = {