@librechat/agents 3.6.3 → 3.6.5

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

@@ -79,6 +79,14 @@ export declare class HookRegistry {
     clearSession(sessionId: string): void;
     /** Copies session-scoped policy into a rebuilt or branched Run. */
     copySession(sourceSessionId: string, targetSessionId: string): void;
+    /**
+     * 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;
     getPendingToolApproval(sessionId: string, key: ToolApprovalReplayKey): AggregatedHookResult | undefined;
     setPendingToolApproval(sessionId: string, key: ToolApprovalReplayKey, result: AggregatedHookResult): void;
     clearPendingToolApproval(sessionId: string, key: ToolApprovalReplayKey): void;

package/dist/types/langchain/messages.d.ts

@@ -1,2 +1,2 @@
-export { AIMessage, AIMessageChunk, BaseMessage, BaseMessageChunk, HumanMessage, SystemMessage, ToolMessage, getBufferString, isAIMessage, isBaseMessage, isToolMessage, } from '@langchain/core/messages';
-export type { BaseMessageFields, MessageContent, MessageContentText, MessageContentImageUrl, UsageMetadata, } from '@langchain/core/messages';
+export { AIMessage, AIMessageChunk, BaseMessage, BaseMessageChunk, HumanMessage, SystemMessage, ToolMessage, getBufferString, isAIMessage, isBaseMessage, isToolMessage, mapChatMessagesToStoredMessages, mapStoredMessagesToChatMessages, } from '@langchain/core/messages';
+export type { BaseMessageFields, MessageContent, MessageContentText, MessageContentImageUrl, StoredMessage, UsageMetadata, } from '@langchain/core/messages';

package/dist/types/langfuseSpanRegistry.d.ts

@@ -6,10 +6,15 @@ export declare function getLangfuseManagedSpanDestination(span: Span): string |
 export declare function getLangfuseSpanProcessorParams(langfuse?: t.LangfuseConfig): LangfuseSpanProcessorParams | undefined;
 /**
  * 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 declare function getLangfuseDestinationKey(params: LangfuseSpanProcessorParams): string;
 /** The export destination a run with this config resolves to, or `undefined`

package/dist/types/run.d.ts

@@ -20,6 +20,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     private subagentUsageSink?;
     private preemption?;
     private streamLimits?;
+    private subagentTasks?;
     private indexTokenCountMap?;
     calibrationRatio: number;
     graphRunnable?: t.CompiledStateWorkflow;

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

@@ -2,7 +2,7 @@ import type { JsonSchemaType, LCTool } from '@/types/tools';
 import type { SubagentConfig } from '@/types';
 import { Constants } from '@/common';
 export declare const SubagentToolName = Constants.SUBAGENT;
-export declare const SubagentToolDescription = "Delegate a task to a specialized subagent or bounded agent team that runs in an isolated context window. The delegated execution returns only its designated final text result \u2014 all intermediate tool calls, reasoning, and context stay isolated.\n\nWHEN TO USE:\n- The task is self-contained and can be described in a single prompt.\n- You want to offload verbose or exploratory work without bloating your own context.\n- A specialized subagent is available for the task domain.\n\nWHAT HAPPENS:\n- A fresh agent or configured agent graph is created with the task description as its only input.\n- The delegated agent or team runs to completion using isolated tools and context.\n- Only the single agent's final response or the graph's designated result-agent response is returned to you.\n\nCONSTRAINTS:\n- subagent_type must match one of the available types listed below.\n- The subagent cannot see your conversation history.";
+export declare const SubagentToolDescription = "Delegate a task to a specialized subagent or bounded agent team that runs in an isolated context window. The delegated execution returns only its designated final text result \u2014 all intermediate tool calls, reasoning, and context stay isolated.\n\nWHEN TO USE:\n- The task is self-contained and can be described in a single prompt.\n- You want to offload verbose or exploratory work without bloating your own context.\n- A specialized subagent is available for the task domain.\n\nWHAT HAPPENS:\n- 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.\n- The delegated agent or team runs to completion using isolated tools and context.\n- Only the single agent's final response or the graph's designated result-agent response is returned to you.\n\nCONSTRAINTS:\n- subagent_type must match one of the available types listed below.\n- The subagent cannot see your conversation history.";
 export declare const SubagentToolSchema: {
     readonly type: "object";
     readonly properties: {
@@ -32,7 +32,10 @@ export declare const SubagentToolDefinition: LCTool;
  * Used by `Graph.createAgentNode()` when constructing the runtime tool instance.
  * Extends `SubagentToolSchema` by populating `subagent_type.enum` dynamically.
  */
-export declare function buildSubagentToolParams(configs: SubagentConfig[]): {
+export declare function buildSubagentToolParams(configs: SubagentConfig[], options?: {
+    background?: boolean;
+    threadContinuation?: boolean;
+}): {
     name: string;
     schema: JsonSchemaType;
     description: string;

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

@@ -0,0 +1,45 @@
+import type { SubagentTaskClaim, SubagentTaskControlCommand, SubagentTaskControlResult, SubagentTaskSnapshot, SubagentTaskStartRequest, SubagentTaskStartResult, SubagentTaskStore } from '@/types';
+export interface InMemorySubagentTaskStoreOptions {
+    completedTtlMs?: number;
+    maxControlMessageChars?: number;
+    maxControlsPerTask?: number;
+    maxErrorChars?: number;
+    maxResultChars?: number;
+    maxRunningPerScope?: number;
+    maxRunningTotal?: number;
+    maxTasksPerScope?: number;
+    maxTasksTotal?: number;
+    taskTimeoutMs?: number;
+}
+/**
+ * Bounded process-local task ownership for detached subagents. Terminal tasks
+ * keep only a bounded claimable result: the child graph, checkpoint, and full
+ * transcript are released. Hosts that need later child-chat continuation may
+ * replace this store and persist the canonical messages returned by `run`.
+ * This default deliberately makes no restart or cross-replica durability
+ * claim.
+ */
+export declare class InMemorySubagentTaskStore implements SubagentTaskStore {
+    private readonly buckets;
+    private readonly options;
+    private runningTasks;
+    private totalTasks;
+    constructor(options?: InMemorySubagentTaskStoreOptions);
+    start(request: SubagentTaskStartRequest): SubagentTaskStartResult;
+    get(scopeId: string, taskId: string): SubagentTaskSnapshot | undefined;
+    list(scopeId: string): SubagentTaskSnapshot[];
+    claim(scopeId: string, taskId: string): SubagentTaskClaim;
+    control(scopeId: string, taskId: string, command: SubagentTaskControlCommand): SubagentTaskControlResult;
+    private getBucket;
+    private find;
+    private makeRoom;
+    private makeGlobalRoom;
+    private sweepBucket;
+    private removeTask;
+    private dropEmptyBucket;
+    private scheduleExpiry;
+    private clearTaskExpiry;
+    private clearTaskTimeout;
+    private finishWithError;
+    private createRuntime;
+}

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

@@ -1,17 +1,19 @@
 import { BaseMessage } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { ToolCall } from '@langchain/core/messages/tool';
-import type { MultiAgentGraphState, HumanInTheLoopConfig, StandardGraphInput, ExecutableSubagentConfigEntry, SubagentExecutionContext, SubagentUsageSink, TokenCounter } from '@/types';
+import type { MultiAgentGraphState, HumanInTheLoopConfig, StandardGraphInput, ExecutableSubagentConfigEntry, SubagentExecutionContext, SubagentTaskConfig, SubagentTaskRuntime, SubagentUsageSink, TokenCounter } from '@/types';
 import type { SubagentResumeManifest, SettledSubagentToolOutput } from './SubagentReplay';
-import type { HookRegistry } from '@/hooks';
 import type { GraphFactory } from '@/graphs/graphFactory';
 import type { StandardGraph } from '@/graphs/Graph';
-import type { HandlerRegistry } from '@/events';
+import { HookRegistry } from '@/hooks';
+import { HandlerRegistry } from '@/events';
 export { buildChildInputs, isGraphSubagentConfig, normalizeSubagentConfigs, normalizeSubagentConfigEntries, resolveSubagentConfigs, resolveSubagentConfigEntries, } from './childGraphConfig';
 export declare const DEFAULT_SUBAGENT_DESCRIPTION = "No task description provided";
 export type SubagentExecuteParams = {
     description: string;
     subagentType: string;
+    /** Saved logical child thread selected by the parent model. */
+    subagentThreadId?: string;
     threadId?: string;
     /** Signal attached to this specific parent tool invocation. */
     signal?: AbortSignal;
@@ -62,10 +64,18 @@ export type SubagentExecuteParams = {
      * rather than sharing parent's host context.
      */
     parentConfigurable?: Record<string, unknown>;
+    /** Dedicated hook session used by a detached task. @internal */
+    hookSessionId?: string;
+    /** Process-local task controls consumed by the child graph. @internal */
+    taskRuntime?: SubagentTaskRuntime;
+    /** Host-restored child transcript for a fresh continuation run. @internal */
+    initialMessages?: BaseMessage[];
 };
 export type SubagentExecuteResult = {
     content: string;
     messages: BaseMessage[];
+    /** Tagged internal failure; foreground callers retain the legacy content. */
+    error?: string;
 };
 /**
  * Factory that constructs a child graph for subagent execution. Injected
@@ -121,6 +131,11 @@ export type SubagentExecutorOptions = {
     /** Preferred polymorphic child constructor. The legacy standard-only
      * factory remains required for source compatibility. */
     createChildGraphByKind?: GraphFactory;
+    /**
+     * Captures a child-graph factory and its run-scoped host dependencies
+     * synchronously, before a detached task can outlive parent cleanup.
+     */
+    createDetachedChildGraphFactory?: (parentHandlerRegistry: HandlerRegistry) => GraphFactory;
     /**
      * Parent's event handler registry. When provided, child-graph events are
      * forwarded through this registry so hosts can:
@@ -143,6 +158,8 @@ export type SubagentExecutorOptions = {
      * nested subagents report through the same sink.
      */
     usageSink?: SubagentUsageSink;
+    /** Host-owned process-local task namespace for detached execution. */
+    taskConfig?: SubagentTaskConfig;
 };
 export declare class SubagentExecutor {
     private readonly configs;
@@ -167,7 +184,9 @@ export declare class SubagentExecutor {
     private readonly maxDepth;
     private readonly createChildGraph;
     private readonly createChildGraphByKind?;
+    private readonly createDetachedChildGraphFactory?;
     private readonly usageSink?;
+    private readonly taskConfig?;
     private readonly executions;
     private replayCheckpointWorkflow?;
     private readonly resolveParentHandlerRegistry?;
@@ -181,6 +200,14 @@ export declare class SubagentExecutor {
     private composeChildSignal;
     /** Snapshot of the parent's registry at the moment a subagent is dispatched. */
     private getParentHandlerRegistry;
+    /**
+     * Starts one independently-owned executor behind the configured task store.
+     * The parent ToolNode receives the handle synchronously; the detached clone
+     * is not registered on the parent graph, so end-of-turn cleanup cannot
+     * invalidate or clear a child that intentionally outlives that turn.
+     */
+    executeInBackground(params: SubagentExecuteParams): string;
+    private executeDetached;
     private bindExecutionDefinition;
     /** Resolve one lazy descriptor per stable child execution. Concurrent
      * duplicate dispatches share the same in-flight resolution; HITL re-entry

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

@@ -1,2 +1,4 @@
 export { DEFAULT_SUBAGENT_DESCRIPTION, SubagentExecutor, filterSubagentResult, filterGraphSubagentResult, isGraphSubagentConfig, normalizeSubagentConfigs, normalizeSubagentConfigEntries, resolveSubagentConfigs, resolveSubagentConfigEntries, buildChildInputs, summarizeEvent, } from './SubagentExecutor';
 export type { SubagentExecuteParams, SubagentExecuteResult, SubagentExecutorOptions, ChildGraphFactory, } from './SubagentExecutor';
+export { InMemorySubagentTaskStore } from './InMemorySubagentTaskStore';
+export type { InMemorySubagentTaskStoreOptions } from './InMemorySubagentTaskStore';

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

@@ -9,6 +9,7 @@ import type { RunStep, RunStepDeltaEvent, RunStepResumeState, RunStepClosedEvent
 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';
+import type { SubagentTaskConfig } from '@/types/subagentTasks';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
 /** Interface for bound model with stream and invoke methods */
@@ -239,6 +240,12 @@ export type StandardGraphInput = {
      * they already flow through the registry's `CHAT_MODEL_END` handler.
      */
     subagentUsageSink?: SubagentUsageSink;
+    /**
+     * Optional host-owned process-local task namespace for detached subagents.
+     * Presence enables `run_in_background` on the subagent tool. Child graphs
+     * do not inherit it, keeping background nesting disabled for the MVP.
+     */
+    subagentTasks?: SubagentTaskConfig;
     /**
      * True when this graph IS a subagent child run (set by `SubagentExecutor`
      * when it constructs the child graph). Drives the hook-input `agentId`
@@ -250,10 +257,10 @@ export type StandardGraphInput = {
      */
     subagentScope?: boolean;
     /**
-     * Cooperative preemption, forwarded from `RunConfig.preemption`. Only ever
-     * set on the top-level graph: a steer targets the conversation, so subagent
-     * children must run to completion and `buildChildInputs` does not propagate
-     * this field.
+     * Cooperative preemption, forwarded from `RunConfig.preemption`. Ordinary
+     * child graphs do not inherit it. Detached subagent tasks may receive their
+     * own internal parent-control source so an interrupt can reuse the same
+     * provider-safe sealing path without targeting the top-level conversation.
      */
     preemption?: StreamPreemption;
     /**
@@ -608,6 +615,17 @@ export interface LangfuseConfig {
      * payloads. Defaults to the Langfuse SDK behavior.
      */
     mediaUploadEnabled?: boolean;
+    /**
+     * Extra HTTP headers sent on every Langfuse export request (OTLP trace
+     * export and media uploads), for self-hosted instances behind an
+     * authenticating proxy or gateway.
+     *
+     * Deployment-level only: one exporter is shared by every span routed to a
+     * destination, so these cannot carry per-request or per-user identity.
+     * Headers participate in destination identity — see
+     * `getLangfuseDestinationKey`.
+     */
+    additionalHeaders?: Record<string, string>;
     metadata?: Record<string, string | number | boolean | null | undefined>;
     /**
      * Internal OTLP span attributes to attach to Langfuse observations before

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

@@ -5,6 +5,7 @@ export * from './messages';
 export * from './run';
 export * from './skill';
 export * from './stream';
+export * from './subagentTasks';
 export * from './tools';
 export * from './summarize';
 export * from './activityLabel';

package/dist/types/types/run.d.ts

@@ -4,6 +4,7 @@ import type { BaseMessage } from '@langchain/core/messages';
 import type { StructuredTool } from '@langchain/core/tools';
 import type * as z from 'zod';
 import type { ToolSessionMap, ToolExecutionConfig, ToolOutputReferencesConfig, EagerEventToolExecutionConfig } from '@/types/tools';
+import type { SubagentTaskConfig } from '@/types/subagentTasks';
 import type { HumanInTheLoopConfig } from '@/types/hitl';
 import type { HookRegistry } from '@/hooks';
 import type * as s from '@/types/stream';
@@ -215,6 +216,11 @@ export type RunConfig = {
      * the registered `CHAT_MODEL_END` handler as usual.
      */
     subagentUsageSink?: g.SubagentUsageSink;
+    /**
+     * Trusted process-local task namespace for detached subagent execution.
+     * Omit to preserve foreground-only subagent behavior.
+     */
+    subagentTasks?: SubagentTaskConfig;
     /**
      * Pre-constructed hook registry for this run. Hooks fire at lifecycle
      * points in `processStream` (RunStart, UserPromptSubmit, Stop,

package/dist/types/types/subagentTasks.d.ts

@@ -0,0 +1,172 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { SubagentUpdateEvent } from './graph';
+import type { InjectedMessage } from './tools';
+/** Terminal and in-flight states for a detached subagent task. */
+export type SubagentTaskStatus = 'running' | 'completed' | 'error' | 'cancelled';
+/** Where a pending parent message may enter the child run. */
+export type SubagentTaskBoundary = 'preempt' | 'tool' | 'turn';
+/** Parent-to-child control operations accepted while a task is running. */
+export type SubagentTaskControlCommand = {
+    action: 'steer' | 'queue' | 'interrupt';
+    message: string;
+} | {
+    action: 'cancel';
+} | {
+    action: 'cancel_message';
+    controlId: string;
+};
+/** Small, payload-free progress view safe to retain between parent turns. */
+export interface SubagentTaskProgress {
+    phase: SubagentUpdateEvent['phase'];
+    at: number;
+    eventCount: number;
+    label?: string;
+}
+/** Read-only task metadata. Results are exposed only through `claim`. */
+export interface SubagentTaskSnapshot {
+    /** Handle for this child-thread execution lease within its trusted scope. */
+    taskId: string;
+    /**
+     * Stable logical thread identity shared by fresh execution leases. Required
+     * from stores that advertise `supportsThreadContinuation`; optional for
+     * legacy/process-local stores that do not expose a durable conversation.
+     */
+    threadId?: string;
+    subagentType: string;
+    status: SubagentTaskStatus;
+    createdAt: number;
+    updatedAt: number;
+    resultAvailable: boolean;
+    resultClaimed: boolean;
+    pendingControls: number;
+    progress?: SubagentTaskProgress;
+    error?: string;
+}
+export type SubagentTaskClaim = {
+    status: 'running';
+    task: SubagentTaskSnapshot;
+} | {
+    status: 'completed';
+    task: SubagentTaskSnapshot;
+    result: string;
+} | {
+    status: 'error';
+    task: SubagentTaskSnapshot;
+    error: string;
+} | {
+    status: 'cancelled';
+    task: SubagentTaskSnapshot;
+    error: string;
+} | {
+    status: 'claimed';
+    task: SubagentTaskSnapshot;
+} | {
+    status: 'not_found';
+};
+export type SubagentTaskControlResult = {
+    status: 'accepted';
+    task: SubagentTaskSnapshot;
+    controlId?: string;
+} | {
+    status: 'cancelled';
+    task: SubagentTaskSnapshot;
+} | {
+    status: 'not_running';
+    task: SubagentTaskSnapshot;
+} | {
+    status: 'not_found';
+} | {
+    status: 'control_not_found';
+    task: SubagentTaskSnapshot;
+} | {
+    status: 'invalid';
+    message: string;
+};
+/**
+ * Child-side view supplied to one detached execution. It intentionally owns
+ * only cancellation, bounded message drains, and payload-free progress — no
+ * request/response object or host transport can leak into retained task state.
+ */
+export interface SubagentTaskRuntime {
+    readonly taskId: string;
+    readonly signal: AbortSignal;
+    shouldPreempt(): boolean;
+    drain(boundary: SubagentTaskBoundary): InjectedMessage[];
+    closeTurn(): {
+        closed: boolean;
+        messages: InjectedMessage[];
+    };
+    reportProgress(event: SubagentUpdateEvent): void;
+}
+export interface SubagentTaskStartRequest {
+    scopeId: string;
+    idempotencyKey: string;
+    /** Host/SDK-owned parent run identity for durable lineage. */
+    parentRunId: string;
+    /** Executing parent agent, when the graph has a stable agent identity. */
+    parentAgentId?: string;
+    /** Provider tool-call identity that created this execution lease. */
+    parentToolCallId: string;
+    /**
+     * Untrusted child-thread selector supplied by the parent model. A
+     * continuation-capable store MUST validate ownership, scope, lineage, and
+     * `subagentType` before loading any saved messages.
+     */
+    threadId?: string;
+    /** Untrusted new user-turn text for host persistence and audit. */
+    input: string;
+    /** Stable hash of model-writable inputs used to reject conflicting replays. */
+    requestFingerprint?: string;
+    /** Execution shape selected from the host-provided subagent catalog. */
+    subagentKind: SubagentUpdateEvent['subagentKind'];
+    subagentType: string;
+    /**
+     * Starts one ephemeral execution lease. The canonical child transcript is
+     * returned so a host-owned store may persist it for a later fresh run;
+     * retaining a graph/checkpoint after terminal completion is unnecessary.
+     */
+    run(runtime: SubagentTaskRuntime, initialMessages?: BaseMessage[]): Promise<{
+        content: string;
+        messages?: BaseMessage[];
+    }>;
+}
+export type SubagentTaskStartResult = {
+    accepted: true;
+    isNew: boolean;
+    task: SubagentTaskSnapshot;
+} | {
+    accepted: false;
+    reason: 'capacity';
+} | {
+    accepted: false;
+    reason: 'thread_unavailable';
+} | {
+    accepted: false;
+    reason: 'conflict';
+    task: SubagentTaskSnapshot;
+};
+/**
+ * Host-replaceable store contract used by the SDK's subagent tool. The store
+ * should normally outlive individual `Run` instances. Durable hosts may
+ * persist the transcript returned by `run` under the task/thread
+ * lineage and start a fresh execution for a later turn.
+ */
+export interface SubagentTaskStore {
+    /**
+     * True only when `start` authorizes an existing `threadId`, loads its
+     * saved transcript, and supplies that transcript to `run`. The flag exposes
+     * the model-facing continuation field, so a store must fail closed for an
+     * unknown or unauthorized id rather than starting an empty child.
+     */
+    readonly supportsThreadContinuation?: boolean;
+    start(request: SubagentTaskStartRequest): SubagentTaskStartResult;
+    get(scopeId: string, taskId: string): SubagentTaskSnapshot | undefined;
+    list(scopeId: string): SubagentTaskSnapshot[];
+    claim(scopeId: string, taskId: string): SubagentTaskClaim;
+    control(scopeId: string, taskId: string, command: SubagentTaskControlCommand): SubagentTaskControlResult;
+}
+/** Trusted, host-selected task namespace. It is never model-writable. */
+export interface SubagentTaskConfig {
+    store: SubagentTaskStore;
+    scopeId: string;
+}

package/package.json

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