@librechat/agents 3.6.4 → 3.6.6

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/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: {
@@ -34,6 +34,7 @@ export declare const SubagentToolDefinition: LCTool;
  */
 export declare function buildSubagentToolParams(configs: SubagentConfig[], options?: {
     background?: boolean;
+    threadContinuation?: boolean;
 }): {
     name: string;
     schema: JsonSchemaType;

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

@@ -12,6 +12,8 @@ export declare const DEFAULT_SUBAGENT_DESCRIPTION = "No task description provide
 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;
@@ -66,6 +68,8 @@ export type SubagentExecuteParams = {
     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;

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

@@ -615,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/subagentTasks.d.ts

@@ -24,8 +24,14 @@ export interface SubagentTaskProgress {
 }
 /** Read-only task metadata. Results are exposed only through `claim`. */
 export interface SubagentTaskSnapshot {
-    /** Handle for this child-conversation execution within its trusted scope. */
+    /** 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;
@@ -95,15 +101,31 @@ export interface SubagentTaskRuntime {
 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): Promise<{
+    run(runtime: SubagentTaskRuntime, initialMessages?: BaseMessage[]): Promise<{
         content: string;
         messages?: BaseMessage[];
     }>;
@@ -115,6 +137,9 @@ export type SubagentTaskStartResult = {
 } | {
     accepted: false;
     reason: 'capacity';
+} | {
+    accepted: false;
+    reason: 'thread_unavailable';
 } | {
     accepted: false;
     reason: 'conflict';
@@ -123,10 +148,17 @@ export type SubagentTaskStartResult = {
 /**
  * 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/conversation
+ * 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[];

package/package.json

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

package/src/graphs/Graph.ts

@@ -4854,6 +4854,7 @@ 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 =
@@ -4863,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. */
@@ -4905,12 +4911,27 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               | undefined,
           };
           if (input.run_in_background === true) {
-            return executor.executeInBackground(executeParams);
+            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, {
           background: this.subagentTasks != null,
+          threadContinuation:
+            this.subagentTasks?.store.supportsThreadContinuation === true,
         }));
         const replayableSubagentTool = subagentTool as typeof subagentTool &
           ReplayableSubagentTool;

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/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.
 
@@ -30,6 +30,9 @@ const SUBAGENT_TYPE_PROP_DESCRIPTION =
 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: {
@@ -59,7 +62,7 @@ export const SubagentToolDefinition: LCTool = {
  */
 export function buildSubagentToolParams(
   configs: SubagentConfig[],
-  options: { background?: boolean } = {}
+  options: { background?: boolean; threadContinuation?: boolean } = {}
 ): {
   name: string;
   schema: JsonSchemaType;
@@ -93,6 +96,15 @@ export function buildSubagentToolParams(
             },
           }
           : {}),
+        ...(options.background === true &&
+        options.threadContinuation === true
+          ? {
+            subagent_thread_id: {
+              type: 'string',
+              description: SUBAGENT_THREAD_PROP_DESCRIPTION,
+            },
+          }
+          : {}),
       },
       required: ['description', 'subagent_type'],
     },
@@ -100,6 +112,10 @@ export function buildSubagentToolParams(
       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}`,
   };
 }

package/src/tools/subagent/InMemorySubagentTaskStore.ts

@@ -50,6 +50,7 @@ type StoredTask = {
   idempotencyKey: string;
   requestFingerprint?: string;
   scopeId: string;
+  threadId: string;
   subagentType: string;
   status: SubagentTaskStatus;
   createdAt: number;
@@ -167,6 +168,7 @@ function toInjectedMessage(control: PendingControl): InjectedMessage {
 function snapshot(task: StoredTask): SubagentTaskSnapshot {
   return {
     taskId: task.id,
+    threadId: task.threadId,
     subagentType: task.subagentType,
     status: task.status,
     createdAt: task.createdAt,
@@ -251,13 +253,19 @@ export class InMemorySubagentTaskStore implements SubagentTaskStore {
       this.dropEmptyBucket(scopeId, bucket);
       return { accepted: false, reason: 'capacity' };
     }
+    const taskId = nanoid();
+    const requestedThreadId = request.threadId?.trim();
     const task: StoredTask = {
-      id: nanoid(),
+      id: taskId,
       idempotencyKey,
       ...(requestFingerprint == null || requestFingerprint === ''
         ? {}
         : { requestFingerprint }),
       scopeId,
+      threadId:
+        requestedThreadId != null && requestedThreadId !== ''
+          ? requestedThreadId
+          : taskId,
       subagentType: request.subagentType,
       status: 'running',
       createdAt: now,

package/src/tools/subagent/SubagentExecutor.ts

@@ -623,10 +623,17 @@ function getSettlementFingerprint(output: PersistedToolOutput): string {
 
 function getBackgroundTaskFingerprint(
   description: string,
-  subagentType: string
+  subagentType: string,
+  threadId?: string
 ): string {
   return createHash('sha256')
-    .update(stableStringify({ description, subagentType }))
+    .update(
+      stableStringify({
+        description,
+        subagentType,
+        ...(threadId == null || threadId === '' ? {} : { threadId }),
+      })
+    )
     .digest('hex');
 }
 
@@ -758,6 +765,8 @@ function createReplayCheckpointWorkflow(
 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;
@@ -812,6 +821,8 @@ export type SubagentExecuteParams = {
   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 = {
@@ -1071,6 +1082,19 @@ export class SubagentExecutor {
           'Background subagent execution requires a parent tool call ID.',
       });
     }
+    const subagentThreadId = params.subagentThreadId?.trim();
+    if (
+      subagentThreadId != null &&
+      subagentThreadId !== '' &&
+      this.taskConfig.store.supportsThreadContinuation !== true
+    ) {
+      return JSON.stringify({
+        status: 'rejected',
+        tool: Constants.SUBAGENT,
+        message:
+          'Child-thread continuation is not enabled by this host.',
+      });
+    }
     const detachedHandlers = new HandlerRegistry();
     const sourceHookSessionId =
       asNonEmptyString(params.parentConfigurable?.run_id) ??
@@ -1092,14 +1116,31 @@ export class SubagentExecutor {
         this.parentAgentId ?? '',
         parentToolCallId,
       ]),
+      parentRunId: this.parentRunId,
+      ...(this.parentAgentId == null
+        ? {}
+        : { parentAgentId: this.parentAgentId }),
+      parentToolCallId,
       requestFingerprint: getBackgroundTaskFingerprint(
         params.description,
-        params.subagentType
+        params.subagentType,
+        subagentThreadId
       ),
+      ...(subagentThreadId == null || subagentThreadId === ''
+        ? {}
+        : { threadId: subagentThreadId }),
+      input: params.description,
+      subagentKind:
+        'kind' in executableConfig && executableConfig.kind === 'graph'
+          ? 'graph'
+          : 'agent',
       subagentType: params.subagentType,
-      run: (runtime) =>
+      run: (runtime, initialMessages) =>
         this.executeDetached(
-          params,
+          {
+            ...params,
+            ...(initialMessages == null ? {} : { initialMessages }),
+          },
           runtime,
           detachedHandlers,
           taskHookRegistry,
@@ -1107,6 +1148,14 @@ export class SubagentExecutor {
         ),
     });
     if (!started.accepted) {
+      if (started.reason === 'thread_unavailable') {
+        return JSON.stringify({
+          status: 'rejected',
+          tool: Constants.SUBAGENT,
+          message:
+            'The requested subagent thread is unavailable in this parent scope. Start a new subagent thread or choose one created by this parent for the same subagent type.',
+        });
+      }
       if (started.reason === 'conflict') {
         return JSON.stringify({
           status: 'rejected',
@@ -1122,8 +1171,28 @@ export class SubagentExecutor {
           'Too many background subagent tasks are already running in this scope or process. Poll or cancel an existing task, or run this call in the foreground.',
       });
     }
+    const startedThreadId = started.task.threadId?.trim();
+    if (
+      this.taskConfig.store.supportsThreadContinuation === true &&
+      (startedThreadId == null || startedThreadId === '')
+    ) {
+      this.taskConfig.store.control(
+        this.taskConfig.scopeId,
+        started.task.taskId,
+        { action: 'cancel' }
+      );
+      return JSON.stringify({
+        status: 'rejected',
+        tool: Constants.SUBAGENT,
+        message:
+          'The host accepted the subagent task without assigning its required thread ID.',
+      });
+    }
     return JSON.stringify({
       background_task_id: started.task.taskId,
+      ...(this.taskConfig.store.supportsThreadContinuation === true
+        ? { subagent_thread_id: startedThreadId }
+        : {}),
       tool: Constants.SUBAGENT,
       subagent_type: params.subagentType,
       status: started.task.status,
@@ -2615,6 +2684,7 @@ export class SubagentExecutor {
         } else {
           childInput = {
             messages: [
+              ...(params.initialMessages ?? []),
               new HumanMessage({
                 content: description,
                 additional_kwargs: {

package/src/types/graph.ts

@@ -787,6 +787,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