@librechat/agents 3.3.13 → 3.4.1

package/dist/types/hooks/types.d.ts

@@ -9,6 +9,7 @@ import type { InjectedMessage } from '@/types/tools';
  * `@librechat/agents` emission points.
  */
 export declare const HOOK_EVENTS: readonly ["RunStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "PreemptBoundary", "PermissionDenied", "SubagentStart", "SubagentStop", "Stop", "StopFailure", "PreCompact", "PostCompact"];
+export declare const TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY = "__librechat_tool_approval_execution_scope";
 export type HookEvent = (typeof HOOK_EVENTS)[number];
 /** Tool-gating decision; executeHooks folds with `deny > ask > allow` precedence. */
 export type ToolDecision = 'allow' | 'deny' | 'ask';
@@ -331,6 +332,17 @@ export interface PreToolUseHookOutput extends BaseHookOutput {
      */
     allowedDecisions?: ReadonlyArray<'approve' | 'reject' | 'edit' | 'respond'>;
 }
+/** Stable identity for replaying a consumed one-shot tool approval. */
+export interface ToolApprovalReplayKey {
+    executionScope: string;
+    agentId: string;
+    toolUseId: string;
+}
+/** Checkpoint-safe copy of a consumed one-shot approval contribution. */
+export interface ToolApprovalReplaySnapshot {
+    key: ToolApprovalReplayKey;
+    result: AggregatedHookResult;
+}
 export interface PostToolUseHookOutput extends BaseHookOutput {
     /**
      * Replacement tool output. Flows through the aggregated result so the

package/dist/types/index.d.ts

@@ -42,6 +42,9 @@ export { CustomOpenAIClient } from './llm/openai';
 export { ChatOpenRouter } from './llm/openrouter';
 export type { OpenRouterReasoning, OpenRouterReasoningEffort, ChatOpenRouterCallOptions, } from './llm/openrouter';
 export { getChatModelClass } from './llm/providers';
+export { CustomChatMistralAI } from './llm/mistral';
+export { smoothStream, resolveStreamDelay, DEFAULT_STREAM_DELAY, computeAdaptivePieceSize, } from './llm/stream/smoother';
+export type { SmoothItem, SmoothPiece } from './llm/stream/smoother';
 export { FakeChatModel, createFakeStreamingLLM } from './llm/fake';
 export { initializeModel } from './llm/init';
 export { attemptInvoke, tryFallbackProviders } from './llm/invoke';

package/dist/types/llm/google/index.d.ts

@@ -5,6 +5,7 @@ import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager
 import type { BaseMessage } from '@langchain/core/messages';
 import type { GoogleClientOptions, GoogleThinkingConfig } from '@/types';
 export declare class CustomChatGoogleGenerativeAI extends ChatGoogleGenerativeAI {
+    _lc_stream_delay: number;
     thinkingConfig?: GoogleThinkingConfig;
     includeServerSideToolInvocations?: boolean;
     /**
@@ -21,4 +22,5 @@ export declare class CustomChatGoogleGenerativeAI extends ChatGoogleGenerativeAI
     invocationParams(options?: this['ParsedCallOptions']): Omit<GenerateContentRequest, 'contents'>;
     _generate(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): Promise<import('@langchain/core/outputs').ChatResult>;
     _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
+    private _streamProviderChunks;
 }

package/dist/types/llm/mistral/index.d.ts

@@ -0,0 +1,11 @@
+import { ChatMistralAI } from '@langchain/mistralai';
+import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
+import type { ChatGenerationChunk } from '@langchain/core/outputs';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { MistralAIClientOptions } from '@/types';
+export declare class CustomChatMistralAI extends ChatMistralAI {
+    _lc_stream_delay: number;
+    static lc_name(): 'LibreChatMistralAI';
+    constructor(fields?: MistralAIClientOptions);
+    _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
+}

package/dist/types/llm/openai/index.d.ts

@@ -10,6 +10,7 @@ import type { BindToolsInput } from '@langchain/core/language_models/chat_models
 import type { ChatResult } from '@langchain/core/outputs';
 import type { ChatXAIInput } from '@langchain/xai';
 import type * as t from '@langchain/openai';
+import type { SmoothItem } from '@/llm/stream/smoother';
 import type { HeaderValue, HeadersLike } from './types';
 import type { PromptCacheTtl } from '@/messages/cache';
 export declare function isHeaders(headers: unknown): headers is Headers;
@@ -44,6 +45,21 @@ export declare function shouldIncludeEncryptedReasoning(model: string, params: {
 export declare function getCacheWriteTokens(message: BaseMessage): number | undefined;
 export declare function attachCacheWriteUsage(message: BaseMessage): void;
 export declare function attachCacheWriteMetadata(response: OpenAIClient.Responses.Response): OpenAIClient.Responses.Response;
+/**
+ * Classifies a generation chunk for the smoothing engine:
+ * - splittable: plain visible text (string content equal to `chunk.text`, no
+ *   logprobs / finish_reason) — sliced adaptively at the pacing cadence.
+ *   ANY logprobs value blocks splitting here (this family only attaches
+ *   logprobs on request; the DeepSeek suite pins chunks with them staying
+ *   intact) — deliberately stricter than `stream/chunkAdapters.ts`, where
+ *   google-common's always-present empty logprobs must not block.
+ * - atomic: text- or reasoning-bearing chunks whose metadata cannot survive
+ *   slicing — paced as one piece, never split (legacy parity: these were
+ *   emitted whole but still paced).
+ * - passthrough: tool-call deltas, usage-only, finish_reason and other
+ *   metadata chunks — strict FIFO, zero delay.
+ */
+export declare function toSmoothItem(chunk: ChatGenerationChunk): SmoothItem<ChatGenerationChunk>;
 export declare function emitStreamChunkCallback(chunk: ChatGenerationChunk, runManager?: CallbackManagerForLLMRun): Promise<void>;
 export declare function _convertToOpenAITool(tool: BindToolsInput, fields?: {
     /**
@@ -61,7 +77,7 @@ export declare class CustomAzureOpenAIClient extends AzureOpenAIClient {
     fetchWithTimeout(url: RequestInfo, init: RequestInit | undefined, ms: number, controller: AbortController): Promise<Response>;
 }
 export declare class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptions> {
-    _lc_stream_delay?: number;
+    _lc_stream_delay: number;
     constructor(fields?: LibreChatOpenAIFields & t.OpenAIChatInput['modelKwargs']);
     get exposedClient(): CustomOpenAIClient;
     static lc_name(): string;
@@ -81,7 +97,7 @@ export declare class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptio
     protected _streamRawResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
 }
 export declare class AzureChatOpenAI extends OriginalAzureChatOpenAI {
-    _lc_stream_delay?: number;
+    _lc_stream_delay: number;
     constructor(fields?: LibreChatAzureOpenAIFields);
     get exposedClient(): CustomOpenAIClient;
     static lc_name(): 'LibreChatAzureOpenAI';
@@ -95,7 +111,7 @@ export declare class AzureChatOpenAI extends OriginalAzureChatOpenAI {
     _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
 }
 export declare class ChatDeepSeek extends OriginalChatDeepSeek {
-    _lc_stream_delay?: number;
+    _lc_stream_delay: number;
     constructor(fields?: ConstructorParameters<typeof OriginalChatDeepSeek>[0] & {
         _lc_stream_delay?: number;
     });
@@ -139,7 +155,7 @@ export declare class ChatMoonshot extends ChatOpenAI {
     static lc_name(): 'LibreChatMoonshot';
 }
 export declare class ChatXAI extends OriginalChatXAI {
-    _lc_stream_delay?: number;
+    _lc_stream_delay: number;
     constructor(fields?: Partial<ChatXAIInput> & {
         configuration?: {
             baseURL?: string;

package/dist/types/llm/openrouter/index.d.ts

@@ -26,7 +26,10 @@ export interface ChatOpenRouterCallOptions extends Omit<ChatOpenAICallOptions, '
      */
     promptCacheTtl?: PromptCacheTtl;
 }
-export type ChatOpenRouterInput = Partial<ChatOpenRouterCallOptions & OpenAIChatInput>;
+export type ChatOpenRouterInput = Partial<ChatOpenRouterCallOptions & OpenAIChatInput> & {
+    /** Minimum delay in ms between visible streamed deltas (default 25; 0 disables). */
+    _lc_stream_delay?: number;
+};
 /** invocationParams return type extended with OpenRouter reasoning */
 export type OpenRouterInvocationParams = Omit<OpenAIClient.Chat.ChatCompletionCreateParams, 'messages'> & {
     reasoning?: OpenRouterReasoning;

package/dist/types/llm/stream/chunkAdapters.d.ts

@@ -0,0 +1,48 @@
+import { AIMessageChunk } from '@langchain/core/messages';
+import { ChatGenerationChunk } from '@langchain/core/outputs';
+import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
+import type { SmoothItem, SmoothPiece } from '@/llm/stream/smoother';
+/**
+ * Rebuilds a generation chunk carrying one piece of a split plain-text chunk.
+ * Unsplit pieces return the original chunk untouched, so disabled smoothing is
+ * byte-identical to no smoothing. Usage metadata, additional kwargs and
+ * response metadata survive only on the first piece: the aggregator merges
+ * dicts by concatenating string fields, so replicating them across pieces
+ * would duplicate reasoning text and scalar metadata once per piece.
+ */
+export declare function cloneGenerationChunkPiece(chunk: ChatGenerationChunk, piece: SmoothPiece): ChatGenerationChunk;
+/**
+ * Chunks that pair visible text with reasoning payloads in
+ * `additional_kwargs` (Gemini thought summaries, reasoning_content deltas,
+ * OpenRouter reasoning_details) must pace whole: split pieces would each
+ * carry the same kwargs and downstream merging — the aggregator's dict merge
+ * or OpenRouter's reasoning_details accumulation — duplicates them once per
+ * piece.
+ */
+/**
+ * Mixed text/tool-call deltas must never split: cloned pieces would each
+ * carry the same tool_call_chunks and downstream accumulation would corrupt
+ * the assembled tool arguments.
+ */
+export declare function hasToolCallChunks(message: AIMessageChunk): boolean;
+export declare function hasReasoningKwargs(message: AIMessageChunk): boolean;
+/**
+ * Extracts the visible reasoning text a kwargs-borne delta contributes, so
+ * reasoning-only chunks (Gemini thoughts, DeepSeek reasoning_content,
+ * OpenAI reasoning summaries, OpenRouter reasoning_details) pace atomically
+ * at the cadence instead of passing through unsmoothed.
+ */
+export declare function getReasoningKwargsText(message: AIMessageChunk): string;
+export declare function toGenerationSmoothItem(chunk: ChatGenerationChunk, getAtomicText?: (message: AIMessageChunk) => string): SmoothItem<ChatGenerationChunk>;
+/**
+ * Wraps a provider's raw chunk stream with adaptive smoothing and per-piece
+ * `handleLLMNewToken` dispatch. The raw stream must NOT dispatch runManager
+ * callbacks itself — callback-echo consumers would otherwise observe the
+ * unsmoothed deltas.
+ */
+export declare function smoothGenerationChunks({ chunks, delayMs, signal, runManager, }: {
+    chunks: AsyncGenerator<ChatGenerationChunk>;
+    delayMs: number;
+    signal?: AbortSignal;
+    runManager?: CallbackManagerForLLMRun;
+}): AsyncGenerator<ChatGenerationChunk>;

package/dist/types/llm/stream/smoother.d.ts

@@ -0,0 +1,95 @@
+export declare const DEFAULT_STREAM_DELAY = 25;
+export declare const SMOOTH_TARGET_LATENCY_MS = 250;
+export declare const MAX_STREAM_QUEUE_CHUNKS = 256;
+export declare const MAX_STREAM_QUEUE_TEXT_CHARS = 8192;
+export declare const MAX_SMOOTH_ITEM_SEGMENT_CHARS = 4096;
+export declare const STREAM_CHUNK_MIN_SIZE = 4;
+export declare const STREAM_BOUNDARIES: ReadonlySet<string>;
+export declare const STREAM_ABORT_MESSAGE = "AbortError: User aborted the request.";
+export declare const STREAM_PRODUCER_FAILURE = "Stream producer failed.";
+/**
+ * How long generator teardown waits for the background producer to observe a
+ * consumer close before abandoning it. Well-behaved streams settle in
+ * microseconds (the next enqueue throws); a stalled provider that ignores
+ * aborts otherwise blocks teardown — and abort propagation — indefinitely.
+ * An abandoned producer still self-terminates on its next enqueue attempt.
+ */
+export declare const PRODUCER_CLOSE_GRACE_MS = 1000;
+/**
+ * Resolves a configured stream delay to its effective value (default 25ms;
+ * 0 disables smoothing). Non-finite inputs (NaN from a malformed config
+ * value, ±Infinity) normalize to the default rather than poisoning piece
+ * arithmetic downstream.
+ */
+export declare function resolveStreamDelay(delay?: number): number;
+export declare function isSignalAborted(signal?: AbortSignal): boolean;
+/**
+ * How far past the target size the word-boundary search may extend before
+ * hard-cutting. Natural language hits a boundary within a few characters;
+ * boundary-free runs (base64, minified data, long identifiers) must not
+ * stretch a piece — or an admission segment — arbitrarily far past its
+ * budget.
+ */
+export declare const STREAM_BOUNDARY_LOOKAHEAD_CHARS = 64;
+export declare function findStreamChunkBoundary(text: string, minSize: number): number;
+/**
+ * Backlog-proportional piece sizing: emit enough per tick that the current
+ * backlog drains in ~`targetLatencyMs`, so render lag stays pinned near the
+ * target regardless of how fast the provider streams. Token-sized arrivals
+ * never exceed the minimum piece, matching the legacy fixed-size splitter.
+ */
+export declare function computeAdaptivePieceSize(bufferedTextLength: number, tickMs: number, targetLatencyMs?: number): number;
+/**
+ * A cadence, not an additive sleep: time the consumer already spent since the
+ * last visible emission counts against the target delay, so slow downstream
+ * handlers never compound latency.
+ */
+export declare function getCadencedStreamDelay({ targetDelay, lastVisibleTextAt, now, }: {
+    targetDelay: number;
+    lastVisibleTextAt?: number;
+    now: number;
+}): number;
+/** Abort-aware sleep that resolves (never rejects) on abort; callers re-check the signal. */
+export declare function waitForStreamDelay(delay: number, signal?: AbortSignal): Promise<void>;
+export type SmoothPiece = {
+    text: string;
+    isFirst: boolean;
+    isLast: boolean;
+};
+/**
+ * One classified unit of provider stream output.
+ *
+ * - `smooth: true` — visible text, paced at the configured cadence and (unless
+ *   `atomic`) sliced adaptively at dequeue time.
+ * - `atomic: true` — paced as a single piece, never split (text-bearing chunks
+ *   whose metadata cannot survive slicing, e.g. logprobs / finish_reason).
+ * - `smooth: false` — passthrough: tool-call deltas, usage-only, id-only and
+ *   seal chunks. Zero delay, strict FIFO with the text around them.
+ *
+ * `emit` builds the provider-specific output for one piece; `isFirst` lets
+ * providers keep usage_metadata on only the first piece of a split.
+ */
+export type SmoothItem<TEmit> = {
+    text: string;
+    smooth: boolean;
+    atomic?: boolean;
+    emit: (piece: SmoothPiece) => TEmit;
+};
+/**
+ * Bounded producer/consumer smoothing engine.
+ *
+ * The producer drains `source` eagerly into a bounded queue (the buffer is the
+ * backlog measurement adaptive sizing needs); at capacity it parks, applying
+ * backpressure to the underlying stream. The consumer emits paced pieces,
+ * decrementing the text budget and waking the producer *before* each cadenced
+ * sleep so the provider stream keeps being read during pacing.
+ *
+ * `delayMs <= 0` disables smoothing entirely: every item passes through FIFO,
+ * unsplit and undelayed.
+ */
+export declare function smoothStream<TEmit>({ source, delayMs, signal, abortUpstream, }: {
+    source: AsyncIterable<SmoothItem<TEmit>>;
+    delayMs: number;
+    signal?: AbortSignal;
+    abortUpstream?: () => void;
+}): AsyncGenerator<TEmit>;

package/dist/types/llm/vertexai/index.d.ts

@@ -340,6 +340,7 @@ export declare function fixThoughtSignatures(contents: GeminiContent[], input: B
  */
 export declare class ChatVertexAI extends ChatGoogle {
     lc_namespace: string[];
+    _lc_stream_delay: number;
     dynamicThinkingBudget: boolean;
     thinkingConfig?: GoogleThinkingConfig;
     static lc_name(): 'LibreChatVertexAI';
@@ -347,5 +348,6 @@ export declare class ChatVertexAI extends ChatGoogle {
     constructor(fields?: VertexAIClientOptions);
     invocationParams(options?: this['ParsedCallOptions'] | undefined): GoogleAIModelRequestParams;
     _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
+    private _streamRepairedChunks;
     buildConnection(fields: VertexAIClientOptions | undefined, client: GoogleAbstractedClient): void;
 }

package/dist/types/run.d.ts

@@ -1,5 +1,6 @@
+import { BaseMessage } from '@langchain/core/messages';
 import { Command } from '@langchain/langgraph';
-import type { MessageContentComplex, BaseMessage } from '@langchain/core/messages';
+import type { MessageContentComplex } from '@langchain/core/messages';
 import type * as t from '@/types';
 import { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
 import { StandardGraph } from '@/graphs/Graph';
@@ -103,6 +104,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     private runPreStreamHooks;
     static create<T extends t.BaseGraphState>(config: t.RunConfig): Promise<Run<T>>;
     getRunMessages(): BaseMessage[] | undefined;
+    getChildCheckpointThreadIds(): string[];
     /**
      * 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
@@ -220,6 +222,7 @@ export declare class Run<_T extends t.BaseGraphState> {
      */
     resume<TResume = t.ToolApprovalDecision[] | t.ToolApprovalDecisionMap>(resumeValue: TResume, callerConfig: t.RunStreamConfig, streamOptions?: t.EventStreamOptions, commandOptions?: Pick<ConstructorParameters<typeof Command>[0], 'update' | 'goto'>): Promise<MessageContentComplex[] | undefined>;
     private resolveInterruptResumeConfig;
+    private restoreInterruptFromCheckpoint;
     private createSystemCallback;
     getCallbacks(clientCallbacks: t.ClientCallbacks): t.SystemCallbacks;
     generateTitle({ provider, inputText, contentParts, titlePrompt, clientOptions, chainOptions, skipLanguage, titleMethod, titlePromptTemplate, }: t.RunTitleOptions): Promise<{

package/dist/types/session/AgentSession.d.ts

@@ -16,6 +16,7 @@ export declare class AgentSession {
     getLatestCheckpoint(options?: AgentSessionCheckpointLookupOptions): Promise<AgentSessionCheckpointReference | undefined>;
     private hasCheckpointState;
     private recordCheckpoint;
+    private recordChildCheckpointThreads;
     private getCheckpointThreadIds;
     private resetCheckpointThreads;
     private runInternal;

package/dist/types/tools/ToolNode.d.ts

@@ -3,6 +3,7 @@ import { END, Command, MessagesAnnotation } from '@langchain/langgraph';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { ToolOutputResolveView, ResolvedArgsByCallId } from '@/tools/toolOutputReferences';
+import type { SubagentToolNodeResumeState } from '@/tools/subagent/SubagentReplay';
 import type * as t from '@/types';
 import { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import { RunnableCallable } from '@/utils';
@@ -50,6 +51,8 @@ type RunToolBatchContext<T = unknown> = {
      * contract for hosts relying on it for policy / recovery guidance.
      */
     additionalContextsSink?: string[];
+    /** Stable identity of the assistant tool-call batch across HITL replay. */
+    replayBatchKey?: string;
     /**
      * Graph state the ToolNode was invoked with, threaded from `run()`
      * so `tool.invoke` can forward it as langgraph 1.4's `runtime.state`
@@ -113,6 +116,10 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * the Run ends.
      */
     private directPathTurns;
+    /** Terminal results from interrupting siblings that must survive a
+     * LangGraph replay of the containing ToolNode. Includes the sidecar data
+     * the fresh batch needs for hook-context injection and completion events. */
+    private settledInterruptingResults;
     /** Tool registry for filtering (lazy computation of programmatic maps) */
     private toolRegistry?;
     /** Cached programmatic tools (computed once on first PTC call) */
@@ -240,12 +247,11 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private shouldHandleUnknownHandoffLocally;
     private getUnknownToolErrorMessage;
     /**
-     * Flush the per-Run direct-path turn cache. Called by the Graph at
-     * end-of-Run via `clearHeavyState`. The map intentionally survives
-     * `run()` re-entry so an interrupt + resume reuses the original
-     * slot (Codex P2 #30), but it would otherwise grow linearly with
-     * tool calls and could collide across Runs if a provider reused
-     * call IDs (Codex P2 #33). Hosts can also call this directly if
+     * Flush per-Run direct replay state. Called by the Graph at end-of-Run via
+     * `clearHeavyState`. The state intentionally survives `run()` re-entry so
+     * interrupt + resume keeps both original turn slots and terminal sibling
+     * outputs, but it would otherwise grow linearly and could collide across
+     * Runs if a provider reused call IDs. Hosts can also call this directly if
      * they reuse a ToolNode across batches outside of a Graph.
      */
     clearDirectPathTurns(): void;
@@ -259,6 +265,8 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * @returns A ReadonlyMap where keys are tool names and values are their usage counts.
      */
     getToolUsageCounts(): ReadonlyMap<string, number>;
+    createSubagentResumeState(): SubagentToolNodeResumeState;
+    restoreSubagentResumeState(state: SubagentToolNodeResumeState): void;
     private recordToolUsageTurn;
     private recordEventToolPlanningTurn;
     /**
@@ -296,9 +304,9 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      *       `blockDirectCall`, `respond` returns the host-supplied
      *       `responseText` as a synthetic success ToolMessage,
      *       `edit` re-runs with edited args. LangGraph re-enters
-     *       ToolNode.run from the start on resume; the hook fires
-     *       again and the resume value distinguishes "first ask" from
-     *       "second pass with decision".
+     *       ToolNode.run from the start on resume. Reusable hooks fire
+     *       again; a consumed one-shot hook replays its pending approval
+     *       result. In both cases `interrupt()` consumes the resume value.
      *     • When HITL is off: collapses to a fail-closed deny (matches
      *       the rest of the SDK's HITL-disabled default). One-time
      *       warning logged so hosts notice the gap.
@@ -465,16 +473,16 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * call throws a `GraphInterrupt`, the `await` below rejects and unwinds the
      * whole ToolNode *before* any non-interrupting sibling has started — so a
      * sibling with real side effects (send_email, billing) never executes on
-     * the first pass. On the resume pass LangGraph re-runs the batch from the
-     * top; the interrupting tool resolves with the host's answer instead of
-     * throwing, and the siblings execute for the FIRST time, exactly once.
+     * the first pass. Terminal interrupting siblings are cached by call id, so
+     * LangGraph replay reuses their complete lifecycle output instead of
+     * repeating model calls, hooks, or side effects.
      *
      * Without this ordering, a flat `Promise.all` starts every sibling
      * concurrently, so a non-idempotent sibling can complete its side effect
      * before the interrupt unwinds and then run a SECOND time on resume — the
-     * duplicate side effect this method exists to prevent. Interrupting tools
-     * are expected to be side-effect-free (they only suspend), so running them
-     * as a group and re-running them on resume is harmless.
+     * duplicate side effect this method exists to prevent. A tool that actually
+     * suspends re-enters until it reaches a terminal result; siblings that
+     * already settled do not re-enter.
      *
      * `batchIndices[i]` is `directCalls[i]`'s position within the parent
      * ToolNode batch (used for `{{tool<i>turn<n>}}` registration); it is

package/dist/types/tools/subagent/SubagentExecutor.d.ts

@@ -1,5 +1,8 @@
-import type { BaseMessage } from '@langchain/core/messages';
-import type { AgentInputs, StandardGraphInput, ResolvedSubagentConfig, SubagentConfig, SubagentUsageSink, TokenCounter } from '@/types';
+import { BaseMessage } from '@langchain/core/messages';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type { AgentInputs, HumanInTheLoopConfig, StandardGraphInput, ResolvedSubagentConfig, SubagentConfig, SubagentUsageSink, TokenCounter } from '@/types';
+import type { SubagentResumeManifest, SettledSubagentToolOutput } from './SubagentReplay';
 import type { HookRegistry } from '@/hooks';
 import type { AgentContext } from '@/agents/AgentContext';
 import type { StandardGraph } from '@/graphs/Graph';
@@ -34,11 +37,12 @@ export type SubagentExecuteParams = {
      *
      * Inheritance details (verified empirically against LangGraph):
      *   - host-set keys propagate as-is into the child's tool dispatches;
-     *   - `thread_id` propagates (with `childRunId` as a fallback when
-     *     parent did not supply one) — matches the "subagent is part of
-     *     the same conversation" mental model and aligns with the
-     *     `sessionId: this.parentRunId` convention this executor already
-     *     uses for `SubagentStart` / `SubagentStop` hooks;
+     *   - with nested HITL enabled, `thread_id` is replaced with a stable
+     *     child checkpoint id derived from the parent's durable thread id,
+     *     checkpoint fork, parent agent id, and spawning tool call id so parent
+     *     and child checkpoints cannot collide, sibling parent forks stay
+     *     isolated, and reconstruction returns to the same child checkpoint;
+     *     parent-scoped hook lookup remains keyed by the inherited `run_id`;
      *   - `parent_run_id` propagates when the host put it on parent's
      *     configurable;
      *   - `run_id` is *overwritten by the LangGraph runtime* at child
@@ -95,6 +99,11 @@ export type SubagentExecutorOptions = {
      * revert to the defaults.
      */
     streamLimits?: StandardGraphInput['streamLimits'];
+    humanInTheLoop?: HumanInTheLoopConfig;
+    /** Shared durable saver used to recover outer tool lifecycle results before
+     * parent hooks re-enter after a process rebuild. Narrowed structurally at
+     * construction because graph compile options also permit framework flags. */
+    checkpointer?: unknown;
     /** Remaining nesting budget. 0 or negative blocks execution. */
     maxDepth?: number;
     /**
@@ -143,9 +152,18 @@ export declare class SubagentExecutor {
     private readonly langfuse?;
     private readonly tokenCounter?;
     private readonly streamLimits?;
+    private readonly humanInTheLoop?;
+    private readonly checkpointer?;
     private readonly maxDepth;
     private readonly createChildGraph;
     private readonly usageSink?;
+    private readonly checkpointThreadIds;
+    private readonly startedChildRuns;
+    private readonly completedChildRuns;
+    private readonly completedChildResults;
+    private readonly childExecutionIdentities;
+    private readonly activeChildRuns;
+    private replayCheckpointWorkflow?;
     private readonly resolveParentHandlerRegistry?;
     constructor(options: SubagentExecutorOptions);
     /** The breaker controller current for this execution — read per spawn
@@ -157,6 +175,27 @@ export declare class SubagentExecutor {
     private composeChildSignal;
     /** Snapshot of the parent's registry at the moment a subagent is dispatched. */
     private getParentHandlerRegistry;
+    /**
+     * Keeps the original child thread as an immutable resume source once a
+     * different parent Run reconstructs it. Each rebuilt parent gets a private
+     * checkpoint fork, while the persisted child run ID remains stable for
+     * activity and usage correlation across the interrupt boundary.
+     */
+    private resolveChildExecutionIdentity;
+    /** Captures one exact checkpoint head per namespace for a child thread. */
+    private getLatestCheckpointSnapshot;
+    /** Copies exact checkpoint lineages, including pending task writes. */
+    private forkCheckpointSnapshot;
+    private createResumeManifest;
+    getResumeManifest(parentToolCallIds?: ReadonlySet<string>): Promise<SubagentResumeManifest | undefined>;
+    getChildCheckpointThreadIds(): string[];
+    resetCheckpointThreadIds(): void;
+    private getGraphChildCheckpointThreadIds;
+    private clearChildGraph;
+    clearHeavyState(): void;
+    getSettledToolOutput(call: ToolCall, config: RunnableConfig): Promise<SettledSubagentToolOutput | undefined>;
+    persistSettledToolOutput(call: ToolCall, config: RunnableConfig, settled: SettledSubagentToolOutput): Promise<void>;
+    private persistChildCheckpointMarker;
     execute(params: SubagentExecuteParams): Promise<SubagentExecuteResult>;
     /**
      * Emits a single {@link GraphEvents.ON_SUBAGENT_UPDATE} envelope through the
@@ -192,6 +231,9 @@ export declare function summarizeEvent(eventName: string, data: unknown): string
  * pure tool_use (e.g. the subagent hit `maxTurns` mid-tool-call), the walk
  * continues to earlier AIMessages so partial progress is salvaged — this
  * matches Claude Code's behavior in `agentToolUtils.finalizeAgentTool`.
+ * Consecutive streamed text-delta blocks with the same provider index are
+ * coalesced without adding whitespace. Annotation-only text blocks are
+ * ignored; complete text blocks and distinct delta indexes remain separated.
  * Returns "Task completed" only when no AIMessage in the history contains
  * any text.
  */

package/dist/types/tools/subagent/SubagentReplay.d.ts

@@ -0,0 +1,81 @@
+import type { ToolCall, ToolMessage } from '@langchain/core/messages/tool';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ToolOutputReferenceState } from '@/tools/toolOutputReferences';
+import type { ToolApprovalReplaySnapshot } from '@/hooks';
+import type { ToolSessionContext } from '@/types';
+export declare const SUBAGENT_RESUME_MANIFEST_CONFIG_KEY = "__librechat_subagent_resume_manifest";
+export declare const SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY = "__librechat_subagent_resume_attempt";
+export declare const SUBAGENT_PARENT_BATCH_CONFIG_KEY = "__librechat_subagent_parent_batch";
+export interface SubagentCheckpointReference {
+    threadId: string;
+    checkpointId: string;
+    checkpointNs: string;
+}
+export interface SubagentToolCallStepReference {
+    toolCallId: string;
+    stepId: string;
+}
+export interface SubagentToolSessionReference {
+    toolName: string;
+    context: ToolSessionContext;
+}
+export interface SubagentToolNodeResumeState {
+    stateKey: string;
+    toolUsageCounts: Array<{
+        toolName: string;
+        count: number;
+    }>;
+    directPathTurns: Array<{
+        toolCallId: string;
+        turn: number;
+    }>;
+}
+export interface SubagentEagerToolUsageState {
+    agentId: string;
+    toolUsageCounts: Array<{
+        toolName: string;
+        count: number;
+    }>;
+}
+export interface SubagentGraphResumeState {
+    toolCallSteps: SubagentToolCallStepReference[];
+    toolSessions: SubagentToolSessionReference[];
+    toolNodes: SubagentToolNodeResumeState[];
+    eagerToolUsage: SubagentEagerToolUsageState[];
+    eagerToolSuppressions: string[];
+    toolOutputReferences?: ToolOutputReferenceState;
+}
+/** Private checkpoint payload linking a parent pause to an exact child state. */
+export interface SubagentResumeExecution {
+    parentToolCallId: string;
+    childRunId: string;
+    approvalExecutionScope: string;
+    checkpoints: SubagentCheckpointReference[];
+    graphState: SubagentGraphResumeState;
+    approvalReplays: ToolApprovalReplaySnapshot[];
+    descendant?: SubagentResumeManifest;
+}
+/** Private checkpoint payload linking a parent pause to every child state. */
+export interface SubagentResumeManifest {
+    version: 1;
+    executions: SubagentResumeExecution[];
+}
+export declare function getSubagentResumeManifest(payload: unknown): SubagentResumeManifest | undefined;
+export declare function requireValidSubagentResumeManifest(payload: unknown): SubagentResumeManifest | undefined;
+export declare function attachSubagentResumeManifest(payload: unknown, manifest: SubagentResumeManifest): object;
+export declare function stripSubagentResumeManifest(payload: unknown): unknown;
+export declare const SUBAGENT_REPLAY_CONTROLLER: unique symbol;
+export type SettledSubagentToolOutput = {
+    output: ToolMessage;
+    additionalContexts: string[];
+    resolvedArgs?: Record<string, unknown>;
+    referenceContent?: string;
+};
+export interface SubagentReplayController {
+    getResumeManifest?(parentToolCallIds?: ReadonlySet<string>): Promise<SubagentResumeManifest | undefined>;
+    getSettledOutput(call: ToolCall, config: RunnableConfig): Promise<SettledSubagentToolOutput | undefined>;
+    persistSettledOutput(call: ToolCall, config: RunnableConfig, settled: SettledSubagentToolOutput): Promise<void>;
+}
+export type ReplayableSubagentTool = {
+    [SUBAGENT_REPLAY_CONTROLLER]?: SubagentReplayController;
+};

package/dist/types/tools/toolOutputReferences.d.ts

@@ -53,6 +53,14 @@ export type ToolOutputReferenceRegistryOptions = {
      */
     maxActiveRuns?: number;
 };
+export interface ToolOutputReferenceState {
+    entries: Array<{
+        key: string;
+        value: string;
+    }>;
+    turnCounter: number;
+    warnedNonStringTools: string[];
+}
 /**
  * Result of resolving placeholders in tool args.
  */
@@ -189,6 +197,10 @@ export declare class ToolOutputReferenceRegistry {
      * completed.
      */
     snapshot(runId: string | undefined): ToolOutputResolveView;
+    /** Captures the checkpoint-safe state needed to resume one run bucket. */
+    snapshotState(runId: string | undefined): ToolOutputReferenceState;
+    /** Restores a checkpointed run bucket under the current resume scope. */
+    restoreState(runId: string | undefined, state: ToolOutputReferenceState): void;
     private resolveAgainst;
     private transform;
     private replaceInString;