@librechat/agents 4.0.2 → 4.0.4

package/src/decisions/structuredOutput.ts

@@ -0,0 +1,25 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+
+export type DecisionOutputMethod = 'jsonSchema' | 'functionCalling';
+
+/** Binds only verified enforcement paths; a model profile alone is not a strict-output guarantee. */
+export function withDecisionStructuredOutput(
+  model: BaseChatModel,
+  schema: Record<string, unknown>,
+  method: DecisionOutputMethod
+): ReturnType<BaseChatModel['withStructuredOutput']> {
+  const options = {
+    name: 'DecideQuestions',
+    method,
+    includeRaw: true as const,
+  };
+  const adapter = model._llmType();
+  if (
+    adapter === 'openai' ||
+    adapter === 'azure_openai' ||
+    (adapter === 'anthropic' && method === 'functionCalling')
+  ) {
+    return model.withStructuredOutput(schema, { ...options, strict: true });
+  }
+  throw new Error('unverified strict decision model adapter');
+}

package/src/graphs/Graph.ts

@@ -131,6 +131,10 @@ import {
   resolveLangfuseConfig,
   resolveToolOutputTracingConfig,
 } from '@/langfuseConfig';
+import {
+  ProviderTextProtectionError,
+  validateProviderTextProtection,
+} from '@/protection/providerText';
 import {
   annotateMessagesForLLM,
   ToolOutputReferenceRegistry,
@@ -139,6 +143,10 @@ import {
   InvalidModelToolCallError,
   snapshotAcceptedModelResponse,
 } from './acceptedModelResponse';
+import {
+  collectSubagentHostArgNames,
+  pickSubagentHostArgInput,
+} from '@/tools/subagent/hostArgs';
 import {
   prepareProviderRequest,
   usesNativeOpenAIResponses,
@@ -1378,6 +1386,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
    * these on every streamed chunk event.
    */
   streamLimits: ResolvedStreamLimits;
+  /** Default-off mandatory provider prose release. */
+  providerTextProtection?: t.StandardGraphInput['providerTextProtection'];
   /**
    * Cumulative streamed argument bytes per in-flight tool call, keyed by
    * generation key + chunk index (see `resolveGenerationKey`). Per-run
@@ -1423,25 +1433,31 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
    * attempt lease; spans resets on purpose. */
   activeStreamLimitGenerations?: Set<string>;
 
-  /** The stream-limit error behind an already-fired breaker, whether this
+  /** The safety error behind an already-fired breaker, whether this
    * graph's own controller tripped or a parent run's breaker arrived through
    * the composed constructor signal (child graphs own separate controllers).
    * Providers can translate either abort into a generic error, and recovery
    * paths must not run in that state. */
   protected resolveTrippedBreakerReason(
     breakerSignal: AbortSignal = this.breakerAbort.signal
-  ): StreamLimitExceededError | PreparedSubagentError | undefined {
+  ):
+    | StreamLimitExceededError
+    | PreparedSubagentError
+    | ProviderTextProtectionError
+    | undefined {
     if (
       breakerSignal.aborted &&
       (breakerSignal.reason instanceof StreamLimitExceededError ||
-        breakerSignal.reason instanceof PreparedSubagentError)
+        breakerSignal.reason instanceof PreparedSubagentError ||
+        breakerSignal.reason instanceof ProviderTextProtectionError)
     ) {
       return breakerSignal.reason;
     }
     if (
       this.signal?.aborted === true &&
       (this.signal.reason instanceof StreamLimitExceededError ||
-        this.signal.reason instanceof PreparedSubagentError)
+        this.signal.reason instanceof PreparedSubagentError ||
+        this.signal.reason instanceof ProviderTextProtectionError)
     ) {
       return this.signal.reason;
     }
@@ -1551,6 +1567,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       onSubagentResolutionFailure,
       preemption,
       streamLimits,
+      providerTextProtection,
       toolExecution,
       clientDelegatedToolNames,
     }: t.StandardGraphInput,
@@ -1580,8 +1597,14 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     this.onSubagentResolutionFailure = onSubagentResolutionFailure;
     this.preemption = preemption;
     this.streamLimits = resolveStreamLimits(streamLimits);
+    if (providerTextProtection != null)
+      validateProviderTextProtection(providerTextProtection);
+    this.providerTextProtection = providerTextProtection;
     this.toolExecution = toolExecution;
