@librechat/agents 3.1.56 → 3.1.60

package/src/tools/ToolNode.ts

@@ -20,6 +20,10 @@ import type { BaseMessage, AIMessage } from '@langchain/core/messages';
 import type { StructuredToolInterface } from '@langchain/core/tools';
 import type * as t from '@/types';
 import { RunnableCallable } from '@/utils';
+import {
+  calculateMaxToolResultChars,
+  truncateToolResultContent,
+} from '@/utils/truncation';
 import { safeDispatchCustomEvent } from '@/utils/events';
 import { Constants, GraphEvents } from '@/common';
 
@@ -53,6 +57,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   private agentId?: string;
   /** Tool names that bypass event dispatch and execute directly (e.g., graph-managed handoff tools) */
   private directToolNames?: Set<string>;
+  /** Maximum characters allowed in a single tool result before truncation. */
+  private maxToolResultChars: number;
 
   constructor({
     tools,
@@ -68,6 +74,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     eventDrivenMode,
     agentId,
     directToolNames,
+    maxContextTokens,
+    maxToolResultChars,
   }: t.ToolNodeConstructorParams) {
     super({ name, tags, func: (input, config) => this.run(input, config) });
     this.toolMap = toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
@@ -81,6 +89,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     this.eventDrivenMode = eventDrivenMode ?? false;
     this.agentId = agentId;
     this.directToolNames = directToolNames;
+    this.maxToolResultChars =
+      maxToolResultChars ?? calculateMaxToolResultChars(maxContextTokens);
   }
 
   /**
@@ -201,10 +211,15 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       ) {
         return output;
       } else {
+        const rawContent =
+          typeof output === 'string' ? output : JSON.stringify(output);
         return new ToolMessage({
           status: 'success',
           name: tool.name,
-          content: typeof output === 'string' ? output : JSON.stringify(output),
+          content: truncateToolResultContent(
+            rawContent,
+            this.maxToolResultChars
+          ),
           tool_call_id: call.id!,
         });
       }
@@ -539,10 +554,14 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           tool_call_id: result.toolCallId,
         });
       } else {
-        contentString =
+        const rawContent =
           typeof result.content === 'string'
             ? result.content
             : JSON.stringify(result.content);
+        contentString = truncateToolResultContent(
+          rawContent,
+          this.maxToolResultChars
+        );
         toolMessage = new ToolMessage({
           status: 'success',
           name: toolName,
@@ -658,7 +677,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
            */
           return (
             (call.id == null || !toolMessageIds.has(call.id)) &&
-            !(call.id?.startsWith('srvtoolu_') ?? false)
+            !(
+              call.id?.startsWith(Constants.ANTHROPIC_SERVER_TOOL_PREFIX) ??
+              false
+            )
           );
         }) ?? [];
 

package/src/types/graph.ts

