@librechat/agents 3.8.0 → 3.8.2

package/src/graphs/Graph.ts

@@ -146,7 +146,10 @@ import {
   findCallback,
   type CallbackEntry,
 } from '@/utils/callbacks';
-import { PreparedSubagents, PreparedSubagentError } from '@/tools/preparedSubagents';
+import {
+  PreparedSubagents,
+  PreparedSubagentError,
+} from '@/tools/preparedSubagents';
 import { ToolNode as CustomToolNode, toolsCondition } from '@/tools/ToolNode';
 import { shouldTraceToolNodeForLangfuse } from '@/langfuseToolOutputTracing';
 import { createLocalCodingToolBundle } from '@/tools/local/LocalCodingTools';
@@ -154,20 +157,30 @@ import { SUBAGENT_REPLAY_CONTROLLER } from '@/tools/subagent/SubagentReplay';
 import { applyGraphRuntimeConfig } from '@/graphs/applyGraphRuntimeConfig';
 import { isFadingTier, isInformativeFadingTier } from '@/messages/fading';
 import { createContextPressureMeter } from '@/llm/contextPressureMeter';
+import { createToolHistoryPreparation } from '@/messages/toolHistoryProjection';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
-import { prepareProviderRequest } from '@/llm/prepareProviderRequest';
+import {
+  prepareProviderRequest,
+  usesNativeOpenAIResponses,
+} from '@/llm/prepareProviderRequest';
 import { createCloudflareCodingToolBundle } from '@/tools/cloudflare';
 import { calculateMaxToolCallInputChars } from '@/utils/truncation';
 import { prepareToolsForPromptCache } from '@/llm/promptCacheTools';
 import { providerRequiresStrictAlternation } from '@/llm/providers';
 import { buildSubagentToolParams } from '@/tools/SubagentTool';
 import { initializeLangfuseTracing } from '@/instrumentation';
-import { shouldTriggerSummarization } from '@/summarization';
+import {
+  ManualSummarizationSkippedError,
+  shouldTriggerSummarization,
+} from '@/summarization';
 import { isRunStepResumeState } from '@/tools/runStepResume';
 import { resolveLocalToolsForBinding } from '@/tools/local';
 import { createSummarizeNode } from '@/summarization/node';
+import {
+  createRemoveAllMessage,
+  messagesStateReducer,
+} from '@/messages/reducer';
 import { getTruncationStopReason } from '@/llm/truncation';
-import { messagesStateReducer } from '@/messages/reducer';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { AgentContext } from '@/agents/AgentContext';
 import { createFakeStreamingLLM } from '@/llm/fake';
@@ -1242,7 +1255,10 @@ export abstract class Graph<
   }> = new Set();
   private _subagentExecutors = new Set<SubagentExecutor>();
   readonly preparedSubagents = new PreparedSubagents();
