@librechat/agents 3.6.11 → 3.6.12

package/dist/types/llm/contextPressureMeter.d.ts

@@ -0,0 +1,30 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { ProviderPayloadMeasurement } from '@/llm/prepareProviderRequest';
+import type * as t from '@/types';
+interface ContextPressureUsage {
+    contextBudget?: number;
+    effectiveInstructionTokens?: number;
+    remainingContextTokens?: number;
+    calibrationRatio?: number;
+}
+interface ContextPressureMeterParams {
+    tokenCounter?: t.TokenCounter;
+    sourceMessages: BaseMessage[];
+    retainedMessages: BaseMessage[];
+    indexTokenCountMap: Record<string, number | undefined>;
+    contextUsage?: ContextPressureUsage | null;
+    instructionTokens: number;
+    calibrationRatio: number;
+}
+interface ProviderPayloadMeasureOptions {
+    contextBudget?: number;
+    forceRawRecount?: boolean;
+}
+export interface ContextPressureMeter {
+    trackProjection(before: BaseMessage[], after: BaseMessage[]): BaseMessage[];
+    trackClone(source: BaseMessage, clone: BaseMessage): void;
+    measure(messages: BaseMessage[], options?: ProviderPayloadMeasureOptions): ProviderPayloadMeasurement;
+}
+/** Measures repeated provider projections while tokenizing each message object once. */
+export declare function createContextPressureMeter({ tokenCounter, sourceMessages, retainedMessages, indexTokenCountMap, contextUsage, instructionTokens, calibrationRatio, }: ContextPressureMeterParams): ContextPressureMeter;
+export {};

package/dist/types/llm/invoke.d.ts

@@ -2,18 +2,21 @@ import { AIMessageChunk } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
+import type { PreparedProviderRequest } from '@/llm/prepareProviderRequest';
 import type { StreamLimitState } from '@/llm/streamLimits';
 import type { ContextOverflowContext } from '@/utils/errors';
 import type * as t from '@/types';
 import { ChatModelStreamHandler } from '@/stream';
 import { Providers } from '@/common';
+export { projectMessagesForProvider, resolveServingModelId, usesNativeOpenAIResponses, } from '@/llm/prepareProviderRequest';
+export type { PreparedProviderRequest, PrepareProviderRequestParams, ProviderMessageProjectionMode, ProviderPayloadMeasurement, ProviderRequestContext, } from '@/llm/prepareProviderRequest';
 /**
  * Context passed to `attemptInvoke`. Matches the subset of Graph that
  * `ChatModelStreamHandler.handle` needs *plus* the explicit
- * `getOrCreateToolOutputRegistry()` accessor that `attemptInvoke`
- * itself calls to pull the run-scoped tool-output registry off the
- * graph and project each relevant ToolMessage into a transient
- * annotated copy before the provider call.
+ * `getOrCreateToolOutputRegistry()` accessor used while preparing a
+ * provider request. Raw callers prepare inside `attemptInvoke`; Graph
+ * callers prepare before final payload measurement and pass the exact
+ * artifact through.
  *
  * The intersection is intentional: `Parameters<...>[3]` resolves
  * indirectly through the stream handler's signature (which returns
@@ -46,26 +49,6 @@ export type InvokeContext = NonNullable<Parameters<ChatModelStreamHandler['handl
  * limits key each model attempt separately.
  */
 export type OnChunk = (chunk: AIMessageChunk, metadata?: Record<string, unknown>) => void | Promise<void>;
-export declare function usesNativeOpenAIResponses(model: t.ChatModel, provider: Providers, callOptions?: unknown): boolean;
-/**
- * Produces the exact provider-facing message representation before a model
- * adapter serializes it. This is shared by invocation and Graph's final budget
- * guard so structured tool output cannot grow after the payload was measured.
- */
-export declare function projectMessagesForProvider({ model, messages, provider, maxToolResultChars, callOptions, }: {
-    model: t.ChatModel;
-    messages: BaseMessage[];
-    provider: Providers;
-    maxToolResultChars?: number;
-    callOptions?: unknown;
-}): BaseMessage[];
-/**
- * The serving model's id, read through the same wrapper stack
- * `collectModelCallbackSources` walks — `bindTools` returns a
- * `RunnableBinding` and a system runnable pipes a `RunnableSequence`, and
- * neither exposes the chat model's `model` at the top level.
- */
-export declare function resolveServingModelId(model: unknown): string | undefined;
 /**
  * Invokes a chat model with the given messages, handling both streaming and
  * non-streaming paths.
@@ -75,10 +58,7 @@ export declare function resolveServingModelId(model: unknown): string | undefine
  * Pass an `onChunk` callback to override this with custom chunk processing
  * (e.g. summarization delta events).
  */
