@librechat/agents 3.7.8 → 3.7.10

package/src/summarization/index.ts

@@ -1,5 +1,16 @@
 import type { SummarizationTrigger } from '@/types';
 
+/**
+ * The summary-boundary seam a caller compacting outside a run needs. The two
+ * default prompts stay out of it: LibreChat's manual flow deliberately words
+ * its own, so exporting these would publish an API with no consumer.
+ */
+export {
+  buildSummarizationInstruction,
+  buildSummaryCarrierText,
+  separateSummarizationParameters,
+} from './shared';
+
 const VALID_TRIGGER_TYPES = [
   'token_ratio',
   'remaining_tokens',

package/src/summarization/node.ts

@@ -1,17 +1,20 @@
-import {
-  AIMessage,
-  ToolMessage,
-  HumanMessage,
-  SystemMessage,
-} from '@langchain/core/messages';
+import { AIMessage, ToolMessage, HumanMessage } from '@langchain/core/messages';
 import type { UsageMetadata, BaseMessage } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { RenderedCompactionSemanticIndex } from '@/summarization/semanticIndex';
 import type { StreamLimitState } from '@/llm/streamLimits';
 import type { AgentContext } from '@/agents/AgentContext';
+import type { EncodingName } from '@/utils/tokens';
 import type { HookRegistry } from '@/hooks';
 import type { OnChunk } from '@/llm/invoke';
 import type * as t from '@/types';
+import {
+  DEFAULT_SUMMARIZATION_PROMPT,
+  DEFAULT_UPDATE_SUMMARIZATION_PROMPT,
+  buildSummaryCarrierText,
+  separateSummarizationParameters,
+  buildSummarizationInstruction,
+} from './shared';
 import {
   addTailCacheControl,
   addBedrockTailCacheControl,
@@ -35,6 +38,11 @@ import {
   resolveIntraTurnRetainTokens,
   splitAtRecencyBoundary,
 } from '@/messages/recency';
+import {
+  createTokenCounter,
+  encodingForModel,
+  encodingOfTokenCounter,
+} from '@/utils/tokens';
 import {
   Constants,
   ContentTypes,
@@ -42,6 +50,10 @@ import {
   StepTypes,
   Providers,
 } from '@/common';
+import {
+  getMaxOutputTokensKey,
+  resolveClientOptionsModel,
+} from '@/llm/request';
 import { renderCompactionSemanticIndex } from '@/summarization/semanticIndex';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
 import { prepareToolsForPromptCache } from '@/llm/promptCacheTools';
@@ -49,13 +61,11 @@ import { attemptInvoke, tryFallbackProviders } from '@/llm/invoke';
 import { calculateMaxToolResultChars } from '@/utils/truncation';
 import { makeIsDeferred } from '@/messages/anthropicToolCache';
 import { createRemoveAllMessage } from '@/messages/reducer';
-import { getMaxOutputTokensKey } from '@/llm/request';
+import { getProviderFamily } from '@/llm/providerRegistry';
 import { initializeModel } from '@/llm/init';
 import { getChunkContent } from '@/stream';
 import { executeHooks } from '@/hooks';
 
-const SUMMARIZATION_PARAM_KEYS = new Set(['maxSummaryTokens']);
-
 /**
  * Default number of recent user-led turns preserved verbatim during
  * compaction.  A turn begins at a HumanMessage and includes every
@@ -66,89 +76,6 @@ const SUMMARIZATION_PARAM_KEYS = new Set(['maxSummaryTokens']);
  * `retainRecent.turns` to `0` reverts to the legacy "summarize every
  * message" behavior.
  */
-/**
- * Token overhead of the XML wrapper + instruction text added around the
- * summary at injection time in AgentContext.buildSystemRunnable:
- * `<summary>\n${text}\n</summary>\n\nYour context window was compacted...`
- * ~33 tokens on Anthropic, ~24-27 on OpenAI.  Using 33 as a safe ceiling.
- */
-const SUMMARY_WRAPPER_OVERHEAD_TOKENS = 33;
-
-/** Structured checkpoint prompt for fresh summarization (no prior summary). */
-export const DEFAULT_SUMMARIZATION_PROMPT = `Hold on, before you continue I need you to write me a checkpoint of everything so far. Your context window is filling up and this checkpoint replaces the messages above, so capture everything you need to pick right back up.
-
-Don't second-guess or fact-check anything you did, your tool results reflect exactly what happened. If a tool result appears truncated, that's just a display artifact from context management: the tool executed fully. Just record what you did and what you observed. Only the checkpoint, don't respond to me or continue the conversation.
-
-## Checkpoint
-
-## Goal
-What I asked you to do and any sub-goals you identified.
-
-## Constraints & Preferences
-Any rules, preferences, or configuration I established.
-
-## Progress
-### Done
-- What you completed and the outcomes
-
-### In Progress
-- What you're currently working on
-
-## Key Decisions
-Decisions you made and why.
-
-## Next Steps
-Concrete task actions remaining, in priority order.
-
-## Critical Context
-Exact identifiers, names, error messages, URLs, and details you need to preserve verbatim.
-
-Rules:
-- Record what you did and observed, don't judge or re-evaluate it
-- For each tool call: the tool name, key inputs, and the outcome
-- Preserve exact identifiers, names, errors, and references verbatim
-- Short declarative sentences
-- Skip empty sections`;
-
-/** Prompt for re-compaction when a prior summary exists. */
-export const DEFAULT_UPDATE_SUMMARIZATION_PROMPT = `Hold on again, update your checkpoint. Merge the new messages into your existing checkpoint and give me a single consolidated replacement.
-
-Keep it roughly the same length as your last checkpoint. Compress older details to make room for what's new, don't just append. Give recent actions more detail, compress older items to one-liners.
-
-Don't fact-check or second-guess anything, your tool results are ground truth. If a tool result appears truncated, that's just a display artifact: the tool executed fully. Only the checkpoint, don't respond to me or continue the conversation.
-
-Rules:
-- Merge new progress into existing sections, don't duplicate headers
-- Compress older completed items into one-line entries
-- Move items from "In Progress" to "Done" when you completed them
-- Update "Next Steps" to reflect current task priorities.
-- For each new tool call: the tool name, key inputs, and the outcome
-- Preserve exact identifiers, names, errors, and references verbatim
-- Skip empty sections`;
-
-function separateParameters(parameters: Record<string, unknown>): {
-  llmParams: Record<string, unknown>;
-  maxSummaryTokens?: number;
-} {
-  const llmParams: Record<string, unknown> = {};
-  let maxSummaryTokens: number | undefined;
-
-  for (const [key, value] of Object.entries(parameters)) {
-    if (SUMMARIZATION_PARAM_KEYS.has(key)) {
-      if (
-        key === 'maxSummaryTokens' &&
-        typeof value === 'number' &&
-        value > 0
-      ) {
-        maxSummaryTokens = value;
-      }
-    } else {
-      llmParams[key] = value;
-    }
-  }
-
-  return { llmParams, maxSummaryTokens };
-}
 
 /**
  * Generates a structural metadata summary without making an LLM call.
@@ -340,7 +267,7 @@ function buildSummarizationClientConfig(
     summarizationConfig?.updatePrompt ?? DEFAULT_UPDATE_SUMMARIZATION_PROMPT;
 
   const { llmParams, maxSummaryTokens: paramMaxSummaryTokens } =
-    separateParameters(parameters);
+    separateSummarizationParameters(parameters);
 
   const isSelfSummarize = provider === (agentContext.provider as string);
   const baseOptions =
@@ -375,23 +302,104 @@ function buildSummarizationClientConfig(
   };
 }
 
-/** Computes the token count for a summary, preferring provider output tokens when available. */
-function computeSummaryTokenCount(
+/**
+ * Sizes a summary from the text that will actually be re-injected, carrier
+ * included, so the stored count is a measurement rather than a body count plus
+ * a remembered constant.
+ *
+ * The provider's `output_tokens` is deliberately not consulted. On a reasoning
+ * summarizer the two diverge by the hidden thinking, which is billed but never
+ * written into the checkpoint, so using it here would make every later context
+ * calculation reserve room for tokens that are never sent. Provider usage stays
+ * exclusively a billing input.
+ *
+ * A missing host counter is not hypothetical: `shouldSummarizeOverflow` fires
+ * precisely when there is nothing to count with, so that branch is the
+ * overflow-recovery summary, and its count is persisted and then reserved by
+ * `AgentContext.instructionTokens` on the retry. Undercounting it is what makes
+ * the retry overflow again, which rules out a character heuristic: measured
+ * against `o200k_base` and Anthropic's tokenizer, four-characters-per-token
+ * understates base64 by 1.5x and Korean by 4.6x, and coefficients large enough
+ * to cover those overestimate English prose by roughly 4x. So this falls back
+ * to the tokenizer this package already bundles rather than to an estimate.
+ *
+ * A host counter that is present is not automatically the right one either. In
+ * a heterogeneous multi-agent run `Run.create` derives a single counter from
+ * `agents[0]` and `StandardGraph` hands that same counter to every
+ * `AgentContext`, so a Claude agent behind a GPT first agent would otherwise
+ * measure its carrier in `o200k_base` and under-reserve by up to 1.9x on CJK.
+ * When the counter came from `createTokenCounter` its encoding is known, so a
+ * disagreement with the receiving agent's encoding takes the bundled path
+ * instead. A counter the host built itself is unstamped and stays authoritative:
+ * its units are the ones the rest of that host's accounting is denominated in.
+ */
+async function computeSummaryTokenCount(
   summaryText: string,
-  summaryUsage: Partial<UsageMetadata> | undefined,
-  tokenCounter?: (message: BaseMessage) => number
-): number {
-  const providerOutputTokens = Number(summaryUsage?.output_tokens) || 0;
-  if (providerOutputTokens > 0) {
-    return providerOutputTokens + SUMMARY_WRAPPER_OVERHEAD_TOKENS;
+  agentContext: AgentContext
+): Promise<number> {
+  const carrier = new HumanMessage(buildSummaryCarrierText(summaryText));
+  const encoding = encodingForReceivingAgent(agentContext);
+  const hostCounter = agentContext.tokenCounter;
+  const hostEncoding =
+    hostCounter != null ? encodingOfTokenCounter(hostCounter) : undefined;
+  if (
+    hostCounter != null &&
+    (hostEncoding == null || hostEncoding === encoding)
+  ) {
+    return hostCounter(carrier);
   }
-  if (tokenCounter) {
-    return (
-      tokenCounter(new SystemMessage(summaryText)) +
-      SUMMARY_WRAPPER_OVERHEAD_TOKENS
-    );
+  const bundledCounter = await createTokenCounter(encoding);
+  return bundledCounter(carrier);
+}
+
+/**
+ * Encoding of the model that will *receive* the carrier.
+ *
+ * That is the agent's own model, never the summarizer's. The two are the same
+ * only by default: `summarizationConfig.model` is undefined for ordinary
+ * self-summarization and can name a different provider entirely when a cheap
+ * dedicated summarizer is configured. The count produced here is spent by
+ * `AgentContext.instructionTokens` against the agent's context window, so it
+ * has to be denominated in the agent's tokenizer, and Anthropic's counts run
+ * well above `o200k_base` on the same text: measuring CJK with the wrong one
+ * understates it by up to 1.9x.
+ *
+ * Both signals are read, because only one of them can ever be positive.
+ * `encodingForModel` matches the substring `claude`, so a name it accepts is
+ * proof, which is what keeps a Claude model reached through Bedrock or
+ * OpenRouter resolving to `claude`. A name it rejects is only the absence of
+ * proof: `production` is an opaque deployment alias, not a statement that the
+ * model behind it is something other than Claude. Both option keys are
+ * consulted for that name, since `modelName` is LangChain's alias for `model`
+ * and hosts configure agents through either, so reading one key alone would
+ * report an unconfigured model and quietly hand a Claude agent the
+ * `o200k_base` tokenizer.
+ *
+ * The provider therefore decides every case the name leaves open, not just the
+ * case where no model was recorded at all, and it is read as a family rather
+ * than as one enum value: a host can register its own provider with
+ * `family: 'anthropic'` (the trait `isThinkingEnabled` already reads the same
+ * way), and such a provider serves Claude behind whatever name and deployment
+ * alias the host chose. `BEDROCK` is left out by the same rule, since its
+ * family is `bedrock` and it also serves Llama, Titan and Mistral. The enum
+ * check stays ahead of the family lookup because the registry is populated by
+ * importing `@/llm/providers`, which a root-barrel consumer defers.
+ *
+ * On an opaque alias this deliberately parts ways with `Run.create`, which
+ * infers from the model name alone and stamps its counter `o200k_base`. That
+ * stamp records which tokenizer the counter is, not which one the agent needs,
+ * so the disagreement routes the carrier to the bundled Claude tokenizer by
+ * the same rule that rejects another agent's counter.
+ */
+function encodingForReceivingAgent(agentContext: AgentContext): EncodingName {
+  const model = resolveClientOptionsModel(agentContext.clientOptions);
+  if (model != null && encodingForModel(model) === 'claude') {
+    return 'claude';
   }
-  return 0;
+  return agentContext.provider === Providers.ANTHROPIC ||
+    getProviderFamily(agentContext.provider) === 'anthropic'
+    ? 'claude'
+    : 'o200k_base';
 }
 
 /**
@@ -1470,10 +1478,9 @@ export function createSummarizeNode({
 
     const summaryText = enrichSummary(rawText, messagesToRefine);
 
-    const tokenCount = computeSummaryTokenCount(
+    const tokenCount = await computeSummaryTokenCount(
       summaryText,
-      summaryUsage,
-      agentContext.tokenCounter
+      agentContext
     );
 
     if (usedIntraTurnFallback) {
@@ -1600,26 +1607,6 @@ function extractResponseText(response: { content: string | object }): string {
   return parts.join('').trim();
 }
 
-function buildSummarizationInstruction(
-  promptText: string,
-  updatePromptText: string | undefined,
-  priorSummaryText: string,
-  semanticIndexAppendix = ''
-): string {
-  const effectivePrompt = priorSummaryText
-    ? (updatePromptText ?? promptText)
-    : promptText;
-  const parts = semanticIndexAppendix
-    ? [semanticIndexAppendix, '\n\n', effectivePrompt]
-    : [effectivePrompt];
-  if (priorSummaryText) {
-    parts.push(
-      `\n\n<previous-summary>\n${priorSummaryText}\n</previous-summary>`
-    );
-  }
-  return parts.join('');
-}
-
 /** Creates an `onChunk` callback that dispatches `ON_SUMMARIZE_DELTA` events for streaming. */
 export function createSummarizationChunkHandler({
   stepId,

package/src/summarization/semanticIndex.ts

@@ -50,6 +50,13 @@ export function setCompactionSemanticIndexProvidedEntryCount(
   snapshotProvidedEntryCounts.set(index, providedEntryCount);
 }
 
+/** Reads producer-side cardinality without exposing snapshot bookkeeping. */
+export function getCompactionSemanticIndexProvidedEntryCount(
+  index: CompactionSemanticIndex
+): number {
+  return snapshotProvidedEntryCounts.get(index) ?? index.length;
+}
+
 type SourceReference = {
   contentOrders: Map<number, number>;
 };
@@ -102,10 +109,13 @@ function snapshotEntry(
   } = entry;
   if (
     typeof sourceMessageId !== 'string' ||
-    sourceMessageId.length >
-      COMPACTION_SEMANTIC_INDEX_LIMITS.maxIdentityChars ||
-    typeof sourceContentIndex !== 'number' ||
-    typeof revision !== 'number' ||
+    normalizeIdentity(sourceMessageId) == null ||
+    !Number.isSafeInteger(sourceContentIndex) ||
+    sourceContentIndex < 0 ||
+    sourceContentIndex >
+      COMPACTION_SEMANTIC_INDEX_LIMITS.maxSourceContentIndex ||
+    !Number.isSafeInteger(revision) ||
+    revision < 0 ||
     !VALID_ENTRY_TYPES.has(type)
   ) {
     return undefined;
@@ -143,14 +153,13 @@ function snapshotEntry(
   if (type === 'reasoning_label') {
     const reasoningStepId = entry.reasoningStepId;
     return typeof reasoningStepId === 'string' &&
-      reasoningStepId.length <=
-        COMPACTION_SEMANTIC_INDEX_LIMITS.maxIdentityChars
+      normalizeIdentity(reasoningStepId) != null
       ? Object.freeze({ type, reasoningStepId, ...common })
       : undefined;
   }
   const toolCallId = entry.toolCallId;
   return typeof toolCallId === 'string' &&
-    toolCallId.length <= COMPACTION_SEMANTIC_INDEX_LIMITS.maxIdentityChars
+    normalizeIdentity(toolCallId) != null
     ? Object.freeze({ type, toolCallId, ...common })
     : undefined;
 }

package/src/summarization/shared.ts

@@ -0,0 +1,130 @@
+/**
+ * Summarization primitives shared by the in-run summarize node and by callers
+ * that compact a conversation outside a run. Kept apart from `node.ts` so the
+ * package can export them without exporting the graph node itself.
+ */
+
+/**
+ * Instruction that follows the summary body inside the carrier. Private on
+ * purpose: it is only ever correct alongside `buildSummaryCarrierText`, and a
+ * caller that reaches for the text separately is a caller that can drift from
+ * the accounting.
+ */
+const SUMMARY_CARRIER_INSTRUCTION =
+  'This is your own checkpoint: you wrote it to preserve context after compaction. Pick up where you left off based on the summary above. Do not repeat prior tasks, information or acknowledge this checkpoint message directly.';
+
+/**
+ * Wraps a persisted summary in the carrier it is re-injected as, ahead of the
+ * messages that survived compaction.
+ *
+ * A stored summary costs what this returns, not what its body costs, so a
+ * caller budgeting for one measures this rather than adding a remembered
+ * constant to the bare text. The wrapper alone is ~48 tokens on `o200k_base`
+ * and more on Anthropic: too much to leave out of a context calculation, and
+ * too easy to get wrong from memory once the instruction is edited.
+ */
+export function buildSummaryCarrierText(summaryText: string): string {
+  return (
+    '<summary>\n' +
+    summaryText +
+    '\n</summary>\n\n' +
+    SUMMARY_CARRIER_INSTRUCTION
+  );
+}
+
+/** Structured checkpoint prompt for fresh summarization (no prior summary). */
+export const DEFAULT_SUMMARIZATION_PROMPT = `Hold on, before you continue I need you to write me a checkpoint of everything so far. Your context window is filling up and this checkpoint replaces the messages above, so capture everything you need to pick right back up.
+
+Don't second-guess or fact-check anything you did, your tool results reflect exactly what happened. If a tool result appears truncated, that's just a display artifact from context management: the tool executed fully. Just record what you did and what you observed. Only the checkpoint, don't respond to me or continue the conversation.
+
+## Checkpoint
+
+## Goal
+What I asked you to do and any sub-goals you identified.
+
+## Constraints & Preferences
+Any rules, preferences, or configuration I established.
+
+## Progress
+### Done
+- What you completed and the outcomes
+
+### In Progress
+- What you're currently working on
+
+## Key Decisions
+Decisions you made and why.
+
+## Next Steps
+Concrete task actions remaining, in priority order.
+
+## Critical Context
+Exact identifiers, names, error messages, URLs, and details you need to preserve verbatim.
+
+Rules:
+- Record what you did and observed, don't judge or re-evaluate it
+- For each tool call: the tool name, key inputs, and the outcome
+- Preserve exact identifiers, names, errors, and references verbatim
+- Short declarative sentences
+- Skip empty sections`;
+
+/** Prompt for re-compaction when a prior summary exists. */
+export const DEFAULT_UPDATE_SUMMARIZATION_PROMPT = `Hold on again, update your checkpoint. Merge the new messages into your existing checkpoint and give me a single consolidated replacement.
+
+Keep it roughly the same length as your last checkpoint. Compress older details to make room for what's new, don't just append. Give recent actions more detail, compress older items to one-liners.
+
+Don't fact-check or second-guess anything, your tool results are ground truth. If a tool result appears truncated, that's just a display artifact: the tool executed fully. Only the checkpoint, don't respond to me or continue the conversation.
+
+Rules:
+- Merge new progress into existing sections, don't duplicate headers
+- Compress older completed items into one-line entries
+- Move items from "In Progress" to "Done" when you completed them
+- Update "Next Steps" to reflect current task priorities.
+- For each new tool call: the tool name, key inputs, and the outcome
+- Preserve exact identifiers, names, errors, and references verbatim
+- Skip empty sections`;
+
+const SUMMARIZATION_PARAM_KEYS = new Set(['maxSummaryTokens']);
+
+export function separateSummarizationParameters(
+  parameters: Record<string, unknown>
+): {
+  llmParams: Record<string, unknown>;
+  maxSummaryTokens?: number;
+} {
+  const llmParams: Record<string, unknown> = {};
+  let maxSummaryTokens: number | undefined;
+
+  for (const [key, value] of Object.entries(parameters)) {
+    if (SUMMARIZATION_PARAM_KEYS.has(key)) {
+      if (
+        key === 'maxSummaryTokens' &&
+        typeof value === 'number' &&
+        value > 0
+      ) {
+        maxSummaryTokens = value;
+      }
+    } else {
+      llmParams[key] = value;
+    }
+  }
+
+  return { llmParams, maxSummaryTokens };
+}
+
+export function buildSummarizationInstruction(
+  promptText: string,
+  updatePromptText: string | undefined,
+  priorSummaryText?: string,
+  semanticIndexAppendix = ''
+): string {
+  const prior = priorSummaryText?.trim() ?? '';
+  const effectivePrompt = prior ? (updatePromptText ?? promptText) : promptText;
+  const parts = semanticIndexAppendix
+    ? [semanticIndexAppendix, '\n\n', effectivePrompt]
+    : [effectivePrompt];
+  if (prior) {
+    parts.push(`\n\n<previous-summary>\n${prior}\n</previous-summary>`);
+  }
+  return parts.join('');
+}

package/src/tools/runStepResume.ts

@@ -23,6 +23,15 @@ export function isRunStepResumeState(
     (state.revision ?? -1) < 0 ||
     !Number.isSafeInteger(state.nextIndex) ||
     (state.nextIndex ?? -1) < 0 ||
+    (state.stopContinuationCount != null &&
+      (!Number.isSafeInteger(state.stopContinuationCount) ||
+        state.stopContinuationCount < 0)) ||
+    (state.stopContinuationExecutionId != null &&
+      (typeof state.stopContinuationExecutionId !== 'string' ||
+        state.stopContinuationExecutionId.length === 0)) ||
+    (state.streamSegment != null &&
+      (!Number.isSafeInteger(state.streamSegment) ||
+        state.streamSegment < 0)) ||
     !Array.isArray(state.toolCallSteps) ||
     !Array.isArray(state.steps)
   ) {