-    if (clientDelegatedToolNames != null && clientDelegatedToolNames.length > 0) {
+    if (
+      clientDelegatedToolNames != null &&
+      clientDelegatedToolNames.length > 0
+    ) {
       if (agents.length !== 1) {
         throw new Error('Client tool delegation requires a single-agent graph');
       }
@@ -4404,7 +4427,12 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
          * succeeding fallback would resolve a run the public contract says
          * must reject. Rethrow before any recovery path.
          */
-        if (primaryError instanceof InvalidModelToolCallError) {
+        if (
+          primaryError instanceof InvalidModelToolCallError ||
+          primaryError instanceof ProviderTextProtectionError
+        ) {
+          if (primaryError instanceof ProviderTextProtectionError)
+            attemptBreaker.abort(primaryError);
           throw primaryError;
         }
         if (
@@ -4747,7 +4775,12 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               })
           );
         } catch (fallbackError) {
-          if (fallbackError instanceof InvalidModelToolCallError) {
+          if (
+            fallbackError instanceof InvalidModelToolCallError ||
+            fallbackError instanceof ProviderTextProtectionError
+          ) {
+            if (fallbackError instanceof ProviderTextProtectionError)
+              attemptBreaker.abort(fallbackError);
             throw fallbackError;
           }
           if (
@@ -5347,6 +5380,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           subagentContext: this.subagentContext,
           onResolutionFailure: this.onSubagentResolutionFailure,
           streamLimits: this.streamLimits,
+          providerTextProtection: this.providerTextProtection,
           humanInTheLoop: this.humanInTheLoop,
           checkpointer: this.compileOptions?.checkpointer,
           maxDepth: effectiveSubagentDepth,
@@ -5361,6 +5395,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           ): GraphFactory => snapshotChildGraphFactory(parentHandlerRegistry),
         });
         this.registerSubagentExecutor(executor);
