@librechat/agents 3.6.3 → 3.6.5

package/src/graphs/Graph.ts

@@ -1312,6 +1312,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   subagentUsageSink?: t.SubagentUsageSink;
   /** See {@link t.StandardGraphInput.subagentScope}. */
   subagentScope: boolean;
+  /** See {@link t.StandardGraphInput.subagentTasks}. */
+  subagentTasks: t.SubagentTaskConfig | undefined;
   /** See {@link t.StandardGraphInput.subagentExecutionContext}. */
   private readonly subagentExecutionContext?: t.SubagentExecutionContext;
   /** See {@link t.StandardGraphInput.preemption}. */
@@ -1445,6 +1447,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       indexTokenCountMap,
       calibrationRatio,
       subagentUsageSink,
+      subagentTasks,
       subagentScope,
       subagentExecutionContext,
       preemption,
@@ -1469,6 +1472,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     this.signal = signal;
     this.langfuse = langfuse;
     this.subagentUsageSink = subagentUsageSink;
+    this.subagentTasks = subagentTasks;
     this.subagentScope = subagentScope === true;
     this.subagentExecutionContext = subagentExecutionContext;
     this.preemption = preemption;
@@ -1695,8 +1699,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
    * budget is taken by {@link claimPreemptSeal} once the accumulated chunk is
    * known to be safe, so a chunk that cannot seal never spends budget.
    *
