@librechat/agents 3.4.6 → 3.5.0

package/dist/esm/run.mjs

@@ -70,11 +70,6 @@ function getStepScopedEventId(data) {
 	const candidate = data;
 	return typeof candidate.id === "string" ? candidate.id : void 0;
 }
-/**
-* Narrows an ON_RUN_STEP_COMPLETED payload (`{ result: ToolCompleteEvent }`)
-* to the ids step closure needs. Returns undefined for malformed payloads and
-* the resume race's empty step id.
-*/
 function getToolCompletion(data) {
 	if (data == null || typeof data !== "object") return;
 	const { result } = data;
@@ -138,29 +133,12 @@ var Run = class Run {
 	Graph;
 	returnContent = false;
 	skipCleanup = false;
-	/**
-	* Whether the compiled graph was built with a checkpointer (host-supplied
-	* or the HITL `MemorySaver` fallback). Captured at graph creation because
-	* the constructor can later overwrite `Graph.compileOptions` with the raw
-	* caller options, dropping the fallback checkpointer from that metadata.
-	*/
 	hasCheckpointer = false;
 	_streamResult;
-	/**
-	* Captured interrupt payload typed as `unknown` because the SDK
-	* does not validate the runtime shape — custom graph nodes can
-	* raise interrupts with arbitrary payloads (not just the SDK's
-	* `HumanInterruptPayload` union). The public `getInterrupt<T>()`
-	* lets callers assert the type they expect.
-	*/
 	_interrupt;
-	/** Per-run sequence for batch-unique activity-label trace-seed fallbacks. */
 	activityLabelSeq = 0;
-	/** Per-run sequence for parent activity-phase trace and invocation ids. */
 	activityPhaseLabelSeq = 0;
-	/** Latest user turn used to keep detached phase roots conversation-shaped. */
 	activityPhaseTraceInput;
-	/** Distinguishes sibling forks started from the same explicit checkpoint. */
 	checkpointForkSeq = 0;
 	_haltedReason;
 	constructor(config) {
@@ -185,12 +163,10 @@ var Run = class Run {
 		this.preemption = config.preemption;
 		this.streamLimits = config.streamLimits;
 		if (!config.graphConfig) throw new Error("Graph config not provided");
-		/** Handle different graph types */
 		if (config.graphConfig.type === "multi-agent") {
 			this.graphRunnable = this.createMultiAgentGraph(config.graphConfig);
 			if (this.Graph) this.Graph.handlerRegistry = handlerRegistry;
 		} else {
-			/** Default to legacy graph for 'standard' or undefined type */
 			this.graphRunnable = this.createLegacyGraph(config.graphConfig);
 			if (this.Graph) this.Graph.handlerRegistry = handlerRegistry;
 		}
@@ -201,13 +177,11 @@ var Run = class Run {
 	createLegacyGraph(config) {
 		let agentConfig;
 		let signal;
-		/** Check if this is a multi-agent style config (has agents array) */
 		if ("agents" in config && Array.isArray(config.agents)) {
 			if (config.agents.length === 0) throw new Error("At least one agent must be provided");
 			agentConfig = config.agents[0];
 			signal = config.signal;
 		} else {
-			/** Legacy path: build agent config from llmConfig */
 			const { type: _type, llmConfig, signal: legacySignal, tools = [], ...agentInputs } = config;
 			const { provider, ...clientOptions } = llmConfig;
 			agentConfig = {
@@ -234,7 +208,6 @@ var Run = class Run {
 				streamLimits: this.streamLimits
 			}
 		});
-		/** Propagate compile options from graph config */
 		standardGraph.compileOptions = this.applyHITLCheckpointerFallback(config.compileOptions);
 		this.hasCheckpointer = standardGraph.compileOptions?.checkpointer != null;
 		applyGraphRuntimeConfig(standardGraph, {
@@ -280,20 +253,6 @@ var Run = class Run {
 		this.Graph = multiAgentGraph;
 		return multiAgentGraph.createWorkflow();
 	}
-	/**
-	* When the host opted into HITL via `humanInTheLoop: { enabled: true }`
-	* and did not supply a checkpointer, install an in-memory `MemorySaver`
-	* so `interrupt()` can persist checkpoints and `Command({ resume })`
-	* can rebuild state. The fallback is intentionally process-local:
-	* production hosts that need durable resumption across processes /
-	* restarts must provide their own checkpointer (Redis, Postgres, etc.)
-	* on `compileOptions.checkpointer`.
-	*
-	* No-op when HITL is off (the default — omitted, or
-	* `{ enabled: false }`) or the host already supplied a checkpointer
-	* of their own. See `HumanInTheLoopConfig` JSDoc for the rationale
-	* behind the default-off stance.
-	*/
 	applyHITLCheckpointerFallback(compileOptions) {
 		if (this.humanInTheLoop?.enabled !== true) return compileOptions;
 		if (compileOptions?.checkpointer != null) return compileOptions;
@@ -302,50 +261,8 @@ var Run = class Run {
 			checkpointer: new MemorySaver()
 		};
 	}
-	/**
-	* Run RunStart + UserPromptSubmit hooks before the graph stream
-	* begins, accumulate any `additionalContext` strings into the input
-	* messages, and short-circuit when a hook signals the run should not
-	* proceed (deny / ask decision on the prompt, or `preventContinuation`
-	* on either hook).
-	*
-	* Returns `true` when the caller should bail with `undefined` (run
-	* was halted before any model call); returns `false` to proceed
-	* into the stream loop.
-	*
-	* ## Side effects
-	*
-	* On the success path:
-	*   - Mutates `stateInputs.messages` in place to append a
-	*     consolidated `HumanMessage` carrying any hook
-	*     `additionalContext` strings. Safe because the host owns the
-	*     array and `processStream` is the only consumer until LangGraph
-	*     reads it.
-	*
-	* On the halt path (returning `true`):
-	*   - Sets `this._haltedReason` so callers (and the eventual host)
-	*     can distinguish a hook-driven halt from a natural completion.
-	*   - Calls `registry.clearSession(this.id)` and
-	*     `registry.clearHaltSignal(this.id)` because no resume is
-	*     expected from a pre-stream halt — the run never entered the
-	*     graph, so the session/halt state for this run would otherwise
-	*     leak to the next `processStream` invocation on the same
-	*     registry. Other concurrent runs on the same registry are
-	*     untouched (halt signals are scoped per session id).
-	*   - Sets `config.callbacks = undefined` to drop the callback
-	*     references the caller built (langfuse handler, custom event
-	*     handler, etc.) since they won't be exercised. Mirrors the
-	*     equivalent cleanup the `processStream` `finally` block does
-	*     on the natural-completion path.
-	*/
 	async runPreStreamHooks(stateInputs, threadId, config) {
 		const registry = this.hookRegistry;
-		/**
-		* Defensive guard: `processStream` already validated `this.Graph`
-		* before calling this helper, but TypeScript can't propagate that
-		* narrowing across method boundaries. The check keeps the body
-		* free of `this.Graph!` non-null assertions.
-		*/
 		if (registry == null || this.Graph == null) return false;
 		const preStreamContexts = [];
 		const runStartResult = await executeHooks({
@@ -360,13 +277,6 @@ var Run = class Run {
 			sessionId: this.id
 		});
 		for (const ctx of runStartResult.additionalContexts) preStreamContexts.push(ctx);
-		/**
-		* Honor `preventContinuation` from RunStart before the stream
-		* starts. Mid-flight halts (from tool/compact/subagent hooks)
-		* route through `HookRegistry.haltRun` and are polled by the
-		* stream loop in `processStream` — different mechanism, same
-		* intent.
-		*/
 		if (runStartResult.preventContinuation === true) {
 			this._haltedReason = runStartResult.stopReason ?? "preventContinuation";
 			registry.clearSession(this.id);
@@ -388,13 +298,6 @@ var Run = class Run {
 				sessionId: this.id
 			});
 			if (promptResult.decision === "deny" || promptResult.decision === "ask" || promptResult.preventContinuation === true) {
-				/**
-				* Always set `_haltedReason` so the host can call
-				* `getHaltReason()` and distinguish a hook-blocked prompt
-				* from a natural empty-output completion. Three signals can
-				* land here, each with its own canonical reason string when
-				* the hook didn't supply one.
-				*/
 				if (promptResult.preventContinuation === true) this._haltedReason = promptResult.stopReason ?? "preventContinuation";
 				else if (promptResult.decision === "deny") this._haltedReason = promptResult.reason ?? "prompt_denied";
 				else this._haltedReason = promptResult.reason ?? "prompt_requires_approval";
@@ -405,20 +308,7 @@ var Run = class Run {
 			}
 			for (const ctx of promptResult.additionalContexts) preStreamContexts.push(ctx);
 		}
-		if (preStreamContexts.length > 0)
- /**
-		* Wraps the joined hook contexts as a `HumanMessage` even though
-		* the intent is system-level guidance. Using a `SystemMessage`
-		* mid-conversation is rejected by Anthropic and Google providers
-		* (system messages must be the leading entry), so the LangChain
-		* convention — also used by `ToolNode.convertInjectedMessages`
-		* — is `HumanMessage` carrying `additional_kwargs.role` as a
-		* marker for hosts inspecting state. The model still sees a
-		* user-role message; the `role: 'system'` field is metadata
-		* only. Hosts that want a true system message should compose
-		* it into the agent's `instructions` config instead.
-		*/
-		stateInputs.messages.push(new HumanMessage({
+		if (preStreamContexts.length > 0) stateInputs.messages.push(new HumanMessage({
 			content: preStreamContexts.join("\n\n"),
 			additional_kwargs: {
 				role: "system",
@@ -428,7 +318,6 @@ var Run = class Run {
 		return false;
 	}
 	static async create(config) {
-		/** Create tokenCounter if indexTokenCountMap is provided but tokenCounter is not */
 		if (config.indexTokenCountMap && !config.tokenCounter) {
 			const gc = config.graphConfig;
 			config.tokenCounter = await createTokenCounter(encodingForModel(("agents" in gc ? gc.agents[0]?.clientOptions : gc.clientOptions)?.model ?? ""));
@@ -442,33 +331,16 @@ var Run = class Run {
 	getChildCheckpointThreadIds() {
 		return this.Graph?.getChildCheckpointThreadIds() ?? [];
 	}
-	/**
-	* Returns a defensive snapshot of tools discovered by the current run.
-	* Pass an agent id for that context, or omit it for the ordered union across
-	* contexts. Interrupted state is available immediately for host persistence;
-	* completed runs retain their final snapshot through graph cleanup.
-	*/
 	getDiscoveredTools(agentId) {
 		if (!this.Graph) throw new Error("Graph not initialized. Make sure to use Run.create() to instantiate the Run.");
 		return this.Graph.getDiscoveredTools(agentId);
 	}
-	/**
-	* Returns the current calibration ratio (EMA of provider-vs-estimate token ratios).
-	* Hosts should persist this value and pass it back as `RunConfig.calibrationRatio`
-	* on the next run for the same conversation so the pruner starts with an accurate
-	* scaling factor instead of the default (1).
-	*/
 	getCalibrationRatio() {
 		return this.calibrationRatio;
 	}
 	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,
@@ -478,35 +350,17 @@ var Run = class Run {
 	getToolCount() {
 		return this.Graph?.getToolCount() ?? 0;
 	}
-	/**
-	* Creates a custom event callback handler that intercepts custom events
-	* and processes them through our handler registry instead of EventStreamCallbackHandler
-	*/
 	createCustomEventCallback() {
 		return async (eventName, data, runId, tags, metadata) => {
 			const stepScopedEventId = getStepScopedEventId(data);
 			if (DIRECT_DISPATCHED_STEP_EVENTS.has(eventName) && this.Graph != null && stepScopedEventId != null && this.Graph.hasHandlerDispatchedEvent(eventName, stepScopedEventId)) return;
 			const handler = this.handlerRegistry?.getHandler(eventName);
-			/**
-			* Tool completions arriving over the custom-event channel are the only
-			* signal ToolNode (which holds no graph reference) emits — observe them
-			* here to drive step closure. Runs in `finally`, independent of handler
-			* registration, so an absent or throwing host handler cannot lose the
-			* close; duplicate callback echoes are absorbed by the terminal-status
-			* guard in `closeRunStep`.
-			*/
 			try {
 				if (handler && this.Graph) return await handler.handle(eventName, data, metadata, this.Graph);
 			} finally {
 				if (eventName === "on_run_step_completed" && this.Graph != null) {
 					const completion = getToolCompletion(data);
-					if (completion != null)
- /**
-					* The producer stamped `completed_at` before dispatch. Carrying it
-					* through keeps the recorded duration the tool's, not the host
-					* handler's — this runs after an arbitrarily slow handler resolves.
-					*/
-					await this.Graph.recordStepCompletion(completion.stepId, {
+					if (completion != null) await this.Graph.recordStepCompletion(completion.stepId, {
 						toolCallId: completion.toolCallId,
 						metadata,
 						at: completion.completedAt
@@ -521,13 +375,6 @@ var Run = class Run {
 	isAwaitingResume(streamThrew) {
 		return this._interrupt != null && this._haltedReason == null && !streamThrew;
 	}
-	/**
-	* Terminal status for steps still open at end-of-run: `cancelled` for
-	* intentional stops (caller abort, hook halt), `failed` for unexpected
-	* stream errors, `completed` for a natural finish. Reads `_haltedReason`
-	* behind a method boundary on purpose — it is assigned inside the
-	* `consumeStream` closure, which control-flow narrowing cannot see.
-	*/
 	resolveSweepStatus(streamThrew, streamAborted) {
 		if (streamThrew) return streamAborted ? "cancelled" : "failed";
 		if (this._haltedReason != null) return "cancelled";
@@ -574,24 +421,9 @@ var Run = class Run {
 		if (!this.Graph) throw new Error("Graph not initialized. Make sure to use Run.create() to instantiate the Run.");
 		const graphRunnable = this.graphRunnable;
 		const graph = this.Graph;
-		/**
-		* `Command` inputs (`Command({ resume, update?, goto? })`) are
-		* resume-mode invocations: LangGraph rebuilds graph state from the
-		* checkpointer, so we skip RunStart / UserPromptSubmit hooks (no
-		* new prompt to evaluate) and read run-state from the Graph wrapper
-		* instead of `inputs.messages`.
-		*/
 		const isResume = inputs instanceof Command;
 		const stateInputs = isResume ? void 0 : inputs;
 		if (stateInputs != null) this.activityPhaseTraceInput = findActivityPhaseTraceInput(stateInputs.messages);
-		/**
-		* 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 = {
 			...callerConfig,
@@ -602,30 +434,7 @@ var Run = class Run {
 			delete config.configurable?.[SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY];
 			delete config.configurable?.[SUBAGENT_RESUME_MANIFEST_CONFIG_KEY];
 		}
-		/**
-		* 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
-		* `messages`, etc.) the resumed `ToolNode` needs to dispatch
-		* tool completions with the correct step ids and re-resolve
-		* `{{tool<i>turn<n>}}` references. Pairs with the
-		* `awaitingResume` gate on `clearHeavyState` in the `finally`
-		* block so the sidecars survive both ends of the interrupt
-		* boundary.
-		*/
 		if (!isResume) {
 			const checkpointThreadId = typeof config.configurable?.thread_id === "string" ? config.configurable.thread_id : void 0;
 			const checkpointNamespace = typeof config.configurable?.checkpoint_ns === "string" ? config.configurable.checkpoint_ns : "";
@@ -641,7 +450,6 @@ var Run = class Run {
 		this._interrupt = void 0;
 		this._haltedReason = void 0;
 		this.hookRegistry?.clearHaltSignal(this.id);
-		/** Custom event callback to intercept and handle custom events */
 		const customEventCallback = this.createCustomEventCallback();
 		const streamCallbacks = streamOptions?.callbacks ? this.getCallbacks(streamOptions.callbacks) : void 0;
 		const customHandler = BaseCallbackHandler.fromMethods({ ["handleCustomEvent"]: customEventCallback });
@@ -683,84 +491,27 @@ var Run = class Run {
 		if (!this.id) throw new Error("Run ID not provided");
 		config.run_id = this.id;
 		config.configurable = Object.assign(config.configurable ?? {}, { run_id: this.id });
-		/**
-		* Default `durability: 'exit'` whenever a checkpointer is active so
-		* runs skip per-superstep checkpoint writes and persist only at the
-		* exit/interrupt boundary (all HITL/resume needs). An explicit caller
-		* value wins; no checkpointer leaves it unset (langgraph default).
-		*/
 		if (config.durability == null && this.hasCheckpointer) config.durability = "exit";
 		const threadId = config.configurable.thread_id;
 		if (this.hookRegistry != null && stateInputs != null) {
 			if (await this.runPreStreamHooks(stateInputs, threadId, config)) return;
 		}
-		/**
-		* Tracks whether the stream loop threw. Used by the `finally`
-		* block to decide whether to honor the interrupt-preservation
-		* guard for session hooks: a captured `_interrupt` is only
-		* meaningful if the stream completed cleanly. If the loop errored
-		* after stashing an interrupt (e.g. a downstream handler throws
-		* after the interrupt event landed), the interrupt is stale —
-		* preserving session hooks would leak them into the next run.
-		*/
 		let streamThrew = false;
 		let streamAborted = false;
-		/**
-		* When the stream itself ended — captured before the post-stream work in
-		* the `finally` (Stop/StopFailure hooks, Langfuse disposal, which can
-		* force-flush) so a slow hook cannot inflate the terminal stamps that the
-		* sweep writes onto steps that were still open.
-		*/
 		let terminalAt;
 		const consumeStream = async () => {
-			/**
-			* `streamEvents` accepts both state inputs and `Command` (resume) at
-			* runtime, but our `CompiledStateWorkflow` type narrows the first
-			* arg to `BaseGraphState`. Cast on the call so the resume path
-			* type-checks without widening the wrapper for every caller.
-			*/
 			const stream = graphRunnable.streamEvents(inputs, config, {
 				raiseError: true,
-				/**
-				* Prevent EventStreamCallbackHandler from processing custom events.
-				* Custom events are already handled via our createCustomEventCallback()
-				* which routes them through the handlerRegistry.
-				* Without this flag, EventStreamCallbackHandler throws errors when
-				* custom events are dispatched for run IDs not in its internal map
-				* (due to timing issues in parallel execution or after run cleanup).
-				*/
 				ignoreCustomEvent: true
 			});
 			for await (const event of stream) {
 				const { data, metadata, ...info } = event;
 				const eventName = info.event;
-				/** Skip custom events as they're handled by our callback */
 				if (CUSTOM_GRAPH_EVENTS.has(eventName)) continue;
-				/**
-				* Detect interrupts surfaced by LangGraph as a synthetic
-				* `__interrupt__` field on the streamed chunk and stash the
-				* first one for the host to read via `run.getInterrupt()`
-				* once the stream drains. Captured as `unknown` because the
-				* SDK does not validate the runtime payload shape — the
-				* built-in ToolNode raises a `HumanInterruptPayload`
-				* (`tool_approval` / `ask_user_question`), but custom nodes
-				* can pass any payload to `interrupt()`. Callers narrow with
-				* the `isToolApprovalInterrupt` / `isAskUserQuestionInterrupt`
-				* guards or assert via `getInterrupt<T>()`.
-				*/
 				if (this._interrupt == null && data.chunk != null && isInterrupted(data.chunk)) {
 					const interrupts = data.chunk[INTERRUPT];
 					if (interrupts.length > 0) {
 						const first = interrupts[0];
-						/**
-						* Capture the interrupt unconditionally — `interrupt(null)`
-						* and `interrupt(undefined)` are valid pauses (a custom
-						* node may want to pause without metadata) and the host
-						* still needs to know the run is awaiting resume. Gating
-						* on `payload != null` would silently downgrade a paused
-						* run to "completed" and let the `Stop` hook fire,
-						* breaking host resume handling.
-						*/
 						this._interrupt = {
 							interruptId: first.id ?? "",
 							threadId,
@@ -768,42 +519,10 @@ var Run = class Run {
 						};
 					}
 				}
-				/**
-				* Stamped before the handler runs: the close below happens after an
-				* arbitrarily slow host handler resolves, and the step's duration
-				* should end when the model did, not when the host finished with it.
-				*/
 				const modelEndAt = eventName === "on_chat_model_end" ? Date.now() : void 0;
 				const handler = this.handlerRegistry?.getHandler(eventName);
 				if (handler) await handler.handle(eventName, data, metadata, this.Graph);
-				/**
-				* A finished model call ends its lane's open message step. Placed
-				* here — not in `ModelEndHandler` — because hosts replace the
-				* CHAT_MODEL_END handler with their own instance, which would
-				* silently drop the close.
-				*/
 				if (eventName === "on_chat_model_end" && this.Graph != null) await this.Graph.closeOpenMessageStep(metadata, modelEndAt);
-				/**
-				* Mid-flight halt: any hook (PreToolUse, PostToolUse,
-				* PostToolBatch, SubagentStart/Stop, PreCompact, PostCompact)
-				* that returned `preventContinuation: true` raises a halt
-				* signal on the registry via `executeHooks`. We poll between
-				* stream events and break out as soon as one is set so the
-				* graph doesn't take another model turn after the halting
-				* operation completes.
-				*
-				* 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) {
 					this._haltedReason = haltSignal.reason;
@@ -812,13 +531,6 @@ var Run = class Run {
 			}
 			terminalAt = Date.now();
 			if (this._interrupt != null) await this.resolveInterruptResumeConfig(config);
-			/**
-			* Skip the Stop hook when the run paused on a HITL interrupt
-			* (still pending human input) or was halted by a hook (the host
-			* already chose to stop, so a Stop hook firing now would be
-			* misleading). The host fires Stop on the resumed-and-completed
-			* run instead.
-			*/
 			if (this._interrupt == null && this._haltedReason == null && this.hookRegistry?.hasHookFor("Stop", this.id) === true) await executeHooks({
 				registry: this.hookRegistry,
 				input: {
@@ -827,35 +539,11 @@ 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";
 		};
@@ -871,13 +559,6 @@ var Run = class Run {
 		} catch (err) {
 			terminalAt = Date.now();
 			streamThrew = true;
-			/**
-			* Corroborate cancellation against an actually-aborted signal. A
-			* provider SDK or host handler can reject with an `AbortError` while
-			* nothing was cancelled — that is an unexpected failure (it also fires
-			* `StopFailure`), and naming it `cancelled` would misreport abort
-			* forensics.
-			*/
 			streamAborted = config.signal?.aborted === true || this.Graph.signal?.aborted === true;
 			if (this.hookRegistry?.hasHookFor("StopFailure", this.id) === true) {
 				const runMessages = this.Graph.getRunMessages() ?? [];
@@ -896,55 +577,12 @@ var Run = class Run {
 			}
 			throw err;
 		} finally {
-			/**
-			* Preserve session-scoped hooks when the run paused on a HITL
-			* interrupt — the very next call will be `Run.resume()`, which
-			* needs the same policy hooks (e.g., the `PreToolUse` matcher
-			* that triggered the interrupt) to fire on the re-executed node
-			* and uphold the approval flow. Clearing here would leak the
-			* approval gate on resume. The session is cleared instead at
-			* natural completion, error (including errors that happen AFTER
-			* an interrupt was captured — those interrupts are stale), or
-			* hook-driven halt (including hooks that returned BOTH `ask`
-			* and `preventContinuation` — the halt wins, no resume is
-			* expected, sessions must drop). Every state where no resume
-			* is expected clears.
-			*/
 			if (this.shouldClearHookSession(streamThrew)) this.hookRegistry?.clearSession(this.id);
-			/**
-			* Drop any halt signal raised mid-stream for this run so a
-			* subsequent `processStream` / `resume` starts with clean state.
-			* The Run captured `_haltedReason` already; the registry entry
-			* for this `sessionId` would otherwise spuriously trip the next
-			* loop. Other concurrent runs sharing this registry are
-			* unaffected — their entries live under their own session ids.
-			*/
 			this.hookRegistry?.clearHaltSignal(this.id);
 			await disposeLangfuseHandler(langfuseHandler);
-			/**
-			* Terminal sweep: close every step that never reached a terminal
-			* status — `completed` on a natural end, `cancelled` on caller abort
-			* or hook halt, `failed` on an unexpected stream error. Skipped on a
-			* HITL pause, where the open steps continue after `resume()`.
-			*
-			* Runs BEFORE the callback teardown below, so a caller observing
-			* lifecycle events only through `RunnableConfig.callbacks` still
-			* receives these closures rather than being left with unmatched
-			* starts, and before `getContentParts()` so terminal stamps flow into
-			* content and session serialization.
-			*/
 			if (!this.isAwaitingResume(streamThrew)) try {
 				await this.Graph.closeUnfinishedRunSteps(this.resolveSweepStatus(streamThrew, streamAborted), terminalAt);
 			} catch {}
-			/**
-			* Break the reference chain that keeps heavy data alive via
-			* LangGraph's internal `__pregel_scratchpad.currentTaskInput` →
-			* `@langchain/core` `RunTree.extra[lc:child_config]` →
-			* Node.js `AsyncLocalStorage` context captured by timers/promises.
-			*
-			* Without this, base64-encoded images/PDFs in message content remain
-			* reachable from lingering `Timeout` handles until GC runs.
-			*/
 			if (!this.skipCleanup) {
 				if (config.configurable != null) {
 					for (const key of Object.getOwnPropertySymbols(config.configurable)) {
@@ -958,52 +596,12 @@ var Run = class Run {
 			}
 			const result = this.returnContent ? this.Graph.getContentParts() : void 0;
 			this.calibrationRatio = this.Graph.getCalibrationRatio();
-			/**
-			* Skip `clearHeavyState()` when the run paused on a clean HITL
-			* interrupt awaiting resume — `Run.resume()` re-enters the same
-			* `ToolNode` instance and needs the sidecars `clearHeavyState`
-			* would wipe (`toolCallStepIds` for completion-event step ids,
-			* the `_toolOutputRegistry` for `{{tool<i>turn<n>}}`
-			* substitutions, `sessions` for code-env continuity, plus the
-			* `hookRegistry` and `humanInTheLoop` config the interrupt
-			* branch itself relies on). Without preservation, the resumed
-			* tool completion would dispatch `ON_RUN_STEP_COMPLETED` with
-			* an empty step id and downstream stream consumers would drop
-			* the result.
-			*
-			* The natural-completion / error / hook-driven-halt paths still
-			* clean up — `_haltedReason != null` or `streamThrew` mean no
-			* resume is expected. Cross-process resume (host rebuilds the
-			* Run from scratch) is a separate concern; see
-			* `HumanInTheLoopConfig` JSDoc.
-			*/
 			const awaitingResume = this.isAwaitingResume(streamThrew);
 			if (!this.skipCleanup && !awaitingResume) this.Graph.clearHeavyState();
 			this._streamResult = result;
 		}
 		return this._streamResult;
 	}
-	/**
-	* Returns the pending interrupt captured during the most recent
-	* `processStream` (or `resume`) invocation. `undefined` when the run
-	* either has not been streamed yet or completed without pausing.
-	*
-	* Hosts call this immediately after `processStream` returns to decide
-	* whether the run is awaiting human input. Persist the returned
-	* descriptor (alongside `thread_id` and the agent run config) so a
-	* later `resume(decisions)` can rebuild the run.
-	*
-	* The default `TPayload` is the SDK's `HumanInterruptPayload` union
-	* (`tool_approval` / `ask_user_question`), suitable for the common
-	* case where interrupts come from the built-in ToolNode or
-	* `askUserQuestion()` helper. Hosts that raise custom interrupts
-	* from custom graph nodes pass their own type — the SDK does not
-	* validate the runtime shape, it just transports whatever the
-	* `interrupt()` call carried. When in doubt, narrow with the
-	* `isToolApprovalInterrupt` / `isAskUserQuestionInterrupt` type
-	* guards (which accept `unknown`) before reading variant-specific
-	* fields.
-	*/
 	getInterrupt() {
 		if (this._interrupt == null) return;
 		return {
@@ -1011,74 +609,16 @@ var Run = class Run {
 			payload: stripSubagentResumeManifest(this._interrupt.payload)
 		};
 	}
-	/**
-	* Returns the reason a hook halted the run via
-	* `preventContinuation: true`, or `undefined` if no hook halted.
-	*
-	* Hosts inspect this after `processStream` returns to distinguish a
-	* natural completion (`undefined`) from a hook-driven halt (a
-	* truthy string). Independent from `getInterrupt()` — a halted run
-	* has no interrupt; an interrupted run has no halt reason.
-	*/
 	getHaltReason() {
 		return this._haltedReason;
 	}
-	/**
-	* Resume a paused HITL run with the value the user (or whatever
-	* decided the interrupt) supplied. The default `TResume` covers the
-	* `tool_approval` interrupt (the common case): an array of decisions
-	* in `action_requests` order, or a record keyed by `tool_call_id`.
-	*
-	* For other interrupt types (e.g., `ask_user_question` →
-	* `AskUserQuestionResolution`, or any custom interrupt a host raises
-	* from a custom node), pass the type parameter and the SDK forwards
-	* the value through unchanged. LangGraph delivers it as the return
-	* value of the original `interrupt()` call inside the paused node.
-	*
-	* The host MUST construct this Run with the same `thread_id` and the
-	* same checkpointer as the original paused run; LangGraph rebuilds
-	* graph state from the checkpoint and re-enters the interrupted node
-	* from the start.
-	*/
-	/**
-	* Returns the per-Run file checkpointer when
-	* `toolExecution.local.fileCheckpointing === true` was set on the
-	* RunConfig. Hosts can capture extra paths or call `rewind()`
-	* directly. Returns undefined when checkpointing is disabled.
-	*
-	* Construction-time invariant: the checkpointer is shared across
-	* every ToolNode the graph compiles (single-agent and multi-agent),
-	* so a `rewind()` call here unwinds writes made by ANY agent in the
-	* run.
-	*/
 	getFileCheckpointer() {
 		return this.Graph?.getOrCreateFileCheckpointer();
 	}
-	/**
-	* Convenience wrapper that calls `rewind()` on the per-Run file
-	* checkpointer. Restores every file the local engine snapshotted
-	* during this Run to its pre-write content (and deletes any path
-	* that didn't exist before being created). Returns the count of
-	* paths processed; returns 0 when checkpointing is disabled.
-	*/
 	async rewindFiles() {
 		const cp = this.getFileCheckpointer();
 		return cp == null ? 0 : cp.rewind();
 	}
-	/**
-	* Resume an interrupted run. `commandOptions` forwards langgraph 1.4.5
-	* `Command` fields applied together with `resume` in one superstep:
-	* - `update`: channel updates committed at the resume point. On a *rebuilt*
-	*   Run (new instance + durable checkpointer), `update.messages` are the first
-	*   write the fresh wrapper sees, so they seed the `getRunMessages()` /
-	*   `returnContent` baseline and are excluded from them (still committed to the
-	*   checkpoint). Hosts that rebuild + inject messages should persist them
-	*   directly or read from `getState`. Unreachable without a durable checkpointer.
-	* - `goto`: a *dynamic* edge that does not cancel static `addEdge` routes. On
-	*   the built-in standard graph the fixed `toolNode -> agentNode/END` edge still
-	*   fires, so `goto` adds rather than replaces (e.g. `goto: END` will not stop a
-	*   tool-node resume). Intended for custom, Command-routed graphs.
-	*/
 	async resume(resumeValue, callerConfig, streamOptions, commandOptions) {
 		const resumeConfig = await this.resolveInterruptResumeConfig(callerConfig, commandOptions?.update);
 		const interruptId = this._interrupt?.interruptId;
@@ -1188,16 +728,7 @@ var Run = class Run {
 			agentName: titleContext?.name
 		});
 		const titleRunName = getLangfuseTraceName(traceMetadata, "LibreChat Title");
-		/** Scope identity carries an opaque per-execution component: public run
-		*  ids are unrestricted, so a purely derived id (`title-<runId>`) could
-		*  collide with an ordinary concurrent run literally named that way and
-		*  defeat foreign-scope rejection. */
 		const titleScopeRunId = `title:${this.id}:${nanoid()}`;
-		/** Seed policy mirrors `generateActivityLabel`:
-		*  `runWithLangfuseRuntimeContext` SPREADS the surrounding context, so an
-		*  absent seed INHERITS an active parent run's and collapses the title
-		*  into that run's trace. Seeded when determinism is opted into OR a
-		*  parent seed is live; otherwise unseeded, matching the other paths. */
 		const inheritedTraceSeed = getTraceIdSeed();
 		const titleRuntimeScope = resolveLangfuseRuntimeScope({
 			runLangfuse: this.langfuse,
@@ -1244,7 +775,6 @@ var Run = class Run {
 			skipLanguage
 		}) }).withConfig({ runName: "PrepareTitleInput" });
 		const titleChain = titleMethod === "completion" ? await createCompletionTitleRunnable(model, titlePrompt) : await createTitleRunnable(model, titlePrompt);
-		/** Pipes `convoTemplate` -> `transformer` -> `titleChain` */
 		const fullChain = convoTemplate.withConfig({ runName: "FormatConversation" }).pipe(convoToTitleInput).pipe(titleChain).withConfig({ runName: "GenerateConversationTitle" });
 		const invokeConfig = Object.assign({}, chainOptions, {
 			run_id: this.id,
@@ -1275,38 +805,17 @@ var Run = class Run {
 			await disposeLangfuseHandler(titleLangfuseHandler);
 		}
 	}
-	/**
-	* Generates a short activity label for a completed tool/reasoning block
-	* using a fast model. Mirrors `generateTitle`'s Langfuse wiring so the
-	* call is traced under the conversation's session (sessionId from
-	* `chainOptions.configurable.thread_id`) with its own tags — never as an
-	* orphan trace. The payload contains no human messages by design: intent
-	* comes from `lastAssistantText`, content from reasoning excerpts and
-	* tool entries.
-	*/
 	async generateActivityLabel({ provider, clientOptions, entries, thinkingExcerpts, lastAssistantText, lastAssistantPhase, previousLabels, prompt, charLimit = 600, chainOptions, traceSeed, agentId }) {
 		if (entries.length === 0 && !(thinkingExcerpts && thinkingExcerpts.length > 0)) return {};
 		const labelSeq = ++this.activityLabelSeq;
-		/** Resolve the LABELED agent's context: its Langfuse overlay carries the
-		*  trace metadata and the tool-output redaction policy that must govern
-		*  this label. */
 		const requestedContext = this.Graph == null || agentId == null ? void 0 : this.Graph.agentContexts.get(agentId);
-		/** Fail closed: an explicit but unknown/stale `agentId` must NOT silently
-		*  fall back to the default agent, whose redaction policy may be weaker
-		*  than the labeled agent's. Skip generation entirely instead. */
 		if (agentId != null && requestedContext == null) return {};
 		const labelContext = this.Graph == null ? void 0 : requestedContext ?? this.Graph.agentContexts.get(this.Graph.defaultAgentId);
-		/** Shallow-cloned: activity labels run once per tool batch, and writing
-		*  the Langfuse handler back onto a host-reused `chainOptions` would
-		*  accumulate duplicate callbacks across batches. */
 		const labelChainOptions = { ...chainOptions ?? {} };
 		const labelUserId = typeof labelChainOptions.configurable?.user_id === "string" ? labelChainOptions.configurable.user_id : void 0;
 		const labelSessionId = typeof labelChainOptions.configurable?.thread_id === "string" ? labelChainOptions.configurable.thread_id : void 0;
 		const labelIndex = labelSeq - 1;
 		const labelParentMessageId = labelChainOptions.configurable?.requestBody?.parentMessageId;
-		/** An omitted `agentId` is attributable only when exactly one context
-		*  exists. Multi-agent callers remain unattributed instead of being
-		*  incorrectly assigned to the graph's default agent. */
 		const labelAgentId = agentId ?? (this.Graph?.agentContexts.size === 1 ? this.Graph.defaultAgentId : void 0);
 		const labelAgentName = labelAgentId == null ? void 0 : labelContext?.name;
 		const labelMetadata = {
@@ -1332,19 +841,8 @@ var Run = class Run {
 		const labelTags = ["librechat", "activity-label"];
 		const labelLangfuseConfig = resolveLangfuseConfig(this.langfuse, labelContext?.langfuse);
 		initializeLangfuseTracing(labelLangfuseConfig);
-		/** Seed policy, threading two constraints:
-		*  1. `runWithLangfuseRuntimeContext` SPREADS the surrounding context, so
-		*     an absent seed INHERITS the parent run's and collapses every label
-		*     into that trace. When a parent seed is active we must override it
-		*     with a per-label one.
-		*  2. Without deterministic tracing there is no parent seed, and forcing
-		*     one here would make label trace ids deterministic when neither
-		*     `processStream` nor `generateTitle` are — so leave it unset.
-		*  Seeded when determinism is opted into OR a parent seed is live;
-		*  otherwise unseeded, matching the other generation paths. */
 		const inheritedTraceSeed = getTraceIdSeed();
 		const labelTraceSeed = labelLangfuseConfig?.deterministicTraceId === true || inheritedTraceSeed != null ? traceSeed ?? `activity-label-${this.id}-${labelSeq}` : void 0;
-		/** Opaque per-execution component: see `titleScopeRunId`. */
 		const labelScopeRunId = `activity-label:${this.id}:${labelSeq}:${nanoid()}`;
 		const labelRuntimeScope = resolveLangfuseRuntimeScope({
 			runLangfuse: this.langfuse,
@@ -1352,13 +850,6 @@ var Run = class Run {
 			traceIdSeed: labelTraceSeed,
 			runId: labelScopeRunId
 		});
-		/** Handler only when a session id resolved from
-		*  `chainOptions.configurable.thread_id`: without it the label call has
-		*  no conversation identity, and tracing it would create an orphan
-		*  trace outside any session — worse than not tracing at all. */
-		/** Declared then conditionally assigned (title precedent): a ternary
-		*  around the object literal makes eslint's indent rule and prettier
-		*  disagree, and both gate CI. */
 		let labelLangfuseHandler;
 		if (labelSessionId != null) labelLangfuseHandler = createLangfuseHandler({
 			langfuse: labelLangfuseConfig,
@@ -1372,14 +863,7 @@ var Run = class Run {
 			traceName: labelRunName
 		});
 		if (labelLangfuseHandler != null) labelChainOptions.callbacks = appendCallbacks(labelChainOptions.callbacks, [labelLangfuseHandler]);
-		/** The label prompt becomes Langfuse generation input, so the resolved
-		*  tool-output redaction policy (global disable / redactedToolNames)
-		*  applies to it exactly as to structured tool observations. */
 		let redaction = hasToolOutputTracingConfig(this.langfuse, labelContext?.langfuse) ? resolveToolOutputTracingConfig(this.langfuse, labelContext?.langfuse) : void 0;
-		/** Multi-agent graph with no `agentId`: the caller did not say WHICH
-		*  agent ran this batch, so resolving from the default agent could trace
-		*  raw output that a stricter sibling's policy forbids. Fold every
-		*  agent's policy into the strictest one instead of guessing. */
 		const agentContexts = this.Graph?.agentContexts;
 		if (agentId == null && agentContexts != null && agentContexts.size > 1) for (const context of agentContexts.values()) {
 			if (!hasToolOutputTracingConfig(this.langfuse, context.langfuse)) continue;
@@ -1395,9 +879,6 @@ var Run = class Run {
 				redactionText: redaction.redactionText
 			};
 		}
-		/** An active redaction policy suppresses free-form reasoning/intent, so
-		*  a reasoning-only block has nothing describable left — skip the model
-		*  call rather than paying for a label built from the prompt alone. */
 		const freeFormSuppressed = redaction != null && (redaction.enabled === false || redaction.redactedToolNames.size > 0);
 		if (entries.length === 0 && freeFormSuppressed) return {};
 		const userPrompt = buildActivityLabelPrompt({
@@ -1415,9 +896,6 @@ var Run = class Run {
 				streaming: false
 			}
 		});
-		/** Distinct run id per label call: callback/tracing integrations key
-		*  in-flight runs by it, so reusing the parent run's id would collide
-		*  across successive (or concurrent) label batches. */
 		const labelRunId = `${this.id}-activity-${labelSeq}`;
 		const invokeConfig = Object.assign({}, labelChainOptions, {
 			run_id: labelRunId,
@@ -1442,10 +920,6 @@ var Run = class Run {
 			let text = "";
 			if (typeof content === "string") text = content;
 			else if (Array.isArray(content)) text = content.map((block) => typeof block === "string" ? block : block.text ?? "").join("");
-			/** Collapsed to one line at the source: a header renders as a single
-			*  row, and hosts feed committed labels back as continuity context —
-			*  so a multi-line result would carry its line breaks into every later
-			*  prompt in the run. */
 			return text.replace(/\s+/g, " ").trim().replace(/^["']|["']$/g, "");
 		};
 		try {
@@ -1453,10 +927,6 @@ var Run = class Run {
 			try {
 				response = await withLangfuseRuntimeScope(labelRuntimeScope, () => invokeLabel(invokeConfig));
 			} catch (error) {
-				/** Retry ONLY recognized callback/tracer failures (the EventStream
-				*  tracer class of errors the stripped-callbacks fallback exists
-				*  for). Aborts and provider failures rethrow — retrying those
-				*  doubles traffic/cost and can restart cancelled requests. */
 				const aborted = labelChainOptions.signal?.aborted === true || error?.name === "AbortError";
 				const callbackFailure = /callback|tracer|event.?stream/i.test(String(error?.stack ?? error?.message ?? ""));
 				if (aborted || !callbackFailure) throw error;
@@ -1471,12 +941,6 @@ var Run = class Run {
 			await disposeLangfuseHandler(labelLangfuseHandler);
 		}
 	}
-	/**
-	* Generates one parent summary for two or more logical activities. The
-	* summary model is traced as a dedicated activity-phase chain root in the
-	* conversation session, with the model callback recorded as its generation
-	* child. No session id means no phase trace, avoiding orphan observations.
-	*/
 	async generateActivityPhaseLabel({ provider, clientOptions, activities, totalActivityCount, assistantContext, closingTextPhase, prompt, charLimit = 600, chainOptions, traceSeed, sourceRunId, sourceTraceId, responseId, phaseIndex, status = "completed", agentIds }) {
 		if (activities.length < 2) return {};
 		const phaseSeq = ++this.activityPhaseLabelSeq;