@librechat/agents 3.7.9 → 3.7.11

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

@@ -24,7 +24,7 @@ export declare function resolveSearchOutcome(data: t.SearchResultData, query: st
  * Executes parallel searches and merges the results,
  * deduplicating top stories by link
  */
-export declare function executeParallelSearches({ searchAPI, query, date, country, safeSearch, images, videos, news, logger, }: {
+export declare function executeParallelSearches({ searchAPI, query, date, country, safeSearch, images, videos, news, logger, provider, metrics, }: {
     searchAPI: ReturnType<typeof createSearchAPI>;
     query: string;
     date?: DATE_RANGE;
@@ -34,5 +34,11 @@ export declare function executeParallelSearches({ searchAPI, query, date, countr
     videos: boolean;
     news: boolean;
     logger: t.Logger;
+    /** Labels the provider in the run summary. Optional so the pre-existing
+     * call contract still holds for callers outside this package. */
+    provider?: string;
+    /** Collector owned by the caller. Without one, this call opens and flushes
+     * its own, so a direct caller still gets the single summary line. */
+    metrics?: t.SearchMetrics;
 }): Promise<t.SearchResult>;
 export declare const createSearchTool: (config?: t.SearchToolConfig) => DynamicStructuredTool;

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

@@ -291,7 +291,9 @@ export interface JinaRerankerResult {
 }
 export interface JinaRerankerResponse {
     model: string;
-    usage: {
+    /** Telemetry only, and absent from some Jina-compatible endpoints — never
+     * dereference it on a path that would discard a usable ranking. */
+    usage?: {
         total_tokens: number;
     };
     results: JinaRerankerResult[];
@@ -303,12 +305,13 @@ export interface CohereRerankerResult {
 export interface CohereRerankerResponse {
     results: CohereRerankerResult[];
     id: string;
-    meta: {
-        api_version: {
+    /** Telemetry only; see {@link JinaRerankerResponse.usage}. */
+    meta?: {
+        api_version?: {
             version: string;
             is_experimental: boolean;
         };
-        billed_units: {
+        billed_units?: {
             search_units: number;
         };
     };
@@ -343,6 +346,81 @@ export interface RagApiRerankResponse {
 }
 export type SafeSearchLevel = 0 | 1 | 2;
 export type Logger = WinstonLogger;
+/** Compact, redacted view of a thrown error, safe to hand to a logger. */
+export interface SafeErrorLog {
+    message: string;
+    name?: string;
+    code?: string;
+    status?: number;
+    method?: string;
+    url?: string;
+    responseDataSummary?: string;
+    value?: string;
+}
+/** Why a rerank returned the candidates' original order instead of a ranking. */
+export type RerankFallback = 'no_api_key' | 'no_base_url' | 'no_token_supplier' | 'bad_response' | 'invalid_results' | 'chunk_error' | 'placeholder' | 'error';
+/** One provider query. `results` is the row count that query contributed. */
+export interface SearchObservation {
+    provider: string;
+    type: string;
+    results: number;
+    durationMs: number;
+    error?: string;
+    /** The query rejected rather than reporting failure in its response. Those
+     * were logged at error level before they were aggregated, so the summary
+     * has to carry the distinction to keep that severity. */
+    thrown?: boolean;
+}
+/** One scraped link. A failure carries `error`; a success carries the sizes
+ * the scrape produced, so the summary can report both without a second pass. */
+export interface ScrapeObservation {
+    url: string;
+    chars?: number;
+    highlights?: number;
+    error?: string;
+}
+/** One reranker round trip. A search reranks once per scraped source, so
+ * these fold into a single summary rather than logging per source. */
+export interface RerankObservation {
+    provider: string;
+    chunks: number;
+    results: number;
+    durationMs: number;
+    model?: string;
+    /** Provider-reported usage: Jina tokens, Cohere billed search units. */
+    units?: number;
+    /** Chunks a provider candidate cap dropped before submission. */
+    dropped?: number;
+    /** Set only when a provider cap reduced the requested result count, so a
+     * search returning fewer highlights than configured says why. */
+    topK?: number;
+    topKLimit?: number;
+    reason?: RerankFallback;
+    error?: SafeErrorLog;
+}
+/** Per-rerank state threaded from the start of a call to whichever exit it
+ * takes, so every path records exactly one observation. */
+export interface RerankRun {
+    metrics: SearchMetrics;
+    documents: string[];
+    topK: number;
+    startedAt: number;
+    model?: string;
+    units?: number;
+    dropped?: number;
+    topKLimit?: number;
+}
+/**
+ * Fold-as-you-go counters for one `web_search` call. Recording is O(1) and
+ * allocation-free past a bounded reason map; {@link SearchMetrics.flush}
+ * emits at most one line per phase that actually ran.
+ */
+export interface SearchMetrics {
+    recordSearch(observation: SearchObservation): void;
+    recordScrape(observation: ScrapeObservation): void;
+    recordRerank(observation: RerankObservation): void;
+    flush(): void;
+}
 export interface SearchToolConfig extends SearchConfig, ProcessSourcesConfig, FirecrawlConfig {
     tavilyScraperOptions?: TavilyScraperConfig;
     crwScraperOptions?: CrwScraperConfig;
@@ -572,6 +650,9 @@ export interface FirecrawlScraperConfig extends BaseSearchProviderConfig {
     onlyMainContent?: boolean;
     changeTrackingOptions?: object;
 }
+/** Result kind a parallel sub-search covers; `web` is the untyped main
+ * search, which every provider serves without a `type` parameter. */
+export type SubSearchType = 'web' | 'images' | 'videos' | 'news';
 export type GetSourcesParams = {
     query: string;
     date?: DATE_RANGE;
@@ -870,6 +951,9 @@ export type ProcessSourcesFields = {
     news: boolean;
     proMode: boolean;
     onGetHighlights: SearchToolConfig['onGetHighlights'];
+    /** Collector owned by the caller; when omitted, one is created and flushed
+     * for this call so a direct `processSources` still summarizes itself. */
+    metrics?: SearchMetrics;
 };
 export interface SearchToolSchema {
     type: 'object';

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

@@ -1,14 +1,6 @@
+import type { SafeErrorLog } from './types';
 import type * as t from './types';
-export interface SafeErrorLog {
-    message: string;
-    name?: string;
-    code?: string;
-    status?: number;
-    method?: string;
-    url?: string;
-    responseDataSummary?: string;
-    value?: string;
-}
+export type { SafeErrorLog } from './types';
 /**
  * Creates a default logger that maps to console methods
  * Uses a singleton pattern to avoid creating multiple instances

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

@@ -131,6 +131,11 @@ export type ToolNodeOptions = {
     /** ID of the agent that owns this tool node, surfaced to hooks as `executingAgentId`
      * so a batch can be attributed to a specific agent even where `agentId` is undefined. */
     executingAgentId?: string;
+    /** Name of the agent that owns this tool node, used for active Langfuse attribution. */
+    executingAgentName?: string;
+    /** Root graph-agent identity retained alongside the currently executing tool owner. */
+    rootAgentId?: string;
+    rootAgentName?: string;
     /** Tool names that must be executed directly (via runTool) even in event-driven mode (e.g., graph-managed handoff tools) */
     directToolNames?: Set<string>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.7.9",
+  "version": "3.7.11",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"

package/src/graphs/Graph.ts

@@ -2620,6 +2620,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         // run_id); `executingAgentId` always identifies the owning agent.
         agentId: this.subagentScope ? agentContext?.agentId : undefined,
         executingAgentId: agentContext?.agentId,
+        executingAgentName: agentContext?.name,
+        rootAgentId: this.defaultAgentId,
+        rootAgentName: this.agentContexts.get(this.defaultAgentId)?.name,
         toolCallStepIds: this.toolCallStepIds,
         toolRegistry: agentContext?.toolRegistry,
         getDiscoveredToolNames: (): readonly string[] =>
@@ -2697,6 +2700,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       // hooks can attribute the batch even at the top level.
       agentId: this.subagentScope ? agentContext?.agentId : undefined,
       executingAgentId: agentContext?.agentId,
+      executingAgentName: agentContext?.name,
+      rootAgentId: this.defaultAgentId,
+      rootAgentName: this.agentContexts.get(this.defaultAgentId)?.name,
       toolCallStepIds: this.toolCallStepIds,
       errorHandler: (data, metadata): Promise<boolean> =>
         StandardGraph.handleToolCallErrorStatic(this, data, metadata),
@@ -3815,6 +3821,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         parentMessageId: config.configurable?.requestBody?.parentMessageId,
         agentId,
         agentName: agentContext.name,
+        rootAgentId: this.defaultAgentId,
+        rootAgentName: this.agentContexts.get(this.defaultAgentId)?.name,
+        activeAgentId: agentId,
+        activeAgentName: agentContext.name,
       });
       let langfuseHandler: CallbackEntry | undefined;
       let invokeConfig = {

package/src/graphs/MultiAgentGraph.ts

@@ -101,6 +101,14 @@ function isTransferToolName(name: unknown): boolean {
   );
 }
 
+function graphToolName(tool: unknown): string | undefined {
+  if (tool == null || typeof tool !== 'object' || !('name' in tool)) {
+    return undefined;
+  }
+  const { name } = tool;
+  return typeof name === 'string' ? name : undefined;
+}
+
 /**
  * Drop transfer `tool_use` content blocks from an AI message's array content.
  * Companion to the reception's tool-call filtering: array-content providers
@@ -287,6 +295,21 @@ function withHandoffGroupMetadata(
   };
 }
 
+function withActiveAgentMetadata(
+  config: LangGraphRunnableConfig | undefined,
+  agentId: string,
+  agentName: string | undefined
+): LangGraphRunnableConfig {
+  return {
+    ...config,
+    metadata: {
+      ...config?.metadata,
+      activeAgentId: agentId,
+      ...(agentName == null ? {} : { activeAgentName: agentName }),
+    },
+  };
+}
+
 /**
  * MultiAgentGraph extends StandardGraph to support dynamic multi-agent workflows
  * with handoffs, fan-in/fan-out, and other composable patterns.
@@ -594,6 +617,24 @@ export class MultiAgentGraph extends StandardGraph {
   private createHandoffTools(): void {
     // Group handoff edges by source agent(s)
     const handoffsByAgent = new Map<string, t.GraphEdge[]>();
+    const tokenAccountingRefresh = new Set<string>();
+
+    /** Transfer tool names are SDK-reserved. Remove externally supplied or
+     * stale transfer tools before deriving the source agent's allowed set
+     * from the graph edges below. */
+    for (const agentContext of this.agentContexts.values()) {
+      const originalTools = agentContext.graphTools;
+      const retainedTools = agentContext.graphTools?.filter(
+        (graphTool) => !isTransferToolName(graphToolName(graphTool))
+      );
+      if (retainedTools?.length !== originalTools?.length) {
+        tokenAccountingRefresh.add(agentContext.agentId);
+      }
+      agentContext.graphTools =
+        retainedTools != null && retainedTools.length > 0
+          ? retainedTools
+          : undefined;
+    }
 
     // Only process handoff edges for tool creation
     for (const edge of this.handoffEdges) {
@@ -643,6 +684,29 @@ export class MultiAgentGraph extends StandardGraph {
       for (const handoffTool of handoffTools) {
         agentContext.graphTools.push(handoffTool);
       }
+      if (handoffTools.length > 0) {
+        tokenAccountingRefresh.add(agentId);
+      }
+    }
+
+    for (const agentId of tokenAccountingRefresh) {
+      const agentContext = this.agentContexts.get(agentId);
+      if (agentContext?.tokenCounter == null) {
+        continue;
+      }
+      const { tokenCounter, baseIndexTokenCountMap } = agentContext;
+      agentContext.tokenCalculationPromise = agentContext
+        .calculateInstructionTokens(tokenCounter)
+        .then(() => {
+          agentContext.updateTokenMapWithInstructions(baseIndexTokenCountMap);
+        })
+        .catch((err) => {
+          // eslint-disable-next-line no-console
+          console.error(
+            'Error recalculating instruction tokens after handoff tool updates:',
+            err
+          );
+        });
     }
   }
 
@@ -1239,10 +1303,16 @@ export class MultiAgentGraph extends StandardGraph {
       ): Promise<t.MultiAgentGraphState | Command> => {
         let result: t.MultiAgentGraphState;
         let inputMessages = state.messages;
-        const memberConfig =
+        const agentContext = this.agentContexts.get(agentId);
+        const recursionLimitedConfig =
           this.memberRecursionLimit == null
             ? config
             : { ...config, recursionLimit: this.memberRecursionLimit };
+        const memberConfig = withActiveAgentMetadata(
+          recursionLimitedConfig,
+          agentId,
+          agentContext?.name
+        );
 
         /**
          * Check if this agent is receiving a handoff.
@@ -1254,7 +1324,6 @@ export class MultiAgentGraph extends StandardGraph {
           state.messages,
           agentId
         );
-        const agentContext = this.agentContexts.get(agentId);
 
         if (
           handoffContext?.sourceAgentName != null &&

package/src/langfuse.ts

@@ -783,17 +783,29 @@ export function createLangfuseTraceMetadata({
   parentMessageId,
   agentId,
   agentName,
+  rootAgentId,
+  rootAgentName,
+  activeAgentId,
+  activeAgentName,
 }: {
   messageId?: unknown;
   parentMessageId?: unknown;
   agentId?: unknown;
   agentName?: unknown;
+  rootAgentId?: unknown;
+  rootAgentName?: unknown;
+  activeAgentId?: unknown;
+  activeAgentName?: unknown;
 }): LangfuseTraceMetadata {
   return createTraceMetadata({
     messageId,
     parentMessageId,
     agentId,
     agentName,
+    rootAgentId,
+    rootAgentName,
+    activeAgentId,
+    activeAgentName,
   });
 }
 

package/src/run.ts

@@ -1311,6 +1311,10 @@ export class Run<_T extends t.BaseGraphState> {
       parentMessageId: config.configurable?.requestBody?.parentMessageId,
       agentId: graph.defaultAgentId,
       agentName: primaryContext?.name,
+      rootAgentId: graph.defaultAgentId,
+      rootAgentName: primaryContext?.name,
+      activeAgentId: graph.defaultAgentId,
+      activeAgentName: primaryContext?.name,
     });
     const traceName = config.runName ?? getLangfuseTraceName(traceMetadata);
     const streamLangfuseConfig = this.getStreamLangfuseConfig(graph);

package/src/tools/ToolNode.ts

@@ -738,6 +738,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
    * even where `agentId` (the subagent-scope marker) is undefined.
    */
   private executingAgentId?: string;
+  private executingAgentName?: string;
+  private rootAgentId?: string;
+  private rootAgentName?: string;
   /** Tool names that bypass event dispatch and execute directly (e.g., graph-managed handoff tools) */
   private directToolNames?: Set<string>;
   /**
@@ -823,6 +826,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     eagerEventToolSuppressions,
     agentId,
     executingAgentId,
+    executingAgentName,
+    rootAgentId,
+    rootAgentName,
     directToolNames,
     interruptingToolNames,
     codeSessionToolNames,
@@ -902,6 +908,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     // Default to agentId so callers constructing ToolNode directly (who pass the
     // existing agentId option) still get attribution without knowing the new option.
     this.executingAgentId = executingAgentId ?? agentId;
+    this.executingAgentName = executingAgentName;
+    this.rootAgentId = rootAgentId;
+    this.rootAgentName = rootAgentName;
     this.directToolNames = directToolNames;
     this.interruptingToolNames =
       interruptingToolNames != null && interruptingToolNames.size > 0
@@ -963,6 +972,16 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           metadata: {
             ...options?.metadata,
             agentId: this.executingAgentId,
+            activeAgentId: this.executingAgentId,
+            ...(this.executingAgentName == null
+              ? {}
+              : { activeAgentName: this.executingAgentName }),
+            ...(this.rootAgentId == null
+              ? {}
+              : { rootAgentId: this.rootAgentId }),
+            ...(this.rootAgentName == null
+              ? {}
+              : { rootAgentName: this.rootAgentName }),
           },
         };
     return withLangfuseRuntimeScope(