@librechat/agents 3.9.0 → 3.9.2

package/dist/types/utils/truncation.d.ts

@@ -4,6 +4,8 @@
  * Prevents oversized tool outputs from entering the message array and
  * consuming the entire context window.
  */
+/** Slices by UTF-16 code units, dropping orphaned surrogate halves at either edge. */
+export declare function sliceWithoutSplittingSurrogates(value: string, start: number, end?: number): string;
 /**
  * Absolute hard cap on tool result length (characters).
  * Even if the model has a 1M-token context, a single tool result

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.9.0",
+  "version": "3.9.2",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"

package/src/graphs/Graph.ts

@@ -70,6 +70,7 @@ import {
   convertInjectedMessages,
   coalesceAdjacentUserTurns,
   appendPredecessorHandoffCue,
+  appendInstructionlessHandoffCue,
   stampSyntheticProviderMessage,
 } from '@/messages';
 import {
@@ -3721,11 +3722,16 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
          * Applied HERE for the primary so the cue is part of the MEASURED
          * payload — the pre-invoke projection and overflow guard run on this
          * stage's output, and a post-measure append could push a just-fits
-         * prompt over budget unreported (#346 round 2). The attemptInvoke
-         * funnel re-keys per SERVING provider: it strips this cue for a
-         * tolerant fallback and adds it for a Claude fallback behind a
-         * tolerant primary.
+         * prompt over budget unreported (#346 round 2). Instructionless tool
+         * handoffs are grounded for every transport. Only the direct-edge
+         * predecessor cue is re-keyed per SERVING provider: tolerant
+         * fallbacks strip it, while Claude fallbacks add it.
          */
