@librechat/agents 3.6.11 → 3.6.13

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/llm/tokenCounterCacheCompatibility.ts

@@ -0,0 +1,22 @@
+import type { BaseMessage } from '@langchain/core/messages';
+
+const stableMessageTokenCounters = new WeakSet<
+  (message: BaseMessage) => number
+>();
+
+/**
+ * Opts a deterministic counter into stable-message count reuse. The counter
+ * must depend only on the message surface consumed by `getTokenCountForMessage`.
+ */
+export function markTokenCounterCacheCompatible<
+  TCounter extends (message: BaseMessage) => number,
+>(tokenCounter: TCounter): TCounter {
+  stableMessageTokenCounters.add(tokenCounter);
+  return tokenCounter;
+}
+
+export function isTokenCounterCacheCompatible(
+  tokenCounter: (message: BaseMessage) => number
+): boolean {
+  return stableMessageTokenCounters.has(tokenCounter);
+}

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/utils/tokens.ts

@@ -7,6 +7,7 @@ import {
   serializeStructuredValueBounded,
 } from './toolContent';
 import { ContentTypes } from '@/common/enum';
+import { markTokenCounterCacheCompatible } from '@/llm/tokenCounterCacheCompatibility';
 
 export type EncodingName = 'o200k_base' | 'claude';
 
@@ -1266,13 +1267,13 @@ export const createTokenCounter = async (
   const tok = await getTokenizer(encoding);
   const countTokens = (text: string): number => tok.count(text);
   const isClaude = encoding === 'claude';
-  return (message: BaseMessage): number => {
+  return markTokenCounterCacheCompatible((message: BaseMessage): number => {
     const count = getTokenCountForMessage(message, countTokens, encoding);
     const correctedCount = isClaude
       ? Math.ceil(count * CLAUDE_TOKEN_CORRECTION)
       : count;
     return ensureSafeTokenMeasurement(correctedCount, 'message');
-  };
+  });
 };
 
 /** Utility to manage the token encoder lifecycle explicitly. */