@librechat/agents 3.3.0 → 3.3.1

package/dist/cjs/graphs/Graph.cjs

@@ -18,6 +18,7 @@ const require_anthropicToolCache = require("../messages/anthropicToolCache.cjs")
 const require_content = require("../messages/content.cjs");
 const require_tools = require("../messages/tools.cjs");
 const require_reducer = require("../messages/reducer.cjs");
+const require_recency = require("../messages/recency.cjs");
 require("../messages/index.cjs");
 const require_graph = require("../utils/graph.cjs");
 const require_llm = require("../utils/llm.cjs");
@@ -26,7 +27,11 @@ const require_toolOutputReferences = require("../tools/toolOutputReferences.cjs"
 const require_events$1 = require("../events.cjs");
 const require_run = require("../utils/run.cjs");
 require("../utils/index.cjs");
-const require_toolCache = require("../llm/openrouter/toolCache.cjs");
+const require_contextOverflowRecovery = require("../llm/contextOverflowRecovery.cjs");
+const require_toolCache = require("../llm/bedrock/toolCache.cjs");
+const require_init = require("../llm/init.cjs");
+const require_invoke = require("../llm/invoke.cjs");
+const require_toolCache$1 = require("../llm/openrouter/toolCache.cjs");
 const require_LocalCodingTools = require("../tools/local/LocalCodingTools.cjs");
 const require_CloudflareSandboxTools = require("../tools/cloudflare/CloudflareSandboxTools.cjs");
 require("../tools/cloudflare/index.cjs");
@@ -35,9 +40,6 @@ require("../tools/local/index.cjs");
 const require_ToolNode = require("../tools/ToolNode.cjs");
 const require_SubagentExecutor = require("../tools/subagent/SubagentExecutor.cjs");
 require("../tools/subagent/index.cjs");
-const require_toolCache$1 = require("../llm/bedrock/toolCache.cjs");
-const require_init = require("../llm/init.cjs");
-const require_invoke = require("../llm/invoke.cjs");
 const require_SubagentTool = require("../tools/SubagentTool.cjs");
 const require_index$6 = require("../summarization/index.cjs");
 const require_request = require("../llm/request.cjs");
@@ -161,6 +163,33 @@ function clearCurrentDeltaStepMarkers({ graph, metadata }) {
 		graph.reasoningStepHasDeltas.delete(stepId);
 	}
 }