+        const beforeHandoffCue = transformed;
+        transformed = trackProviderMessageOrigins(
+          beforeHandoffCue,
+          appendInstructionlessHandoffCue(beforeHandoffCue, callConfig)
+        );
         if (isAnthropicLike(provider, clientOptions as { model?: string })) {
           const before = transformed;
           transformed = trackProviderMessageOrigins(

package/src/graphs/MultiAgentGraph.ts

@@ -28,12 +28,13 @@ import {
   setProviderMessageProvenance,
   stampSyntheticProviderMessage,
 } from '@/messages/provenance';
-import { serializeToolContentBounded } from '@/utils/toolContent';
-import { Constants, MULTI_AGENT_GRAPH_RUN_NAME } from '@/common';
 import {
   calculateMaxToolResultChars,
   HARD_MAX_TOOL_RESULT_CHARS,
 } from '@/utils/truncation';
+import { withInstructionlessHandoffCue } from '@/messages/handoffCue';
+import { serializeToolContentBounded } from '@/utils/toolContent';
+import { Constants, MULTI_AGENT_GRAPH_RUN_NAME } from '@/common';
 import { StandardGraph } from './Graph';
 
 /** Pattern to extract instructions from transfer ToolMessage content */
@@ -1354,12 +1355,6 @@ export class MultiAgentGraph extends StandardGraph {
           this.memberRecursionLimit == null
             ? config
             : { ...config, recursionLimit: this.memberRecursionLimit };
-        const memberConfig = withActiveAgentMetadata(
-          recursionLimitedConfig,
-          agentId,
-          agentContext?.name
-        );
-
         /**
          * Check if this agent is receiving a handoff.
          * If so, filter out the transfer messages and inject instructions as preamble.
@@ -1371,6 +1366,19 @@ export class MultiAgentGraph extends StandardGraph {
           agentId
         );
 
+        const memberConfig = withInstructionlessHandoffCue(
+          withActiveAgentMetadata(
+            recursionLimitedConfig,
+            agentId,
+            agentContext?.name
+          ),
+          handoffContext != null &&
+            (handoffContext.instructions == null ||
+              handoffContext.instructions === '')
+            ? handoffContext.filteredMessages.at(-1)
+            : undefined
+        );
+
         if (
           handoffContext?.sourceAgentName != null &&
           handoffContext.sourceAgentName !== ''
@@ -1582,7 +1590,9 @@ export class MultiAgentGraph extends StandardGraph {
     }
 
     const startingNodes =
-      summarizeOnlyAgentId != null ? [summarizeOnlyAgentId] : this.startingNodes;
+      summarizeOnlyAgentId != null
+        ? [summarizeOnlyAgentId]
+        : this.startingNodes;
     for (const startNode of startingNodes) {
       // eslint-disable-next-line @typescript-eslint/ban-ts-comment
       /** @ts-ignore */
@@ -1634,7 +1644,10 @@ export class MultiAgentGraph extends StandardGraph {
             this.resolveMaxRoutingPromptChars(destination);
 
           if (typeof prompt === 'function') {
-            const resolvedPrompt = await prompt(state.messages, this.startIndex);
+            const resolvedPrompt = await prompt(
+              state.messages,
+              this.startIndex
+            );
             promptText =
               resolvedPrompt == null
                 ? undefined

package/src/llm/prepareProviderRequest.ts

@@ -6,8 +6,8 @@ import type {
 } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
-import type * as t from '@/types';
 import type { ToolHistoryPreparation } from '@/messages/toolHistoryProjection';
+import type * as t from '@/types';
 import {
   projectCacheControlledToolOutputsToText,
   projectComputerCallOutputsToText,
@@ -21,6 +21,7 @@ import {
 import {
   coalesceAdjacentUserTurns,
   appendPredecessorHandoffCue,
+  appendInstructionlessHandoffCue,
   removePredecessorHandoffCue,
 } from '@/messages';
 import {
@@ -28,12 +29,12 @@ import {
   stripBedrockCacheControl,
   cloneMessage,
 } from '@/messages/cache';
+import { createToolHistoryPreparation } from '@/messages/toolHistoryProjection';
 import { isAnthropicLike, isGoogleLike, isOpenAILike } from '@/utils/llm';
 import { annotateMessagesForLLM } from '@/tools/toolOutputReferences';
 import { providerRequiresStrictAlternation } from '@/llm/providers';
 import { getProviderFamily } from '@/llm/providerRegistry';
 import { Providers } from '@/common';
-import { createToolHistoryPreparation } from '@/messages/toolHistoryProjection';
 
 const preparedProviderRequestBrand = Symbol('PreparedProviderRequest');
 const OMITTED_ATTACHMENT_TEXT =
@@ -555,16 +556,17 @@ export function prepareProviderRequest({
   const annotated = annotateMessagesForLLM(projected, registry, runId);
   const isRunProduced = context?.isRunProducedMessage;
   const modelId = resolveServingModelId(model);
+  const handoffGrounded = appendInstructionlessHandoffCue(annotated, config);
   const cued = isAnthropicLike(provider, {
     model: modelId,
   })
     ? appendPredecessorHandoffCue(
-      annotated,
+      handoffGrounded,
       isRunProduced == null
         ? undefined
         : (message): boolean => isRunProduced.call(context, message)
     )
-    : removePredecessorHandoffCue(annotated);
+    : removePredecessorHandoffCue(handoffGrounded);
   const preparedMessages = providerRequiresStrictAlternation(provider)
     ? coalesceAdjacentUserTurns(cued)
     : cued;

package/src/messages/contextPruning.ts

@@ -26,6 +26,7 @@ import {
   serializeToolContentBounded,
 } from '@/utils/toolContent';
 import { resolveContextPruningSettings } from './contextPruningSettings';
+import { sliceWithoutSplittingSurrogates } from '@/utils/truncation';
 
 /**
  * Applies head+tail soft-trim to tool result content.
@@ -36,7 +37,11 @@ function softTrimContent(
 ): string {
   const { headChars, tailChars } = settings;
   const indicator = `\n\n… [soft-trimmed: ${content.length} chars → ${headChars + tailChars} chars, middle removed] …\n\n`;
-  return content.slice(0, headChars) + indicator + content.slice(-tailChars);
+  return (
+    sliceWithoutSplittingSurrogates(content, 0, headChars) +
+    indicator +
+    sliceWithoutSplittingSurrogates(content, -tailChars)
+  );
 }
 
 export interface ContextPruningResult {
@@ -140,7 +145,8 @@ export function applyContextPruning(params: {
     }
     const content = message.content;
     const contentLength = getToolContentCharLength(content);
-    const eligibilityContent = params.canonicalMessages?.[i]?.content ?? content;
+    const eligibilityContent =
+      params.canonicalMessages?.[i]?.content ?? content;
     if (
       getToolContentCharLength(eligibilityContent) <
       settings.minPrunableToolChars

package/src/messages/handoffCue.ts

@@ -1,8 +1,59 @@
 // src/messages/handoffCue.ts
 import { HumanMessage } from '@langchain/core/messages';
+import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
 import { stampSyntheticProviderMessage } from './provenance';
 
+const HANDOFF_CUE_MESSAGE_ID = '__handoff_cue_message_id';
+export const INSTRUCTIONLESS_HANDOFF_CUE =
+  'Continue as the receiving agent using the preceding user request and context.';
+
+/** Scope transport-only grounding to this recipient's incoming assistant turn.
+ * Every agent entry resets the marker, including direct edges and cycles. The
+ * reducer has already assigned the source message's id, including on replay. */
+export function withInstructionlessHandoffCue(
+  config: RunnableConfig | undefined,
+  tail?: BaseMessage
+): RunnableConfig {
+  return {
+    ...config,
+    metadata: {
+      ...config?.metadata,
+      [HANDOFF_CUE_MESSAGE_ID]:
+        tail?.getType() === 'ai' ? (tail.id ?? null) : null,
+    },
+  };
+}
+
+/** Only provider projections get this cue. Matching the incoming turn's id
+ * prevents it leaking into later tool iterations or deliberate assistant
+ * prefill. It is independent of transport provider and run-produced ids, so
+ * gateways and checkpoint replays follow the same handoff contract. */
+export function appendInstructionlessHandoffCue(
+  messages: BaseMessage[],
+  config?: RunnableConfig
+): BaseMessage[] {
+  const tail = messages.at(-1);
+  const sourceId = config?.metadata?.[HANDOFF_CUE_MESSAGE_ID];
+  if (
+    typeof sourceId !== 'string' ||
+    sourceId === '' ||
+    tail?.getType() !== 'ai' ||
+    tail.id !== sourceId
+  ) {
+    return messages;
+  }
+  return [
+    ...messages,
+    stampSyntheticProviderMessage(
+      new HumanMessage({
+        content: INSTRUCTIONLESS_HANDOFF_CUE,
+        additional_kwargs: { role: 'user', isMeta: true, source: 'routing' },
+      })
+    ),
+  ];
+}
+
 /**
  * Bracketed-meta convention, like the handoff path's
  * `[Processed tool result and transferring to …]` bridge. The wording makes

package/src/messages/prune.ts

@@ -19,6 +19,7 @@ import {
   HARD_MAX_TOOL_CALL_INPUT_CHARS,
   HARD_MAX_TOOL_RESULT_CHARS,
   MIN_JSON_VALUE_CHARS,
+  sliceWithoutSplittingSurrogates,
   calculateMaxToolCallInputChars,
   calculateMaxToolResultChars,
 } from '@/utils/truncation';
@@ -1591,7 +1592,8 @@ function createBoundedTruncationValue(
     const next = Math.ceil((low + high) / 2);
     const candidate = {
       _truncated:
-        TOOL_INPUT_TRUNCATION_MARKER + canonicalPrefix.slice(0, next),
+        TOOL_INPUT_TRUNCATION_MARKER +
+        sliceWithoutSplittingSurrogates(canonicalPrefix, 0, next),
       _originalChars: originalChars,
     };
     if (JSON.stringify(candidate).length <= normalizedMaxChars) {
@@ -1604,7 +1606,8 @@ function createBoundedTruncationValue(
     // Keep the marker separate from a pure canonical prefix so another,
     // slightly smaller cap can be derived without nesting the envelope.
     _truncated:
-      TOOL_INPUT_TRUNCATION_MARKER + canonicalPrefix.slice(0, low),
+      TOOL_INPUT_TRUNCATION_MARKER +
+      sliceWithoutSplittingSurrogates(canonicalPrefix, 0, low),
     _originalChars: originalChars,
   };
 }
@@ -1847,8 +1850,12 @@ function projectStringInputWithinLimit(
   return {
     value:
       marker.length >= normalizedMaxChars
-        ? prefix.slice(0, normalizedMaxChars)
-        : prefix.slice(0, normalizedMaxChars - marker.length) + marker,
+        ? sliceWithoutSplittingSurrogates(prefix, 0, normalizedMaxChars)
+        : sliceWithoutSplittingSurrogates(
+          prefix,
+          0,
+          normalizedMaxChars - marker.length
+        ) + marker,
     changed: true,
   };
 }
@@ -2366,7 +2373,9 @@ function applyToolCallInputCaps(params: {
         additionalKwargsChanges
       );
     }
-    if (capped.response_metadata.output !== canonical.response_metadata.output) {
+    if (
+      capped.response_metadata.output !== canonical.response_metadata.output
+    ) {
       changes.response_metadata = cloneWithProjectedProperties(
         current.response_metadata,
         { output: capped.response_metadata.output }
@@ -2523,11 +2532,7 @@ export function createPruneMessages(factoryParams: PruneMessagesFactoryParams) {
       originalToolContent.clear();
       originalToolContentSize = 0;
     }
-    for (
-      let i = toolExchangeWidthThrough;
-      i < canonicalMessages.length;
-      i++
-    ) {
+    for (let i = toolExchangeWidthThrough; i < canonicalMessages.length; i++) {
       maxToolExchangeWidth = Math.max(
         maxToolExchangeWidth,
         getToolCallIds(canonicalMessages[i]).size

package/src/utils/toolContent.ts

@@ -3,6 +3,7 @@ import { ToolMessage, type BaseMessage } from '@langchain/core/messages';
 import {
   HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE,
   truncateToolResultContent,
+  sliceWithoutSplittingSurrogates,
 } from './truncation';
 
 type ToolContent = BaseMessage['content'];
@@ -421,7 +422,7 @@ type SegmentedStringBuffer = {
 export type BoundedStructuredSerialization = {
   /** Provider-facing head/tail preview, bounded by `maxChars`. */
   content: string;
-  /** Exact serialized prefix up to the defensive traversal-work ceiling. */
+  /** Code-point-aligned serialized prefix up to the traversal-work ceiling. */
   prefix: string;
   /** Exact length, or `Number.MAX_SAFE_INTEGER` when traversal was capped. */
   originalChars: number;
@@ -505,6 +506,10 @@ function materializeSegmentedStringBuffer(
   return segments.join('');
 }
 
+/**
+ * Retains exact code-unit prefixes internally. Trimming surrogate edges here
+ * would let later chunks fill the gap and corrupt the prefix; trim on exposure.
+ */
 function appendSerializedChunk(
   collector: StructuredSerializationCollector,
   chunk: string
@@ -953,7 +958,7 @@ function formatBoundedStructuredContent(
   suffix: string
 ): string {
   if (collector.totalChars <= maxChars) {
-    return prefix.slice(0, collector.totalChars);
+    return sliceWithoutSplittingSurrogates(prefix, 0, collector.totalChars);
   }
 
   const indicator = collector.work.exceeded
@@ -962,10 +967,13 @@ function formatBoundedStructuredContent(
       `${maxChars} limit] …\n\n`;
   const available = maxChars - indicator.length;
   if (available <= 0) {
-    return prefix.slice(0, maxChars);
+    return sliceWithoutSplittingSurrogates(prefix, 0, maxChars);
   }
   if (available < 200) {
-    return prefix.slice(0, available) + indicator.trimEnd();
+    return (
+      sliceWithoutSplittingSurrogates(prefix, 0, available) +
+      indicator.trimEnd()
+    );
   }
 
   const headSize = Math.ceil(available * 0.7);
@@ -982,7 +990,11 @@ function formatBoundedStructuredContent(
     tailStart = tailNewline + 1;
   }
 
-  return prefix.slice(0, headEnd) + indicator + suffix.slice(tailStart);
+  return (
+    sliceWithoutSplittingSurrogates(prefix, 0, headEnd) +
+    indicator +
+    sliceWithoutSplittingSurrogates(suffix, tailStart)
+  );
 }
 
 /**
@@ -1036,7 +1048,7 @@ export function serializeStructuredValueBounded(
       prefix,
       suffix
     ),
-    prefix: prefix.slice(0, normalizedPrefixChars),
+    prefix: sliceWithoutSplittingSurrogates(prefix, 0, normalizedPrefixChars),
     originalChars,
     truncated:
       collector.work.exceeded || collector.totalChars > normalizedMaxChars,
@@ -1931,7 +1943,11 @@ function serializeDenseTextBlocksWithinLimit(
     }
     preview += textBlocks[i].text.slice(0, available - preview.length);
   }
-  return (preview + indicator).slice(0, normalizedMaxChars);
+  return sliceWithoutSplittingSurrogates(
+    sliceWithoutSplittingSurrogates(preview, 0) + indicator,
+    0,
+    normalizedMaxChars
+  );
 }
 
 export type CompactToolContentResult = {

package/src/utils/truncation.ts

@@ -5,6 +5,22 @@
  * consuming the entire context window.
  */
 
+/** Slices by UTF-16 code units, dropping orphaned surrogate halves at either edge. */
+export function sliceWithoutSplittingSurrogates(
+  value: string,
+  start: number,
+  end?: number
+): string {
+  const sliced = value.slice(start, end);
+  const first = sliced.charCodeAt(0);
+  const last = sliced.charCodeAt(sliced.length - 1);
+  const trimStart = first >= 0xdc00 && first <= 0xdfff;
+  const trimEnd = last >= 0xd800 && last <= 0xdbff;
+  return trimStart || trimEnd
+    ? sliced.slice(trimStart ? 1 : 0, sliced.length - (trimEnd ? 1 : 0))
+    : sliced;
+}
+
 /**
  * Absolute hard cap on tool result length (characters).
  * Even if the model has a 1M-token context, a single tool result
@@ -85,7 +101,9 @@ export function truncateToolInput(
 
   if (available < 100) {
     return {
-      _truncated: serialized.slice(0, maxChars) + indicator.trimEnd(),
+      _truncated:
+        sliceWithoutSplittingSurrogates(serialized, 0, maxChars) +
+        indicator.trimEnd(),
       _originalChars: serialized.length,
     };
   }
@@ -95,9 +113,9 @@ export function truncateToolInput(
 
   return {
     _truncated:
-      serialized.slice(0, headSize) +
+      sliceWithoutSplittingSurrogates(serialized, 0, headSize) +
       indicator +
-      serialized.slice(serialized.length - tailSize),
+      sliceWithoutSplittingSurrogates(serialized, serialized.length - tailSize),
     _originalChars: serialized.length,
   };
 }
@@ -126,12 +144,15 @@ export function truncateToolResultContent(
   const indicator = `\n\n… [truncated: ${content.length} chars exceeded ${maxChars} limit] …\n\n`;
   const available = maxChars - indicator.length;
   if (available <= 0) {
-    return content.slice(0, maxChars);
+    return sliceWithoutSplittingSurrogates(content, 0, maxChars);
   }
 
   // When budget is too small for a meaningful tail, fall back to head-only
   if (available < 200) {
-    return content.slice(0, available) + indicator.trimEnd();
+    return (
+      sliceWithoutSplittingSurrogates(content, 0, available) +
+      indicator.trimEnd()
+    );
   }
 
   const headSize = Math.ceil(available * 0.7);
@@ -150,7 +171,11 @@ export function truncateToolResultContent(
     tailStart = tailNewline + 1;
   }
 
-  return content.slice(0, headEnd) + indicator + content.slice(tailStart);
+  return (
+    sliceWithoutSplittingSurrogates(content, 0, headEnd) +
+    indicator +
+    sliceWithoutSplittingSurrogates(content, tailStart)
+  );
 }
 
 /** Absolute hard cap on a single tool-call input (characters). */