-  protected readonly subagentToolNodes = new Map<string, CustomToolNode<t.BaseGraphState>>();
+  protected readonly subagentToolNodes = new Map<
+    string,
+    CustomToolNode<t.BaseGraphState>
+  >();
   public getOrCreateFileCheckpointer(): t.LocalFileCheckpointer | undefined {
     // Return the cached instance unconditionally if one exists. The
     // toolExecution check below decides whether to *create* a new
@@ -1404,13 +1420,15 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   ): StreamLimitExceededError | PreparedSubagentError | undefined {
     if (
       breakerSignal.aborted &&
-      (breakerSignal.reason instanceof StreamLimitExceededError || breakerSignal.reason instanceof PreparedSubagentError)
+      (breakerSignal.reason instanceof StreamLimitExceededError ||
+        breakerSignal.reason instanceof PreparedSubagentError)
     ) {
       return breakerSignal.reason;
     }
     if (
       this.signal?.aborted === true &&
-      (this.signal.reason instanceof StreamLimitExceededError || this.signal.reason instanceof PreparedSubagentError)
+      (this.signal.reason instanceof StreamLimitExceededError ||
+        this.signal.reason instanceof PreparedSubagentError)
     ) {
       return this.signal.reason;
     }
@@ -1463,6 +1481,12 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
    * cannot suppress an unrelated agent's turn in a multi-agent graph.
    */
   outputTruncatedIncomplete = false;
+  /**
+   * The agent a summarize-only run summarizes with. Set from the first agent
+   * input that opted in; while set, the model step after the summary routes
+   * to END, and a multi-agent workflow compiles to this agent alone.
+   */
+  summarizeOnlyAgentId?: string;
   /**
    * `stopReason` from a `PreemptBoundary` hook that halted the turn.
    *
@@ -1551,6 +1575,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         indexTokenCountMap,
         toolExecution
       );
+      if (agentConfig.summarizeOnly === true) {
+        this.summarizeOnlyAgentId ??= agentContext.agentId;
+      }
       if (calibrationRatio != null && calibrationRatio > 0) {
         agentContext.calibrationRatio = calibrationRatio;
       }
@@ -1573,7 +1600,33 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       this.agentContexts.set(agentConfig.agentId, agentContext);
     }
 
-    this.defaultAgentId = agents[0].agentId;
+    /** The run's agent: root trace identity and Langfuse routing follow it,
+     *  so a summarize-only run is attributed to the agent that summarizes. */
+    this.defaultAgentId = this.summarizeOnlyAgentId ?? agents[0].agentId;
+  }
+
+  /**
+   * A compaction applies its remove-all inside the agent subgraph, so the
+   * subgraph's result carries only the retained tail, and an outer reducer
+   * would merge that tail back into the history it already holds. Re-issuing
+   * the remove-all across the boundary keeps a checkpointed outer state as
+   * compacted as the subgraph's. A run that produced no summary changed
+   * nothing and passes through.
+   */
+  protected propagateManualCompaction<
+    S extends { messages: BaseMessage[]; manualSummary?: string },
+  >(result: S): S {
+    if (
+      this.summarizeOnlyAgentId == null ||
+      result.manualSummary == null ||
+      result.manualSummary.length === 0
+    ) {
+      return result;
+    }
+    return {
+      ...result,
+      messages: [createRemoveAllMessage(), ...result.messages],
+    };
   }
 
   /** Rotates the Langfuse identities that must never cross fresh executions. */
@@ -1957,8 +2010,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     this.nextContentIndex = state.nextIndex;
     this.runStepStateRevision = state.revision;
     this.stopContinuationCount = state.stopContinuationCount ?? 0;
-    this.stopContinuationExecutionId =
-      state.stopContinuationExecutionId ?? '';
+    this.stopContinuationExecutionId = state.stopContinuationExecutionId ?? '';
     this.streamSegment = state.streamSegment ?? 0;
     for (const { toolCallId, stepId } of state.toolCallSteps) {
       this.toolCallStepIds.set(toolCallId, stepId);
@@ -3086,6 +3138,79 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     });
   }
 