+        const hostArgNames = collectSubagentHostArgNames(executableConfigs);
 
         const subagentTool = tool(
           async (rawInput, config) => {
@@ -5370,6 +5405,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               subagent_thread_id?: string;
               run_in_background?: boolean;
             };
+            const hostArgInput = pickSubagentHostArgInput(input, hostArgNames);
+            if (!hostArgInput.ok) {
+              return hostArgInput.message;
+            }
             const description =
               typeof input.description === 'string' &&
               input.description.trim().length > 0
@@ -5426,6 +5465,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               parentConfigurable: config.configurable as
                 | Record<string, unknown>
                 | undefined,
+              ...(hostArgInput.hostArgs == null
+                ? {}
+                : { hostArgs: hostArgInput.hostArgs }),
             };
             if (input.run_in_background === true) {
               return executor.executeInBackground({
@@ -5556,8 +5598,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       const delegatedNames = this.clientDelegatedToolNames;
       if (delegatedNames != null && delegatedNames.size > 0) {
         const { messages } = state as t.BaseGraphState;
-        const last = messages[messages.length - 1] as AIMessageChunk | undefined;
-        const calls = last?.getType() === 'ai' ? last.tool_calls ?? [] : [];
+        const last = messages[messages.length - 1] as
+          | AIMessageChunk
+          | undefined;
+        const calls = last?.getType() === 'ai' ? (last.tool_calls ?? []) : [];
         if (calls.some((call) => delegatedNames.has(call.name))) {
           if (
             calls.some(

package/src/index.ts

@@ -16,6 +16,7 @@ export * from './summarization';
 
 /* Tools */
 export * from './tools/Calculator';
+export * from './tools/GitHubCompare';
 export * from './tools/CodeExecutor';
 export * from './tools/BashExecutor';
 export * from './tools/ProgrammaticToolCalling';
@@ -121,3 +122,10 @@ export type {
 } from './llm/streamLimits';
 export * from './decisions';
 export * from './rerank';
+
+export { PROVIDER_TEXT_PROTECTION_VERSION, ProviderTextProtectionError } from './protection/providerText';
+export type {
+  ProviderTextProtection,
+  ProviderTextProtectionResult,
+  ProviderTextProtectionErrorCode,
+} from './protection/providerText';

package/src/llm/invoke.ts

@@ -14,6 +14,7 @@ import type { ToolCall } from '@langchain/core/messages/tool';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import type { PreparedProviderRequest } from '@/llm/prepareProviderRequest';
+import type { ProviderTextProtection } from '@/protection/providerText';
 import type { ContextOverflowContext } from '@/utils/errors';
 import type { StreamLimitState } from '@/llm/streamLimits';
 import type { PreemptAction } from '@/llm/preempt';
@@ -28,6 +29,12 @@ import {
   STREAM_LIMIT_REDISPATCH_KEY,
   STREAM_LIMIT_ATTEMPT_KEY,
 } from '@/llm/streamLimits';
+import {
+  validateProviderTextProtection,
+  ProviderTextProtectionError,
+  createProviderTextRestartCancellation,
+  isProviderTextRestartCancellation,
+} from '@/protection/providerText';
 import {
   inspectProviderMessageProjection,
   ProviderMessageProjectionInvariantError,
@@ -56,6 +63,7 @@ import {
 } from '@/llm/providers';
 import { ChatModelStreamHandler, dispatchesChatModelStream } from '@/stream';
 import { Constants, ContentTypes, GraphEvents, Providers } from '@/common';
+import { withProviderTextBoundary } from '@/llm/providerTextBoundary';
 import { PreparedSubagentError } from '@/tools/preparedSubagents';
 import { assertNotTruncatedToolCall } from '@/llm/truncation';
 import { resolveClientOptionsModel } from '@/llm/request';
@@ -623,6 +631,7 @@ function appendStreamChunk({
  */
 interface AttemptInvokeCommonParams {
   context?: InvokeContext;
+  providerTextProtection?: ProviderTextProtection;
   onChunk?: OnChunk;
   /**
    * The agent lane this attempt belongs to, as the model node names it. Only
@@ -697,6 +706,9 @@ export async function attemptInvoke(
   params: AttemptInvokeParams,
   config?: RunnableConfig
 ): Promise<Partial<t.BaseGraphState>> {
+  const policy =
+    params.providerTextProtection ?? params.context?.providerTextProtection;
+  if (policy != null) validateProviderTextProtection(policy);
   const provider = resolveAttemptProvider(params);
   const providerStampedConfig: RunnableConfig = {
     ...config,
@@ -707,7 +719,14 @@ export async function attemptInvoke(
       resolvedProvider: provider,
     },
   };
-  const request = resolveAttemptRequest(params, providerStampedConfig);
+  const preparedRequest = resolveAttemptRequest(params, providerStampedConfig);
+  const request =
+    policy == null
+      ? preparedRequest
+      : {
+        ...preparedRequest,
+        model: withProviderTextBoundary(preparedRequest.model, policy, provider),
+      };
   const configuredModel =
     providerStampedConfig.metadata?.[Constants.INVOKED_MODEL];
   const modelId =
@@ -763,6 +782,7 @@ export async function attemptInvoke(
         context: params.context,
         onChunk: params.onChunk,
         preemptAgentId: params.preemptAgentId,
+        providerTextProtection: policy,
       },
       stampedConfig
     );
@@ -775,6 +795,16 @@ export async function attemptInvoke(
     prepared?.finish(preparedAttempt, calls);
     return result;
   } catch (error) {
+    if (policy != null && config?.signal?.aborted === true) {
+      const reason: unknown = config.signal.reason;
+      if (reason instanceof StreamLimitExceededError || reason instanceof PreparedSubagentError) {
+        prepared?.finish(preparedAttempt, undefined, reason);
+        throw reason;
+      }
+      const cancelled = new ProviderTextProtectionError(reason instanceof ProviderTextProtectionError ? reason.code : 'cancelled');
+      prepared?.finish(preparedAttempt, undefined, cancelled);
+      throw cancelled;
+    }
     prepared?.finish(preparedAttempt, undefined, error);
     throw error;
   } finally {
@@ -799,9 +829,10 @@ async function attemptInvokeBody(
     context,
     onChunk,
     preemptAgentId,
+    providerTextProtection,
   }: Pick<
     AttemptInvokeCommonParams,
-    'context' | 'onChunk' | 'preemptAgentId'
+    'context' | 'onChunk' | 'preemptAgentId' | 'providerTextProtection'
   > & {
     request: PreparedProviderRequest;
   },
@@ -1068,7 +1099,7 @@ async function attemptInvokeBody(
         notePreemptRestartedRun(sealedRunId, finalChunk);
       }
       restartRoute = 'aborted';
-      restartController.abort();
+      restartController.abort(providerTextProtection == null ? undefined : createProviderTextRestartCancellation());
       return true;
     };
     const unsubscribeWake =
@@ -1085,7 +1116,8 @@ async function attemptInvokeBody(
       if (
         signal?.aborted === true &&
         (signal.reason instanceof StreamLimitExceededError ||
-          signal.reason instanceof PreparedSubagentError)
+          signal.reason instanceof PreparedSubagentError ||
+          signal.reason instanceof ProviderTextProtectionError)
       ) {
         throw signal.reason;
       }
@@ -1334,6 +1366,7 @@ async function attemptInvokeBody(
         restartRoute === 'aborted' &&
         !(error instanceof StreamLimitExceededError) &&
         !(error instanceof PreparedSubagentError) &&
+        (!(error instanceof ProviderTextProtectionError) || isProviderTextRestartCancellation(error)) &&
         config.signal?.aborted !== true;
       if (!ownAbort) {
         throw error;
@@ -1561,6 +1594,7 @@ export async function tryFallbackProviders({
   context,
   onChunk,
   streamLimitState,
+  providerTextProtection,
   preemptAgentId,
   overflowContext,
   prepareProviderRequest: prepareFallbackRequest,
@@ -1576,6 +1610,7 @@ export async function tryFallbackProviders({
   /** Accounting-lease owner forwarded to each fallback attempt (see
    * `AttemptInvokeParams.streamLimitState`). */
   streamLimitState?: StreamLimitState;
+  providerTextProtection?: ProviderTextProtection;
   /** Forwarded so a fallback-served attempt records a discarded turn in the
    * SAME lane the primary would have (see
    * `AttemptInvokeParams.preemptAgentId`). Dropping it here would leave the
@@ -1610,6 +1645,7 @@ export async function tryFallbackProviders({
     config?: RunnableConfig;
   }) => BaseMessage[] | Promise<BaseMessage[]>;
 }): Promise<Partial<t.BaseGraphState> | undefined> {
+  if (primaryError instanceof ProviderTextProtectionError) throw primaryError;
   const isOverflow = (
     error: unknown,
     contextOverride = overflowContext
@@ -1686,7 +1722,8 @@ export async function tryFallbackProviders({
       if (
         config?.signal?.aborted === true &&
         (config.signal.reason instanceof StreamLimitExceededError ||
-          config.signal.reason instanceof PreparedSubagentError)
+          config.signal.reason instanceof PreparedSubagentError ||
+          config.signal.reason instanceof ProviderTextProtectionError)
       ) {
         throw config.signal.reason;
       }
@@ -1697,6 +1734,7 @@ export async function tryFallbackProviders({
             context,
             onChunk,
             streamLimitState,
+            providerTextProtection,
             preemptAgentId,
           },
           fbConfig
@@ -1710,6 +1748,7 @@ export async function tryFallbackProviders({
           context,
           onChunk,
           streamLimitState,
+          providerTextProtection,
           preemptAgentId,
         },
         fbConfig
@@ -1723,7 +1762,8 @@ export async function tryFallbackProviders({
       if (
         e instanceof StreamLimitExceededError ||
         e instanceof PreparedSubagentError ||
-        e instanceof InvalidModelToolCallError
+        e instanceof InvalidModelToolCallError ||
+        e instanceof ProviderTextProtectionError
       ) {
         throw e;
       }
@@ -1734,7 +1774,8 @@ export async function tryFallbackProviders({
       if (
         config?.signal?.aborted === true &&
         (config.signal.reason instanceof StreamLimitExceededError ||
-          config.signal.reason instanceof PreparedSubagentError)
+          config.signal.reason instanceof PreparedSubagentError ||
+          config.signal.reason instanceof ProviderTextProtectionError)
       ) {
         throw config.signal.reason;
       }

package/src/llm/openai/index.ts

@@ -63,6 +63,7 @@ import {
   hasToolCallChunks,
   getReasoningKwargsText,
 } from '@/llm/stream/chunkAdapters';
+import { registerProviderTextChunkConstructor } from '@/llm/providerTextChunk';
 import { isReasoningModel, _convertMessagesToOpenAIParams } from './utils';
 import { smoothStream, resolveStreamDelay } from '@/llm/stream/smoother';
 import { INTENT_ARG, isIntentLabelProperty } from '@/tools/intentArg';
@@ -855,6 +856,8 @@ class ResponsesReplayAIMessageChunk extends AIMessageChunk {
   }
 }
 
+registerProviderTextChunkConstructor(ResponsesReplayAIMessageChunk);
+
 function makeResponsesReplayAggregationSafe(
   chunk: ChatGenerationChunk
 ): ChatGenerationChunk {
@@ -2923,6 +2926,11 @@ export class AzureChatOpenAI extends OriginalAzureChatOpenAI {
     super(fields);
     this.completions = new LibreChatAzureOpenAICompletions(fields);
     this.responses = new LibreChatAzureOpenAIResponses(fields);
+    this.fields = {
+      ...this.fields,
+      completions: this.completions,
+      responses: this.responses,
+    };
     this._lc_stream_delay = resolveStreamDelay(fields?._lc_stream_delay);
     this.firstPartyEndpoint = fields?.firstPartyEndpoint;
   }