@librechat/agents 3.3.11 → 3.3.12

package/dist/cjs/graphs/Graph.cjs

@@ -1,3 +1,4 @@
+const require_misc = require("../utils/misc.cjs");
 const require_langfuseConfig = require("../langfuseConfig.cjs");
 const require_langfuseRuntimeScope = require("../langfuseRuntimeScope.cjs");
 const require_langfuse = require("../langfuse.cjs");
@@ -27,6 +28,7 @@ const require_reducer = require("../messages/reducer.cjs");
 const require_recency = require("../messages/recency.cjs");
 require("../messages/index.cjs");
 const require_handlers = require("../tools/handlers.cjs");
+const require_streamLimits = require("../llm/streamLimits.cjs");
 const require_toolOutputReferences = require("../tools/toolOutputReferences.cjs");
 const require_llm = require("../utils/llm.cjs");
 const require_toolCache = require("../llm/bedrock/toolCache.cjs");
@@ -68,17 +70,6 @@ const EMPTY_PREEMPT_BOUNDARY = {
 	messages: [],
 	preventContinuation: false
 };
-/**
-* One signal that fires when either input fires. `AbortSignal.any` is skipped
-* when the inputs collapse to a single signal — the composite is a fresh
-* object per call, and the common cases (one channel, or the host reusing the
-* same controller for both) don't need one.
-*/
-function composeAbortSignals(a, b) {
-	if (a == null || a === b) return b;
-	if (b == null) return a;
-	return AbortSignal.any([a, b]);
-}
 /** Minimum relative variance before calibrated toolSchemaTokens overrides current value. */
 const CALIBRATION_VARIANCE_THRESHOLD = .15;
 function createToolHandlerRegistry(source) {
@@ -575,6 +566,62 @@ var StandardGraph = class StandardGraph extends Graph {
 	/** See {@link t.StandardGraphInput.preemption}. */
 	preemption;
 	/**
+	* Stream circuit breakers, resolved once from
+	* {@link t.StandardGraphInput.streamLimits}. The stream handler enforces
+	* these on every streamed chunk event.
+	*/
+	streamLimits;
+	/**
+	* Cumulative streamed argument bytes per in-flight tool call, keyed by
+	* generation key + chunk index (see `resolveGenerationKey`). Per-run
+	* accumulation state, cleared by both reset paths.
+	*/
+	streamedToolCallArgTallies = /* @__PURE__ */ new Map();
+	/** Streamed chunk events per model generation, keyed by generation key. */
+	streamDeltaEventCounts = /* @__PURE__ */ new Map();
+	/** Per-chunk-object, per-generation charge balances (lazily created; see
+	* `StreamLimitState`). Reinitialized by both reset paths: a model may
+	* retain and re-yield one mutable chunk object, whose nested map would
+	* otherwise grow by one attempt-stamped entry per model call for the
+	* graph's lifetime. */
+	streamLimitChargeCredits;
+	/** Run-scoped breaker abort: composed into every model invocation and
+	* every SubagentExecutor child signal, and tripped when a stream circuit
+	* breaker fires anywhere in the run, so parallel agent nodes' in-flight
+	* provider calls and subagents stop consuming quota while the rejection
+	* propagates. Recreated by both reset paths — the abort is one-way within
+	* a run, and a reused graph must start its next run unaborted. */
+	breakerAbort = new AbortController();
+	/** Incremented whenever `breakerAbort` is replaced. Stamped into each
+	* model attempt's metadata ({@link STREAM_LIMIT_EPOCH_KEY}) so the stream
+	* handler's consumer-side trip binds to the run that produced the event
+	* rather than whichever controller is live when a straggling chunk is
+	* finally handled. */
+	breakerEpoch = 0;
+	/** Immutable snapshot of the run's breaker identity (epoch + controller),
+	* replaced as ONE object whenever `resetValues` installs a fresh
+	* controller. Sites that pause across awaits capture it at entry and
+	* revalidate by REFERENCE afterwards — a single identity comparison
+	* proves no reset happened while suspended, where separate epoch and
+	* controller reads could interleave with one. */
+	runScope = Object.freeze({
+		epoch: 0,
+		controller: this.breakerAbort
+	});
+	/** Generation keys of model attempts still in flight (see
+	* `StreamLimitState.activeStreamLimitGenerations`). Lazily created by the
+	* attempt lease; spans resets on purpose. */
+	activeStreamLimitGenerations;
+	/** The stream-limit error behind an already-fired breaker, whether this
+	* graph's own controller tripped or a parent run's breaker arrived through
+	* the composed constructor signal (child graphs own separate controllers).
+	* Providers can translate either abort into a generic error, and recovery
+	* paths must not run in that state. */
+	resolveTrippedBreakerReason(breakerSignal = this.breakerAbort.signal) {
+		if (breakerSignal.aborted && breakerSignal.reason instanceof require_streamLimits.StreamLimitExceededError) return breakerSignal.reason;
+		if (this.signal?.aborted === true && this.signal.reason instanceof require_streamLimits.StreamLimitExceededError) return this.signal.reason;
+	}
+	/**
 	* Seals charged against `preemption.maxSeals`. Per-turn: cleared by both
 	* reset paths so a fresh turn gets a fresh budget, while a HITL resume —
 	* which skips `resetValues` — keeps what it had left.
@@ -619,7 +666,7 @@ var StandardGraph = class StandardGraph extends Graph {
 	* another's turn.
 	*/
 	pendingPreemptReturn = /* @__PURE__ */ new Set();
-	constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, subagentUsageSink, subagentScope, preemption }) {
+	constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, subagentUsageSink, subagentScope, preemption, streamLimits }) {
 		super();
 		this.runId = runId;
 		this.langfuseScopeRunId = `${runId ?? "graph"}:${(0, nanoid.nanoid)()}`;
@@ -628,6 +675,7 @@ var StandardGraph = class StandardGraph extends Graph {
 		this.subagentUsageSink = subagentUsageSink;
 		this.subagentScope = subagentScope === true;
 		this.preemption = preemption;
+		this.streamLimits = require_streamLimits.resolveStreamLimits(streamLimits);
 		if (agents.length === 0) throw new Error("At least one agent configuration is required");
 		for (const agentConfig of agents) {
 			const agentContext = require_AgentContext.AgentContext.fromConfig(agentConfig, tokenCounter, indexTokenCountMap);
@@ -658,6 +706,28 @@ var StandardGraph = class StandardGraph extends Graph {
 		this.clearEagerEventToolUsageCounts();
 		this.eagerEventToolCallChunks.clear();
 		this.eagerEventToolSuppressions.clear();
+		/** Grace sweep instead of a clear: producer loops of straggling
+		* attempts use these maps directly and sit outside the consumer-only
+		* epoch gate — clearing would hand a cancellation-ignoring provider a
+		* fresh allowance at every run start. Entries from the epoch that is
+		* ending survive exactly one reset so those stragglers stay on their
+		* original budgets; older entries are removed. */
+		require_streamLimits.sweepStaleStreamLimitEntries(this.streamedToolCallArgTallies, this.breakerEpoch, this.activeStreamLimitGenerations);
+		require_streamLimits.sweepStaleStreamLimitEntries(this.streamDeltaEventCounts, this.breakerEpoch, this.activeStreamLimitGenerations);
+		this.streamLimitChargeCredits = void 0;
+		/** Run-start is the only safe replacement point for the breaker:
+		* end-of-run cleanup must leave it in place so straggling parallel
+		* children from the failed run cannot start on a fresh signal.
+		* Replaced UNCONDITIONALLY here — a run that failed on an ordinary
+		* error leaves the controller un-aborted, and stragglers still settling
+		* hold their entry-time capture of it; a late stream-limit trip on that
+		* old controller must not cancel the run starting now. */
+		this.breakerAbort = new AbortController();
+		this.breakerEpoch += 1;
+		this.runScope = Object.freeze({
+			epoch: this.breakerEpoch,
+			controller: this.breakerAbort
+		});
 		this.handlerDispatchedStepIds = require_graph.resetIfNotEmpty(this.handlerDispatchedStepIds, /* @__PURE__ */ new Set());
 		this.handlerDispatchedEventCounts = require_graph.resetIfNotEmpty(this.handlerDispatchedEventCounts, /* @__PURE__ */ new Map());
 		this.messageIdsByStepKey = require_graph.resetIfNotEmpty(this.messageIdsByStepKey, /* @__PURE__ */ new Map());
@@ -679,6 +749,21 @@ var StandardGraph = class StandardGraph extends Graph {
 		super.clearHeavyState();
 		this.messages = [];
 		this.overrideModel = void 0;
+		/** Stream-limit accounting (argument tallies, event counts, charge
+		* credits) deliberately SURVIVES cleanup: this runs in `processStream`'s
+		* finally, which an ordinary parallel-branch failure reaches while
+		* sibling attempts are still unwinding on the retained breaker — a
+		* cancellation-ignoring provider's late chunks would otherwise recreate
+		* their budgets from zero and stream another full allowance. The maps
+		* are bounded by in-flight call sizes and `resetValues` clears them at
+		* the next run start, where the epoch bump already drops stamped
+		* straggler events before accounting. */
+		/** Deliberately NOT recreating a tripped breakerAbort here: this runs in
+		* `processStream`'s cleanup, which a rejected parallel batch reaches
+		* while sibling subagents can still be pre-invoke — a fresh controller
+		* would hand them an un-aborted signal and let provider requests start
+		* after the run already failed. `resetValues` recreates it when the next
+		* run begins. */
 		/**
 		* Turn state only. The reported totals must outlive cleanup — this runs
 		* in `processStream`'s `finally`, and the host reads `getPreemptStats()`
@@ -850,9 +935,13 @@ var StandardGraph = class StandardGraph extends Graph {
 		return keyList.some((key) => key === void 0);
 	}
 	getRunMessages() {
-		if (this.messages == null) return this.cachedRunMessages;
-		if (this.messages.length === 0 && this.cachedRunMessages != null) return this.cachedRunMessages;
-		return this.messages.slice(this.startIndex);
+		/** Runtime-honest widening: a disposed-but-cached graph (HITL
+		* resume/reconnect through a WeakRef cache) can carry null here despite
+		* the field type. */
+		const messages = this.messages;
+		if (messages == null) return this.cachedRunMessages;
+		if (messages.length === 0 && this.cachedRunMessages != null) return this.cachedRunMessages;
+		return messages.slice(this.startIndex);
 	}
 	getDiscoveredTools(agentId) {
 		if (agentId != null) {
@@ -880,8 +969,9 @@ var StandardGraph = class StandardGraph extends Graph {
 		return typeof id === "string" && id !== "" && this.runProducedAiMessageIds.has(id);
 	}
 	getContentParts() {
-		if (this.messages == null) return;
-		return require_core.convertMessagesToContent(this.messages.slice(this.startIndex));
+		const messages = this.messages;
+		if (messages == null) return;
+		return require_core.convertMessagesToContent(messages.slice(this.startIndex));
 	}
 	getCalibrationRatio() {
 		return this.agentContexts.get(this.defaultAgentId)?.calibrationRatio ?? 1;
@@ -897,9 +987,10 @@ var StandardGraph = class StandardGraph extends Graph {
 	* Get all run steps, optionally filtered by agent ID
 	*/
 	getRunSteps(agentId) {
-		if (this.contentData == null) return [];
-		if (agentId == null || agentId === "") return [...this.contentData];
-		return this.contentData.filter((step) => step.agentId === agentId);
+		const contentData = this.contentData;
+		if (contentData == null) return [];
+		if (agentId == null || agentId === "") return [...contentData];
+		return contentData.filter((step) => step.agentId === agentId);
 	}
 	/**
 	* Get run steps grouped by agent ID
@@ -979,6 +1070,8 @@ var StandardGraph = class StandardGraph extends Graph {
 				maxToolResultChars: agentContext?.maxToolResultChars,
 				toolOutputRegistry: this.getOrCreateToolOutputRegistry(),
 				fileCheckpointer: this.getOrCreateFileCheckpointer(),
+				getBreakerSignal: () => this.breakerAbort.signal,
+				getRunScope: () => this.runScope,
 				errorHandler: (data, metadata) => StandardGraph.handleToolCallErrorStatic(this, data, metadata)
 			});
 			this.registerCompiledToolNode(node);
@@ -1006,7 +1099,9 @@ var StandardGraph = class StandardGraph extends Graph {
 			maxContextTokens: agentContext?.maxContextTokens,
 			maxToolResultChars: agentContext?.maxToolResultChars,
 			toolOutputRegistry: this.getOrCreateToolOutputRegistry(),
-			fileCheckpointer: this.getOrCreateFileCheckpointer()
+			fileCheckpointer: this.getOrCreateFileCheckpointer(),
+			getBreakerSignal: () => this.breakerAbort.signal,
+			getRunScope: () => this.runScope
 		});
 		this.registerCompiledToolNode(node);
 		return node;
@@ -1075,6 +1170,21 @@ var StandardGraph = class StandardGraph extends Graph {
 	}
 	createCallModel(agentId = "default") {
 		return async (state, config) => {
+			/** Captured at node ENTRY, before any host-facing await (context-usage
+			* dispatch, hooks): a sibling's trip can fail the run and a prompt
+			* next run can reset the controller while this node is paused in one
+			* of those awaits, and a later capture would bind this attempt to the
+			* fresh controller. Trips and reason reads below stay on this
+			* capture. */
+			const attemptBreaker = this.breakerAbort;
+			const attemptBreakerEpoch = this.breakerEpoch;
+			/** Already-tripped-at-entry: a parallel sibling's breach has failed
+			* the run before this node was scheduled. Rethrow before hooks or the
+			* provider call — a custom provider that doesn't synchronously reject
+			* an aborted signal would otherwise start another model request on a
+			* failed run. */
+			const entryTripReason = this.resolveTrippedBreakerReason(attemptBreaker.signal);
+			if (entryTripReason != null) throw entryTripReason;
 			const agentContext = this.agentContexts.get(agentId);
 			if (!agentContext) throw new Error(`Agent context not found for agentId: ${agentId}`);
 			if (!config) throw new Error("No config provided");
@@ -1670,6 +1780,10 @@ var StandardGraph = class StandardGraph extends Graph {
 			let langfuseHandler;
 			let invokeConfig = {
 				...config,
+				/** The run-scoped breaker composed in, so a stream-limit trip in one
+				* parallel agent node also cancels sibling nodes' in-flight model
+				* calls, not only their subagents. */
+				signal: require_misc.composeAbortSignals(config.signal, attemptBreaker.signal),
 				metadata: {
 					...config.metadata ?? {},
 					...traceMetadata,
@@ -1677,7 +1791,8 @@ var StandardGraph = class StandardGraph extends Graph {
 					*  filtering: `createLangfuseTraceMetadata` drops values over its
 					*  length cap, but scope trust (`isForeignScope`) needs the id
 					*  verbatim regardless of length. */
-					agentId
+					agentId,
+					[require_streamLimits.STREAM_LIMIT_EPOCH_KEY]: attemptBreakerEpoch
 				}
 			};
 			require_instrumentation.initializeLangfuseTracing(langfuse);
@@ -1700,6 +1815,14 @@ var StandardGraph = class StandardGraph extends Graph {
 			const metadata = config.metadata;
 			try {
 				if (preInvokeContextOverflowError != null) throw preInvokeContextOverflowError;
+				/** Rechecked after the pre-invoke awaits (context-usage dispatch,
+				* hooks): a sibling can trip the breaker while this node is paused
+				* in one of them, and a provider that doesn't synchronously reject
+				* an aborted signal would still start the request. */
+				{
+					const preInvokeTrip = this.resolveTrippedBreakerReason(attemptBreaker.signal);
+					if (preInvokeTrip != null) throw preInvokeTrip;
+				}
 				result = await require_langfuseRuntimeScope.withLangfuseRuntimeScope(require_langfuseRuntimeScope.resolveLangfuseRuntimeScope({
 					runLangfuse: this.langfuse,
 					langfuseOverlay: agentContext.langfuse,
@@ -1717,6 +1840,28 @@ var StandardGraph = class StandardGraph extends Graph {
 					metadata
 				});
 				/**
+				* A tripped stream circuit breaker is a deliberate abort, not a
+				* provider failure: entering overflow recovery or the fallback chain
+				* would spend more provider work after the safety limit fired, and a
+				* succeeding fallback would resolve a run the public contract says
+				* must reject. Rethrow before any recovery path.
+				*/
+				if (primaryError instanceof require_streamLimits.StreamLimitExceededError) {
+					/** Tripped before rethrowing so parallel agent nodes' in-flight
+					* model calls and subagents stop while the rejection propagates. */
+					attemptBreaker.abort(primaryError);
+					throw primaryError;
+				}
+				/** A sibling that tripped the shared breaker aborts this branch's
+				* composed signal, and some providers surface that as a generic
+				* abort error; entering overflow planning or the fallback chain
+				* would start new provider work after the run-wide breaker fired.
+				* Rethrow the breaker's own stream-limit reason instead. */
+				{
+					const trippedReason = this.resolveTrippedBreakerReason(attemptBreaker.signal);
+					if (trippedReason != null) throw trippedReason;
+				}
+				/**
 				* 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
@@ -1848,6 +1993,18 @@ var StandardGraph = class StandardGraph extends Graph {
 						}
 					}));
 				} catch (fallbackError) {
+					if (fallbackError instanceof require_streamLimits.StreamLimitExceededError) {
+						/** Same treatment as the primary path: a fallback stream that
+						* trips the breaker must stop parallel agent nodes' model calls
+						* and subagents before the rejection propagates. */
+						attemptBreaker.abort(fallbackError);
+						throw fallbackError;
+					}
+					{
+						/** Same sibling-abort translation guard as the primary catch. */
+						const trippedReason = this.resolveTrippedBreakerReason(attemptBreaker.signal);
+						if (trippedReason != null) throw trippedReason;
+					}
 					const overflowCandidates = require_invoke.getFallbackOverflowCandidates(fallbackError);
 					let fallbackRecovery = null;
 					let fallbackRecoveryPromptEstimate;
@@ -2083,7 +2240,7 @@ var StandardGraph = class StandardGraph extends Graph {
 			* construction signal. When both exist they may be different
 			* controllers, and a drain must stop when EITHER fires.
 			*/
-			signal: composeAbortSignals(this.signal, this.callerSignal)
+			signal: require_misc.composeAbortSignals(this.signal, this.callerSignal)
 		}).catch(() => void 0);
 		if (result == null) return EMPTY_PREEMPT_BOUNDARY;
 		/**
@@ -2166,6 +2323,7 @@ var StandardGraph = class StandardGraph extends Graph {
 				const executor = new require_SubagentExecutor.SubagentExecutor({
 					configs: new Map(resolvedConfigs.map((c) => [c.type, c])),
 					parentSignal: this.signal,
+					breakerScope: { controller: () => this.breakerAbort },
 					hookRegistry: this.hookRegistry,
 					/** Lazy — Run wires the registry onto the graph AFTER
 					*  `createWorkflow()` runs, so a direct capture here would be
@@ -2176,6 +2334,7 @@ var StandardGraph = class StandardGraph extends Graph {
 					langfuse: this.langfuse,
 					tokenCounter: agentContext.tokenCounter,
 					usageSink: this.subagentUsageSink,
+					streamLimits: this.streamLimits,
 					maxDepth: effectiveSubagentDepth,
 					createChildGraph: (input) => {
 						const childGraph = new StandardGraph(input);
@@ -2215,11 +2374,17 @@ var StandardGraph = class StandardGraph extends Graph {
 					*/
 					const toolCall = config.toolCall;
 					const parentToolCallId = typeof toolCall?.id === "string" ? toolCall.id : void 0;
+					/** The parent tool batch's entry-captured scope (stamped by
+					* ToolNode before PreToolUse hooks) — binds this child to the
+					* run that dispatched it, not to whatever controller a reset
+					* installed while the hooks were awaited. */
+					const batchScope = config.configurable?.[require_streamLimits.RUN_BREAKER_SCOPE_CONFIG_KEY];
 					return (await executor.execute({
 						description,
 						subagentType,
 						threadId,
 						parentToolCallId,
+						breaker: batchScope?.controller,
 						/**
 						* Forward the parent's `configurable` so host-set fields
 						* (`requestBody`, `user`, etc.) propagate into the child
@@ -2262,7 +2427,7 @@ var StandardGraph = class StandardGraph extends Graph {
 			if (state.summarizationRequest != null) return summarizeNode;
 			return require_ToolNode.toolsCondition(state, toolNode, this.invokedToolIds);
 		};
-		return new _langchain_langgraph.StateGraph(_langchain_langgraph.Annotation.Root({
+		const StateAnnotation = _langchain_langgraph.Annotation.Root({
 			messages: (0, _langchain_langgraph.Annotation)({
 				reducer: require_reducer.messagesStateReducer,
 				default: () => []
@@ -2271,7 +2436,17 @@ var StandardGraph = class StandardGraph extends Graph {
 				reducer: (_, b) => b,
 				default: () => void 0
 			})
-		})).addNode(agentNode, this.createCallModel(agentId)).addNode(toolNode, this.initializeTools({
+		});
+		const readChargeCredits = () => this.streamLimitChargeCredits;
+		const readBreakerEpoch = () => this.breakerEpoch;
+		const readActiveGenerations = () => this.activeStreamLimitGenerations;
+		const writeActiveGenerations = (value) => {
+			this.activeStreamLimitGenerations = value;
+		};
+		const writeChargeCredits = (value) => {
+			this.streamLimitChargeCredits = value;
+		};
+		return new _langchain_langgraph.StateGraph(StateAnnotation).addNode(agentNode, this.createCallModel(agentId)).addNode(toolNode, this.initializeTools({
 			currentTools: agentContext.tools,
 			currentToolMap: agentContext.toolMap,
 			agentContext
@@ -2286,6 +2461,52 @@ var StandardGraph = class StandardGraph extends Graph {
 				runId: this.runId,
 				isMultiAgent: this.isMultiAgentGraph(),
 				hookRegistry: this.hookRegistry,
+				/**
+				* Live references (both maps are cleared in place, never
+				* replaced), so summarization streams share the run's event
+				* budget accounting under their own generation key.
+				*/
+				streamLimits: this.streamLimits,
+				streamDeltaEventCounts: this.streamDeltaEventCounts,
+				streamedToolCallArgTallies: this.streamedToolCallArgTallies,
+				/** Accessor pair, not a value copy: unlike the two maps above,
+				* the credit map is REPLACED by graph resets rather than cleared
+				* in place, and the guards' lazy `??=` must install onto the
+				* graph — a copy held here would survive resets and grow one
+				* attempt-stamped entry per compaction for a retained reused
+				* chunk object. */
+				get streamLimitChargeCredits() {
+					return readChargeCredits();
+				},
+				set streamLimitChargeCredits(value) {
+					writeChargeCredits(value);
+				},
+				/** Live epoch, so summary tallies are creation-tagged and the
+				* resetValues grace sweep treats them like model-attempt
+				* entries. */
+				get breakerEpoch() {
+					return readBreakerEpoch();
+				},
+				/** Accessor pair like the charge credits: summary attempts
+				* lease their generations on the GRAPH's active set, and the
+				* lazy `??=` in the lease helper must install there. */
+				get activeStreamLimitGenerations() {
+					return readActiveGenerations();
+				},
+				set activeStreamLimitGenerations(value) {
+					writeActiveGenerations(value);
+				},
+				/** Read per attempt: a sibling branch tripping the run breaker
+				* must also cancel in-flight summarization model calls. */
+				getBreakerSignal: () => this.breakerAbort.signal,
+				/** The node captures this at entry so its own chunk handler's
+				* breach trips the run that STARTED the summarization, not a
+				* controller installed by a later reset. */
+				getBreakerController: () => this.breakerAbort,
+				/** Captured at node entry and stamped into the summary attempt
+				* metadata, so the wire consumer epoch-gates old-run summary
+				* chunks exactly like model-attempt chunks. */
+				getBreakerEpoch: () => this.breakerEpoch,
 				dispatchRunStep: async (runStep, nodeConfig) => {
 					const resolvedConfig = nodeConfig ?? this.config;
 					if (runStep.agentId != null) {