@librechat/agents 4.0.2 → 4.0.3

package/src/tools/ToolNode.ts

@@ -130,6 +130,7 @@ import {
 } from '@/tools/local';
 import { stripCodeSessionFileSummary } from '@/tools/CodeSessionFileSummary';
 import { Constants, GraphEvents, CODE_EXECUTION_TOOLS } from '@/common';
+import { ProviderTextProtectionError } from '@/protection/providerText';
 import { formatToolErrorContent } from '@/tools/toolErrorContent';
 import { PreparedSubagentError } from '@/tools/preparedSubagents';
 import { attachRunStepResumeState } from '@/tools/runStepResume';
@@ -2146,7 +2147,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
        */
       if (
         e instanceof StreamLimitExceededError ||
-        e instanceof PreparedSubagentError
+        e instanceof PreparedSubagentError ||
+        e instanceof ProviderTextProtectionError
       ) {
         throw e;
       }
@@ -3486,7 +3488,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     if (
       signal?.aborted === true &&
       (signal.reason instanceof StreamLimitExceededError ||
-        signal.reason instanceof PreparedSubagentError)
+        signal.reason instanceof PreparedSubagentError ||
+        signal.reason instanceof ProviderTextProtectionError)
     ) {
       throw signal.reason;
     }
@@ -5467,7 +5470,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     if (
       composedSignal?.aborted === true &&
       (composedSignal.reason instanceof StreamLimitExceededError ||
-        composedSignal.reason instanceof PreparedSubagentError)
+        composedSignal.reason instanceof PreparedSubagentError ||
+        composedSignal.reason instanceof ProviderTextProtectionError)
     ) {
       throw composedSignal.reason;
     }

package/src/tools/subagent/SubagentExecutionRegistry.ts

