@librechat/agents 3.5.1 → 3.6.1

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

@@ -126,6 +126,8 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private programmaticCache?;
     /** Reference to Graph's sessions map for automatic session injection */
     private sessions?;
+    /** Partition within `sessions` owned by this agent's execution profile. */
+    private codeSessionKey;
     /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
     private eventDrivenMode;
     /** Opt-in stream-layer prestart config for event-driven tools. */
@@ -211,7 +213,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * other's in-flight state.
      */
     private anonBatchCounter;
-    constructor({ tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, eagerEventToolSuppressions, agentId, executingAgentId, directToolNames, interruptingToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, getBreakerSignal, getRunScope, }: t.ToolNodeConstructorParams);
+    constructor({ tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, codeSessionKey, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, eagerEventToolSuppressions, agentId, executingAgentId, directToolNames, interruptingToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, getBreakerSignal, getRunScope, restoreRunStepResumeState, createRunStepResumeState, }: t.ToolNodeConstructorParams);
     invoke(input: any, options?: Partial<RunnableConfig>): Promise<any>;
     /**
      * Returns the run-scoped tool output registry, or `undefined` when

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

@@ -0,0 +1,5 @@
+import type { RunStepResumeState } from '@/types';
+export declare function isRunStepResumeState(value: unknown): value is RunStepResumeState;
+export declare function attachRunStepResumeState(payload: unknown, state: RunStepResumeState): object;
+export declare function getRunStepResumeState(payload: unknown): RunStepResumeState | undefined;
+export declare function stripRunStepResumeState(payload: unknown): unknown;

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

@@ -207,6 +207,31 @@ export declare class SubagentExecutor {
     resetCheckpointThreadIds(): void;
     private getGraphChildCheckpointThreadIds;
     private clearChildGraph;
+    /**
+     * Terminal sweep for a child graph's run steps. `Run.processStream` sweeps
+     * only the graph it owns, and a child executes through `workflow.invoke()`
+     * outside that loop — so without this, a child's last message step (no
+     * successor step ever opens to close it) and every step of an aborted child
+     * stay `in_progress` forever, leaving hosts with unmatched starts.
+     *
+     * Must run BEFORE `forwarding.drain()`: closures reach the parent only as
+     * child custom events through the forwarder, which stops relaying once
+     * drained.
+     *
+     * Deliberately not called on the interrupt path, mirroring the parent's
+     * `isAwaitingResume` guard: an in-process resume continues into these same
+     * steps, so closing them would strand the resumed run. A resume that
+     * crosses a process boundary is a known gap either way — the child rebuilds
+     * from `SubagentGraphResumeState`, which carries tool-call identity but not
+     * `contentData`, so pre-interrupt steps are unreachable from the new graph
+     * and stay open. That is the child-level instance of the same cross-process
+     * orphan the parent graph has, and it needs persisted lifecycle state to
+     * fix rather than a sweep here.
+     *
+     * `at` is the moment execution actually ended, threaded through so
+     * observational work between then and the sweep cannot inflate the stamps.
+     */
+    private closeChildRunSteps;
     clearHeavyState(): void;
     private getResumeCheckpointMarker;
     getSettledToolOutput(call: ToolCall, config: RunnableConfig): Promise<SettledSubagentToolOutput | undefined>;

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

@@ -2,7 +2,7 @@ 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';
+import type { RunStepResumeState, 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";
@@ -43,6 +43,7 @@ export interface SubagentGraphResumeState {
     toolNodes: SubagentToolNodeResumeState[];
     eagerToolUsage: SubagentEagerToolUsageState[];
     eagerToolSuppressions: string[];
+    runStepState?: RunStepResumeState;
     toolOutputReferences?: ToolOutputReferenceState;
 }
 /** Private checkpoint payload linking a parent pause to an exact child state. */

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

@@ -5,7 +5,7 @@ import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleAIToolType } from '@langchain/google-common';
 import type { SummarizationNodeInput, SummarizeCompleteEvent, SummarizationConfig, SummarizeStartEvent, SummarizeDeltaEvent } from '@/types/summarize';
