@librechat/agents 3.3.3 → 3.3.5

package/dist/cjs/graphs/Graph.cjs

@@ -3,20 +3,27 @@ const require_langfuseRuntimeScope = require("../langfuseRuntimeScope.cjs");
 const require_langfuse = require("../langfuse.cjs");
 const require_langfuseToolOutputTracing = require("../langfuseToolOutputTracing.cjs");
 const require_callbacks = require("../utils/callbacks.cjs");
+const require_constants = require("../common/constants.cjs");
 const require_enum = require("../common/enum.cjs");
 require("../common/index.cjs");
+const require_truncation = require("../utils/truncation.cjs");
+const require_toolContent = require("../utils/toolContent.cjs");
 const require_tokens = require("../utils/tokens.cjs");
+const require_preempt = require("../llm/preempt.cjs");
 const require_instrumentation = require("../instrumentation.cjs");
+const require_cache = require("../messages/cache.cjs");
 const require_core = require("../messages/core.cjs");
 const require_ids = require("../messages/ids.cjs");
 const require_prune = require("../messages/prune.cjs");
 const require_budget = require("../messages/budget.cjs");
 const require_events = require("../utils/events.cjs");
 const require_format = require("../messages/format.cjs");
-const require_cache = require("../messages/cache.cjs");
 const require_anthropicToolCache = require("../messages/anthropicToolCache.cjs");
 const require_content = require("../messages/content.cjs");
 const require_tools = require("../messages/tools.cjs");
+const require_injected = require("../messages/injected.cjs");
+const require_alternation = require("../messages/alternation.cjs");
+const require_handoffCue = require("../messages/handoffCue.cjs");
 const require_reducer = require("../messages/reducer.cjs");
 const require_recency = require("../messages/recency.cjs");
 require("../messages/index.cjs");
@@ -27,11 +34,13 @@ 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_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_contextOverflowRecovery = require("../llm/contextOverflowRecovery.cjs");
 const require_toolCache$1 = require("../llm/openrouter/toolCache.cjs");
+const require_executeHooks = require("../hooks/executeHooks.cjs");
+require("../hooks/index.cjs");
 const require_LocalCodingTools = require("../tools/local/LocalCodingTools.cjs");
 const require_CloudflareSandboxTools = require("../tools/cloudflare/CloudflareSandboxTools.cjs");
 require("../tools/cloudflare/index.cjs");
@@ -41,7 +50,7 @@ const require_ToolNode = require("../tools/ToolNode.cjs");
 const require_SubagentExecutor = require("../tools/subagent/SubagentExecutor.cjs");
 require("../tools/subagent/index.cjs");
 const require_SubagentTool = require("../tools/SubagentTool.cjs");
-const require_index$6 = require("../summarization/index.cjs");
+const require_index$7 = require("../summarization/index.cjs");
 const require_request = require("../llm/request.cjs");
 const require_node = require("../summarization/node.cjs");
 const require_schema = require("../tools/schema.cjs");
@@ -51,8 +60,25 @@ let _langchain_core_messages = require("@langchain/core/messages");
 let _langchain_langgraph = require("@langchain/langgraph");
 let _langchain_core_tools = require("@langchain/core/tools");
 let nanoid = require("nanoid");
+let _langchain_core_errors = require("@langchain/core/errors");
+let uuid = require("uuid");
 //#region src/graphs/Graph.ts
 const { AGENT, TOOLS, SUMMARIZE } = require_enum.GraphNodeKeys;
