@librechat/agents 3.7.19 → 3.7.21

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

package/src/tools/diagnostics.ts

@@ -0,0 +1,107 @@
+import type * as t from '@/types';
+
+/**
+ * Operator diagnostics for the Code API tools.
+ *
+ * Every failure these tools surface to the model is reduced to a fixed
+ * sentence, so this log is the only surviving account of what went wrong —
+ * which also makes it the one place a credential can escape by accident. It
+ * escaped repeatedly while any field was quoted from something the tools did
+ * not produce: a response body echoing the header that was sent, an error
+ * message quoting an excerpt of a malformed signing key, a `stack` whose first
+ * line is that message, a writable `name`, a configured base URL carrying a
+ * capability in its path or its authority.
+ *
+ * Filtering those carriers case by case never converged, because the shape of
+ * a credential inside free text is not decidable. The rule here is structural
+ * instead: a diagnostic NAMES what happened using values this module owns, and
+ * QUOTES nothing it received. `CodeApiDiagnosticDetail` is a closed union of
+ * such values, so host-authored text cannot reach a log without failing to
+ * compile — and adding a field means widening that union in this file, which
+ * is the point at which the question gets asked.
+ */
+
+export type CodeApiMethod = 'GET' | 'POST';
+
+type CodeApiProfileLabel = t.CodeApiExecutionProfile | 'unset';
+
+const KNOWN_ERROR_TYPES: ReadonlyArray<
+  readonly [CodeApiErrorLabel, new () => Error]
+> = [
+  ['SyntaxError', SyntaxError],
+  ['TypeError', TypeError],
+  ['RangeError', RangeError],
+  ['ReferenceError', ReferenceError],
+  ['URIError', URIError],
+  ['EvalError', EvalError],
+];
+
+/** Built-in error types, the `typeof` results for a non-Error rejection, and
+ * the two labels this module supplies when neither applies. */
+type CodeApiErrorLabel =
+  | 'SyntaxError'
+  | 'TypeError'
+  | 'RangeError'
+  | 'ReferenceError'
+  | 'URIError'
+  | 'EvalError'
+  | 'Error'
+  | 'UndescribableError'
+  | 'string'
+  | 'number'
+  | 'bigint'
+  | 'boolean'
+  | 'symbol'
+  | 'undefined'
+  | 'object'
+  | 'function';
+
+export type CodeApiDiagnosticDetail =
+  | { type: CodeApiErrorLabel }
+  | { method: CodeApiMethod; profile: CodeApiProfileLabel; status: number }
+  | { files: 'none' };
+
+/**
+ * Classifies a rejection without reading anything off it. `instanceof` walks
+ * the prototype chain, so an accessor trap is never reached; the guard covers
+ * a `getPrototypeOf` trap, which would otherwise cost both the log and the
+ * rejection.
+ */
+export function describeCodeApiError(error: unknown): {
+  type: CodeApiErrorLabel;
+} {
+  try {
+    if (!(error instanceof Error)) {
+      return { type: typeof error };
+    }
+    for (const [label, constructor] of KNOWN_ERROR_TYPES) {
+      if (error instanceof constructor) {
+        return { type: label };
+      }
+    }
+    return { type: 'Error' };
+  } catch {
+    return { type: 'UndescribableError' };
+  }
+}
+
+type CodeApiDiagnosticSource =
+  | 'CodeExecutor'
+  | 'BashExecutor'
+  | 'ProgrammaticToolCalling'
+  | 'BashProgrammaticToolCalling';
+
+/**
+ * Console is the SDK's diagnostic channel; a winston logger is the host's
+ * concern. Hosts correlate these lines with their own request-scoped logs,
+ * which is where received identifiers such as a session id belong.
+ */
+export function logCodeApiDiagnostic(
+  source: CodeApiDiagnosticSource,
+  level: 'debug' | 'warn' | 'error',
+  message: string,
+  detail: CodeApiDiagnosticDetail
+): void {
+  // eslint-disable-next-line no-console
+  console[level](`[${source}] ${message}`, detail);
+}

package/src/tools/search/format.ts

@@ -11,6 +11,9 @@ const DEFAULT_MAX_LLM_OUTPUT_CHARS = 50000;
  *  this we drop it whole rather than emit a useless sliver. */
 const MIN_PARTIAL_HIGHLIGHT_CHARS = 200;
 
