@librechat/agents 3.3.13 → 3.4.1

package/dist/types/types/graph.d.ts

@@ -524,11 +524,11 @@ export interface AgentInputs {
      * raise a LangGraph `interrupt()` (e.g. a tool built on `askUserQuestion()`) —
      * the host-side event handler runs outside the graph task, where `interrupt()`
      * throws. Do NOT also list these tools in `toolDefinitions` (they would be bound
-     * twice). NOT inherited by SELF-SPAWNED subagent children (their config is a
-     * shallow spread of the parent's inputs, and child graphs compile without a
-     * checkpointer, so an interrupt-capable tool could never pause there) —
-     * `buildChildInputs` scrubs the inherited copy; an EXPLICIT child config that
-     * lists its own `graphTools` keeps them.
+     * twice). NOT inherited by SELF-SPAWNED subagent children: `buildChildInputs`
+     * scrubs the shallow-spread parent copy so parent-scoped direct tools are not
+     * exposed to a child implicitly. An EXPLICIT child config that lists its own
+     * `graphTools` keeps them; with HITL enabled, those tools share the parent's
+     * checkpointer and may pause and resume inside the child graph.
      *
      * Deliberately `GenericTool[]`, not `GraphTools`: the wider union admits
      * schema-only shapes (OpenAI `BindToolsInput`, Google tool objects) that

package/dist/types/types/hitl.d.ts

@@ -97,6 +97,17 @@ export type ToolApprovalDecisionMap = Record<string, ToolApprovalDecision>;
  * below; this type alias is primarily an integration-layer contract.
  */
 export type HumanInterruptType = 'tool_approval' | 'ask_user_question';
+/** Identifies an interrupt that originated inside a checkpointed subagent. */
+export interface SubagentInterruptScope {
+    /** Child execution run id used by subagent update and usage events. */
+    run_id: string;
+    /** Child agent id that owns the interrupted tool call. */
+    agent_id: string;
+    /** Configured subagent type selected by the parent tool call. */
+    subagent_type: string;
+    /** Parent `subagent` tool call that launched this child. */
+    parent_tool_call_id?: string;
+}
 /**
  * Structured payload the SDK passes to `interrupt()` when one or more
  * pending tool calls require host approval. All `ask`-decision tool calls
@@ -110,6 +121,10 @@ export interface ToolApprovalInterruptPayload {
     type: 'tool_approval';
     action_requests: ToolApprovalRequest[];
     review_configs: ToolApprovalReviewConfig[];
+    /** Hook-registry session whose policy raised this interrupt. */
+    hook_session_id?: string;
+    /** Present when the approval request was bridged from a child graph. */
+    subagent?: SubagentInterruptScope;
 }
 /**
  * Pre-defined option the user can pick when answering an

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

@@ -28,7 +28,7 @@ export type AzureClientOptions = Partial<OpenAIChatInput> & Partial<AzureOpenAII
     deploymentName?: string;
 } & BaseChatModelParams & {
     configuration?: OAIClientOptions;
-} & ManagedRequestOptions;
+} & ManagedRequestOptions & StreamSmoothingOptions;
 /**
  * Controls whether Claude's reasoning content is returned in adaptive
  * thinking responses. Added for Claude Opus 4.7, which omits thinking by
@@ -58,8 +58,19 @@ export type ManagedRequestOptions = {
     promptCacheExplicit?: boolean;
     safety_identifier?: string;
 };
-export type OpenAIClientOptions = ChatOpenAIFields & ManagedRequestOptions;
-export type AnthropicClientOptions = Omit<AnthropicInput, 'thinking'> & {
+/**
+ * Adaptive stream-smoothing configuration shared by every provider client.
+ */
+export type StreamSmoothingOptions = {
+    /**
+     * Minimum delay in milliseconds between visible streamed content deltas.
+     * Defaults to 25; piece sizes adapt to the backlog so render lag stays
+     * bounded regardless of provider chunk size. Set 0 to disable smoothing.
+     */
+    _lc_stream_delay?: number;
+};
+export type OpenAIClientOptions = ChatOpenAIFields & ManagedRequestOptions & StreamSmoothingOptions;
+export type AnthropicClientOptions = Omit<AnthropicInput, 'thinking'> & StreamSmoothingOptions & {
     thinking?: ThinkingConfig;
     promptCache?: boolean;
     /**
@@ -69,12 +80,12 @@ export type AnthropicClientOptions = Omit<AnthropicInput, 'thinking'> & {
      */
     promptCacheTtl?: PromptCacheTtl;
 };
