@librechat/agents 3.8.9 → 3.9.1

package/dist/esm/messages/handoffCue.mjs

@@ -1,6 +1,30 @@
 import { stampSyntheticProviderMessage } from "./provenance.mjs";
 import { HumanMessage } from "@langchain/core/messages";
 //#region src/messages/handoffCue.ts
+const HANDOFF_CUE_MESSAGE_ID = "__handoff_cue_message_id";
+const INSTRUCTIONLESS_HANDOFF_CUE = "Continue as the receiving agent using the preceding user request and context.";
+function withInstructionlessHandoffCue(config, tail) {
+	return {
+		...config,
+		metadata: {
+			...config?.metadata,
+			[HANDOFF_CUE_MESSAGE_ID]: tail?.getType() === "ai" ? tail.id ?? null : null
+		}
+	};
+}
+function appendInstructionlessHandoffCue(messages, config) {
+	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"
+		}
+	}))];
+}
 const PREDECESSOR_HANDOFF_CUE = "[The assistant message above is the completed output of a previous agent. Respond now according to your own role and instructions.]";
 function appendPredecessorHandoffCue(messages, isRunProduced) {
 	const last = messages.at(-1);
@@ -21,6 +45,6 @@ function removePredecessorHandoffCue(messages) {
 	return messages.slice(0, -1);
 }
 //#endregion
-export { PREDECESSOR_HANDOFF_CUE, appendPredecessorHandoffCue, removePredecessorHandoffCue };
+export { INSTRUCTIONLESS_HANDOFF_CUE, PREDECESSOR_HANDOFF_CUE, appendInstructionlessHandoffCue, appendPredecessorHandoffCue, removePredecessorHandoffCue, withInstructionlessHandoffCue };
 
 //# sourceMappingURL=handoffCue.mjs.map

package/dist/esm/messages/handoffCue.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"handoffCue.mjs","names":[],"sources":["../../../src/messages/handoffCue.ts"],"mappings":";;;AAYA,MAAa,0BACX;AAyBF,SAAgB,4BACd,UACA,eACe;CACf,MAAM,OAAO,SAAS,GAAG,EAAE;CAC3B,IAAI,QAAQ,QAAQ,KAAK,QAAQ,MAAM,MACrC,OAAO;CAET,IAAI,iBAAiB,QAAQ,CAAC,cAAc,IAAI,GAC9C,OAAO;CAET,OAAO,CACL,GAAG,UACH,8BACE,IAAI,aAAa;EACf,SAAS;EACT,mBAAmB;GAAE,MAAM;GAAQ,QAAQ;GAAM,QAAQ;EAAU;CACrE,CAAC,CACH,CACF;AACF;AASA,SAAgB,4BACd,UACe;CACf,MAAM,OAAO,SAAS,GAAG,EAAE;CAC3B,IACE,QAAQ,QACR,KAAK,QAAQ,MAAM,WACnB,KAAK,kBAAkB,WAAW,aAClC,KAAK,YAAA,uIAEL,OAAO;CAET,OAAO,SAAS,MAAM,GAAG,EAAE;AAC7B"}
+{"version":3,"file":"handoffCue.mjs","names":[],"sources":["../../../src/messages/handoffCue.ts"],"mappings":";;;AAMA,MAAM,yBAAyB;AAC/B,MAAa,8BACX;AAKF,SAAgB,8BACd,QACA,MACgB;CAChB,OAAO;EACL,GAAG;EACH,UAAU;GACR,GAAG,QAAQ;IACV,yBACC,MAAM,QAAQ,MAAM,OAAQ,KAAK,MAAM,OAAQ;EACnD;CACF;AACF;AAMA,SAAgB,gCACd,UACA,QACe;CACf,MAAM,OAAO,SAAS,GAAG,EAAE;CAC3B,MAAM,WAAW,QAAQ,WAAW;CACpC,IACE,OAAO,aAAa,YACpB,aAAa,MACb,MAAM,QAAQ,MAAM,QACpB,KAAK,OAAO,UAEZ,OAAO;CAET,OAAO,CACL,GAAG,UACH,8BACE,IAAI,aAAa;EACf,SAAS;EACT,mBAAmB;GAAE,MAAM;GAAQ,QAAQ;GAAM,QAAQ;EAAU;CACrE,CAAC,CACH,CACF;AACF;AASA,MAAa,0BACX;AAyBF,SAAgB,4BACd,UACA,eACe;CACf,MAAM,OAAO,SAAS,GAAG,EAAE;CAC3B,IAAI,QAAQ,QAAQ,KAAK,QAAQ,MAAM,MACrC,OAAO;CAET,IAAI,iBAAiB,QAAQ,CAAC,cAAc,IAAI,GAC9C,OAAO;CAET,OAAO,CACL,GAAG,UACH,8BACE,IAAI,aAAa;EACf,SAAS;EACT,mBAAmB;GAAE,MAAM;GAAQ,QAAQ;GAAM,QAAQ;EAAU;CACrE,CAAC,CACH,CACF;AACF;AASA,SAAgB,4BACd,UACe;CACf,MAAM,OAAO,SAAS,GAAG,EAAE;CAC3B,IACE,QAAQ,QACR,KAAK,QAAQ,MAAM,WACnB,KAAK,kBAAkB,WAAW,aAClC,KAAK,YAAA,uIAEL,OAAO;CAET,OAAO,SAAS,MAAM,GAAG,EAAE;AAC7B"}

package/dist/esm/messages/index.mjs

@@ -5,6 +5,7 @@ import "./toolHistoryProjection.mjs";
 import "./core.mjs";
 import "./fading.mjs";
 import "./injected.mjs";
+import "./handoffCue.mjs";
 import "./ids.mjs";
 import "./contextPruningSettings.mjs";
 import "./contextPruning.mjs";
@@ -15,7 +16,6 @@ import "./format.mjs";
 import "./anthropicToolCache.mjs";
 import "./tools.mjs";
 import "./alternation.mjs";
-import "./handoffCue.mjs";
 import "./reducer.mjs";
 import "./recency.mjs";
 import "./assistantPhase.mjs";

package/dist/types/llm/prepareProviderRequest.d.ts

@@ -1,8 +1,8 @@
 import type { BaseMessage } 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';
 declare const preparedProviderRequestBrand: unique symbol;
 export type ProviderMessageProjectionMode = 'chat-messages' | 'openai-responses';
 export interface ProviderPayloadMeasurement {

package/dist/types/messages/handoffCue.d.ts

@@ -1,4 +1,15 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
+export declare 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 declare function withInstructionlessHandoffCue(config: RunnableConfig | undefined, tail?: BaseMessage): RunnableConfig;
+/** 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 declare function appendInstructionlessHandoffCue(messages: BaseMessage[], config?: RunnableConfig): BaseMessage[];
 /**
  * Bracketed-meta convention, like the handoff path's
  * `[Processed tool result and transferring to …]` bridge. The wording makes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.8.9",
+  "version": "3.9.1",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"
@@ -359,7 +359,7 @@
     "mongodb": "^6.21.0",
     "mongodb-memory-server-core": "^11.2.0",
     "prettier": "^3.6.2",
-    "ts-jest": "^29.4.6",
+    "ts-jest": "^29.4.12",
     "tsc-alias": "^1.8.10",
     "tsdown": "^0.22.2",
     "tslib": "^2.6.3",

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/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