-interface AttemptInvokeParams {
-    model: t.ChatModel;
-    messages: BaseMessage[];
-    provider: Providers;
+interface AttemptInvokeCommonParams {
     context?: InvokeContext;
     onChunk?: OnChunk;
     /** Accounting owner for callers that deliberately pass no `context`
@@ -86,6 +66,17 @@ interface AttemptInvokeParams {
      * for charge claims. */
     streamLimitState?: StreamLimitState;
 }
+type AttemptInvokeParams = AttemptInvokeCommonParams & ({
+    request: PreparedProviderRequest;
+    model?: never;
+    messages?: never;
+    provider?: never;
+} | {
+    request?: never;
+    model: t.ChatModel;
+    messages: BaseMessage[];
+    provider: Providers;
+});
 /**
  * One model attempt. Stamps the attempt identity into callback metadata
  * (see the generation-key notes in `streamLimits.ts`), leases the attempt's
@@ -122,7 +113,7 @@ export declare function getFallbackOverflowCandidates(error: unknown): FallbackO
  * behind a later unrelated error would surface a dead end instead. Ordinary
  * failures still throw last-error-wins.
  */
-export declare function tryFallbackProviders({ fallbacks, tools, messages, config, primaryError, context, onChunk, streamLimitState, overflowContext, prepareProviderMessages, }: {
+export declare function tryFallbackProviders({ fallbacks, tools, messages, config, primaryError, context, onChunk, streamLimitState, overflowContext, prepareProviderRequest: prepareFallbackRequest, prepareProviderMessages, }: {
     fallbacks: t.FallbackConfig[];
     tools?: t.GraphTools;
     messages: BaseMessage[];
@@ -141,10 +132,18 @@ export declare function tryFallbackProviders({ fallbacks, tools, messages, confi
      */
     overflowContext?: ContextOverflowContext;
     /**
-     * Optional final payload guard used by Graph. It receives the initialized,
-     * tool-bound fallback model so Responses-vs-Chat projection is exact before
-     * the fallback request is measured and sent.
+     * Optional exact-payload preparation used by Graph. The returned request is
+     * measured and sent without another provider projection.
      */
+    prepareProviderRequest?: (input: {
+        model: t.ChatModel;
+        messages: BaseMessage[];
+        provider: Providers;
+        clientOptions?: t.ClientOptions;
+        maxContextTokens?: number;
+        config?: RunnableConfig;
+    }) => PreparedProviderRequest | Promise<PreparedProviderRequest>;
+    /** @deprecated Return a `PreparedProviderRequest` instead. */
     prepareProviderMessages?: (input: {
         model: t.ChatModel;
         messages: BaseMessage[];
@@ -154,4 +153,3 @@ export declare function tryFallbackProviders({ fallbacks, tools, messages, confi
         config?: RunnableConfig;
     }) => BaseMessage[] | Promise<BaseMessage[]>;
 }): Promise<Partial<t.BaseGraphState> | undefined>;
-export {};

package/dist/types/llm/prepareProviderRequest.d.ts

@@ -0,0 +1,55 @@
+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 { Providers } from '@/common';
+declare const preparedProviderRequestBrand: unique symbol;
+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;
+}
+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 declare function usesNativeOpenAIResponses(model: t.ChatModel, provider: Providers, callOptions?: unknown): boolean;
+interface ProjectMessagesForProviderParams {
+    model: t.ChatModel;
+    messages: BaseMessage[];
+    provider: Providers;
+    maxToolResultChars?: number;
+    callOptions?: unknown;
+}
+/** Produces the provider-facing representation before adapter serialization. */
+export declare function projectMessagesForProvider(params: ProjectMessagesForProviderParams): BaseMessage[];
+/** Reads the serving model id through LangChain binding/sequence wrappers. */
+export declare function resolveServingModelId(model: unknown): string | undefined;
+/**
+ * Finalizes one provider request and measures the exact message array that
+ * will be passed to LangChain. Source messages remain untouched.
+ */
+export declare function prepareProviderRequest({ model, messages, provider, context, config, maxToolResultChars, measure, }: PrepareProviderRequestParams): PreparedProviderRequest;
+export declare function assertPreparedProviderRequestFor(request: PreparedProviderRequest, model: t.ChatModel, provider: Providers, config?: RunnableConfig): void;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.6.11",
+  "version": "3.6.12",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"

package/src/graphs/Graph.ts

@@ -50,8 +50,8 @@ import {
   addBedrockTailCacheControl,
   projectArtifactPayload,
   formatContentStrings,
+  cloneMessage,
   CALIBRATION_RATIO_MAX,
-  REPLY_PRIMER_TOKENS,
   createPruneMessages,
   projectToolCallInputs,
   calculateMaxToolCallInputChars,
@@ -74,7 +74,6 @@ import {
   coalesceAdjacentUserTurns,
   strictAlternationProviders,
   appendPredecessorHandoffCue,
-  removePredecessorHandoffCue,
   stampSyntheticProviderMessage,
 } from '@/messages';
 import {
@@ -104,9 +103,9 @@ import {
   tryFallbackProviders,
   getFallbackErrorContext,
   getFallbackOverflowCandidates,
-  projectMessagesForProvider,
-  resolveServingModelId,
 } from '@/llm/invoke';
+import { prepareProviderRequest } from '@/llm/prepareProviderRequest';
+import { createContextPressureMeter } from '@/llm/contextPressureMeter';
 import {
   resolveStreamLimits,
   StreamLimitExceededError,
@@ -3154,105 +3153,18 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
        * baseline, then attribute it across retained messages. Provider
        * transforms can shrink one message while expanding or adding another;
        * per-origin accounting prevents that unrelated shrink from canceling
-       * the expansion. Raw counts are frozen before in-place formatters run.
+       * the expansion. Exact counts are memoized across repeated projections.
        */
-      let providerMessageBaseline:
-        | Array<{ rawTokens: number; accountingWeight: number }>
-        | undefined;
-      const providerMessageOrigins = new WeakMap<BaseMessage, number>();
-      if (contextUsage != null && agentContext.tokenCounter != null) {
-        const sourceIndices = new WeakMap<BaseMessage, number>();
-        for (let i = 0; i < messages.length; i++) {
-          sourceIndices.set(messages[i], i);
-        }
-        providerMessageBaseline = messagesToUse.map((message, index) => {
-          const rawTokens = agentContext.tokenCounter!(message);
-          const sourceIndex = sourceIndices.get(message);
-          const indexedTokens =
-            sourceIndex != null
-              ? agentContext.indexTokenCountMap[sourceIndex]
-              : undefined;
-          const accountingWeight =
-            indexedTokens != null &&
-            Number.isFinite(indexedTokens) &&
-            indexedTokens >= 0
-              ? indexedTokens
-              : rawTokens;
-          if (!providerMessageOrigins.has(message)) {
-            providerMessageOrigins.set(message, index);
-          }
-          return { rawTokens, accountingWeight };
-        });
-      }
-
-      const getProviderMessageOriginKey = (
-        message: BaseMessage
-      ): string | undefined => {
-        const type = message.getType();
-        if (
-          message instanceof ToolMessage &&
-          typeof message.tool_call_id === 'string' &&
-          message.tool_call_id.length > 0
-        ) {
-          return `tool:call:${message.tool_call_id}`;
-        }
-        if (typeof message.id === 'string' && message.id.length > 0) {
-          return `${type}:id:${message.id}`;
-        }
-        return undefined;
-      };
-
-      /**
-       * Provider projections clone messages. Preserve their baseline origin
-       * without writing tracking metadata onto the wire. Synthetic fold
-       * messages intentionally remain unattributed and are charged in full.
-       */
-      const trackProviderMessageOrigins = (
-        before: BaseMessage[],
-        after: BaseMessage[]
-      ): BaseMessage[] => {
-        if (providerMessageBaseline == null || before === after) {
-          return after;
-        }
-        if (before.length === after.length) {
-          for (let i = 0; i < after.length; i++) {
-            const origin = providerMessageOrigins.get(before[i]);
-            if (
-              origin != null &&
-              !providerMessageOrigins.has(after[i]) &&
-              before[i].getType() === after[i].getType() &&
-              !isSyntheticProviderContextMessage(after[i])
-            ) {
-              providerMessageOrigins.set(after[i], origin);
-            }
-          }
-          return after;
-        }
-
-        const keyedOrigins = new Map<string, number | null>();
-        for (const message of before) {
-          const origin = providerMessageOrigins.get(message);
-          const key = getProviderMessageOriginKey(message);
-          if (origin == null || key == null) {
-            continue;
-          }
-          keyedOrigins.set(key, keyedOrigins.has(key) ? null : origin);
-        }
-        for (const message of after) {
-          if (
-            providerMessageOrigins.has(message) ||
-            isSyntheticProviderContextMessage(message)
-          ) {
-            continue;
-          }
-          const key = getProviderMessageOriginKey(message);
-          const origin = key != null ? keyedOrigins.get(key) : undefined;
-          if (origin != null) {
-            providerMessageOrigins.set(message, origin);
-          }
-        }
-        return after;
-      };
+      const contextPressure = createContextPressureMeter({
+        tokenCounter: agentContext.tokenCounter,
+        sourceMessages: messages,
+        retainedMessages: messagesToUse,
+        indexTokenCountMap: agentContext.indexTokenCountMap,
+        contextUsage,
+        instructionTokens: agentContext.instructionTokens,
+        calibrationRatio: agentContext.calibrationRatio,
+      });
+      const trackProviderMessageOrigins = contextPressure.trackProjection;
 
       if (agentContext.useLegacyContent) {
         const before = finalMessages;
@@ -3300,8 +3212,13 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         typeof lastMessageX.content === 'string'
       ) {
         const trimmed = lastMessageX.content.trim();
-        finalMessages[finalMessages.length - 2].content =
-          trimmed.length > 0 ? [{ type: 'text' as const, text: trimmed }] : '';
+        const before = finalMessages;
+        finalMessages = [...before];
+        finalMessages[finalMessages.length - 2] = cloneMessage(
+          lastMessageX,
+          trimmed.length > 0 ? [{ type: 'text' as const, text: trimmed }] : ''
+        );
+        finalMessages = trackProviderMessageOrigins(before, finalMessages);
       }
 
       const localProviderOverflowMeasurements = new WeakMap<
@@ -3311,123 +3228,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           estimatedPromptTokens: number;
         }
       >();
-      const measureProviderPayload = (
-        candidate: BaseMessage[],
-        contextBudgetOverride?: number,
-        forceRawRecount = false
-      ): {
-        fits: boolean;
-        projectedMessageTokens?: number;
-        availableMessageTokens?: number;
-        contextBudget?: number;
-        effectiveInstructionTokens?: number;
-      } => {
-        const contextBudget =
-          contextBudgetOverride ?? contextUsage?.contextBudget;
-        const effectiveInstructionTokens =
-          contextUsage?.effectiveInstructionTokens ??
-          (forceRawRecount ? agentContext.instructionTokens : undefined);
-        if (
-          agentContext.tokenCounter == null ||
-          contextBudget == null ||
-          effectiveInstructionTokens == null
-        ) {
-          return { fits: true };
-        }
-        const availableMessageTokens = Math.max(
-          0,
-          contextBudget - effectiveInstructionTokens
-        );
-        let usageRatio =
-          agentContext.calibrationRatio > 0 ? agentContext.calibrationRatio : 1;
-        if (
-          contextUsage?.calibrationRatio != null &&
-          contextUsage.calibrationRatio > 0
-        ) {
-          usageRatio = contextUsage.calibrationRatio;
-        }
-        if (forceRawRecount) {
-          usageRatio = Math.max(1, usageRatio);
-        }
-        const baselineRemaining = contextUsage?.remainingContextTokens;
-        const accountedMessageTokens =
-          !forceRawRecount &&
-          providerMessageBaseline != null &&
-          baselineRemaining != null &&
-          Number.isFinite(baselineRemaining)
-            ? availableMessageTokens -
-              Math.min(availableMessageTokens, Math.max(0, baselineRemaining))
-            : undefined;
-
-        let projectedMessageTokens: number;
-        if (accountedMessageTokens != null && providerMessageBaseline != null) {
-          const replyPrimerTokens = Math.round(
-            REPLY_PRIMER_TOKENS * usageRatio
-          );
-          const rawWeights: Record<string, number> = {};
-          let totalWeight = 0;
-          for (let i = 0; i < providerMessageBaseline.length; i++) {
-            const weight = providerMessageBaseline[i].accountingWeight;
-            rawWeights[i] = weight;
-            totalWeight += weight;
-          }
-          const attributableTokens =
-            totalWeight > 0
-              ? Math.min(
-                Math.max(0, accountedMessageTokens - replyPrimerTokens),
-                Math.round(totalWeight * usageRatio)
-              )
-              : 0;
-          const apportionedTokens =
-            totalWeight > 0
-              ? apportionTokenCounts(
-                rawWeights,
-                attributableTokens / totalWeight,
-                attributableTokens
-              )
-              : {};
-          const attributedByOrigin = providerMessageBaseline.map(
-            (_, origin) => apportionedTokens[origin] || 0
-          );
-          projectedMessageTokens = Math.max(
-            replyPrimerTokens,
-            accountedMessageTokens - attributableTokens
-          );
-          let newRawTokens = 0;
-          const usedOrigins = new Set<number>();
-          for (const message of candidate) {
-            const rawTokens = agentContext.tokenCounter(message);
-            const origin = providerMessageOrigins.get(message);
-            if (origin == null || usedOrigins.has(origin)) {
-              newRawTokens += rawTokens;
-              continue;
-            }
-            usedOrigins.add(origin);
-            projectedMessageTokens += Math.max(
-              0,
-              attributedByOrigin[origin] +
-                Math.round(
-                  (rawTokens - providerMessageBaseline[origin].rawTokens) *
-                    usageRatio
-                )
-            );
-          }
-          projectedMessageTokens += Math.round(newRawTokens * usageRatio);
-        } else {
-          let rawTokens = REPLY_PRIMER_TOKENS;
-          for (const message of candidate) {
-            rawTokens += agentContext.tokenCounter(message);
-          }
-          projectedMessageTokens = Math.round(rawTokens * usageRatio);
-        }
-        return {
-          fits: projectedMessageTokens <= availableMessageTokens,
-          projectedMessageTokens,
-          availableMessageTokens,
-          contextBudget,
-          effectiveInstructionTokens,
-        };
-      };
+      const measureProviderPayload = contextPressure.measure;
 
       const createProviderPayloadOverflowError = ({
         projection,
@@ -3782,10 +3583,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         finalMessages = trackProviderMessageOrigins(
           beforeSanitizeMessages,
           sanitizeOrphanToolBlocks(beforeSanitizeMessages, (source, clone) => {
-            const origin = providerMessageOrigins.get(source);
-            if (origin != null) {
-              providerMessageOrigins.set(clone, origin);
-            }
+            contextPressure.trackClone(source, clone);
           })
         );
         if (finalMessages.length !== beforeSanitize) {
@@ -3858,23 +3656,30 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
 
       const fallbackBaseMessages = finalMessages;
       const beforeFinalProviderProjection = fallbackBaseMessages;
-      finalMessages = trackProviderMessageOrigins(
-        beforeFinalProviderProjection,
-        projectMessagesForProvider({
-          model: (this.overrideModel ?? model) as t.ChatModel,
-          messages: beforeFinalProviderProjection,
-          provider: agentContext.provider,
-          maxToolResultChars: maxProviderToolResultChars,
-          callOptions: config,
-        })
-      );
+      const preparedRequest = prepareProviderRequest({
+        model: (this.overrideModel ?? model) as t.ChatModel,
+        messages: beforeFinalProviderProjection,
+        provider: agentContext.provider,
+        context: this,
+        config,
+        maxToolResultChars: maxProviderToolResultChars,
+        measure: (preparedMessages) =>
+          measureProviderPayload(
+            trackProviderMessageOrigins(
+              beforeFinalProviderProjection,
+              preparedMessages
+            )
+          ),
+      });
+      finalMessages = preparedRequest.messages;
 
       /**
        * Prompt-cache placement and orphan sanitization are provider-wire
        * transforms too. Re-measure after both so no content added after the
        * earlier artifact/synthetic compaction decision can bypass the guard.
        */
-      finalProjection = measureProviderPayload(finalMessages);
+      finalProjection =
+        preparedRequest.measurement ?? measureProviderPayload(finalMessages);
       const preInvokeContextOverflowError = !finalProjection.fits
         ? createProviderPayloadOverflowError({
           projection: finalProjection,
@@ -4083,9 +3888,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           () =>
             attemptInvoke(
               {
-                model: (this.overrideModel ?? model) as t.ChatModel,
-                messages: finalMessages,
-                provider: agentContext.provider,
+                request: preparedRequest,
                 context: this,
               },
               invokeConfig
@@ -4288,7 +4091,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                   estimatedPromptTokens: getEstimatedPromptTokens(contextUsage),
                   maxContextTokens: agentContext.maxContextTokens,
                 },
-                prepareProviderMessages: ({
+                prepareProviderRequest: ({
                   model: fallbackModel,
                   messages: fallbackMessages,
                   provider: fallbackProvider,
@@ -4300,36 +4103,6 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                     calculateMaxToolResultChars(
                       fallbackMaxContextTokens ?? agentContext.maxContextTokens
                     );
-                  /**
-                   * Serving-provider cue shaping BEFORE the fallback payload
-                   * is measured: a Claude fallback behind a tolerant primary
-                   * gains the cue inside the guarded projection (a prompt
-                   * within the cue's cost of the fallback budget must take
-                   * the recovery path, not ship oversized), and a tolerant
-                   * fallback behind an Anthropic primary sheds the baked cue
-                   * before it is measured against the tighter budget. The
-                   * attemptInvoke funnel pass then finds nothing to change.
-                   */
-                  const cueShapedFallbackMessages = trackProviderMessageOrigins(
-                    fallbackMessages,
-                    isAnthropicLike(fallbackProvider, {
-                      model: resolveServingModelId(fallbackModel),
-                    })
-                      ? appendPredecessorHandoffCue(fallbackMessages, (m) =>
-                        this.isRunProducedMessage(m)
-                      )
-                      : removePredecessorHandoffCue(fallbackMessages)
-                  );
-                  const projectedFallbackMessages = trackProviderMessageOrigins(
-                    cueShapedFallbackMessages,
-                    projectMessagesForProvider({
-                      model: fallbackModel,
-                      messages: cueShapedFallbackMessages,
-                      provider: fallbackProvider,
-                      maxToolResultChars: fallbackToolResultChars,
-                      callOptions: fallbackConfig,
-                    })
-                  );
                   const primaryContextBudget = contextUsage?.contextBudget;
                   const fallbackContextBudget =
                     fallbackMaxContextTokens == null
@@ -4338,11 +4111,31 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                         primaryContextBudget ?? fallbackMaxContextTokens,
                         fallbackMaxContextTokens
                       );
-                  const projection = measureProviderPayload(
-                    projectedFallbackMessages,
-                    fallbackContextBudget,
-                    true
-                  );
+                  const preparedFallbackRequest = prepareProviderRequest({
+                    model: fallbackModel,
+                    messages: fallbackMessages,
+                    provider: fallbackProvider,
+                    context: this,
+                    config: fallbackConfig,
+                    maxToolResultChars: fallbackToolResultChars,
+                    measure: (preparedMessages) =>
+                      measureProviderPayload(
+                        trackProviderMessageOrigins(
+                          fallbackMessages,
+                          preparedMessages
+                        ),
+                        {
+                          contextBudget: fallbackContextBudget,
+                          forceRawRecount: true,
+                        }
+                      ),
+                  });
+                  const projection =
+                    preparedFallbackRequest.measurement ??
+                    measureProviderPayload(preparedFallbackRequest.messages, {
+                      contextBudget: fallbackContextBudget,
+                      forceRawRecount: true,
+                    });
                   if (!projection.fits) {
                     throw createProviderPayloadOverflowError({
                       projection,
@@ -4350,7 +4143,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                       info: 'Fallback provider message formatting exceeded the context budget before invocation.',
                     });
                   }
-                  return projectedFallbackMessages;
+                  return preparedFallbackRequest;
                 },
               })
           );

package/src/index.ts

@@ -88,6 +88,14 @@ export type { SmoothItem, SmoothPiece } from './llm/stream/smoother';
 export { FakeChatModel, createFakeStreamingLLM } from './llm/fake';
 export { initializeModel } from './llm/init';
 export { attemptInvoke, tryFallbackProviders } from './llm/invoke';
+export { prepareProviderRequest } from './llm/prepareProviderRequest';
+export type {
+  PreparedProviderRequest,
+  PrepareProviderRequestParams,
+  ProviderMessageProjectionMode,
+  ProviderPayloadMeasurement,
+  ProviderRequestContext,
+} from './llm/prepareProviderRequest';
 export { canSealPreempt } from './llm/preempt';
 export { isThinkingEnabled, getMaxOutputTokensKey } from './llm/request';
 export {