-export type MistralAIClientOptions = ChatMistralAIInput;
-export type VertexAIClientOptions = ChatVertexAIInput & {
+export type MistralAIClientOptions = ChatMistralAIInput & StreamSmoothingOptions;
+export type VertexAIClientOptions = ChatVertexAIInput & StreamSmoothingOptions & {
     includeThoughts?: boolean;
     thinkingConfig?: GoogleThinkingConfig;
 };
-export type BedrockAnthropicInput = ChatBedrockConverseInput & {
+export type BedrockAnthropicInput = ChatBedrockConverseInput & StreamSmoothingOptions & {
     additionalModelRequestFields?: ChatBedrockConverseInput['additionalModelRequestFields'] & AnthropicReasoning;
     promptCache?: boolean;
     /**
@@ -84,20 +95,16 @@ export type BedrockAnthropicInput = ChatBedrockConverseInput & {
      * server-side, so the default is safe to leave on.
      */
     promptCacheTtl?: PromptCacheTtl;
-    /**
-     * Minimum delay in milliseconds between visible streamed content deltas.
-     */
-    _lc_stream_delay?: number;
 };
 export type BedrockConverseClientOptions = BedrockAnthropicInput;
 export type BedrockAnthropicClientOptions = BedrockAnthropicInput;
-export type GoogleClientOptions = GoogleGenerativeAIChatInput & {
+export type GoogleClientOptions = GoogleGenerativeAIChatInput & StreamSmoothingOptions & {
     customHeaders?: RequestOptions['customHeaders'];
     thinkingConfig?: GoogleThinkingConfig;
     includeServerSideToolInvocations?: boolean;
 };
-export type DeepSeekClientOptions = Partial<ChatDeepSeekInput>;
-export type XAIClientOptions = ChatXAIInput;
+export type DeepSeekClientOptions = Partial<ChatDeepSeekInput> & StreamSmoothingOptions;
+export type XAIClientOptions = ChatXAIInput & StreamSmoothingOptions;
 export type ClientOptions = OpenAIClientOptions | AzureClientOptions | AnthropicClientOptions | MistralAIClientOptions | VertexAIClientOptions | BedrockConverseClientOptions | GoogleClientOptions | DeepSeekClientOptions | XAIClientOptions;
 export type SharedLLMConfig = {
     provider: Providers;
@@ -122,7 +129,7 @@ export type ProviderOptionsMap = {
     [Providers.ANTHROPIC]: AnthropicClientOptions;
     [Providers.MISTRALAI]: MistralAIClientOptions;
     [Providers.MISTRAL]: MistralAIClientOptions;
-    [Providers.OPENROUTER]: ChatOpenRouterCallOptions;
+    [Providers.OPENROUTER]: ChatOpenRouterCallOptions & StreamSmoothingOptions;
     [Providers.BEDROCK]: BedrockAnthropicClientOptions;
     [Providers.XAI]: XAIClientOptions;
     [Providers.MOONSHOT]: OpenAIClientOptions;

package/dist/types/utils/tokens.d.ts

@@ -1,5 +1,15 @@
 import type { BaseMessage } from '@langchain/core/messages';
 export type EncodingName = 'o200k_base' | 'claude';
+export type UnsafeTokenMeasurementReason = 'message_proxy' | 'content_proxy' | 'metadata_proxy' | 'metadata_accessor' | 'invalid_count';
+export declare class UnsafeTokenMeasurementError extends Error {
+    readonly type = "unsafe_token_measurement";
+    readonly reason: UnsafeTokenMeasurementReason;
+    readonly path: string;
+    constructor({ reason, path, }: {
+        reason: UnsafeTokenMeasurementReason;
+        path: string;
+    });
+}
 /** Safety margin for image and document token estimates (5% overestimate). */
 export declare const IMAGE_TOKEN_SAFETY_MARGIN = 1.05;
 /**

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@librechat/agents",
-  "version": "3.3.13",
+  "version": "3.4.1",
+  "reova": {
+    "enabled": true,
+    "endpoint": "https://telemetry.reo.dev/data"
+  },
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -248,7 +252,7 @@
     "nanoid": "^3.3.7",
     "okapibm25": "^1.4.1",
     "openai": "^6.46.0",
-    "reo-census": "^1.2.9",
+    "reova": "^0.4.1",
     "socks-proxy-agent": "^8.0.5",
     "uuid": "^11.1.1"
   },

package/src/graphs/Graph.ts

@@ -17,6 +17,13 @@ import type {
   MessageContent,
 } from '@langchain/core/messages';
 import type { ToolCall } from '@langchain/core/messages/tool';
+import type {
+  ReplayableSubagentTool,
+  SubagentGraphResumeState,
+  SubagentResumeManifest,
+  SubagentToolNodeResumeState,
+  SettledSubagentToolOutput,
+} from '@/tools/subagent/SubagentReplay';
 import type {
   ResolvedStreamLimits,
   RunBreakerScope,
@@ -60,14 +67,6 @@ import {
   appendPredecessorHandoffCue,
   removePredecessorHandoffCue,
 } from '@/messages';
-import {
-  attemptInvoke,
-  tryFallbackProviders,
-  getFallbackErrorContext,
-  getFallbackOverflowCandidates,
-  projectMessagesForProvider,
-  resolveServingModelId,
-} from '@/llm/invoke';
 import {
   resetIfNotEmpty,
   isAnthropicLike,
@@ -79,6 +78,21 @@ import {
   joinKeys,
   sleep,
 } from '@/utils';
+import {
+  attemptInvoke,
+  tryFallbackProviders,
+  getFallbackErrorContext,
+  getFallbackOverflowCandidates,
+  projectMessagesForProvider,
+  resolveServingModelId,
+} from '@/llm/invoke';
+import {
+  resolveStreamLimits,
+  StreamLimitExceededError,
+  sweepStaleStreamLimitEntries,
+  STREAM_LIMIT_EPOCH_KEY,
+  RUN_BREAKER_SCOPE_CONFIG_KEY,
+} from '@/llm/streamLimits';
 import {
   Constants,
   GraphNodeKeys,
@@ -122,17 +136,11 @@ import {
   findCallback,
   type CallbackEntry,
 } from '@/utils/callbacks';
-import {
-  resolveStreamLimits,
-  StreamLimitExceededError,
-  sweepStaleStreamLimitEntries,
-  STREAM_LIMIT_EPOCH_KEY,
-  RUN_BREAKER_SCOPE_CONFIG_KEY,
-} from '@/llm/streamLimits';
 import { partitionAndMarkOpenRouterToolCache } from '@/llm/openrouter/toolCache';
 import { ToolNode as CustomToolNode, toolsCondition } from '@/tools/ToolNode';
 import { shouldTraceToolNodeForLangfuse } from '@/langfuseToolOutputTracing';
 import { createLocalCodingToolBundle } from '@/tools/local/LocalCodingTools';
+import { SUBAGENT_REPLAY_CONTROLLER } from '@/tools/subagent/SubagentReplay';
 import { SubagentExecutor, resolveSubagentConfigs } from '@/tools/subagent';
 import { partitionAndMarkBedrockToolCache } from '@/llm/bedrock/toolCache';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
@@ -630,6 +638,10 @@ export abstract class Graph<
   _TNodeName extends string = string,
 > {
   abstract resetValues(keepContent?: boolean, checkpointScope?: string): void;
+  restoreCheckpointMessages(
+    _messages: BaseMessage[],
+    _pendingMessages?: BaseMessage[]
+  ): void {}
   abstract initializeTools({
     currentTools,
     currentToolMap,
@@ -848,11 +860,18 @@ export abstract class Graph<
     // Flush each compiled ToolNode's direct-path turn cache so it
     // doesn't leak across Runs (Codex P2 #33). The cache survives
     // `run()` re-entry by design (resume-stable), but end-of-Run
-    // is the right point to reset it.
+    // is the right point to reset it. Retain the registrations because
+    // the compiled workflow can be reused for later Runs; compilation
+    // will not register these instances again.
     for (const node of this._compiledToolNodes) {
       node.clearDirectPathTurns();
     }
-    this._compiledToolNodes.clear();
+    // Subagent executors are likewise compiled once and reused. Clear
+    // their per-Run state without dropping the registrations needed by
+    // subsequent cleanup cycles.
+    for (const executor of this._subagentExecutors) {
+      executor.clearHeavyState();
+    }
     this.sessions.clear();
   }
 
@@ -904,10 +923,137 @@ export abstract class Graph<
    */
   protected registerCompiledToolNode(node: {
     clearDirectPathTurns(): void;
+    createSubagentResumeState(): SubagentToolNodeResumeState;
+    restoreSubagentResumeState(state: SubagentToolNodeResumeState): void;
   }): void {
     this._compiledToolNodes.add(node);
   }
 
+  protected registerSubagentExecutor(executor: SubagentExecutor): void {
+    this._subagentExecutors.add(executor);
+  }
+
+  protected resetSubagentCheckpointThreadIds(): void {
+    for (const executor of this._subagentExecutors) {
+      executor.resetCheckpointThreadIds();
+    }
+  }
+
+  getChildCheckpointThreadIds(): string[] {
+    const threadIds = new Set<string>();
+    for (const executor of this._subagentExecutors) {
+      for (const threadId of executor.getChildCheckpointThreadIds()) {
+        threadIds.add(threadId);
+      }
+    }
+    return [...threadIds];
+  }
+
+  createSubagentResumeState(runId: string): SubagentGraphResumeState {
+    return {
+      toolCallSteps: [...this.toolCallStepIds].map(([toolCallId, stepId]) => ({
+        toolCallId,
+        stepId,
+      })),
+      toolSessions: [...this.sessions].map(([toolName, context]) => ({
+        toolName,
+        context: {
+          ...context,
+          ...(context.files == null
+            ? {}
+            : { files: context.files.map((file) => ({ ...file })) }),
+        },
+      })),
+      toolNodes: [...this._compiledToolNodes].map((node) =>
+        node.createSubagentResumeState()
+      ),
+      eagerToolUsage: [
+        {
+          agentId: '',
+          toolUsageCounts: [...this.eagerEventToolUsageCount].map(
+            ([toolName, count]) => ({ toolName, count })
+          ),
+        },
+        ...[...this.eagerEventToolUsageCountsByAgentId].map(
+          ([agentId, usageCounts]) => ({
+            agentId,
+            toolUsageCounts: [...usageCounts].map(([toolName, count]) => ({
+              toolName,
+              count,
+            })),
+          })
+        ),
+      ],
+      eagerToolSuppressions: [...this.eagerEventToolSuppressions],
+      ...(this._toolOutputRegistry == null
+        ? {}
+        : {
+          toolOutputReferences: this._toolOutputRegistry.snapshotState(runId),
+        }),
+    };
+  }
+
+  restoreSubagentResumeState(
+    state: SubagentGraphResumeState,
+    runId: string
+  ): void {
+    const toolNodesByKey = new Map(
+      [...this._compiledToolNodes].map((node) => {
+        const nodeState = node.createSubagentResumeState();
+        return [nodeState.stateKey, node] as const;
+      })
+    );
+    if (toolNodesByKey.size !== state.toolNodes.length) {
+      throw new Error('Cannot restore changed subagent tool topology.');
+    }
+    for (const nodeState of state.toolNodes) {
+      if (!toolNodesByKey.has(nodeState.stateKey)) {
+        throw new Error(
+          `Cannot restore subagent tool state for "${nodeState.stateKey}".`
+        );
+      }
+    }
+    const registry =
+      state.toolOutputReferences == null
+        ? undefined
+        : this.getOrCreateToolOutputRegistry();
+    if (state.toolOutputReferences != null && registry == null) {
+      throw new Error('Cannot restore disabled tool output references.');
+    }
+
+    this.toolCallStepIds.clear();
+    for (const { toolCallId, stepId } of state.toolCallSteps) {
+      this.toolCallStepIds.set(toolCallId, stepId);
+    }
+    this.sessions.clear();
+    for (const { toolName, context } of state.toolSessions) {
+      this.sessions.set(toolName, {
+        ...context,
+        ...(context.files == null
+          ? {}
+          : { files: context.files.map((file) => ({ ...file })) }),
+      });
+    }
+    for (const nodeState of state.toolNodes) {
+      const node = toolNodesByKey.get(nodeState.stateKey)!;
+      node.restoreSubagentResumeState(nodeState);
+    }
+    this.clearEagerEventToolUsageCounts();
+    for (const usageState of state.eagerToolUsage) {
+      const usageCounts = this.getEagerEventToolUsageCount(usageState.agentId);
+      for (const { toolName, count } of usageState.toolUsageCounts) {
+        usageCounts.set(toolName, count);
+      }
+    }
+    this.eagerEventToolSuppressions.clear();
+    for (const toolName of state.eagerToolSuppressions) {
+      this.eagerEventToolSuppressions.add(toolName);
+    }
+    if (state.toolOutputReferences != null && registry != null) {
+      registry.restoreState(runId, state.toolOutputReferences);
+    }
+  }
+
   /**
    * Returns the shared `ToolOutputReferenceRegistry` for this run,
    * constructing it on first access. Returns `undefined` when the
@@ -957,7 +1103,10 @@ export abstract class Graph<
    */
   private _compiledToolNodes: Set<{
     clearDirectPathTurns(): void;
+    createSubagentResumeState(): SubagentToolNodeResumeState;
+    restoreSubagentResumeState(state: SubagentToolNodeResumeState): void;
   }> = new Set();
+  private _subagentExecutors = new Set<SubagentExecutor>();
   public getOrCreateFileCheckpointer(): t.LocalFileCheckpointer | undefined {
     // Return the cached instance unconditionally if one exists. The
     // toolExecution check below decides whether to *create* a new
@@ -998,11 +1147,14 @@ export abstract class Graph<
 
 export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   overrideModel?: t.ChatModel;
+  private subagentModelOverride?: t.ChatModel;
   /** Optional compile options passed into workflow.compile() */
   compileOptions?: t.CompileOptions | undefined;
   /** Whether the workflow was actually compiled with a checkpointer. */
   hasCompiledCheckpointer: boolean = false;
   messages: BaseMessage[] = [];
+  /** Whether a rebuilt resume seeded the message baseline from its checkpoint. */
+  private hasRestoredCheckpointMessages = false;
   /** Cached run messages preserved before clearHeavyState() so getRunMessages() works after cleanup. */
   private cachedRunMessages?: BaseMessage[];
   /** Per-agent discovery snapshots preserved before contexts are reset on cleanup. */
@@ -1057,8 +1209,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
    * generation key + chunk index (see `resolveGenerationKey`). Per-run
    * accumulation state, cleared by both reset paths.
    */
-  streamedToolCallArgTallies: Map<string, StreamedToolCallArgTally> =
-    new Map();
+  streamedToolCallArgTallies: Map<string, StreamedToolCallArgTally> = new Map();
   /** Streamed chunk events per model generation, keyed by generation key. */
   streamDeltaEventCounts: Map<string, StreamDeltaEventTally> = new Map();
   /** Per-chunk-object, per-generation charge balances (lazily created; see
@@ -1212,7 +1363,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   /* Init */
 
   resetValues(keepContent?: boolean, checkpointScope?: string): void {
+    this.resetSubagentCheckpointThreadIds();
     this.messages = [];
+    this.hasRestoredCheckpointMessages = false;
     this.cachedRunMessages = undefined;
     this.cachedDiscoveredTools = undefined;
     this.config = resetIfNotEmpty(this.config, undefined);
@@ -1309,6 +1462,23 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       : undefined;
   }
 
+  /** Seeds the sidecar message view that checkpoint restoration bypasses. */
+  override restoreCheckpointMessages(
+    messages: BaseMessage[],
+    pendingMessages?: BaseMessage[]
+  ): void {
+    if (this.messages.length > 0) {
+      return;
+    }
+    this.messages =
+      pendingMessages == null
+        ? [...messages]
+        : messagesStateReducer(messages, pendingMessages);
+    this.startIndex = this.messages.length;
+    this.hasRestoredCheckpointMessages = true;
+    this.cachedRunMessages = undefined;
+  }
+
   override clearHeavyState(): void {
     this.cachedRunMessages = this.messages.slice(this.startIndex);
     this.cachedDiscoveredTools = new Map(
@@ -1320,6 +1490,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     super.clearHeavyState();
     this.messages = [];
     this.overrideModel = undefined;
+    this.subagentModelOverride = undefined;
     /** Stream-limit accounting (argument tallies, event counts, charge
      * credits) deliberately SURVIVES cleanup: this runs in `processStream`'s
      * finally, which an ordinary parallel-branch failure reaches while
@@ -1796,6 +1967,15 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       runLangfuse: this.langfuse,
       agentLangfuse: agentContext?.langfuse,
     });
+    const interruptingToolNames = new Set(this.interruptingToolNames ?? []);
+    if (
+      this.humanInTheLoop?.enabled === true &&
+      (agentContext?.subagentConfigs?.length ?? 0) > 0
+    ) {
+      interruptingToolNames.add(Constants.SUBAGENT);
+    }
+    const effectiveInterruptingToolNames =
+      interruptingToolNames.size > 0 ? interruptingToolNames : undefined;
 
     if (eventDrivenMode) {
       const schemaTools = createSchemaOnlyTools(toolDefinitions);
@@ -1847,11 +2027,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         eagerEventToolSuppressions: this.eagerEventToolSuppressions,
         toolExecution: this.toolExecution,
         directToolNames: directToolNames.size > 0 ? directToolNames : undefined,
-        interruptingToolNames:
-          this.interruptingToolNames != null &&
-          this.interruptingToolNames.length > 0
-            ? new Set(this.interruptingToolNames)
-            : undefined,
+        interruptingToolNames: effectiveInterruptingToolNames,
         maxContextTokens: agentContext?.maxContextTokens,
         maxToolResultChars: agentContext?.maxToolResultChars,
         toolOutputRegistry: this.getOrCreateToolOutputRegistry(),
@@ -1914,11 +2090,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       sessions: this.sessions,
       toolExecution: this.toolExecution,
       codeSessionToolNames: this.codeSessionToolNames,
-      interruptingToolNames:
-        this.interruptingToolNames != null &&
-        this.interruptingToolNames.length > 0
-          ? new Set(this.interruptingToolNames)
-          : undefined,
+      interruptingToolNames: effectiveInterruptingToolNames,
       hookRegistry: this.hookRegistry,
       humanInTheLoop: this.humanInTheLoop,
       maxContextTokens: agentContext?.maxContextTokens,
@@ -1944,6 +2116,11 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     });
   }
 
+  /** Explicitly overrides the model used by isolated descendant subagent graphs. */
+  setSubagentModelOverride(model: t.ChatModel): void {
+    this.subagentModelOverride = model;
+  }
+
   getUsageMetadata(
     finalMessage?: BaseMessage
   ): Partial<UsageMetadata> | undefined {
@@ -3370,7 +3547,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
          * would start new provider work after the run-wide breaker fired.
          * Rethrow the breaker's own stream-limit reason instead. */
         {
-          const trippedReason = this.resolveTrippedBreakerReason(attemptBreaker.signal);
+          const trippedReason = this.resolveTrippedBreakerReason(
+            attemptBreaker.signal
+          );
           if (trippedReason != null) {
             throw trippedReason;
           }
@@ -3617,7 +3796,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           }
           {
             /** Same sibling-abort translation guard as the primary catch. */
-            const trippedReason = this.resolveTrippedBreakerReason(attemptBreaker.signal);
+            const trippedReason = this.resolveTrippedBreakerReason(
+              attemptBreaker.signal
+            );
             if (trippedReason != null) {
               throw trippedReason;
             }
@@ -4054,19 +4235,25 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           tokenCounter: agentContext.tokenCounter,
           usageSink: this.subagentUsageSink,
           streamLimits: this.streamLimits,
+          humanInTheLoop: this.humanInTheLoop,
+          checkpointer: this.compileOptions?.checkpointer,
           maxDepth: effectiveSubagentDepth,
           createChildGraph: (input): StandardGraph => {
             const childGraph = new StandardGraph(input);
+            if (this.subagentModelOverride != null) {
+              childGraph.overrideModel = this.subagentModelOverride;
+              childGraph.setSubagentModelOverride(this.subagentModelOverride);
+            }
             const toolHandlerRegistry = createToolHandlerRegistry(
               getParentHandlerRegistry()
             );
             childGraph.hookRegistry = this.hookRegistry;
-            /**
-             * Do not propagate `humanInTheLoop` into the child graph yet:
-             * nested subagent interrupts need a stable child checkpoint and
-             * resume bridge. Child hooks still fire; `ask` decisions fail
-             * closed inside the subagent until that flow is implemented.
-             */
+            childGraph.humanInTheLoop = this.humanInTheLoop;
+            if (this.humanInTheLoop?.enabled === true) {
+              childGraph.compileOptions = {
+                checkpointer: this.compileOptions?.checkpointer,
+              };
+            }
             childGraph.toolOutputReferences = this.toolOutputReferences;
             childGraph.eagerEventToolExecution = this.eagerEventToolExecution;
             childGraph.codeSessionToolNames = this.codeSessionToolNames;
@@ -4088,6 +4275,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             return childGraph;
           },
         });
+        this.registerSubagentExecutor(executor);
 
         const subagentTool = tool(async (rawInput, config) => {
           const input = rawInput as {
@@ -4102,20 +4290,22 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           const subagentType =
             typeof input.subagent_type === 'string' ? input.subagent_type : '';
           const threadId = config.configurable?.thread_id as string | undefined;
-          /**
-           * When the tool is dispatched from an LLM's `tool_call`, LangChain
-           * threads the originating `ToolCall` onto the RunnableConfig as
-           * `config.toolCall` (see `ToolRunnableConfig` in
-           * `@langchain/core/tools` — internal but stable since ≥0.3.x).
-           * Surfacing its id lets hosts correlate `SubagentUpdateEvent`s
-           * back to the parent's `tool_call_id` deterministically — no
-           * temporal heuristics needed. If a future LangChain version
-           * changes the threading, the type-guarded read falls back to
-           * `undefined` and the correlation degrades gracefully.
-           */
-          const toolCall = (config as { toolCall?: { id?: string } }).toolCall;
-          const parentToolCallId =
-            typeof toolCall?.id === 'string' ? toolCall.id : undefined;
+          /** Surface the parent call id so child checkpoints, interrupts, and
+           * update events remain correlated across replay and resume. */
+          const toolRuntime = config as {
+            toolCallId?: string;
+            toolCall?: { id?: string };
+          };
+          const toolCall = toolRuntime.toolCall;
+          let parentToolCallId: string | undefined;
+          if (
+            typeof toolRuntime.toolCallId === 'string' &&
+            toolRuntime.toolCallId !== ''
+          ) {
+            parentToolCallId = toolRuntime.toolCallId;
+          } else if (typeof toolCall?.id === 'string' && toolCall.id !== '') {
+            parentToolCallId = toolCall.id;
+          }
           /** The parent tool batch's entry-captured scope (stamped by
            * ToolNode before PreToolUse hooks) — binds this child to the
            * run that dispatched it, not to whatever controller a reset
@@ -4141,6 +4331,21 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           });
           return result.content;
         }, buildSubagentToolParams(resolvedConfigs));
+        const replayableSubagentTool = subagentTool as typeof subagentTool &
+          ReplayableSubagentTool;
+        replayableSubagentTool[SUBAGENT_REPLAY_CONTROLLER] = {
+          getResumeManifest: (
+            parentToolCallIds
+          ): Promise<SubagentResumeManifest | undefined> =>
+            executor.getResumeManifest(parentToolCallIds),
+          getSettledOutput: (
+            call,
+            config
+          ): Promise<SettledSubagentToolOutput | undefined> =>
+            executor.getSettledToolOutput(call, config),
+          persistSettledOutput: (call, config, output): Promise<void> =>
+            executor.persistSettledToolOutput(call, config, output),
+        };
 
         if (!agentContext.graphTools) {
           agentContext.graphTools = [];
@@ -4388,7 +4593,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     const StateAnnotation = Annotation.Root({
       messages: Annotation<BaseMessage[]>({
         reducer: (a, b) => {
-          if (!this.messages.length) {
+          if (!this.messages.length && !this.hasRestoredCheckpointMessages) {
             this.startIndex = a.length + b.length;
           }
           const result = messagesStateReducer(a, b);