Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🧾 fix: Count the Tool Results a Tool-Limit Stop Retains (#15893)

Marco Berettae95e696d70a3
diff --git a/api/server/controllers/agents/__tests__/callbacks.spec.js b/api/server/controllers/agents/__tests__/callbacks.spec.js
index cd9c1cd2ae..318adaf8bc 100644
--- a/api/server/controllers/agents/__tests__/callbacks.spec.js
+++ b/api/server/controllers/agents/__tests__/callbacks.spec.js
@@ -24,6 +24,7 @@ jest.mock('@librechat/api', () => ({
),
isCodeArtifactToolOutput: jest.requireActual('@librechat/api').isCodeArtifactToolOutput,
isCodeSessionToolName: jest.requireActual('@librechat/api').isCodeSessionToolName,
+ collectToolCallIds: jest.requireActual('@librechat/api').collectToolCallIds,
}));
jest.mock('@librechat/data-schemas', () => ({
@@ -210,10 +211,17 @@ describe('resumable event generation fencing', () => {
);
const contextUsageSink = { latest: null, count: 0, onSnapshot };
const usageEmitSink = [{ input_tokens: 10 }];
+ /** The call this snapshot already accounts for: a later tool-limit stop counts
+ * the results of the calls missing from this set. */
+ const contentParts = [
+ { type: 'text', text: 'answering' },
+ { type: 'tool_call', tool_call: { id: 'call_1', name: 'grep' } },
+ ];
const data = { contextBudget: 1000, remainingContextTokens: 400 };
const handlers = getDefaultHandlers({
res: { write: jest.fn() },
aggregateContent: jest.fn(),
+ contentParts,
toolEndCallback: jest.fn(),
collectedUsage: [],
streamId: 'conversation-1',
@@ -230,7 +238,12 @@ describe('resumable event generation fencing', () => {
});
await Promise.resolve();
- expect(contextUsageSink).toMatchObject({ latest: data, count: 1, latestUsageIndex: 1 });
+ expect(contextUsageSink).toMatchObject({
+ latest: data,
+ count: 1,
+ latestUsageIndex: 1,
+ latestToolCallIds: new Set(['call_1']),
+ });
expect(onSnapshot).toHaveBeenCalledTimes(1);
expect(settled).toBe(false);
releaseSnapshot();
diff --git a/api/server/controllers/agents/__tests__/client.contextMetadata.spec.js b/api/server/controllers/agents/__tests__/client.contextMetadata.spec.js
index 6df38efb6c..6fe18af863 100644
--- a/api/server/controllers/agents/__tests__/client.contextMetadata.spec.js
+++ b/api/server/controllers/agents/__tests__/client.contextMetadata.spec.js
@@ -1,3 +1,12 @@
+/** The counting itself is exercised in packages/api (it needs a loaded encoding,
+ * which this environment cannot load); here the resolver stands in so the WIRING
+ * is pinned: which content the save path hands it, and where its figure lands. */
+const mockResolveRetainedToolTokens = jest.fn();
+jest.mock('@librechat/api', () => ({
+ ...jest.requireActual('@librechat/api'),
+ resolveRetainedToolTokens: (...args) => mockResolveRetainedToolTokens(...args),
+}));
+
const AgentClient = require('../client');
/** Minimal post-(maybe-)summary snapshot. baseUsed = maxContextTokens(1000) -
@@ -34,18 +43,41 @@ const primaryFor = (runId, output_tokens) => ({
runId,
});
-function buildMeta({ snap, latestUsageIndex, usageEvents }) {
+const toolPart = (id, name, output) => ({
+ type: 'tool_call',
+ tool_call: { id, name, args: '{"path":"a"}', output },
+});
+
+function buildMeta({
+ snap,
+ latestUsageIndex,
+ usageEvents,
+ stepLimitReached = false,
+ latestToolCallIds,
+ contentParts,
+ maxRetainedToolCountChars,
+}) {
const self = {
collectedThoughtSignatures: null,
usageEmitSink: usageEvents,
+ stepLimitReached,
+ contentParts,
+ getEncoding: () => 'o200k_base',
+ options: {
+ req: { config: { endpoints: { agents: { maxRetainedToolCountChars } } } },
+ },
contextUsageSink: snap
- ? { latest: snap, count: 1, latestUsageIndex }
+ ? { latest: snap, count: 1, latestUsageIndex, latestToolCallIds }
: { latest: null, count: 0 },
};
return AgentClient.prototype.buildResponseMetadata.call(self);
}
describe('AgentClient.buildResponseMetadata — snapshot persistence + summary marker', () => {
+ beforeEach(() => {
+ mockResolveRetainedToolTokens.mockReset();
+ });
+
it('persists the snapshot when a primary usage follows it (normal turn)', () => {
const meta = buildMeta({ snap: snapshot(0), latestUsageIndex: 0, usageEvents: [primary] });
expect(meta.contextUsage).toBeDefined();
@@ -136,4 +168,54 @@ describe('AgentClient.buildResponseMetadata — snapshot persistence + summary m
/** run-1's own primary follows the snapshot → snapshot persisted with output 5. */
expect(meta.contextUsage.completedOutputTokens).toBe(5);
});
+
+ /** A turn that stops at the tool-call limit keeps the results of the tools its
+ * final call ran. The snapshot describing that call precedes them and no further
+ * call is made, so the counted figure has to ride along or the client's gauge
+ * misses the retained result until the next turn. */
+ it('hands the resolver this snapshot’s call boundary and persists its figure', () => {
+ mockResolveRetainedToolTokens.mockReturnValue(180);
+ const contentParts = [
+ toolPart('call_1', 'grep', 'the result the snapshot already counts'),
+ toolPart('call_2', 'read_file', 'the retained result'),
+ ];
+ const latestToolCallIds = new Set(['call_1']);
+ const meta = buildMeta({
+ snap: snapshot(0),
+ latestUsageIndex: 0,
+ usageEvents: [primary],
+ stepLimitReached: true,
+ latestToolCallIds,
+ contentParts,
+ maxRetainedToolCountChars: 1_048_576,
+ });
+ expect(mockResolveRetainedToolTokens).toHaveBeenCalledWith({
+ stoppedAtToolLimit: true,
+ contentParts,
+ /** The calls the snapshot already saw; only the rest are retained. */
+ priorToolCallIds: latestToolCallIds,
+ encoding: 'o200k_base',
+ /** The deployment's ceiling on the tokenization this costs. */
+ maxCountChars: 1_048_576,
+ });
+ expect(meta.contextUsage.retainedToolTokens).toBe(180);
+ });
+
+ it('reports a turn that did not stop at the tool-call limit as such', () => {
+ mockResolveRetainedToolTokens.mockReturnValue(undefined);
+ const meta = buildMeta({
+ snap: snapshot(0),
+ latestUsageIndex: 0,
+ usageEvents: [primary],
+ latestToolCallIds: new Set(),
+ contentParts: [toolPart('call_1', 'read_file', 'a result the next call re-counted')],
+ });
+ expect(mockResolveRetainedToolTokens).toHaveBeenCalledWith(
+ expect.objectContaining({ stoppedAtToolLimit: false }),
+ );
+ /** Nothing to add, so the blob stays exactly as it was before this change. */
+ expect(Object.prototype.hasOwnProperty.call(meta.contextUsage, 'retainedToolTokens')).toBe(
+ false,
+ );
+ });
});
diff --git a/api/server/controllers/agents/callbacks.js b/api/server/controllers/agents/callbacks.js
index 6c295b6568..4b27bde7fe 100644
--- a/api/server/controllers/agents/callbacks.js
+++ b/api/server/controllers/agents/callbacks.js
@@ -31,6 +31,7 @@ const {
shouldSignalSandboxStart,
getToolInputValidationDetails,
captureSubagentIdentity,
+ collectToolCallIds,
} = require('@librechat/api');
const { processFileCitations } = require('~/server/services/Files/Citations');
const { processCodeOutput, runPreviewFinalize } = require('~/server/services/Files/Code/process');
@@ -385,7 +386,9 @@ function feedSubagentAggregator(aggregator, event) {
* @param {UsageCostDeps} [options.usageCost] - Pricing context for authoritative per-event cost.
* @param {{ latest: TContextUsageEvent | null, count: number }} [options.contextUsageSink] - Mutable
* holder for the latest visible context snapshot + a count of visible snapshots (model calls),
- * used to persist the breakdown only when the final call emitted usage.
+ * used to persist the breakdown only when the final call emitted usage. Also records that
+ * snapshot's position in the usage stream and in `contentParts`, so the save path can tell
+ * which usage events and which content parts came after it.
* @param {Array<TTokenUsageEvent>} [options.usageEmitSink] - Array collecting each emitted
* `on_token_usage` payload (incl. cost) so the response's usage rollup can be persisted.
* @param {(toolName: string, agentId?: string) => string | undefined} [options.resolveMcpServerName]
@@ -851,6 +854,13 @@ function getDefaultHandlers({
contextUsageSink.latest = data;
contextUsageSink.count = (contextUsageSink.count ?? 0) + 1;
contextUsageSink.latestUsageIndex = usageEmitSink?.length ?? 0;
+ /** Which tool calls this snapshot already accounts for. A turn that
+ * stops at the tool-call limit counts the results of the calls missing
+ * from this set — the ones its own call produced, which no later
+ * snapshot describes. Ids, not a content index: completion reshapes the
+ * array (skill cards unshifted, hidden sequential output filtered), so
+ * an index recorded here would mean something else by save time. */
+ contextUsageSink.latestToolCallIds = collectToolCallIds(contentParts);
}
/** Every agent's snapshot publishes the run's context meta, hidden
* sequential agents included: their model calls latch tiers too, and a
diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.js
index c1fd96a5b9..5b9b955257 100644
--- a/api/server/controllers/agents/client.js
+++ b/api/server/controllers/agents/client.js
@@ -34,6 +34,7 @@ const {
aggregateEmittedUsage,
resolveAgentTokenConfig,
buildPersistedContextUsage,
+ resolveRetainedToolTokens,
computeSummaryUsedTokens,
priorRunOutputTokens,
createSubagentUsageSink,
@@ -3596,7 +3597,19 @@ class AgentClient extends BaseClient {
event.runId === latestSnapshotRunId),
);
if (latestSnapshot && hasPrimaryAfterSnapshot) {
- metadata.contextUsage = buildPersistedContextUsage(latestSnapshot, usageEvents);
+ /** The counted tool results this turn keeps past that snapshot — only a
+ * tool-call-limit stop has any; see `resolveRetainedToolTokens`. */
+ metadata.contextUsage = buildPersistedContextUsage(latestSnapshot, usageEvents, {
+ retainedToolTokens: resolveRetainedToolTokens({
+ stoppedAtToolLimit: this.stepLimitReached === true,
+ contentParts: this.contentParts,
+ priorToolCallIds: this.contextUsageSink?.latestToolCallIds,
+ encoding: this.getEncoding(),
+ maxCountChars:
+ this.options?.req?.config?.endpoints?.[EModelEndpoint.agents]
+ ?.maxRetainedToolCountChars,
+ }),
+ });
}
/** Lightweight summarization marker — persisted whenever this turn compacted
* the context, INDEPENDENT of the snapshot guard above. When the client has
diff --git a/client/src/components/Chat/Input/TokenUsage/Breakdown.spec.tsx b/client/src/components/Chat/Input/TokenUsage/Breakdown.spec.tsx
index 2b3eb89c2b..756e6e4612 100644
--- a/client/src/components/Chat/Input/TokenUsage/Breakdown.spec.tsx
+++ b/client/src/components/Chat/Input/TokenUsage/Breakdown.spec.tsx
@@ -322,6 +322,39 @@ describe('TokenUsage Breakdown', () => {
expect(rowFor('com_ui_context_messages').textContent).toContain('400');
expect(rowFor('com_ui_context_tool_calls').textContent).toContain('150');
});
+
+ it('widens the tool-call row for retained results without exceeding used tokens', async () => {
+ const retainedToolSplit = JSON.parse(JSON.stringify(toolSplitView)) as TokenUsageView;
+ retainedToolSplit.usedTokens = 1075;
+ retainedToolSplit.percent = 53.75;
+ retainedToolSplit.snapshot!.retainedToolTokens = 75;
+
+ renderBreakdown({ view: retainedToolSplit });
+ await userEvent.click(toggle());
+
+ const breakdown = screen.getByTestId('context-breakdown');
+ const rowFor = (label: string) =>
+ within(breakdown).getByText(label).parentElement?.parentElement as HTMLElement;
+
+ /** 1075 used − 400 instructions − 50 summary − 225 tool calls = 400
+ * messages: the 75 retained tokens sit outside the pre-invoke 550 total. */
+ expect(rowFor('com_ui_context_messages').textContent).toContain('400');
+ expect(rowFor('com_ui_context_tool_calls').textContent).toContain('225');
+
+ /** The free track is the only visible peer outside the used context; all
+ * other peer rows must still add up exactly to the meter total. */
+ const peerTotal = Array.from(breakdown.children)
+ .filter(
+ (child) =>
+ !child.className.includes('pl-6') &&
+ !child.textContent?.includes('com_ui_context_free'),
+ )
+ .reduce(
+ (sum, child) => sum + Number.parseInt(child.lastElementChild?.textContent ?? '0', 10),
+ 0,
+ );
+ expect(peerTotal).toBe(1075);
+ });
it('shows every named tool result, including known zeroes, in the disclosure', async () => {
const manyTools = JSON.parse(JSON.stringify(toolSplitView)) as TokenUsageView;
manyTools.snapshot!.breakdown.toolMessageTokenCounts = {
diff --git a/client/src/components/Chat/Input/TokenUsage/Breakdown.tsx b/client/src/components/Chat/Input/TokenUsage/Breakdown.tsx
index 6e008bcab4..0beb7245ea 100644
--- a/client/src/components/Chat/Input/TokenUsage/Breakdown.tsx
+++ b/client/src/components/Chat/Input/TokenUsage/Breakdown.tsx
@@ -162,17 +162,22 @@ export default function Breakdown({
* `toolMessageTokens` is absent on older SDK snapshots, keeping the row
* unsplit. */
const summaryTokens = normalizeTokenCount(breakdown?.summaryTokens);
+ const retainedToolTokens = normalizeTokenCount(snapshot?.retainedToolTokens);
const messageBudget = Math.max(0, usedTokens - instructionTokens - summaryTokens);
- /** `toolMessageTokens` is a subset of messages. Bound it by both the
- * persisted message total and the current used-token remainder so malformed
- * or stale snapshots cannot make the rows exceed the meter. */
+ /** `toolMessageTokens` is a subset of pre-invoke messages, while retained
+ * tool results sit outside that total. Widen both sides of the split by the
+ * retained count, then bound the share by the current used-token remainder. */
const rawToolCallTokens =
breakdown?.toolMessageTokens != null
? normalizeTokenCount(breakdown.toolMessageTokens)
: undefined;
const toolCallTokens =
rawToolCallTokens != null
- ? Math.min(rawToolCallTokens, normalizeTokenCount(breakdown?.messageTokens), messageBudget)
+ ? Math.min(
+ rawToolCallTokens + retainedToolTokens,
+ normalizeTokenCount(breakdown?.messageTokens) + retainedToolTokens,
+ messageBudget,
+ )
: undefined;
const messageTokens = Math.max(0, messageBudget - (toolCallTokens ?? 0));
const freeTokens = maxTokens != null ? Math.max(0, maxTokens - usedTokens) : null;
diff --git a/client/src/hooks/Chat/__tests__/useTokenUsage.spec.tsx b/client/src/hooks/Chat/__tests__/useTokenUsage.spec.tsx
index 70daf163d2..9e93a7c061 100644
--- a/client/src/hooks/Chat/__tests__/useTokenUsage.spec.tsx
+++ b/client/src/hooks/Chat/__tests__/useTokenUsage.spec.tsx
@@ -122,6 +122,22 @@ describe('useTokenUsage — post-snapshot output', () => {
expect(result.current.runwayTurns).toBe(3);
});
+ it('charges retained tool results in the gauge, tool share, and runway', () => {
+ const retainedSnapshot = {
+ ...tailSnapshot,
+ retainedToolTokens: 700,
+ breakdown: { ...tailSnapshot.breakdown, toolMessageTokens: 900 },
+ } as ContextSnapshot;
+ const { result } = renderTokenUsage(undefined, { snapshot: retainedSnapshot });
+
+ /** The retained result is post-snapshot context: 195000 pre-invoke used +
+ * 2000 finalized output + 700 retained tool tokens = 197700. The split
+ * widens from 900 to 1600, while runway headroom falls to 2300 (2 turns). */
+ expect(result.current.usedTokens).toBe(197700);
+ expect(result.current.toolCallTokens).toBe(1600);
+ expect(result.current.runwayTurns).toBe(2);
+ });
+
it('counts the finalized output in what a summarization could reclaim', () => {
const { result } = renderTokenUsage();
diff --git a/client/src/hooks/Chat/useTokenUsage.ts b/client/src/hooks/Chat/useTokenUsage.ts
index 8cffbf407d..96dcf4da47 100644
--- a/client/src/hooks/Chat/useTokenUsage.ts
+++ b/client/src/hooks/Chat/useTokenUsage.ts
@@ -75,9 +75,10 @@ export interface TokenUsageView {
* shows a single pruned Messages row instead of input/output/estimated. */
messagesPruned: boolean;
/** Tool-call share of the message tokens: `breakdown.toolMessageTokens` on
- * the snapshot path, the clamped branch walk share on the estimate path.
- * Undefined when the producing SDK doesn't report it (older snapshots) or
- * the estimate is zero — the row stays hidden. A SUBSET of messages. */
+ * the snapshot path, plus retained post-snapshot tool results; the clamped
+ * branch walk share on the estimate path. Undefined when the producing SDK
+ * doesn't report it (older snapshots) or the estimate is zero — the row stays
+ * hidden. */
toolCallTokens?: number;
/** Cache split of the reconciling call's prompt (live or persisted) — a
* share of the used context, not an addition. */
@@ -266,15 +267,20 @@ export default function useTokenUsage({
const anchorSeries =
effective != null ? collectAnchorSeries(conversationKey, tailId, snapshotsByAnchor) : [];
/** The snapshot is pre-invoke, so its `remainingContextTokens` predates the
- * last call's finalized output and any in-flight output. Both already ate
- * that headroom (`usedTokens` adds them), so the projection must too. */
+ * last call's finalized output, any retained tool result, and any in-flight
+ * output. All already ate that headroom (`usedTokens` adds them), so the
+ * projection must too. */
const completedOutput = normalizeTokenCount(effective?.completedOutputTokens);
+ const retainedToolTokens = normalizeTokenCount(effective?.retainedToolTokens);
const liveOutput = normalizeTokenCount(liveTokens);
const remainingForRunway =
effective?.remainingContextTokens != null
? Math.max(
0,
- normalizeTokenCount(effective.remainingContextTokens) - completedOutput - liveOutput,
+ normalizeTokenCount(effective.remainingContextTokens) -
+ completedOutput -
+ retainedToolTokens -
+ liveOutput,
)
: null;
let runwayTurns: number | undefined;
@@ -313,8 +319,11 @@ export default function useTokenUsage({
: instructionTokens + normalizeTokenCount(breakdown.messageTokens);
/** The snapshot is pre-invoke: in-flight output rides on `liveTokens` (0
* unless streaming this branch), the last call's finalized output on
- * `completedOutputTokens`. */
- const usedTokens = normalizeTokenCount(Math.max(0, baseUsed) + liveOutput + completedOutput);
+ * `completedOutputTokens`, and retained tool results on
+ * `retainedToolTokens`. */
+ const usedTokens = normalizeTokenCount(
+ Math.max(0, baseUsed) + liveOutput + completedOutput + retainedToolTokens,
+ );
return {
usedTokens,
maxTokens,
@@ -333,12 +342,15 @@ export default function useTokenUsage({
overheadTokens: 0,
messageTokens: 0,
messagesPruned: false,
+ /** Retained tool results sit outside `messageTokens`, so widen the
+ * reported tool-call share without clipping it back to that pre-invoke
+ * total. Keep older snapshots unsplit when no split was reported. */
toolCallTokens:
breakdown.toolMessageTokens != null
? Math.min(
normalizeTokenCount(breakdown.toolMessageTokens),
normalizeTokenCount(breakdown.messageTokens),
- )
+ ) + retainedToolTokens
: undefined,
cacheRead: normalizeTokenCount(effective.cacheRead),
cacheWrite: normalizeTokenCount(effective.cacheWrite),
@@ -350,12 +362,17 @@ export default function useTokenUsage({
* the summary block's size so a compacting turn's summarization output —
* folded into the response's `tokenCount` but held outside
* `messageTokens` — is not subtracted from a total that never carried
- * it. While a response streams, `completedOutput` is 0 and the in-flight
- * tail is excluded from both sides (it rides on `liveTokens`). */
+ * it. A retained tool result is added for the same reason: the kept
+ * exchange counts it, so leaving it out of the total would subtract
+ * content that was never in it and understate the savings — on a large
+ * final result, down to zero. While a response streams, `completedOutput`
+ * is 0 and the in-flight tail is excluded from both sides (it rides on
+ * `liveTokens`). */
compactionReclaim: Math.max(
0,
normalizeTokenCount(breakdown.messageTokens) +
- completedOutput -
+ completedOutput +
+ retainedToolTokens -
latestExchangeTokens(
conversationKey,
tailId,
diff --git a/client/src/hooks/SSE/__tests__/useUsageHandler.spec.tsx b/client/src/hooks/SSE/__tests__/useUsageHandler.spec.tsx
index d571c4d676..b1366db0e3 100644
--- a/client/src/hooks/SSE/__tests__/useUsageHandler.spec.tsx
+++ b/client/src/hooks/SSE/__tests__/useUsageHandler.spec.tsx
@@ -110,6 +110,48 @@ describe('useUsageHandler — live snapshot reconciliation', () => {
expect(store.get(liveTokensFamily(convo))).toBe(500);
});
+ it('carries retained tool tokens from response metadata into the live snapshot', () => {
+ const convo = 'convo-finalize-retained';
+ const submission = {
+ userMessage: { messageId: 'u-retained', conversationId: convo },
+ conversation: { conversationId: convo },
+ };
+ const { result } = renderHook(() => useUsageHandler());
+ const store = getDefaultStore();
+
+ result.current.contextHandler(inflatedSnapshot(), submission);
+ result.current.finalizeUsage(
+ {
+ conversation: { conversationId: convo },
+ responseMessage: {
+ messageId: 'a-retained',
+ conversationId: convo,
+ metadata: { contextUsage: { retainedToolTokens: 321 } },
+ },
+ },
+ submission,
+ );
+ expect(store.get(contextSnapshotFamily(convo))?.retainedToolTokens).toBe(321);
+
+ const noRetainedConvo = 'convo-finalize-without-retained';
+ const noRetainedSubmission = {
+ userMessage: { messageId: 'u-no-retained', conversationId: noRetainedConvo },
+ conversation: { conversationId: noRetainedConvo },
+ };
+ result.current.contextHandler(inflatedSnapshot(), noRetainedSubmission);
+ result.current.finalizeUsage(
+ {
+ conversation: { conversationId: noRetainedConvo },
+ responseMessage: {
+ messageId: 'a-no-retained',
+ conversationId: noRetainedConvo,
+ },
+ },
+ noRetainedSubmission,
+ );
+ expect(store.get(contextSnapshotFamily(noRetainedConvo))?.retainedToolTokens).toBeUndefined();
+ });
+
it('does not reconcile a replayed (already-folded) primary usage', () => {
/** On resume, backfill marks the run's collected usages folded; a replayed
* `on_token_usage` then arrives folded=false. Since tool-loop calls share the
diff --git a/client/src/hooks/SSE/useUsageHandler.ts b/client/src/hooks/SSE/useUsageHandler.ts
index ab6bea2c4b..ee54a940ec 100644
--- a/client/src/hooks/SSE/useUsageHandler.ts
+++ b/client/src/hooks/SSE/useUsageHandler.ts
@@ -425,12 +425,20 @@ export default function useUsageHandler(): UsageHandlers {
* when a response is regenerated — to the branch-unique response message,
* so switching to a sibling branch falls back to that branch's own
* totals instead of showing this generation's snapshot. Also carry the
- * output streamed since the pre-invoke snapshot, kept after live resets. */
+ * output streamed since the pre-invoke snapshot, kept after live resets.
+ * The finalized response metadata is the authoritative source for retained
+ * tool results, which the live snapshot must keep after its re-anchor. */
if (snapshot != null && snapshot.anchorMessageId === userMsgId) {
+ const retainedToolTokens = (
+ data.responseMessage?.metadata?.contextUsage as TContextUsageEvent | undefined
+ )?.retainedToolTokens;
const finalized: ContextSnapshot = {
...snapshot,
anchorMessageId: responseId ?? snapshot.anchorMessageId,
...(liveAtFinalize > 0 && { completedOutputTokens: liveAtFinalize }),
+ ...(retainedToolTokens != null &&
+ Number.isFinite(retainedToolTokens) &&
+ retainedToolTokens > 0 && { retainedToolTokens }),
};
jotai.set(snapshotAtom, finalized);
/** Retain this generation's breakdown keyed by the branch-unique
diff --git a/packages/api/src/agents/client.spec.ts b/packages/api/src/agents/client.spec.ts
index fa62cb4bb1..77dbea864a 100644
--- a/packages/api/src/agents/client.spec.ts
+++ b/packages/api/src/agents/client.spec.ts
@@ -1,9 +1,11 @@
-import { ContentTypes } from 'librechat-data-provider';
import { Tokenizer as AiTokenizer } from 'ai-tokenizer';
import { Providers, StandardGraph } from '@librechat/agents';
import { HumanMessage } from '@librechat/agents/langchain/messages';
+import { ContentTypes, DEFAULT_MAX_RETAINED_TOOL_COUNT_CHARS } from 'librechat-data-provider';
import type { TMessage } from 'librechat-data-provider';
import {
+ collectToolCallIds,
+ countRetainedToolTokens,
createCachedTokenCounter,
prependQuotes,
prependFileContext,
@@ -45,6 +47,146 @@ describe('createCachedTokenCounter', () => {
});
});
+describe('countRetainedToolTokens', () => {
+ const toolPart = (id: string, name: string, output?: string) => ({
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { id, name, args: '{"path":"a"}', ...(output != null && { output }) },
+ });
+ /** Stands in for the run's tokenizer: one token per four characters, so every
+ * expectation below is a plain arithmetic consequence of what was counted. */
+ const countExact = (text: string) => Math.ceil(text.length / 4);
+
+ it('counts only the results of calls the snapshot had not seen', () => {
+ const contentParts = [
+ toolPart('call_1', 'grep', 'x'.repeat(4000)),
+ { type: ContentTypes.TEXT, text: 'calling the tool' },
+ toolPart('call_2', 'read_file', 'the retained result'),
+ ];
+
+ /** The earlier call is already inside the snapshot's own message tokens;
+ * counting it again would double the whole loop. */
+ expect(
+ countRetainedToolTokens({
+ contentParts,
+ priorToolCallIds: new Set(['call_1']),
+ countExact,
+ }),
+ ).toBe(countExact('the retained result'));
+ });
+
+ it('follows the call ids through a reshaped content array', () => {
+ /** Completion unshifts skill cards and can filter hidden sequential output,
+ * so the retained call moves; its id does not. */
+ const retained = toolPart('call_2', 'read_file', 'the retained result');
+ const reshaped = [
+ { type: ContentTypes.TOOL_CALL, tool_call: { id: 'skill_card', name: 'prime' } },
+ retained,
+ ];
+ expect(
+ countRetainedToolTokens({
+ contentParts: reshaped,
+ priorToolCallIds: new Set(['call_1']),
+ countExact,
+ }),
+ ).toBe(countExact('the retained result'));
+ });
+
+ it('ignores the model-authored call and everything that is not a tool result', () => {
+ /** Name and arguments are output tokens the snapshot's `completedOutputTokens`
+ * already carries, and assistant text is output too. An id-less call cannot be
+ * placed against the boundary at all. */
+ const contentParts = [
+ toolPart('call_1', 'read_file'),
+ { type: ContentTypes.TEXT, text: 'a long assistant explanation of the call' },
+ { type: ContentTypes.THINK, think: 'reasoning that never re-enters context' },
+ { type: ContentTypes.TOOL_CALL, tool_call: { name: 'read_file', output: 'unplaceable' } },
+ ];
+ expect(countRetainedToolTokens({ contentParts, priorToolCallIds: new Set(), countExact })).toBe(
+ 0,
+ );
+ expect(
+ countRetainedToolTokens({ contentParts: undefined, priorToolCallIds: null, countExact }),
+ ).toBe(0);
+ });
+
+ it('applies the Claude framing correction, matching the counter the snapshot used', () => {
+ const contentParts = [toolPart('call_1', 'read_file', 'r'.repeat(500))];
+ const base = countRetainedToolTokens({
+ contentParts,
+ priorToolCallIds: new Set(),
+ countExact,
+ });
+ expect(
+ countRetainedToolTokens({
+ contentParts,
+ priorToolCallIds: new Set(),
+ countExact,
+ isClaude: true,
+ }),
+ ).toBe(Math.ceil((base ?? 0) * 1.1));
+ });
+
+ it('reports nothing rather than an estimate when a result cannot be counted', () => {
+ /** A gauge missing the retained result is better than exact provider figures
+ * with a guess folded in, so one uncountable result withdraws the whole value. */
+ expect(
+ countRetainedToolTokens({
+ contentParts: [
+ toolPart('call_1', 'read_file', 'countable'),
+ toolPart('call_2', 'grep', 'uncountable'),
+ ],
+ priorToolCallIds: new Set(),
+ countExact: (text) => (text === 'uncountable' ? undefined : countExact(text)),
+ }),
+ ).toBeUndefined();
+ });
+
+ it('withdraws once the turn exhausts its tokenization budget', () => {
+ /** Tokenizing costs ~60 ms/MB, so the deployment's ceiling covers the whole
+ * turn: a final call requesting several tools cannot multiply it per result. */
+ const counted = jest.fn(countExact);
+ expect(
+ countRetainedToolTokens({
+ contentParts: [
+ toolPart('call_1', 'grep', 'a'.repeat(60)),
+ toolPart('call_2', 'read_file', 'b'.repeat(60)),
+ ],
+ priorToolCallIds: new Set(),
+ countExact: counted,
+ maxCountChars: 100,
+ }),
+ ).toBeUndefined();
+ /** It stops at the budget rather than counting the rest for nothing. */
+ expect(counted).toHaveBeenCalledTimes(1);
+ });
+
+ it('defaults the budget to the shipped ceiling', () => {
+ const output = 'a'.repeat(1024);
+ expect(
+ countRetainedToolTokens({
+ contentParts: [toolPart('call_1', 'grep', output)],
+ priorToolCallIds: new Set(),
+ countExact,
+ }),
+ ).toBe(countExact(output));
+ expect(DEFAULT_MAX_RETAINED_TOOL_COUNT_CHARS).toBe(8 * 1024 * 1024);
+ });
+});
+
+describe('collectToolCallIds', () => {
+ it('collects the ids a snapshot has seen and skips everything else', () => {
+ expect(
+ collectToolCallIds([
+ { type: ContentTypes.TOOL_CALL, tool_call: { id: 'call_1', name: 'grep' } },
+ { type: ContentTypes.TEXT, text: 'text carries no call' },
+ { type: ContentTypes.TOOL_CALL, tool_call: { name: 'no id' } },
+ undefined,
+ ]),
+ ).toEqual(new Set(['call_1']));
+ expect(collectToolCallIds(undefined)).toEqual(new Set());
+ });
+});
+
describe('prependFileContext', () => {
it('prepends file context to string content', () => {
const message: FormattedMessageWithContent = { content: 'Answer this question.' };
diff --git a/packages/api/src/agents/client.ts b/packages/api/src/agents/client.ts
index fe00e5ec2a..2a644b27e9 100644
--- a/packages/api/src/agents/client.ts
+++ b/packages/api/src/agents/client.ts
@@ -1,5 +1,9 @@
import { logger } from '@librechat/data-schemas';
-import { ContentTypes, isAgentsEndpoint } from 'librechat-data-provider';
+import {
+ ContentTypes,
+ isAgentsEndpoint,
+ DEFAULT_MAX_RETAINED_TOOL_COUNT_CHARS,
+} from 'librechat-data-provider';
import {
labelContentByAgent,
extractImageDimensions,
@@ -61,7 +65,7 @@ type ContentBlock = {
mime_type?: string;
data?: string;
text?: string;
- tool_call?: { name?: string; args?: string; output?: string };
+ tool_call?: { id?: string; name?: string; args?: string; output?: string };
};
export type FormattedMessageContentPart = {
@@ -379,6 +383,97 @@ export function countFormattedMessageTokens(
return isClaude ? Math.ceil(numTokens * CLAUDE_TOKEN_CORRECTION) : numTokens;
}
+/**
+ * Exact token count of the tool results a turn retains beyond its last context
+ * snapshot.
+ *
+ * Snapshots are dispatched pre-invoke, so the results of the tools the call they
+ * precede requested are never in them; normally the next call's snapshot carries
+ * those results as kept-message context, but a run that stops at the tool-call
+ * limit makes no next call — the result stays on the response and in no snapshot.
+ * `priorToolCallIds` are the calls the last snapshot already saw, so a call whose
+ * id is absent from it belongs to that final, unsnapshotted step. The boundary is
+ * the call id rather than a content index because completion reshapes the array —
+ * skill cards are unshifted onto the front and `hide_sequential_outputs` replaces
+ * it with a filtered one — so any index recorded mid-run means something else by
+ * the time the turn is saved. A call with no id cannot be placed and is skipped.
+ *
+ * Only the tool OUTPUT counts. A call's name and arguments are model output,
+ * already carried by the snapshot's `completedOutputTokens`, so counting them
+ * again would double them. The result-message framing the next turn adds (role,
+ * tool_call_id, per-message overhead) is left out as well: the figure is added to
+ * exact provider accounting, so it errs low rather than overstating the context.
+ * Non-string outputs are skipped, matching {@link countFormattedMessageTokens}.
+ *
+ * `maxCountChars` bounds the tokenization this turn may cost — one call can request
+ * several tools, so the budget spans all their results — and `countExact` returns
+ * `undefined` for content it cannot count exactly. Either limit withdraws the whole
+ * figure: a turn whose gauge is missing the retained result is better than one
+ * whose exact figures absorbed a guess. The Claude framing correction is applied,
+ * matching the counter that produced the snapshot.
+ */
+export function countRetainedToolTokens({
+ contentParts,
+ priorToolCallIds,
+ countExact,
+ maxCountChars = DEFAULT_MAX_RETAINED_TOOL_COUNT_CHARS,
+ isClaude = false,
+}: {
+ contentParts: ReadonlyArray<unknown> | null | undefined;
+ priorToolCallIds: ReadonlySet<string> | null | undefined;
+ countExact: (text: string) => number | undefined;
+ maxCountChars?: number;
+ isClaude?: boolean;
+}): number | undefined {
+ if (!Array.isArray(contentParts)) {
+ return 0;
+ }
+ let tokens = 0;
+ let charactersCounted = 0;
+ for (const candidate of contentParts) {
+ const part = candidate as ContentBlock | null | undefined;
+ if (part == null || part.type !== ContentTypes.TOOL_CALL) {
+ continue;
+ }
+ const { id, output } = part.tool_call ?? {};
+ if (typeof id !== 'string' || id.length === 0 || priorToolCallIds?.has(id) === true) {
+ continue;
+ }
+ if (typeof output !== 'string' || output.length === 0) {
+ continue;
+ }
+ charactersCounted += output.length;
+ if (charactersCounted > maxCountChars) {
+ return undefined;
+ }
+ const counted = countExact(output);
+ if (counted == null) {
+ return undefined;
+ }
+ tokens += counted;
+ }
+ return isClaude ? Math.ceil(tokens * CLAUDE_TOKEN_CORRECTION) : tokens;
+}
+
+/** The tool calls a content array carries, by provider id — the boundary a later
+ * save path measures "retained past this snapshot" against. */
+export function collectToolCallIds(
+ contentParts: ReadonlyArray<unknown> | null | undefined,
+): Set<string> {
+ const ids = new Set<string>();
+ if (!Array.isArray(contentParts)) {
+ return ids;
+ }
+ for (const candidate of contentParts) {
+ const part = candidate as ContentBlock | null | undefined;
+ const id = part?.type === ContentTypes.TOOL_CALL ? part.tool_call?.id : undefined;
+ if (typeof id === 'string' && id.length > 0) {
+ ids.add(id);
+ }
+ }
+ return ids;
+}
+
export function createTokenCounter(
encoding: Parameters<typeof Tokenizer.getTokenCount>[1],
): TokenCounter {
diff --git a/packages/api/src/agents/usage.spec.ts b/packages/api/src/agents/usage.spec.ts
index f567344953..94fa217441 100644
--- a/packages/api/src/agents/usage.spec.ts
+++ b/packages/api/src/agents/usage.spec.ts
@@ -18,8 +18,78 @@ import {
buildAbortedResponseMetadata,
computeSummaryUsedTokens,
priorRunOutputTokens,
+ resolveRetainedToolTokens,
} from './usage';
import { runWithDetachedSubagentUsage } from './subagentTaskContext';
+import Tokenizer from '~/utils/tokenizer';
+
+describe('resolveRetainedToolTokens', () => {
+ const toolPart = (id: string, output: string) => ({
+ type: 'tool_call',
+ tool_call: { id, name: 'read_file', args: '{"path":"a"}', output },
+ });
+
+ beforeAll(async () => {
+ await Tokenizer.initEncoding('o200k_base');
+ });
+
+ it('counts the results retained past the snapshot when the tool limit stopped the turn', () => {
+ /** Left to its default, the counter is the run's own tokenizer — the one the
+ * snapshot was measured with — so the figure is the real token count of the
+ * retained result and nothing else. */
+ const retained = resolveRetainedToolTokens({
+ stoppedAtToolLimit: true,
+ contentParts: [
+ toolPart('call_1', 'the result the snapshot counted'),
+ toolPart('call_2', 'the retained result'),
+ ],
+ priorToolCallIds: new Set(['call_1']),
+ encoding: 'o200k_base',
+ });
+ expect(retained).toBe(Tokenizer.countExactTokens('the retained result', 'o200k_base'));
+ });
+
+ it('reports nothing for every other ending, whatever the turn produced', () => {
+ /** Its tools were followed by another model call, hence another snapshot that
+ * already counts them as kept-message context. */
+ expect(
+ resolveRetainedToolTokens({
+ stoppedAtToolLimit: false,
+ contentParts: [toolPart('call_1', 'a result the next call re-counted')],
+ priorToolCallIds: new Set(),
+ encoding: 'o200k_base',
+ }),
+ ).toBeUndefined();
+ });
+
+ it('passes the deployment ceiling on to the counter', () => {
+ /** `endpoints.agents.maxRetainedToolCountChars`: past it the figure is withdrawn
+ * rather than estimated, so the gauge under-reports instead of stalling a save. */
+ expect(
+ resolveRetainedToolTokens({
+ stoppedAtToolLimit: true,
+ contentParts: [toolPart('call_1', 'a result longer than the ceiling allows')],
+ priorToolCallIds: new Set(),
+ encoding: 'o200k_base',
+ maxCountChars: 4,
+ }),
+ ).toBeUndefined();
+ });
+
+ it('takes a supplied counter instead of reaching for the shared tokenizer', () => {
+ const countExact = jest.fn((text: string) => text.length);
+ expect(
+ resolveRetainedToolTokens({
+ stoppedAtToolLimit: true,
+ contentParts: [toolPart('call_1', 'result')],
+ priorToolCallIds: new Set(),
+ encoding: 'claude',
+ countExact,
+ }),
+ ).toBe(Math.ceil('result'.length * 1.1));
+ expect(countExact).toHaveBeenCalledWith('result');
+ });
+});
describe('aggregateCollectedUsage', () => {
it('preserves the no-child baseline and ignores absent entries', () => {
@@ -2060,6 +2130,32 @@ describe('buildPersistedContextUsage', () => {
expect(result.completedOutputTokens).toBe(25);
});
+ it('carries a counted retained tool figure as a second post-snapshot delta', () => {
+ /** A turn stopped at the tool-call limit keeps the results of the tools its
+ * final call ran. They are outside the pre-invoke breakdown AND outside the
+ * final call's output, so they ride as their own field — never folded into
+ * the provider-reconciled `messageTokens`. */
+ const events: TTokenUsageEvent[] = [
+ { input_tokens: 200, output_tokens: 25, total_tokens: 225, provider: 'openAI' },
+ ];
+ const result = buildPersistedContextUsage(baseSnapshot, events, { retainedToolTokens: 640 });
+ expect(result.retainedToolTokens).toBe(640);
+ expect(result.completedOutputTokens).toBe(25);
+ /** The provider-reconciled message total is untouched: the retained result is
+ * an addend the client applies, not part of the exact accounting. */
+ expect(result.breakdown).toEqual(buildPersistedContextUsage(baseSnapshot, events).breakdown);
+ });
+
+ it.each([
+ ['a normal turn passes nothing', undefined],
+ ['no tool result was retained', 0],
+ ['the count is negative', -5],
+ ['the count is not finite', Number.NaN],
+ ])('omits the retained tool figure when %s', (_label, retainedToolTokens) => {
+ const result = buildPersistedContextUsage(baseSnapshot, [], { retainedToolTokens });
+ expect(Object.prototype.hasOwnProperty.call(result, 'retainedToolTokens')).toBe(false);
+ });
+
it.each(['openAI', 'bedrock'])('persists the final primary cache split for %s', (provider) => {
const events: TTokenUsageEvent[] = [
{ runId: 'run-1', input_tokens: 100, input_token_details: { cache_read: 10 } },
diff --git a/packages/api/src/agents/usage.ts b/packages/api/src/agents/usage.ts
index e3f9467858..c68d30a543 100644
--- a/packages/api/src/agents/usage.ts
+++ b/packages/api/src/agents/usage.ts
@@ -24,7 +24,9 @@ import {
prepareTokenSpend,
} from './transactions';
import { collectDetachedSubagentUsage } from './subagentTaskContext';
+import Tokenizer, { type EncodingName } from '~/utils/tokenizer';
import { getSafeErrorMetadata } from '~/utils/errors';
+import { countRetainedToolTokens } from './client';
type SpendTokensFn = (txData: TxMetadata, tokenUsage: TokenUsage) => Promise<unknown>;
type SpendStructuredTokensFn = (
@@ -388,6 +390,51 @@ const normalizePersistedTokenRecord = (
return found ? normalized : undefined;
};
+/**
+ * The counted tool results a save path attaches to its snapshot, or `undefined`
+ * when there are none to attach.
+ *
+ * Only a turn that stopped at the tool-call limit retains any: it keeps the
+ * results of the tools its final call requested, and the snapshot describing that
+ * call precedes them with no further call to produce a new one. Every other
+ * ending leaves nothing behind — a turn that finishes normally ends on model
+ * text, and a turn whose tools ran gets another call, hence another snapshot.
+ * A result that cannot be counted exactly withdraws the whole figure rather than
+ * contributing a guess (see `countRetainedToolTokens`).
+ *
+ * `countExact` is the run's own exact counter. It defaults to the shared
+ * tokenizer for the given encoding — the same one the SDK counted the snapshot
+ * with, which is the point — and is a parameter so a caller (or a test) can
+ * supply its own without reaching into module state. `maxCountChars` is the
+ * deployment's ceiling on that work (`endpoints.agents.maxRetainedToolCountChars`).
+ */
+export function resolveRetainedToolTokens({
+ stoppedAtToolLimit,
+ contentParts,
+ priorToolCallIds,
+ encoding,
+ maxCountChars,
+ countExact = (text: string) => Tokenizer.countExactTokens(text, encoding),
+}: {
+ stoppedAtToolLimit: boolean;
+ contentParts: ReadonlyArray<unknown> | null | undefined;
+ priorToolCallIds: ReadonlySet<string> | null | undefined;
+ encoding: EncodingName;
+ maxCountChars?: number;
+ countExact?: (text: string) => number | undefined;
+}): number | undefined {
+ if (!stoppedAtToolLimit) {
+ return undefined;
+ }
+ return countRetainedToolTokens({
+ contentParts,
+ priorToolCallIds,
+ countExact,
+ maxCountChars,
+ isClaude: encoding === 'claude',
+ });
+}
+
/**
* Projects the latest live context snapshot into the blob persisted on
* `responseMessage.metadata.contextUsage`. Reconciles the calibrated estimate to
@@ -399,10 +446,19 @@ const normalizePersistedTokenRecord = (
* `completedOutputTokens` so rehydration adds the same post-snapshot delta the
* live gauge did. The client re-anchors the blob to the response message id on
* load.
+ *
+ * `retainedToolTokens` is the second post-snapshot delta: the counted tool
+ * results a turn that stopped at the tool-call limit keeps beyond its last
+ * snapshot (see `countRetainedToolTokens`). It stays a separate field rather than
+ * being folded into `breakdown.messageTokens`, which is provider-reconciled — a
+ * locally counted figure added there would silently become part of the exact
+ * accounting. Zero and malformed values are dropped, so a normal turn carries
+ * nothing new.
*/
export function buildPersistedContextUsage(
snapshot: TContextUsageEvent,
usageEvents: ReadonlyArray<TTokenUsageEvent> = [],
+ options: { retainedToolTokens?: number } = {},
): TContextUsageEvent {
const finalCall = finalPrimaryCall(usageEvents, snapshot.runId);
const reconciled = finalCall ? reconcileContextUsageFromEvent(snapshot, finalCall) : snapshot;
@@ -433,9 +489,11 @@ export function buildPersistedContextUsage(
persistedBreakdown.toolMessageTokenCounts = toolMessageTokenCounts;
}
}
+ const retainedToolTokens = finiteNonNegativeInteger(options.retainedToolTokens);
return {
...reconciled,
breakdown: persistedBreakdown,
+ ...(retainedToolTokens != null && retainedToolTokens > 0 && { retainedToolTokens }),
};
}
diff --git a/packages/api/src/utils/tokenizer.spec.ts b/packages/api/src/utils/tokenizer.spec.ts
index 1b55b31ca6..bda83078ad 100644
--- a/packages/api/src/utils/tokenizer.spec.ts
+++ b/packages/api/src/utils/tokenizer.spec.ts
@@ -101,4 +101,43 @@ describe('Tokenizer', () => {
}
});
});
+
+ describe('countExactTokens', () => {
+ beforeAll(async () => {
+ await Tokenizer.initEncoding('o200k_base');
+ });
+
+ it('tokenizes oversized input whole instead of falling back to byte length', () => {
+ /** The fast-path estimate is byte length, several times the real count on
+ * ordinary text; a figure ADDED to provider accounting cannot carry that.
+ * Nor can it carry a sum of slices: a BPE merge spanning a seam is charged
+ * twice, so the whole input is tokenized in one pass. */
+ const text = 'word '.repeat(4096);
+ const exact = Tokenizer.countExactTokens(text, 'o200k_base');
+ expect(exact).toBeGreaterThan(0);
+ expect(exact).toBeLessThan(Tokenizer.getTokenCount(text, 'o200k_base'));
+ const bound = 4 * 1024;
+ let sliced = 0;
+ for (let index = 0; index < text.length; index += bound) {
+ sliced += Tokenizer.countExactTokens(text.slice(index, index + bound), 'o200k_base') ?? 0;
+ }
+ expect(exact).toBeLessThan(sliced);
+ });
+
+ it('matches the tokenizer for input inside the fast-path bound', () => {
+ const text = 'Hello, world!';
+ expect(Tokenizer.countExactTokens(text, 'o200k_base')).toBe(
+ Tokenizer.getTokenCount(text, 'o200k_base'),
+ );
+ expect(Tokenizer.countExactTokens('', 'o200k_base')).toBe(0);
+ });
+
+ it('returns nothing while the encoding is still cold', () => {
+ jest.isolateModules(() => {
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
+ const cold = require('./tokenizer').default as typeof Tokenizer;
+ expect(cold.countExactTokens('Uncounted tool result', 'o200k_base')).toBeUndefined();
+ });
+ });
+ });
});
diff --git a/packages/api/src/utils/tokenizer.ts b/packages/api/src/utils/tokenizer.ts
index 9bbd9591ee..06de186c6d 100644
--- a/packages/api/src/utils/tokenizer.ts
+++ b/packages/api/src/utils/tokenizer.ts
@@ -78,6 +78,38 @@ class Tokenizer {
}
}
+ /**
+ * Token count for content that must not be estimated, or `undefined` when it
+ * cannot be produced, so the caller can omit a figure instead of publishing a
+ * guess. Used for a value that is ADDED to exact provider accounting — see the
+ * retained tool results of a turn stopped at the tool-call limit — where
+ * {@link getTokenCount}'s two fallbacks would corrupt the sum: the cold-start
+ * estimate is a character ratio, and the oversized-input shortcut returns byte
+ * length, several times the real count on ordinary text.
+ *
+ * The input is tokenized whole. Counting it in slices would be cheaper but not
+ * exact — a BPE merge spanning a seam is charged twice, ~1 token per 4 KiB
+ * measured — and this is the one caller that needs the real number. It costs
+ * ~60 ms/MB, so the caller decides how much content is worth counting
+ * (`endpoints.agents.maxRetainedToolCountChars`) rather than a bound here.
+ */
+ countExactTokens(text: string, encoding: EncodingName = 'o200k_base'): number | undefined {
+ if (text.length === 0) {
+ return 0;
+ }
+ const tokenizer = this.tokenizersCache[encoding];
+ if (!tokenizer) {
+ void this.initEncoding(encoding);
+ return undefined;
+ }
+ try {
+ return tokenizer.count(text);
+ } catch (error) {
+ this.handleCountError(encoding, tokenizer, error);
+ return undefined;
+ }
+ }
+
private handleCountError(encoding: EncodingName, tokenizer: AiTokenizer, error: unknown): void {
logger.error('[Tokenizer] Error getting token count:', error);
if (this.tokenizersCache[encoding] !== tokenizer) {
diff --git a/packages/data-provider/src/config.spec.ts b/packages/data-provider/src/config.spec.ts
index dfa3f34196..3da0959bab 100644
--- a/packages/data-provider/src/config.spec.ts
+++ b/packages/data-provider/src/config.spec.ts
@@ -2,6 +2,7 @@ import type { TEndpointsConfig } from './types';
import {
allowedAddressesSchema,
agentsEndpointSchema,
+ DEFAULT_MAX_RETAINED_TOOL_COUNT_CHARS,
bedrockModels,
configSchema,
excludedKeys,
@@ -22,6 +23,26 @@ const endpointsConfig: TEndpointsConfig = {
Gemini: { type: EModelEndpoint.custom, userProvide: false, order: 9999 },
};
+describe('retained tool-count ceiling', () => {
+ it('ships the exact-count budget a deployment can raise or lower', () => {
+ /** The save path tokenizes a stopped turn's retained tool results to add an
+ * exact figure to the context gauge; this bounds that work. */
+ expect(agentsEndpointSchema.parse({}).maxRetainedToolCountChars).toBe(
+ DEFAULT_MAX_RETAINED_TOOL_COUNT_CHARS,
+ );
+ expect(
+ agentsEndpointSchema.parse({ maxRetainedToolCountChars: 1_048_576 })
+ .maxRetainedToolCountChars,
+ ).toBe(1_048_576);
+ /** Zero withholds the figure entirely; a fraction of a character is nonsense. */
+ expect(
+ agentsEndpointSchema.parse({ maxRetainedToolCountChars: 0 }).maxRetainedToolCountChars,
+ ).toBe(0);
+ expect(agentsEndpointSchema.safeParse({ maxRetainedToolCountChars: -1 }).success).toBe(false);
+ expect(agentsEndpointSchema.safeParse({ maxRetainedToolCountChars: 1.5 }).success).toBe(false);
+ });
+});
+
describe('run-scoped subagent file sharing config', () => {
it('preserves the opt-in default for existing configurations', () => {
expect(agentsEndpointSchema.parse({}).fileSharing).toBeUndefined();
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index 3a48abcebc..c2c4a40211 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -22,9 +22,13 @@ import {
MIN_BALANCE_RESERVATION_TTL_MS,
DEFAULT_BALANCE_RESERVATION_TTL_MS,
} from './balance';
+import {
+ MAX_SUBAGENTS,
+ MAX_SUBAGENTS_CEILING,
+ DEFAULT_MAX_RETAINED_TOOL_COUNT_CHARS,
+} from './limits';
import { ComponentTypes, SettingTypes, OptionTypes } from './generate';
import { CODE_ENVIRONMENT_DECISION_VERSION } from './code/workspace';
-import { MAX_SUBAGENTS, MAX_SUBAGENTS_CEILING } from './limits';
import { STATEFUL_CODE_ENVIRONMENTS } from './stateful-code';
import { specsConfigSchema, TSpecsConfig } from './models';
import { isActionTool } from './types/assistants';
@@ -40,6 +44,7 @@ export {
MAX_GRAPH_SUBAGENT_MEMBERS,
MAX_CHAT_PROJECT_NAME_LENGTH,
MAX_CHAT_PROJECT_DESCRIPTION_LENGTH,
+ DEFAULT_MAX_RETAINED_TOOL_COUNT_CHARS,
} from './limits';
export const defaultSocialLogins = ['google', 'facebook', 'openid', 'github', 'discord', 'saml'];
@@ -1196,6 +1201,18 @@ export const agentsEndpointSchema = baseEndpointSchema
* disables the guard for that tool only. Merged over LibreChat's shipped default of
* `{ create_file: 131072 }`. */
maxToolCallArgBytesByTool: z.record(z.number()).optional(),
+ /** Characters of retained tool output the save path may tokenize exactly for the
+ * context gauge when a turn stops at the tool-call limit (see
+ * `retainedToolTokens`). Tokenizing costs ~60 ms/MB and runs once per stopped
+ * turn; past this ceiling the figure is withdrawn rather than estimated, so the
+ * gauge under-reports that turn instead of blocking the save. Raise it for
+ * deployments whose tools legitimately return more, lower it on slow hardware. */
+ maxRetainedToolCountChars: z
+ .number()
+ .int()
+ .min(0)
+ .optional()
+ .default(DEFAULT_MAX_RETAINED_TOOL_COUNT_CHARS),
maxCitations: z.number().min(1).max(50).optional().default(30),
maxCitationsPerFile: z.number().min(1).max(10).optional().default(7),
minRelevanceScore: z.number().min(0.0).max(1.0).optional().default(0.45),
diff --git a/packages/data-provider/src/limits.ts b/packages/data-provider/src/limits.ts
index 8ff3f3250b..1c759f2efe 100644
--- a/packages/data-provider/src/limits.ts
+++ b/packages/data-provider/src/limits.ts
@@ -28,3 +28,8 @@ export const MAX_CHAT_PROJECT_DESCRIPTION_LENGTH = 1000;
/** Mirrors the bounded graph-child member limit in `@librechat/agents`. */
export const MAX_GRAPH_SUBAGENT_MEMBERS = 32;
+
+/** Characters of retained tool output one stopped turn may be tokenized for, so the
+ * context gauge can add an exact figure instead of an estimate. The schema default
+ * and the save path share it; tokenizing runs ~60 ms/MB, once per stopped turn. */
+export const DEFAULT_MAX_RETAINED_TOOL_COUNT_CHARS = 8 * 1024 * 1024;
diff --git a/packages/data-provider/src/types/runs.ts b/packages/data-provider/src/types/runs.ts
index 4ab53c8251..45a5b2ac82 100644
--- a/packages/data-provider/src/types/runs.ts
+++ b/packages/data-provider/src/types/runs.ts
@@ -295,6 +295,15 @@ export type TContextUsageEvent = {
/** Completed output in a resumable job. Separate from the saved-message field
* so older clients do not add it alongside their trailing-text estimate. */
resumedOutputTokens?: number;
+ /** Tool-result tokens retained AFTER this pre-invoke snapshot, counted with the
+ * run's own tokenizer. A run that stops at the tool-call limit keeps the result
+ * its final call's tools produced, and no later snapshot describes it: the
+ * snapshot precedes the call, and the limit means no further call is made. The
+ * client adds this the way it adds `completedOutputTokens`, so the gauge and the
+ * tool-call share include the retained result instead of missing it until the
+ * next turn's snapshot carries it as kept-message context. Counted, never
+ * estimated — the per-tool `toolMessageTokenCounts` stay a subset of the share. */
+ retainedToolTokens?: number;
};
/**