@@ -22,6 +22,13 @@ import type { ToolMap, ToolEndEvent, GenericTool, LCTool } from '@/types/tools';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
+import type {
+  SummarizationNodeInput,
+  SummarizeCompleteEvent,
+  SummarizationConfig,
+  SummarizeStartEvent,
+  SummarizeDeltaEvent,
+} from '@/types/summarize';
 import type {
   RunStep,
   RunStepDeltaEvent,
@@ -66,12 +73,25 @@ export type BaseGraphState = {
   messages: BaseMessage[];
 };
 
+export type AgentSubgraphState = BaseGraphState & {
+  summarizationRequest?: SummarizationNodeInput;
+};
+
 export type MultiAgentGraphState = BaseGraphState & {
   agentMessages?: BaseMessage[];
 };
 
 export type IState = BaseGraphState;
 
+export interface AgentLogEvent {
+  level: 'debug' | 'info' | 'warn' | 'error';
+  scope: 'prune' | 'summarize' | 'graph' | 'sanitize' | (string & {});
+  message: string;
+  data?: Record<string, unknown>;
+  runId?: string;
+  agentId?: string;
+}
+
 export interface EventHandler {
   handle(
     event: string,
@@ -82,6 +102,10 @@ export interface EventHandler {
       | RunStepDeltaEvent
       | MessageDeltaEvent
       | ReasoningDeltaEvent
+      | SummarizeStartEvent
+      | SummarizeDeltaEvent
+      | SummarizeCompleteEvent
+      | AgentLogEvent
       | { result: ToolEndEvent },
     metadata?: Record<string, unknown>,
     graph?: StandardGraph | MultiAgentGraph
@@ -142,24 +166,30 @@ export type CompiledMultiAgentWorkflow = CompiledStateGraph<
 >;
 
 export type CompiledAgentWorfklow = CompiledStateGraph<
-  {
-    messages: BaseMessage[];
-  },
-  {
-    messages?: BaseMessage[] | undefined;
-  },
-  '__start__' | `agent=${string}` | `tools=${string}`,
+  AgentSubgraphState,
+  Partial<AgentSubgraphState>,
+  '__start__' | `agent=${string}` | `tools=${string}` | `summarize=${string}`,
   {
     messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+    summarizationRequest: BinaryOperatorAggregate<
+      SummarizationNodeInput | undefined,
+      SummarizationNodeInput | undefined
+    >;
   },
   {
     messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+    summarizationRequest: BinaryOperatorAggregate<
+      SummarizationNodeInput | undefined,
+      SummarizationNodeInput | undefined
+    >;
   },
   StateDefinition,
   {
     [x: `agent=${string}`]: Partial<BaseGraphState>;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     [x: `tools=${string}`]: any;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [x: `summarize=${string}`]: any;
   }
 >;
 
@@ -314,6 +344,7 @@ export type StandardGraphInput = {
   agents: AgentInputs[];
   tokenCounter?: TokenCounter;
   indexTokenCountMap?: Record<string, number>;
+  calibrationRatio?: number;
 };
 
 export type GraphEdge = {
@@ -391,4 +422,28 @@ export interface AgentInputs {
    * in tool binding without requiring tool_search.
    */
   discoveredTools?: string[];
+  summarizationEnabled?: boolean;
+  summarizationConfig?: SummarizationConfig;
+  /** Cross-run summary from a previous run, forwarded from formatAgentMessages.
+   *  Injected into the system message via AgentContext.buildInstructionsString(). */
+  initialSummary?: { text: string; tokenCount: number };
+  contextPruningConfig?: ContextPruningConfig;
+  maxToolResultChars?: number;
+}
+
+export interface ContextPruningConfig {
+  enabled?: boolean;
+  keepLastAssistants?: number;
+  softTrimRatio?: number;
+  hardClearRatio?: number;
+  minPrunableToolChars?: number;
+  softTrim?: {
+    maxChars?: number;
+    headChars?: number;
+    tailChars?: number;
+  };
+  hardClear?: {
+    enabled?: boolean;
+    placeholder?: string;
+  };
 }

package/src/types/index.ts

@@ -4,3 +4,4 @@ export * from './llm';
 export * from './run';
 export * from './stream';
 export * from './tools';
+export * from './summarize';

package/src/types/run.ts

@@ -115,6 +115,15 @@ export type RunConfig = {
   returnContent?: boolean;
   tokenCounter?: TokenCounter;
   indexTokenCountMap?: Record<string, number>;
+  /**
+   * Calibration ratio from a previous run's contextMeta.
+   * Seeds the pruner's EMA so new messages are scaled immediately.
+   *
+   * Hosts should persist the value returned by `Run.getCalibrationRatio()`
+   * after each run and pass it back here on subsequent runs for the same
+   * conversation. Without this, the EMA resets to 1 on every new Run instance.
+   */
+  calibrationRatio?: number;
   /** Skip post-stream cleanup (clearHeavyState) — useful for tests that inspect graph state after processStream */
   skipCleanup?: boolean;
 };
@@ -124,6 +133,29 @@ export type ProvidedCallbacks =
   | undefined;
 
 export type TokenCounter = (message: BaseMessage) => number;
+
+/** Structured breakdown of how context token budget is consumed. */
+export type TokenBudgetBreakdown = {
+  /** Total context window budget (maxContextTokens). */
+  maxContextTokens: number;
+  /** Total instruction tokens (system + tools + summary). */
+  instructionTokens: number;
+  /** Tokens from the system message text alone. */
+  systemMessageTokens: number;
+  /** Tokens from tool schema definitions. */
+  toolSchemaTokens: number;
+  /** Tokens from the conversation summary. */
+  summaryTokens: number;
+  /** Number of registered tools. */
+  toolCount: number;
+  /** Number of messages in the conversation. */
+  messageCount: number;
+  /** Total tokens consumed by messages (excluding system). */
+  messageTokens: number;
+  /** Tokens available for messages after instructions. */
+  availableForMessages: number;
+};
+
 export type EventStreamOptions = {
   callbacks?: g.ClientCallbacks;
   keepContent?: boolean;

package/src/types/stream.ts

@@ -10,6 +10,7 @@ import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
 import type { LLMResult, Generation } from '@langchain/core/outputs';
 import type { AnthropicContentBlock } from '@/llm/anthropic/types';
 import type { Command } from '@langchain/langgraph';
+import type { SummarizeCompleteEvent } from '@/types/summarize';
 import type { ToolEndEvent } from '@/types/tools';
 import { StepTypes, ContentTypes, GraphEvents } from '@/common/enum';
 
@@ -80,6 +81,7 @@ export type RunStep = {
   index: number; // #new
   stepIndex?: number; // #new
   stepDetails: StepDetails;
+  summary?: SummaryContentBlock;
   usage?: null | object;
   // {
   // Define usage structure if it's ever non-null
@@ -106,7 +108,12 @@ export interface RunStepDeltaEvent {
 
 export type StepDetails = MessageCreationDetails | ToolCallsDetails;
 
-export type StepCompleted = ToolCallCompleted;
+export type SummaryCompleted = {
+  type: 'summary';
+  summary: SummaryContentBlock;
+};
+
+export type StepCompleted = ToolCallCompleted | SummaryCompleted;
 
 export type MessageCreationDetails = {
   type: StepTypes.MESSAGE_CREATION;
@@ -164,6 +171,7 @@ export type ToolCallsDetails = {
 export type ToolCallDelta = {
   type: StepTypes;
   tool_calls?: ToolCallChunk[]; // #new
+  summary?: SummaryContentBlock;
   auth?: string;
   expires_at?: number;
 };
@@ -260,13 +268,35 @@ export type MessageDeltaUpdate = {
 };
 export type ReasoningDeltaUpdate = { type: ContentTypes.THINK; think: string };
 
-export type ContentType = 'text' | 'image_url' | 'tool_call' | 'think' | string;
+export type ContentType =
+  | 'text'
+  | 'image_url'
+  | 'tool_call'
+  | 'think'
+  | 'summary'
+  | string;
 
 export type ReasoningContentText = {
   type: ContentTypes.THINK;
   think: string;
 };
 
+export type SummaryBoundary = {
+  messageId: string;
+  contentIndex: number;
+};
+
+export type SummaryContentBlock = {
+  type: ContentTypes.SUMMARY;
+  content?: MessageContentComplex[];
+  tokenCount?: number;
+  boundary?: SummaryBoundary;
+  summaryVersion?: number;
+  model?: string;
+  provider?: string;
+  createdAt?: string;
+};
+
 /** Vertex AI / Google Common - Reasoning Content Block Format */
 export type GoogleReasoningContentText = {
   type: ContentTypes.REASONING;
@@ -330,6 +360,7 @@ export type ToolResultContent = {
 export type MessageContentComplex = (
   | ToolResultContent
   | ThinkingContentText
+  | SummaryContentBlock
   | AgentUpdate
   | ToolCallContent
   | ReasoningContentText
@@ -399,6 +430,13 @@ export type SplitStreamHandlers = Partial<{
   }) => void;
 }>;
 
+export type SummarizeDeltaData = {
+  id: string;
+  delta: {
+    summary: SummaryContentBlock;
+  };
+};
+
 export type ContentAggregator = ({
   event,
   data,
@@ -406,11 +444,13 @@ export type ContentAggregator = ({
   event: GraphEvents;
   data:
     | RunStep
+    | AgentUpdate
     | MessageDeltaEvent
+    | ReasoningDeltaEvent
     | RunStepDeltaEvent
-    | {
-        result: ToolEndEvent;
-      };
+    | SummarizeDeltaData
+    | SummarizeCompleteEvent
+    | { result: ToolEndEvent };
 }) => void;
 export type ContentAggregatorResult = {
   stepMap: Map<string, RunStep | undefined>;

package/src/types/summarize.ts

@@ -0,0 +1,58 @@
+import type { SummaryContentBlock } from '@/types/stream';
+import type { Providers } from '@/common';
+
+export type SummarizationTrigger = {
+  type:
+    | 'token_ratio'
+    | 'remaining_tokens'
+    | 'messages_to_refine'
+    | (string & {});
+  value: number;
+};
+
+export type SummarizationConfig = {
+  provider?: Providers;
+  model?: string;
+  parameters?: Record<string, unknown>;
+  prompt?: string;
+  updatePrompt?: string;
+  trigger?: SummarizationTrigger;
+  maxSummaryTokens?: number;
+  /** Fraction of the token budget reserved as headroom (0–1). Defaults to 0.05. */
+  reserveRatio?: number;
+};
+
+export interface SummarizeResult {
+  text: string;
+  tokenCount: number;
+  model?: string;
+  provider?: string;
+}
+
+export interface SummarizationNodeInput {
+  remainingContextTokens: number;
+  agentId: string;
+}
+
+export interface SummarizeStartEvent {
+  agentId: string;
+  provider: string;
+  model?: string;
+  messagesToRefineCount: number;
+  /** Which summarization cycle this is (1-based, increments each time summarization fires) */
+  summaryVersion: number;
+}
+
+export interface SummarizeDeltaEvent {
+  id: string;
+  delta: {
+    summary: SummaryContentBlock;
+  };
+}
+
+export interface SummarizeCompleteEvent {
+  id: string;
+  agentId: string;
+  summary?: SummaryContentBlock;
+  error?: string;
+}

package/src/types/tools.ts

@@ -49,6 +49,13 @@ export type ToolNodeOptions = {
   agentId?: string;
   /** Tool names that must be executed directly (via runTool) even in event-driven mode (e.g., graph-managed handoff tools) */
   directToolNames?: Set<string>;
+  /** Max context tokens for the agent — used to compute tool result truncation limits. */
+  maxContextTokens?: number;
+  /**
+   * Maximum characters allowed in a single tool result before truncation.
+   * When provided, takes precedence over the value computed from maxContextTokens.
+   */
+  maxToolResultChars?: number;
 };
 
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;

package/src/utils/errors.ts

@@ -0,0 +1,117 @@
+/**
+ * Context overflow error detection utilities.
+ *
+ * Identifies provider-specific error messages that indicate the request
+ * exceeded the model's context window. Used by the overflow recovery loop
+ * to decide whether to retry with truncation/compaction vs. propagating
+ * the error.
+ */
+
+/**
+ * Exact phrases that definitively indicate a context overflow error.
+ * These are returned by various LLM providers when the prompt is too large.
+ */
+const CONTEXT_OVERFLOW_PHRASES = [
+  'request_too_large',
+  'context length exceeded',
+  'maximum context length',
+  'prompt is too long',
+  'exceeds model context window',
+  'exceeds the model',
+  'too large for model',
+  'context_length_exceeded',
+  'max_tokens',
+  'token limit',
+  'input too long',
+  'payload too large',
+  'content_too_large',
+] as const;
+
+/**
+ * HTTP status codes and broader hints that suggest context overflow.
+ * Used by the less-strict `isLikelyContextOverflowError`.
+ */
+const CONTEXT_OVERFLOW_HINT_RE =
+  /413|too large|too long|context.*exceed|exceed.*context|token.*limit|limit.*token|prompt.*size|size.*limit|maximum.*length|length.*maximum/i;
+
+/**
+ * Patterns that should NOT be treated as context overflow even if they
+ * contain words like "limit" or "too large".
+ */
+const FALSE_POSITIVE_RE =
+  /rate.?limit|too many requests|quota|billing|auth|permission|forbidden/i;
+
+/**
+ * Extracts a human-readable error message from an unknown error value.
+ */
+export function extractErrorMessage(error: unknown): string {
+  if (error == null) {
+    return '';
+  }
+  if (typeof error === 'string') {
+    return error;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === 'object') {
+    const record = error as Record<string, unknown>;
+    if (typeof record.message === 'string') {
+      return record.message;
+    }
+    if (typeof record.error === 'string') {
+      return record.error;
+    }
+    if (
+      typeof record.error === 'object' &&
+      record.error != null &&
+      typeof (record.error as Record<string, unknown>).message === 'string'
+    ) {
+      return (record.error as Record<string, unknown>).message as string;
+    }
+  }
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+
+/**
+ * Returns true if the error message definitively indicates a context
+ * overflow / prompt-too-large error from the provider.
+ *
+ * This is the strict check: only matches known, unambiguous phrases.
+ * Use this when you want high confidence before taking recovery action.
+ */
+export function isContextOverflowError(errorMessage?: string): boolean {
+  if (!errorMessage) {
+    return false;
+  }
+  const lower = errorMessage.toLowerCase();
+  if (FALSE_POSITIVE_RE.test(lower)) {
+    return false;
+  }
+  return CONTEXT_OVERFLOW_PHRASES.some((phrase) => lower.includes(phrase));
+}
+
+/**
+ * Returns true if the error message likely indicates a context overflow.
+ * Uses broader heuristic matching (regex) in addition to exact phrases.
+ *
+ * May produce false positives for unusual error messages. Use this when
+ * the cost of a false positive (one extra retry) is acceptable.
+ */
+export function isLikelyContextOverflowError(errorMessage?: string): boolean {
+  if (!errorMessage) {
+    return false;
+  }
+  if (isContextOverflowError(errorMessage)) {
+    return true;
+  }
+  const lower = errorMessage.toLowerCase();
+  if (FALSE_POSITIVE_RE.test(lower)) {
+    return false;
+  }
+  return CONTEXT_OVERFLOW_HINT_RE.test(lower);
+}

package/src/utils/events.ts

@@ -2,6 +2,8 @@
 // src/utils/events.ts
 import { dispatchCustomEvent } from '@langchain/core/callbacks/dispatch';
 import type { RunnableConfig } from '@langchain/core/runnables';
+import type { AgentLogEvent } from '@/types/graph';
+import { GraphEvents } from '@/common';
 
 /**
  * Safely dispatches a custom event and properly awaits it to avoid
@@ -30,3 +32,32 @@ export async function safeDispatchCustomEvent(
     console.error('Error dispatching custom event:', e);
   }
 }
+
+/**
+ * Fire-and-forget diagnostic log event.
+ * Debug-level logs are gated behind AGENT_DEBUG_LOGGING=true to avoid
+ * overhead in production. Info/warn/error always flow through.
+ * Pass `force: true` to bypass the env-var gate (e.g. invoke timing).
+ */
+export function emitAgentLog(
+  config: RunnableConfig | undefined,
+  level: AgentLogEvent['level'],
+  scope: AgentLogEvent['scope'],
+  message: string,
+  data?: Record<string, unknown>,
+  meta?: { runId?: string; agentId?: string },
+  options?: { force?: boolean }
+): void {
+  if (!config) return;
+  if (
+    level === 'debug' &&
+    !(options?.force ?? false) &&
+    process.env.AGENT_DEBUG_LOGGING !== 'true'
+  )
+    return;
+  void safeDispatchCustomEvent(
+    GraphEvents.ON_AGENT_LOG,
+    { level, scope, message, data, ...meta } satisfies AgentLogEvent,
+    config
+  );
+}

package/src/utils/handlers.ts

@@ -97,6 +97,24 @@ export function createHandlers(callbacks?: HandlerCallbacks): {
         callbacks?.onMessageDelta?.(event, data);
       },
     },
+
+    [GraphEvents.ON_SUMMARIZE_DELTA]: {
+      handle: (event: string, data: t.StreamEventData): void => {
+        aggregateContent({
+          event: event as GraphEvents,
+          data: data as t.SummarizeDeltaData,
+        });
+      },
+    },
+
+    [GraphEvents.ON_SUMMARIZE_COMPLETE]: {
+      handle: (event: string, data: t.StreamEventData): void => {
+        aggregateContent({
+          event: event as GraphEvents,
+          data: data as t.SummarizeCompleteEvent,
+        });
+      },
+    },
   };
 
   return {

package/src/utils/index.ts

@@ -5,3 +5,5 @@ export * from './handlers';
 export * from './run';
 export * from './tokens';
 export * from './schema';
+export * from './truncation';
+export * from './errors';

package/src/utils/llm.ts

@@ -24,3 +24,15 @@ export function isGoogleLike(provider?: string | Providers): boolean {
     provider
   );
 }
+
+/** Returns true for native Anthropic or Bedrock running a Claude model. */
+export function isAnthropicLike(
+  provider?: string | Providers,
+  clientOptions?: { model?: string }
+): boolean {
+  if (provider === Providers.ANTHROPIC) return true;
+  if (provider === Providers.BEDROCK) {
+    return /claude/i.test(String(clientOptions?.model ?? ''));
+  }
+  return false;
+}