@librechat/agents 3.6.10 → 3.6.12

package/src/llm/prepareProviderRequest.ts

@@ -0,0 +1,357 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
+import type * as t from '@/types';
+import {
+  projectCacheControlledToolOutputsToText,
+  projectComputerCallOutputsToText,
+  projectOpenAIChatToolMessageContent,
+  projectOpenAIResponsesToolMessageContent,
+  projectOpenRouterToolMessageContent,
+  projectSingleTextToolOutputsToText,
+  projectStructuredToolOutputsToText,
+  projectToolStreamContentForProvider,
+} from '@/messages/core';
+import {
+  coalesceAdjacentUserTurns,
+  strictAlternationProviders,
+  appendPredecessorHandoffCue,
+  removePredecessorHandoffCue,
+} from '@/messages';
+import {
+  stripAnthropicCacheControl,
+  stripBedrockCacheControl,
+} from '@/messages/cache';
+import { annotateMessagesForLLM } from '@/tools/toolOutputReferences';
+import { Providers } from '@/common';
+import { isAnthropicLike, isOpenAILike } from '@/utils/llm';
+
+const preparedProviderRequestBrand = Symbol('PreparedProviderRequest');
+
+export type ProviderMessageProjectionMode =
+  | 'chat-messages'
+  | 'openai-responses';
+
+export interface ProviderPayloadMeasurement {
+  readonly fits: boolean;
+  readonly projectedMessageTokens?: number;
+  readonly availableMessageTokens?: number;
+  readonly contextBudget?: number;
+  readonly effectiveInstructionTokens?: number;
+}
+
+export interface PreparedProviderRequest {
+  readonly model: t.ChatModel;
+  readonly modelId?: string;
+  readonly provider: Providers;
+  readonly projectionMode: ProviderMessageProjectionMode;
+  readonly messages: BaseMessage[];
+  readonly measurement?: ProviderPayloadMeasurement;
+  readonly [preparedProviderRequestBrand]: true;
+}
+
+type PreparedProviderRequestData = Omit<
+  PreparedProviderRequest,
+  typeof preparedProviderRequestBrand
+>;
+
+export interface ProviderRequestContext {
+  getOrCreateToolOutputRegistry?(): ToolOutputReferenceRegistry | undefined;
+  isRunProducedMessage?(message: BaseMessage): boolean;
+}
+
+export interface PrepareProviderRequestParams {
+  model: t.ChatModel;
+  messages: BaseMessage[];
+  provider: Providers;
+  context?: ProviderRequestContext;
+  config?: RunnableConfig;
+  maxToolResultChars?: number;
+  measure?: (messages: BaseMessage[]) => ProviderPayloadMeasurement;
+}
+
+export function usesNativeOpenAIResponses(
+  model: t.ChatModel,
+  provider: Providers,
+  callOptions?: unknown
+): boolean {
+  if (!isOpenAILike(provider)) {
+    return false;
+  }
+  let candidate: unknown = model;
+  let effectiveCallOptions = callOptions;
+  const seen = new Set<object>();
+  for (let depth = 0; depth < 20; depth++) {
+    if (candidate == null || typeof candidate !== 'object') {
+      return false;
+    }
+    if (seen.has(candidate)) {
+      return false;
+    }
+    seen.add(candidate);
+    const runnable = candidate as {
+      _useResponsesApi?: (options?: unknown) => boolean;
+      bound?: unknown;
+      defaultOptions?: unknown;
+      last?: unknown;
+      constructor?: { name?: unknown };
+    };
+    try {
+      if (
+        runnable.defaultOptions != null &&
+        typeof runnable.defaultOptions === 'object' &&
+        !Array.isArray(runnable.defaultOptions) &&
+        effectiveCallOptions != null &&
+        typeof effectiveCallOptions === 'object' &&
+        !Array.isArray(effectiveCallOptions)
+      ) {
+        effectiveCallOptions = {
+          ...(runnable.defaultOptions as Record<string, unknown>),
+          ...(effectiveCallOptions as Record<string, unknown>),
+        };
+      } else if (effectiveCallOptions == null) {
+        effectiveCallOptions = runnable.defaultOptions;
+      }
+      if (
+        runnable._useResponsesApi?.(effectiveCallOptions) === true ||
+        runnable._useResponsesApi?.(undefined) === true
+      ) {
+        return true;
+      }
+    } catch {
+      // Continue through RunnableSequence/RunnableBinding wrappers.
+    }
+    if (
+      typeof runnable.constructor?.name === 'string' &&
+      runnable.constructor.name.includes('Responses')
+    ) {
+      return true;
+    }
+    if (runnable.last != null && typeof runnable.last === 'object') {
+      candidate = runnable.last;
+      continue;
+    }
+    if (runnable.bound != null && typeof runnable.bound === 'object') {
+      candidate = runnable.bound;
+      continue;
+    }
+    return false;
+  }
+  return false;
+}
+
+function resolveProviderMessageProjectionMode(
+  model: t.ChatModel,
+  provider: Providers,
+  callOptions?: unknown
+): ProviderMessageProjectionMode {
+  return usesNativeOpenAIResponses(model, provider, callOptions)
+    ? 'openai-responses'
+    : 'chat-messages';
+}
+
+interface ProjectMessagesForProviderParams {
+  model: t.ChatModel;
+  messages: BaseMessage[];
+  provider: Providers;
+  maxToolResultChars?: number;
+  callOptions?: unknown;
+}
+
+function projectMessagesForProviderMode({
+  messages,
+  provider,
+  maxToolResultChars,
+}: ProjectMessagesForProviderParams,
+projectionMode: ProviderMessageProjectionMode
+): BaseMessage[] {
+  const nativeOpenAIResponses = projectionMode === 'openai-responses';
+  const providerInputMessages = projectToolStreamContentForProvider(
+    messages,
+    nativeOpenAIResponses ? 'native' : 'fallback',
+    maxToolResultChars
+  );
+  if (nativeOpenAIResponses) {
+    return projectOpenAIResponsesToolMessageContent(
+      stripAnthropicCacheControl(
+        stripBedrockCacheControl(providerInputMessages)
+      ),
+      maxToolResultChars
+    );
+  }
+  if (provider === Providers.OPENROUTER) {
+    return projectComputerCallOutputsToText(
+      projectOpenRouterToolMessageContent(
+        stripBedrockCacheControl(providerInputMessages),
+        maxToolResultChars
+      )
+    );
+  }
+  if (isOpenAILike(provider)) {
+    return projectComputerCallOutputsToText(
+      projectOpenAIChatToolMessageContent(
+        stripAnthropicCacheControl(
+          stripBedrockCacheControl(providerInputMessages)
+        ),
+        maxToolResultChars
+      )
+    );
+  }
+  if (provider === Providers.ANTHROPIC) {
+    return projectComputerCallOutputsToText(
+      projectSingleTextToolOutputsToText(
+        stripBedrockCacheControl(providerInputMessages),
+        maxToolResultChars
+      )
+    );
+  }
+  if (provider === Providers.BEDROCK) {
+    return stripAnthropicCacheControl(
+      projectComputerCallOutputsToText(
+        projectCacheControlledToolOutputsToText(
+          providerInputMessages,
+          maxToolResultChars
+        )
+      )
+    );
+  }
+  return projectComputerCallOutputsToText(
+    projectStructuredToolOutputsToText(
+      projectSingleTextToolOutputsToText(
+        stripAnthropicCacheControl(
+          stripBedrockCacheControl(providerInputMessages)
+        ),
+        maxToolResultChars
+      ),
+      maxToolResultChars
+    )
+  );
+}
+
+/** Produces the provider-facing representation before adapter serialization. */
+export function projectMessagesForProvider(
+  params: ProjectMessagesForProviderParams
+): BaseMessage[] {
+  return projectMessagesForProviderMode(
+    params,
+    resolveProviderMessageProjectionMode(
+      params.model,
+      params.provider,
+      params.callOptions
+    )
+  );
+}
+
+/** Reads the serving model id through LangChain binding/sequence wrappers. */
+export function resolveServingModelId(model: unknown): string | undefined {
+  const seen = new Set<unknown>();
+  let current: unknown = model;
+  while (current != null && typeof current === 'object' && !seen.has(current)) {
+    seen.add(current);
+    const wrapper = current as {
+      model?: unknown;
+      bound?: unknown;
+      last?: unknown;
+      steps?: unknown[];
+    };
+    if (typeof wrapper.model === 'string' && wrapper.model !== '') {
+      return wrapper.model;
+    }
+    current =
+      wrapper.bound ??
+      wrapper.last ??
+      (Array.isArray(wrapper.steps)
+        ? wrapper.steps[wrapper.steps.length - 1]
+        : undefined);
+  }
+  return undefined;
+}
+
+/**
+ * Finalizes one provider request and measures the exact message array that
+ * will be passed to LangChain. Source messages remain untouched.
+ */
+export function prepareProviderRequest({
+  model,
+  messages,
+  provider,
+  context,
+  config,
+  maxToolResultChars,
+  measure,
+}: PrepareProviderRequestParams): PreparedProviderRequest {
+  const projectionMode = resolveProviderMessageProjectionMode(
+    model,
+    provider,
+    config
+  );
+  const projected = projectMessagesForProviderMode(
+    {
+      model,
+      messages,
+      provider,
+      maxToolResultChars,
+      callOptions: config,
+    },
+    projectionMode
+  );
+  const registry = context?.getOrCreateToolOutputRegistry?.();
+  const runId = config?.configurable?.run_id as string | undefined;
+  const annotated = annotateMessagesForLLM(projected, registry, runId);
+  const isRunProduced = context?.isRunProducedMessage;
+  const modelId = resolveServingModelId(model);
+  const cued = isAnthropicLike(provider, {
+    model: modelId,
+  })
+    ? appendPredecessorHandoffCue(
+      annotated,
+      isRunProduced == null
+        ? undefined
+        : (message): boolean => isRunProduced.call(context, message)
+    )
+    : removePredecessorHandoffCue(annotated);
+  const preparedMessages = strictAlternationProviders.has(provider)
+    ? coalesceAdjacentUserTurns(cued)
+    : cued;
+
+  const request: PreparedProviderRequestData = {
+    model,
+    modelId,
+    provider,
+    projectionMode,
+    messages: preparedMessages,
+    measurement: measure?.(preparedMessages),
+  };
+  Object.defineProperty(request, preparedProviderRequestBrand, {
+    value: true,
+    enumerable: false,
+  });
+  return Object.freeze(request) as PreparedProviderRequest;
+}
+
+export function assertPreparedProviderRequestFor(
+  request: PreparedProviderRequest,
+  model: t.ChatModel,
+  provider: Providers,
+  config?: RunnableConfig
+): void {
+  if (
+    !Object.prototype.hasOwnProperty.call(request, preparedProviderRequestBrand)
+  ) {
+    throw new Error('Invalid prepared provider request');
+  }
+  if (request.model !== model) {
+    throw new Error('Prepared provider request does not match serving model');
+  }
+  if (request.provider !== provider) {
+    throw new Error('Prepared provider request does not match serving provider');
+  }
+  if (
+    request.projectionMode !==
+    resolveProviderMessageProjectionMode(model, provider, config)
+  ) {
+    throw new Error(
+      'Prepared provider request does not match invocation options'
+    );
+  }
+}

