@librechat/agents 3.4.0 → 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/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

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;

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/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@librechat/agents",
-  "version": "3.4.0",
+  "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.10",
+    "reova": "^0.4.1",
     "socks-proxy-agent": "^8.0.5",
     "uuid": "^11.1.1"
   },