@@ -63,6 +63,8 @@ export type SubagentInvocationBinding = Readonly<{
   description: string;
   subagentType: string;
   configId?: string;
+  /** Value-free identity of the call's validated host arguments. */
+  hostArgsDigest?: string;
 }>;
 
 export type SubagentSettlementBinding = Readonly<{
@@ -340,7 +342,8 @@ function assertCompatibleResumeExecution(
     current.parentToolCallId === next.parentToolCallId &&
     current.childRunId === next.childRunId &&
     current.subagentType === next.subagentType &&
-    current.configId === next.configId
+    current.configId === next.configId &&
+    current.hostArgsDigest === next.hostArgsDigest
   ) {
     return;
   }
@@ -354,7 +357,8 @@ function assertSameInvocation(
   if (
     current.description === next.description &&
     current.subagentType === next.subagentType &&
-    current.configId === next.configId
+    current.configId === next.configId &&
+    current.hostArgsDigest === next.hostArgsDigest
   ) {
     return;
   }

package/src/tools/subagent/SubagentExecutor.ts

@@ -60,6 +60,7 @@ import type {
   SubagentTaskConfig,
   SubagentTaskRuntime,
   SubagentResolveConfigurable,
+  SubagentHostArgs,
   SubagentResolveRequestContext,
   SubagentResolveUserContext,
   StepCompleted,
@@ -80,6 +81,12 @@ import type {
   SubagentExecutionPreparationLease,
   SubagentExecutionRecord,
 } from './SubagentExecutionRegistry';
+import type {
+  SubagentResolutionPhase,
+  SubagentResolutionCause,
+  SubagentHostArgumentFailure,
+  SubagentResolutionFailureHandler,
+} from './diagnostics';
 import type {
   SubagentResumeExecution,
   SubagentResumeManifest,
@@ -92,11 +99,6 @@ import type {
   PreemptBoundaryHookOutput,
   ToolApprovalReplaySnapshot,
 } from '@/hooks';
-import type {
-  SubagentResolutionPhase,
-  SubagentResolutionCause,
-  SubagentResolutionFailureHandler,
-} from './diagnostics';
 import type { RunBreakerScope } from '@/llm/streamLimits';
 import type { GraphFactory } from '@/graphs/graphFactory';
 import type { StandardGraph } from '@/graphs/Graph';
@@ -114,6 +116,18 @@ import {
   SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY,
   SUBAGENT_RESUME_MANIFEST_CONFIG_KEY,
 } from './SubagentReplay';
+import {
+  logSubagentResolutionFailure,
+  SubagentResolutionError,
+  getSubagentHostArgumentFailure,
+  getSubagentHostArgumentFailureMessage,
+} from './diagnostics';
+import {
+  getSubagentHostArgSpecs,
+  resolveSubagentHostArgs,
+  pickSubagentHostArgInput,
+  getSubagentHostArgsDigest,
+} from './hostArgs';
 import {
   rebindToolBatchReplayScope,
   rebindToolBatchReplayPayload,
@@ -132,10 +146,6 @@ import {
   DEFAULT_SUBAGENT_MAX_TURNS,
   SUBAGENT_RECURSION_MULTIPLIER,
 } from './runtimeLimits';
-import {
-  logSubagentResolutionFailure,
-  SubagentResolutionError,
-} from './diagnostics';
 import {
   ContentTypes,
   Constants,
@@ -147,6 +157,7 @@ import {
   createChildGraphPlan,
   isGraphSubagentConfig,
 } from './childGraphConfig';
+import { ProviderTextProtectionError } from '@/protection/providerText';
 import { stripRunStepResumeState } from '@/tools/runStepResume';
 import { seedAgentInitialSessions } from '@/utils/toolSessions';
 import { stableStringify } from '@/tools/eagerEventExecution';
@@ -178,7 +189,11 @@ const SUBAGENT_INVOCATION_CHANGED_MESSAGE =
 
 function isSubagentResolutionControlFlow(error: unknown): boolean {
   try {
-    return error instanceof StreamLimitExceededError || isGraphInterrupt(error);
+    return (
+      error instanceof StreamLimitExceededError ||
+      error instanceof ProviderTextProtectionError ||
+      isGraphInterrupt(error)
+    );
   } catch {
     return false;
   }
@@ -678,7 +693,8 @@ function getSettlementFingerprint(output: PersistedToolOutput): string {
 function getBackgroundTaskFingerprint(
   description: string,
   subagentType: string,
-  threadId?: string
+  threadId?: string,
+  hostArgsDigest?: string
 ): string {
   return createHash('sha256')
     .update(
@@ -686,11 +702,29 @@ function getBackgroundTaskFingerprint(
         description,
         subagentType,
         ...(threadId == null || threadId === '' ? {} : { threadId }),
+        ...(hostArgsDigest == null ? {} : { hostArgsDigest }),
       })
     )
     .digest('hex');
 }
 
+/** Host-argument digest of persisted lifecycle args, when they are well formed. */
+function getHostArgsDigestFromArgs(
+  config: ExecutableSubagentConfigEntry | undefined,
+  args: unknown
+): string | undefined {
+  if (config == null || !isObjectLike(args)) {
+    return undefined;
+  }
+  const names = new Set(getSubagentHostArgSpecs(config).map(([name]) => name));
+  const picked = pickSubagentHostArgInput(args, names);
+  if (!picked.ok) {
+    return undefined;
+  }
+  const resolved = resolveSubagentHostArgs(config, picked.hostArgs);
+  return resolved.ok ? getSubagentHostArgsDigest(resolved.hostArgs) : undefined;
+}
+
 function getBackgroundTaskHookSessionId(
   sourceHookSessionId: string,
   taskId: string
@@ -877,6 +911,11 @@ export type SubagentExecuteParams = {
   taskRuntime?: SubagentTaskRuntime;
   /** Host-restored child transcript for a fresh continuation run. @internal */
   initialMessages?: BaseMessage[];
+  /**
+   * Values for the selected subagent's declared `hostArgs`. Checked against
+   * the declaration before an execution opens, then bound to it.
+   */
+  hostArgs?: SubagentHostArgs;
 };
 
 export type SubagentExecuteResult = SubagentContextResult & {
@@ -886,6 +925,7 @@ export type SubagentExecuteResult = SubagentContextResult & {
   resolutionFailure?: {
     phase: SubagentResolutionPhase;
     cause: SubagentResolutionCause;
+    hostArgument?: SubagentHostArgumentFailure;
   };
   /** Completed child work whose host projection must be retried without re-execution. */
   retryableDelivery?: true;
@@ -957,6 +997,7 @@ export type SubagentExecutorOptions = {
    * graph's own resolved limits; without this the child would silently
    * revert to the defaults.
    */
+  providerTextProtection?: StandardGraphInput['providerTextProtection'];
   streamLimits?: StandardGraphInput['streamLimits'];
   humanInTheLoop?: HumanInTheLoopConfig;
   /** Shared durable saver used to recover outer tool lifecycle results before
@@ -1034,6 +1075,7 @@ export class SubagentExecutor {
   private readonly executionContext: SubagentExecutionContext;
   private readonly langfuse?: StandardGraphInput['langfuse'];
   private readonly tokenCounter?: TokenCounter;
+  private readonly providerTextProtection?: StandardGraphInput['providerTextProtection'];
   private readonly streamLimits?: StandardGraphInput['streamLimits'];
   private readonly humanInTheLoop?: HumanInTheLoopConfig;
   private readonly checkpointer?: BaseCheckpointSaver;
@@ -1074,6 +1116,7 @@ export class SubagentExecutor {
     this.langfuse = options.langfuse;
     this.tokenCounter = options.tokenCounter;
     this.streamLimits = options.streamLimits;
+    this.providerTextProtection = options.providerTextProtection;
     this.humanInTheLoop = options.humanInTheLoop;
     this.checkpointer = isCheckpointSaver(options.checkpointer)
       ? options.checkpointer
@@ -1148,6 +1191,18 @@ export class SubagentExecutor {
         message: `Unknown subagent type "${params.subagentType}".`,
       });
     }
+    const hostArgResult = resolveSubagentHostArgs(
+      executableConfig,
+      params.hostArgs
+    );
+    if (!hostArgResult.ok) {
+      return JSON.stringify({
+        status: 'rejected',
+        tool: Constants.SUBAGENT,
+        message: hostArgResult.message,
+      });
+    }
+    const { hostArgs } = hostArgResult;
     if (this.maxDepth <= 0) {
       return JSON.stringify({
         status: 'rejected',
@@ -1213,7 +1268,8 @@ export class SubagentExecutor {
       requestFingerprint: getBackgroundTaskFingerprint(
         params.description,
         params.subagentType,
-        subagentThreadId
+        subagentThreadId,
+        getSubagentHostArgsDigest(hostArgs)
       ),
       ...(subagentThreadId == null || subagentThreadId === ''
         ? {}
@@ -1228,6 +1284,7 @@ export class SubagentExecutor {
         this.executeDetached(
           {
             ...params,
+            hostArgs,
             ...(initialMessages == null ? {} : { initialMessages }),
           },
           runtime,
@@ -1344,6 +1401,7 @@ export class SubagentExecutor {
       subagentContext: this.subagentContext,
       onResolutionFailure: this.onResolutionFailure,
       streamLimits: this.streamLimits,
+      providerTextProtection: this.providerTextProtection,
       humanInTheLoop:
         this.humanInTheLoop?.enabled === true ||
         this.humanInTheLoop?.backgroundPausePolicy === 'deny'
@@ -1397,7 +1455,8 @@ export class SubagentExecutor {
         if (result.resolutionFailure != null) {
           throw new SubagentResolutionError(
             result.resolutionFailure.phase,
-            result.resolutionFailure.cause
+            result.resolutionFailure.cause,
+            result.resolutionFailure.hostArgument
           );
         }
         throw new Error(result.error);
@@ -1461,6 +1520,7 @@ export class SubagentExecutor {
       threadId?: string;
       parentToolCallId?: string;
       parentConfigurable?: Record<string, unknown>;
+      hostArgs?: SubagentHostArgs;
     }
   ): Promise<ResolvedSubagentConfigEntry> {
     if (isGraphSubagentConfig(config) || config.agentInputs != null) {
@@ -1489,6 +1549,9 @@ export class SubagentExecutor {
                 context.parentConfigurable == null
                   ? undefined
                   : sanitizeResolverConfigurable(context.parentConfigurable),
+              ...(context.hostArgs == null
+                ? {}
+                : { hostArgs: context.hostArgs }),
             }),
           context.childSignal
         ).then(
@@ -1937,7 +2000,7 @@ export class SubagentExecutor {
     }
     const executions: SubagentResumeExecution[] = [];
     for (const record of records) {
-      const { identity, binding, activeRun } = record.snapshot;
+      const { identity, binding, invocation, activeRun } = record.snapshot;
       if (identity == null) {
         continue;
       }
@@ -1981,6 +2044,9 @@ export class SubagentExecutor {
           ? {}
           : { subagentType: binding.subagentType }),
         ...(binding?.configId == null ? {} : { configId: binding.configId }),
+        ...(invocation?.hostArgsDigest == null
+          ? {}
+          : { hostArgsDigest: invocation.hostArgsDigest }),
         approvalExecutionScope: identity.approvalExecutionScope,
         checkpoints,
         graphState,
@@ -2333,6 +2399,22 @@ export class SubagentExecutor {
     ) {
       return;
     }
+    const resolvedHostArgsDigest =
+      settled.resolvedArgs == null
+        ? undefined
+        : getHostArgsDigestFromArgs(
+          this.configs.get(
+            resolvedSubagentType ?? execution.binding?.subagentType ?? ''
+          ),
+          settled.resolvedArgs
+        );
+    if (
+      boundInvocation != null &&
+      settled.resolvedArgs != null &&
+      resolvedHostArgsDigest !== boundInvocation.hostArgsDigest
+    ) {
+      return;
+    }
     const description =
       boundInvocation?.description ??
       resolvedDescription ??
@@ -2364,10 +2446,15 @@ export class SubagentExecutor {
       return;
     }
     const persistedOutput = serializeToolOutput(settled);
+    const hostArgsDigest =
+      settled.resolvedArgs == null
+        ? getHostArgsDigestFromArgs(executableConfig, call.args)
+        : resolvedHostArgsDigest;
     const invocation = boundInvocation ?? {
       description,
       subagentType,
       ...(configId == null ? {} : { configId }),
+      ...(hostArgsDigest == null ? {} : { hostArgsDigest }),
     };
     try {
       await execution.settle(
@@ -2484,6 +2571,15 @@ export class SubagentExecutor {
         )
       );
     }
+    const hostArgResult = resolveSubagentHostArgs(
+      executableConfig,
+      params.hostArgs
+    );
+    if (!hostArgResult.ok) {
+      return Promise.resolve(createSubagentFailure(hostArgResult.message));
+    }
+    const { hostArgs } = hostArgResult;
+    const hostArgsDigest = getSubagentHostArgsDigest(hostArgs);
     if (this.maxDepth <= 0) {
       return Promise.resolve(
         createSubagentFailure('Error: Maximum subagent nesting depth exceeded.')
@@ -2522,8 +2618,10 @@ export class SubagentExecutor {
           ...(executableConfig.configId == null
             ? {}
             : { configId: executableConfig.configId }),
+          ...(hostArgsDigest == null ? {} : { hostArgsDigest }),
         },
-        () => this.executeOnce(params, execution, executableConfig)
+        () =>
+          this.executeOnce({ ...params, hostArgs }, execution, executableConfig)
       );
     } catch (error) {
       if (error instanceof SubagentDefinitionBindingError) {
@@ -2616,8 +2714,21 @@ export class SubagentExecutor {
             : execution.address.branchChildThreadId),
         taskId: params.taskRuntime?.taskId,
       },
-      this.onResolutionFailure
+      this.onResolutionFailure,
+      params.hostArgs
     );
+    const hostArgument =
+      phase === 'config'
+        ? getSubagentHostArgumentFailure(error, params.hostArgs)
+        : undefined;
+    if (hostArgument != null) {
+      return {
+        ...createSubagentFailure(
+          getSubagentHostArgumentFailureMessage(hostArgument)
+        ),
+        resolutionFailure: { phase, cause: detail.cause, hostArgument },
+      };
+    }
     return {
       ...createSubagentFailure(detail.message),
       resolutionFailure: { phase, cause: detail.cause },
@@ -2652,6 +2763,14 @@ export class SubagentExecutor {
       this.executions.remove(execution);
       return createSubagentFailure(SUBAGENT_CONFIG_CHANGED_MESSAGE);
     }
+    if (
+      resumeExecution != null &&
+      resumeExecution.hostArgsDigest !==
+        getSubagentHostArgsDigest(params.hostArgs)
+    ) {
+      this.executions.remove(execution);
+      return createSubagentFailure(SUBAGENT_INVOCATION_CHANGED_MESSAGE);
+    }
     let identity: SubagentExecutionIdentity;
     try {
       identity = await this.resolveChildExecutionIdentity(execution);
@@ -2690,6 +2809,7 @@ export class SubagentExecutor {
         threadId,
         parentToolCallId,
         parentConfigurable: params.parentConfigurable,
+        hostArgs: params.hostArgs,
       });
       execution.assertUsable(childSignal);
     } catch (error) {
@@ -2831,6 +2951,7 @@ export class SubagentExecutor {
       langfuse: this.langfuse,
       tokenCounter: this.tokenCounter,
       streamLimits: this.streamLimits,
+      providerTextProtection: this.providerTextProtection,
       subagentScope: true,
       subagentExecutionContext: childExecutionContext,
       subagentContext: this.subagentContext,
@@ -3277,7 +3398,10 @@ export class SubagentExecutor {
        * quota for that entire interval. Trips the ENTRY-captured controller:
        * after a reset, a straggler must break its own dead run, not the
        * current one. */
-      if (error instanceof StreamLimitExceededError) {
+      if (
+        error instanceof StreamLimitExceededError ||
+        error instanceof ProviderTextProtectionError
+      ) {
         childBreaker.abort(error);
       }
       const errorMessage = truncateErrorMessage(error);
@@ -3316,7 +3440,10 @@ export class SubagentExecutor {
        * fired. Rethrown here and passed through ToolNode's error conversion,
        * so the parent run rejects with the child's limit error.
        */
-      if (error instanceof StreamLimitExceededError) {
+      if (
+        error instanceof StreamLimitExceededError ||
+        error instanceof ProviderTextProtectionError
+      ) {
         throw error;
       }
       return createSubagentFailure(

package/src/tools/subagent/SubagentReplay.ts

@@ -1,20 +1,20 @@
 import type { ToolCall, ToolMessage } from '@langchain/core/messages/tool';
 import type { RunnableConfig } from '@langchain/core/runnables';
-import type { ToolOutputReferenceState } from '@/tools/toolOutputReferences';
-import type { ToolApprovalReplaySnapshot } from '@/hooks';
 import type {
   FadingTier,
   FadingTiers,
   RunStepResumeState,
   ToolSessionContext,
 } from '@/types';
-import { isFadingTier, isLegacyFadingTier } from '@/messages/fading';
+import type { ToolOutputReferenceState } from '@/tools/toolOutputReferences';
+import type { ToolApprovalReplaySnapshot } from '@/hooks';
 import {
   attachRunStepResumeState,
   getRunStepResumeState,
   isRunStepResumeState,
   stripRunStepResumeState,
 } from '@/tools/runStepResume';
+import { isFadingTier, isLegacyFadingTier } from '@/messages/fading';
 
 export const SUBAGENT_RESUME_MANIFEST_CONFIG_KEY =
   '__librechat_subagent_resume_manifest';
@@ -35,6 +35,7 @@ const SUBAGENT_RESUME_PRIVATE_PAYLOAD_KEYS = [
   SUBAGENT_RESUME_WRAPPER_VERSION_KEY,
 ] as const;
 const MAX_RESUME_MANIFEST_DEPTH = 32;
+const HOST_ARGS_DIGEST_PATTERN = /^[a-f0-9]{64}$/;
 
 export interface SubagentCheckpointReference {
   threadId: string;
@@ -83,6 +84,8 @@ export interface SubagentResumeExecution {
   subagentType?: string;
   /** Lazy child revision bound when this execution first resolved. */
   configId?: string;
+  /** SHA-256 identity of the host arguments bound to this execution; never the values. */
+  hostArgsDigest?: string;
   approvalExecutionScope: string;
   checkpoints: SubagentCheckpointReference[];
   graphState: SubagentGraphResumeState;
@@ -354,6 +357,7 @@ function isSubagentResumeExecution(
   const childRunId = execution.childRunId;
   const subagentType = execution.subagentType;
   const configId = execution.configId;
+  const hostArgsDigest = execution.hostArgsDigest;
   const approvalExecutionScope = execution.approvalExecutionScope;
   const checkpoints = execution.checkpoints;
   const graphState = execution.graphState;
@@ -363,6 +367,9 @@ function isSubagentResumeExecution(
     !isString(childRunId) ||
     (subagentType != null && !isString(subagentType)) ||
     (configId != null && !isString(configId)) ||
+    (hostArgsDigest != null &&
+      (typeof hostArgsDigest !== 'string' ||
+        !HOST_ARGS_DIGEST_PATTERN.test(hostArgsDigest))) ||
     !isString(approvalExecutionScope) ||
     !Array.isArray(checkpoints) ||
     checkpoints.length === 0 ||

package/src/tools/subagent/childGraphConfig.ts

@@ -15,6 +15,7 @@ import {
   MAX_GRAPH_SUBAGENT_MEMBERS,
   MAX_GRAPH_SUBAGENT_TURNS,
 } from './runtimeLimits';
+import { getSubagentHostArgSpecs } from './hostArgs';
 
 const RESERVED_GRAPH_MEMBER_IDS = new Set([
   '__start__',
@@ -69,6 +70,7 @@ type GraphSubagentConfigCandidate = {
   configId?: unknown;
   agentInputs?: unknown;
   resolveAgentInputs?: unknown;
+  hostArgs?: unknown;
   self?: unknown;
 };
 
@@ -156,10 +158,11 @@ function assertGraphSubagentConfigShape(
     candidate.agentInputs !== undefined ||
     candidate.resolveAgentInputs !== undefined ||
     candidate.configId !== undefined ||
+    candidate.hostArgs !== undefined ||
     candidate.self !== undefined
   ) {
     throw new Error(
-      `Graph subagent "${configType}" cannot define agentInputs or self, or lazy fields configId/resolveAgentInputs.`
+      `Graph subagent "${configType}" cannot define agentInputs or self, or lazy fields configId/resolveAgentInputs/hostArgs.`
     );
   }
 }
@@ -482,6 +485,14 @@ function normalizeSingleAgentConfig(
       `Subagent "${config.type}" cannot combine self with resolveAgentInputs.`
     );
   }
+  if (
+    getSubagentHostArgSpecs(config).length > 0 &&
+    (config.resolveAgentInputs == null || config.agentInputs != null)
+  ) {
+    throw new Error(
+      `Subagent "${config.type}" declares hostArgs, which only a lazy resolveAgentInputs config without eager agentInputs can receive.`
+    );
+  }
   if (config.agentInputs != null) {
     return config as ResolvedSingleAgentSubagentConfig;
   }