@librechat/agents 3.2.64 → 3.2.66

package/dist/types/tools/search/types.d.ts

@@ -2,8 +2,8 @@ import type { RunnableConfig } from '@langchain/core/runnables';
 import type { Logger as WinstonLogger } from 'winston';
 import type { BaseReranker } from './rerankers';
 import { DATE_RANGE } from './schema';
-export type SearchProvider = 'serper' | 'searxng' | 'tavily' | 'keenable';
-export type ScraperProvider = 'firecrawl' | 'serper' | 'tavily';
+export type SearchProvider = 'serper' | 'searxng' | 'tavily' | 'keenable' | 'crw';
+export type ScraperProvider = 'firecrawl' | 'serper' | 'tavily' | 'crw';
 export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'none';
 export interface Highlight {
     score: number;
@@ -91,6 +91,48 @@ export interface TavilySearchPayload {
     include_favicon?: boolean;
     chunks_per_source?: number;
 }
+export interface CrwSearchOptions {
+    /** Max results to request (maps to `limit`; clamped 1..20). */
+    maxResults?: number;
+    /** Add 'images' to the sources array. */
+    includeImages?: boolean;
+    timeout?: number;
+}
+export type CrwSearchSource = 'web' | 'images' | 'news';
+export interface CrwSearchPayload {
+    query: string;
+    limit: number;
+    sources?: CrwSearchSource[];
+    tbs?: string;
+}
+export interface CrwSearchResult {
+    title?: string;
+    url?: string;
+    description?: string;
+    snippet?: string;
+    position?: number;
+    category?: string;
+}
+export interface CrwImageSearchResult extends CrwSearchResult {
+    imageUrl?: string;
+    imageFormat?: string;
+}
+export interface CrwNewsSearchResult extends CrwSearchResult {
+    publishedDate?: string;
+}
+export interface CrwSearchGroups {
+    web?: CrwSearchResult[];
+    images?: CrwImageSearchResult[];
+    news?: CrwNewsSearchResult[];
+}
+export interface CrwSearchResponse {
+    success: boolean;
+    data?: (CrwSearchGroups & {
+        results?: CrwSearchGroups;
+    }) | CrwSearchResult[];
+    error?: string;
+    error_code?: string;
+}
 export interface SearchConfig {
     searchProvider?: SearchProvider;
     serperApiKey?: string;
@@ -103,6 +145,9 @@ export interface SearchConfig {
     keenableApiKey?: string;
     keenableApiUrl?: string;
     keenableSearchOptions?: KeenableSearchOptions;
+    crwApiKey?: string;
+    crwApiUrl?: string;
+    crwSearchOptions?: CrwSearchOptions;
 }
 export interface KeenableSearchOptions {
     maxResults?: number;
@@ -224,6 +269,7 @@ export type SafeSearchLevel = 0 | 1 | 2;
 export type Logger = WinstonLogger;
 export interface SearchToolConfig extends SearchConfig, ProcessSourcesConfig, FirecrawlConfig {
     tavilyScraperOptions?: TavilyScraperConfig;
+    crwScraperOptions?: CrwScraperConfig;
     /** 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
@@ -255,7 +301,7 @@ export type UsedReferences = {
     originalIndex: number;
     reference: MediaReference;
 }[];
-export type AnyScraperResponse = FirecrawlScrapeResponse | SerperScrapeResponse | TavilyScrapeResponse;
+export type AnyScraperResponse = FirecrawlScrapeResponse | SerperScrapeResponse | TavilyScrapeResponse | CrwScrapeResponse;
 /** Base Scraper Interface */
 export interface BaseScraper {
     scrapeUrl(url: string, options?: unknown): Promise<[string, AnyScraperResponse]>;
@@ -265,6 +311,24 @@ export interface BaseScraper {
 }
 /** Firecrawl */
 export type FirecrawlScrapeOptions = Omit<FirecrawlScraperConfig, 'apiKey' | 'apiUrl' | 'version' | 'logger'>;
+export interface CrwScraperConfig {
+    apiKey?: string;
+    apiUrl?: string;
+    formats?: string[];
+    timeout?: number;
+    logger?: Logger;
+    onlyMainContent?: boolean;
+    includeTags?: string[];
+    excludeTags?: string[];
+    waitFor?: number;
+    headers?: Record<string, string>;
+    renderJs?: boolean | null;
+    cssSelector?: string;
+    xpath?: string;
+    proxy?: string;
+    stealth?: boolean;
+}
+export type CrwScrapeOptions = Omit<CrwScraperConfig, 'apiKey' | 'apiUrl' | 'logger'>;
 export type SerperScrapeOptions = Omit<SerperScraperConfig, 'apiKey' | 'apiUrl' | 'logger'>;
 export type TavilyScrapeOptions = Omit<TavilyScraperConfig, 'apiKey' | 'apiUrl' | 'logger'>;
 export interface TavilyExtractPayload {
@@ -341,6 +405,27 @@ export interface FirecrawlScrapeResponse {
     };
     error?: string;
 }
+export interface CrwScrapeData {
+    markdown?: string;
+    html?: string;
+    rawHtml?: string;
+    plainText?: string;
+    screenshot?: string;
+    links?: string[];
+    metadata?: ScrapeMetadata;
+}
+export interface CrwScrapeResponse {
+    success: boolean;
+    data?: CrwScrapeData;
+    error?: string;
+    error_code?: string;
+}
+export interface CrwRawScrapeResponse extends CrwScrapeData {
+    success?: boolean;
+    data?: CrwScrapeData;
+    error?: string;
+    error_code?: string;
+}
 export interface SerperScrapeResponse {
     success: boolean;
     data?: {

package/dist/types/types/graph.d.ts

@@ -406,9 +406,9 @@ export type LangfuseToolOutputTracingConfig = {
 };
 export type LangfuseToolNodeTracingConfig = {
     /**
-     * Overrides ToolNode callback tracing. ToolNode spans are exported by the
-     * env-backed Langfuse callback, so this only enables tracing when that
-     * callback is configured.
+     * Opts into the internal ToolNode batch observation. Graph tool-dispatch
+     * and individual tool observations are exported without this wrapper, so
+     * the default is false to avoid a redundant hierarchy level.
      */
     enabled?: boolean;
 };
@@ -417,6 +417,13 @@ export interface LangfuseConfig {
     publicKey?: string;
     secretKey?: string;
     baseUrl?: string;
+    /**
+     * Environment identifier attached to exported traces (Langfuse
+     * `environment`). When unset, falls back to `LANGFUSE_TRACING_ENVIRONMENT`
+     * then `NODE_ENV`, so production traces are not collapsed under the
+     * `default` environment.
+     */
+    environment?: string;
     metadata?: Record<string, string | number | boolean | null | undefined>;
     /**
      * Internal OTLP span attributes to attach to Langfuse observations before

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.2.64",
+  "version": "3.2.66",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/graphs/Graph.ts

@@ -96,6 +96,18 @@ const { AGENT, TOOLS, SUMMARIZE } = GraphNodeKeys;
 /** Minimum relative variance before calibrated toolSchemaTokens overrides current value. */
 const CALIBRATION_VARIANCE_THRESHOLD = 0.15;
 
+function createToolHandlerRegistry(
+  source: HandlerRegistry | undefined
+): HandlerRegistry | undefined {
+  const toolHandler = source?.getHandler(GraphEvents.ON_TOOL_EXECUTE);
+  if (toolHandler == null) {
+    return undefined;
+  }
+  const registry = new HandlerRegistry();
+  registry.register(GraphEvents.ON_TOOL_EXECUTE, toolHandler);
+  return registry;
+}
+
 /**
  * Start index of the span post-prune formatters can mutate in place: the
  * trailing tool batch plus its owning AI message (artifact formatting touches
@@ -576,6 +588,8 @@ export abstract class Graph<
   /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
   invokedToolIds?: Set<string>;
   handlerRegistry: HandlerRegistry | undefined;
+  /** Host registry retained only for forwarding tools from nested child graphs. */
+  protected parentToolHandlerRegistry: HandlerRegistry | undefined;
   /**
    * True when event-driven tool execution can be routed through callbacks even
    * though this graph intentionally does not own the full handler registry.
@@ -661,6 +675,7 @@ export abstract class Graph<
     this.prelimMessageIdsByStepKey = new Map();
     this.invokedToolIds = undefined;
     this.handlerRegistry = undefined;
+    this.parentToolHandlerRegistry = undefined;
     this.hookRegistry = undefined;
     this.humanInTheLoop = undefined;
     this.toolOutputReferences = undefined;
@@ -1130,6 +1145,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   /* Misc.*/
 
   getRunMessages(): BaseMessage[] | undefined {
+    if (this.messages == null) {
+      return this.cachedRunMessages;
+    }
     if (this.messages.length === 0 && this.cachedRunMessages != null) {
       return this.cachedRunMessages;
     }
@@ -1137,6 +1155,12 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   }
 
   getContentParts(): t.MessageContentComplex[] | undefined {
+    // `messages` can be null/undefined on a graph that has been disposed
+    // (clearHeavyState) but is still reachable via a cache (e.g. RedisJobStore's
+    // WeakRef) during a HITL resume/reconnect. Guard instead of dereferencing null.
+    if (this.messages == null) {
+      return undefined;
+    }
     return convertMessagesToContent(this.messages.slice(this.startIndex));
   }
 
@@ -1169,6 +1193,12 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
    * Get all run steps, optionally filtered by agent ID
    */
   getRunSteps(agentId?: string): t.RunStep[] {
+    // `contentData` can be null/undefined on a disposed-but-cached graph during a
+    // HITL resume/reconnect; without this guard `[...this.contentData]` throws
+    // "this.contentData is not iterable".
+    if (this.contentData == null) {
+      return [];
+    }
     if (agentId == null || agentId === '') {
       return [...this.contentData];
     }
@@ -2361,7 +2391,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       );
       if (resolvedConfigs.length > 0) {
         const getParentHandlerRegistry = (): HandlerRegistry | undefined =>
-          this.handlerRegistry;
+          this.handlerRegistry ?? this.parentToolHandlerRegistry;
         const executor = new SubagentExecutor({
           configs: new Map(resolvedConfigs.map((c) => [c.type, c])),
           parentSignal: this.signal,
@@ -2378,6 +2408,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           maxDepth: effectiveSubagentDepth,
           createChildGraph: (input): StandardGraph => {
             const childGraph = new StandardGraph(input);
+            const toolHandlerRegistry = createToolHandlerRegistry(
+              getParentHandlerRegistry()
+            );
             childGraph.hookRegistry = this.hookRegistry;
             /**
              * Do not propagate `humanInTheLoop` into the child graph yet:
@@ -2400,9 +2433,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             // have the executable graphTool, the guard correctly applies.
             childGraph.interruptingToolNames = this.interruptingToolNames;
             childGraph.toolExecution = this.toolExecution;
+            childGraph.parentToolHandlerRegistry = toolHandlerRegistry;
             childGraph.eventToolExecutionAvailable =
-              this.handlerRegistry?.getHandler(GraphEvents.ON_TOOL_EXECUTE) !=
-              null;
+              toolHandlerRegistry != null;
             return childGraph;
           },
         });

package/src/instrumentation.ts

@@ -75,17 +75,35 @@ export function ensureOpenTelemetryContextManager(): void {
   }
 }
 
+function resolveLangfuseEnvironment(
+  langfuse?: t.LangfuseConfig
+): string | undefined {
+  const candidates = [
+    langfuse?.environment,
+    process.env.LANGFUSE_TRACING_ENVIRONMENT,
+    process.env.NODE_ENV,
+  ];
+  for (const candidate of candidates) {
+    if (candidate != null && candidate.trim() !== '') {
+      return candidate.trim();
+    }
+  }
+  return undefined;
+}
+
 function getLangfuseSpanProcessorParams(
   langfuse?: t.LangfuseConfig
 ): LangfuseSpanProcessorParams | undefined {
   if (langfuse?.enabled === false) {
     return undefined;
   }
+  const environment = resolveLangfuseEnvironment(langfuse);
   if (hasLangfuseConfigCredentials(langfuse)) {
     return {
       publicKey: langfuse.publicKey,
       secretKey: langfuse.secretKey,
       ...(isPresent(langfuse.baseUrl) ? { baseUrl: langfuse.baseUrl } : {}),
+      ...(isPresent(environment) ? { environment } : {}),
     };
   }
   if (hasLangfuseEnvConfig()) {
@@ -97,6 +115,7 @@ function getLangfuseSpanProcessorParams(
       publicKey: process.env.LANGFUSE_PUBLIC_KEY as string,
       secretKey: process.env.LANGFUSE_SECRET_KEY as string,
       ...(isPresent(baseUrl) ? { baseUrl } : {}),
+      ...(isPresent(environment) ? { environment } : {}),
     };
   }
   if (isPresent(langfuse?.baseUrl) && hasLangfuseEnvCredentials()) {
@@ -104,6 +123,7 @@ function getLangfuseSpanProcessorParams(
       publicKey: process.env.LANGFUSE_PUBLIC_KEY as string,
       secretKey: process.env.LANGFUSE_SECRET_KEY as string,
       baseUrl: langfuse.baseUrl,
+      ...(isPresent(environment) ? { environment } : {}),
     };
   }
   return undefined;

package/src/langfuseToolOutputTracing.ts

@@ -483,10 +483,8 @@ export function shouldTraceToolNodeForLangfuse({
   }
 
   const explicit = langfuse?.toolNodeTracing?.enabled;
-  if (explicit != null) {
-    return (
-      explicit && (hasLangfuseConfigKeys(langfuse) || hasLangfuseEnvKeys())
-    );
+  if (explicit !== true) {
+    return false;
   }
 
   return hasLangfuseConfigKeys(langfuse) || hasLangfuseEnvKeys();

package/src/langfuseTraceShaping.ts

@@ -5,8 +5,13 @@ const LANGGRAPH_START_NODE = '__start__';
 const ANONYMOUS_LAMBDA_NAME = 'RunnableLambda';
 const LANGGRAPH_AGENT_NODE_PREFIX = 'agent=';
 const LANGGRAPH_TOOL_NODE_PREFIX = 'tools=';
-const TOOL_BATCH_RUN_NAME = 'tool_batch';
 const AGENT_NODE_SPAN_NAME = 'agent';
+const TOOL_DISPATCH_SPAN_NAME = 'tool-dispatch';
+const GENERATION_SPAN_NAME = 'llm';
+const ROOT_OBSERVATION_TYPE = 'agent';
+const CHAIN_OBSERVATION_TYPE = 'chain';
+const AGENT_TRACE_TAG = 'agent';
+const TITLE_TRACE_TAG = 'title';
 
 type MutableSpan = ReadableSpan & {
   name: string;
@@ -207,6 +212,8 @@ function isRootSpan(span: ReadableSpan): boolean {
  * LangGraph plumbing observations that add noise without information:
  * the duplicated `__start__` channel-seed nodes and anonymous
  * `RunnableLambda` pass-throughs (Langfuse team feedback items 4 & 5).
+ * Internal ToolNode batch spans are disabled at their source so traced child
+ * tools retain an exported parent. Explicitly traced ToolNodes are preserved.
  */
 export function shouldDropLangfuseSpan(spanName: string): boolean {
   return (
@@ -216,18 +223,26 @@ export function shouldDropLangfuseSpan(spanName: string): boolean {
 
 function shapeToolNodeSpan(span: MutableSpan): void {
   const inputKey = LangfuseOtelSpanAttributes.OBSERVATION_INPUT;
+  span.name = TOOL_DISPATCH_SPAN_NAME;
+  span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_TYPE] =
+    CHAIN_OBSERVATION_TYPE;
   const calls = findPendingToolCalls(
     parseAttributeValue(span.attributes[inputKey])
   );
   if (calls.length === 0) {
     return;
   }
-  span.name = [...new Set(calls.map((call) => call.name))].join(', ');
   span.attributes[inputKey] = JSON.stringify(
     calls.map(({ name, args }) => ({ name, args }))
   );
 }
 
+function shapeAgentNodeSpan(span: MutableSpan): void {
+  span.name = AGENT_NODE_SPAN_NAME;
+  span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_TYPE] =
+    ROOT_OBSERVATION_TYPE;
+}
+
 function shapeRootSpan(span: MutableSpan): void {
   const inputKey = LangfuseOtelSpanAttributes.OBSERVATION_INPUT;
   const outputKey = LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT;
@@ -241,11 +256,47 @@ function shapeRootSpan(span: MutableSpan): void {
   );
   if (question != null) {
     span.attributes[inputKey] = question;
-    span.attributes[LangfuseOtelSpanAttributes.TRACE_INPUT] = question;
   }
   if (answer != null) {
     span.attributes[outputKey] = answer;
-    span.attributes[LangfuseOtelSpanAttributes.TRACE_OUTPUT] = answer;
+  }
+  const traceInput = question ?? span.attributes[inputKey];
+  const traceOutput = answer ?? span.attributes[outputKey];
+  if (traceInput != null) {
+    span.attributes[LangfuseOtelSpanAttributes.TRACE_INPUT] = traceInput;
+  }
+  if (traceOutput != null) {
+    span.attributes[LangfuseOtelSpanAttributes.TRACE_OUTPUT] = traceOutput;
+  }
+}
+
+function isGenerationSpan(span: MutableSpan): boolean {
+  const type = span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_TYPE];
+  return typeof type === 'string' && type.toLowerCase() === 'generation';
+}
+
+function hasTraceTag(span: MutableSpan, expectedTag: string): boolean {
+  const tags = parseAttributeValue(
+    span.attributes[LangfuseOtelSpanAttributes.TRACE_TAGS]
+  );
+  return (
+    Array.isArray(tags) &&
+    tags.some((tag) => typeof tag === 'string' && tag === expectedTag)
+  );
+}
+
+function shapeRootObservationType(span: MutableSpan): void {
+  if (isGenerationSpan(span)) {
+    return;
+  }
+  if (hasTraceTag(span, AGENT_TRACE_TAG)) {
+    span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_TYPE] =
+      ROOT_OBSERVATION_TYPE;
+    return;
+  }
+  if (hasTraceTag(span, TITLE_TRACE_TAG)) {
+    span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_TYPE] =
+      CHAIN_OBSERVATION_TYPE;
   }
 }
 
@@ -254,27 +305,29 @@ function shapeRootSpan(span: MutableSpan): void {
  * - `agent=<id>` / `tools=<id>` node names carry the ephemeral agent id
  *   (`provider__model`) — strip it so switching models doesn't break
  *   name-based logic (item 1).
- * - Tool node spans are renamed to the actual tool name(s) and their
- *   input scoped to the pending tool-call args instead of the whole
- *   chat history (items 3 & 4).
- * - The root span (and trace) input/output become the user question and
- *   assistant response so the session view reads as a conversation
- *   (item 2).
+ * - LLM generation spans keep the provider client class name (`ChatOpenAI`,
+ *   `AzureChatOpenAI`, …); rename them to a provider-agnostic `llm` so the
+ *   name reflects the operation, not the model (the model stays on the
+ *   generation's model attribute).
+ * - Agent nodes become `agent` observations, while tool-dispatch nodes become
+ *   stable `chain` observations whose input is scoped to the pending calls.
+ *   Individual child calls remain `tool` observations (items 3 & 4).
+ * - Agent trace roots become `agent` observations and title trace roots become
+ *   `chain` observations. Root and trace input/output are reduced to the user
+ *   question and assistant response when chat messages are available (item 2).
  */
 export function shapeLangfuseSpan(span: ReadableSpan): void {
   const mutable = span as MutableSpan;
   if (mutable.name.startsWith(LANGGRAPH_AGENT_NODE_PREFIX)) {
-    mutable.name = AGENT_NODE_SPAN_NAME;
-    return;
-  }
-  if (
-    mutable.name.startsWith(LANGGRAPH_TOOL_NODE_PREFIX) ||
-    mutable.name === TOOL_BATCH_RUN_NAME
-  ) {
+    shapeAgentNodeSpan(mutable);
+  } else if (mutable.name.startsWith(LANGGRAPH_TOOL_NODE_PREFIX)) {
     shapeToolNodeSpan(mutable);
-    return;
+  } else if (isGenerationSpan(mutable)) {
+    mutable.name = GENERATION_SPAN_NAME;
   }
-  if (isRootSpan(span)) {
-    shapeRootSpan(mutable);
+  if (!isRootSpan(span)) {
+    return;
   }
+  shapeRootObservationType(mutable);
+  shapeRootSpan(mutable);
 }