@librechat/agents 3.1.67 → 3.1.68-dev.1

package/src/summarization/node.ts

@@ -7,6 +7,7 @@ import {
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { UsageMetadata, BaseMessage } from '@langchain/core/messages';
 import type { AgentContext } from '@/agents/AgentContext';
+import type { HookRegistry } from '@/hooks';
 import type { OnChunk } from '@/llm/invoke';
 import type * as t from '@/types';
 import { ContentTypes, GraphEvents, StepTypes, Providers } from '@/common';
@@ -17,6 +18,7 @@ import { getMaxOutputTokensKey } from '@/llm/request';
 import { addCacheControl } from '@/messages/cache';
 import { initializeModel } from '@/llm/init';
 import { getChunkContent } from '@/stream';
+import { executeHooks } from '@/hooks';
 
 const SUMMARIZATION_PARAM_KEYS = new Set(['maxSummaryTokens']);
 
@@ -364,6 +366,122 @@ type LogFn = (
   data?: Record<string, unknown>
 ) => void;
 
+/**
+ * Extracts an HTTP status code from a thrown LLM-provider error. Returns
+ * `undefined` for non-object values (including `null` or `undefined`, both
+ * valid `throw` targets in JS) so callers never dereference a nullish
+ * value.
+ */
+function extractHttpStatus(err: unknown): number | undefined {
+  if (err == null || typeof err !== 'object') {
+    return undefined;
+  }
+  const errRecord = err as Record<string, unknown>;
+  const direct = errRecord.status;
+  if (typeof direct === 'number') {
+    return direct;
+  }
+  const statusCode = errRecord.statusCode;
+  if (typeof statusCode === 'number') {
+    return statusCode;
+  }
+  const response = errRecord.response;
+  if (response != null && typeof response === 'object') {
+    const nested = (response as Record<string, unknown>).status;
+    if (typeof nested === 'number') {
+      return nested;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Formats a provider-level error for logging. Returns both a human-readable
+ * suffix (safe to include in the message string so it survives any host-side
+ * formatter) and a structured metadata bag for rich log backends.
+ */
+function describeProviderError(
+  err: unknown,
+  provider: string,
+  modelName?: string
+): { suffix: string; data: Record<string, unknown> } {
+  const providerLabel = `${provider}/${modelName ?? '(no-model)'}`;
+  const errMsg = err instanceof Error ? err.message : String(err);
+
+  const data: Record<string, unknown> = {
+    provider,
+    model: modelName,
+  };
+  if (err instanceof Error) {
+    data.errorName = err.name;
+    data.errorStack = err.stack;
+  }
+
+  const status = extractHttpStatus(err);
+  const statusSuffix = status != null ? ` (HTTP ${status})` : '';
+  if (status != null) {
+    data.status = status;
+  }
+
+  return {
+    suffix: `[${providerLabel}]${statusSuffix}: ${errMsg}`,
+    data,
+  };
+}
+
+/**
+ * Formats an exhausted-fallback error. `tryFallbackProviders` throws the
+ * last fallback provider's error, which may be from any of the configured
+ * fallbacks — not the primary — so we label the log with the list of
+ * fallback providers attempted rather than mis-attributing to the primary.
+ *
+ * Entries in `fallbacks` are normally strongly typed, but we defend against
+ * malformed runtime config (null/undefined entries, missing `provider`
+ * field) so a recoverable summarization failure is never promoted to an
+ * uncaught exception from inside the logging path.
+ */
+function describeFallbackError(
+  err: unknown,
+  fallbacks: unknown
+): { suffix: string; data: Record<string, unknown> } {
+  const errMsg = err instanceof Error ? err.message : String(err);
+  const list: ReadonlyArray<unknown> = Array.isArray(fallbacks)
+    ? fallbacks
+    : [];
+  const providerNames = list
+    .map((f) => {
+      if (f == null || typeof f !== 'object') {
+        return undefined;
+      }
+      const raw = (f as { provider?: unknown }).provider;
+      return raw != null ? String(raw) : undefined;
+    })
+    .filter((p): p is string => typeof p === 'string');
+  const label =
+    providerNames.length > 0
+      ? `fallbacks=[${providerNames.join(',')}]`
+      : 'no-fallbacks';
+
+  const data: Record<string, unknown> = {
+    fallbackProviders: providerNames,
+    fallbackCount: list.length,
+  };
+  if (err instanceof Error) {
+    data.errorName = err.name;
+    data.errorStack = err.stack;
+  }
+  const status = extractHttpStatus(err);
+  const statusSuffix = status != null ? ` (HTTP ${status})` : '';
+  if (status != null) {
+    data.status = status;
+  }
+
+  return {
+    suffix: `[${label}]${statusSuffix}: ${errMsg}`,
+    data,
+  };
+}
+
 /**
  * Runs the summarization LLM call with primary + fallback providers,
  * falling back to a metadata stub when all calls fail.
@@ -387,18 +505,23 @@ async function executeSummarizationWithFallback(params: {
     log,
   } = params;
 
-  const summarizationModel = initializeModel({
-    provider: clientConfig.provider as Providers,
-    clientOptions: clientConfig.clientOptions as t.ClientOptions,
-    tools: agentContext.getToolsForBinding(),
-  }) as t.ChatModel;
-
   const priorSummaryText = agentContext.getSummaryText()?.trim() ?? '';
 
   let summaryText = '';
   let summaryUsage: Partial<UsageMetadata> | undefined;
 
   try {
+    /**
+     * Initialize inside the try so that a misconfigured provider
+     * (e.g. an unrecognized summarization.provider) surfaces through the
+     * `log('error', ...)` path below rather than bubbling up silently.
+     */
+    const summarizationModel = initializeModel({
+      provider: clientConfig.provider as Providers,
+      clientOptions: clientConfig.clientOptions as t.ClientOptions,
+      tools: agentContext.getToolsForBinding(),
+    }) as t.ChatModel;
+
     const result = await summarizeWithCacheHit({
       model: summarizationModel,
       messages,
@@ -415,19 +538,20 @@ async function executeSummarizationWithFallback(params: {
     summaryText = result.text;
     summaryUsage = result.usage;
   } catch (primaryError) {
-    log('error', 'Summarization LLM call failed', {
-      error:
-        primaryError instanceof Error
-          ? primaryError.message
-          : String(primaryError),
-      provider: clientConfig.provider,
-      model: clientConfig.modelName,
+    const primaryDescribed = describeProviderError(
+      primaryError,
+      clientConfig.provider,
+      clientConfig.modelName
+    );
+    log('error', `Summarization LLM call failed ${primaryDescribed.suffix}`, {
+      ...primaryDescribed.data,
       messagesToRefineCount: messages.length,
     });
 
-    const fallbacks =
-      (clientConfig.clientOptions as unknown as t.LLMConfig | undefined)
-        ?.fallbacks ?? [];
+    const rawFallbacks = (
+      clientConfig.clientOptions as unknown as t.LLMConfig | undefined
+    )?.fallbacks;
+    const fallbacks = Array.isArray(rawFallbacks) ? rawFallbacks : [];
     if (fallbacks.length > 0) {
       try {
         const onChunk = createSummarizationChunkHandler({
@@ -460,18 +584,21 @@ async function executeSummarizationWithFallback(params: {
           );
         }
       } catch (fbErr) {
-        log('warn', 'Fallback providers also failed', {
-          error: fbErr instanceof Error ? fbErr.message : String(fbErr),
+        const fbDescribed = describeFallbackError(fbErr, fallbacks);
+        log('warn', `Fallback providers also failed ${fbDescribed.suffix}`, {
+          ...fbDescribed.data,
         });
       }
     }
     if (!summaryText) {
-      log('warn', 'Summarization failed, falling back to metadata stub', {
-        error:
-          primaryError instanceof Error
-            ? primaryError.message
-            : String(primaryError),
-      });
+      log(
+        'warn',
+        `Summarization failed, falling back to metadata stub ${primaryDescribed.suffix}`,
+        {
+          ...primaryDescribed.data,
+          messagesToRefineCount: messages.length,
+        }
+      );
       summaryText = generateMetadataStub(messages);
     }
   }
@@ -530,6 +657,35 @@ async function dispatchCompletionEvents(params: {
     );
   }
 
+  const sessionId = graph.runId ?? '';
+  if (graph.hookRegistry?.hasHookFor('PostCompact', sessionId) === true) {
+    const threadId = (
+      runnableConfig?.configurable as Record<string, unknown> | undefined
+    )?.thread_id as string | undefined;
+    const firstBlock = summaryBlock.content?.[0];
+    const summaryText =
+      firstBlock != null &&
+      typeof firstBlock === 'object' &&
+      'text' in firstBlock &&
+      typeof firstBlock.text === 'string'
+        ? firstBlock.text
+        : '';
+    await executeHooks({
+      registry: graph.hookRegistry,
+      input: {
+        hook_event_name: 'PostCompact',
+        runId: sessionId,
+        threadId,
+        agentId,
+        summary: summaryText,
+        messagesAfterCount: 0,
+      },
+      sessionId,
+    }).catch(() => {
+      /* PostCompact is observational — swallow errors */
+    });
+  }
+
   agentContext.rebuildTokenMapAfterSummarization({});
 }
 
@@ -545,6 +701,7 @@ interface CreateSummarizeNodeParams {
     config?: RunnableConfig;
     runId?: string;
     isMultiAgent: boolean;
+    hookRegistry?: HookRegistry;
     dispatchRunStep: (
       runStep: t.RunStep,
       config?: RunnableConfig
@@ -650,6 +807,27 @@ export function createSummarizeNode({
       );
     }
 
+    const sessionId = graph.runId ?? '';
+    if (graph.hookRegistry?.hasHookFor('PreCompact', sessionId) === true) {
+      const threadId = (
+        runnableConfig?.configurable as Record<string, unknown> | undefined
+      )?.thread_id as string | undefined;
+      await executeHooks({
+        registry: graph.hookRegistry,
+        input: {
+          hook_event_name: 'PreCompact',
+          runId: sessionId,
+          threadId,
+          agentId: request.agentId,
+          messagesBeforeCount: messagesToRefine.length,
+          trigger: agentContext.summarizationConfig?.trigger?.type ?? 'default',
+        },
+        sessionId,
+      }).catch(() => {
+        /* PreCompact is observational — swallow errors */
+      });
+    }
+
     const isSelfSummarizeModel =
       clientConfig.provider === (agentContext.provider as string);
     const hasPromptCache =

package/src/tools/BashExecutor.ts

@@ -0,0 +1,193 @@
+import { config } from 'dotenv';
+import fetch, { RequestInit } from 'node-fetch';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import { tool, DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+import { imageExtRegex, getCodeBaseURL } from './CodeExecutor';
+import { Constants } from '@/common';
+
+config();
+
+const imageMessage = 'Image is already displayed to the user';
+const otherMessage = 'File is already downloaded by the user';
+const accessMessage =
+  'Note: Files from previous executions are automatically available and can be modified.';
+const emptyOutputMessage =
+  'stdout: Empty. Ensure you\'re writing output explicitly.\n';
+
+const baseEndpoint = getCodeBaseURL();
+const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
+
+export const BashExecutionToolSchema = {
+  type: 'object',
+  properties: {
+    command: {
+      type: 'string',
+      description: `The bash command or script to execute.
+- The environment is stateless; variables and state don't persist between executions.
+- Generated files from previous executions are automatically available in "/mnt/data/".
+- Files from previous executions are automatically available and can be modified in place.
+- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.
+- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.
+- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.
+- Use \`echo\`, \`printf\`, or \`cat\` for all outputs.`,
+    },
+    args: {
+      type: 'array',
+      items: { type: 'string' },
+      description:
+        'Additional arguments to execute the command with. This should only be used if the input command requires additional arguments to run.',
+    },
+  },
+  required: ['command'],
+} as const;
+
+export const BashExecutionToolDescription = `
+Runs bash commands and returns stdout/stderr output from a stateless execution environment, similar to running scripts in a command-line interface. Each execution is isolated and independent.
+
+Usage:
+- No network access available.
+- Generated files are automatically delivered; **DO NOT** provide download links.
+- NEVER use this tool to execute malicious commands.
+`.trim();
+
+export const BashExecutionToolName = Constants.BASH_TOOL;
+
+export const BashExecutionToolDefinition = {
+  name: BashExecutionToolName,
+  description: BashExecutionToolDescription,
+  schema: BashExecutionToolSchema,
+} as const;
+
+function createBashExecutionTool(
+  params: t.BashExecutionToolParams = {}
+): DynamicStructuredTool {
+  return tool(
+    async (rawInput, config) => {
+      const { command, ...rest } = rawInput as {
+        command: string;
+        args?: string[];
+      };
+      const { session_id, _injected_files } = (config.toolCall ?? {}) as {
+        session_id?: string;
+        _injected_files?: t.CodeEnvFile[];
+      };
+
+      const postData: Record<string, unknown> = {
+        lang: 'bash',
+        code: command,
+        ...rest,
+        ...params,
+      };
+
+      if (_injected_files && _injected_files.length > 0) {
+        postData.files = _injected_files;
+      } else if (session_id != null && session_id.length > 0) {
+        try {
+          const filesEndpoint = `${baseEndpoint}/files/${session_id}?detail=full`;
+          const fetchOptions: RequestInit = {
+            method: 'GET',
+            headers: {
+              'User-Agent': 'LibreChat/1.0',
+            },
+          };
+
+          if (process.env.PROXY != null && process.env.PROXY !== '') {
+            fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);
+          }
+
+          const response = await fetch(filesEndpoint, fetchOptions);
+          if (!response.ok) {
+            throw new Error(
+              `Failed to fetch files for session: ${response.status}`
+            );
+          }
+
+          const files = await response.json();
+          if (Array.isArray(files) && files.length > 0) {
+            const fileReferences: t.CodeEnvFile[] = files.map((file) => {
+              const nameParts = file.name.split('/');
+              const id = nameParts.length > 1 ? nameParts[1].split('.')[0] : '';
+
+              return {
+                session_id,
+                id,
+                name: file.metadata['original-filename'],
+              };
+            });
+
+            postData.files = fileReferences;
+          }
+        } catch {
+          // eslint-disable-next-line no-console
+          console.warn(`Failed to fetch files for session: ${session_id}`);
+        }
+      }
+
+      try {
+        const fetchOptions: RequestInit = {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'User-Agent': 'LibreChat/1.0',
+          },
+          body: JSON.stringify(postData),
+        };
+
+        if (process.env.PROXY != null && process.env.PROXY !== '') {
+          fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);
+        }
+        const response = await fetch(EXEC_ENDPOINT, fetchOptions);
+        if (!response.ok) {
+          throw new Error(`HTTP error! status: ${response.status}`);
+        }
+
+        const result: t.ExecuteResult = await response.json();
+        let formattedOutput = '';
+        if (result.stdout) {
+          formattedOutput += `stdout:\n${result.stdout}\n`;
+        } else {
+          formattedOutput += emptyOutputMessage;
+        }
+        if (result.stderr) formattedOutput += `stderr:\n${result.stderr}\n`;
+        if (result.files && result.files.length > 0) {
+          formattedOutput += 'Generated files:\n';
+
+          const fileCount = result.files.length;
+          for (let i = 0; i < fileCount; i++) {
+            const file = result.files[i];
+            const isImage = imageExtRegex.test(file.name);
+            formattedOutput += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;
+
+            if (i < fileCount - 1) {
+              formattedOutput += fileCount <= 3 ? ', ' : ',\n';
+            }
+          }
+
+          formattedOutput += `\n\n${accessMessage}`;
+          return [
+            formattedOutput.trim(),
+            {
+              session_id: result.session_id,
+              files: result.files,
+            },
+          ];
+        }
+
+        return [formattedOutput.trim(), { session_id: result.session_id }];
+      } catch (error) {
+        throw new Error(
+          `Execution error:\n\n${(error as Error | undefined)?.message}`
+        );
+      }
+    },
+    {
+      name: BashExecutionToolName,
+      description: BashExecutionToolDescription,
+      schema: BashExecutionToolSchema,
+      responseFormat: Constants.CONTENT_AND_ARTIFACT,
+    }
+  );
+}
+
+export { createBashExecutionTool };