+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) {
@@ -62,19 +88,6 @@ function createToolHandlerRegistry(source) {
 	registry.register("on_tool_execute", toolHandler);
 	return registry;
 }
-/**
-* Start index of the span post-prune formatters can mutate in place: the
-* trailing tool batch plus its owning AI message (artifact formatting touches
-* every tool result after the last AI tool call; Bedrock rewrites the AI
-* message before a trailing tool result). Capped so the usage-snapshot
-* recount stays constant-cost.
-*/
-function trailingMutationStart(messages) {
-	const MAX_SPAN = 16;
-	let index = messages.length - 1;
-	while (index >= 0 && messages[index]?.getType() === "tool" && messages.length - index < MAX_SPAN) index--;
-	return Math.max(0, Math.min(index, messages.length - 2));
-}
 function getHandlerDispatchedEventKey(eventName, stepId) {
 	return `${eventName}:${stepId}`;
 }
@@ -276,6 +289,20 @@ var Graph = class {
 	reasoningStepHasDeltas = /* @__PURE__ */ new Set();
 	handlerDispatchedEventCounts = /* @__PURE__ */ new Map();
 	signal;
+	/**
+	* The abort signal the CALLER handed to the current `processStream` call,
+	* assigned unconditionally — including back to `undefined` — on every call.
+	*
+	* Kept separate from {@link signal} on purpose. That field is construction
+	* state with its own consumers (model-call config, subagent parentSignal),
+	* so adopting a per-call signal into it would leak one call's controller
+	* into the next — `clearHeavyState()` is skipped on HITL interrupts, so a
+	* host that aborts a finished request's controller would poison the resumed
+	* run's model calls and boundary drains with an already-aborted signal.
+	* Boundary dispatch composes the two instead; see
+	* `StandardGraph.dispatchPreemptBoundary`.
+	*/
+	callerSignal;
 	/** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
 	invokedToolIds;
 	handlerRegistry;
@@ -352,6 +379,7 @@ var Graph = class {
 	clearHeavyState() {
 		this.config = void 0;
 		this.signal = void 0;
+		this.callerSignal = void 0;
 		this.contentData = [];
 		this.contentIndexMap = /* @__PURE__ */ new Map();
 		this.stepKeyIds = /* @__PURE__ */ new Map();
@@ -491,6 +519,8 @@ var StandardGraph = class StandardGraph extends Graph {
 	messages = [];
 	/** Cached run messages preserved before clearHeavyState() so getRunMessages() works after cleanup. */
 	cachedRunMessages;
+	/** Ids of AI turns the agent node returned THIS run; see isRunProducedMessage. */
+	runProducedAiMessageIds = /* @__PURE__ */ new Set();
 	/** Checkpoint scope whose messages match index-keyed tool snapshots. */
 	originalToolContentCheckpointScope;
 	runId;
@@ -516,13 +546,61 @@ var StandardGraph = class StandardGraph extends Graph {
 	subagentUsageSink;
 	/** See {@link t.StandardGraphInput.subagentScope}. */
 	subagentScope;
-	constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, subagentUsageSink, subagentScope }) {
+	/** See {@link t.StandardGraphInput.preemption}. */
+	preemption;
+	/**
+	* 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.
+	*/
+	preemptSealBudgetUsed = 0;
+	/**
+	* Seals honored over the graph's lifetime. Reported by
+	* {@link getPreemptStats}, so it deliberately SURVIVES `clearHeavyState()`
+	* — a host reads it after `processStream` returns, which is strictly after
+	* cleanup runs.
+	*/
+	preemptSealCount = 0;
+	/** Boundaries that produced nothing to inject, so the turn stopped early. */
+	preemptEmptyBoundaries = 0;
+	/**
+	* Set between claiming a seal and resolving its boundary. `MultiAgentGraph`
+	* fans parallel agents through this one instance against a single host
+	* request, so without a one-at-a-time gate several streams would each seal
+	* for the same queued message and every loser would take the
+	* nothing-to-inject path and cut its answer short.
+	*/
+	preemptSealInFlight = false;
+	/**
+	* True when a seal ended the turn without a resume. The assistant turn is
+	* real and kept, but it is not the answer the model intended to finish —
+	* hosts persist it as unfinished rather than complete.
+	*/
+	preemptIncomplete = false;
+	/**
+	* `stopReason` from a `PreemptBoundary` hook that halted the turn.
+	*
+	* Clearing the registry halt is what keeps the sealed turn alive, but the
+	* registry held the only copy of the reason — so it is captured here first.
+	* Without it `getHaltReason()` returns undefined and a host records a
+	* hook-halted turn as an ordinary completion.
+	*/
+	preemptHaltReason;
+	/**
+	* Agent IDs whose next superstep must return to the agent node. Keyed by
+	* agent because `MultiAgentGraph` routes every parallel agent through this
+	* same instance, and a single field would let one agent's boundary resume
+	* another's turn.
+	*/
+	pendingPreemptReturn = /* @__PURE__ */ new Set();
+	constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, subagentUsageSink, subagentScope, preemption }) {
 		super();
 		this.runId = runId;
 		this.signal = signal;
 		this.langfuse = langfuse;
 		this.subagentUsageSink = subagentUsageSink;
 		this.subagentScope = subagentScope === true;
+		this.preemption = preemption;
 		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);
@@ -547,6 +625,7 @@ var StandardGraph = class StandardGraph extends Graph {
 		* a stale reference on 2nd+ processStream calls.
 		*/
 		this.toolCallStepIds.clear();
+		this.runProducedAiMessageIds.clear();
 		this.eagerEventToolExecutions.clear();
 		this.clearEagerEventToolUsageCounts();
 		this.eagerEventToolCallChunks.clear();
@@ -558,6 +637,8 @@ 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);
+		this.resetPreemptTurnState();
+		this.resetPreemptTotals();
 		const hasScopedCheckpoint = this.hasCompiledCheckpointer && checkpointScope != null && checkpointScope !== "";
 		const preserveOriginalToolContent = hasScopedCheckpoint && this.originalToolContentCheckpointScope === checkpointScope;
 		for (const context of this.agentContexts.values()) context.reset({ preserveOriginalToolContent });
@@ -568,9 +649,98 @@ var StandardGraph = class StandardGraph extends Graph {
 		super.clearHeavyState();
 		this.messages = [];
 		this.overrideModel = void 0;
+		/**
+		* Turn state only. The reported totals must outlive cleanup — this runs
+		* in `processStream`'s `finally`, and the host reads `getPreemptStats()`
+		* after that returns.
+		*/
+		this.resetPreemptTurnState();
 		const preserveOriginalToolContent = this.hasCompiledCheckpointer && this.originalToolContentCheckpointScope != null;
 		for (const context of this.agentContexts.values()) context.reset({ preserveOriginalToolContent });
 	}
+	/**
+	* Per-turn seal budget and routing markers. Cleared by both reset paths so
+	* a new turn starts with a full budget and no stale resume marker.
+	*
+	* The REPORTED counters are deliberately not touched here — see
+	* {@link resetPreemptTotals}.
+	*/
+	resetPreemptTurnState() {
+		this.preemptSealBudgetUsed = 0;
+		this.preemptSealInFlight = false;
+		this.pendingPreemptReturn.clear();
+	}
+	/**
+	* Lifetime seal totals, cleared only when a genuinely new run starts.
+	* `clearHeavyState()` must NOT call this: it runs in `processStream`'s
+	* `finally`, so zeroing here would make {@link getPreemptStats} and
+	* `preemptIncomplete` unreadable for every caller of the method that just
+	* produced them.
+	*/
+	resetPreemptTotals() {
+		this.preemptSealCount = 0;
+		this.preemptEmptyBoundaries = 0;
+		this.preemptIncomplete = false;
+		this.preemptHaltReason = void 0;
+	}
+	/**
+	* True when the host has requested a cooperative seal AND this graph may
+	* honor it. Read once per streamed chunk, so it stays property reads plus
+	* one host callback — no I/O, no allocation.
+	*
+	* Non-mutating: a true result only means a seal is worth evaluating. The
+	* budget is taken by {@link claimPreemptSeal} once the accumulated chunk is
+	* known to be safe, so a chunk that cannot seal never spends budget.
+	*
+	* Subagent scopes never seal: a steer targets the top-level conversation,
+	* and a child run must finish so its parent sees a complete result.
+	*/
+	/** Internal seal preconditions only — no host callback, no side effects. */
+	canClaimPreemptSeal() {
+		/**
+		* Resolved and required here with the same rule `dispatchPreemptBoundary`
+		* uses. Without it a direct `StandardGraph` consumer that supplies no
+		* `runId` could claim a seal on the strength of a global matcher, then hit
+		* the boundary's own null-runId guard and get nothing back — truncating
+		* the answer for a drain that provably could not run.
+		*/
+		const runId = this.config?.configurable?.run_id ?? this.runId;
+		return !this.subagentScope && this.preemption != null && !this.preemptSealInFlight && this.preemptSealBudgetUsed < require_preempt.resolveMaxSeals(this.preemption.maxSeals) && runId != null && this.hookRegistry?.hasDispatchableHookFor("PreemptBoundary", runId) === true;
+	}
+	shouldPreemptStream() {
+		return this.canClaimPreemptSeal() && this.preemption?.shouldPreempt() === true;
+	}
+	/**
+	* Takes the seal slot, or returns false if another stream already holds it.
+	*
+	* Assumes the caller already polled `shouldPreemptStream()` for THIS chunk,
+	* and deliberately does not poll the host again — `StreamPreemption`
+	* documents `shouldPreempt` as once per chunk, and a host that consumes a
+	* pending flag on read would lose the request to a second call.
+	*
+	* The guard and both mutations remain one synchronous body, which is what
+	* makes this safe under a parallel `MultiAgentGraph`: several agents share
+	* one graph and can each see the poll as true, but no `await` can split the
+	* claim, so only one takes the slot. The loser keeps streaming normally
+	* rather than sealing for a message it would never receive.
+	*/
+	claimPreemptSeal() {
+		if (!this.canClaimPreemptSeal()) return false;
+		this.preemptSealInFlight = true;
+		this.preemptSealBudgetUsed += 1;
+		this.preemptSealCount += 1;
+		return true;
+	}
+	/** Releases the seal slot once its boundary has resolved, win or lose. */
+	releasePreemptSeal() {
+		this.preemptSealInFlight = false;
+	}
+	getPreemptStats() {
+		return {
+			seals: this.preemptSealCount,
+			emptyBoundaries: this.preemptEmptyBoundaries
+		};
+	}
 	getRunStep(stepId) {
 		const index = this.contentIndexMap.get(stepId);
 		if (index !== void 0) return this.contentData[index];
@@ -654,6 +824,20 @@ var StandardGraph = class StandardGraph extends Graph {
 		if (this.messages.length === 0 && this.cachedRunMessages != null) return this.cachedRunMessages;
 		return this.messages.slice(this.startIndex);
 	}
+	/**
+	* True when THIS RUN produced `message` — the provenance the handoff cue
+	* gate needs. Tracked as an id set rather than inferred from `startIndex`
+	* arithmetic: summarization's remove-all compaction rewrites the live
+	* array and leaves `startIndex` stale, so index-based run/host
+	* discrimination silently breaks right after a mid-run summarize. Ids
+	* survive compaction (retained messages keep theirs), host-supplied
+	* prefill messages are never in the set, and membership is O(1) per
+	* model call.
+	*/
+	isRunProducedMessage(message) {
+		const id = message.id;
+		return typeof id === "string" && id !== "" && this.runProducedAiMessageIds.has(id);
+	}
 	getContentParts() {
 		if (this.messages == null) return;
 		return require_core.convertMessagesToContent(this.messages.slice(this.startIndex));
@@ -852,6 +1036,20 @@ var StandardGraph = class StandardGraph extends Graph {
 			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");
+			/**
+			* A `PreemptBoundary` hook halted this run and the sealed commit is
+			* already in state. Enforced at every model node's ENTRY because that
+			* is the only site that covers all of `MultiAgentGraph`'s onward
+			* routing at once — static direct edges, Command fan-out, fan-in
+			* wrappers, and parallel siblings' subsequent inner-loop turns — none
+			* of which consult the halt (the registry signal was deliberately
+			* cleared to keep the stream-cancel from destroying the sealed turn).
+			* Declining the model call turns every routed-to successor into a
+			* no-op, so the outer workflow drains to END without new turns or tool
+			* side effects. Reset per turn in `resetPreemptTotals`, so the next
+			* `processStream` call starts clean.
+			*/
+			if (this.preemptHaltReason != null) return { messages: [] };
 			const { messages } = state;
 			const discoveredNames = require_tools.extractToolDiscoveries(messages);
 			if (discoveredNames.length > 0) agentContext.markToolsAsDiscovered(discoveredNames);
@@ -901,6 +1099,7 @@ var StandardGraph = class StandardGraph extends Graph {
 				provider: agentContext.provider,
 				tokenCounter: agentContext.tokenCounter,
 				maxTokens: agentContext.maxContextTokens,
+				maxToolResultChars: agentContext.maxToolResultChars,
 				thinkingEnabled: require_request.isThinkingEnabled(agentContext.provider, agentContext.clientOptions),
 				indexTokenCountMap: agentContext.indexTokenCountMap,
 				contextPruningConfig: agentContext.contextPruningConfig,
@@ -971,7 +1170,7 @@ var StandardGraph = class StandardGraph extends Graph {
 				require_budget.syncBudgetDerivedFields(contextUsage);
 				if (agentContext.summarizationEnabled === true && Array.isArray(messagesToRefine) && messagesToRefine.length > 0) {
 					const shouldSkip = agentContext.shouldSkipSummarization(messages.length);
-					if (!shouldSkip && require_index$6.shouldTriggerSummarization({
+					if (!shouldSkip && require_index$7.shouldTriggerSummarization({
 						trigger: agentContext.summarizationConfig?.trigger,
 						maxContextTokens: agentContext.maxContextTokens,
 						prePruneContextTokens: prePruneContextTokens != null ? prePruneContextTokens + agentContext.instructionTokens : void 0,
@@ -1010,28 +1209,73 @@ var StandardGraph = class StandardGraph extends Graph {
 				}
 			}
 			let finalMessages = messagesToUse;
-			/** Tail snapshot for the dispatch-time usage delta: in-place
-			*  formatters (artifact appends, Bedrock content rewrites, legacy
-			*  string conversion) mutate without changing length or identity —
-			*  capture before they run. Legacy string conversion can also touch
-			*  messages before the tail, so those convertible indices are
-			*  tracked separately (none exist in the common case). */
-			const tailStart = trailingMutationStart(messagesToUse);
-			let preFormatTailTokens = null;
-			let legacyIndices = null;
-			let preFormatLegacyTokens = 0;
+			/**
+			* Keep the pruner's provider-grounded aggregate as the authoritative
+			* baseline, then attribute it across retained messages. Provider
+			* transforms can shrink one message while expanding or adding another;
+			* per-origin accounting prevents that unrelated shrink from canceling
+			* the expansion. Raw counts are frozen before in-place formatters run.
+			*/
+			let providerMessageBaseline;
+			const providerMessageOrigins = /* @__PURE__ */ new WeakMap();
 			if (contextUsage != null && agentContext.tokenCounter != null) {
-				preFormatTailTokens = 0;
-				for (const message of messagesToUse.slice(tailStart)) preFormatTailTokens += agentContext.tokenCounter(message);
-				if (agentContext.useLegacyContent) {
-					legacyIndices = [];
-					for (let i = 0; i < tailStart; i++) if (require_content.isLegacyConvertible(messagesToUse[i])) {
-						legacyIndices.push(i);
-						preFormatLegacyTokens += agentContext.tokenCounter(messagesToUse[i]);
+				const sourceIndices = /* @__PURE__ */ new WeakMap();
+				for (let i = 0; i < messages.length; i++) sourceIndices.set(messages[i], i);
+				providerMessageBaseline = messagesToUse.map((message, index) => {
+					const rawTokens = agentContext.tokenCounter(message);
+					const sourceIndex = sourceIndices.get(message);
+					const indexedTokens = sourceIndex != null ? agentContext.indexTokenCountMap[sourceIndex] : void 0;
+					const accountingWeight = indexedTokens != null && Number.isFinite(indexedTokens) && indexedTokens >= 0 ? indexedTokens : rawTokens;
+					if (!providerMessageOrigins.has(message)) providerMessageOrigins.set(message, index);
+					return {
+						rawTokens,
+						accountingWeight
+					};
+				});
+			}
+			const getProviderMessageOriginKey = (message) => {
+				const type = message.getType();
+				if (message instanceof _langchain_core_messages.ToolMessage && typeof message.tool_call_id === "string" && message.tool_call_id.length > 0) return `tool:call:${message.tool_call_id}`;
+				if (typeof message.id === "string" && message.id.length > 0) return `${type}:id:${message.id}`;
+			};
+			/**
+			* Provider projections clone messages. Preserve their baseline origin
+			* without writing tracking metadata onto the wire. Synthetic fold
+			* messages intentionally remain unattributed and are charged in full.
+			*/
+			const trackProviderMessageOrigins = (before, after) => {
+				if (providerMessageBaseline == null || before === after) return after;
+				if (before.length === after.length) {
+					for (let i = 0; i < after.length; i++) {
+						const origin = providerMessageOrigins.get(before[i]);
+						if (origin != null && !providerMessageOrigins.has(after[i]) && before[i].getType() === after[i].getType() && !require_format.isSyntheticProviderContextMessage(after[i])) providerMessageOrigins.set(after[i], origin);
 					}
+					return after;
+				}
+				const keyedOrigins = /* @__PURE__ */ new Map();
+				for (const message of before) {
+					const origin = providerMessageOrigins.get(message);
+					const key = getProviderMessageOriginKey(message);
+					if (origin == null || key == null) continue;
+					keyedOrigins.set(key, keyedOrigins.has(key) ? null : origin);
 				}
+				for (const message of after) {
+					if (providerMessageOrigins.has(message) || require_format.isSyntheticProviderContextMessage(message)) continue;
+					const key = getProviderMessageOriginKey(message);
+					const origin = key != null ? keyedOrigins.get(key) : void 0;
+					if (origin != null) providerMessageOrigins.set(message, origin);
+				}
+				return after;
+			};
+			if (agentContext.useLegacyContent) {
+				const before = finalMessages;
+				finalMessages = trackProviderMessageOrigins(before, require_content.formatContentStrings(before));
 			}
-			if (agentContext.useLegacyContent) finalMessages = require_content.formatContentStrings(finalMessages);
+			const maxProviderToolResultChars = agentContext.maxToolResultChars ?? require_truncation.calculateMaxToolResultChars(agentContext.maxContextTokens);
+			const beforeToolStreamProjection = finalMessages;
+			finalMessages = trackProviderMessageOrigins(beforeToolStreamProjection, require_core.projectToolStreamContentForProvider(beforeToolStreamProjection));
+			const beforeToolInputProjection = finalMessages;
+			finalMessages = trackProviderMessageOrigins(beforeToolInputProjection, require_prune.projectToolCallInputs(beforeToolInputProjection, require_prune.calculateMaxToolCallInputChars(agentContext.maxContextTokens)));
 			const lastMessageX = finalMessages.length >= 2 ? finalMessages[finalMessages.length - 2] : null;
 			const lastMessageY = finalMessages.length >= 1 ? finalMessages[finalMessages.length - 1] : null;
 			const anthropicLike = require_llm.isAnthropicLike(agentContext.provider, agentContext.clientOptions);
@@ -1042,34 +1286,238 @@ var StandardGraph = class StandardGraph extends Graph {
 					text: trimmed
 				}] : "";
 			}
+			const localProviderOverflowMeasurements = /* @__PURE__ */ new WeakMap();
+			const measureProviderPayload = (candidate, contextBudgetOverride, forceRawRecount = false) => {
+				const contextBudget = contextBudgetOverride ?? contextUsage?.contextBudget;
+				const effectiveInstructionTokens = contextUsage?.effectiveInstructionTokens ?? (forceRawRecount ? agentContext.instructionTokens : void 0);
+				if (agentContext.tokenCounter == null || contextBudget == null || effectiveInstructionTokens == null) return { fits: true };
+				const availableMessageTokens = Math.max(0, contextBudget - effectiveInstructionTokens);
+				let usageRatio = agentContext.calibrationRatio > 0 ? agentContext.calibrationRatio : 1;
+				if (contextUsage?.calibrationRatio != null && contextUsage.calibrationRatio > 0) usageRatio = contextUsage.calibrationRatio;
+				if (forceRawRecount) usageRatio = Math.max(1, usageRatio);
+				const baselineRemaining = contextUsage?.remainingContextTokens;
+				const accountedMessageTokens = !forceRawRecount && providerMessageBaseline != null && baselineRemaining != null && Number.isFinite(baselineRemaining) ? availableMessageTokens - Math.min(availableMessageTokens, Math.max(0, baselineRemaining)) : void 0;
+				let projectedMessageTokens;
+				if (accountedMessageTokens != null && providerMessageBaseline != null) {
+					const replyPrimerTokens = Math.round(3 * usageRatio);
+					const rawWeights = {};
+					let totalWeight = 0;
+					for (let i = 0; i < providerMessageBaseline.length; i++) {
+						const weight = providerMessageBaseline[i].accountingWeight;
+						rawWeights[i] = weight;
+						totalWeight += weight;
+					}
+					const attributableTokens = totalWeight > 0 ? Math.min(Math.max(0, accountedMessageTokens - replyPrimerTokens), Math.round(totalWeight * usageRatio)) : 0;
+					const apportionedTokens = totalWeight > 0 ? require_tokens.apportionTokenCounts(rawWeights, attributableTokens / totalWeight, attributableTokens) : {};
+					const attributedByOrigin = providerMessageBaseline.map((_, origin) => apportionedTokens[origin] || 0);
+					projectedMessageTokens = Math.max(replyPrimerTokens, accountedMessageTokens - attributableTokens);
+					let newRawTokens = 0;
+					const usedOrigins = /* @__PURE__ */ new Set();
+					for (const message of candidate) {
+						const rawTokens = agentContext.tokenCounter(message);
+						const origin = providerMessageOrigins.get(message);
+						if (origin == null || usedOrigins.has(origin)) {
+							newRawTokens += rawTokens;
+							continue;
+						}
+						usedOrigins.add(origin);
+						projectedMessageTokens += Math.max(0, attributedByOrigin[origin] + Math.round((rawTokens - providerMessageBaseline[origin].rawTokens) * usageRatio));
+					}
+					projectedMessageTokens += Math.round(newRawTokens * usageRatio);
+				} else {
+					let rawTokens = 3;
+					for (const message of candidate) rawTokens += agentContext.tokenCounter(message);
+					projectedMessageTokens = Math.round(rawTokens * usageRatio);
+				}
+				return {
+					fits: projectedMessageTokens <= availableMessageTokens,
+					projectedMessageTokens,
+					availableMessageTokens,
+					contextBudget,
+					effectiveInstructionTokens
+				};
+			};
+			const createProviderPayloadOverflowError = ({ projection, provider, info }) => {
+				const error = new _langchain_core_errors.ContextOverflowError(JSON.stringify({
+					type: "final_context_overflow",
+					info,
+					provider,
+					projectedMessageTokens: projection.projectedMessageTokens,
+					availableMessageTokens: projection.availableMessageTokens
+				}));
+				if (projection.projectedMessageTokens != null && projection.contextBudget != null && projection.effectiveInstructionTokens != null) localProviderOverflowMeasurements.set(error, {
+					contextBudget: projection.contextBudget,
+					estimatedPromptTokens: projection.projectedMessageTokens + projection.effectiveInstructionTokens
+				});
+				return error;
+			};
+			const applyProviderMessageTransforms = (candidate) => {
+				let transformed = candidate;
+				if (require_request.isThinkingEnabled(agentContext.provider, agentContext.clientOptions)) {
+					/**
+					* Current-run AI messages may validly omit a thinking block. The
+					* boundary prevents them from being mistaken for foreign history.
+					*/
+					const before = transformed;
+					transformed = trackProviderMessageOrigins(before, require_format.ensureThinkingBlockInMessages(before, agentContext.provider, config, this.startIndex));
+				}
+				/**
+				* Tool-less destinations cannot send inherited tool blocks without a
+				* tool schema, so fold those interactions into provider-valid content.
+				*/
+				if (toolsForBinding == null || toolsForBinding.length === 0) {
+					const before = transformed;
+					transformed = trackProviderMessageOrigins(before, require_format.foldToolBlocksForToollessAgent(before, config));
+					if (agentContext.useLegacyContent) {
+						const beforeLegacyFormat = transformed;
+						transformed = trackProviderMessageOrigins(beforeLegacyFormat, require_content.formatContentStrings(beforeLegacyFormat));
+					}
+				}
+				/**
+				* 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.
+				*/
+				if (require_llm.isAnthropicLike(agentContext.provider, agentContext.clientOptions)) {
+					const before = transformed;
+					transformed = trackProviderMessageOrigins(before, require_handoffCue.appendPredecessorHandoffCue(before, (message) => this.isRunProducedMessage(message)));
+				}
+				return transformed;
+			};
+			const toolOutputRegistry = this.getOrCreateToolOutputRegistry();
+			const providerRunId = config.configurable?.run_id;
+			const projectProviderReferences = (candidate) => trackProviderMessageOrigins(candidate, require_toolOutputReferences.annotateMessagesForLLM(candidate, toolOutputRegistry, providerRunId));
+			const compactSyntheticProviderContext = (candidate) => {
+				const synthetic = [];
+				for (let i = 0; i < candidate.length; i++) {
+					const message = candidate[i];
+					if (!(message instanceof _langchain_core_messages.HumanMessage) || !require_format.isSyntheticProviderContextMessage(message)) continue;
+					const content = message.content;
+					synthetic.push({
+						index: i,
+						message,
+						chars: require_toolContent.getToolContentCharLength(content)
+					});
+				}
+				if (synthetic.length === 0) return candidate;
+				const buildCandidate = (scale) => {
+					const compacted = [...candidate];
+					for (const { index, message, chars } of synthetic) {
+						const content = require_toolContent.compactToolContent(message.content, Math.floor(chars * scale)).content;
+						compacted[index] = new _langchain_core_messages.HumanMessage({
+							content,
+							id: message.id,
+							name: message.name,
+							additional_kwargs: message.additional_kwargs,
+							response_metadata: message.response_metadata
+						});
+					}
+					return compacted;
+				};
+				let best = buildCandidate(0);
+				if (!measureProviderPayload(best).fits) return candidate;
+				let low = 0;
+				let high = 1;
+				for (let i = 0; i < 12; i++) {
+					const scale = (low + high) / 2;
+					const attempt = buildCandidate(scale);
+					if (measureProviderPayload(attempt).fits) {
+						best = attempt;
+						low = scale;
+					} else high = scale;
+				}
+				return best;
+			};
+			let artifactBaseMessages;
 			if (lastMessageY instanceof _langchain_core_messages.ToolMessage) {
-				if (anthropicLike) require_core.formatAnthropicArtifactContent(finalMessages);
-				else if (require_llm.isOpenAILike(agentContext.provider) && agentContext.provider !== "deepseek" || require_llm.isGoogleLike(agentContext.provider)) require_core.formatArtifactPayload(finalMessages);
+				let artifactCandidate = finalMessages;
+				if (anthropicLike) artifactCandidate = trackProviderMessageOrigins(finalMessages, require_core.projectAnthropicArtifactContent(finalMessages, maxProviderToolResultChars));
+				else if (require_llm.isOpenAILike(agentContext.provider) && agentContext.provider !== "deepseek" || require_llm.isGoogleLike(agentContext.provider)) artifactCandidate = trackProviderMessageOrigins(finalMessages, require_core.projectArtifactPayload(finalMessages, maxProviderToolResultChars));
+				if (artifactCandidate !== finalMessages) {
+					const projection = measureProviderPayload(artifactCandidate);
+					if (projection.fits) {
+						artifactBaseMessages = finalMessages;
+						finalMessages = artifactCandidate;
+					} else require_events.emitAgentLog(config, "warn", "graph", "Artifact payload omitted because it exceeds the remaining context budget", {
+						projectedMessageTokens: projection.projectedMessageTokens,
+						availableMessageTokens: projection.availableMessageTokens
+					}, {
+						runId: this.runId,
+						agentId
+					});
+				}
+			}
+			finalMessages = projectProviderReferences(applyProviderMessageTransforms(finalMessages));
+			let finalProjection = measureProviderPayload(finalMessages);
+			if (artifactBaseMessages != null) {
+				if (!finalProjection.fits) {
+					finalMessages = projectProviderReferences(applyProviderMessageTransforms(artifactBaseMessages));
+					finalProjection = measureProviderPayload(finalMessages);
+					require_events.emitAgentLog(config, "warn", "graph", "Artifact payload omitted after final provider formatting exceeded the remaining context budget", {
+						projectedMessageTokens: finalProjection.projectedMessageTokens,
+						availableMessageTokens: finalProjection.availableMessageTokens
+					}, {
+						runId: this.runId,
+						agentId
+					});
+				}
+			}
+			if (!finalProjection.fits) {
+				const compacted = compactSyntheticProviderContext(finalMessages);
+				if (compacted !== finalMessages) {
+					finalMessages = compacted;
+					finalProjection = measureProviderPayload(finalMessages);
+					require_events.emitAgentLog(config, finalProjection.fits ? "warn" : "error", "graph", finalProjection.fits ? "Synthetic provider context compacted to fit the final payload budget" : "Final provider payload still exceeds budget after synthetic context compaction", {
+						projectedMessageTokens: finalProjection.projectedMessageTokens,
+						availableMessageTokens: finalProjection.availableMessageTokens
+					}, {
+						runId: this.runId,
+						agentId
+					});
+				}
 			}
-			if (require_request.isThinkingEnabled(agentContext.provider, agentContext.clientOptions))
- /**
-			* Pass `this.startIndex` so the function can distinguish CURRENT-run
-			* AI messages (the agent's own iterations — possibly without a
-			* leading thinking block, which Claude is allowed to skip) from
-			* historical context that genuinely needs the
-			* `[Previous agent context]` placeholder. Without this signal the
-			* function would convert the agent's own in-run tool_use messages,
-			* polluting the next iteration's prompt with a placeholder the
-			* model treats as suspicious injected content.
-			*/
-			finalMessages = require_format.ensureThinkingBlockInMessages(finalMessages, agentContext.provider, config, this.startIndex);
 			/**
-			* A destination that binds no tools is invoked without a tool schema, but
-			* in a multi-agent graph it can still inherit a prior agent's toolUse/
-			* toolResult history. Bedrock's Converse API (and other tool-schema-strict
-			* providers) reject such a request when no top-level toolConfig is sent.
-			* Fold that historical tool content into plain text so the tool-less agent
-			* receives valid, context-preserving messages. Handoff tools count as
-			* bound tools, so a tool-less router mid-handoff is not affected.
+			* Mistral rejects consecutive user turns outright; Bedrock's Converse
+			* API documents strict user/assistant alternation across its model
+			* families, with enforcement varying by family (Claude on Converse
+			* currently tolerates the shape — verified live — but the payload is
+			* normalized for all of them rather than betting on leniency). Four
+			* sites can emit them — the `PostToolBatch` and `PreemptBoundary` hook
+			* boundaries (a consolidated context message followed by one
+			* `HumanMessage` per injected entry), a queue drain carrying more than
+			* one steer, and `run.ts`'s pre-stream context push onto a payload that
+			* already ends on a user turn.
+			*
+			* Normalized here, at the last provider-facing hop, rather than at any
+			* one boundary: the boundaries must keep per-message identity, because
+			* `additional_kwargs.source`/`skillName` drive steer rendering and the
+			* trailing-steer anchor downstream. Graph state and the host's
+			* persisted messages are untouched — this shapes only what goes on the
+			* wire, for the providers that actually care.
+			*
+			* Runs AFTER synthetic-context compaction: that pass can rewrite or
+			* drop messages, so coalescing has to see its output, and it is the
+			* last shaping step before the cache breakpoint is chosen.
 			*/
-			if (toolsForBinding == null || toolsForBinding.length === 0) {
-				finalMessages = require_format.foldToolBlocksForToollessAgent(finalMessages, config);
-				if (agentContext.useLegacyContent) finalMessages = require_content.formatContentStrings(finalMessages);
+			if (require_alternation.strictAlternationProviders.has(agentContext.provider)) {
+				/**
+				* Wrapped like every other provider transform: the merged message is
+				* a NEW object, and without re-attachment the final pre-invoke
+				* measurement would drop both source turns' calibrated shares and
+				* recharge the merge at full raw estimate — enough to flip a
+				* just-fits payload (the synthetic-context compaction above binary
+				* searches to exactly that) into a spurious pre-invoke overflow. The
+				* merge keeps the first source's id, so the keyed branch re-attaches
+				* that origin; the absorbed turn's tokens are charged as new raw
+				* growth, which only ever under-estimates by less than the old
+				* behavior over-estimated.
+				*/
+				const beforeCoalesce = finalMessages;
+				finalMessages = trackProviderMessageOrigins(beforeCoalesce, require_alternation.coalesceAdjacentUserTurns(beforeCoalesce));
 			}
 			const anthropicPromptCacheEnabled = agentContext.provider === "anthropic" && agentContext.clientOptions?.promptCache === true;
 			const openRouterPromptCacheEnabled = agentContext.provider === "openrouter" && agentContext.clientOptions?.promptCache === true;
@@ -1077,7 +1525,11 @@ var StandardGraph = class StandardGraph extends Graph {
 			const providerPromptCacheEnabled = anthropicPromptCacheEnabled || openRouterPromptCacheEnabled || bedrockPromptCacheEnabled;
 			if (anthropicLike && (!agentContext.pruneMessages || finalMessages !== messagesToUse || providerPromptCacheEnabled)) {
 				const beforeSanitize = finalMessages.length;
-				finalMessages = require_prune.sanitizeOrphanToolBlocks(finalMessages);
+				const beforeSanitizeMessages = finalMessages;
+				finalMessages = trackProviderMessageOrigins(beforeSanitizeMessages, require_prune.sanitizeOrphanToolBlocks(beforeSanitizeMessages, (source, clone) => {
+					const origin = providerMessageOrigins.get(source);
+					if (origin != null) providerMessageOrigins.set(clone, origin);
+				}));
 				if (finalMessages.length !== beforeSanitize) require_events.emitAgentLog(config, "warn", "sanitize", "Orphan tool blocks removed", {
 					before: beforeSanitize,
 					after: finalMessages.length,
@@ -1087,11 +1539,34 @@ var StandardGraph = class StandardGraph extends Graph {
 					agentId
 				});
 			}
-			if ((anthropicPromptCacheEnabled || openRouterPromptCacheEnabled) && !agentContext.systemRunnable) finalMessages = require_cache.addTailCacheControl(finalMessages, require_cache.resolvePromptCacheTtl(anthropicPromptCacheEnabled ? agentContext.clientOptions?.promptCacheTtl : agentContext.clientOptions?.promptCacheTtl));
-			else if (bedrockPromptCacheEnabled) {
+			if ((anthropicPromptCacheEnabled || openRouterPromptCacheEnabled) && !agentContext.systemRunnable) {
+				const beforeCacheControl = finalMessages;
+				finalMessages = trackProviderMessageOrigins(beforeCacheControl, require_cache.addTailCacheControl(beforeCacheControl, require_cache.resolvePromptCacheTtl(anthropicPromptCacheEnabled ? agentContext.clientOptions?.promptCacheTtl : agentContext.clientOptions?.promptCacheTtl)));
+			} else if (bedrockPromptCacheEnabled) {
 				const bedrockOptions = agentContext.clientOptions;
-				finalMessages = require_cache.addBedrockTailCacheControl(finalMessages, require_cache.resolveBedrockPromptCacheTtl(bedrockOptions?.promptCacheTtl, bedrockOptions?.model));
+				const beforeCacheControl = finalMessages;
+				finalMessages = trackProviderMessageOrigins(beforeCacheControl, require_cache.addBedrockTailCacheControl(beforeCacheControl, require_cache.resolveBedrockPromptCacheTtl(bedrockOptions?.promptCacheTtl, bedrockOptions?.model)));
 			}
+			const fallbackBaseMessages = finalMessages;
+			const beforeFinalProviderProjection = fallbackBaseMessages;
+			finalMessages = trackProviderMessageOrigins(beforeFinalProviderProjection, require_invoke.projectMessagesForProvider({
+				model: this.overrideModel ?? model,
+				messages: beforeFinalProviderProjection,
+				provider: agentContext.provider,
+				maxToolResultChars: maxProviderToolResultChars,
+				callOptions: config
+			}));
+			/**
+			* Prompt-cache placement and orphan sanitization are provider-wire
+			* transforms too. Re-measure after both so no content added after the
+			* earlier artifact/synthetic compaction decision can bypass the guard.
+			*/
+			finalProjection = measureProviderPayload(finalMessages);
+			const preInvokeContextOverflowError = !finalProjection.fits ? createProviderPayloadOverflowError({
+				projection: finalProjection,
+				provider: agentContext.provider,
+				info: "Provider message formatting exceeded the context budget and no safe synthetic-context compaction could make it fit."
+			}) : void 0;
 			if (agentContext.lastStreamCall != null && agentContext.streamBuffer != null) {
 				const timeSinceLastCall = Date.now() - agentContext.lastStreamCall;
 				if (timeSinceLastCall < agentContext.streamBuffer) await require_run.sleep(Math.ceil((agentContext.streamBuffer - timeSinceLastCall) / 1e3) * 1e3);
@@ -1125,28 +1600,9 @@ var StandardGraph = class StandardGraph extends Graph {
 			}
 			/** Past the empty-prompt guard — a model call is now guaranteed */
 			if (contextUsage != null) {
-				const usageRatio = contextUsage.calibrationRatio != null && contextUsage.calibrationRatio > 0 ? contextUsage.calibrationRatio : 1;
-				if (agentContext.tokenCounter != null && finalMessages.length !== messagesToUse.length) {
-					/** Post-prune formatting restructured the payload (e.g. thinking
-					*  placeholder collapse, orphan drops) — recount so the gauge
-					*  reflects what is actually sent */
-					let rawTokens = 0;
-					for (const message of finalMessages) rawTokens += agentContext.tokenCounter(message);
+				if (finalProjection.projectedMessageTokens != null && finalProjection.availableMessageTokens != null) {
 					contextUsage.breakdown.messageCount = finalMessages.length;
-					if (contextUsage.contextBudget != null && contextUsage.effectiveInstructionTokens != null) contextUsage.remainingContextTokens = Math.max(0, contextUsage.contextBudget - contextUsage.effectiveInstructionTokens - Math.round(rawTokens * usageRatio));
-				} else if (preFormatTailTokens != null && agentContext.tokenCounter != null && contextUsage.remainingContextTokens != null) {
-					/** Same-length formatting can still mutate in place — the trailing
-					*  tool batch (artifacts, Bedrock rewrites) and any legacy-converted
-					*  messages before it — adjust remaining by the calibrated delta */
-					let postFormatTailTokens = 0;
-					for (const message of finalMessages.slice(tailStart)) postFormatTailTokens += agentContext.tokenCounter(message);
-					let formatDelta = postFormatTailTokens - preFormatTailTokens;
-					if (legacyIndices != null && legacyIndices.length > 0) {
-						let postFormatLegacyTokens = 0;
-						for (const index of legacyIndices) postFormatLegacyTokens += agentContext.tokenCounter(finalMessages[index]);
-						formatDelta += postFormatLegacyTokens - preFormatLegacyTokens;
-					}
-					if (formatDelta !== 0) contextUsage.remainingContextTokens = Math.max(0, Math.min(contextUsage.contextBudget ?? Number.MAX_SAFE_INTEGER, contextUsage.remainingContextTokens - Math.round(formatDelta * usageRatio)));
+					contextUsage.remainingContextTokens = Math.max(0, finalProjection.availableMessageTokens - finalProjection.projectedMessageTokens);
 				}
 				require_budget.syncBudgetDerivedFields(contextUsage);
 				/** Awaited so async host handlers receive the pre-invoke snapshot
@@ -1194,6 +1650,7 @@ var StandardGraph = class StandardGraph extends Graph {
 			}
 			const metadata = config.metadata;
 			try {
+				if (preInvokeContextOverflowError != null) throw preInvokeContextOverflowError;
 				result = await require_langfuseRuntimeScope.withLangfuseRuntimeScope(require_langfuseRuntimeScope.resolveLangfuseRuntimeScope({
 					runLangfuse: this.langfuse,
 					langfuseOverlay: agentContext.langfuse
@@ -1223,31 +1680,37 @@ var StandardGraph = class StandardGraph extends Graph {
 				* 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 getLocalProviderOverflowMeasurement = (error) => typeof error === "object" && error !== null ? localProviderOverflowMeasurements.get(error) : void 0;
+				const getRecoveryPromptEstimate = (error, fallbackContext) => {
+					const resolvedFallbackContext = fallbackContext ?? require_invoke.getFallbackErrorContext(error);
+					return getLocalProviderOverflowMeasurement(error)?.estimatedPromptTokens ?? (resolvedFallbackContext == null ? estimatedPromptTokens : void 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 localMeasurement = getLocalProviderOverflowMeasurement(error);
+					const recoveryPromptEstimate = getRecoveryPromptEstimate(error, fallbackContext);
+					/**
+					* A previous correction that left the rejected prompt no smaller
+					* proves this state has nothing left to compact. Use the fallback
+					* projection when one exists so unlike provider formats are never
+					* compared through the primary's cheaper pre-projection estimate.
+					*/
+					if (agentContext.overflowRecoveryStalled(recoveryPromptEstimate)) return null;
 					const recovery = require_contextOverflowRecovery.planContextOverflowRecovery({
 						error,
 						provider: fallbackContext?.provider ?? agentContext.provider,
-						maxContextTokens: fallbackContext?.maxContextTokens ?? agentContext.maxContextTokens,
-						estimatedPromptTokens,
+						maxContextTokens: localMeasurement?.contextBudget ?? fallbackContext?.maxContextTokens ?? agentContext.maxContextTokens,
+						estimatedPromptTokens: recoveryPromptEstimate,
 						calibrationRatio: agentContext.calibrationRatio,
 						instructionTokens: agentContext.instructionTokens,
 						canSummarize: agentContext.summarizationEnabled === true,
@@ -1257,20 +1720,23 @@ var StandardGraph = class StandardGraph extends Graph {
 					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)),
+						budgetTokens: minDefined(require_contextOverflowRecovery.getBlindRecoveryBudget(agentContext.maxContextTokens), localMeasurement != null ? recovery.budgetTokens : 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
-				});
+				if (recovery != null) {
+					const recoveryPromptEstimate = getRecoveryPromptEstimate(primaryError);
+					return this.beginOverflowRecovery({
+						recovery,
+						agentContext,
+						agentId,
+						config,
+						originalToolContent: prunedOriginalToolContent,
+						estimatedPromptTokens: recoveryPromptEstimate
+					});
+				}
 				/**
 				* A fallback can reject the same prompt as too large even when the
 				* primary failed for an unrelated reason — a fallback with a smaller
@@ -1284,7 +1750,7 @@ var StandardGraph = class StandardGraph extends Graph {
 					}), () => require_invoke.tryFallbackProviders({
 						fallbacks,
 						tools: agentContext.tools,
-						messages: finalMessages,
+						messages: fallbackBaseMessages,
 						config: invokeConfig,
 						primaryError,
 						context: this,
@@ -1297,16 +1763,52 @@ var StandardGraph = class StandardGraph extends Graph {
 							provider: agentContext.provider,
 							estimatedPromptTokens: getEstimatedPromptTokens(contextUsage),
 							maxContextTokens: agentContext.maxContextTokens
+						},
+						prepareProviderMessages: ({ model: fallbackModel, messages: fallbackMessages, provider: fallbackProvider, maxContextTokens: fallbackMaxContextTokens, config: fallbackConfig }) => {
+							const fallbackToolResultChars = agentContext.maxToolResultChars ?? require_truncation.calculateMaxToolResultChars(fallbackMaxContextTokens ?? agentContext.maxContextTokens);
+							/**
+							* Serving-provider cue shaping BEFORE the fallback payload
+							* is measured: a Claude fallback behind a tolerant primary
+							* gains the cue inside the guarded projection (a prompt
+							* within the cue's cost of the fallback budget must take
+							* the recovery path, not ship oversized), and a tolerant
+							* fallback behind an Anthropic primary sheds the baked cue
+							* before it is measured against the tighter budget. The
+							* attemptInvoke funnel pass then finds nothing to change.
+							*/
+							const cueShapedFallbackMessages = trackProviderMessageOrigins(fallbackMessages, require_llm.isAnthropicLike(fallbackProvider, { model: require_invoke.resolveServingModelId(fallbackModel) }) ? require_handoffCue.appendPredecessorHandoffCue(fallbackMessages, (m) => this.isRunProducedMessage(m)) : require_handoffCue.removePredecessorHandoffCue(fallbackMessages));
+							const projectedFallbackMessages = trackProviderMessageOrigins(cueShapedFallbackMessages, require_invoke.projectMessagesForProvider({
+								model: fallbackModel,
+								messages: cueShapedFallbackMessages,
+								provider: fallbackProvider,
+								maxToolResultChars: fallbackToolResultChars,
+								callOptions: fallbackConfig
+							}));
+							const primaryContextBudget = contextUsage?.contextBudget;
+							const projection = measureProviderPayload(projectedFallbackMessages, fallbackMaxContextTokens == null ? primaryContextBudget : Math.min(primaryContextBudget ?? fallbackMaxContextTokens, fallbackMaxContextTokens), true);
+							if (!projection.fits) throw createProviderPayloadOverflowError({
+								projection,
+								provider: fallbackProvider,
+								info: "Fallback provider message formatting exceeded the context budget before invocation."
+							});
+							return projectedFallbackMessages;
 						}
 					}));
 				} catch (fallbackError) {
 					const overflowCandidates = require_invoke.getFallbackOverflowCandidates(fallbackError);
 					let fallbackRecovery = null;
+					let fallbackRecoveryPromptEstimate;
 					for (const candidate of overflowCandidates) {
 						fallbackRecovery = planRecovery(candidate.error, candidate.context);
-						if (fallbackRecovery != null) break;
+						if (fallbackRecovery != null) {
+							fallbackRecoveryPromptEstimate = getRecoveryPromptEstimate(candidate.error, candidate.context);
+							break;
+						}
+					}
+					if (overflowCandidates.length === 0) {
+						fallbackRecovery = planRecovery(fallbackError);
+						fallbackRecoveryPromptEstimate = getRecoveryPromptEstimate(fallbackError);
 					}
-					if (overflowCandidates.length === 0) fallbackRecovery = planRecovery(fallbackError);
 					if (fallbackRecovery == null) throw fallbackError;
 					return this.beginOverflowRecovery({
 						recovery: fallbackRecovery,
@@ -1314,7 +1816,7 @@ var StandardGraph = class StandardGraph extends Graph {
 						agentId,
 						config,
 						originalToolContent: prunedOriginalToolContent,
-						estimatedPromptTokens
+						estimatedPromptTokens: fallbackRecoveryPromptEstimate
 					});
 				}
 			} finally {
@@ -1337,6 +1839,22 @@ var StandardGraph = class StandardGraph extends Graph {
 			* handled everything — both paths become no-ops.
 			*/
 			const responseMessage = result.messages?.[0];
+			/**
+			* Provenance for the handoff-cue gate: recorded at the node, where the
+			* produced turn is unambiguous. The public ChatModel contract does not
+			* require implementations to set message ids — the reducer would
+			* assign one AFTER this node returns, which is too late for the set —
+			* so an id is assigned here first, the same way the reducer does it
+			* (`v4()`, mirrored into `lc_kwargs`), and the reducer's
+			* keep-existing-id rule makes the state message match.
+			*/
+			if (responseMessage?.getType() === "ai") {
+				if (typeof responseMessage.id !== "string" || responseMessage.id === "") {
+					responseMessage.id = (0, uuid.v4)();
+					responseMessage.lc_kwargs.id = responseMessage.id;
+				}
+				this.runProducedAiMessageIds.add(responseMessage.id);
+			}
 			const toolCalls = responseMessage?.tool_calls;
 			const hasToolCalls = Array.isArray(toolCalls) && toolCalls.length > 0;
 			const responseReasoningContent = getResponseReasoningContent({
@@ -1401,8 +1919,16 @@ var StandardGraph = class StandardGraph extends Graph {
 			}
 			const invokeElapsed = ((Date.now() - invokeStart) / 1e3).toFixed(2);
 			agentContext.currentUsage = this.getUsageMetadata(result.messages?.[0]);
+			/**
+			* Synthetic usage from a sealed turn is an estimate derived from the
+			* host's own counter, so feeding it to calibration would teach a ratio
+			* of exactly 1.0 — self-consistent by construction, and wrong for any
+			* provider whose real ratio differs. It still flows to `currentUsage`
+			* for host billing; it just does not get to move the EMA.
+			*/
+			const estimatedUsage = (result.messages?.[0])?.response_metadata.estimated_usage === true;
 			if (agentContext.currentUsage) {
-				agentContext.updateLastCallUsage(agentContext.currentUsage);
+				if (!estimatedUsage) agentContext.updateLastCallUsage(agentContext.currentUsage);
 				require_events.emitAgentLog(config, "debug", "graph", `LLM call complete (${invokeElapsed}s)`, {
 					...agentContext.currentUsage,
 					elapsedSeconds: Number(invokeElapsed),
@@ -1414,10 +1940,157 @@ var StandardGraph = class StandardGraph extends Graph {
 				elapsedSeconds: Number(invokeElapsed),
 				messageCount: finalMessages.length
 			}, invokeMeta, { force: true });
+			if (responseMessage?.response_metadata.preempted === true) {
+				const { messages: injected, preventContinuation } = await this.dispatchPreemptBoundary(agentId, config);
+				/**
+				* Release before branching: the slot is held only for the duration of
+				* the drain, and an early return below must not strand it.
+				*/
+				this.releasePreemptSeal();
+				if (preventContinuation) {
+					/**
+					* A hook halted at the boundary. Commit the sealed turn and anything
+					* it injected, but do NOT self-loop: `preventContinuation` promises
+					* no further model turn, and the run-loop poll in `processStream`
+					* only sees the halt AFTER the next call would already have started
+					* — direct graph consumers never poll it at all. A trailing injected
+					* HumanMessage carries no tool calls, so `toolsCondition` routes it
+					* to END.
+					*/
+					this.preemptIncomplete = true;
+					/**
+					* A halting boundary that ALSO injected nothing is still an empty
+					* boundary by the `getPreemptStats().emptyBoundaries` contract —
+					* hosts use the counter for truncated-seal telemetry, and both
+					* paths end the turn with nothing to resume from.
+					*/
+					if (injected.length === 0) this.preemptEmptyBoundaries += 1;
+					this.cleanupSignalListener();
+					return injected.length > 0 ? { messages: [...result.messages ?? [], ...injected] } : result;
+				}
+				if (injected.length > 0) {
+					this.pendingPreemptReturn.add(agentId);
+					this.cleanupSignalListener();
+					return { messages: [...result.messages ?? [], ...injected] };
+				}
+				/**
+				* Nothing to inject — the host cancelled or already drained. Do NOT
+				* self-loop: a trailing model turn with no new input is dropped by
+				* some Gemini models and read as prefill by Anthropic. Do NOT pretend
+				* the turn completed either; the answer really was cut short.
+				*/
+				this.preemptEmptyBoundaries += 1;
+				this.preemptIncomplete = true;
+			}
 			this.cleanupSignalListener();
 			return result;
 		};
 	}
+	/**
+	* Fires `PreemptBoundary` after a sealed turn and returns whatever the
+	* hooks asked to inject, converted through the same `convertInjectedMessages`
+	* the tool boundary uses so the two sites cannot emit different shapes.
+	*
+	* Never throws: a drain that fails or times out costs the injection, not the
+	* run. The caller treats an empty result as "nothing to resume with".
+	*
+	* `preventContinuation` is surfaced alongside the messages rather than left
+	* to the registry halt signal, which `processStream` only polls between
+	* stream events — by then the self-loop it was meant to prevent has already
+	* issued another model call, and a direct graph consumer never polls it.
+	*/
+	async dispatchPreemptBoundary(agentId, config) {
+		if (this.hookRegistry == null) return EMPTY_PREEMPT_BOUNDARY;
+		const configurable = config?.configurable;
+		const runId = configurable?.run_id ?? this.runId;
+		if (runId == null) return EMPTY_PREEMPT_BOUNDARY;
+		const result = await require_executeHooks.executeHooks({
+			registry: this.hookRegistry,
+			input: {
+				hook_event_name: "PreemptBoundary",
+				runId,
+				threadId: configurable?.thread_id,
+				agentId: this.subagentScope ? agentId : void 0,
+				executingAgentId: agentId,
+				sealCount: this.preemptSealCount
+			},
+			sessionId: runId,
+			timeoutMs: require_constants.PREEMPT_BOUNDARY_HOOK_TIMEOUT_MS,
+			/**
+			* The host's own abort signal(s), deliberately NOT `config.signal` —
+			* inside a node the latter is LangGraph's composed signal, which also
+			* fires when an unrelated sibling in the same superstep throws.
+			* Cancellation already returns control in milliseconds without this;
+			* what it buys is that a drain does not keep running after the run it
+			* belongs to died.
+			*
+			* Composed because the host can cancel through either channel: the
+			* construction signal, or the per-call `callerConfig.signal` — the only
+			* one a multi-agent run has, since `MultiAgentGraphConfig` exposes no
+			* construction signal. When both exist they may be different
+			* controllers, and a drain must stop when EITHER fires.
+			*/
+			signal: composeAbortSignals(this.signal, this.callerSignal)
+		}).catch(() => void 0);
+		if (result == null) return EMPTY_PREEMPT_BOUNDARY;
+		/**
+		* `executeHooks` raises a registry halt whenever a hook returns
+		* `preventContinuation`. That halt has exactly one consumer — the poll in
+		* `Run.processStream` — and its `break` cancels the stream iterator, which
+		* aborts Pregel. The abort lands BEFORE the outer reducer commits
+		* `StandardGraph.messages`, so honoring the halt here would destroy the
+		* sealed assistant turn: the run returns empty content and the host
+		* persists nothing. Measured deterministically — the commit is several
+		* stream events downstream of the point the halt becomes observable.
+		*
+		* The `preventContinuation` branch in `createCallModel` already enforces
+		* the contract locally by declining to self-loop, and a sealed chunk
+		* provably carries no tool calls, so the turn routes to END after exactly
+		* one model call either way. Clearing the halt therefore costs nothing it
+		* was buying and saves the content the seal exists to preserve.
+		*
+		* Scoped to a halt this event raised, so a halt from an earlier hook in
+		* the same run — `haltRun` is first-write-wins — is left alone.
+		*/
+		const halt = this.hookRegistry.getHaltSignal(runId);
+		if (result.preventContinuation === true && halt?.source === "PreemptBoundary") {
+			this.preemptHaltReason = halt.reason;
+			this.hookRegistry.clearHaltSignal(runId);
+		}
+		const injected = [];
+		/**
+		* `PreemptBoundaryHookOutput` is `BaseHookOutput`, so `additionalContext`
+		* is part of the contract here just as it is at the tool boundary. It has
+		* to be materialized BEFORE the emptiness test, or a hook that returns
+		* context alone would read as "nothing to resume with" and cut the answer
+		* short. Same system-flavored `HumanMessage` convention `ToolNode` uses —
+		* Anthropic and Google reject a mid-conversation `SystemMessage`.
+		*/
+		/**
+		* Whitespace-only entries are dropped for the same reason empty
+		* `injectedMessages` are: `executeHooks` keeps them because their raw
+		* length is nonzero, but a blank turn is not something to resume from —
+		* it costs a model call and strict providers reject it outright.
+		*/
+		const contexts = result.additionalContexts.filter((context) => context.trim() !== "");
+		if (contexts.length > 0) injected.push(new _langchain_core_messages.HumanMessage({
+			content: contexts.join("\n\n"),
+			additional_kwargs: {
+				role: "system",
+				isMeta: true,
+				source: "hook"
+			}
+		}));
+		if (result.injectedMessages.length > 0) try {
+			injected.push(...require_injected.convertInjectedMessages(result.injectedMessages));
+		} catch (e) {
+			console.warn("[StandardGraph] Failed to convert PreemptBoundary injectedMessages:", e instanceof Error ? e.message : e);
+		}
+		return {
+			messages: injected,
+			preventContinuation: result.preventContinuation === true
+		};
+	}
 	createAgentNode(agentId) {
 		const getConfig = () => this.config;
 		const agentContext = this.agentContexts.get(agentId);
@@ -1527,6 +2200,12 @@ var StandardGraph = class StandardGraph extends Graph {
 		const summarizeNode = `${SUMMARIZE}${agentId}`;
 		const routeMessage = (state, config) => {
 			this.config = config;
+			/**
+			* A sealed turn that injected messages resumes in the SAME pregel run:
+			* back to the agent node as a new superstep, so the model continues in
+			* one assistant message instead of restarting the graph.
+			*/
+			if (this.pendingPreemptReturn.delete(agentId)) return agentNode;
 			if (state.summarizationRequest != null) return summarizeNode;
 			return require_ToolNode.toolsCondition(state, toolNode, this.invokedToolIds);
 		};
@@ -1690,13 +2369,16 @@ var StandardGraph = class StandardGraph extends Graph {
 		const stepId = graph.toolCallStepIds.get(data.id) ?? "";
 		if (!stepId) return false;
 		const { name, input: args, error } = data;
+		const eventValueLimit = require_truncation.calculateMaxToolResultChars();
+		const errorOutputPrefix = "Error processing tool";
+		const errorDetail = error?.message != null ? `: ${require_toolContent.serializeToolContentBounded(error.message, Math.max(0, eventValueLimit - 21 - 2))}` : "";
 		const runStep = graph.getRunStep(stepId);
 		if (!runStep) return false;
 		const tool_call = {
 			id: data.id,
 			name: name || "",
-			args: typeof args === "string" ? args : JSON.stringify(args),
-			output: `Error processing tool${error?.message != null ? `: ${error.message}` : ""}`,
+			args: require_toolContent.serializeToolContentBounded(args, eventValueLimit),
+			output: `${errorOutputPrefix}${errorDetail}`,
 			progress: 1
 		};
 		const handler = graph.handlerRegistry?.getHandler("on_run_step_completed");