package/src/messages/content.ts

@@ -3,6 +3,7 @@ import type {
   MessageContentComplex,
 } from '@langchain/core/messages';
 import { ContentTypes } from '@/common';
+import { cloneMessage } from './cache';
 
 /**
  * Whether {@link formatContentStrings} will flatten this message's content:
@@ -42,13 +43,12 @@ export const formatContentStrings = (
     const blocks = message.content as MessageContentComplex[];
     const content = blocks.reduce((acc, curr) => {
       if (curr.type === ContentTypes.TEXT) {
-        return `${acc}${curr[ContentTypes.TEXT] || ''}\n`;
+        return `${acc}${curr[ContentTypes.TEXT] ?? ''}\n`;
       }
       return acc;
     }, '');
 
-    message.content = content.trim();
-    result.push(message);
+    result.push(cloneMessage(message, content.trim()));
   }
 
   return result;

package/src/stream.ts

@@ -820,6 +820,12 @@ function startEagerToolExecutions(args: {
       toolCalls: entries.map((entry) => entry.request),
       userId: graph.config?.configurable?.user_id as string | undefined,
       agentId: agentContext?.agentId,
+      callerCapabilityProjection:
+        (
+          agentContext as
+            | Partial<Pick<AgentContext, 'getCallerCapabilityProjectionSnapshot'>>
+            | undefined
+        )?.getCallerCapabilityProjectionSnapshot?.(),
       configurable: graph.config?.configurable as
         | Record<string, unknown>
         | undefined,

package/src/tools/CallerCapabilities.ts

@@ -14,6 +14,74 @@ export type CallerCapabilityProjection = {
   codeExecutionOnlyTools: t.LCTool[];
 };
 
+/**
+ * Combines event schemas with runtime capability metadata. Matching runtime
+ * entries override caller/defer policy without replacing the event schema;
+ * runtime-only definitions are appended intact.
+ */
+export function mergeCallerCapabilityDefinitions(
+  toolDefs: Iterable<t.LCTool> | null | undefined,
+  overrides: Iterable<t.LCTool> | null | undefined
+): t.LCTool[] {
+  const runtimeDefinitions = Array.from(overrides ?? []);
+  const merged = new Map(
+    applyCallerCapabilityDefinitionOverrides(
+      toolDefs ?? [],
+      runtimeDefinitions
+    ).map((toolDef) => [toolDef.name, toolDef])
+  );
+  for (const override of runtimeDefinitions) {
+    if (!merged.has(override.name)) {
+      merged.set(override.name, override);
+    }
+  }
+  return Array.from(merged.values());
+}
+
+/**
+ * Applies runtime caller metadata to schema-only event definitions without
+ * adding registry-only tools or replacing their model-facing schemas.
+ */
+export function applyCallerCapabilityDefinitionOverrides(
+  toolDefs: Iterable<t.LCTool>,
+  overrides: Iterable<t.LCTool> | null | undefined
+): t.LCTool[] {
+  const overridesByName = new Map<string, t.LCTool>();
+  for (const override of overrides ?? []) {
+    overridesByName.set(override.name, override);
+  }
+  return Array.from(toolDefs, (toolDef) => {
+    const override = overridesByName.get(toolDef.name);
+    if (override == null) {
+      return toolDef;
+    }
+    return {
+      ...toolDef,
+      allowed_callers: override.allowed_callers,
+      defer_loading: override.defer_loading,
+    };
+  });
+}
+
+/** Converts the live projection into the versioned event transport shape. */
+export function createCallerCapabilityProjectionSnapshot(
+  projection: CallerCapabilityProjection
+): t.CallerCapabilityProjectionSnapshot {
+  return {
+    version: 1,
+    directToolNames: projection.directTools.map((toolDef) => toolDef.name),
+    codeExecutionToolNames: projection.codeExecutionTools.map(
+      (toolDef) => toolDef.name
+    ),
+    directOnlyToolNames: projection.directOnlyTools.map(
+      (toolDef) => toolDef.name
+    ),
+    codeExecutionOnlyToolNames: projection.codeExecutionOnlyTools.map(
+      (toolDef) => toolDef.name
+    ),
+  };
+}
+
 export function getAllowedCallers(
   toolDef: t.LCTool
 ): readonly t.AllowedCaller[] {

package/src/tools/ToolNode.ts

@@ -95,8 +95,11 @@ import {
   resolveLocalExecutionTools,
 } from '@/tools/local';
 import {
+  type CallerCapabilityProjection,
+  createCallerCapabilityProjectionSnapshot,
   isToolDefinitionActive,
   isProgrammaticControlTool,
+  mergeCallerCapabilityDefinitions,
   resolveCallerCapabilityProjection,
 } from '@/tools/CallerCapabilities';
 import { stripCodeSessionFileSummary } from '@/tools/CodeSessionFileSummary';
@@ -698,6 +701,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   >();
   /** Tool registry for filtering (lazy computation of programmatic maps) */
   private toolRegistry?: t.LCToolRegistry;
+  /** Schema-only definitions used when event mode has no runtime registry. */
+  private toolDefinitions?: t.LCToolRegistry;
+  /** Tool-map entries created or replaced by the local execution resolver. */
+  private localImplementationNames = new Set<string>();
   /** Reads deferred-tool discovery state from the owning agent context. */
   private getDiscoveredToolNames?: () => readonly string[];
   /** Reference to Graph's sessions map for automatic session injection */
@@ -803,6 +810,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     handleToolErrors,
     loadRuntimeTools,
     toolRegistry,
+    toolDefinitions,
     getDiscoveredToolNames,
     sessions,
     codeSessionKey,
@@ -879,6 +887,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       toolRegistry,
       toolExecution,
     });
