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
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🧾 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.jsindex 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.jsindex 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.jsindex 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 adiff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.jsindex 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 hasdiff --git a/client/src/components/Chat/Input/TokenUsage/Breakdown.spec.tsx b/client/src/components/Chat/Input/TokenUsage/Breakdown.spec.tsxindex 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.tsxindex 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.tsxindex 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.tsindex 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.tsxindex 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 thediff --git a/client/src/hooks/SSE/useUsageHandler.ts b/client/src/hooks/SSE/useUsageHandler.tsindex 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-uniquediff --git a/packages/api/src/agents/client.spec.ts b/packages/api/src/agents/client.spec.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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;};/**