+  /**
+   * The two model steps of a summarize-only run, neither of which calls the
+   * model. The first requests the summary outright — no trigger consulted,
+   * because the user asked for it — and the second, entered after the
+   * summarize node, dispatches the post-summary usage snapshot (the host's
+   * gauge and summary baseline read it) and ends the run. Returns `null`
+   * for every other run so the ordinary step proceeds.
+   */
+  private async summarizeOnlyStep({
+    agentContext,
+    agentId,
+    messageCount,
+    contextUsage,
+    config,
+  }: {
+    agentContext: AgentContext;
+    agentId: string;
+    messageCount: number;
+    contextUsage: t.ContextUsageEvent | null;
+    config: RunnableConfig;
+  }): Promise<Partial<t.AgentSubgraphState> | null> {
+    if (agentContext.summarizeOnly !== true) {
+      return null;
+    }
+    const meta = { runId: this.runId, agentId };
+    if (agentContext.claimManualSummarization()) {
+      if (agentContext.summarizationEnabled !== true) {
+        throw new ManualSummarizationSkippedError(
+          'disabled',
+          'Compaction skipped: summarization is not enabled for this agent'
+        );
+      }
+      emitAgentLog(
+        config,
+        'info',
+        'graph',
+        'Manual summarization requested',
+        {
+          totalMessages: messageCount,
+          summaryVersion: agentContext.summaryVersion + 1,
+        },
+        meta
+      );
+      agentContext.markSummarizationTriggered(messageCount);
+      return {
+        summarizationRequest: {
+          remainingContextTokens: contextUsage?.remainingContextTokens ?? 0,
+          agentId: agentId || agentContext.agentId,
+          reason: 'manual',
+        },
+        /** A checkpointed thread may still hold the previous compaction's
+         *  summary; only the one this run produces may be reported. */
+        manualSummary: '',
+      };
+    }
+    if (contextUsage != null) {
+      await safeDispatchCustomEvent(
+        GraphEvents.ON_CONTEXT_USAGE,
+        contextUsage,
+        config
+      );
+    }
+    emitAgentLog(
+      config,
+      'debug',
+      'graph',
+      'Summarize-only run complete — ending without a model call',
+      { summaryVersion: agentContext.summaryVersion },
+      meta
+    );
+    return { messages: [] };
+  }
+
   createCallModel(agentId = 'default') {
     return async (
       state: t.AgentSubgraphState,
@@ -3143,35 +3268,6 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         agentContext.markToolsAsDiscovered(discoveredNames);
       }
 
-      /**
-       * Anthropic prompt-cache breakpoint on the tool definitions.
-       *
-       * Without this, the (often static) tool inventory shows up as
-       * fresh input on every turn — measured at ~28k tokens/turn for
-       * the local engine's coding-tool bundle, dominating per-turn
-       * cost even when message-level caching is on.
-       *
-       * Strategy: partition tools into [static, deferred] and stamp
-       * `cache_control: ephemeral` on the last static tool.
-       * Discovered deferred tools that arrive across turns sit *after*
-       * the breakpoint and don't invalidate the prefix.
-       */
-      const toolsForBinding = this.getPreparedToolsForBinding(agentContext);
-
-      let model =
-        this.overrideModel ??
-        initializeModel({
-          tools: toolsForBinding,
-          provider: agentContext.provider,
-          clientOptions: agentContext.clientOptions,
-        });
-
-      if (agentContext.systemRunnable) {
-        model = agentContext.systemRunnable
-          .pipe(model as Runnable)
-          .withConfig({ runName: AGENT_MODEL_CALL_RUN_NAME });
-      }
-
       if (agentContext.tokenCalculationPromise) {
         await agentContext.tokenCalculationPromise;
       }
@@ -3309,6 +3405,17 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         };
         syncBudgetDerivedFields(contextUsage);
 
+        const summarizeOnlyStep = await this.summarizeOnlyStep({
+          agentContext,
+          agentId,
+          messageCount: messages.length,
+          contextUsage,
+          config,
+        });
+        if (summarizeOnlyStep != null) {
+          return summarizeOnlyStep;
+        }
+
         const hasPrunedMessages =
           agentContext.summarizationEnabled === true &&
           Array.isArray(messagesToRefine) &&
@@ -3381,9 +3488,57 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             );
           }
         }