+export const MISSING_SEARCH_RESULT_DATA_ERROR =
+  'Search provider returned no result data';
+
 /** Resolves the per-search highlight budget from config, the
  *  `SEARCH_MAX_LLM_OUTPUT_CHARS` env var, or the default (50,000 chars). */
 export function resolveMaxLLMOutputChars(maxOutputChars?: number): number {
@@ -219,9 +222,16 @@ function formatSource(
 
 export function formatResultsForLLM(
   turn: number,
-  results: t.SearchResultData,
+  results?: t.SearchResultData | null,
   maxOutputChars?: number
 ): { output: string; references: t.ResultReference[] } {
+  if (results == null) {
+    return {
+      output: `Search failed: ${MISSING_SEARCH_RESULT_DATA_ERROR}`,
+      references: [],
+    };
+  }
+
   /** Bound highlight content to the per-search budget before formatting */
   const trimmedHighlights = trimHighlightsToBudget(
     results,
@@ -239,6 +249,10 @@ export function formatResultsForLLM(
 
   const references: t.ResultReference[] = [];
 
+  if (results.error != null && results.error !== '') {
+    outputLines.push(`Search failed: ${results.error}`);
+  }
+
   // Organic (web) results
   if (results.organic?.length != null && results.organic.length > 0) {
     addSection(`Web Results, Turn ${turn}`);

package/src/tools/search/rerankers.ts

@@ -21,6 +21,23 @@ const getDefaultCohereApiUrl = (): string =>
     ? process.env.COHERE_API_URL
     : DEFAULT_COHERE_API_URL;
 
+/**
+ * Ranking used whenever no reranker scores the chunks: the candidates' own
+ * order, capped at `topK`, with a neutral score.
+ *
+ * Exported because it is not only a *fallback*. With `rerankerType: 'none'`
+ * there is no reranker to fall back from, and the search pipeline needs the
+ * same ranking to hand the scraped text downstream — see `getHighlights` in
+ * `./search`.
+ */
+export const getDefaultRanking = (
+  documents: string[],
+  topK: number
+): t.Highlight[] =>
+  documents
+    .slice(0, Math.min(topK, documents.length))
+    .map((doc) => ({ text: doc, score: 0 }));
+
 export abstract class BaseReranker {
   protected apiKey: string | undefined;
   protected logger: t.Logger;
@@ -51,9 +68,7 @@ export abstract class BaseReranker {
     documents: string[],
     topK: number
   ): t.Highlight[] {
-    return documents
-      .slice(0, Math.min(topK, documents.length))
-      .map((doc) => ({ text: doc, score: 0 }));
+    return getDefaultRanking(documents, topK);
   }
 
   /** A direct caller has no enclosing search to fold into, so one

package/src/tools/search/search.ts

@@ -10,7 +10,7 @@ import { createKeenableAPI } from './keenable-search';
 import { createTavilyAPI } from './tavily-search';
 import { createSearchMetrics } from './metrics';
 import { createCrwAPI } from './crw-search';
-import { BaseReranker } from './rerankers';
+import { BaseReranker, getDefaultRanking } from './rerankers';
 
 /** Engines queried when `searxngSearchOptions.engines` is not configured. */
 const DEFAULT_SEARXNG_ENGINES = 'google,bing,duckduckgo';
@@ -144,9 +144,20 @@ function createSourceUpdateCallback(sourceMap: Map<string, t.ValidSource>) {
   };
 }
 
+/** Provider label for the metrics summary when reranking is switched off.
+ * `undefined` would be indistinguishable from a reranker that never ran. */
+const NO_RERANKER_PROVIDER = 'none';
+
 /** Returns undefined without logging when there is nothing to rank: an empty
- * scrape is already counted by the scrape summary, and a missing reranker is
- * reported once at tool construction rather than once per source. */
+ * scrape is already counted by the scrape summary.
+ *
+ * A *missing* reranker is not the same as nothing to rank. `rerankerType:
+ * 'none'` is a schema-valid opt-out, and `createReranker` returns `undefined`
+ * for it by design. Returning `undefined` here as well would leave the source
+ * without highlights, and `expandHighlights` then strips its content — the
+ * search would answer with links and no text at all. So the chunks are handed
+ * on in their original order via `getDefaultRanking`, exactly what every
+ * reranker's own failure path already does. */
 const getHighlights = async ({
   query,
   content,
@@ -164,7 +175,7 @@ const getHighlights = async ({
   maxContentLength?: number;
   chunkOptions?: { chunkSize: number; chunkOverlap: number };
 }): Promise<t.Highlight[] | undefined> => {
-  if (!content || !reranker) {
+  if (!content) {
     return;
   }
 
@@ -181,7 +192,7 @@ const getHighlights = async ({
     );
   } catch (error) {
     metrics.recordRerank({
-      provider: reranker.provider,
+      provider: reranker?.provider ?? NO_RERANKER_PROVIDER,
       chunks: 0,
       results: 0,
       durationMs: Date.now() - chunkStartedAt,
@@ -191,6 +202,20 @@ const getHighlights = async ({
     return;
   }
 
+  /** Reranking is switched off, so the chunks pass through unscored. Recorded
+   * like any other rerank so the search summary still accounts for the source;
+   * it carries no `reason`, because nothing failed. */
+  if (!reranker) {
+    const highlights = getDefaultRanking(documents, topResults);
+    metrics.recordRerank({
+      provider: NO_RERANKER_PROVIDER,
+      chunks: documents.length,
+      results: highlights.length,
+      durationMs: Date.now() - chunkStartedAt,
+    });
+    return highlights;
+  }
+
   const rerankStartedAt = Date.now();
   try {
     return await reranker.rerank(query, documents, topResults, metrics);

package/src/tools/search/tool.ts

@@ -21,7 +21,10 @@ import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { createCrwScraper } from './crw-scraper';
 import { expandHighlights } from './highlights';
 import { createSearchMetrics } from './metrics';
-import { formatResultsForLLM } from './format';
+import {
+  formatResultsForLLM,
+  MISSING_SEARCH_RESULT_DATA_ERROR,
+} from './format';
 import { createDefaultLogger } from './utils';
 import { createReranker } from './rerankers';
 import { Constants } from '@/common';
@@ -66,6 +69,12 @@ export function resolveSearchOutcome(
   return `Found ${count} result${count === 1 ? '' : 's'} for "${query}"`;
 }
 
+export function normalizeSearchResultData(
+  result: t.SearchResultData | null | undefined
+): t.SearchResultData {
+  return result ?? { error: MISSING_SEARCH_RESULT_DATA_ERROR };
+}
+
 /** Distinct rows across the main search's two collections. SearXNG derives
  * both from one result array — a row matching its news heuristic lands in
  * `organic` and `topStories` alike — so summing the lengths would report
@@ -431,12 +440,13 @@ function createTool({
         }),
       });
       const turn = runnableConfig.toolCall?.turn ?? 0;
+      const resultData = normalizeSearchResultData(searchResult);
       const { output, references } = formatResultsForLLM(
         turn,
-        searchResult,
+        resultData,
         maxOutputChars
       );
-      const data: t.SearchResultData = { turn, ...searchResult, references };
+      const data: t.SearchResultData = { turn, ...resultData, references };
       const outcome = resolveSearchOutcome(data, query);
       return [
         output,

package/src/types/llm.ts

@@ -81,6 +81,29 @@ export type GoogleThinkingConfig = {
 export type ManagedRequestOptions = {
   promptCacheExplicit?: boolean;
   safety_identifier?: string;
+  /**
+   * Declares that this client talks to the first-party OpenAI or Azure surface.
+   * Gates the model-specific request *shaping* documented only for it —
+   * currently GPT-6 Astra's rejected sampling and logprob parameters, its
+   * unsupported reasoning efforts, and the encrypted reasoning it supports —
+   * and defaults to off.
+   *
+   * Shaping only. Which API serves the turn is not decided here: GPT-6 Astra
+   * serves tool calls only from the Responses API, and a caller wanting them
+   * must select it with `useResponsesApi`, alongside the rest of the request
+   * shaping that depends on which API is in use.
+   *
+   * The shaping runs inside this SDK's own request delegates. A caller that
+   * supplies its own `completions` or `responses` delegate replaces that
+   * construction and owns the request shaping for it — this flag cannot reach
+   * inside a delegate it did not build.
+   *
+   * Declared rather than inferred from a base URL: only the caller knows
+   * whether a URL is a faithful first-party route, a gateway, or a proxy with
+   * its own semantics, and every gate it controls removes capability, so
+   * guessing wrong silently degrades an endpoint the SDK cannot see.
+   */
+  firstPartyEndpoint?: boolean;
 };
 /**
  * Adaptive stream-smoothing configuration shared by every provider client.