+/**
+* The completion allowance the caller configured, under whichever key the
+* provider's client uses. Providers count it against the same ceiling as the
+* prompt, so overflow recovery has to reserve it when the error did not
+* itemize the total.
+*/
+function getConfiguredCompletionTokens(clientOptions) {
+	const options = clientOptions;
+	for (const value of [options?.maxTokens, options?.maxOutputTokens]) if (typeof value === "number" && Number.isFinite(value) && value > 0) return value;
+}
+/**
+* Our own estimate of the prompt that was actually sent, derived from the
+* pre-invoke usage snapshot. Used to corroborate ambiguous provider errors
+* and to measure how far our token accounting sits from the provider's.
+*/
+function getEstimatedPromptTokens(contextUsage) {
+	const budget = contextUsage?.contextBudget;
+	const remaining = contextUsage?.remainingContextTokens;
+	if (budget == null || remaining == null || !Number.isFinite(budget) || !Number.isFinite(remaining)) return;
+	const used = budget - remaining;
+	return used > 0 ? used : void 0;
+}
+function minDefined(left, right) {
+	if (left == null) return right;
+	if (right == null) return left;
+	return Math.min(left, right);
+}
 async function dispatchMessageCreationStep({ graph, stepKey, messageId, metadata }) {
 	await graph.dispatchRunStep(stepKey, {
 		type: "message_creation",
@@ -457,9 +486,13 @@ var StandardGraph = class StandardGraph extends Graph {
 	overrideModel;
 	/** Optional compile options passed into workflow.compile() */
 	compileOptions;
+	/** Whether the workflow was actually compiled with a checkpointer. */
+	hasCompiledCheckpointer = false;
 	messages = [];
 	/** Cached run messages preserved before clearHeavyState() so getRunMessages() works after cleanup. */
 	cachedRunMessages;
+	/** Checkpoint scope whose messages match index-keyed tool snapshots. */
+	originalToolContentCheckpointScope;
 	runId;
 	/**
 	* Boundary between historical messages (loaded from conversation state)
@@ -498,7 +531,7 @@ var StandardGraph = class StandardGraph extends Graph {
 		}
 		this.defaultAgentId = agents[0].agentId;
 	}
-	resetValues(keepContent) {
+	resetValues(keepContent, checkpointScope) {
 		this.messages = [];
 		this.cachedRunMessages = void 0;
 		this.config = require_graph.resetIfNotEmpty(this.config, void 0);
@@ -525,14 +558,18 @@ var StandardGraph = class StandardGraph extends Graph {
 		this.reasoningStepHasDeltas = require_graph.resetIfNotEmpty(this.reasoningStepHasDeltas, /* @__PURE__ */ new Set());
 		this.prelimMessageIdsByStepKey = require_graph.resetIfNotEmpty(this.prelimMessageIdsByStepKey, /* @__PURE__ */ new Map());
 		this.invokedToolIds = require_graph.resetIfNotEmpty(this.invokedToolIds, void 0);
-		for (const context of this.agentContexts.values()) context.reset();
+		const hasScopedCheckpoint = this.hasCompiledCheckpointer && checkpointScope != null && checkpointScope !== "";
+		const preserveOriginalToolContent = hasScopedCheckpoint && this.originalToolContentCheckpointScope === checkpointScope;
+		for (const context of this.agentContexts.values()) context.reset({ preserveOriginalToolContent });
+		this.originalToolContentCheckpointScope = hasScopedCheckpoint ? checkpointScope : void 0;
 	}
 	clearHeavyState() {
 		this.cachedRunMessages = this.messages.slice(this.startIndex);
 		super.clearHeavyState();
 		this.messages = [];
 		this.overrideModel = void 0;
-		for (const context of this.agentContexts.values()) context.reset();
+		const preserveOriginalToolContent = this.hasCompiledCheckpointer && this.originalToolContentCheckpointScope != null;
+		for (const context of this.agentContexts.values()) context.reset({ preserveOriginalToolContent });
 	}
 	getRunStep(stepId) {
 		const index = this.contentIndexMap.get(stepId);
@@ -767,6 +804,49 @@ var StandardGraph = class StandardGraph extends Graph {
 		this.signal.removeEventListener("abort", client.abortHandler);
 		client.abortHandler = void 0;
 	}
+	/**
+	* Applies a context-overflow recovery plan and hands control to the
+	* summarize node, which compacts and then routes straight back here for a
+	* retry against the corrected budget.
+	*
+	* Returning the detour rather than rethrowing is the whole point: the
+	* caller never sees the provider's rejection, only a slightly longer turn.
+	*/
+	beginOverflowRecovery({ recovery, agentContext, agentId, config, originalToolContent, estimatedPromptTokens }) {
+		const previousBudget = agentContext.maxContextTokens;
+		/**
+		* Deterministic compaction first. Re-pruning against the corrected budget
+		* raises context pressure, which is what drives the pruner's tool-output
+		* truncation and observation masking — no model call, no cost, and no
+		* message content lost. A summarization call is held back until that has
+		* been tried and the provider rejected the prompt again.
+		*/
+		const allowSummarization = agentContext.shouldSummarizeOverflow();
+		agentContext.preserveOriginalToolContent(originalToolContent);
+		agentContext.applyContextBudgetCorrection(recovery.budgetTokens, estimatedPromptTokens);
+		agentContext.applyObservedOverflowCalibration(recovery.info.provider, recovery.observedCalibrationRatio);
+		require_events.emitAgentLog(config, "warn", "graph", "Provider rejected the prompt as too large — compacting and retrying", {
+			kind: recovery.info.kind,
+			previousBudget,
+			recoveredBudget: recovery.budgetTokens,
+			providerReportedLimit: recovery.info.limitTokens,
+			providerReportedTokens: recovery.info.requestedTokens,
+			providerReportedPromptTokens: recovery.info.promptTokens,
+			observedCalibrationRatio: recovery.observedCalibrationRatio,
+			detectedBy: recovery.info.source,
+			attempt: agentContext.overflowRecoveryAttempts,
+			compaction: allowSummarization ? "summarize" : "compress"
+		}, {
+			runId: this.runId,
+			agentId
+		}, { force: true });
+		return { summarizationRequest: {
+			remainingContextTokens: 0,
+			agentId: agentId || agentContext.agentId,
+			reason: "overflow",
+			allowSummarization
+		} };
+	}
 	createCallModel(agentId = "default") {
 		return async (state, config) => {
 			const agentContext = this.agentContexts.get(agentId);
@@ -794,10 +874,10 @@ var StandardGraph = class StandardGraph extends Graph {
 			*/
 			let toolsForBinding = rawToolsForBinding;
 			if (agentContext.provider === "anthropic" && agentContext.clientOptions?.promptCache === true) toolsForBinding = require_anthropicToolCache.partitionAndMarkAnthropicToolCache(rawToolsForBinding, require_anthropicToolCache.makeIsDeferred(agentContext.toolDefinitions), require_cache.resolvePromptCacheTtl(agentContext.clientOptions?.promptCacheTtl)) ?? rawToolsForBinding;
-			else if (agentContext.provider === "openrouter" && agentContext.clientOptions?.promptCache === true) toolsForBinding = require_toolCache.partitionAndMarkOpenRouterToolCache(rawToolsForBinding, require_anthropicToolCache.makeIsDeferred(agentContext.toolDefinitions), require_cache.resolvePromptCacheTtl(agentContext.clientOptions?.promptCacheTtl)) ?? rawToolsForBinding;
+			else if (agentContext.provider === "openrouter" && agentContext.clientOptions?.promptCache === true) toolsForBinding = require_toolCache$1.partitionAndMarkOpenRouterToolCache(rawToolsForBinding, require_anthropicToolCache.makeIsDeferred(agentContext.toolDefinitions), require_cache.resolvePromptCacheTtl(agentContext.clientOptions?.promptCacheTtl)) ?? rawToolsForBinding;
 			else if (agentContext.provider === "bedrock" && agentContext.clientOptions?.promptCache === true) {
 				const bedrockModel = agentContext.clientOptions?.model;
-				if (bedrockModel == null || require_cache.supportsBedrockToolCache(bedrockModel)) toolsForBinding = require_toolCache$1.partitionAndMarkBedrockToolCache(rawToolsForBinding, require_anthropicToolCache.makeIsDeferred(agentContext.toolDefinitions)) ?? rawToolsForBinding;
+				if (bedrockModel == null || require_cache.supportsBedrockToolCache(bedrockModel)) toolsForBinding = require_toolCache.partitionAndMarkBedrockToolCache(rawToolsForBinding, require_anthropicToolCache.makeIsDeferred(agentContext.toolDefinitions)) ?? rawToolsForBinding;
 			}
 			let model = this.overrideModel ?? require_init.initializeModel({
 				tools: toolsForBinding,
@@ -810,6 +890,12 @@ var StandardGraph = class StandardGraph extends Graph {
 			this.config = config;
 			let messagesToUse = messages;
 			let contextUsage = null;
+			/**
+			* Held outside the prune block so overflow recovery — which detours to
+			* the summarize node from the invoke catch below — can preserve the
+			* same masking record the configured trigger preserves.
+			*/
+			let prunedOriginalToolContent;
 			if (!agentContext.pruneMessages && agentContext.tokenCounter && agentContext.maxContextTokens != null) agentContext.pruneMessages = require_prune.createPruneMessages({
 				startIndex: agentContext.indexTokenCountMap[0] != null ? this.startIndex : 0,
 				provider: agentContext.provider,
@@ -830,12 +916,22 @@ var StandardGraph = class StandardGraph extends Graph {
 				}
 			});
 			if (agentContext.pruneMessages) {
-				const { context, indexTokenCountMap, messagesToRefine, prePruneContextTokens, remainingContextTokens, originalToolContent, calibrationRatio, resolvedInstructionOverhead, contextBudget, effectiveInstructionTokens } = agentContext.pruneMessages({
+				const { context, indexTokenCountMap, messagesToRefine, prePruneContextTokens, remainingContextTokens, newOriginalToolContent, calibrationRatio, resolvedInstructionOverhead, contextBudget, effectiveInstructionTokens } = agentContext.pruneMessages({
 					messages,
 					usageMetadata: agentContext.currentUsage,
 					lastCallUsage: agentContext.lastCallUsage,
 					totalTokensFresh: agentContext.totalTokensFresh
 				});
+				prunedOriginalToolContent = newOriginalToolContent;
+				/**
+				* Masking rewrites tool content in `state.messages` in place, so this
+				* map is the only surviving copy of the full output. Persist it on
+				* every prune, not just when a summary is about to be written — the
+				* pruner closure that produced it is discarded on the next reset, and
+				* with it any chance of a later summary restoring the real content.
+				* AgentContext bounds what accumulates.
+				*/
+				agentContext.preserveOriginalToolContent(newOriginalToolContent);
 				agentContext.indexTokenCountMap = indexTokenCountMap;
 				if (calibrationRatio != null && calibrationRatio > 0) agentContext.calibrationRatio = calibrationRatio;
 				if (resolvedInstructionOverhead != null) {
@@ -882,31 +978,6 @@ var StandardGraph = class StandardGraph extends Graph {
 						remainingContextTokens,
 						messagesToRefineCount: messagesToRefine.length
 					})) {
-						if (originalToolContent != null && originalToolContent.size > 0)
- /**
-						* Merge — never overwrite — the pruner's masking record
-						* into pendingOriginalToolContent.  Carry-over entries
-						* from a prior summarize (preserved by the recency
-						* window for masked tool messages still in the tail) and
-						* the current pruner's new entries are both keyed by
-						* indices in the current `state.messages`, so a key-wise
-						* union is correct.  Overwriting would discard the
-						* carry-over and reduce summary fidelity when those
-						* masked tail messages eventually move into the head.
-						*/
-						if (agentContext.pendingOriginalToolContent == null) agentContext.pendingOriginalToolContent = originalToolContent;
-						else {
-							for (const [idx, content] of originalToolContent) agentContext.pendingOriginalToolContent.set(idx, content);
-							/**
-							* Re-apply the per-store char cap after the union.  The
-							* pruner enforces ORIGINAL_CONTENT_MAX_CHARS inside its
-							* own map via the onContentStored callback, but a
-							* key-wise merge with recency carry-over bypasses that
-							* accounting and could let the merged map grow without
-							* bound across long sessions.
-							*/
-							require_prune.enforceOriginalContentCap(agentContext.pendingOriginalToolContent);
-						}
 						require_events.emitAgentLog(config, "info", "graph", "Summarization triggered", void 0, {
 							runId: this.runId,
 							agentId
@@ -1137,17 +1208,115 @@ var StandardGraph = class StandardGraph extends Graph {
 					graph: this,
 					metadata
 				});
-				result = await require_langfuseRuntimeScope.withLangfuseRuntimeScope(require_langfuseRuntimeScope.resolveLangfuseRuntimeScope({
-					runLangfuse: this.langfuse,
-					langfuseOverlay: agentContext.langfuse
-				}), () => require_invoke.tryFallbackProviders({
-					fallbacks,
-					tools: agentContext.tools,
-					messages: finalMessages,
-					config: invokeConfig,
-					primaryError,
-					context: this
-				}));
+				/**
+				* A context overflow is a deterministic consequence of the payload,
+				* not a provider being unavailable — so it is answered by compacting
+				* and retrying rather than by re-sending the same oversized prompt
+				* down the fallback chain. Fallbacks still run for every other
+				* failure, and for an overflow whose recovery budget is spent.
+				*/
+				/**
+				* Compaction has to have something to work with. Without a token
+				* counter there is no pruner, and with summarization disabled the
+				* summarize node deliberately no-ops — so in that combination the
+				* retry would resend a byte-identical prompt. Skipping the detour
+				* keeps the original error and one round trip instead of three.
+				*/
+				const estimatedPromptTokens = getEstimatedPromptTokens(contextUsage);
+				/**
+				* A previous correction that left the prompt no smaller proves this
+				* state has nothing left to compact — an emptied message list whose
+				* content rides along in an injected summary, for instance. Measuring
+				* that beats trying to predict every such configuration.
+				*/
+				const recoveryStalled = agentContext.overflowRecoveryStalled(estimatedPromptTokens);
+				const canSummarizeOverflow = agentContext.summarizationEnabled === true && require_recency.splitAtRecencyBoundary(messages, {
+					turns: agentContext.summarizationConfig?.retainRecent?.turns ?? 2,
+					tokens: agentContext.summarizationConfig?.retainRecent?.tokens,
+					tokenCounter: agentContext.tokenCounter
+				}).head.length > 0;
+				const planRecovery = (error, attributedFallbackContext) => {
+					if (recoveryStalled) return null;
+					/**
+					* When the rejection came from a fallback, plan against *that*
+					* client: its window and output allowance are why it was configured
+					* as an alternative in the first place.
+					*/
+					const fallbackContext = attributedFallbackContext ?? require_invoke.getFallbackErrorContext(error);
+					const recovery = require_contextOverflowRecovery.planContextOverflowRecovery({
+						error,
+						provider: fallbackContext?.provider ?? agentContext.provider,
+						maxContextTokens: fallbackContext?.maxContextTokens ?? agentContext.maxContextTokens,
+						estimatedPromptTokens,
+						calibrationRatio: agentContext.calibrationRatio,
+						instructionTokens: agentContext.instructionTokens,
+						canSummarize: agentContext.summarizationEnabled === true,
+						configuredCompletionTokens: getConfiguredCompletionTokens(fallbackContext?.clientOptions ?? agentContext.clientOptions),
+						attemptsSoFar: agentContext.overflowRecoveryAttempts
+					});
+					if (recovery == null) return null;
+					const translatedRecovery = fallbackContext != null ? {
+						...recovery,
+						budgetTokens: minDefined(require_contextOverflowRecovery.getBlindRecoveryBudget(agentContext.maxContextTokens), require_contextOverflowRecovery.translateRecoveryBudget(recovery.budgetTokens, recovery.observedCalibrationRatio ?? 5, agentContext.calibrationRatio)),
+						observedCalibrationRatio: void 0
+					} : recovery;
+					return canSummarizeOverflow || agentContext.tokenCounter != null && translatedRecovery.budgetTokens != null ? translatedRecovery : null;
+				};
+				const recovery = planRecovery(primaryError);
+				if (recovery != null) return this.beginOverflowRecovery({
+					recovery,
+					agentContext,
+					agentId,
+					config,
+					originalToolContent: prunedOriginalToolContent,
+					estimatedPromptTokens
+				});
+				/**
+				* A fallback can reject the same prompt as too large even when the
+				* primary failed for an unrelated reason — a fallback with a smaller
+				* window is the obvious case. Planning against the exhausted-chain
+				* error keeps that path recoverable instead of surfacing it.
+				*/
+				try {
+					result = await require_langfuseRuntimeScope.withLangfuseRuntimeScope(require_langfuseRuntimeScope.resolveLangfuseRuntimeScope({
+						runLangfuse: this.langfuse,
+						langfuseOverlay: agentContext.langfuse
+					}), () => require_invoke.tryFallbackProviders({
+						fallbacks,
+						tools: agentContext.tools,
+						messages: finalMessages,
+						config: invokeConfig,
+						primaryError,
+						context: this,
+						/**
+						* Lets the chain recognise a fallback overflow whose signature
+						* carries no reason of its own (Vertex AI's bare 400) and
+						* surface it rather than a later unrelated failure.
+						*/
+						overflowContext: {
+							provider: agentContext.provider,
+							estimatedPromptTokens: getEstimatedPromptTokens(contextUsage),
+							maxContextTokens: agentContext.maxContextTokens
+						}
+					}));
+				} catch (fallbackError) {
+					const overflowCandidates = require_invoke.getFallbackOverflowCandidates(fallbackError);
+					let fallbackRecovery = null;
+					for (const candidate of overflowCandidates) {
+						fallbackRecovery = planRecovery(candidate.error, candidate.context);
+						if (fallbackRecovery != null) break;
+					}
+					if (overflowCandidates.length === 0) fallbackRecovery = planRecovery(fallbackError);
+					if (fallbackRecovery == null) throw fallbackError;
+					return this.beginOverflowRecovery({
+						recovery: fallbackRecovery,
+						agentContext,
+						agentId,
+						config,
+						originalToolContent: prunedOriginalToolContent,
+						estimatedPromptTokens
+					});
+				}
 			} finally {
 				await require_langfuse.disposeLangfuseHandler(langfuseHandler);
 			}
@@ -1386,9 +1555,13 @@ var StandardGraph = class StandardGraph extends Graph {
 				isMultiAgent: this.isMultiAgentGraph(),
 				hookRegistry: this.hookRegistry,
 				dispatchRunStep: async (runStep, nodeConfig) => {
+					const resolvedConfig = nodeConfig ?? this.config;
+					if (runStep.agentId != null) {
+						const groupId = this.resolveParallelGroupId(runStep.agentId, resolvedConfig?.metadata);
+						if (groupId != null) runStep.groupId = groupId;
+					}
 					this.contentData.push(runStep);
 					this.contentIndexMap.set(runStep.id, runStep.index);
-					const resolvedConfig = nodeConfig ?? this.config;
 					const handler = this.handlerRegistry?.getHandler("on_run_step");
 					if (handler) {
 						await handler.handle("on_run_step", runStep, resolvedConfig?.configurable, this);
@@ -1416,6 +1589,7 @@ var StandardGraph = class StandardGraph extends Graph {
 		})).addEdge(_langchain_langgraph.START, agentNode).addConditionalEdges(agentNode, routeMessage).addEdge(summarizeNode, agentNode).addEdge(toolNode, agentContext.toolEnd ? _langchain_langgraph.END : agentNode).compile();
 	}
 	createWorkflow() {
+		this.hasCompiledCheckpointer = this.compileOptions?.checkpointer != null;
 		const agentNode = this.createAgentNode(this.defaultAgentId);
 		return new _langchain_langgraph.StateGraph(_langchain_langgraph.Annotation.Root({ messages: (0, _langchain_langgraph.Annotation)({
 			reducer: (a, b) => {
@@ -1443,6 +1617,13 @@ var StandardGraph = class StandardGraph extends Graph {
 	* @returns undefined for StandardGraph (no parallel groups), or group number for MultiAgentGraph
 	*/
 	getParallelGroupIdForAgent(_agentId) {}
+	resolveParallelGroupId(agentId, metadata) {
+		if (metadata == null || !Object.prototype.hasOwnProperty.call(metadata, "__handoff_group_id")) return this.getParallelGroupIdForAgent(agentId);
+		const runtimeGroupId = metadata["__handoff_group_id"];
+		if (runtimeGroupId === null) return;
+		if (typeof runtimeGroupId === "number" && Number.isSafeInteger(runtimeGroupId) && runtimeGroupId > 0) return runtimeGroupId;
+		return this.getParallelGroupIdForAgent(agentId);
+	}
 	/**
 	* Dispatches a run step to the client, returns the step ID
 	*/
@@ -1468,7 +1649,7 @@ var StandardGraph = class StandardGraph extends Graph {
 			const agentContext = this.getAgentContext(metadata);
 			if (this.isMultiAgentGraph() && agentContext.agentId) {
 				runStep.agentId = agentContext.agentId;
-				const groupId = this.getParallelGroupIdForAgent(agentContext.agentId);
+				const groupId = this.resolveParallelGroupId(agentContext.agentId, metadata);
 				if (groupId != null) runStep.groupId = groupId;
 			}
 		} catch (_e) {}