@librechat/agents 3.3.4 → 3.3.5

package/dist/esm/messages/handoffCue.mjs

@@ -0,0 +1,61 @@
+import { HumanMessage } from "@langchain/core/messages";
+//#region src/messages/handoffCue.ts
+/**
+* Bracketed-meta convention, like the handoff path's
+* `[Processed tool result and transferring to …]` bridge. The wording makes
+* two things unambiguous to the model: the assistant turn above is FINISHED,
+* and it belongs to a previous stage — so the successor answers as itself
+* instead of continuing someone else's sentence.
+*/
+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.]";
+/**
+* Appends a user-turn handoff cue when a payload ends with an assistant turn
+* that THIS RUN produced — which only happens when a different agent in a
+* multi-agent workflow produced it (an agent's own self-loops always re-enter
+* on a tool result or an injected user turn).
+*
+* Why: providers with prefill semantics (Anthropic, Bedrock-Claude) treat a
+* trailing assistant message as a prefill and CONTINUE it. A bare direct-edge
+* successor therefore speaks in its predecessor's voice — or, when the
+* trailing turn reads complete (a preemption steer's short resume, say),
+* returns empty content (danny-avila/agents#345, reproduced live 3/3).
+* Handoff edges with instructions and prompt-instruction edges already break
+* the prefill with a user turn; this closes the same gap for bare edges.
+*
+* Fail-safe OFF by provenance: the trailing payload message must be one the
+* run itself produced (`isRunProduced`, backed by the graph's run-produced id
+* set — immune to summarization compaction, which rewrites the live array
+* and stales index-based boundaries). Host-supplied trailing assistant
+* turns (deliberate prefill flows) never match — the run has not produced
+* them — so single-agent prefill behavior is untouched. Wire-only: the cue is
+* appended to the provider projection, never to graph state or host history.
+*/
+function appendPredecessorHandoffCue(messages, isRunProduced) {
+	const last = messages.at(-1);
+	if (last == null || last.getType() !== "ai") return messages;
+	if (isRunProduced == null || !isRunProduced(last)) return messages;
+	return [...messages, new HumanMessage({
+		content: PREDECESSOR_HANDOFF_CUE,
+		additional_kwargs: {
+			role: "user",
+			isMeta: true,
+			source: "handoff"
+		}
+	})];
+}
+/**
+* Strips a trailing handoff cue. The counterpart for the serving-provider
+* funnel: an Anthropic-like PRIMARY bakes the cue into its measured payload,
+* and a tolerant fallback (OpenAI, Mistral, Bedrock-Nova) re-sending that
+* payload must not ship the Claude-only synthetic turn. Identity on the
+* no-op path.
+*/
+function removePredecessorHandoffCue(messages) {
+	const last = messages.at(-1);
+	if (last == null || last.getType() !== "human" || last.additional_kwargs.source !== "handoff" || last.content !== "[The assistant message above is the completed output of a previous agent. Respond now according to your own role and instructions.]") return messages;
+	return messages.slice(0, -1);
+}
+//#endregion
+export { PREDECESSOR_HANDOFF_CUE, appendPredecessorHandoffCue, removePredecessorHandoffCue };
+
+//# sourceMappingURL=handoffCue.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handoffCue.mjs","names":[],"sources":["../../../src/messages/handoffCue.ts"],"sourcesContent":["// src/messages/handoffCue.ts\nimport { HumanMessage } from '@langchain/core/messages';\nimport type { BaseMessage } from '@langchain/core/messages';\n\n/**\n * Bracketed-meta convention, like the handoff path's\n * `[Processed tool result and transferring to …]` bridge. The wording makes\n * two things unambiguous to the model: the assistant turn above is FINISHED,\n * and it belongs to a previous stage — so the successor answers as itself\n * instead of continuing someone else's sentence.\n */\nexport const PREDECESSOR_HANDOFF_CUE =\n  '[The assistant message above is the completed output of a previous ' +\n  'agent. Respond now according to your own role and instructions.]';\n\n/**\n * Appends a user-turn handoff cue when a payload ends with an assistant turn\n * that THIS RUN produced — which only happens when a different agent in a\n * multi-agent workflow produced it (an agent's own self-loops always re-enter\n * on a tool result or an injected user turn).\n *\n * Why: providers with prefill semantics (Anthropic, Bedrock-Claude) treat a\n * trailing assistant message as a prefill and CONTINUE it. A bare direct-edge\n * successor therefore speaks in its predecessor's voice — or, when the\n * trailing turn reads complete (a preemption steer's short resume, say),\n * returns empty content (danny-avila/agents#345, reproduced live 3/3).\n * Handoff edges with instructions and prompt-instruction edges already break\n * the prefill with a user turn; this closes the same gap for bare edges.\n *\n * Fail-safe OFF by provenance: the trailing payload message must be one the\n * run itself produced (`isRunProduced`, backed by the graph's run-produced id\n * set — immune to summarization compaction, which rewrites the live array\n * and stales index-based boundaries). Host-supplied trailing assistant\n * turns (deliberate prefill flows) never match — the run has not produced\n * them — so single-agent prefill behavior is untouched. Wire-only: the cue is\n * appended to the provider projection, never to graph state or host history.\n */\nexport function appendPredecessorHandoffCue(\n  messages: BaseMessage[],\n  isRunProduced: ((message: BaseMessage) => boolean) | undefined\n): BaseMessage[] {\n  const last = messages.at(-1);\n  if (last == null || last.getType() !== 'ai') {\n    return messages;\n  }\n  if (isRunProduced == null || !isRunProduced(last)) {\n    return messages;\n  }\n  return [\n    ...messages,\n    new HumanMessage({\n      content: PREDECESSOR_HANDOFF_CUE,\n      additional_kwargs: { role: 'user', isMeta: true, source: 'handoff' },\n    }),\n  ];\n}\n\n/**\n * Strips a trailing handoff cue. The counterpart for the serving-provider\n * funnel: an Anthropic-like PRIMARY bakes the cue into its measured payload,\n * and a tolerant fallback (OpenAI, Mistral, Bedrock-Nova) re-sending that\n * payload must not ship the Claude-only synthetic turn. Identity on the\n * no-op path.\n */\nexport function removePredecessorHandoffCue(\n  messages: BaseMessage[]\n): BaseMessage[] {\n  const last = messages.at(-1);\n  if (\n    last == null ||\n    last.getType() !== 'human' ||\n    last.additional_kwargs.source !== 'handoff' ||\n    last.content !== PREDECESSOR_HANDOFF_CUE\n  ) {\n    return messages;\n  }\n  return messages.slice(0, -1);\n}\n"],"mappings":";;;;;;;;;AAWA,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,IAAI,aAAa;EACf,SAAS;EACT,mBAAmB;GAAE,MAAM;GAAQ,QAAQ;GAAM,QAAQ;EAAU;CACrE,CAAC,CACH;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

