@librechat/agents 4.0.1 → 4.0.3

package/src/stream.ts

@@ -58,6 +58,7 @@ import {
 import { createToolCallsDispatchedEvent, safeDispatchCustomEvent } from '@/utils/events';
 import { resolveToolOutcome, outcomeFieldsFromResult } from '@/tools/intentArg';
 import { snapshotValidatedModelChunk } from '@/graphs/acceptedModelResponse';
+import { ProviderTextProtectionError } from '@/protection/providerText';
 import { TOOL_OUTPUT_REF_PATTERN } from '@/tools/toolOutputReferences';
 import { formatToolErrorContent } from '@/tools/toolErrorContent';
 import { PreparedSubagentError } from '@/tools/preparedSubagents';
@@ -1687,6 +1688,7 @@ export class ChatModelStreamHandler implements t.EventHandler {
       graph.breakerAbort instanceof AbortController
         ? graph.breakerAbort
         : undefined;
+    const entrySignals = [eventBreaker?.signal, graph.signal, graph.config.signal];
     /** Immutable scope captured at handler entry. A reset while this
      * handler is suspended in an await replaces the object, so ONE
      * reference comparison proves the event still belongs to the live run
@@ -1695,13 +1697,16 @@ export class ChatModelStreamHandler implements t.EventHandler {
     const runScopeInvalidated = (): boolean =>
       entryRunScope != null && graph.runScope !== entryRunScope;
     const throwIfRunBreakerTripped = (): void => {
-      if (
-        eventBreaker != null &&
-        eventBreaker.signal.aborted &&
-        (eventBreaker.signal.reason instanceof StreamLimitExceededError ||
-          eventBreaker.signal.reason instanceof PreparedSubagentError)
-      ) {
-        throw eventBreaker.signal.reason;
+      for (const signal of entrySignals) {
+        if (signal?.aborted === true &&
+            (signal.reason instanceof StreamLimitExceededError ||
+              signal.reason instanceof PreparedSubagentError ||
+              signal.reason instanceof ProviderTextProtectionError)) {
+          throw signal.reason;
+        }
+        if (signal?.aborted === true && graph.providerTextProtection != null) {
+          throw new ProviderTextProtectionError('cancelled');
+        }
       }
     };
 
@@ -1797,6 +1802,8 @@ export class ChatModelStreamHandler implements t.EventHandler {
       metadata,
       agentContext,
     });
+    if (runScopeInvalidated()) return;
+    throwIfRunBreakerTripped();
     if (skipHandling) {
       return;
     }
@@ -1831,6 +1838,8 @@ export class ChatModelStreamHandler implements t.EventHandler {
         content,
         metadata,
       });
+      if (runScopeInvalidated()) return;
+      throwIfRunBreakerTripped();
     }
 
     if (
@@ -2033,6 +2042,23 @@ export class ChatModelStreamHandler implements t.EventHandler {
       });
       runStep = graph.getRunStep(stepId);
     }
+    if (
+      graph.providerTextProtection != null &&
+      runStep?.type === StepTypes.TOOL_CALLS &&
+      agentContext.currentTokenType === ContentTypes.TEXT &&
+      (typeof content === 'string' || content.every(isTextContentPart))
+    ) {
+      stepId = await dispatchMessageCreationStep({
+        graph,
+        stepKey,
+        content,
+        contentType: ContentTypes.TEXT,
+        metadata,
+      });
+      if (runScopeInvalidated()) return;
+      throwIfRunBreakerTripped();
+      runStep = graph.getRunStep(stepId);
+    }
     if (!runStep) {
       console.warn(`\n
 ==============================================================

package/src/summarization/node.ts

@@ -56,6 +56,7 @@ import {
   resolveClientOptionsModel,
 } from '@/llm/request';
 import { renderCompactionSemanticIndex } from '@/summarization/semanticIndex';
+import { ProviderTextProtectionError } from '@/protection/providerText';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
 import { prepareToolsForPromptCache } from '@/llm/promptCacheTools';
 import { attemptInvoke, tryFallbackProviders } from '@/llm/invoke';
@@ -739,16 +740,6 @@ async function executeSummarizationWithFallback(params: {
     summaryText = result.text;
     summaryUsage = result.usage;
   } catch (primaryError) {
-    const primaryDescribed = describeProviderError(
-      primaryError,
-      clientConfig.provider,
-      clientConfig.modelName
-    );
-    log('error', `Summarization LLM call failed ${primaryDescribed.suffix}`, {
-      ...primaryDescribed.data,
-      messagesToRefineCount: messages.length,
-    });
-
     /**
      * A tripped stream circuit breaker is a safety abort, not a
      * summarization failure to recover from: retrying on fallback providers
@@ -758,7 +749,7 @@ async function executeSummarizationWithFallback(params: {
      * rejects the run. Rethrown so the summarize node fails the run with
      * the actionable limit error, consistent with agent turns and subagents.
      */
-    if (primaryError instanceof StreamLimitExceededError) {
+    if (primaryError instanceof StreamLimitExceededError || primaryError instanceof ProviderTextProtectionError) {
       throw primaryError;
     }
     /** A parallel branch's trip aborts the composed summarization signal,
@@ -777,6 +768,16 @@ async function executeSummarizationWithFallback(params: {
       }
     }
 
+    const primaryDescribed = describeProviderError(
+      primaryError,
+      clientConfig.provider,
+      clientConfig.modelName
+    );
+    log('error', `Summarization LLM call failed ${primaryDescribed.suffix}`, {
+      ...primaryDescribed.data,
+      messagesToRefineCount: messages.length,
+    });
+
     const rawFallbacks = (
       clientConfig.clientOptions as unknown as t.LLMConfig | undefined
     )?.fallbacks;
@@ -819,7 +820,9 @@ async function executeSummarizationWithFallback(params: {
           );
         }
       } catch (fbErr) {
-        if (fbErr instanceof StreamLimitExceededError) {
+        const trip = findStreamLimitAbortReason(graph?.getBreakerSignal?.(), summarizeConfig?.signal);
+        if (trip != null) throw trip;
+        if (fbErr instanceof StreamLimitExceededError || fbErr instanceof ProviderTextProtectionError) {
           throw fbErr;
         }
         const fbDescribed = describeFallbackError(fbErr, fallbacks);
@@ -842,6 +845,8 @@ async function executeSummarizationWithFallback(params: {
     }
   }
 
+  const trip = findStreamLimitAbortReason(graph?.getBreakerSignal?.(), summarizeConfig?.signal);
+  if (trip != null) throw trip;
   return { text: summaryText, usage: summaryUsage, usedMetadataStub };
 }
 
@@ -875,6 +880,11 @@ async function dispatchCompletionEvents(params: {
     messagesAfterCount,
   } = params;
 
+  const assertNotTripped = (): void => {
+    const trip = findStreamLimitAbortReason(graph.getBreakerSignal?.(), runnableConfig?.signal);
+    if (trip != null) throw trip;
+  };
+  assertNotTripped();
   runStep.summary = summaryBlock;
   if (summaryUsage) {
     runStep.usage = {
@@ -892,6 +902,7 @@ async function dispatchCompletionEvents(params: {
     runnableConfig
   );
 
+  assertNotTripped();
   if (runnableConfig) {
     await safeDispatchCustomEvent(
       GraphEvents.ON_SUMMARIZE_COMPLETE,
@@ -904,6 +915,7 @@ async function dispatchCompletionEvents(params: {
     );
   }
 
+  assertNotTripped();
   const sessionId = graph.runId ?? '';
   if (graph.hookRegistry?.hasHookFor('PostCompact', sessionId) === true) {
     const threadId = (
@@ -1017,11 +1029,11 @@ function withBreakerSignal<T extends { signal?: AbortSignal }>(
  * child's private breaker never fires for it. */
 function findStreamLimitAbortReason(
   ...signals: Array<AbortSignal | undefined>
-): StreamLimitExceededError | undefined {
+): StreamLimitExceededError | ProviderTextProtectionError | undefined {
   for (const signal of signals) {
     if (
       signal?.aborted === true &&
-      signal.reason instanceof StreamLimitExceededError
+      (signal.reason instanceof StreamLimitExceededError || signal.reason instanceof ProviderTextProtectionError)
     ) {
       return signal.reason;
     }
@@ -1526,6 +1538,8 @@ export function createSummarizeNode({
       return { summarizationRequest: undefined };
     }
 
+    const postCallTrip = findStreamLimitAbortReason(entryBreakerSignal, config?.signal);
+    if (postCallTrip != null) throw postCallTrip;
     const summaryText = enrichSummary(rawText, messagesToRefine);
 
     const tokenCount = await computeSummaryTokenCount(
@@ -1533,6 +1547,8 @@ export function createSummarizeNode({
       agentContext
     );
 
+    const commitTrip = findStreamLimitAbortReason(entryBreakerSignal, config?.signal);
+    if (commitTrip != null) throw commitTrip;
     if (usedIntraTurnFallback) {
       agentContext.setSummary(summaryText, tokenCount, {
         precedesMessages: true,
@@ -1712,6 +1728,8 @@ export function createSummarizationChunkHandler({
         throw error;
       }
     }
+    const protectionTrip = findStreamLimitAbortReason(graph?.getBreakerController?.().signal, config.signal);
+    if (protectionTrip != null) throw protectionTrip;
     const chunkAny = chunk as Parameters<typeof getChunkContent>[0]['chunk'];
     const raw = getChunkContent({ chunk: chunkAny, provider, reasoningKey });
     if (raw == null || (typeof raw === 'string' && !raw)) {

package/src/tools/SubagentTool.ts

@@ -1,5 +1,6 @@
 import type { JsonSchemaType, LCTool } from '@/types/tools';
 import type { SubagentConfig } from '@/types';
+import { buildSubagentHostArgProperties } from '@/tools/subagent/hostArgs';
 import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
 
@@ -33,6 +34,9 @@ const RUN_IN_BACKGROUND_PROP_DESCRIPTION =
 const SUBAGENT_THREAD_PROP_DESCRIPTION =
   'Continue a host-owned child thread using a fresh execution lease. The saved thread must belong to this scope and subagent type. Only available with run_in_background.';
 
+const HOST_ARGS_DESCRIPTION =
+  '\n\nOPTIONAL ARGUMENTS:\n- Some types accept extra arguments, listed in brackets after the type. Each is optional: omit it to let the host choose. Where values are listed, pass one listed for the selected type; where it says any text, pass a short value of your own.';
+
 export const SubagentToolSchema = {
   type: 'object',
   properties: {
@@ -69,8 +73,13 @@ export function buildSubagentToolParams(
   description: string;
 } {
   const types = configs.map((c) => c.type);
+  const hostArgs = buildSubagentHostArgProperties(configs);
   const typeDescriptions = configs
-    .map((c) => `- "${c.type}" (${c.name}): ${c.description}`)
+    .map((c) => {
+      const summary = hostArgs.summaries.get(c.type);
+      const line = `- "${c.type}" (${c.name}): ${c.description}`;
+      return summary == null ? line : `${line} [optional ${summary}]`;
+    })
     .join('\n');
 
   return {
@@ -96,8 +105,7 @@ export function buildSubagentToolParams(
             },
           }
           : {}),
-        ...(options.background === true &&
-        options.threadContinuation === true
+        ...(options.background === true && options.threadContinuation === true
           ? {
             subagent_thread_id: {
               type: 'string',
@@ -105,10 +113,13 @@ export function buildSubagentToolParams(
             },
           }
           : {}),
+        ...hostArgs.properties,
       },
       required: ['description', 'subagent_type'],
     },
     description: `${SubagentToolDescription}${
+      hostArgs.summaries.size > 0 ? HOST_ARGS_DESCRIPTION : ''
+    }${
       options.background === true
         ? '\n\nBACKGROUND EXECUTION:\n- Set run_in_background to true when you do not need the result immediately. The call returns a background_task_id; use the host background-task tools to poll, steer, queue, interrupt, or cancel it.'
         : ''

package/src/tools/ToolNode.ts

@@ -130,6 +130,7 @@ import {
 } from '@/tools/local';
 import { stripCodeSessionFileSummary } from '@/tools/CodeSessionFileSummary';
 import { Constants, GraphEvents, CODE_EXECUTION_TOOLS } from '@/common';
+import { ProviderTextProtectionError } from '@/protection/providerText';
 import { formatToolErrorContent } from '@/tools/toolErrorContent';
 import { PreparedSubagentError } from '@/tools/preparedSubagents';
 import { attachRunStepResumeState } from '@/tools/runStepResume';
@@ -2146,7 +2147,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
        */
       if (
         e instanceof StreamLimitExceededError ||
-        e instanceof PreparedSubagentError
+        e instanceof PreparedSubagentError ||
+        e instanceof ProviderTextProtectionError
       ) {
         throw e;
       }
@@ -3486,7 +3488,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     if (
       signal?.aborted === true &&
       (signal.reason instanceof StreamLimitExceededError ||
-        signal.reason instanceof PreparedSubagentError)
+        signal.reason instanceof PreparedSubagentError ||
+        signal.reason instanceof ProviderTextProtectionError)
     ) {
       throw signal.reason;
     }
@@ -5467,7 +5470,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     if (
       composedSignal?.aborted === true &&
       (composedSignal.reason instanceof StreamLimitExceededError ||
-        composedSignal.reason instanceof PreparedSubagentError)
+        composedSignal.reason instanceof PreparedSubagentError ||
+        composedSignal.reason instanceof ProviderTextProtectionError)
     ) {
       throw composedSignal.reason;
     }

package/src/tools/search/search.ts

@@ -9,8 +9,8 @@ import {
 import { createKeenableAPI } from './keenable-search';
 import { createTavilyAPI } from './tavily-search';
 import { createSearchMetrics } from './metrics';
+import { getDefaultRanking } from './rerankers';
 import { createCrwAPI } from './crw-search';
-import { BaseReranker, getDefaultRanking } from './rerankers';
 
 /** Engines queried when `searxngSearchOptions.engines` is not configured. */
 const DEFAULT_SEARXNG_ENGINES = 'google,bing,duckduckgo';
@@ -169,7 +169,7 @@ const getHighlights = async ({
 }: {
   content: string;
   query: string;
-  reranker?: BaseReranker;
+  reranker?: t.SearchReranker;
   metrics: t.SearchMetrics;
   topResults?: number;
   maxContentLength?: number;
@@ -453,7 +453,7 @@ const createSearXNGAPI = (
       const organicResults = (data.results ?? [])
         .slice(0, numResults)
         .map((result: t.SearXNGResult, index: number) => {
-          let attribution = '';
+          let attribution: string;
           try {
             attribution = new URL(result.url ?? '').hostname;
           } catch {
@@ -486,7 +486,7 @@ const createSearXNGAPI = (
       const newsResults = (data.results ?? [])
         .filter(isNewsResult)
         .map((result: t.SearXNGResult, index: number) => {
-          let attribution = '';
+          let attribution: string;
           try {
             attribution = new URL(result.url ?? '').hostname;
           } catch {

package/src/tools/search/tool.ts

@@ -12,6 +12,10 @@ import {
   newsSchema,
   DATE_RANGE,
 } from './schema';
+import {
+  formatResultsForLLM,
+  MISSING_SEARCH_RESULT_DATA_ERROR,
+} from './format';
 import { createSearchAPI, createSourceProcessor } from './search';
 import { createKeenableScraper } from './keenable-scraper';
 import { createSerperScraper } from './serper-scraper';
@@ -21,10 +25,6 @@ import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { createCrwScraper } from './crw-scraper';
 import { expandHighlights } from './highlights';
 import { createSearchMetrics } from './metrics';
-import {
-  formatResultsForLLM,
-  MISSING_SEARCH_RESULT_DATA_ERROR,
-} from './format';
 import { createDefaultLogger } from './utils';
 import { createReranker } from './rerankers';
 import { Constants } from '@/common';
@@ -535,13 +535,13 @@ export const createSearchTool = (
   } = config;
 
   const logger = config.logger || createDefaultLogger();
-  const effectiveTavilySearchOptions =
-    searchProvider === 'tavily' && config.safeSearch != null
-      ? {
-        ...tavilySearchOptions,
-        safeSearch: config.safeSearch !== 0,
-      }
-      : tavilySearchOptions;
+  let effectiveTavilySearchOptions = tavilySearchOptions;
+  if (searchProvider === 'tavily' && config.safeSearch != null) {
+    effectiveTavilySearchOptions = {
+      ...tavilySearchOptions,
+      safeSearch: config.safeSearch !== 0,
+    };
+  }
 
   const schemaProperties: Record<string, unknown> = {
     intent: { ...INTENT_PROPERTY },
@@ -643,20 +643,22 @@ export const createSearchTool = (
     });
   }
 
-  const selectedReranker = createReranker({
-    rerankerType,
-    jinaApiKey,
-    jinaApiUrl,
-    cohereApiKey,
-    cohereApiUrl,
-    ragApiUrl,
-    ragApiTokenSupplier,
-    ragApiProfile,
-    rerankerTimeout,
-    httpAgent,
-    httpsAgent,
-    logger,
-  });
+  const selectedReranker =
+    config.reranker ??
+    createReranker({
+      rerankerType,
+      jinaApiKey,
+      jinaApiUrl,
+      cohereApiKey,
+      cohereApiUrl,
+      ragApiUrl,
+      ragApiTokenSupplier,
+      ragApiProfile,
+      rerankerTimeout,
+      httpAgent,
+      httpsAgent,
+      logger,
+    });
 
   /** `none` is a deliberate opt-out that `createReranker` already reports;
    * only an unusable configuration warrants a warning here. */

package/src/tools/search/types.ts

@@ -287,6 +287,9 @@ export interface ScrapeResult {
   highlights?: Highlight[];
 }
 
+/** Host implementations need only the public ranking seam, not BaseReranker's private state. */
+export type SearchReranker = Pick<BaseReranker, 'provider' | 'rerank'>;
+
 export interface ProcessSourcesConfig {
   topResults?: number;
   /** Max chars of scraped content stored per source and passed to the
@@ -306,7 +309,7 @@ export interface ProcessSourcesConfig {
   separatorExpandBy?: number;
   strategies?: string[];
   filterContent?: boolean;
-  reranker?: BaseReranker;
+  reranker?: SearchReranker;
   logger?: Logger;
 }
 

package/src/tools/subagent/SubagentExecutionRegistry.ts

@@ -63,6 +63,8 @@ export type SubagentInvocationBinding = Readonly<{
   description: string;
   subagentType: string;
   configId?: string;
+  /** Value-free identity of the call's validated host arguments. */
+  hostArgsDigest?: string;
 }>;
 
 export type SubagentSettlementBinding = Readonly<{
@@ -340,7 +342,8 @@ function assertCompatibleResumeExecution(
     current.parentToolCallId === next.parentToolCallId &&
     current.childRunId === next.childRunId &&
     current.subagentType === next.subagentType &&
-    current.configId === next.configId
+    current.configId === next.configId &&
+    current.hostArgsDigest === next.hostArgsDigest
   ) {
     return;
   }
@@ -354,7 +357,8 @@ function assertSameInvocation(
   if (
     current.description === next.description &&
     current.subagentType === next.subagentType &&
-    current.configId === next.configId
+    current.configId === next.configId &&
+    current.hostArgsDigest === next.hostArgsDigest
   ) {
     return;
   }
@@ -425,6 +429,7 @@ export class SubagentExecutionRecord<
   TSettledOutput = never,
 > {
   private identityValue?: SubagentExecutionIdentity;
+  private attemptedIdentityValue?: SubagentExecutionIdentity;
   private bindingValue?: SubagentDefinitionBinding;
   private bindingAuthority?: 'provisional' | 'effective';
   private invocationValue?: SubagentInvocationBinding;
@@ -488,6 +493,24 @@ export class SubagentExecutionRecord<
     return this.identityValue;
   }
 
+  /** Correlation only; never committed identity or resume authority. */
+  get attemptedIdentity(): SubagentExecutionIdentity | undefined {
+    return this.attemptedIdentityValue;
+  }
+
+  recordIdentityAttempt(identity: SubagentExecutionIdentity): void {
+    const current = this.attemptedIdentityValue;
+    if (
+      current != null &&
+      current.childRunId === identity.childRunId &&
+      current.childThreadId === identity.childThreadId &&
+      current.approvalExecutionScope === identity.approvalExecutionScope
+    ) {
+      return;
+    }
+    this.attemptedIdentityValue = Object.freeze({ ...identity });
+  }
+
   get binding(): SubagentDefinitionBinding | undefined {
     return this.bindingValue;
   }
@@ -570,6 +593,7 @@ export class SubagentExecutionRecord<
     if (this.pendingIdentityResolution != null) {
       return this.pendingIdentityResolution;
     }
+    this.attemptedIdentityValue = undefined;
     const pending = Promise.resolve()
       .then(() => {
         this.assertCurrentIdentityResolution(pending);
@@ -929,6 +953,7 @@ export class SubagentExecutionRegistry<
     if (this.recordsByAddress.get(record.address.key) !== record) {
       throw new SubagentExecutionInvalidatedError();
     }
+    record.recordIdentityAttempt(identity);
     const checkpointKey = getPreparationResourceKey(
       'checkpoint',
       identity.childThreadId