-import type { RunStep, RunStepDeltaEvent, RunStepClosedEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
+import type { RunStep, RunStepDeltaEvent, RunStepResumeState, RunStepClosedEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
 import type { ToolMap, ToolSessionMap, ToolEndEvent, GenericTool, LCTool, ToolExecuteBatchRequest } from '@/types/tools';
 import type { TokenCounter, StreamLimits, StreamPreemption, TokenBudgetBreakdown } from '@/types/run';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
@@ -28,6 +28,7 @@ export type SystemCallbacks = {
 };
 export type BaseGraphState = {
     messages: BaseMessage[];
+    runStepState?: RunStepResumeState;
 };
 export type AgentSubgraphState = BaseGraphState & {
     summarizationRequest?: SummarizationNodeInput;
@@ -628,6 +629,14 @@ export interface LangfuseConfig {
 }
 export interface AgentInputs {
     agentId: string;
+    /**
+     * Partition key for transient code-session ids and file refs. Agents with
+     * the same key share those refs; different execution profiles/scopes must
+     * use different keys. Defaults to the legacy shared `execute_code` slot.
+     * Non-default partitions also disable speculative eager execution of code
+     * tools because their factory may target a durable backend.
+     */
+    codeSessionKey?: string;
     /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
     name?: string;
     toolEnd?: boolean;

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

@@ -9,3 +9,4 @@ export * from './tools';
 export * from './summarize';
 export * from './activityLabel';
 export * from './assistantPhase';
+export * from './reasoningLabel';

package/dist/types/types/reasoningLabel.d.ts

@@ -0,0 +1,56 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { UsageMetadata } from '@langchain/core/messages';
+import type { ClientOptions } from '@/types/llm';
+import type { Providers } from '@/common';
+/** Lifecycle state of the visible reasoning snapshot being labeled. */
+export type ReasoningLabelStatus = 'streaming' | 'complete';
+/** Result of one reasoning-label revision. */
+export type ReasoningLabelResult = {
+    label?: string;
+    /** Provider-reported usage for host-side billing after a durable commit. */
+    usage?: UsageMetadata;
+};
+/** Options for `Run.generateReasoningLabel`. */
+export type RunReasoningLabelOptions = {
+    provider: Providers;
+    clientOptions?: ClientOptions;
+    /**
+     * Complete user-visible reasoning accumulated for this step so far. Hidden
+     * chain-of-thought must never be supplied through this API.
+     */
+    visibleReasoning: string;
+    /** Stable run-step identity shared by every revision of this label. */
+    reasoningStepId: string;
+    /** Monotonically increasing host revision for this reasoning step. */
+    revision: number;
+    /** Whether the snapshot can still grow. Default `streaming`. */
+    status?: ReasoningLabelStatus;
+    /**
+     * Last durably visible label for this step. The model repeats it exactly
+     * when the reasoning direction has not materially changed, allowing hosts
+     * to avoid redundant UI updates.
+     */
+    previousLabel?: string;
+    /**
+     * Agent that emitted the reasoning. Selects its Langfuse overlay and
+     * redaction policy. Unknown agents and omitted multi-agent ownership fail
+     * closed before tracing or generation.
+     */
+    agentId?: string;
+    /** Override for the default reasoning-label system prompt. */
+    prompt?: string;
+    /** Maximum reasoning characters retained in the prompt. Default 6000. */
+    charLimit?: number;
+    /** LangChain runnable config carrier (signal, callbacks, thread/user ids). */
+    chainOptions?: Partial<RunnableConfig> & {
+        configurable?: Record<string, unknown>;
+    };
+    /** Deterministic seed for this reasoning-label revision trace. */
+    traceSeed?: string;
+    /** Stable source run identifier recorded on the observation. */
+    sourceRunId?: string;
+    /** Source Langfuse trace id for linking this detached label trace. */
+    sourceTraceId?: string;
+    /** Host response/message identifier recorded on the observation. */
+    responseId?: string;
+};

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

@@ -75,6 +75,24 @@ export type RunStep = {
     summary?: SummaryContentBlock;
     usage?: null | object;
 };
+/** Minimal durable lifecycle state needed to continue open run steps. */
+export interface RunStepResumeEntry {
+    step: RunStep;
+    pendingToolCallIds: string[];
+    latestCompletionAt?: number;
+    openMessageStep: boolean;
+}
+/** SDK-private state persisted in LangGraph checkpoints for process-safe resume. */
+export interface RunStepResumeState {
+    version: 1;
+    revision: number;
+    nextIndex: number;
+    toolCallSteps: Array<{
+        toolCallId: string;
+        stepId: string;
+    }>;
+    steps: RunStepResumeEntry[];
+}
 /**
  * Represents a run step delta i.e. any changed fields on a run step during
  * streaming.

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

@@ -1,9 +1,9 @@
 import type { StructuredToolInterface } from '@langchain/core/tools';
-import type { RunnableToolLike } from '@langchain/core/runnables';
+import type { RunnableConfig, RunnableToolLike } from '@langchain/core/runnables';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import type { RunBreakerScope } from '@/llm/streamLimits';
-import type { MessageContentComplex, ToolErrorData } from './stream';
+import type { MessageContentComplex, RunStepResumeState, ToolErrorData } from './stream';
 import type { HumanInTheLoopConfig } from './hitl';
 import type { LangfuseConfig } from './graph';
 import type { HookRegistry } from '@/hooks';
@@ -118,6 +118,8 @@ export type ToolNodeOptions = {
     toolRegistry?: LCToolRegistry;
     /** Reference to Graph's sessions map for automatic session injection */
     sessions?: ToolSessionMap;
+    /** Partition within `sessions` used by this agent's code tools. */
+    codeSessionKey?: string;
     /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
     eventDrivenMode?: boolean;
     /** Tool definitions for event-driven mode (used for context, not invocation) */
@@ -264,6 +266,10 @@ export type ToolNodeOptions = {
      * controller.
      */
     getRunScope?: () => RunBreakerScope;
+    /** SDK-owned checkpoint bridge for open run-step lifecycle state. */
+    restoreRunStepResumeState?: (state?: RunStepResumeState, config?: RunnableConfig) => void;
+    /** SDK-owned checkpoint snapshot for open run-step lifecycle state. */
+    createRunStepResumeState?: () => RunStepResumeState;
 };
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
 export type ToolEndEvent = {
@@ -361,6 +367,19 @@ export type CodeEnvFile = (CodeEnvFileBase & {
     kind: 'user';
 });
 export type CodeExecutionToolParams = undefined | {
+    /** Trusted Code API endpoint selected by the host for this agent. */
+    baseUrl?: string;
+    /**
+     * Expected Code API execution profile. Sent as a request assertion so
+     * endpoint/configuration drift fails closed instead of silently using
+     * the wrong sandbox backend.
+     */
+    executionProfile?: CodeApiExecutionProfile;
+    /**
+     * Trusted warm-runtime affinity hint selected by the host for this
+     * agent invocation. This overrides the legacy ToolNode-injected hint.
+     */
+    runtimeSessionHint?: string;
     /** Execution session — see `CodeSessionContext.session_id`. */
     session_id?: string;
     user_id?: string;
@@ -368,15 +387,14 @@ export type CodeExecutionToolParams = undefined | {
     /** Optional host-supplied Code API auth headers. */
     authHeaders?: CodeApiAuthHeaders;
     /**
-     * Advertise best-effort stateful sessions in the tool description
-     * (variables/files may persist between calls, may reset). Prompt text
-     * only, and it must be set here because the description is bound to the
-     * LLM at construction time. Pair it with the run-scoped
-     * `toolExecution.sandbox.statefulSessions` gate, which drives the wire
-     * hint — set both from one flag so the prompt and the backend agree.
+     * Advertise filesystem-tier stateful sessions in the tool description
+     * and allow a trusted runtime affinity hint onto the wire. Resolve this,
+     * `baseUrl`, `executionProfile`, and `runtimeSessionHint` together from
+     * the executing agent so the prompt and backend agree.
      */
     statefulSessions?: boolean;
 };
+export type CodeApiExecutionProfile = 'default' | 'stateful';
 export type CodeApiAuthHeaderMap = Record<string, string>;
 export type CodeApiAuthHeaders = CodeApiAuthHeaderMap | (() => CodeApiAuthHeaderMap | Promise<CodeApiAuthHeaderMap>);
 export type FileRef = {
@@ -1032,19 +1050,17 @@ export type CloudflareSandboxExecutionConfig = {
 };
 export type SandboxExecutionConfig = {
     /**
-     * Opt into best-effort stateful runtime sessions on the remote Code API
-     * (its warm per-session MicroVM backend). This gate is run-scoped: it only
-     * controls the wire behavior (ToolNode injecting the session hint on
-     * execute_code/bash calls). The transport is otherwise unchanged.
+     * Legacy run-scoped opt-in for warm runtime hint injection. New hosts that
+     * need mixed execution profiles should resolve `statefulSessions`,
+     * `baseUrl`, `executionProfile`, and `runtimeSessionHint` on each executing
+     * agent's tool factories instead. Direct executors ignore this injected hint
+     * unless their own factory has `statefulSessions: true`.
      *
      * It does NOT change the model-facing tool description. Tool descriptions are
      * bound to the LLM at construction time (`createCodeExecutionTool` /
      * `createBashExecutionTool`), before this run config is applied inside the
      * graph, so they can only be adjusted via the tools' own `statefulSessions`
-     * factory param. Set BOTH from one flag (as LibreChat does): with this on but
-     * the factory param off, the backend runs statefully while the model is still
-     * told the environment is stateless (non-corrupting — the model just won't
-     * exploit persistence).
+     * factory param.
      */
     statefulSessions?: boolean;
     /**
@@ -1193,6 +1209,10 @@ export type BashProgrammaticToolCallingParams = ProgrammaticToolCallingParams;
 export type ProgrammaticToolCallingParams = {
     /** Code API base URL (or use CODE_BASEURL env var) */
     baseUrl?: string;
+    /** Expected Code API execution profile (host-controlled). */
+    executionProfile?: CodeApiExecutionProfile;
+    /** Trusted warm-runtime affinity hint for this agent invocation. */
+    runtimeSessionHint?: string;
     /** Safety limit for round-trips (default: 20) */
     maxRoundTrips?: number;
     /** Maximum per-sandbox-run timeout for PTC's legacy `timeout` field. */

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

@@ -0,0 +1,18 @@
+import type * as t from '@/types';
+type CodeSessionAgent = Pick<t.AgentInputs, 'codeSessionKey' | 'initialSessions'>;
+/**
+ * Seeds a top-level graph while preserving the legacy run-wide session map.
+ * A legacy `execute_code` seed is copied into every custom agent partition
+ * unless the host already supplied an explicit seed for that partition.
+ */
+export declare function seedRunInitialSessions(args: {
+    sessions: t.ToolSessionMap;
+    initialSessions: t.ToolSessionMap;
+    agents: Iterable<Pick<t.AgentInputs, 'codeSessionKey'>>;
+}): void;
+/**
+ * Seeds an isolated child graph from each selected agent. Legacy code-session
+ * entries are remapped to the owning agent's partition before they are merged.
+ */
+export declare function seedAgentInitialSessions(sessions: t.ToolSessionMap, agents: Iterable<CodeSessionAgent>): void;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.5.1",
+  "version": "3.6.1",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"

package/src/agents/AgentContext.ts

@@ -63,6 +63,7 @@ export class AgentContext {
   ): AgentContext {
     const {
       agentId,
+      codeSessionKey,
       name,
       provider,
       clientOptions,
@@ -92,6 +93,7 @@ export class AgentContext {
 
     const agentContext = new AgentContext({
       agentId,
+      codeSessionKey,
       name: name ?? agentId,
       provider,
       clientOptions,
@@ -167,6 +169,8 @@ export class AgentContext {
 
   /** Agent identifier */
   agentId: string;
+  /** Partition for this agent's transient code session and file refs. */
+  codeSessionKey?: string;
   /** Human-readable name for this agent (used in handoff context). Falls back to agentId if not provided. */
   name?: string;
   /** Provider for this specific agent */
@@ -370,6 +374,7 @@ export class AgentContext {
 
   constructor({
     agentId,
+    codeSessionKey,
     name,
     provider,
     clientOptions,
@@ -394,6 +399,7 @@ export class AgentContext {
     maxToolResultChars,
   }: {
     agentId: string;
+    codeSessionKey?: string;
     name?: string;
     provider: Providers;
     clientOptions?: t.ClientOptions;
@@ -418,6 +424,7 @@ export class AgentContext {
     maxToolResultChars?: number;
   }) {
     this.agentId = agentId;
+    this.codeSessionKey = codeSessionKey;
     this.name = name;
     this.provider = provider;
     this.clientOptions = clientOptions;