@librechat/agents 3.3.0 → 3.3.1

package/src/summarization/node.ts

@@ -15,6 +15,10 @@ import {
   resolvePromptCacheTtl,
   type PromptCacheTtl,
 } from '@/messages/cache';
+import {
+  DEFAULT_RETAIN_RECENT_TURNS,
+  splitAtRecencyBoundary,
+} from '@/messages/recency';
 import {
   Constants,
   ContentTypes,
@@ -25,7 +29,6 @@ import {
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
 import { attemptInvoke, tryFallbackProviders } from '@/llm/invoke';
 import { createRemoveAllMessage } from '@/messages/reducer';
-import { splitAtRecencyBoundary } from '@/messages/recency';
 import { getMaxOutputTokensKey } from '@/llm/request';
 import { initializeModel } from '@/llm/init';
 import { getChunkContent } from '@/stream';
@@ -43,8 +46,6 @@ const SUMMARIZATION_PARAM_KEYS = new Set(['maxSummaryTokens']);
  * `retainRecent.turns` to `0` reverts to the legacy "summarize every
  * message" behavior.
  */
-const DEFAULT_RETAIN_RECENT_TURNS = 2;
-
 /**
  * Token overhead of the XML wrapper + instruction text added around the
  * summary at injection time in AgentContext.buildSystemRunnable:
@@ -517,7 +518,16 @@ async function executeSummarizationWithFallback(params: {
   stepId: string;
   usePromptCache: boolean;
   log: LogFn;
-}): Promise<{ text: string; usage?: Partial<UsageMetadata> }> {
+}): Promise<{
+  text: string;
+  usage?: Partial<UsageMetadata>;
+  /**
+   * True when every model call failed and `text` is the generated metadata
+   * stub rather than a real summary. Callers that would replace history with
+   * this need to know it carries none of the original content.
+   */
+  usedMetadataStub?: boolean;
+}> {
   const {
     agentContext,
     messages,
@@ -532,6 +542,7 @@ async function executeSummarizationWithFallback(params: {
 
   let summaryText = '';
   let summaryUsage: Partial<UsageMetadata> | undefined;
+  let usedMetadataStub = false;
 
   try {
     /**
@@ -634,10 +645,11 @@ async function executeSummarizationWithFallback(params: {
         }
       );
       summaryText = generateMetadataStub(messages);
+      usedMetadataStub = true;
     }
   }
 
-  return { text: summaryText, usage: summaryUsage };
+  return { text: summaryText, usage: summaryUsage, usedMetadataStub };
 }
 
 /** Dispatches run step completion, ON_SUMMARIZE_COMPLETE, and rebuilds token map. */
@@ -774,6 +786,34 @@ export function createSummarizeNode({
       return { summarizationRequest: undefined };
     }
 
+    /**
+     * Overflow recovery routes through this node purely to get back to the
+     * agent node with a corrected budget, and deliberately spends no model
+     * call on its first attempt: re-pruning under the raised context pressure
+     * drives the pruner's tool-output compression and masking, which is
+     * cheaper than a summary and cannot lose message content. Summarization
+     * is also skipped outright when the caller never enabled it.
+     */
+    if (
+      request.reason === 'overflow' &&
+      (request.allowSummarization !== true ||
+        agentContext.summarizationEnabled !== true)
+    ) {
+      emitAgentLog(
+        config,
+        'debug',
+        'summarize',
+        'Overflow recovery re-prune — compressing tool output without a summarization call',
+        {
+          maxContextTokens: agentContext.maxContextTokens,
+          summarizationEnabled: agentContext.summarizationEnabled === true,
+          allowSummarization: request.allowSummarization === true,
+        },
+        { runId: graph.runId, agentId: request.agentId }
+      );
+      return { summarizationRequest: undefined };
+    }
+
     const maxCtx = agentContext.maxContextTokens ?? 0;
     if (maxCtx > 0 && agentContext.instructionTokens >= maxCtx) {
       emitAgentLog(
@@ -976,16 +1016,61 @@ export function createSummarizeNode({
       }
       : undefined;
 
-    const { text: rawText, usage: summaryUsage } =
-      await executeSummarizationWithFallback({
-        agentContext,
-        messages: messagesToRefine,
-        clientConfig,
-        summarizeConfig,
+    const {
+      text: rawText,
+      usage: summaryUsage,
+      usedMetadataStub,
+    } = await executeSummarizationWithFallback({
+      agentContext,
+      messages: messagesToRefine,
+      clientConfig,
+      summarizeConfig,
+      stepId,
+      usePromptCache: isSelfSummarizeModel && hasPromptCache,
+      log,
+    });
+
+    /**
+     * The metadata stub describes the history rather than summarizing it, so
+     * committing it means removing the head and keeping nothing of what it
+     * said. That trade is never worth making to paper over an overflow: the
+     * recovery would "succeed" only by destroying the conversation it was
+     * supposed to preserve. Leave state untouched and let the provider error
+     * surface instead.
+     */
+    if (usedMetadataStub === true && request.reason === 'overflow') {
+      log(
+        'warn',
+        'Overflow summarization failed; keeping history rather than replacing it with a metadata stub'
+      );
+      agentContext.markSummarizationTriggered(state.messages.length);
+      /**
+       * The run step was already dispatched, so it has to be resolved here or
+       * consumers tracking step lifecycle keep an unfinished placeholder for
+       * the rest of the run.
+       */
+      await graph.dispatchRunStepCompleted(
         stepId,
-        usePromptCache: isSelfSummarizeModel && hasPromptCache,
-        log,
-      });
+        {
+          type: 'summary',
+          summary: placeholderSummary,
+        } satisfies t.SummaryCompleted,
+        runnableConfig
+      );
+      if (runnableConfig) {
+        await safeDispatchCustomEvent(
+          GraphEvents.ON_SUMMARIZE_COMPLETE,
+          {
+            id: stepId,
+            agentId: request.agentId,
+            error:
+              'Summarization failed during overflow recovery; conversation history was preserved',
+          } satisfies t.SummarizeCompleteEvent,
+          runnableConfig
+        );
+      }
+      return { summarizationRequest: undefined };
+    }
 
     if (!rawText) {
       agentContext.markSummarizationTriggered(0);

package/src/tools/BashExecutor.ts

@@ -11,7 +11,9 @@ import {
   appendCodeSessionFileSummary,
   emptyOutputMessage,
   buildCodeApiHttpErrorMessage,
+  CodeApiRequestError,
   getCodeBaseURL,
+  normalizeCodeApiRequestError,
   resolveCodeApiAuthHeaders,
 } from './CodeExecutor';
 import { Constants } from '@/common';
@@ -250,7 +252,7 @@ function createBashExecutionTool(
         }
         const response = await fetch(EXEC_ENDPOINT, fetchOptions);
         if (!response.ok) {
-          throw new Error(
+          throw new CodeApiRequestError(
             await buildCodeApiHttpErrorMessage('POST', EXEC_ENDPOINT, response)
           );
         }
@@ -291,7 +293,7 @@ function createBashExecutionTool(
         ];
       } catch (error) {
         const messageWithReminder = appendFailedExecutionFileReminder(
-          (error as Error | undefined)?.message ?? '',
+          normalizeCodeApiRequestError(error).message,
           command
         );
         throw new Error(`Execution error:\n\n${messageWithReminder}`);

package/src/tools/BashProgrammaticToolCalling.ts

@@ -7,6 +7,8 @@ import {
   BASH_SHELL_GUIDANCE,
   CODE_ARTIFACT_PATH_GUIDANCE,
   appendFailedExecutionFileReminder,
+  buildCodeApiExecutionErrorMessage,
+  CodeApiRequestError,
   getCodeBaseURL,
 } from './CodeExecutor';
 import {
@@ -434,15 +436,10 @@ export function createBashProgrammaticToolCallingTool(
         }
 
         if (response.status === 'error') {
-          throw new Error(
-            `Execution error: ${response.error}` +
-              (response.stderr != null && response.stderr !== ''
-                ? `\n\nStderr:\n${response.stderr}`
-                : '')
-          );
+          throw new Error(buildCodeApiExecutionErrorMessage(response));
         }
 
-        throw new Error(`Unexpected response status: ${response.status}`);
+        throw new CodeApiRequestError();
       } catch (error) {
         const messageWithReminder = appendFailedExecutionFileReminder(
           (error as Error).message,

package/src/tools/CodeExecutor.ts

@@ -111,6 +111,102 @@ const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
 
 type SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];
 
+const MAX_RETRY_AFTER_SECONDS = 3600;
+
+export const CODE_API_UNAVAILABLE_ERROR_MESSAGE =
+  'Code execution is temporarily unavailable. Please retry.';
+export const CODE_API_AUTHORIZATION_ERROR_MESSAGE =
+  'Code execution is not authorized. Verify access before trying again.';
+export const CODE_API_EXECUTION_FAILED_ERROR_MESSAGE = 'Code execution failed.';
+export const CODE_API_INVALID_REQUEST_ERROR_MESSAGE =
+  'The code execution request was rejected. Please check the tool input and try again.';
+export const CODE_API_RATE_LIMITED_ERROR_MESSAGE =
+  'Code execution is temporarily rate-limited. Please retry shortly.';
+
+const SAFE_CODE_API_EXECUTION_ERROR_DETAILS: Readonly<
+  Partial<Record<string, string>>
+> = {
+  'Execution failed or timed out': 'Execution failed or timed out.',
+  'Out of memory': 'Execution exceeded the memory limit.',
+  'Time limit exceeded': 'Execution exceeded the time limit.',
+  'sandbox emitted an empty pending tool call block; aborting to avoid a tight retry loop':
+    'Generated code emitted an invalid empty tool request.',
+  'stderr length exceeded': 'Execution error output exceeded the size limit.',
+  'stdout length exceeded': 'Execution output exceeded the size limit.',
+};
+
+export class CodeApiRequestError extends Error {
+  constructor(message = CODE_API_UNAVAILABLE_ERROR_MESSAGE) {
+    super(message);
+    this.name = 'CodeApiRequestError';
+  }
+}
+
+function getRetryAfterSeconds(responseBody: string): number | undefined {
+  try {
+    const parsed = JSON.parse(responseBody) as {
+      error?: unknown;
+      retry_after_seconds?: unknown;
+    };
+    if (
+      parsed.error !== 'rate_limited' ||
+      typeof parsed.retry_after_seconds !== 'number' ||
+      !Number.isFinite(parsed.retry_after_seconds) ||
+      parsed.retry_after_seconds <= 0
+    ) {
+      return undefined;
+    }
+    return Math.min(
+      Math.ceil(parsed.retry_after_seconds),
+      MAX_RETRY_AFTER_SECONDS
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+export function normalizeCodeApiRequestError(
+  error: unknown
+): CodeApiRequestError {
+  return error instanceof CodeApiRequestError
+    ? error
+    : new CodeApiRequestError();
+}
+
+function getSafeCodeApiExecutionErrorDetail(
+  error: unknown
+): string | undefined {
+  if (typeof error !== 'string') {
+    return undefined;
+  }
+  const exactMatch = SAFE_CODE_API_EXECUTION_ERROR_DETAILS[error];
+  if (exactMatch != null) {
+    return exactMatch;
+  }
+  if (/^Sandbox exited with code (?:-?\d{1,4}|unknown)$/.test(error)) {
+    return error.replace(/^Sandbox/, 'Execution');
+  }
+  if (/^Sandbox requested an unregistered tool: .+$/.test(error)) {
+    return 'Generated code requested a tool that is not available.';
+  }
+  return undefined;
+}
+
+export function buildCodeApiExecutionErrorMessage(response: {
+  error?: unknown;
+  stderr?: unknown;
+}): string {
+  const safeDetail = getSafeCodeApiExecutionErrorDetail(response.error);
+  const message =
+    safeDetail != null
+      ? `${CODE_API_EXECUTION_FAILED_ERROR_MESSAGE} ${safeDetail}`
+      : CODE_API_EXECUTION_FAILED_ERROR_MESSAGE;
+  if (typeof response.stderr === 'string' && response.stderr !== '') {
+    return `${message}\n\nStderr:\n${response.stderr}`;
+  }
+  return message;
+}
+
 export async function resolveCodeApiAuthHeaders(
   authHeaders?: t.CodeApiAuthHeaders
 ): Promise<t.CodeApiAuthHeaderMap> {
@@ -118,14 +214,19 @@ export async function resolveCodeApiAuthHeaders(
     return {};
   }
   if (typeof authHeaders === 'function') {
-    return authHeaders();
+    try {
+      const resolvedHeaders = await authHeaders();
+      return resolvedHeaders;
+    } catch {
+      throw new CodeApiRequestError(CODE_API_AUTHORIZATION_ERROR_MESSAGE);
+    }
   }
   return authHeaders;
 }
 
 export async function buildCodeApiHttpErrorMessage(
-  method: string,
-  endpoint: string,
+  _method: string,
+  _endpoint: string,
   response: { status: number; text: () => Promise<string> }
 ): Promise<string> {
   let responseBody = '';
@@ -134,9 +235,19 @@ export async function buildCodeApiHttpErrorMessage(
   } catch {
     responseBody = '';
   }
-  const body = responseBody.trim();
-  const bodySuffix = body === '' ? '' : `, body: ${body.slice(0, 1000)}`;
-  return `CodeAPI request failed: ${method} ${endpoint} returned ${response.status}${bodySuffix}`;
+  if (response.status === 429) {
+    const retryAfterSeconds = getRetryAfterSeconds(responseBody);
+    return retryAfterSeconds != null
+      ? `Code execution is temporarily rate-limited. Retry after ${retryAfterSeconds} seconds.`
+      : CODE_API_RATE_LIMITED_ERROR_MESSAGE;
+  }
+  if (response.status === 401 || response.status === 403) {
+    return CODE_API_AUTHORIZATION_ERROR_MESSAGE;
+  }
+  if (response.status === 400 || response.status === 422) {
+    return CODE_API_INVALID_REQUEST_ERROR_MESSAGE;
+  }
+  return CODE_API_UNAVAILABLE_ERROR_MESSAGE;
 }
 
 export const CodeExecutionToolDescription = `
@@ -314,7 +425,7 @@ function createCodeExecutionTool(
         }
         const response = await fetch(EXEC_ENDPOINT, fetchOptions);
         if (!response.ok) {
-          throw new Error(
+          throw new CodeApiRequestError(
             await buildCodeApiHttpErrorMessage('POST', EXEC_ENDPOINT, response)
           );
         }
@@ -358,7 +469,7 @@ function createCodeExecutionTool(
         ];
       } catch (error) {
         const messageWithReminder = appendFailedExecutionFileReminder(
-          (error as Error | undefined)?.message ?? '',
+          normalizeCodeApiRequestError(error).message,
           code
         );
         throw new Error(`Execution error:\n\n${messageWithReminder}`);

package/src/tools/ProgrammaticToolCalling.ts

@@ -10,10 +10,13 @@ import {
   CODE_ARTIFACT_PATH_GUIDANCE,
   appendCodeSessionFileSummary,
   appendFailedExecutionFileReminder,
+  buildCodeApiExecutionErrorMessage,
   buildCodeApiHttpErrorMessage,
+  CodeApiRequestError,
   emptyOutputMessage,
   getCodeBaseURL,
   appendTmpScratchReminder,
+  normalizeCodeApiRequestError,
   resolveCodeApiAuthHeaders,
 } from './CodeExecutor';
 import {
@@ -474,30 +477,34 @@ export async function makeRequest(
   proxy?: string,
   authHeaders?: t.CodeApiAuthHeaders
 ): Promise<t.ProgrammaticExecutionResponse> {
-  const resolvedAuthHeaders = await resolveCodeApiAuthHeaders(authHeaders);
-  const fetchOptions: RequestInit = {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'User-Agent': 'LibreChat/1.0',
-      ...resolvedAuthHeaders,
-    },
-    body: JSON.stringify(body),
-  };
+  try {
+    const resolvedAuthHeaders = await resolveCodeApiAuthHeaders(authHeaders);
+    const fetchOptions: RequestInit = {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': 'LibreChat/1.0',
+        ...resolvedAuthHeaders,
+      },
+      body: JSON.stringify(body),
+    };
 
-  if (proxy != null && proxy !== '') {
-    fetchOptions.agent = new HttpsProxyAgent(proxy);
-  }
+    if (proxy != null && proxy !== '') {
+      fetchOptions.agent = new HttpsProxyAgent(proxy);
+    }
 
-  const response = await fetch(endpoint, fetchOptions);
+    const response = await fetch(endpoint, fetchOptions);
 
-  if (!response.ok) {
-    throw new Error(
-      await buildCodeApiHttpErrorMessage('POST', endpoint, response)
-    );
-  }
+    if (!response.ok) {
+      throw new CodeApiRequestError(
+        await buildCodeApiHttpErrorMessage('POST', endpoint, response)
+      );
+    }
 
-  return (await response.json()) as t.ProgrammaticExecutionResponse;
+    return (await response.json()) as t.ProgrammaticExecutionResponse;
+  } catch (error) {
+    throw normalizeCodeApiRequestError(error);
+  }
 }
 
 /**
@@ -1014,15 +1021,10 @@ export function createProgrammaticToolCallingTool(
         }
 
         if (response.status === 'error') {
-          throw new Error(
-            `Execution error: ${response.error}` +
-              (response.stderr != null && response.stderr !== ''
-                ? `\n\nStderr:\n${response.stderr}`
-                : '')
-          );
+          throw new Error(buildCodeApiExecutionErrorMessage(response));
         }
 
-        throw new Error(`Unexpected response status: ${response.status}`);
+        throw new CodeApiRequestError();
       } catch (error) {
         const messageWithReminder = appendFailedExecutionFileReminder(
           (error as Error).message,

package/src/tools/ToolNode.ts

@@ -1,3 +1,4 @@
+import { nanoid } from 'nanoid';
 import { ToolCall } from '@langchain/core/messages/tool';
 import { AsyncLocalStorageProviderSingleton } from '@langchain/core/singletons';
 import {
@@ -119,6 +120,9 @@ type RunToolBatchContext<T = unknown> = {
 };
 
 const TOOL_NODE_RUN_NAME = 'tool_batch';
+const NANOID_URL_ALPHABET =
+  '_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
+const RUNTIME_HANDOFF_GROUP_OFFSET = 2 ** 48;
 
 /**
  * Per-batch context for `dispatchToolEvents` / `executeViaEvent`.
@@ -158,6 +162,41 @@ function isHandoffToolName(name: string): boolean {
   return name.startsWith(Constants.LC_TRANSFER_TO_);
 }
 
+/**
+ * Encodes 48 random bits from the persisted batch key into a safe integer.
+ * The high offset keeps runtime groups disjoint from low, structural group IDs.
+ */
+function getRuntimeHandoffGroupId(batch: string): number {
+  let value = 0;
+  for (const char of batch.slice(0, 8)) {
+    const digit = NANOID_URL_ALPHABET.indexOf(char);
+    value = value * 64 + Math.max(digit, 0);
+  }
+  return RUNTIME_HANDOFF_GROUP_OFFSET + value;
+}
+
+function findHandoffMessage(
+  messages: BaseMessage[],
+  destination: string
+): ToolMessage | undefined {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.getType() !== 'tool') {
+      continue;
+    }
+    const toolMessage = message as ToolMessage;
+    const isStandardHandoff =
+      toolMessage.name === `${Constants.LC_TRANSFER_TO_}${destination}`;
+    const isConditionalHandoff =
+      toolMessage.name === 'conditional_transfer' &&
+      toolMessage.additional_kwargs.handoff_destination === destination;
+    if (isStandardHandoff || isConditionalHandoff) {
+      return toolMessage;
+    }
+  }
+  return undefined;
+}
+
 /**
  * Format a fail-closed diagnostic for malformed approval-decision
  * fields. Hosts deserialize resume payloads from untyped JSON, so
@@ -3854,21 +3893,24 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         const goto = cmd.goto;
         return typeof goto === 'string' ? goto : (goto as string[])[0];
       });
+      const parallelBatch = nanoid();
+      const parallelGroupId = getRuntimeHandoffGroupId(parallelBatch);
 
       const sends = handoffCommands.map((cmd, idx) => {
         const destination = allDestinations[idx];
         /** Get siblings (other destinations, not this one) */
         const siblings = allDestinations.filter((d) => d !== destination);
 
-        /** Add siblings to ToolMessage additional_kwargs */
         const update = cmd.update as { messages?: BaseMessage[] } | undefined;
-        if (update && update.messages) {
-          for (const msg of update.messages) {
-            if (msg.getType() === 'tool') {
-              (msg as ToolMessage).additional_kwargs.handoff_parallel_siblings =
-                siblings;
-            }
-          }
+        const handoffMessage = update?.messages
+          ? findHandoffMessage(update.messages, destination)
+          : undefined;
+        if (handoffMessage) {
+          handoffMessage.additional_kwargs.handoff_parallel_siblings = siblings;
+          handoffMessage.additional_kwargs[Constants.HANDOFF_PARALLEL_BATCH] =
+            parallelBatch;
+          handoffMessage.additional_kwargs[Constants.HANDOFF_GROUP_ID] =
+            parallelGroupId;
         }
 
         return new Send(destination, cmd.update);