+      } else {
+        /** No pruner (no token counter or budget): the summarize-only run
+         *  still has to request its summary and stop, just without usage. */
+        const summarizeOnlyStep = await this.summarizeOnlyStep({
+          agentContext,
+          agentId,
+          messageCount: messages.length,
+          contextUsage: null,
+          config,
+        });
+        if (summarizeOnlyStep != null) {
+          return summarizeOnlyStep;
+        }
+      }
+
+      /**
+       * Anthropic prompt-cache breakpoint on the tool definitions.
+       *
+       * Without this, the (often static) tool inventory shows up as
+       * fresh input on every turn — measured at ~28k tokens/turn for
+       * the local engine's coding-tool bundle, dominating per-turn
+       * cost even when message-level caching is on.
+       *
+       * Strategy: partition tools into [static, deferred] and stamp
+       * `cache_control: ephemeral` on the last static tool.
+       * Discovered deferred tools that arrive across turns sit *after*
+       * the breakpoint and don't invalidate the prefix.
+       *
+       * Built only once a model call is certain: a summarize-only step
+       * returns above without one, and must not fail on a primary model
+       * it never invokes.
+       */
+      const toolsForBinding = this.getPreparedToolsForBinding(agentContext);
+
+      let model =
+        this.overrideModel ??
+        initializeModel({
+          tools: toolsForBinding,
+          provider: agentContext.provider,
+          clientOptions: agentContext.clientOptions,
+        });
+
+      if (agentContext.systemRunnable) {
+        model = agentContext.systemRunnable
+          .pipe(model as Runnable)
+          .withConfig({ runName: AGENT_MODEL_CALL_RUN_NAME });
       }
 
       let finalMessages = messagesToUse;
+      /** Primary wire shaping is lossy; each fallback starts from pruned source history. */
+      const fallbackBaseMessages = messagesToUse;
       /**
        * Keep the pruner's provider-grounded aggregate as the authoritative
        * baseline, then attribute it across retained messages. Provider
@@ -3392,6 +3547,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
        * the expansion. Exact counts are memoized across repeated projections.
        */
       const contextPressure = createContextPressureMeter({
+        provider: agentContext.provider,
         tokenCounter: agentContext.tokenCounter,
         tokenCountCache: agentContext.contextPressureTokenCounts,
         sourceMessages: messages,
@@ -3402,6 +3558,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         calibrationRatio: agentContext.calibrationRatio,
       });
       const trackProviderMessageOrigins = contextPressure.trackProjection;
+      const toolHistory = createToolHistoryPreparation();
 
       if (agentContext.useLegacyContent) {
         const before = finalMessages;
@@ -3419,7 +3576,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         beforeToolInputProjection,
         projectToolMessagesForProvider(
           beforeToolInputProjection,
-          calculateMaxToolCallInputChars(agentContext.maxContextTokens)
+          calculateMaxToolCallInputChars(agentContext.maxContextTokens),
+          agentContext.provider
         )
       );
 