@@ -9,6 +9,9 @@ import "./format.mjs";
 import "./anthropicToolCache.mjs";
 import "./content.mjs";
 import "./tools.mjs";
+import "./injected.mjs";
+import "./alternation.mjs";
+import "./handoffCue.mjs";
 import "./reducer.mjs";
 import "./recency.mjs";
 export {};

package/dist/esm/messages/injected.mjs

@@ -0,0 +1,60 @@
+import "../common/enum.mjs";
+import "../common/index.mjs";
+import { toLangChainContent } from "./langchain.mjs";
+import { HumanMessage } from "@langchain/core/messages";
+//#region src/messages/injected.ts
+/**
+* Converts `InjectedMessage` instances to LangChain `HumanMessage` objects.
+* Both 'user' and 'system' roles become `HumanMessage` to avoid provider
+* rejections (Anthropic/Google reject non-leading SystemMessages). The
+* original role is preserved in `additional_kwargs` for downstream consumers.
+*
+* Shared by both injection boundaries — `ToolNode`'s tool-batch dispatch and
+* `StandardGraph`'s preempt-boundary dispatch. Keeping one implementation is
+* load-bearing rather than tidy: the provider-safety argument for sealing a
+* stream mid-generation rests on the injected turn having byte-identical
+* shape to the one the already-shipped tool boundary emits, so the two sites
+* must not be able to drift.
+*/
+/**
+* True when an entry carries nothing a provider will accept as a turn.
+*
+* The public `InjectedMessage` type admits `content: ''` and `content: []`,
+* and a host hook is free to return one. Converting it anyway produces a
+* `HumanMessage` that passes the caller's `length > 0` test, so the graph
+* resumes and sends a trailing EMPTY user turn — which Anthropic and other
+* strict providers reject outright, turning a cooperative seal into a failed
+* run. Permissive providers merely burn a model call.
+*
+* Whitespace counts as empty, matching the standard `canSealPreempt` applies
+* to the assistant side of the same pair. Non-text blocks count as content: a
+* media-only steer is a real turn and must survive.
+*/
+function isEmptyInjectedContent(content) {
+	if (typeof content === "string") return content.trim() === "";
+	if (content.length === 0) return true;
+	return content.every((block) => {
+		if (block.type !== "text") return false;
+		const text = block["text"];
+		return typeof text !== "string" || text.trim() === "";
+	});
+}
+function convertInjectedMessages(messages) {
+	const converted = [];
+	for (const msg of messages) {
+		if (isEmptyInjectedContent(msg.content)) continue;
+		const additional_kwargs = { role: msg.role };
+		if (msg.isMeta != null) additional_kwargs.isMeta = msg.isMeta;
+		if (msg.source != null) additional_kwargs.source = msg.source;
+		if (msg.skillName != null) additional_kwargs.skillName = msg.skillName;
+		converted.push(new HumanMessage({
+			content: toLangChainContent(msg.content),
+			additional_kwargs
+		}));
+	}
+	return converted;
+}
+//#endregion
+export { convertInjectedMessages };
+
+//# sourceMappingURL=injected.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"injected.mjs","names":[],"sources":["../../../src/messages/injected.ts"],"sourcesContent":["// src/messages/injected.ts\nimport { HumanMessage } from '@langchain/core/messages';\nimport type { BaseMessage } from '@langchain/core/messages';\nimport type { InjectedMessage } from '@/types/tools';\nimport { ContentTypes } from '@/common';\nimport { toLangChainContent } from './langchain';\n\n/**\n * Converts `InjectedMessage` instances to LangChain `HumanMessage` objects.\n * Both 'user' and 'system' roles become `HumanMessage` to avoid provider\n * rejections (Anthropic/Google reject non-leading SystemMessages). The\n * original role is preserved in `additional_kwargs` for downstream consumers.\n *\n * Shared by both injection boundaries — `ToolNode`'s tool-batch dispatch and\n * `StandardGraph`'s preempt-boundary dispatch. Keeping one implementation is\n * load-bearing rather than tidy: the provider-safety argument for sealing a\n * stream mid-generation rests on the injected turn having byte-identical\n * shape to the one the already-shipped tool boundary emits, so the two sites\n * must not be able to drift.\n */\n/**\n * True when an entry carries nothing a provider will accept as a turn.\n *\n * The public `InjectedMessage` type admits `content: ''` and `content: []`,\n * and a host hook is free to return one. Converting it anyway produces a\n * `HumanMessage` that passes the caller's `length > 0` test, so the graph\n * resumes and sends a trailing EMPTY user turn — which Anthropic and other\n * strict providers reject outright, turning a cooperative seal into a failed\n * run. Permissive providers merely burn a model call.\n *\n * Whitespace counts as empty, matching the standard `canSealPreempt` applies\n * to the assistant side of the same pair. Non-text blocks count as content: a\n * media-only steer is a real turn and must survive.\n */\nfunction isEmptyInjectedContent(content: InjectedMessage['content']): boolean {\n  if (typeof content === 'string') {\n    return content.trim() === '';\n  }\n  if (content.length === 0) {\n    return true;\n  }\n  return content.every((block) => {\n    if (block.type !== ContentTypes.TEXT) {\n      return false;\n    }\n    const text = block[ContentTypes.TEXT];\n    return typeof text !== 'string' || text.trim() === '';\n  });\n}\n\nexport function convertInjectedMessages(\n  messages: InjectedMessage[]\n): BaseMessage[] {\n  const converted: BaseMessage[] = [];\n  for (const msg of messages) {\n    if (isEmptyInjectedContent(msg.content)) {\n      continue;\n    }\n    const additional_kwargs: Record<string, unknown> = {\n      role: msg.role,\n    };\n    if (msg.isMeta != null) additional_kwargs.isMeta = msg.isMeta;\n    if (msg.source != null) additional_kwargs.source = msg.source;\n    if (msg.skillName != null) additional_kwargs.skillName = msg.skillName;\n\n    converted.push(\n      new HumanMessage({\n        content: toLangChainContent(msg.content),\n        additional_kwargs,\n      })\n    );\n  }\n  return converted;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,SAAS,uBAAuB,SAA8C;CAC5E,IAAI,OAAO,YAAY,UACrB,OAAO,QAAQ,KAAK,MAAM;CAE5B,IAAI,QAAQ,WAAW,GACrB,OAAO;CAET,OAAO,QAAQ,OAAO,UAAU;EAC9B,IAAI,MAAM,SAAA,QACR,OAAO;EAET,MAAM,OAAO,MAAA;EACb,OAAO,OAAO,SAAS,YAAY,KAAK,KAAK,MAAM;CACrD,CAAC;AACH;AAEA,SAAgB,wBACd,UACe;CACf,MAAM,YAA2B,CAAC;CAClC,KAAK,MAAM,OAAO,UAAU;EAC1B,IAAI,uBAAuB,IAAI,OAAO,GACpC;EAEF,MAAM,oBAA6C,EACjD,MAAM,IAAI,KACZ;EACA,IAAI,IAAI,UAAU,MAAM,kBAAkB,SAAS,IAAI;EACvD,IAAI,IAAI,UAAU,MAAM,kBAAkB,SAAS,IAAI;EACvD,IAAI,IAAI,aAAa,MAAM,kBAAkB,YAAY,IAAI;EAE7D,UAAU,KACR,IAAI,aAAa;GACf,SAAS,mBAAmB,IAAI,OAAO;GACvC;EACF,CAAC,CACH;CACF;CACA,OAAO;AACT"}

