@librechat/agents 3.7.20 → 3.7.22

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;
     }

package/src/tools/BashExecutor.ts

@@ -18,6 +18,7 @@ import {
   resolveCodeApiAuthHeaders,
   selectRuntimeSessionHint,
 } from './CodeExecutor';
+import { logCodeApiDiagnostic } from '@/tools/diagnostics';
 import { resolveFetchProxyAgent } from '@/utils/proxy';
 import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
@@ -249,9 +250,11 @@ function createBashExecutionTool(
         session_id.length > 0 &&
         !Array.isArray(postData.files)
       ) {
-        // eslint-disable-next-line no-console
-        console.debug(
-          `[BashExecutor] No injected files for session_id=${session_id} — exec will run without input files`
+        logCodeApiDiagnostic(
+          'BashExecutor',
+          'debug',
+          'session carried no injected files; exec will run without input files',
+          { files: 'none' }
         );
       }
 
@@ -278,7 +281,9 @@ function createBashExecutionTool(
         const response = await fetch(execEndpoint, fetchOptions);
         if (!response.ok) {
           throw new CodeApiRequestError(
-            await buildCodeApiHttpErrorMessage('POST', execEndpoint, response)
+            await buildCodeApiHttpErrorMessage('POST', execEndpoint, response, {
+              profile: executionProfile,
+            })
           );
         }
 

package/src/tools/BashProgrammaticToolCalling.ts

@@ -31,6 +31,7 @@ import {
   runPlainExecution,
   formatCompletedResponse,
 } from './ProgrammaticToolCalling';
+import { logCodeApiDiagnostic } from '@/tools/diagnostics';
 import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
 
@@ -423,9 +424,11 @@ export function createBashProgrammaticToolCallingTool(
         if (_injected_files && _injected_files.length > 0) {
           files = _injected_files;
         } else if (session_id != null && session_id.length > 0) {
-          // eslint-disable-next-line no-console
-          console.debug(
-            `[BashProgrammaticToolCalling] No injected files for session_id=${session_id} — exec will run without input files`
+          logCodeApiDiagnostic(
+            'BashProgrammaticToolCalling',
+            'debug',
+            'session carried no injected files; exec will run without input files',
+            { files: 'none' }
           );
         }
 

package/src/tools/CodeExecutor.ts

@@ -2,7 +2,13 @@ import { config } from 'dotenv';
 import fetch, { RequestInit } from 'node-fetch';
 import { getEnvironmentVariable } from '@langchain/core/utils/env';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
+import type { Readable } from 'node:stream';
+import type { CodeApiMethod } from '@/tools/diagnostics';
 import type * as t from '@/types';
+import {
+  describeCodeApiError,
+  logCodeApiDiagnostic,
+} from '@/tools/diagnostics';
 import { appendCodeSessionFileSummary } from '@/tools/CodeSessionFileSummary';
 import { resolveFetchProxyAgent } from '@/utils/proxy';
 import { INTENT_PROPERTY } from '@/tools/intentArg';
@@ -119,8 +125,7 @@ export const CodeExecutionToolSchema = {
   required: ['lang', 'code'],
 } as const;
 
-export const CODE_API_EXPECTED_PROFILE_HEADER =
-  'X-CodeAPI-Expected-Profile';
+export const CODE_API_EXPECTED_PROFILE_HEADER = 'X-CodeAPI-Expected-Profile';
 
 type SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];
 
@@ -221,7 +226,8 @@ export function buildCodeApiExecutionErrorMessage(response: {
 }
 
 export async function resolveCodeApiAuthHeaders(
-  authHeaders?: t.CodeApiAuthHeaders
+  authHeaders?: t.CodeApiAuthHeaders,
+  options?: { recoverable?: boolean }
 ): Promise<t.CodeApiAuthHeaderMap> {
   if (authHeaders == null) {
     return {};
@@ -230,7 +236,15 @@ export async function resolveCodeApiAuthHeaders(
     try {
       const resolvedHeaders = await authHeaders();
       return resolvedHeaders;
-    } catch {
+    } catch (error) {
+      if (options?.recoverable !== true) {
+        logCodeApiDiagnostic(
+          'CodeExecutor',
+          'error',
+          'auth header resolution failed; the Code API request was never sent',
+          describeCodeApiError(error)
+        );
+      }
       throw new CodeApiRequestError(CODE_API_AUTHORIZATION_ERROR_MESSAGE);
     }
   }
@@ -250,18 +264,73 @@ export function addCodeApiExecutionProfileHeader(
   };
 }
 
+type CodeApiErrorResponse = {
+  status: number;
+  text: () => Promise<string>;
+  /** node-fetch types this as `NodeJS.ReadableStream`, which does not declare
+   * `destroy`; every runtime instance is a `Readable`, and a test double may
+   * supply nothing at all. */
+  body?: NodeJS.ReadableStream | null;
+};
+
+/**
+ * Only the 429 branch reads the body, and node-fetch keeps the stream and its
+ * socket alive until something does. Repeated backend failures would otherwise
+ * accumulate connections holding payloads this module deliberately discards.
+ */
+function discardResponseBody(response: CodeApiErrorResponse): void {
+  const body = response.body;
+  if (body == null || !('destroy' in body)) {
+    return;
+  }
+  const destroy = (body as NodeJS.ReadableStream & Partial<Readable>).destroy;
+  if (typeof destroy !== 'function') {
+    return;
+  }
+  try {
+    destroy.call(body);
+  } catch {
+    /* Already finished or not destroyable; nothing is being held open. */
+  }
+}
+
 export async function buildCodeApiHttpErrorMessage(
-  _method: string,
+  method: CodeApiMethod,
   _endpoint: string,
-  response: { status: number; text: () => Promise<string> }
+  response: CodeApiErrorResponse,
+  options?: { recoverable?: boolean; profile?: t.CodeApiExecutionProfile }
 ): Promise<string> {
-  let responseBody = '';
-  try {
-    responseBody = await response.text();
-  } catch {
-    responseBody = '';
+  /* Logged before the body is touched. A non-OK response can leave a chunked
+     body open, and there is no read timeout here, so draining first would
+     withhold the diagnostic indefinitely for exactly the backend it identifies.
+     The body itself is never logged — it is upstream free text that can echo
+     the header that was sent — and the endpoint is host-configured, so the
+     backend is named by the profile this module chose rather than by its
+     address. A recoverable caller reports its own outcome; logging here too
+     would raise an error-level alert for a lookup that succeeds by returning
+     nothing. */
+  if (options?.recoverable !== true) {
+    logCodeApiDiagnostic(
+      'CodeExecutor',
+      response.status === 429 ? 'warn' : 'error',
+      'Code API rejected the request',
+      {
+        method,
+        profile: options?.profile ?? 'unset',
+        status: response.status,
+      }
+    );
+  }
+  if (response.status !== 429) {
+    discardResponseBody(response);
   }
   if (response.status === 429) {
+    let responseBody = '';
+    try {
+      responseBody = await response.text();
+    } catch {
+      responseBody = '';
+    }
     const retryAfterSeconds = getRetryAfterSeconds(responseBody);
     return retryAfterSeconds != null
       ? `Code execution is temporarily rate-limited. Retry after ${retryAfterSeconds} seconds.`
@@ -445,9 +514,11 @@ function createCodeExecutionTool(
         session_id.length > 0 &&
         !Array.isArray(postData.files)
       ) {
-        // eslint-disable-next-line no-console
-        console.debug(
-          `[CodeExecutor] No injected files for session_id=${session_id} — exec will run without input files`
+        logCodeApiDiagnostic(
+          'CodeExecutor',
+          'debug',
+          'session carried no injected files; exec will run without input files',
+          { files: 'none' }
         );
       }
 
@@ -474,7 +545,9 @@ function createCodeExecutionTool(
         const response = await fetch(execEndpoint, fetchOptions);
         if (!response.ok) {
           throw new CodeApiRequestError(
-            await buildCodeApiHttpErrorMessage('POST', execEndpoint, response)
+            await buildCodeApiHttpErrorMessage('POST', execEndpoint, response, {
+              profile: executionProfile,
+            })
           );
         }
 

package/src/tools/ProgrammaticToolCalling.ts

@@ -33,6 +33,10 @@ import {
   createCodeApiRunTimeoutSchema,
   resolveCodeApiRunTimeoutMs,
 } from './ptcTimeout';
+import {
+  describeCodeApiError,
+  logCodeApiDiagnostic,
+} from '@/tools/diagnostics';
 import { resolveFetchProxyAgent } from '@/utils/proxy';
 import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
@@ -449,7 +453,9 @@ export async function fetchSessionFiles(
       }
     }
     const filesEndpoint = `${baseUrl}/files/${encodeURIComponent(sessionId)}?${query.toString()}`;
-    const resolvedAuthHeaders = await resolveCodeApiAuthHeaders(authHeaders);
+    const resolvedAuthHeaders = await resolveCodeApiAuthHeaders(authHeaders, {
+      recoverable: true,
+    });
     const fetchOptions: RequestInit = {
       method: 'GET',
       headers: {
@@ -466,7 +472,9 @@ export async function fetchSessionFiles(
     const response = await fetch(filesEndpoint, fetchOptions);
     if (!response.ok) {
       throw new Error(
-        await buildCodeApiHttpErrorMessage('GET', filesEndpoint, response)
+        await buildCodeApiHttpErrorMessage('GET', filesEndpoint, response, {
+          recoverable: true,
+        })
       );
     }
 
@@ -479,9 +487,11 @@ export async function fetchSessionFiles(
       .filter(isCodeApiSessionFileWire)
       .map((file) => normalizeSessionFile(file, sessionId, scope));
   } catch (error) {
-    // eslint-disable-next-line no-console
-    console.warn(
-      `Failed to fetch files for session: ${sessionId}, ${(error as Error).message}`
+    logCodeApiDiagnostic(
+      'ProgrammaticToolCalling',
+      'warn',
+      'session file lookup failed; continuing without input files',
+      describeCodeApiError(error)
     );
     return [];
   }
@@ -525,7 +535,9 @@ export async function makeRequest(
 
     if (!response.ok) {
       throw new CodeApiRequestError(
-        await buildCodeApiHttpErrorMessage('POST', endpoint, response)
+        await buildCodeApiHttpErrorMessage('POST', endpoint, response, {
+          profile: executionProfile,
+        })
       );
     }
 
@@ -931,9 +943,7 @@ export async function runPlainExecution(args: {
     {
       lang: args.lang,
       code:
-        args.lang === 'py'
-          ? wrapPythonForPlainExecution(args.code)
-          : args.code,
+        args.lang === 'py' ? wrapPythonForPlainExecution(args.code) : args.code,
       ...(args.timeout != null ? { timeout: args.timeout } : {}),
       ...(args.sessionId != null && args.sessionId !== ''
         ? { session_id: args.sessionId }
@@ -1085,9 +1095,11 @@ export function createProgrammaticToolCallingTool(
         if (_injected_files && _injected_files.length > 0) {
           files = _injected_files;
         } else if (session_id != null && session_id.length > 0) {
-          // eslint-disable-next-line no-console
-          console.debug(
-            `[ProgrammaticToolCalling] No injected files for session_id=${session_id} — exec will run without input files`
+          logCodeApiDiagnostic(
+            'ProgrammaticToolCalling',
+            'debug',
+            'session carried no injected files; exec will run without input files',
+            { files: 'none' }
           );
         }