@@ -3496,12 +3654,24 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       };
 
       const applyProviderMessageTransforms = (
-        candidate: BaseMessage[]
+        candidate: BaseMessage[],
+        serving?: {
+          provider: t.ProviderName;
+          clientOptions?: t.ClientOptions;
+          model: t.ChatModel;
+          config?: RunnableConfig;
+          history: ReturnType<typeof createToolHistoryPreparation>;
+        }
       ): BaseMessage[] => {
+        const provider = serving?.provider ?? agentContext.provider;
+        const clientOptions =
+          serving == null ? agentContext.clientOptions : serving.clientOptions;
+        const callConfig = serving == null ? config : serving.config;
+        const history = serving?.history ?? toolHistory;
+        const servingModel =
+          serving?.model ?? ((this.overrideModel ?? model) as t.ChatModel);
         let transformed = candidate;
-        if (
-          isThinkingEnabled(agentContext.provider, agentContext.clientOptions)
-        ) {
+        if (isThinkingEnabled(provider, clientOptions)) {
           /**
            * Current-run AI messages may validly omit a thinking block. The
            * boundary prevents them from being mistaken for foreign history.
@@ -3511,9 +3681,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             before,
             ensureThinkingBlockInMessages(
               before,
-              agentContext.provider,
-              config,
-              this.startIndex
+              provider,
+              callConfig,
+              this.startIndex,
+              history
             )
           );
         }
@@ -3526,7 +3697,12 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           const before = transformed;
           transformed = trackProviderMessageOrigins(
             before,
-            foldToolBlocksForToollessAgent(before, config)
+            foldToolBlocksForToollessAgent(
+              before,
+              callConfig,
+              usesNativeOpenAIResponses(servingModel, provider, callConfig),
+              history
+            )
           );
           if (agentContext.useLegacyContent) {
             const beforeLegacyFormat = transformed;
@@ -3545,12 +3721,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
          * tolerant fallback and adds it for a Claude fallback behind a
          * tolerant primary.
          */
-        if (
-          isAnthropicLike(
-            agentContext.provider,
-            agentContext.clientOptions as { model?: string }
-          )
-        ) {
+        if (isAnthropicLike(provider, clientOptions as { model?: string })) {
           const before = transformed;
           transformed = trackProviderMessageOrigins(
             before,
@@ -3573,7 +3744,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         );
 
       const compactSyntheticProviderContext = (
-        candidate: BaseMessage[]
+        candidate: BaseMessage[],
+        measure = measureProviderPayload
       ): BaseMessage[] => {
         const synthetic: Array<{
           index: number;
@@ -3611,7 +3783,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         };
 
         let best = buildCandidate(0);
-        if (!measureProviderPayload(best).fits) {
+        if (!measure(best).fits) {
           return candidate;
         }
         let low = 0;
@@ -3619,7 +3791,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         for (let i = 0; i < 12; i++) {
           const scale = (low + high) / 2;
           const attempt = buildCandidate(scale);
-          if (measureProviderPayload(attempt).fits) {
+          if (measure(attempt).fits) {
             best = attempt;
             low = scale;
           } else {
@@ -3629,27 +3801,83 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         return best;
       };
 
-      let artifactBaseMessages: BaseMessage[] | undefined;
-      if (lastMessageY instanceof ToolMessage) {
-        let artifactCandidate = finalMessages;
-        if (anthropicLike) {
-          artifactCandidate = trackProviderMessageOrigins(
-            finalMessages,
-            projectAnthropicArtifactContent(
-              finalMessages,
-              maxProviderToolResultChars
-            )
+      const projectServingArtifacts = (
+        candidate: BaseMessage[],
+        provider: t.ProviderName,
+        clientOptions: t.ClientOptions | undefined,
+        maxChars: number
+      ): BaseMessage[] => {
+        if (!(candidate[candidate.length - 1] instanceof ToolMessage)) {
+          return candidate;
+        }
+        if (isAnthropicLike(provider, clientOptions as { model?: string })) {
+          return trackProviderMessageOrigins(
+            candidate,
+            projectAnthropicArtifactContent(candidate, maxChars)
           );
-        } else if (
-          (isOpenAILike(agentContext.provider) &&
-            agentContext.provider !== Providers.DEEPSEEK) ||
-          isGoogleLike(agentContext.provider)
+        }
+        if (
+          (isOpenAILike(provider) && provider !== Providers.DEEPSEEK) ||
+          isGoogleLike(provider)
         ) {
-          artifactCandidate = trackProviderMessageOrigins(
-            finalMessages,
-            projectArtifactPayload(finalMessages, maxProviderToolResultChars)
+          return trackProviderMessageOrigins(
+            candidate,
+            projectArtifactPayload(candidate, maxChars)
           );
         }
+        return candidate;
+      };
+
+      const applyServingTailCache = (
+        candidate: BaseMessage[],
+        provider: t.ProviderName,
+        clientOptions: t.ClientOptions | undefined,
+        systemOwnsTail = false
+      ): BaseMessage[] => {
+        if (provider === Providers.BEDROCK) {
+          const options = clientOptions as
+            | t.BedrockAnthropicClientOptions
+            | undefined;
+          return options?.promptCache === true
+            ? trackProviderMessageOrigins(
+              candidate,
+              addBedrockTailCacheControl(
+                candidate,
+                resolveBedrockPromptCacheTtl(
+                  options.promptCacheTtl,
+                  options.model
+                )
+              )
+            )
+            : candidate;
+        }
+        if (
+          systemOwnsTail ||
+          (provider !== Providers.ANTHROPIC &&
+            provider !== Providers.OPENROUTER)
+        ) {
+          return candidate;
+        }
+        const options = clientOptions as t.AnthropicClientOptions | undefined;
+        return options?.promptCache === true
+          ? trackProviderMessageOrigins(
+            candidate,
+            addTailCacheControl(
+              candidate,
+              resolvePromptCacheTtl(options.promptCacheTtl)
+            )
+          )
+          : candidate;
+      };
+
+      let artifactBaseMessages: BaseMessage[] | undefined;
+      if (lastMessageY instanceof ToolMessage) {
+        const artifactCandidate = projectServingArtifacts(
+          finalMessages,
+          agentContext.provider,
+          agentContext.clientOptions,
+          maxProviderToolResultChars
+        );
 
         if (artifactCandidate !== finalMessages) {
           const projection = measureProviderPayload(artifactCandidate);
@@ -3843,51 +4071,14 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       // call (zero message caching). Anchoring on the final message list keeps
       // the marker on a block that actually ships. The system-runnable path
       // adds its body marker in AgentContext, so this node skips it there.
-      if (
-        (anthropicPromptCacheEnabled || openRouterPromptCacheEnabled) &&
-        !agentContext.systemRunnable
-      ) {
-        const beforeCacheControl = finalMessages;
-        finalMessages = trackProviderMessageOrigins(
-          beforeCacheControl,
-          addTailCacheControl<BaseMessage>(
-            beforeCacheControl,
-            resolvePromptCacheTtl(
-              anthropicPromptCacheEnabled
-                ? (
-                    agentContext.clientOptions as
-                      | t.AnthropicClientOptions
-                      | undefined
-                )?.promptCacheTtl
-                : (
-                    agentContext.clientOptions as
-                      | t.ProviderOptionsMap[Providers.OPENROUTER]
-                      | undefined
-                )?.promptCacheTtl
-            )
-          )
-        );
-      } else if (bedrockPromptCacheEnabled) {
-        const bedrockOptions = agentContext.clientOptions as
-          | t.BedrockAnthropicClientOptions
-          | undefined;
-        // Non-Claude models (Nova) reject the extended 1h TTL, so resolve it
-        // against the model — message/system caching stays on, clamped to 5m.
-        const beforeCacheControl = finalMessages;
-        finalMessages = trackProviderMessageOrigins(
-          beforeCacheControl,
-          addBedrockTailCacheControl<BaseMessage>(
-            beforeCacheControl,
-            resolveBedrockPromptCacheTtl(
-              bedrockOptions?.promptCacheTtl,
-              (bedrockOptions as { model?: string } | undefined)?.model
-            )
-          )
-        );
-      }
+      finalMessages = applyServingTailCache(
+        finalMessages,
+        agentContext.provider,
+        agentContext.clientOptions,
+        agentContext.systemRunnable != null
+      );
 
-      const fallbackBaseMessages = finalMessages;
-      const beforeFinalProviderProjection = fallbackBaseMessages;
+      const beforeFinalProviderProjection = finalMessages;
       const preparedRequest = prepareProviderRequest({
         model: (this.overrideModel ?? model) as t.ChatModel,
         messages: beforeFinalProviderProjection,
@@ -3895,6 +4086,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         context: this,
         config,
         maxToolResultChars: maxProviderToolResultChars,
+        toolHistory,
         measure: (preparedMessages) =>
           measureProviderPayload(
             trackProviderMessageOrigins(
@@ -4006,7 +4198,18 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               finalProjection.projectedMessageTokens
           );
         }
-        syncBudgetDerivedFields(contextUsage);
+        contextUsage.breakdown.toolMessageTokens =
+          finalProjection.toolMessageTokens;
+        contextUsage.breakdown.toolMessageTokenCounts =
+          finalProjection.toolMessageTokenCounts;
+        syncBudgetDerivedFields(
+          contextUsage,
+          undefined,
+          undefined,
+          config,
+          agentContext.provider,
+          finalProjection.toolMessageUsageError
+        );
         /** Awaited so async host handlers receive the pre-invoke snapshot
          *  before any model deltas are emitted */
         await safeDispatchCustomEvent(
@@ -4188,6 +4391,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         const canSummarizeOverflow =
           agentContext.summarizationEnabled === true &&
           splitAtRecencyBoundary(messages, {
+            provider: agentContext.provider,
             turns:
               agentContext.summarizationConfig?.retainRecent?.turns ??
               DEFAULT_RETAIN_RECENT_TURNS,
@@ -4344,9 +4548,11 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                   model: fallbackModel,
                   messages: fallbackMessages,
                   provider: fallbackProvider,
+                  clientOptions: fallbackClientOptions,
                   maxContextTokens: fallbackMaxContextTokens,
                   config: fallbackConfig,
                 }) => {
+                  const fallbackToolHistory = createToolHistoryPreparation();
                   const fallbackToolResultChars =
                     agentContext.maxToolResultChars ??
                     calculateMaxToolResultChars(
@@ -4360,31 +4566,112 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                         primaryContextBudget ?? fallbackMaxContextTokens,
                         fallbackMaxContextTokens
                       );
-                  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, {
+                  const measureFallback = (
+                    candidate: BaseMessage[]
+                  ): ReturnType<typeof measureProviderPayload> =>
+                    measureProviderPayload(candidate, {
                       contextBudget: fallbackContextBudget,
                       forceRawRecount: true,
                     });
+                  const source = agentContext.useLegacyContent
+                    ? trackProviderMessageOrigins(
+                      fallbackMessages,
+                      formatContentStrings(fallbackMessages)
+                    )
+                    : fallbackMessages;
+                  const boundedSource = trackProviderMessageOrigins(
+                    source,
+                    projectToolMessagesForProvider(
+                      source,
+                      calculateMaxToolCallInputChars(fallbackMaxContextTokens),
+                      fallbackProvider
+                    )
+                  );
+                  const artifactSource = projectServingArtifacts(
+                    boundedSource,
+                    fallbackProvider,
+                    fallbackClientOptions,
+                    fallbackToolResultChars
+                  );
+                  const transformFallback = (
+                    candidate: BaseMessage[]
+                  ): BaseMessage[] =>
+                    applyProviderMessageTransforms(candidate, {
+                      provider: fallbackProvider,
+                      clientOptions: fallbackClientOptions,
+                      model: fallbackModel,
+                      config: fallbackConfig,
+                      history: fallbackToolHistory,
+                    });
+                  const prepareFallback = (
+                    candidate: BaseMessage[]
+                  ): {
+                    request: ReturnType<typeof prepareProviderRequest>;
+                    projection: ReturnType<typeof measureProviderPayload>;
+                  } => {
+                    const sanitized = isAnthropicLike(
+                      fallbackProvider,
+                      fallbackClientOptions as { model?: string }
+                    )
+                      ? trackProviderMessageOrigins(
+                        candidate,
+                        sanitizeOrphanToolBlocks(
+                          candidate,
+                          (original, clone) =>
+                            contextPressure.trackClone(original, clone)
+                        )
+                      )
+                      : candidate;
+                    const cached = applyServingTailCache(
+                      sanitized,
+                      fallbackProvider,
+                      fallbackClientOptions
+                    );
+                    let projection: ReturnType<typeof measureProviderPayload> | undefined;
+                    const request = prepareProviderRequest({
+                      model: fallbackModel,
+                      messages: cached,
+                      provider: fallbackProvider,
+                      context: this,
+                      config: fallbackConfig,
+                      maxToolResultChars: fallbackToolResultChars,
+                      toolHistory: fallbackToolHistory,
+                      measure: (prepared) => {
+                        projection = measureFallback(
+                          trackProviderMessageOrigins(cached, prepared)
+                        );
+                        return projection;
+                      },
+                    });
+                    if (projection == null) {
+                      throw new Error('Fallback preparation did not measure its payload');
+                    }
+                    return { request, projection };
+                  };
+                  let servingFallbackMessages =
+                    transformFallback(artifactSource);
+                  let preparedFallbackRequest = prepareFallback(
+                    servingFallbackMessages
+                  );
+                  let projection = preparedFallbackRequest.projection;
+                  if (!projection.fits && artifactSource !== boundedSource) {
+                    servingFallbackMessages = transformFallback(boundedSource);
+                    preparedFallbackRequest = prepareFallback(
+                      servingFallbackMessages
+                    );
+                    projection = preparedFallbackRequest.projection;
+                  }
+                  if (!projection.fits) {
+                    const compacted = compactSyntheticProviderContext(
+                      servingFallbackMessages,
+                      (candidate) =>
+                        prepareFallback(candidate).projection
+                    );
+                    if (compacted !== servingFallbackMessages) {
+                      preparedFallbackRequest = prepareFallback(compacted);
+                      projection = preparedFallbackRequest.projection;
+                    }
+                  }
                   if (!projection.fits) {
                     throw createProviderPayloadOverflowError({
                       projection,
@@ -4392,7 +4679,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                       info: 'Fallback provider message formatting exceeded the context budget before invocation.',
                     });
                   }
-                  return preparedFallbackRequest;
+                  return preparedFallbackRequest.request;
                 },
               })
           );
@@ -5129,7 +5416,17 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       this.config = config;
       this.restoreRunStepResumeState(state.runStepState);
       const result = await invoke();
-      return { ...result, runStepState: this.createRunStepResumeState() };
+      /** An ordinary run on a checkpointed thread inherits the last
+       *  compaction's summary in state; it is not this run's output. */
+      const clearsManualSummary =
+        this.summarizeOnlyAgentId == null &&
+        typeof state.manualSummary === 'string' &&
+        state.manualSummary.length > 0;
+      return {
+        ...result,
+        ...(clearsManualSummary ? { manualSummary: '' } : {}),
+        runStepState: this.createRunStepResumeState(),
+      };
     };
 
     const routeMessage = (
@@ -5148,6 +5445,11 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       if (state.summarizationRequest != null) {
         return summarizeNode;
       }
+      /** A summarize-only run never calls the model, so the step after the
+       *  summary has nothing to route: the summary itself is the result. */
+      if (this.summarizeOnlyAgentId != null) {
+        return END;
+      }
       const decision = toolsCondition(
         state as t.BaseGraphState,
         toolNode,
@@ -5186,6 +5488,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         ) => b,
         default: () => undefined,
       }),
+      manualSummary: Annotation<string | undefined>({
+        reducer: (_: string | undefined, b: string | undefined) => b,
+        default: () => undefined,
+      }),
       runStepState: this.createRunStepStateAnnotation(),
     });
 
@@ -5395,15 +5701,27 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         },
         default: () => [],
       }),
+      /** Surfaced from the agent subgraph on a summarize-only run. */
+      manualSummary: Annotation<string | undefined>({
+        reducer: (_: string | undefined, b: string | undefined) => b,
+        default: () => undefined,
+      }),
       runStepState: this.createRunStepStateAnnotation(),
     });
+    const compactingAgentNode = async (
+      state: t.AgentSubgraphState,
+      config?: RunnableConfig
+    ): Promise<Partial<t.AgentSubgraphState>> =>
+      this.propagateManualCompaction(await agentNode.invoke(state, config));
     const workflow = new StateGraph(StateAnnotation)
       .addNode(
         this.defaultAgentId,
-        agentNode as Runnable<
-          t.AgentSubgraphState,
-          Partial<t.AgentSubgraphState>
-        >,
+        this.summarizeOnlyAgentId != null
+          ? compactingAgentNode
+          : (agentNode as Runnable<
+              t.AgentSubgraphState,
+              Partial<t.AgentSubgraphState>
+            >),
         { ends: [END] }
       )
       .addEdge(START, this.defaultAgentId);