+    this.toolDefinitions = toolDefinitions;
     this.getDiscoveredToolNames = getDiscoveredToolNames;
     this.sessions = sessions;
     this.codeSessionKey = codeSessionKey ?? Constants.EXECUTE_CODE;
@@ -999,6 +1008,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     });
 
     this.toolMap = resolved.toolMap;
+    this.localImplementationNames = resolved.localImplementationNames;
     if (resolved.fileCheckpointer != null) {
       this.fileCheckpointer = resolved.fileCheckpointer;
     }
@@ -1105,27 +1115,58 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     this.settledInterruptingResults.clear();
   }
 
+  /** Returns the live caller projection used by direct and event execution. */
+  private getCallerCapabilityProjection(): CallerCapabilityProjection {
+    const discoveredToolNames = new Set(
+      this.getDiscoveredToolNames?.() ?? []
+    );
+    return resolveCallerCapabilityProjection(
+      mergeCallerCapabilityDefinitions(
+        this.toolDefinitions?.values(),
+        this.toolRegistry?.values()
+      ),
+      (toolDef) => isToolDefinitionActive(toolDef, discoveredToolNames)
+    );
+  }
+
+  /** Serializes the live caller projection for event-driven hosts. */
+  private getCallerCapabilityProjectionSnapshot(): t.CallerCapabilityProjectionSnapshot {
+    return createCallerCapabilityProjectionSnapshot(
+      this.getCallerCapabilityProjection()
+    );
+  }
+
   /** Returns active tools projected by their effective caller capabilities. */
   private getProgrammaticTools(): t.ProgrammaticCache {
     const toolMap: t.ToolMap = new Map();
+    const toolDefs: t.LCTool[] = [];
     const discoveredToolNames = new Set(
       this.getDiscoveredToolNames?.() ?? []
     );
-    const capabilities = resolveCallerCapabilityProjection(
+    const executableCapabilities = resolveCallerCapabilityProjection(
       this.toolRegistry?.values() ?? [],
       (toolDef) => isToolDefinitionActive(toolDef, discoveredToolNames)
     );
-    for (const toolDef of capabilities.codeExecutionTools) {
+    for (const toolDef of executableCapabilities.codeExecutionTools) {
+      if (
+        this.eventDrivenMode &&
+        this.directToolNames?.has(toolDef.name) !== true &&
+        !this.localImplementationNames.has(toolDef.name)
+      ) {
+        continue;
+      }
       const tool = this.toolMap.get(toolDef.name);
       if (tool != null) {
         toolMap.set(toolDef.name, tool);
+        toolDefs.push(toolDef);
       }
     }
+    const activeCapabilities = this.getCallerCapabilityProjection();
 
     return {
       toolMap,
-      toolDefs: capabilities.codeExecutionTools,
-      disallowedToolDefs: capabilities.directOnlyTools
+      toolDefs,
+      disallowedToolDefs: activeCapabilities.directOnlyTools
         .filter((toolDef) => !isProgrammaticControlTool(toolDef.name))
         .map((toolDef) => ({ name: toolDef.name })),
     };
@@ -3455,6 +3496,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
               // the eager path sends `agentContext.agentId` — this must
               // match it at the top level too.
               agentId: this.executingAgentId,
+              callerCapabilityProjection:
+                this.getCallerCapabilityProjectionSnapshot(),
               configurable: stripRunBreakerScope(
                   config.configurable as Record<string, unknown> | undefined
               ),