@librechat/agents 3.8.5 → 3.8.7

package/src/tools/local/LocalProgrammaticToolCalling.ts

@@ -214,6 +214,7 @@ export async function applyPreToolUseHooksForBridge(
       runId: hookContext.runId,
       threadId: hookContext.threadId,
       agentId: hookContext.agentId,
+      executionContext: hookContext.executionContext,
       executingAgentId: hookContext.executingAgentId,
       toolName,
       toolInput,

package/src/tools/subagent/SubagentExecutionRegistry.ts

@@ -783,7 +783,6 @@ export class SubagentExecutionRecord<
     this.transitionTo('completed', ['active']);
     this.completedValue = true;
     this.completedResultValue = result;
-    this.resolvedConfigValue = undefined;
   }
 
   releaseActiveRun(): TActiveRun | undefined {

package/src/tools/subagent/SubagentExecutor.ts

@@ -52,6 +52,10 @@ import type {
   ResolvedSubagentConfig,
   ResolvedSubagentConfigEntry,
   SubagentExecutionContext,
+  SubagentContextAdapter,
+  SubagentContextInput,
+  SubagentContextResult,
+  PreparedSubagentContext,
   SubagentTaskConfig,
   SubagentTaskRuntime,
   SubagentResolveConfigurable,
@@ -88,11 +92,6 @@ import type {
   ToolApprovalReplaySnapshot,
 } from '@/hooks';
 import type { GraphFactory } from '@/graphs/graphFactory';
-import {
-  rebindToolBatchReplayScope,
-  rebindToolBatchReplayPayload,
-  restoreToolReplayConfig,
-} from '@/tools/toolBatchReplay';
 import type { StandardGraph } from '@/graphs/Graph';
 import {
   getSubagentApprovalExecutionScope,
@@ -108,6 +107,11 @@ import {
   SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY,
   SUBAGENT_RESUME_MANIFEST_CONFIG_KEY,
 } from './SubagentReplay';
+import {
+  rebindToolBatchReplayScope,
+  rebindToolBatchReplayPayload,
+  restoreToolReplayConfig,
+} from '@/tools/toolBatchReplay';
 import {
   executeHooks,
   HookRegistry,
@@ -138,6 +142,7 @@ import { stableStringify } from '@/tools/eagerEventExecution';
 import { convertInjectedMessages } from '@/messages/injected';
 import { resolveClientOptionsModel } from '@/llm/request';
 import { composeAbortSignals } from '@/utils/misc';
+import { sleep } from '@/utils/run';
 import { HandlerRegistry } from '@/events';
 
 export {
@@ -168,6 +173,31 @@ function seedChildGraphSessions(
   seedAgentInitialSessions(childGraph.sessions, agents);
 }
 
+async function awaitWithAbort<T>(
+  promise: Promise<T>,
+  signal: AbortSignal
+): Promise<T> {
+  signal.throwIfAborted();
+  let onAbort: (() => void) | undefined;
+  const aborted = new Promise<never>((_resolve, reject) => {
+    onAbort = (): void => {
+      reject(
+        signal.reason instanceof Error
+          ? signal.reason
+          : new Error('Detached subagent task cancelled.')
+      );
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+  try {
+    return await Promise.race([promise, aborted]);
+  } finally {
+    if (onAbort != null) {
+      signal.removeEventListener('abort', onAbort);
+    }
+  }
+}
+
 async function dispatchObservationalSubagentUpdate(
   handler: EventHandler,
   event: SubagentUpdateEvent
@@ -831,11 +861,11 @@ export type SubagentExecuteParams = {
   initialMessages?: BaseMessage[];
 };
 
-export type SubagentExecuteResult = {
-  content: string;
-  messages: BaseMessage[];
+export type SubagentExecuteResult = SubagentContextResult & {
   /** Tagged internal failure; foreground callers retain the legacy content. */
   error?: string;
+  /** Completed child work whose host projection must be retried without re-execution. */
+  retryableDelivery?: true;
 };
 
 function createSubagentFailure(
@@ -931,6 +961,7 @@ export type SubagentExecutorOptions = {
   usageSink?: SubagentUsageSink;
   /** Host-owned process-local task namespace for detached execution. */
   taskConfig?: SubagentTaskConfig;
+  subagentContext?: SubagentContextAdapter;
 };
 
 type DurableExecutionRecord = SubagentExecutionRecord<
@@ -968,6 +999,7 @@ export class SubagentExecutor {
   ) => GraphFactory;
   private readonly usageSink?: SubagentUsageSink;
   private readonly taskConfig?: SubagentTaskConfig;
+  private readonly subagentContext?: SubagentContextAdapter;
   private readonly executions: SubagentExecutionRegistry<
     SubagentExecuteResult,
     ResolvedSubagentConfig,
@@ -1012,6 +1044,7 @@ export class SubagentExecutor {
       options.createDetachedChildGraphFactory;
     this.usageSink = options.usageSink;
     this.taskConfig = options.taskConfig;
+    this.subagentContext = options.subagentContext;
     const rawRegistry = options.parentHandlerRegistry;
     if (typeof rawRegistry === 'function') {
       this.resolveParentHandlerRegistry = rawRegistry;
@@ -1257,6 +1290,7 @@ export class SubagentExecutor {
       langfuse: this.langfuse,
       tokenCounter: this.tokenCounter,
       usageSink: this.usageSink,
+      subagentContext: this.subagentContext,
       streamLimits: this.streamLimits,
       maxDepth: this.maxDepth,
       createChildGraph:
@@ -1268,21 +1302,38 @@ export class SubagentExecutor {
         detachedGraphFactory ?? this.createChildGraphByKind,
     });
     try {
-      const result = await detached.execute({
-        ...params,
-        signal: undefined,
-        breaker: undefined,
-        hookSessionId: taskHookSessionId,
-        taskRuntime: runtime,
-        parentConfigurable: {
-          ...params.parentConfigurable,
-          run_id: taskHookSessionId,
-        },
-      });
-      if (runtime.signal.aborted) {
-        throw runtime.signal.reason instanceof Error
-          ? runtime.signal.reason
-          : new Error('Detached subagent task cancelled.');
+      const executeAttempt = async (): Promise<SubagentExecuteResult> => {
+        const result = await detached.execute({
+          ...params,
+          signal: undefined,
+          breaker: undefined,
+          hookSessionId: taskHookSessionId,
+          taskRuntime: runtime,
+          parentConfigurable: {
+            ...params.parentConfigurable,
+            run_id: taskHookSessionId,
+          },
+        });
+        if (runtime.signal.aborted) {
+          throw runtime.signal.reason instanceof Error
+            ? runtime.signal.reason
+            : new Error('Detached subagent task cancelled.');
+        }
+        return result;
+      };
+      let deliveryAttempts = 1;
+      let result = await executeAttempt();
+      while (
+        result.retryableDelivery === true &&
+        deliveryAttempts < 3
+      ) {
+        if (deliveryAttempts > 1) {
+          await sleep(
+            Math.min(100 * 2 ** Math.min(deliveryAttempts - 2, 6), 5_000)
+          );
+        }
+        deliveryAttempts += 1;
+        result = await executeAttempt();
       }
       if (result.error != null) {
         throw new Error(result.error);
@@ -1454,7 +1505,10 @@ export class SubagentExecutor {
         resumeExecution.checkpoints,
         branchChildThreadId,
         lease,
-        { source: resumeExecution.approvalExecutionScope, target: approvalExecutionScope }
+        {
+          source: resumeExecution.approvalExecutionScope,
+          target: approvalExecutionScope,
+        }
       );
       let previousApprovals: ToolApprovalReplaySnapshot[] = [];
       let approvalsMutated = false;
@@ -1765,14 +1819,20 @@ export class SubagentExecutor {
           }
           /** Repeated unconsumed forks must persist their current owner. */
           const reboundValue =
-            channel === INTERRUPT && approvalScope != null &&
-            value != null && typeof value === 'object' && 'value' in value
-              ? { ...value, value: rebindToolBatchReplayPayload(
-                value.value,
-                approvalScope.source,
-                approvalScope.target,
-                targetThreadId
-              ) }
+            channel === INTERRUPT &&
+            approvalScope != null &&
+            value != null &&
+            typeof value === 'object' &&
+            'value' in value
+              ? {
+                ...value,
+                value: rebindToolBatchReplayPayload(
+                  value.value,
+                  approvalScope.source,
+                  approvalScope.target,
+                  targetThreadId
+                ),
+              }
               : value;
           writes.push([channel, reboundValue]);
         }
@@ -2117,6 +2177,9 @@ export class SubagentExecutor {
     ) {
       return;
     }
+    if (settled.output.status === 'error' && config.signal?.aborted === true) {
+      return;
+    }
     const parentConfigurable = config.configurable as
       | Record<string, unknown>
       | undefined;
@@ -2126,6 +2189,9 @@ export class SubagentExecutor {
       parentToolCallId,
       parentConfigurable,
     });
+    if (execution.completedResult != null && settled.output.status === 'error') {
+      return;
+    }
     const { resumeExecution } = execution;
     const resolvedSubagentType = getSubagentTypeFromArgs(settled.resolvedArgs);
     const resolvedDescription = getSubagentDescriptionFromArgs(
@@ -2386,11 +2452,6 @@ export class SubagentExecutor {
     if (!bound) {
       return createSubagentFailure(SUBAGENT_CONFIG_CHANGED_MESSAGE);
     }
-    const completedChildResult = execution.completedResult;
-    if (completedChildResult != null) {
-      return completedChildResult;
-    }
-
     let config: ResolvedSubagentConfigEntry;
     try {
       config = await this.resolveExecutionConfig(executableConfig, execution, {
@@ -2450,6 +2511,63 @@ export class SubagentExecutor {
         },
       ],
     };
+    const hostContextInput: SubagentContextInput = {
+      executionContext: childExecutionContext,
+      parentThreadId: threadId,
+      memberAgentIds: childPlan.agents.map((agent) => agent.agentId),
+      signal: childSignal,
+      resumed: execution.started || resumeExecution != null,
+    };
+    let preparedContext: PreparedSubagentContext | undefined;
+    try {
+      preparedContext =
+        this.subagentContext?.prepare == null
+          ? undefined
+          : await awaitWithAbort(
+            Promise.resolve(this.subagentContext.prepare(hostContextInput)),
+            childSignal
+          );
+      execution.assertUsable(childSignal);
+      for (const [agentId, sessions] of Object.entries(
+        preparedContext?.agentSessions ?? {}
+      )) {
+        const member = childPlan.memberInputs.get(agentId);
+        if (member == null) throw new Error('Unknown subagent context member.');
+        const activeMember =
+          execution.activeRun?.graph.agentContexts.get(agentId);
+        if (
+          activeMember != null &&
+          activeMember.codeSessionKey !== sessions.codeSessionKey
+        ) {
+          throw new Error(
+            'Subagent session partition changed during execution.'
+          );
+        }
+        member.codeSessionKey = sessions.codeSessionKey;
+        member.initialSessions = sessions.initialSessions;
+      }
+    } catch (error) {
+      if (childSignal.aborted) {
+        throw childSignal.reason instanceof Error
+          ? childSignal.reason
+          : error;
+      }
+      if (execution.completedResult != null) {
+        return {
+          ...createSubagentFailure(
+            'Subagent context is unavailable or access was denied.'
+          ),
+          retryableDelivery: true,
+        };
+      }
+      return createSubagentFailure(
+        'Subagent context is unavailable or access was denied.'
+      );
+    }
+    const completedChildResult = execution.completedResult;
+    if (completedChildResult != null) {
+      return this.completeHostContext(hostContextInput, completedChildResult);
+    }
     const maxTurns = config.maxTurns ?? DEFAULT_SUBAGENT_MAX_TURNS;
     const memberRecursionLimit = maxTurns * SUBAGENT_RECURSION_MULTIPLIER;
     const recursionLimit =
@@ -2476,6 +2594,7 @@ export class SubagentExecutor {
       streamLimits: this.streamLimits,
       subagentScope: true,
       subagentExecutionContext: childExecutionContext,
+      subagentContext: this.subagentContext,
       ...(resumeExecution?.graphState.fadingTier == null
         ? {}
         : { fadingTier: resumeExecution.graphState.fadingTier }),
@@ -2522,9 +2641,7 @@ export class SubagentExecutor {
     if (params.taskRuntime != null) {
       childGraph.hookRegistry = this.hookRegistry;
     }
-    if (cachedChildRun == null) {
-      seedChildGraphSessions(childGraph, childPlan.agents);
-    }
+    seedChildGraphSessions(childGraph, childPlan.agents);
     let forwarding: ForwarderCallback | undefined;
     if (forwardingEnabled) {
       forwarding = this.createForwarderCallback({
@@ -2626,6 +2743,8 @@ export class SubagentExecutor {
       }
       const childConfigurable: Record<string, unknown> = {
         ...inheritedConfigurable,
+        ...sanitizePreparedConfigurable(preparedContext?.configurable),
+        executionContext: childExecutionContext,
       };
       if (this.humanInTheLoop?.enabled === true) {
         childConfigurable[TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY] =
@@ -2666,16 +2785,18 @@ export class SubagentExecutor {
         }
         const persistedInterrupts = getPersistedInterrupts(persistedState);
         if (persistedInterrupts.length > 0) {
-          activeChildRun.pendingInterrupts = resumeExecution == null ? persistedInterrupts :
-            persistedInterrupts.map((pending) => ({
-              ...pending,
-              value: rebindToolBatchReplayPayload(
-                pending.value,
-                resumeExecution.approvalExecutionScope,
-                approvalExecutionScope,
-                childThreadId
-              ),
-            }));
+          activeChildRun.pendingInterrupts =
+            resumeExecution == null
+              ? persistedInterrupts
+              : persistedInterrupts.map((pending) => ({
+                ...pending,
+                value: rebindToolBatchReplayPayload(
+                  pending.value,
+                  resumeExecution.approvalExecutionScope,
+                  approvalExecutionScope,
+                  childThreadId
+                ),
+              }));
           execution.markStarted();
           childAlreadyStarted = true;
         } else if (persistedState.next.length > 0) {
@@ -2710,9 +2831,12 @@ export class SubagentExecutor {
         }
         let childInput: BaseGraphState | Command | null;
         if (childResumeMap != null) {
-          const pending = activeChildRun.pendingInterrupts.find((entry) =>
-            entry.id != null && Object.prototype.hasOwnProperty.call(childResumeMap, entry.id)
-          ) ?? activeChildRun.pendingInterrupts[0];
+          const pending =
+            activeChildRun.pendingInterrupts.find(
+              (entry) =>
+                entry.id != null &&
+                Object.prototype.hasOwnProperty.call(childResumeMap, entry.id)
+            ) ?? activeChildRun.pendingInterrupts[0];
           restoreToolReplayConfig(childConfigurable, pending.id, pending.value);
           rebindToolBatchReplayScope(
             childConfigurable,
@@ -2734,6 +2858,7 @@ export class SubagentExecutor {
                   [SUBAGENT_RUN_ID_KEY]: childRunId,
                 },
               }),
+              ...(preparedContext?.messages ?? []),
             ],
           };
         }
@@ -2749,6 +2874,7 @@ export class SubagentExecutor {
             registry: this.hookRegistry,
             input: {
               hook_event_name: 'SubagentStart',
+              executionContext: childExecutionContext,
               runId: currentHookSessionId,
               threadId,
               parentAgentId: this.parentAgentId,
@@ -2955,6 +3081,7 @@ export class SubagentExecutor {
         registry: this.hookRegistry,
         input: {
           hook_event_name: 'SubagentStop',
+          executionContext: childExecutionContext,
           runId: currentHookSessionId,
           threadId,
           agentId: childAgentId,
@@ -2997,12 +3124,33 @@ export class SubagentExecutor {
 
     this.clearChildGraph(childGraph);
 
-    const completedResult = {
+    const completedResult: SubagentExecuteResult = {
       content: filteredContent,
       messages: result.messages,
     };
     execution.markCompleted(completedResult);
-    return completedResult;
+    return this.completeHostContext(hostContextInput, completedResult);
+  }
+
+  private async completeHostContext(
+    input: SubagentContextInput,
+    result: SubagentExecuteResult
+  ): Promise<SubagentExecuteResult> {
+    if (this.subagentContext?.complete == null) return result;
+    try {
+      input.signal.throwIfAborted();
+      const completed = await awaitWithAbort(
+        this.subagentContext.complete(input, result),
+        input.signal
+      );
+      input.signal.throwIfAborted();
+      return { ...result, content: completed.content };
+    } catch {
+      return {
+        ...createSubagentFailure('Subagent result delivery failed.'),
+        retryableDelivery: true,
+      };
+    }
   }
 
   /**
@@ -3535,6 +3683,17 @@ function sanitizeChildConfigurable(
   );
 }
 
+function sanitizePreparedConfigurable(
+  configurable: RunnableConfig['configurable']
+): Record<string, unknown> {
+  const prepared = sanitizeChildConfigurable(configurable);
+  delete prepared.run_id;
+  delete prepared.parent_run_id;
+  delete prepared.thread_id;
+  delete prepared.executionContext;
+  return prepared;
+}
+
 function isLangGraphRuntimeConfigKey(key: string): boolean {
   return (
     key.startsWith(LANGGRAPH_RUNTIME_CONFIG_PREFIX) ||

package/src/tools/toolBatchReplay.ts

@@ -32,6 +32,8 @@ export interface SettledToolBatchResult {
   output: BaseMessage | Command;
   additionalContexts: string[];
   resolvedArgs?: Record<string, unknown>;
+  /** Code-session identities injected into this completed direct call. */
+  codeSessionBaseline?: Array<[string, string]>;
   completionHandled?: boolean;
   referenceContent?: string;
   turn?: number;
@@ -474,6 +476,14 @@ export async function restoreToolBatchReplayState(
               throw new Error('Invalid settled tool batch results');
             }
             const result = entry[1] as Partial<SettledToolBatchResult> | null;
+            const codeSessionBaseline: unknown = (
+              result as { codeSessionBaseline?: unknown } | null
+            )?.codeSessionBaseline;
+            const baselineNames = Array.isArray(codeSessionBaseline)
+              ? codeSessionBaseline.map((pair) =>
+                Array.isArray(pair) ? pair[0] : undefined
+              )
+              : [];
             if (
               result == null ||
               (!isBaseMessage(result.output) && !isCommand(result.output)) ||
@@ -491,7 +501,19 @@ export async function restoreToolBatchReplayState(
               typeof result.proposal.name !== 'string' ||
               result.proposal.name.length === 0 ||
               !isRecord(result.proposal.args) ||
-              (result.resolvedArgs != null && !isRecord(result.resolvedArgs))
+              (result.resolvedArgs != null && !isRecord(result.resolvedArgs)) ||
+              (codeSessionBaseline != null &&
+                (!Array.isArray(codeSessionBaseline) ||
+                  codeSessionBaseline.some(
+                    (pair) =>
+                      !Array.isArray(pair) ||
+                      pair.length !== 2 ||
+                      typeof pair[0] !== 'string' ||
+                      pair[0].length === 0 ||
+                      typeof pair[1] !== 'string' ||
+                      pair[1].length === 0
+                  ) ||
+                  new Set(baselineNames).size !== baselineNames.length))
             ) {
               throw new Error('Invalid settled tool batch results');
             }

package/src/types/graph.ts

@@ -395,6 +395,8 @@ export type StandardGraphInput = {
    * do not inherit it, keeping background nesting disabled for the MVP.
    */
   subagentTasks?: SubagentTaskConfig;
+  /** Host-owned context and result projection for each isolated child execution. */
+  subagentContext?: SubagentContextAdapter;
   /**
    * True when this graph IS a subagent child run (set by `SubagentExecutor`
    * when it constructs the child graph). Drives the hook-input `agentId`
@@ -669,6 +671,41 @@ export interface SubagentExecutionContext {
   readonly ancestry: readonly SubagentAncestryEntry[];
 }
 
+/** Trusted identity supplied before a child can access host-owned resources. */
+export interface SubagentContextInput {
+  executionContext: SubagentExecutionContext;
+  parentThreadId?: string;
+  memberAgentIds: readonly string[];
+  signal: AbortSignal;
+  resumed: boolean;
+}
+
+export interface PreparedSubagentContext {
+  /** Added to the initial child input; checkpoint recovery does not add them again. */
+  messages?: BaseMessage[];
+  /** Host configuration; SDK execution and checkpoint identities remain authoritative. */
+  configurable?: RunnableConfig['configurable'];
+  /** Each entry replaces that member's inherited code partition and initial sessions. */
+  agentSessions?: Readonly<
+    Record<string, Pick<AgentInputs, 'codeSessionKey' | 'initialSessions'>>
+  >;
+}
+
+export interface SubagentContextResult {
+  content: string;
+  messages: BaseMessage[];
+}
+
+export interface SubagentContextAdapter {
+  /** Reauthorizes reconstructed executions; durable work must be idempotent by child run ID. */
+  prepare(input: SubagentContextInput): Promise<PreparedSubagentContext>;
+  /** Projects durable references into the result returned to the parent. */
+  complete?(
+    input: SubagentContextInput,
+    result: SubagentContextResult
+  ): Promise<Pick<SubagentContextResult, 'content'>>;
+}
+
 /**
  * Wrapper event emitted when a subagent's child graph dispatches activity.
  * Lets hosts show subagent progress in a UI surface separate from the parent

package/src/types/run.ts

@@ -291,6 +291,8 @@ export type RunConfig = {
    * Omit to preserve foreground-only subagent behavior.
    */
   subagentTasks?: SubagentTaskConfig;
+  /** Authorizes and supplies host-owned context to isolated child runs. */
+  subagentContext?: g.SubagentContextAdapter;
   /**
    * Pre-constructed hook registry for this run. Hooks fire at lifecycle
    * points in `processStream` (RunStart, UserPromptSubmit, Stop,