-   * Subagent scopes never seal: a steer targets the top-level conversation,
-   * and a child run must finish so its parent sees a complete result.
+   * Ordinary subagent scopes never receive `preemption`. A detached child may
+   * receive a dedicated parent-control preemption source, in which case the
+   * same provider-safe seal path is intentionally reused inside that child.
    */
   /** Internal seal preconditions only — no host callback, no side effects. */
   private canClaimPreemptSeal(): boolean {
@@ -1710,7 +1715,6 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     const runId =
       (this.config?.configurable?.run_id as string | undefined) ?? this.runId;
     return (
-      !this.subagentScope &&
       this.preemption != null &&
       !this.preemptSealInFlight &&
       this.preemptSealBudgetUsed < resolveMaxSeals(this.preemption.maxSeals) &&
@@ -4769,19 +4773,12 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         }
         const getParentHandlerRegistry = (): HandlerRegistry | undefined =>
           this.handlerRegistry ?? this.parentToolHandlerRegistry;
-        const createConfiguredChildGraph: GraphFactory = (request) => {
-          const childGraph = this.graphFactory(request);
-          if (this.subagentModelOverride != null) {
-            childGraph.overrideModel = this.subagentModelOverride;
-            childGraph.setSubagentModelOverride(this.subagentModelOverride);
-          }
-          const childHandlerRegistry = createChildHandlerRegistry(
-            getParentHandlerRegistry()
-          );
-          // Pure execution-ordering hint (unlike `humanInTheLoop`). It only
-          // reorders tools already in the child's direct group; it does not
-          // force a schema-only event tool onto the direct execution path.
-          applyGraphRuntimeConfig(childGraph, {
+        const snapshotChildGraphFactory = (
+          parentHandlerRegistry: HandlerRegistry | undefined
+        ): GraphFactory => {
+          const graphFactory = this.graphFactory;
+          const subagentModelOverride = this.subagentModelOverride;
+          const runtimeConfig = {
             hookRegistry: this.hookRegistry,
             humanInTheLoop: this.humanInTheLoop,
             toolOutputReferences: this.toolOutputReferences,
@@ -4789,18 +4786,33 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             codeSessionToolNames: this.codeSessionToolNames,
             interruptingToolNames: this.interruptingToolNames,
             toolExecution: this.toolExecution,
-          });
-          if (this.humanInTheLoop?.enabled === true) {
-            childGraph.compileOptions = {
-              checkpointer: this.compileOptions?.checkpointer,
-            };
-          }
-          childGraph.parentToolHandlerRegistry = childHandlerRegistry;
-          childGraph.eventToolExecutionAvailable =
-            childHandlerRegistry?.getHandler(GraphEvents.ON_TOOL_EXECUTE) !=
-            null;
-          return childGraph;
+          };
+          const checkpointer = this.compileOptions?.checkpointer;
+          return (request): StandardGraph => {
+            const childGraph = graphFactory(request);
+            if (subagentModelOverride != null) {
+              childGraph.overrideModel = subagentModelOverride;
+              childGraph.setSubagentModelOverride(subagentModelOverride);
+            }
+            const childHandlerRegistry = createChildHandlerRegistry(
+              parentHandlerRegistry
+            );
+            // Pure execution-ordering hint (unlike `humanInTheLoop`). It only
+            // reorders tools already in the child's direct group; it does not
+            // force a schema-only event tool onto the direct execution path.
+            applyGraphRuntimeConfig(childGraph, runtimeConfig);
+            if (runtimeConfig.humanInTheLoop?.enabled === true) {
+              childGraph.compileOptions = { checkpointer };
+            }
+            childGraph.parentToolHandlerRegistry = childHandlerRegistry;
+            childGraph.eventToolExecutionAvailable =
+              childHandlerRegistry?.getHandler(GraphEvents.ON_TOOL_EXECUTE) !=
+              null;
+            return childGraph;
+          };
         };
+        const createConfiguredChildGraph: GraphFactory = (request) =>
+          snapshotChildGraphFactory(getParentHandlerRegistry())(request);
         const executor = new SubagentExecutor({
           configs: new Map(
             executableConfigs.map((config) => [config.type, config])
@@ -4820,6 +4832,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           langfuse: this.langfuse,
           tokenCounter: agentContext.tokenCounter,
           usageSink: this.subagentUsageSink,
+          taskConfig: this.subagentTasks,
           streamLimits: this.streamLimits,
           humanInTheLoop: this.humanInTheLoop,
           checkpointer: this.compileOptions?.checkpointer,
@@ -4830,6 +4843,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               input,
             }),
           createChildGraphByKind: createConfiguredChildGraph,
+          createDetachedChildGraphFactory: (
+            parentHandlerRegistry
+          ): GraphFactory =>
+            snapshotChildGraphFactory(parentHandlerRegistry),
         });
         this.registerSubagentExecutor(executor);
 
@@ -4837,6 +4854,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           const input = rawInput as {
             description?: string;
             subagent_type?: string;
+            subagent_thread_id?: string;
+            run_in_background?: boolean;
           };
           const description =
             typeof input.description === 'string' &&
@@ -4845,6 +4864,11 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               : DEFAULT_SUBAGENT_DESCRIPTION;
           const subagentType =
             typeof input.subagent_type === 'string' ? input.subagent_type : '';
+          const subagentThreadId =
+            typeof input.subagent_thread_id === 'string' &&
+            input.subagent_thread_id.trim() !== ''
+              ? input.subagent_thread_id.trim()
+              : undefined;
           const threadId = config.configurable?.thread_id as string | undefined;
           /** Surface the parent call id so child checkpoints, interrupts, and
            * update events remain correlated across replay and resume. */
@@ -4869,7 +4893,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           const batchScope = config.configurable?.[
             RUN_BREAKER_SCOPE_CONFIG_KEY
           ] as RunBreakerScope | undefined;
-          const result = await executor.execute({
+          const executeParams = {
             description,
             subagentType,
             threadId,
@@ -4885,9 +4909,30 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             parentConfigurable: config.configurable as
               | Record<string, unknown>
               | undefined,
-          });
+          };
+          if (input.run_in_background === true) {
+            return executor.executeInBackground({
+              ...executeParams,
+              ...(subagentThreadId == null
+                ? {}
+                : { subagentThreadId }),
+            });
+          }
+          if (subagentThreadId != null) {
+            return JSON.stringify({
+              status: 'rejected',
+              tool: Constants.SUBAGENT,
+              message:
+                'Child-thread continuation requires run_in_background.',
+            });
+          }
+          const result = await executor.execute(executeParams);
           return result.content;
-        }, buildSubagentToolParams(executableConfigs));
+        }, buildSubagentToolParams(executableConfigs, {
+          background: this.subagentTasks != null,
+          threadContinuation:
+            this.subagentTasks?.store.supportsThreadContinuation === true,
+        }));
         const replayableSubagentTool = subagentTool as typeof subagentTool &
           ReplayableSubagentTool;
         replayableSubagentTool[SUBAGENT_REPLAY_CONTROLLER] = {

package/src/hooks/HookRegistry.ts

@@ -6,6 +6,7 @@ import type {
   ToolApprovalReplaySnapshot,
   AggregatedHookResult,
 } from './types';
+import { HOOK_EVENTS } from './types';
 
 function serializeApprovalKey(key: ToolApprovalReplayKey): string {
   return JSON.stringify([key.executionScope, key.agentId, key.toolUseId]);
@@ -227,6 +228,23 @@ export class HookRegistry {
     }
   }
 
+  /**
+   * Takes an isolated policy snapshot for work that may outlive the source
+   * run. Global and source-session matchers become global to the returned
+   * task-local registry, so parent cleanup and one-shot hook consumption
+   * cannot mutate the detached child (or vice versa). Runtime halt signals
+   * and pending approvals are intentionally not copied.
+   */
+  forkSession(sourceSessionId: string): HookRegistry {
+    const fork = new HookRegistry();
+    for (const event of HOOK_EVENTS) {
+      for (const matcher of this.getMatchers(event, sourceSessionId)) {
+        fork.register(event, matcher);
+      }
+    }
+    return fork;
+  }
+
   getPendingToolApproval(
     sessionId: string,
     key: ToolApprovalReplayKey

package/src/langchain/messages.ts

@@ -10,6 +10,8 @@ export {
   isAIMessage,
   isBaseMessage,
   isToolMessage,
+  mapChatMessagesToStoredMessages,
+  mapStoredMessagesToChatMessages,
 } from '@langchain/core/messages';
 
 export type {
@@ -17,5 +19,6 @@ export type {
   MessageContent,
   MessageContentText,
   MessageContentImageUrl,
+  StoredMessage,
   UsageMetadata,
 } from '@langchain/core/messages';

package/src/langfuseConfig.ts

@@ -175,6 +175,44 @@ export function resolveToolOutputTracingConfig(
   };
 }
 
+/**
+ * Merges header maps case-insensitively, keeping the override's casing.
+ *
+ * A plain spread would keep both `X-Proxy-Token` and `x-proxy-token`, and
+ * filling a fetch `Headers` from that record *appends* rather than replaces —
+ * the exporter would send one comma-joined `run-token, agent-token` value, so
+ * the agent override never cleanly wins and a gateway sees a malformed
+ * credential. Matches the case-insensitive identity already used for the
+ * destination key.
+ */
+function mergeAdditionalHeaders(
+  base?: Record<string, string>,
+  override?: Record<string, string>
+): Record<string, string> | undefined {
+  if (base == null && override == null) {
+    return undefined;
+  }
+
+  const merged: Record<string, string> = { ...base };
+  if (override == null) {
+    return merged;
+  }
+
+  const baseKeyByLower = new Map<string, string>(
+    Object.keys(merged).map((key) => [key.toLowerCase(), key])
+  );
+  for (const [key, value] of Object.entries(override)) {
+    const lower = key.toLowerCase();
+    const existingKey = baseKeyByLower.get(lower);
+    if (existingKey != null && existingKey !== key) {
+      delete merged[existingKey];
+    }
+    merged[key] = value;
+    baseKeyByLower.set(lower, key);
+  }
+  return merged;
+}
+
 export function resolveLangfuseConfig(
   runLangfuse?: t.LangfuseConfig,
   agentLangfuse?: t.LangfuseConfig
@@ -208,6 +246,10 @@ export function resolveLangfuseConfig(
         ...agentLangfuse.metadata,
       }
       : undefined;
+  const additionalHeaders = mergeAdditionalHeaders(
+    runLangfuse.additionalHeaders,
+    agentLangfuse.additionalHeaders
+  );
   const librechatTraceAttributes =
     runLangfuse.librechatTraceAttributes != null ||
     agentLangfuse.librechatTraceAttributes != null
@@ -230,6 +272,7 @@ export function resolveLangfuseConfig(
     ...runLangfuse,
     ...agentLangfuse,
     ...(metadata != null ? { metadata } : {}),
+    ...(additionalHeaders != null ? { additionalHeaders } : {}),
     ...(librechatTraceAttributes != null ? { librechatTraceAttributes } : {}),
     ...(tags != null ? { tags } : {}),
     ...(toolNodeTracing != null ? { toolNodeTracing } : {}),

package/src/langfuseSpanRegistry.ts

@@ -59,6 +59,12 @@ function resolveLangfuseEnvironment(
   return undefined;
 }
 
+function hasAdditionalHeaders(
+  headers?: Record<string, string>
+): headers is Record<string, string> {
+  return headers != null && Object.keys(headers).length > 0;
+}
+
 export function getLangfuseSpanProcessorParams(
   langfuse?: t.LangfuseConfig
 ): LangfuseSpanProcessorParams | undefined {
@@ -66,6 +72,9 @@ export function getLangfuseSpanProcessorParams(
     return undefined;
   }
   const environment = resolveLangfuseEnvironment(langfuse);
+  const additionalHeaders = hasAdditionalHeaders(langfuse?.additionalHeaders)
+    ? { additionalHeaders: langfuse.additionalHeaders }
+    : {};
   if (hasLangfuseConfigCredentials(langfuse)) {
     return {
       publicKey: langfuse.publicKey,
@@ -75,6 +84,7 @@ export function getLangfuseSpanProcessorParams(
       ...(langfuse.mediaUploadEnabled != null
         ? { mediaUploadEnabled: langfuse.mediaUploadEnabled }
         : {}),
+      ...additionalHeaders,
     };
   }
   if (hasLangfuseEnvConfig()) {
@@ -90,6 +100,7 @@ export function getLangfuseSpanProcessorParams(
       ...(langfuse?.mediaUploadEnabled != null
         ? { mediaUploadEnabled: langfuse.mediaUploadEnabled }
         : {}),
+      ...additionalHeaders,
     };
   }
   if (isPresent(langfuse?.baseUrl) && hasLangfuseEnvCredentials()) {
@@ -101,6 +112,7 @@ export function getLangfuseSpanProcessorParams(
       ...(langfuse.mediaUploadEnabled != null
         ? { mediaUploadEnabled: langfuse.mediaUploadEnabled }
         : {}),
+      ...additionalHeaders,
     };
   }
   return undefined;
@@ -112,12 +124,37 @@ function hashCacheKeyValue(value: string | undefined): string | undefined {
     : undefined;
 }
 
+/**
+ * Order- and case-insensitive digest of the custom headers sent to a
+ * destination, so header maps that differ only in key order or header-name
+ * casing resolve to one destination instead of duplicating its exporter.
+ * Hashed because these values are credentials (proxy tokens, gateway keys).
+ * Absent and empty both yield `undefined`, keeping keys stable for the
+ * overwhelmingly common no-headers case.
+ */
+function hashAdditionalHeaders(
+  headers: Record<string, string> | undefined
+): string | undefined {
+  if (!hasAdditionalHeaders(headers)) {
+    return undefined;
+  }
+  const normalized = Object.entries(headers)
+    .map(([name, value]) => JSON.stringify([name.trim().toLowerCase(), value]))
+    .sort();
+  return hashCacheKeyValue(normalized.join('\n'));
+}
+
 /**
  * Identity of an export destination (project credentials + endpoint +
- * environment) only. Processor-level policies like `toolOutputTracing` are
- * deliberately excluded: two spans exporting to the same project under
- * different redaction settings still share a destination and may parent one
- * another.
+ * environment + custom headers) only. Processor-level policies like
+ * `toolOutputTracing` are deliberately excluded: two spans exporting to the
+ * same project under different redaction settings still share a destination
+ * and may parent one another.
+ *
+ * Custom headers are included because a gateway may route on them, making two
+ * otherwise-identical configs different projects. Treating them as part of the
+ * destination keeps a run from inheriting a parent span bound elsewhere, and
+ * keeps a rotated proxy credential from reusing the stale exporter.
  */
 export function getLangfuseDestinationKey(
   params: LangfuseSpanProcessorParams
@@ -127,6 +164,7 @@ export function getLangfuseDestinationKey(
     secretKeyHash: hashCacheKeyValue(params.secretKey),
     baseUrl: params.baseUrl,
     environment: params.environment,
+    additionalHeadersHash: hashAdditionalHeaders(params.additionalHeaders),
   });
 }
 

package/src/run.ts

@@ -296,6 +296,7 @@ export class Run<_T extends t.BaseGraphState> {
   private subagentUsageSink?: t.SubagentUsageSink;
   private preemption?: t.StreamPreemption;
   private streamLimits?: t.StreamLimits;
+  private subagentTasks?: t.SubagentTaskConfig;
   private indexTokenCountMap?: Record<string, number>;
   calibrationRatio: number = 1;
   graphRunnable?: t.CompiledStateWorkflow;
@@ -363,6 +364,7 @@ export class Run<_T extends t.BaseGraphState> {
     this.interruptingToolNames = config.interruptingToolNames;
     this.toolExecution = config.toolExecution;
     this.subagentUsageSink = config.subagentUsageSink;
+    this.subagentTasks = config.subagentTasks;
     this.preemption = config.preemption;
     this.streamLimits = config.streamLimits;
 
@@ -455,6 +457,7 @@ export class Run<_T extends t.BaseGraphState> {
         indexTokenCountMap: this.indexTokenCountMap,
         calibrationRatio: this.calibrationRatio,
         subagentUsageSink: this.subagentUsageSink,
+        subagentTasks: this.subagentTasks,
         preemption: this.preemption,
         streamLimits: this.streamLimits,
       },
@@ -493,6 +496,7 @@ export class Run<_T extends t.BaseGraphState> {
         indexTokenCountMap: this.indexTokenCountMap,
         calibrationRatio: this.calibrationRatio,
         subagentUsageSink: this.subagentUsageSink,
+        subagentTasks: this.subagentTasks,
         preemption: this.preemption,
         streamLimits: this.streamLimits,
       },

package/src/tools/SubagentTool.ts

@@ -13,7 +13,7 @@ WHEN TO USE:
 - A specialized subagent is available for the task domain.
 
 WHAT HAPPENS:
-- A fresh agent or configured agent graph is created with the task description as its only input.
+- A fresh agent or configured agent graph is created with the task description as its only input, unless the host enables child-thread continuation and you provide a saved thread id.
 - The delegated agent or team runs to completion using isolated tools and context.
 - Only the single agent's final response or the graph's designated result-agent response is returned to you.
 
@@ -27,6 +27,12 @@ const DESCRIPTION_PROP_DESCRIPTION =
 const SUBAGENT_TYPE_PROP_DESCRIPTION =
   'Which subagent type to delegate to. Must be one of the available types.';
 
+const RUN_IN_BACKGROUND_PROP_DESCRIPTION =
+  'Set true to start the subagent as a detached process-local task and return a background_task_id immediately. Poll the host background-task tool to collect its result. The task can outlive this turn but does not survive a process restart.';
+
+const SUBAGENT_THREAD_PROP_DESCRIPTION =
+  'Continue a host-owned child thread using a fresh execution lease. The saved thread must belong to this scope and subagent type. Only available with run_in_background.';
+
 export const SubagentToolSchema = {
   type: 'object',
   properties: {
@@ -54,7 +60,10 @@ export const SubagentToolDefinition: LCTool = {
  * Used by `Graph.createAgentNode()` when constructing the runtime tool instance.
  * Extends `SubagentToolSchema` by populating `subagent_type.enum` dynamically.
  */
-export function buildSubagentToolParams(configs: SubagentConfig[]): {
+export function buildSubagentToolParams(
+  configs: SubagentConfig[],
+  options: { background?: boolean; threadContinuation?: boolean } = {}
+): {
   name: string;
   schema: JsonSchemaType;
   description: string;
@@ -79,10 +88,35 @@ export function buildSubagentToolParams(configs: SubagentConfig[]): {
           enum: types,
           description: `${SUBAGENT_TYPE_PROP_DESCRIPTION} Available: ${types.join(', ')}.`,
         },
+        ...(options.background === true
+          ? {
+            run_in_background: {
+              type: 'boolean',
+              description: RUN_IN_BACKGROUND_PROP_DESCRIPTION,
+            },
+          }
+          : {}),
+        ...(options.background === true &&
+        options.threadContinuation === true
+          ? {
+            subagent_thread_id: {
+              type: 'string',
+              description: SUBAGENT_THREAD_PROP_DESCRIPTION,
+            },
+          }
+          : {}),
       },
       required: ['description', 'subagent_type'],
     },
-    description: `${SubagentToolDescription}\n\nAvailable types:\n${typeDescriptions}`,
+    description: `${SubagentToolDescription}${
+      options.background === true
+        ? '\n\nBACKGROUND EXECUTION:\n- Set run_in_background to true when you do not need the result immediately. The call returns a background_task_id; use the host background-task tools to poll, steer, queue, interrupt, or cancel it.'
+        : ''
+    }${
+      options.background === true && options.threadContinuation === true
+        ? '\n- To continue a completed child later, set run_in_background and pass its subagent_thread_id. The host starts a fresh execution from saved history; it does not restore a completed runtime.'
+        : ''
+    }\n\nAvailable types:\n${typeDescriptions}`,
   };
 }