package/dist/esm/run.mjs

@@ -4,10 +4,12 @@ import { resolveLangfuseRuntimeScope, withLangfuseRuntimeScope } from "./langfus
 import { createLangfuseHandler, createLangfuseTraceMetadata, disposeLangfuseHandler, getLangfuseTraceName, isLangfuseCallbackHandler, withLangfuseAttributes } from "./langfuse.mjs";
 import { ACTIVITY_LABEL_PROMPT, buildActivityLabelPrompt } from "./prompts/activityLabel.mjs";
 import { appendCallbacks, findCallback } from "./utils/callbacks.mjs";
+import "./common/constants.mjs";
 import "./common/enum.mjs";
 import "./common/index.mjs";
 import { createCompletionTitleRunnable, createTitleRunnable } from "./utils/title.mjs";
 import { createTokenCounter, encodingForModel } from "./utils/tokens.mjs";
+import { resolveMaxSeals } from "./llm/preempt.mjs";
 import { initializeLangfuseTracing } from "./instrumentation.mjs";
 import { isOpenAILike } from "./utils/llm.mjs";
 import { HandlerRegistry } from "./events.mjs";
@@ -79,6 +81,7 @@ var Run = class Run {
 	interruptingToolNames;
 	toolExecution;
 	subagentUsageSink;
+	preemption;
 	indexTokenCountMap;
 	calibrationRatio = 1;
 	graphRunnable;
@@ -125,6 +128,7 @@ var Run = class Run {
 		this.interruptingToolNames = config.interruptingToolNames;
 		this.toolExecution = config.toolExecution;
 		this.subagentUsageSink = config.subagentUsageSink;
+		this.preemption = config.preemption;
 		if (!config.graphConfig) throw new Error("Graph config not provided");
 		/** Handle different graph types */
 		if (config.graphConfig.type === "multi-agent") {
@@ -171,7 +175,8 @@ var Run = class Run {
 			tokenCounter: this.tokenCounter,
 			indexTokenCountMap: this.indexTokenCountMap,
 			calibrationRatio: this.calibrationRatio,
-			subagentUsageSink: this.subagentUsageSink
+			subagentUsageSink: this.subagentUsageSink,
+			preemption: this.preemption
 		});
 		/** Propagate compile options from graph config */
 		standardGraph.compileOptions = this.applyHITLCheckpointerFallback(config.compileOptions);
@@ -196,7 +201,8 @@ var Run = class Run {
 			tokenCounter: this.tokenCounter,
 			indexTokenCountMap: this.indexTokenCountMap,
 			calibrationRatio: this.calibrationRatio,
-			subagentUsageSink: this.subagentUsageSink
+			subagentUsageSink: this.subagentUsageSink,
+			preemption: this.preemption
 		});
 		multiAgentGraph.compileOptions = this.applyHITLCheckpointerFallback(compileOptions);
 		this.hasCheckpointer = multiAgentGraph.compileOptions?.checkpointer != null;
@@ -381,6 +387,17 @@ var Run = class Run {
 	getResolvedInstructionOverhead() {
 		return this.Graph?.getResolvedInstructionOverhead();
 	}
+	/**
+	* Cooperative-seal counters for this run. `emptyBoundaries` is the one to
+	* watch: it counts seals whose `PreemptBoundary` produced nothing to
+	* inject, which ends the turn early and leaves the answer unfinished.
+	*/
+	getPreemptStats() {
+		return this.Graph?.getPreemptStats() ?? {
+			seals: 0,
+			emptyBoundaries: 0
+		};
+	}
 	getToolCount() {
 		return this.Graph?.getToolCount() ?? 0;
 	}
@@ -452,12 +469,34 @@ var Run = class Run {
 		*/
 		const isResume = inputs instanceof Command;
 		const stateInputs = isResume ? void 0 : inputs;
+		/**
+		* Every honored seal costs one extra superstep, so a preemption-enabled
+		* run reserves headroom for its whole seal budget. Without it, a
+		* tool-heavy agent that gets preempted could hit `GraphRecursionError` —
+		* which surfaces as a thrown stream, setting `streamThrew`, firing
+		* `StopFailure`, and wiping via `clearHeavyState()` exactly the partial
+		* content the seal existed to preserve.
+		*/
+		const recursionLimit = (callerConfig.recursionLimit ?? 50) + (this.preemption != null ? resolveMaxSeals(this.preemption.maxSeals) : 0);
 		const config = {
-			recursionLimit: 50,
 			...callerConfig,
+			recursionLimit,
 			configurable: { ...callerConfig.configurable }
 		};
 		/**
+		* Cancellation can arrive either at graph construction or per-call through
+		* `callerConfig.signal`, and boundary hooks need to observe both — for a
+		* multi-agent run the construction signal does not exist at all, since
+		* `MultiAgentGraphConfig` exposes none. Carried on its own field, assigned
+		* unconditionally: writing into `graph.signal` would leak this call's
+		* controller into later calls (model-call config and subagent
+		* parentSignal read that field, and `clearHeavyState()` is skipped on
+		* HITL interrupts), while a conditional write would keep observing a
+		* stale controller the host has since aborted. The boundary dispatch
+		* composes both channels; see `dispatchPreemptBoundary`.
+		*/
+		graph.callerSignal = callerConfig.signal;
+		/**
 		* Skip `resetValues` on resume — we're continuing an in-flight
 		* run, not starting a fresh one. Resetting would wipe the
 		* sidecars (`toolCallStepIds`, `stepKeyIds`, accumulated
@@ -604,10 +643,17 @@ var Run = class Run {
 				* graph doesn't take another model turn after the halting
 				* operation completes.
 				*
-				* Limitation: the current step (in-flight model call, ongoing
-				* tool batch) is not aborted — only the next step is skipped.
-				* This matches Claude Code's `continue: false` semantic where
-				* the active operation finishes before halting takes effect.
+				* This `break` is NOT graceful, despite what a `continue: false`
+				* reading suggests. Leaving the `for await` calls the iterator's
+				* `return()`, which cancels the reader
+				* (`@langchain/core/utils/stream`), and langgraph's stream wrapper
+				* turns that cancel into `_abortController.abort()`
+				* (`pregel/stream.js`). The in-flight model call or tool batch is
+				* torn down where it stands — it does not finish first.
+				*
+				* A halt is therefore the wrong tool for "stop generating but keep
+				* what you have". That is what `RunConfig.preemption` is for: it
+				* seals the stream at a provider-safe boundary and keeps the run.
 				*/
 				const haltSignal = this.hookRegistry?.getHaltSignal(this.id);
 				if (haltSignal != null) {
@@ -631,10 +677,37 @@ var Run = class Run {
 					threadId,
 					agentId: graph.defaultAgentId,
 					messages: graph.getRunMessages() ?? stateInputs?.messages ?? [],
+					/**
+					* A seal whose boundary ended the turn early must say so. The
+					* hook-supplied reason wins when a `PreemptBoundary` hook halted
+					* with one — a persistence/audit `Stop` hook should record the
+					* actual cause, not the generic label — and `preempt_incomplete`
+					* is reserved for the boundary that simply had nothing to inject.
+					*/
+					stopReason: graph.preemptHaltReason ?? (graph.preemptIncomplete ? "preempt_incomplete" : void 0),
 					stopHookActive: false
 				},
 				sessionId: this.id
 			}).catch(() => {});
+			/**
+			* A `PreemptBoundary` hook that returned `preventContinuation` has its
+			* registry halt cleared by the graph — that is what stops the halt from
+			* cancelling the stream before the sealed turn commits — so the reason
+			* is carried across on the graph instead. Surfaced here, AFTER the
+			* `Stop` dispatch above, so the host still receives a completion signal
+			* to persist the partial answer with while `getHaltReason()` correctly
+			* reports that a hook stopped the run rather than the model finishing.
+			*
+			* An empty boundary — sealed, but nothing to inject because the host's
+			* queue was drained or cancelled in the meantime — cut the answer short
+			* just as surely, only without a hook-supplied reason. It surfaces
+			* through the same channel under the same name the `Stop` dispatch
+			* already used for its `stopReason`, so terminal consumers
+			* (`AgentSession` emits `run.halted`, not `run.completed`) cannot
+			* finalize a truncated answer as a natural finish.
+			*/
+			if (this._haltedReason == null && graph.preemptHaltReason != null) this._haltedReason = graph.preemptHaltReason;
+			else if (this._haltedReason == null && graph.preemptIncomplete) this._haltedReason = "preempt_incomplete";
 		};
 		try {
 			await withLangfuseRuntimeScope(resolveLangfuseRuntimeScope({