@librechat/agents 3.7.21 → 3.7.22

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

@@ -3,6 +3,7 @@ import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type { MessageContentComplex, RunStepResumeState, ToolErrorData } from './stream';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
+import type { PreparedSubagents } from '@/tools/preparedSubagents';
 import type { RunBreakerScope } from '@/llm/streamLimits';
 import type { HumanInTheLoopConfig } from './hitl';
 import type { LangfuseConfig } from './graph';
@@ -42,6 +43,13 @@ export type EagerEventToolExecutionConfig = {
      * execution with final args.
      */
     excludeToolNames?: string[];
+    /**
+     * Maximum retained early foreground subagent invocations per graph. Defaults
+     * to 4; 0 disables them. Checkpoints, parent tool hooks, background calls and
+     * control-flow graph tools retain normal batch execution. Once a child has
+     * started, a failed/revised model attempt fails instead of automatically retrying.
+     */
+    maxPendingSubagents?: number;
 };
 export type EagerEventToolExecutionOutcome = {
     results: ToolExecuteResult[];
@@ -273,6 +281,8 @@ export type ToolNodeOptions = {
      * controller.
      */
     getRunScope?: () => RunBreakerScope;
+    /** Internal graph-owned prepared invocation registry. */
+    preparedSubagents?: PreparedSubagents;
     /** SDK-owned checkpoint bridge for open run-step lifecycle state. */
     restoreRunStepResumeState?: (state?: RunStepResumeState, config?: RunnableConfig) => void;
     /** SDK-owned checkpoint snapshot for open run-step lifecycle state. */
@@ -1160,6 +1170,13 @@ export type ToolSearchArtifact = {
         total_searched: number;
         pattern: string;
         error?: string;
+        /** Servers that had tools to search, emitted when a server filter matched
+         * nothing so the caller can see what it could have asked for. */
+        available_mcp_servers?: string[];
+        /** Requested servers that matched no registered server. */
+        unmatched_mcp_servers?: string[];
+        /** Requested servers that exist but had no tools left to search. */
+        idle_mcp_servers?: string[];
     };
 };
 /**

package/package.json

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

package/src/graphs/Graph.ts

@@ -146,6 +146,7 @@ import {
   findCallback,
   type CallbackEntry,
 } from '@/utils/callbacks';
+import { PreparedSubagents, PreparedSubagentError } from '@/tools/preparedSubagents';
 import { ToolNode as CustomToolNode, toolsCondition } from '@/tools/ToolNode';
 import { shouldTraceToolNodeForLangfuse } from '@/langfuseToolOutputTracing';
 import { createLocalCodingToolBundle } from '@/tools/local/LocalCodingTools';
@@ -898,6 +899,7 @@ export abstract class Graph<
    * Call after a run completes and content has been extracted.
    */
   clearHeavyState(): void {
+    this.preparedSubagents.clear();
     this.config = undefined;
     this.signal = undefined;
     this.callerSignal = undefined;
@@ -1239,6 +1241,8 @@ export abstract class Graph<
     restoreSubagentResumeState(state: SubagentToolNodeResumeState): void;
   }> = new Set();
   private _subagentExecutors = new Set<SubagentExecutor>();
+  readonly preparedSubagents = new PreparedSubagents();
+  protected readonly subagentToolNodes = new Map<string, CustomToolNode<t.BaseGraphState>>();
   public getOrCreateFileCheckpointer(): t.LocalFileCheckpointer | undefined {
     // Return the cached instance unconditionally if one exists. The
     // toolExecution check below decides whether to *create* a new
@@ -1397,16 +1401,16 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
    * paths must not run in that state. */
   protected resolveTrippedBreakerReason(
     breakerSignal: AbortSignal = this.breakerAbort.signal
-  ): StreamLimitExceededError | undefined {
+  ): StreamLimitExceededError | PreparedSubagentError | undefined {
     if (
       breakerSignal.aborted &&
-      breakerSignal.reason instanceof StreamLimitExceededError
+      (breakerSignal.reason instanceof StreamLimitExceededError || breakerSignal.reason instanceof PreparedSubagentError)
     ) {
       return breakerSignal.reason;
     }
     if (
       this.signal?.aborted === true &&
-      this.signal.reason instanceof StreamLimitExceededError
+      (this.signal.reason instanceof StreamLimitExceededError || this.signal.reason instanceof PreparedSubagentError)
     ) {
       return this.signal.reason;
     }
@@ -1581,6 +1585,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   /* Init */
 
   resetValues(keepContent?: boolean, checkpointScope?: string): void {
+    this.preparedSubagents.clear();
     this.resetSubagentCheckpointThreadIds();
     this.messages = [];
     this.hasRestoredCheckpointMessages = false;
@@ -2717,6 +2722,49 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
 
   /* Graph */
 
+  canPrestartSubagents(agentContext?: AgentContext): boolean {
+    if (
+      this.eagerEventToolExecution?.enabled !== true ||
+      (this.eagerEventToolExecution.maxPendingSubagents ?? 4) <= 0 ||
+      this.compileOptions?.checkpointer != null ||
+      this.humanInTheLoop?.enabled === true ||
+      (this.interruptingToolNames?.length ?? 0) > 0 ||
+      agentContext == null ||
+      !this.subagentToolNodes.has(agentContext.agentId)
+    ) {
+      return false;
+    }
+    const graphTools = agentContext.graphTools as t.GenericTool[] | undefined;
+    return (
+      graphTools?.length === 1 &&
+      graphTools[0].name === Constants.SUBAGENT &&
+      SUBAGENT_REPLAY_CONTROLLER in graphTools[0]
+    );
+  }
+
+  prestartSubagent(
+    call: ToolCall,
+    attempt: string,
+    agentContext?: AgentContext
+  ): void {
+    const config = this.preparedSubagents.getConfig(attempt);
+    if (
+      !this.canPrestartSubagents(agentContext) ||
+      config == null ||
+      agentContext == null
+    ) {
+      return;
+    }
+    this.subagentToolNodes
+      .get(agentContext.agentId)
+      ?.prestartSubagent(
+        call,
+        attempt,
+        config,
+        this.eagerEventToolExecution?.maxPendingSubagents ?? 4
+      );
+  }
+
   initializeTools({
     currentTools,
     currentToolMap,
@@ -2791,6 +2839,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         hookRegistry: this.hookRegistry,
         humanInTheLoop: this.humanInTheLoop,
         eagerEventToolExecution: this.eagerEventToolExecution,
+        preparedSubagents: this.preparedSubagents,
         codeSessionToolNames: this.codeSessionToolNames,
         eagerEventToolExecutions: this.eagerEventToolExecutions,
         eagerEventToolUsageCount: this.getEagerEventToolUsageCount(
@@ -2816,6 +2865,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           StandardGraph.handleToolCallErrorStatic(this, data, metadata),
       });
       this.registerCompiledToolNode(node);
+      if (agentContext != null) {
+        this.subagentToolNodes.set(agentContext.agentId, node);
+      }
       return node;
     }
 
@@ -4092,7 +4144,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
          * succeeding fallback would resolve a run the public contract says
          * must reject. Rethrow before any recovery path.
          */
-        if (primaryError instanceof StreamLimitExceededError) {
+        if (
+          primaryError instanceof StreamLimitExceededError ||
+          primaryError instanceof PreparedSubagentError
+        ) {
           /** Tripped before rethrowing so parallel agent nodes' in-flight
            * model calls and subagents stop while the rejection propagates. */
           attemptBreaker.abort(primaryError);
@@ -4342,7 +4397,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               })
           );
         } catch (fallbackError) {
-          if (fallbackError instanceof StreamLimitExceededError) {
+          if (
+            fallbackError instanceof StreamLimitExceededError ||
+            fallbackError instanceof PreparedSubagentError
+          ) {
             /** Same treatment as the primary path: a fallback stream that
              * trips the breaker must stop parallel agent nodes' model calls
              * and subagents before the rejection propagates. */

package/src/llm/invoke.ts

@@ -51,6 +51,7 @@ import {
 } from '@/llm/providers';
 import { ChatModelStreamHandler, dispatchesChatModelStream } from '@/stream';
 import { Constants, ContentTypes, GraphEvents, Providers } from '@/common';
+import { PreparedSubagentError } from '@/tools/preparedSubagents';
 import { assertNotTruncatedToolCall } from '@/llm/truncation';
 import { resolveClientOptionsModel } from '@/llm/request';
 import { safeDispatchCustomEvent } from '@/utils/events';
@@ -702,9 +703,8 @@ export async function attemptInvoke(
     },
   };
   const request = resolveAttemptRequest(params, providerStampedConfig);
-  const configuredModel = providerStampedConfig.metadata?.[
-    Constants.INVOKED_MODEL
-  ];
+  const configuredModel =
+    providerStampedConfig.metadata?.[Constants.INVOKED_MODEL];
   const modelId =
     request.modelId ??
     (typeof configuredModel === 'string' ? configuredModel : undefined);
@@ -745,8 +745,14 @@ export async function attemptInvoke(
   if (leaseTarget != null && generationKey != null) {
     registerActiveStreamLimitGeneration(leaseTarget, generationKey);
   }
+  const prepared =
+    params.context?.eagerEventToolExecution?.enabled === true
+      ? params.context.preparedSubagents
+      : undefined;
+  const preparedAttempt = resolveGenerationKey(stampedConfig.metadata);
+  prepared?.begin(preparedAttempt, stampedConfig);
   try {
-    return await attemptInvokeBody(
+    const result = await attemptInvokeBody(
       {
         request,
         context: params.context,
@@ -755,7 +761,27 @@ export async function attemptInvoke(
       },
       stampedConfig
     );
+    const calls =
+      result.messages?.flatMap((message) =>
+        'tool_calls' in message
+          ? ((message.tool_calls as ToolCall[] | undefined) ?? [])
+          : []
+      ) ?? [];
+    prepared?.finish(preparedAttempt, calls);
+    return result;
+  } catch (error) {
+    prepared?.finish(preparedAttempt, undefined, error);
+    throw error;
   } finally {
+    const chunks = params.context?.eagerEventToolCallChunks;
+    if (prepared != null && chunks != null) {
+      const prefix = `prepared:${preparedAttempt}\u0000`;
+      for (const key of chunks.keys()) {
+        if (key.startsWith(prefix)) {
+          chunks.delete(key);
+        }
+      }
+    }
     if (leaseTarget != null && generationKey != null) {
       releaseStreamLimitGeneration(leaseTarget, generationKey);
     }
@@ -1053,7 +1079,7 @@ async function attemptInvokeBody(
       const signal = config.signal;
       if (
         signal?.aborted === true &&
-        signal.reason instanceof StreamLimitExceededError
+        (signal.reason instanceof StreamLimitExceededError || signal.reason instanceof PreparedSubagentError)
       ) {
         throw signal.reason;
       }
@@ -1290,6 +1316,7 @@ async function attemptInvokeBody(
       const ownAbort =
         restartRoute === 'aborted' &&
         !(error instanceof StreamLimitExceededError) &&
+        !(error instanceof PreparedSubagentError) &&
         config.signal?.aborted !== true;
       if (!ownAbort) {
         throw error;
@@ -1639,7 +1666,7 @@ export async function tryFallbackProviders({
        * a run that must reject. Check before every fallback invocation. */
       if (
         config?.signal?.aborted === true &&
-        config.signal.reason instanceof StreamLimitExceededError
+        (config.signal.reason instanceof StreamLimitExceededError || config.signal.reason instanceof PreparedSubagentError)
       ) {
         throw config.signal.reason;
       }
@@ -1673,7 +1700,7 @@ export async function tryFallbackProviders({
        * provider failure. Continuing would try the remaining fallbacks and a
        * succeeding one would resolve a run that must reject.
        */
-      if (e instanceof StreamLimitExceededError) {
+      if (e instanceof StreamLimitExceededError || e instanceof PreparedSubagentError) {
         throw e;
       }
       /** A parallel sibling's trip aborts this branch's composed signal, and
@@ -1682,7 +1709,7 @@ export async function tryFallbackProviders({
        * abort. Rethrow the breaker's own reason instead. */
       if (
         config?.signal?.aborted === true &&
-        config.signal.reason instanceof StreamLimitExceededError
+        (config.signal.reason instanceof StreamLimitExceededError || config.signal.reason instanceof PreparedSubagentError)
       ) {
         throw config.signal.reason;
       }

package/src/stream.ts

@@ -15,6 +15,7 @@ import {
   requiresStreamLimitAccounting,
   StreamLimitExceededError,
   STREAM_LIMIT_EPOCH_KEY,
+  resolveGenerationKey,
 } from '@/llm/streamLimits';
 import {
   getStreamedToolCallSeal,
@@ -56,6 +57,7 @@ import {
 } from '@/utils/truncation';
 import { resolveToolOutcome, outcomeFieldsFromResult } from '@/tools/intentArg';
 import { TOOL_OUTPUT_REF_PATTERN } from '@/tools/toolOutputReferences';
+import { PreparedSubagentError } from '@/tools/preparedSubagents';
 import { isReasoningContentBlock } from '@/messages/core';
 import { safeDispatchCustomEvent } from '@/utils/events';
 import { composeAbortSignals } from '@/utils/misc';
@@ -1319,6 +1321,65 @@ function startReadyStreamedEagerToolExecutions(args: {
   });
 }
 
+/** Shares provider sealing/parsing with event tools, but never relaxes their batch guard. */
+function startPreparedSubagents(
+  graph: StandardGraph,
+  agentContext: AgentContext | undefined,
+  chunk: Partial<AIMessageChunk>,
+  metadata?: Record<string, unknown>
+): void {
+  const attempt = resolveGenerationKey(metadata);
+  if (
+    (graph as Partial<StandardGraph>).canPrestartSubagents?.(agentContext) !==
+      true ||
+    graph.preparedSubagents.isOpen(attempt) !== true ||
+    graph.hookRegistry?.hasResultAlteringHooks(
+      graph.preparedSubagents.getConfig(attempt)?.configurable?.run_id
+    ) === true
+  ) {
+    return;
+  }
+  let calls: ToolCall[];
+  if (hasOnArrivalToolCallSeal(chunk) && (chunk.tool_calls?.length ?? 0) > 0) {
+    calls = chunk.tool_calls!;
+  } else {
+    const seal = getStreamedToolCallSeal(chunk.response_metadata);
+    const allowSequentialSeal =
+      canPrestartSequentialStreamedToolChunks(agentContext) ||
+      streamedToolCallAdapterAllowsSequentialSeal(chunk.response_metadata);
+    if (!hasExplicitStreamedToolCallSeals(chunk) && !allowSequentialSeal) {
+      return;
+    }
+    const stepKey = `prepared:${attempt}`;
+    recordEagerToolCallChunks({
+      graph,
+      stepKey,
+      toolCallChunks: chunk.tool_call_chunks ?? [],
+      seal,
+    });
+    calls = getStreamedReadyToolCalls({
+      graph,
+      stepKey,
+      toolCallChunks: chunk.tool_call_chunks,
+      seal,
+      allowSequentialSeal,
+    });
+    pruneEagerToolCallChunkStates({
+      graph,
+      stepKey,
+      toolCallIds: new Set(calls.map((call) => call.id!)),
+    });
+  }
+  for (const call of calls) {
+    if (
+      call.name === Constants.SUBAGENT &&
+      !hasToolOutputReference(call.args)
+    ) {
+      graph.prestartSubagent(call, attempt, agentContext);
+    }
+  }
+}
+
 export function getChunkContent({
   chunk,
   provider,
@@ -1597,7 +1658,7 @@ export class ChatModelStreamHandler implements t.EventHandler {
       if (
         eventBreaker != null &&
         eventBreaker.signal.aborted &&
-        eventBreaker.signal.reason instanceof StreamLimitExceededError
+        (eventBreaker.signal.reason instanceof StreamLimitExceededError || eventBreaker.signal.reason instanceof PreparedSubagentError)
       ) {
         throw eventBreaker.signal.reason;
       }
@@ -1743,6 +1804,9 @@ export class ChatModelStreamHandler implements t.EventHandler {
         return;
       }
       throwIfRunBreakerTripped();
+      if (hasOnArrivalToolCallSeal(chunk)) {
+        startPreparedSubagents(graph, agentContext, chunk, metadata);
+      }
       if (hasFinalToolCallSignal(chunk)) {
         startEagerToolExecutions({
           graph,
@@ -1839,6 +1903,11 @@ export class ChatModelStreamHandler implements t.EventHandler {
       }
     }
 
+    if (!hasOnArrivalToolCallSeal(chunk) && !runScopeInvalidated()) {
+      throwIfRunBreakerTripped();
+      startPreparedSubagents(graph, agentContext, chunk, metadata);
+    }
+
     if (isEmptyContent) {
       return;
     }