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

🧮 feat: Surface Retained Tool-Message Context Usage (#15796)

Marco Berettae2f5772961d2
diff --git a/api/server/controllers/agents/__tests__/toolContext.spec.js b/api/server/controllers/agents/__tests__/toolContext.spec.js
new file mode 100644
index 0000000000..be207a21ab
--- /dev/null
+++ b/api/server/controllers/agents/__tests__/toolContext.spec.js
@@ -0,0 +1,176 @@
+const {
+ AIMessage,
+ HumanMessage,
+ ToolMessage,
+ FunctionMessage,
+} = require('@langchain/core/messages');
+const { syncBudgetDerivedFields } = require('@librechat/agents');
+
+function snapshot(messageTokens = 1000, calibrationRatio = 1) {
+ return {
+ calibrationRatio,
+ contextBudget: 1100,
+ effectiveInstructionTokens: 100,
+ remainingContextTokens: 1000 - messageTokens,
+ breakdown: { messageTokens },
+ };
+}
+
+function result(id, name) {
+ return new ToolMessage({ content: 'result', tool_call_id: id, name });
+}
+
+describe('agents tool context accounting', () => {
+ test('counts retained results and tool-only invocations without double counting raw calls', () => {
+ const usage = snapshot();
+ const messages = [
+ new HumanMessage('question'),
+ new AIMessage({
+ content: '',
+ tool_calls: [{ id: 'a', name: 'read_file', args: {} }],
+ additional_kwargs: {
+ tool_calls: [
+ { id: 'a', type: 'function', function: { name: 'read_file', arguments: '{}' } },
+ ],
+ },
+ }),
+ result('a'),
+ new AIMessage('answer'),
+ ];
+ syncBudgetDerivedFields(usage, messages, () => 10);
+ expect(usage.breakdown.toolMessageTokens).toBe(20);
+ expect(usage.breakdown.toolMessageTokenCounts).toEqual({ read_file: 10 });
+ });
+
+ test('keeps visible text and media assistant content outside the tool share', () => {
+ const content = [
+ 'explaining',
+ ['explaining'],
+ [{ type: 'image_url', image_url: { url: 'https://example.com/image.png' } }],
+ ];
+ for (const mixed of content) {
+ const usage = snapshot();
+ const messages = [
+ new AIMessage({ content: mixed, tool_calls: [{ id: 'a', name: 'read_file', args: {} }] }),
+ result('a'),
+ ];
+ syncBudgetDerivedFields(usage, messages, () => 10);
+ expect(usage.breakdown.toolMessageTokens).toBe(10);
+ expect(usage.breakdown.toolMessageTokenCounts).toEqual({ read_file: 10 });
+ }
+ });
+
+ test('counts tool-only reasoning and inline provider results without attributing invocation overhead', () => {
+ const usage = snapshot();
+ syncBudgetDerivedFields(
+ usage,
+ [
+ new AIMessage({
+ content: [
+ { type: 'thinking', thinking: 'reasoning' },
+ { type: 'tool_use', id: 'a', name: 'file_search', input: {} },
+ { type: 'web_search_tool_result', tool_use_id: 'a', content: [] },
+ ],
+ }),
+ result('a', 'file_search'),
+ ],
+ () => 10,
+ );
+ expect(usage.breakdown.toolMessageTokens).toBe(20);
+ expect(usage.breakdown.toolMessageTokenCounts).toEqual({ file_search: 10 });
+ });
+
+ test('attributes raw calls, legacy functions, and unknown results without guessing an unrelated name', () => {
+ const usage = snapshot();
+ syncBudgetDerivedFields(
+ usage,
+ [
+ new AIMessage({
+ content: '',
+ additional_kwargs: {
+ tool_calls: [
+ { id: 'raw', type: 'function', function: { name: 'raw_tool', arguments: '{}' } },
+ ],
+ },
+ }),
+ result('raw'),
+ new AIMessage({
+ content: '',
+ additional_kwargs: { function_call: { name: 'legacy_tool', arguments: '{}' } },
+ }),
+ new FunctionMessage({ content: 'legacy result', name: '' }),
+ result('missing', 'explicit_tool'),
+ result('missing'),
+ ],
+ () => 10,
+ );
+ expect(usage.breakdown.toolMessageTokens).toBe(60);
+ expect(usage.breakdown.toolMessageTokenCounts).toEqual({
+ raw_tool: 10,
+ legacy_tool: 10,
+ explicit_tool: 10,
+ unknown_tool: 10,
+ });
+ });
+
+ test('preserves prototype-sensitive tool names through JSON serialization', () => {
+ const usage = snapshot();
+ syncBudgetDerivedFields(
+ usage,
+ [result('a', '__proto__'), result('b', 'constructor'), result('c', 'toString')],
+ () => 10,
+ );
+ const counts = JSON.parse(JSON.stringify(usage)).breakdown.toolMessageTokenCounts;
+ expect(Object.hasOwn(counts, '__proto__')).toBe(true);
+ expect(counts.__proto__).toBe(10);
+ expect(counts.constructor).toBe(10);
+ expect(counts.toString).toBe(10);
+ });
+
+ test('apportions fractional calibration and budget clamping without exceeding the tool total', () => {
+ for (const ratio of [0.5, 1, 1.5, 5]) {
+ for (const available of [0, 1, 2, 10]) {
+ const usage = snapshot(available, ratio);
+ syncBudgetDerivedFields(
+ usage,
+ [result('a', 'a'), result('b', 'b'), result('c', 'c')],
+ () => 1,
+ );
+ const { toolMessageTokens, toolMessageTokenCounts } = usage.breakdown;
+ expect(toolMessageTokens).toBe(Math.min(available, Math.round(3 * ratio)));
+ const counts = Object.values(toolMessageTokenCounts ?? {});
+ expect(counts.every((count) => Number.isSafeInteger(count) && count >= 0)).toBe(true);
+ expect(counts.reduce((sum, count) => sum + count, 0)).toBe(toolMessageTokens);
+ }
+ }
+ });
+
+ test('distinguishes a known empty share from an unavailable counter', () => {
+ const known = snapshot();
+ syncBudgetDerivedFields(known, [new HumanMessage('hello')], () => 10);
+ expect(known.breakdown.toolMessageTokens).toBe(0);
+ expect(known.breakdown.toolMessageTokenCounts).toBeUndefined();
+ const unavailable = snapshot();
+ syncBudgetDerivedFields(unavailable, [result('a')]);
+ expect(unavailable.breakdown.toolMessageTokens).toBeUndefined();
+ });
+
+ test('drops an unavailable tool share without failing the model call', () => {
+ for (const value of [NaN, Infinity, -1, Number.MAX_SAFE_INTEGER + 1]) {
+ const usage = snapshot();
+ usage.breakdown.toolMessageTokens = 20;
+ usage.breakdown.toolMessageTokenCounts = { read_file: 10 };
+ syncBudgetDerivedFields(usage, [result('a')], () => value);
+ expect(usage.breakdown.toolMessageTokens).toBeUndefined();
+ expect(usage.breakdown.toolMessageTokenCounts).toBeUndefined();
+ expect(usage.breakdown.messageTokens).toBe(1000);
+ }
+ });
+
+ test('accepts approximate fractional token counters', () => {
+ const usage = snapshot();
+ syncBudgetDerivedFields(usage, [result('a', 'file_search')], () => 1.5);
+ expect(usage.breakdown.toolMessageTokens).toBe(2);
+ expect(usage.breakdown.toolMessageTokenCounts).toEqual({ file_search: 2 });
+ });
+});
diff --git a/api/server/controllers/agents/__tests__/usageEvents.integration.spec.js b/api/server/controllers/agents/__tests__/usageEvents.integration.spec.js
index caa14f6ea7..cd61f4e167 100644
--- a/api/server/controllers/agents/__tests__/usageEvents.integration.spec.js
+++ b/api/server/controllers/agents/__tests__/usageEvents.integration.spec.js
@@ -232,6 +232,14 @@ describe('usage events through the real agents pipeline', () => {
expect(remainingContextTokens).toBeLessThan(contextBudget);
expect(breakdown.toolTokenCounts.add).toBeGreaterThan(0);
}
+ expect(contextEvents[0].data.breakdown.toolMessageTokens).toBe(0);
+ const toolBreakdown = contextEvents[1].data.breakdown;
+ expect(toolBreakdown.toolMessageTokens).toBeGreaterThan(0);
+ expect(toolBreakdown.toolMessageTokens).toBeLessThanOrEqual(toolBreakdown.messageTokens);
+ expect(toolBreakdown.toolMessageTokenCounts.add).toBeGreaterThan(0);
+ expect(
+ Object.values(toolBreakdown.toolMessageTokenCounts).reduce((sum, count) => sum + count, 0),
+ ).toBeLessThanOrEqual(toolBreakdown.toolMessageTokens);
/** Tool loop grows the context between calls */
expect(contextEvents[1].data.prePruneContextTokens).toBeGreaterThan(
diff --git a/client/src/components/Chat/Input/TokenUsage/Breakdown.spec.tsx b/client/src/components/Chat/Input/TokenUsage/Breakdown.spec.tsx
index 74dd039280..6841b51ac4 100644
--- a/client/src/components/Chat/Input/TokenUsage/Breakdown.spec.tsx
+++ b/client/src/components/Chat/Input/TokenUsage/Breakdown.spec.tsx
@@ -2,7 +2,7 @@ import '@testing-library/jest-dom/extend-expect';
import { Provider } from 'jotai';
import userEvent from '@testing-library/user-event';
import { Constants, Tools } from 'librechat-data-provider';
-import { render, screen, within, fireEvent } from '@testing-library/react';
+import { render, screen, within, fireEvent, waitFor } from '@testing-library/react';
import type { TokenUsageView } from '~/hooks/Chat/useTokenUsage';
import Breakdown from './Breakdown';
@@ -23,6 +23,8 @@ const view = {
total: 1,
estTokens: 0,
tailEstTokens: 0,
+ estToolTokens: 0,
+ tailEstToolTokens: 0,
containsAnchor: false,
summaryBaseline: 0,
usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, costKnown: true },
@@ -77,6 +79,14 @@ const snapshotView = {
},
} as unknown as TokenUsageView;
+/** Same snapshot with a reported tool-call split present: 150 of the 550
+ * message tokens are tool exchanges, so Messages shows 400 and a Tool calls
+ * row appears. */
+const toolSplitView = JSON.parse(JSON.stringify(snapshotView)) as unknown as TokenUsageView;
+toolSplitView.snapshot!.breakdown.toolMessageTokens = 150;
+toolSplitView.snapshot!.breakdown.toolMessageTokenCounts = { read_file: 100 };
+toolSplitView.toolMessageTokenCounts = toolSplitView.snapshot!.breakdown.toolMessageTokenCounts;
+
const renderBreakdown = (props: Partial<React.ComponentProps<typeof Breakdown>> = {}) =>
render(
<Provider>
@@ -139,14 +149,14 @@ describe('TokenUsage Breakdown', () => {
),
).toEqual([
'bg-series-1', // messages
- 'bg-series-2', // system prompt
- 'bg-series-3', // system tools
- 'bg-series-3', // system tools, deferred
- 'bg-series-4', // mcp tools
- 'bg-series-4', // mcp tools, deferred
- 'bg-series-5', // skills
- 'bg-series-6', // subagents
- 'bg-series-7', // summary
+ 'bg-series-3', // system prompt
+ 'bg-series-4', // system tools
+ 'bg-series-4', // system tools, deferred
+ 'bg-series-5', // mcp tools
+ 'bg-series-5', // mcp tools, deferred
+ 'bg-series-6', // skills
+ 'bg-series-7', // subagents
+ 'bg-series-8', // summary
]);
});
@@ -157,7 +167,7 @@ describe('TokenUsage Breakdown', () => {
renderBreakdown({ view: noSkills });
expect(screen.getByRole('progressbar').children).toHaveLength(8);
- expect(screen.getByRole('progressbar').querySelector('.bg-series-5')).toBeNull();
+ expect(screen.getByRole('progressbar').querySelector('.bg-series-6')).toBeNull();
});
it('gives the deferred rows their family slot and a hatch', async () => {
@@ -172,9 +182,8 @@ describe('TokenUsage Breakdown', () => {
const deferred = rowFor('com_ui_context_tools_system_deferred')
.firstElementChild as HTMLElement;
- expect(system).toHaveClass('bg-series-3');
- expect(deferred).toHaveClass('bg-series-3');
- expect(system.getAttribute('style') ?? '').not.toContain('repeating-linear-gradient');
+ expect(system).toHaveClass('bg-series-4');
+ expect(deferred).toHaveClass('bg-series-4');
expect(deferred.getAttribute('style')).toContain('repeating-linear-gradient');
});
@@ -271,6 +280,208 @@ describe('TokenUsage Breakdown', () => {
expect(estimate).toBeInTheDocument();
expect(estimate.querySelector('[class*="bg-series-"]')).toBeNull();
});
+
+ it('keeps the estimate rows summing to used tokens when a tool share is known', async () => {
+ const estimateWithTools = {
+ ...view,
+ usedTokens: 600,
+ maxTokens: 2000,
+ branchTotals: { ...view.branchTotals, input: 300, output: 200 },
+ estimatedTokens: 100,
+ messageTokens: 600,
+ toolCallTokens: 150,
+ } as TokenUsageView;
+
+ renderBreakdown({ view: estimateWithTools });
+ await userEvent.click(toggle());
+
+ const estimate = screen.getByTestId('context-estimate');
+ const peerTotal = Array.from(estimate.children)
+ .filter((child) => !child.className.includes('pl-6'))
+ .reduce((sum, child) => sum + Number(child.lastElementChild?.textContent ?? 0), 0);
+
+ /** 300 input + 200 output + 100 estimated = 600 used. The tool share is a
+ * subset of those rows, so it may only appear as an indented subtotal —
+ * as a peer row the visible rows would claim 750 of a 600-token window. */
+ expect(peerTotal).toBe(600);
+
+ const toolRow = within(estimate).getByText('com_ui_context_tool_calls').parentElement
+ ?.parentElement as HTMLElement;
+ expect(toolRow.parentElement?.className).toContain('pl-6');
+ expect(toolRow.textContent).toContain('150');
+ });
+ it('splits tool-call usage out of the messages row when reported', async () => {
+ renderBreakdown({ view: toolSplitView });
+ await userEvent.click(toggle());
+
+ const breakdown = screen.getByTestId('context-breakdown');
+ const rowFor = (label: string) =>
+ within(breakdown).getByText(label).parentElement?.parentElement as HTMLElement;
+
+ /** 1000 used − 400 instructions − 50 summary − 150 tool calls = 400 */
+ expect(rowFor('com_ui_context_messages').textContent).toContain('400');
+ expect(rowFor('com_ui_context_tool_calls').textContent).toContain('150');
+ });
+ 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 = {
+ alpha: 30,
+ beta: 20,
+ gamma: 10,
+ delta: 8,
+ epsilon: 7,
+ zeta: 5,
+ eta: 3,
+ zero_tool: 0,
+ };
+ manyTools.toolMessageTokenCounts = manyTools.snapshot!.breakdown.toolMessageTokenCounts;
+
+ renderBreakdown({ view: manyTools });
+ await userEvent.click(toggle());
+ await userEvent.click(screen.getByRole('button', { name: /com_ui_context_tool_calls/ }));
+
+ const details = screen.getByText('com_ui_context_tool_breakdown')
+ .parentElement as HTMLElement;
+ for (const name of [
+ 'alpha',
+ 'beta',
+ 'gamma',
+ 'delta',
+ 'epsilon',
+ 'zeta',
+ 'eta',
+ 'zero_tool',
+ ]) {
+ expect(within(details).getByText(name)).toBeInTheDocument();
+ }
+ expect(
+ within(details).getByText('zero_tool').parentElement?.parentElement?.textContent,
+ ).toContain('0');
+ });
+
+ it('renders a reported zero tool-call share instead of treating it as unavailable', async () => {
+ const knownZero = JSON.parse(JSON.stringify(snapshotView)) as TokenUsageView;
+ knownZero.snapshot!.breakdown.toolMessageTokens = 0;
+
+ renderBreakdown({ view: knownZero });
+ await userEvent.click(toggle());
+ const breakdown = screen.getByTestId('context-breakdown');
+ expect(within(breakdown).getByText('com_ui_context_tool_calls')).toBeInTheDocument();
+ expect(
+ within(breakdown).getByText('com_ui_context_tool_calls').parentElement?.parentElement
+ ?.textContent,
+ ).toContain('0');
+ });
+
+ it('uses a native disclosure button for the expandable tool list', async () => {
+ renderBreakdown({ view: toolSplitView });
+ await userEvent.click(toggle());
+
+ const toolButton = screen.getByRole('button', { name: /com_ui_context_tool_calls/ });
+ expect(toolButton).toHaveAttribute('aria-expanded', 'false');
+
+ toolButton.focus();
+ await userEvent.keyboard('{Enter}');
+
+ expect(toolButton).toHaveAttribute('aria-expanded', 'true');
+ expect(screen.getByText('com_ui_context_tool_breakdown')).toBeInTheDocument();
+ expect(document.getElementById(toolButton.getAttribute('aria-controls')!)).toContainElement(
+ screen.getByText('com_ui_context_tool_breakdown'),
+ );
+ await userEvent.keyboard(' ');
+ expect(toolButton).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('keeps the messages row unsplit when the snapshot lacks the tool split', async () => {
+ renderBreakdown({ view: snapshotView });
+ await userEvent.click(toggle());
+
+ const breakdown = screen.getByTestId('context-breakdown');
+ expect(within(breakdown).queryByText('com_ui_context_tool_calls')).toBeNull();
+ expect(
+ within(breakdown).getByText('com_ui_context_messages').parentElement?.parentElement
+ ?.textContent,
+ ).toContain('550');
+ });
+
+ it('shows cached prompt shares as a subtotal, not beside the context rows', async () => {
+ const cached = {
+ ...snapshotView,
+ cacheRead: 30,
+ cacheWrite: 10,
+ } as TokenUsageView;
+ renderBreakdown({ view: cached });
+ await userEvent.click(toggle());
+
+ const breakdown = screen.getByTestId('context-breakdown');
+ const cachedRow = within(breakdown).getByText('com_ui_context_cached').parentElement
+ ?.parentElement as HTMLElement;
+
+ /** Reconciliation already counted the cached prompt inside the segments
+ * above, so these may only appear indented — as peer rows a fully cached
+ * prompt would show its tokens twice and the visible rows would sum past
+ * the meter. */
+ expect(cachedRow.parentElement?.className).toContain('pl-6');
+ expect(cachedRow.textContent).toContain('30');
+ const peers = Array.from(breakdown.children).filter(
+ (child) => !child.className.includes('pl-6'),
+ );
+ expect(peers.some((peer) => peer.textContent?.includes('com_ui_context_cache_write'))).toBe(
+ false,
+ );
+ expect(screen.getByRole('progressbar')).toHaveAttribute('aria-valuenow', '50');
+ });
+
+ it('hides the compaction hint when the operation is unavailable', async () => {
+ renderBreakdown({
+ view: { ...toolSplitView, runwayTurns: 2, compactionReclaim: 90000 },
+ compactionAvailable: false,
+ });
+ await userEvent.click(toggle());
+ await userEvent.click(screen.getByTestId('context-insights-toggle'));
+ const hints = await screen.findByTestId('context-hints');
+ expect(hints.textContent).toContain('com_ui_context_runway');
+ expect(hints.textContent).not.toContain('com_ui_context_compaction');
+ });
+
+ it('warns under pressure inline, with insights behind the ⓘ button', async () => {
+ const pressured = JSON.parse(JSON.stringify(toolSplitView)) as TokenUsageView;
+ pressured.percent = 85;
+ pressured.snapshot!.breakdown.toolMessageTokenCounts = {
+ grep: 1500,
+ read_file: 500,
+ };
+ pressured.toolMessageTokenCounts = pressured.snapshot!.breakdown.toolMessageTokenCounts;
+ pressured.runwayTurns = 2;
+ pressured.compactionReclaim = 90000;
+
+ renderBreakdown({ view: pressured, compactionAvailable: true });
+ await userEvent.click(toggle());
+
+ /** Pressure warns inline; insights stay hidden until the ⓘ is hovered */
+ expect(screen.getByText('com_ui_context_pressure_warn')).toBeInTheDocument();
+ expect(screen.queryByTestId('context-hints')).toBeNull();
+
+ const info = screen.getByTestId('context-insights-toggle');
+ await userEvent.click(info);
+ const hints = await screen.findByTestId('context-hints');
+ expect(hints.textContent).toContain('com_ui_context_largest_tool');
+ expect(hints.textContent).toContain('com_ui_context_runway');
+ expect(hints.textContent).toContain('com_ui_context_compaction');
+
+ await userEvent.keyboard('{Escape}');
+ await waitFor(() => expect(screen.queryByTestId('context-hints')).toBeNull());
+ });
+
+ it('shows the danger tint at the hard threshold', async () => {
+ const critical = JSON.parse(JSON.stringify(toolSplitView)) as TokenUsageView;
+ critical.percent = 96;
+
+ renderBreakdown({ view: critical });
+ await userEvent.click(toggle());
+
+ expect(screen.getByText('com_ui_context_pressure_danger')).toBeInTheDocument();
+ });
});
describe('totals', () => {
@@ -284,6 +495,32 @@ describe('TokenUsage Breakdown', () => {
}),
).toBeInTheDocument();
});
+
+ it('counts a cached subagent call in the all-branches subtotal', async () => {
+ /** A fully cached subagent call reports its prompt under cacheRead and
+ * returns nothing: summing input+output alone would hide the row while
+ * the cache rows above still count the same traffic. */
+ const cachedSubagent = {
+ ...view,
+ branchUsage: { ...view.branchUsage, cacheRead: 900 },
+ subagentUsage: {
+ input: 0,
+ output: 0,
+ cacheRead: 900,
+ cacheWrite: 100,
+ cost: 0,
+ costKnown: true,
+ },
+ } as TokenUsageView;
+
+ renderBreakdown({ view: cachedSubagent });
+ await userEvent.click(toggle());
+
+ const totals = within(screen.getByTestId('token-usage-totals'));
+ expect(
+ totals.getByText('com_ui_context_subagents_all').parentElement?.nextElementSibling,
+ ).toHaveTextContent('1K');
+ });
});
describe('langfuse', () => {
diff --git a/client/src/components/Chat/Input/TokenUsage/Breakdown.tsx b/client/src/components/Chat/Input/TokenUsage/Breakdown.tsx
index 53959fafc9..83c69b2657 100644
--- a/client/src/components/Chat/Input/TokenUsage/Breakdown.tsx
+++ b/client/src/components/Chat/Input/TokenUsage/Breakdown.tsx
@@ -1,8 +1,12 @@
-import { useState } from 'react';
+import { Fragment, useId, useMemo, useState } from 'react';
import { useAtom } from 'jotai';
-import { ChevronDown, ExternalLink } from 'lucide-react';
+import { ChevronDown, ExternalLink, Info, TriangleAlert } from 'lucide-react';
import {
Button,
+ HoverCard,
+ HoverCardPortal,
+ HoverCardContent,
+ HoverCardTrigger,
Collapsible,
MeterSwatch,
SegmentedMeter,
@@ -12,7 +16,7 @@ import {
import type { MeterSegment } from '@librechat/client';
import type { TokenUsageView } from '~/hooks/Chat/useTokenUsage';
import type { CurrencyConfig } from '~/utils';
-import { groupToolTokens, formatTokens, formatCost } from '~/utils';
+import { groupToolTokens, formatTokens, formatCost, normalizeTokenCount, cn } from '~/utils';
import { contextBreakdownExpandedAtom } from '~/store/usage';
import { useLocalize } from '~/hooks';
@@ -27,16 +31,28 @@ interface RowProps {
/** Meter segment this row keys; hovering it highlights its slice of the bar */
id?: string;
onHoverChange?: (id: string | null) => void;
+ onClick?: () => void;
+ expanded?: boolean;
+ controls?: string;
}
-function Row({ label, value, max, segment, track, id, onHoverChange }: RowProps) {
- const percent = max != null && max > 0 ? Math.min((value / max) * 100, 100) : null;
- return (
- <div
- className="flex items-center justify-between gap-4 text-sm"
- onPointerEnter={id != null ? () => onHoverChange?.(id) : undefined}
- onPointerLeave={id != null ? () => onHoverChange?.(null) : undefined}
- >
+function Row({
+ label,
+ value,
+ max,
+ segment,
+ track,
+ id,
+ onHoverChange,
+ onClick,
+ expanded,
+ controls,
+}: RowProps) {
+ const safeValue = normalizeTokenCount(value);
+ const safeMax = max != null ? normalizeTokenCount(max) : 0;
+ const percent = safeMax > 0 ? Math.min((safeValue / safeMax) * 100, 100) : null;
+ const content = (
+ <>
<span className="flex min-w-0 items-center gap-2">
{segment != null && <MeterSwatch segment={segment} />}
{track === true && (
@@ -45,16 +61,41 @@ function Row({ label, value, max, segment, track, id, onHoverChange }: RowProps)
className="size-2 flex-none rounded-sm bg-surface-tertiary ring-1 ring-inset ring-border-medium"
/>
)}
- <span className="text-text-secondary">{label}</span>
+ <span className="min-w-0 break-words text-text-secondary">{label}</span>
</span>
- <span className="font-medium text-text-primary">
- {formatTokens(value)}
+ <span className="shrink-0 whitespace-nowrap font-medium text-text-primary">
+ {formatTokens(safeValue)}
{percent != null && (
<span className="ml-1 text-xs text-text-secondary" aria-hidden="true">
({Math.round(percent)}%)
</span>
)}
</span>
+ </>
+ );
+ const className = cn(
+ 'flex w-full items-center justify-between gap-4 text-left text-sm',
+ onClick != null &&
+ 'rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-text-primary',
+ );
+ const handlers = {
+ onPointerEnter: id != null ? () => onHoverChange?.(id) : undefined,
+ onPointerLeave: id != null ? () => onHoverChange?.(null) : undefined,
+ };
+ return onClick != null ? (
+ <button
+ type="button"
+ className={className}
+ aria-expanded={expanded}
+ aria-controls={controls}
+ onClick={onClick}
+ {...handlers}
+ >
+ {content}
+ </button>
+ ) : (
+ <div className={className} {...handlers}>
+ {content}
</div>
);
}
@@ -62,6 +103,7 @@ function Row({ label, value, max, segment, track, id, onHoverChange }: RowProps)
interface BreakdownProps {
view: TokenUsageView;
showCost: boolean;
+ compactionAvailable?: boolean;
currency?: CurrencyConfig;
langfuseSessionUrl?: string;
}
@@ -69,31 +111,137 @@ interface BreakdownProps {
export default function Breakdown({
view,
showCost,
+ compactionAvailable = false,
currency,
langfuseSessionUrl,
}: BreakdownProps) {
const localize = useLocalize();
const [expanded, setExpanded] = useAtom(contextBreakdownExpandedAtom);
const [hoveredSegment, setHoveredSegment] = useState<string | null>(null);
- const { usedTokens, maxTokens, percent, snapshot, snapshotActive, branchUsage, hasUsage } = view;
+ const [toolsExpanded, setToolsExpanded] = useState(false);
+ const [insightsOpen, setInsightsOpen] = useState(false);
+ const insightsId = useId();
+ const toolBreakdownId = useId();
+ const usedTokens = normalizeTokenCount(view.usedTokens);
+ const maxTokens = view.maxTokens != null ? normalizeTokenCount(view.maxTokens) : undefined;
+ let percent =
+ maxTokens != null && maxTokens > 0 ? Math.min((usedTokens / maxTokens) * 100, 100) : 0;
+ if (typeof view.percent === 'number' && Number.isFinite(view.percent)) {
+ percent = Math.min(Math.max(view.percent, 0), 100);
+ }
+ const { snapshot, snapshotActive, branchUsage, hasUsage } = view;
/** Show the all-branches total only when it (a) exceeds the active branch —
* epsilon guards against float summation order surfacing a spurious row in an
* unbranched conversation — and (b) has COMPLETE cost coverage, so a sibling
* branch saved without cost can't render an under-reported total. */
- const showTotal = view.totalUsage.costKnown && view.totalCost - view.branchCost > 1e-9;
+ const showTotal =
+ view.totalUsage.costKnown &&
+ Number.isFinite(view.totalCost) &&
+ Number.isFinite(view.branchCost) &&
+ view.totalCost - view.branchCost > 1e-9;
+
+ /** Every normalized bucket of the subagent calls: a cached call reports its
+ * prompt under `cacheRead`/`cacheWrite`, so summing input+output alone
+ * under-reports it — and hides a fully cached call with no output entirely,
+ * while the Totals rows above still count its cache traffic. */
+ const subagentTokens =
+ normalizeTokenCount(view.subagentUsage?.input) +
+ normalizeTokenCount(view.subagentUsage?.output) +
+ normalizeTokenCount(view.subagentUsage?.cacheRead) +
+ normalizeTokenCount(view.subagentUsage?.cacheWrite);
const breakdown = snapshotActive ? snapshot?.breakdown : undefined;
- const instructionTokens =
- snapshot?.effectiveInstructionTokens ?? breakdown?.instructionTokens ?? 0;
- const systemTokens =
- (breakdown?.systemMessageTokens ?? 0) + (breakdown?.dynamicInstructionTokens ?? 0);
- /** Summary has its own row, so exclude it (it's part of `usedTokens`) to avoid
- * double-counting it inside the Messages row on a summarized turn. */
- const messageTokens = Math.max(
- 0,
- usedTokens - instructionTokens - (breakdown?.summaryTokens ?? 0),
+ const instructionTokens = normalizeTokenCount(
+ snapshot?.effectiveInstructionTokens ?? breakdown?.instructionTokens,
);
+ const systemTokens =
+ normalizeTokenCount(breakdown?.systemMessageTokens) +
+ normalizeTokenCount(breakdown?.dynamicInstructionTokens);
+ /** Summary and tool calls have their own rows, so exclude both (they're part
+ * of `usedTokens`) to avoid double-counting them inside the Messages row.
+ * `toolMessageTokens` is absent on older SDK snapshots, keeping the row
+ * unsplit. */
+ const summaryTokens = normalizeTokenCount(breakdown?.summaryTokens);
+ 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. */
+ const rawToolCallTokens =
+ breakdown?.toolMessageTokens != null
+ ? normalizeTokenCount(breakdown.toolMessageTokens)
+ : undefined;
+ const toolCallTokens =
+ rawToolCallTokens != null
+ ? Math.min(rawToolCallTokens, normalizeTokenCount(breakdown?.messageTokens), messageBudget)
+ : undefined;
+ const messageTokens = Math.max(0, messageBudget - (toolCallTokens ?? 0));
const freeTokens = maxTokens != null ? Math.max(0, maxTokens - usedTokens) : null;
+ /** Context pressure: the gauge percent against soft (80%) and hard (95%)
+ * thresholds, driving the warning line's tint and the offender/runway hints. */
+ let pressure: 'danger' | 'warn' | 'none' = 'none';
+ if (percent >= 95) {
+ pressure = 'danger';
+ } else if (percent >= 80) {
+ pressure = 'warn';
+ }
+ const dynamicInstructionTokens = normalizeTokenCount(breakdown?.dynamicInstructionTokens);
+ /** Keep the largest tool for the pressure insight, but retain every named
+ * result in the disclosure. Result counts are a subset of the tool-call
+ * share; any invocation overhead in that share remains unassigned. */
+ const { largestTool, toolBreakdown } = useMemo(() => {
+ const counts = view.toolMessageTokenCounts;
+ if (counts == null) {
+ return {
+ largestTool: null,
+ toolBreakdown: [] as Array<{ name: string; tokens: number }>,
+ };
+ }
+ const candidates: Array<{ name: string; tokens: number }> = [];
+ for (const name in counts) {
+ if (!Object.prototype.hasOwnProperty.call(counts, name)) {
+ continue;
+ }
+ candidates.push({ name, tokens: normalizeTokenCount(counts[name]) });
+ }
+ candidates.sort((a, b) => b.tokens - a.tokens);
+
+ /** Keep displayed results within the reported tool-call share even when a
+ * malformed snapshot overstates one or more per-tool counts. Do not drop
+ * names after the share is exhausted: a known zero is different from an
+ * unavailable result count. */
+ let remaining = toolCallTokens ?? Number.MAX_SAFE_INTEGER;
+ for (const candidate of candidates) {
+ candidate.tokens = Math.min(candidate.tokens, remaining);
+ remaining -= candidate.tokens;
+ }
+ return {
+ largestTool: candidates[0]?.tokens > 0 ? candidates[0] : null,
+ toolBreakdown: candidates,
+ };
+ }, [toolCallTokens, view.toolMessageTokenCounts]);
+ const hasToolCounts = toolBreakdown.length > 0;
+ /** Insights shown on hovering the ⓘ button: largest tool, runway, and what a
+ * summarization could reclaim. */
+ const insights: string[] = [];
+ if (largestTool != null) {
+ insights.push(
+ localize('com_ui_context_largest_tool', {
+ 0: largestTool.name,
+ 1: formatTokens(largestTool.tokens),
+ }),
+ );
+ }
+ const runwayTurns =
+ typeof view.runwayTurns === 'number' && Number.isFinite(view.runwayTurns)
+ ? Math.max(0, Math.floor(view.runwayTurns))
+ : null;
+ if (runwayTurns != null && runwayTurns <= 25) {
+ insights.push(localize('com_ui_context_runway', { 0: String(runwayTurns) }));
+ }
+ const compactionReclaim = normalizeTokenCount(view.compactionReclaim);
+ if (compactionAvailable && compactionReclaim > 0) {
+ insights.push(localize('com_ui_context_compaction', { 0: formatTokens(compactionReclaim) }));
+ }
const groups =
breakdown?.toolTokenCounts != null
@@ -114,14 +262,20 @@ export default function Breakdown({
value: messageTokens,
slot: 1,
},
- { id: 'system', label: localize('com_ui_context_system'), value: systemTokens, slot: 2 },
+ {
+ id: 'tool-calls',
+ label: localize('com_ui_context_tool_calls'),
+ value: toolCallTokens ?? 0,
+ slot: 2,
+ },
+ { id: 'system', label: localize('com_ui_context_system'), value: systemTokens, slot: 3 },
...(groups == null
? [
{
id: 'tools',
label: localize('com_ui_context_tools'),
- value: breakdown.toolSchemaTokens,
- slot: 3,
+ value: normalizeTokenCount(breakdown.toolSchemaTokens),
+ slot: 4,
},
]
: [
@@ -129,44 +283,43 @@ export default function Breakdown({
id: 'tools-system',
label: localize('com_ui_context_tools_system'),
value: groups.system,
- slot: 3,
+ slot: 4,
},
{
id: 'tools-system-deferred',
label: localize('com_ui_context_tools_system_deferred'),
value: groups.systemDeferred,
- slot: 3,
+ slot: 4,
hatched: true,
},
{
id: 'tools-mcp',
label: localize('com_ui_context_tools_mcp'),
value: groups.mcp,
- slot: 4,
+ slot: 5,
},
{
id: 'tools-mcp-deferred',
label: localize('com_ui_context_tools_mcp_deferred'),
value: groups.mcpDeferred,
- slot: 4,
+ slot: 5,
hatched: true,
},
- { id: 'skills', label: localize('com_ui_skills'), value: groups.skills, slot: 5 },
+ { id: 'skills', label: localize('com_ui_skills'), value: groups.skills, slot: 6 },
{
id: 'subagents',
label: localize('com_ui_context_subagents'),
value: groups.subagents,
- slot: 6,
+ slot: 7,
},
]),
{
id: 'summary',
label: localize('com_ui_context_summary'),
- value: breakdown.summaryTokens,
- slot: 7,
+ value: normalizeTokenCount(breakdown.summaryTokens),
+ slot: 8,
},
];
-
/** The estimate path knows the total but not the composition, so it keeps a
* single unsegmented fill and its rows carry no swatches. */
const meterSegments: MeterSegment[] =
@@ -192,7 +345,7 @@ export default function Breakdown({
<div className="w-72" role="region" aria-label={localize('com_ui_context_usage')}>
<Collapsible open={expanded} onOpenChange={setExpanded}>
<CollapsibleTrigger
- className="group flex w-full items-center justify-between gap-2 rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring-primary"
+ className="group flex w-full items-center justify-between gap-2 rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-text-primary"
data-testid="context-breakdown-toggle"
>
<span className="whitespace-nowrap text-sm font-medium text-text-primary">
@@ -225,27 +378,144 @@ export default function Breakdown({
so it collapses with the height. On the parent it would be a margin
outside the animation, and unmounting the content would drop it in a
single 12px jump after the height reached zero. */}
- <CollapsibleContent className="overflow-hidden data-[state=closed]:animate-collapsible-up data-[state=open]:animate-collapsible-down motion-reduce:animate-none">
+ <CollapsibleContent className="overflow-hidden data-[state=closed]:animate-collapsible-up data-[state=open]:animate-collapsible-down motion-reduce:data-[state=closed]:animate-none motion-reduce:data-[state=open]:animate-none">
<div className="mt-3 space-y-3">
+ {(pressure !== 'none' || insights.length > 0) && (
+ <div className="relative flex items-center justify-between gap-2">
+ {pressure !== 'none' ? (
+ <p
+ className={cn(
+ 'flex min-w-0 items-center gap-1.5 text-xs',
+ pressure === 'danger' ? 'text-text-destructive' : 'text-text-warning',
+ )}
+ >
+ <TriangleAlert className="size-3.5 shrink-0" aria-hidden="true" />
+ {localize(
+ pressure === 'danger'
+ ? 'com_ui_context_pressure_danger'
+ : 'com_ui_context_pressure_warn',
+ )}
+ </p>
+ ) : (
+ <span />
+ )}
+ {insights.length > 0 && (
+ <HoverCard open={insightsOpen} onOpenChange={setInsightsOpen}>
+ <HoverCardTrigger asChild>
+ <Button
+ type="button"
+ variant="ghost"
+ size="icon"
+ aria-label={localize('com_ui_context_insights')}
+ aria-expanded={insightsOpen}
+ aria-controls={insightsOpen ? insightsId : undefined}
+ data-testid="context-insights-toggle"
+ className="size-6"
+ onFocus={() => setInsightsOpen(true)}
+ onBlur={() => setInsightsOpen(false)}
+ onClick={() => setInsightsOpen(true)}
+ >
+ <Info className="size-3.5" aria-hidden="true" />
+ </Button>
+ </HoverCardTrigger>
+ <HoverCardPortal>
+ <HoverCardContent
+ id={insightsId}
+ role="region"
+ aria-label={localize('com_ui_context_insights')}
+ data-testid="context-hints"
+ className="max-w-[calc(100vw-2rem)] motion-reduce:data-[state=closed]:animate-none motion-reduce:data-[state=open]:animate-none"
+ align="end"
+ >
+ {insights.map((insight, index) => (
+ <p className="break-words text-xs text-text-secondary" key={index}>
+ {insight}
+ </p>
+ ))}
+ </HoverCardContent>
+ </HoverCardPortal>
+ </HoverCard>
+ )}
+ </div>
+ )}
<div
className="space-y-1.5"
data-testid={breakdown ? 'context-breakdown' : 'context-estimate'}
>
{breakdown ? (
<>
- {segments.map(
- ({ id, label, value, ...segment }) =>
- value > 0 && (
+ {segments.map(({ id, label, value, ...segment }) => {
+ const shouldRender =
+ value > 0 || (id === 'tool-calls' && toolCallTokens != null);
+ if (!shouldRender) {
+ return null;
+ }
+ return (
+ <Fragment key={id}>
+ {id === 'tool-calls' && hasToolCounts ? (
+ <Row
+ label={label}
+ value={value}
+ max={maxTokens}
+ segment={segment}
+ id={id}
+ onHoverChange={setHoveredSegment}
+ onClick={() => setToolsExpanded((open) => !open)}
+ expanded={toolsExpanded}
+ controls={toolsExpanded ? toolBreakdownId : undefined}
+ />
+ ) : (
+ <Row
+ label={label}
+ value={value}
+ max={maxTokens}
+ segment={segment}
+ id={id}
+ onHoverChange={setHoveredSegment}
+ />
+ )}
+ {id === 'tool-calls' && toolsExpanded && hasToolCounts && (
+ <div id={toolBreakdownId} className="space-y-1 pl-6">
+ <p className="text-xs font-medium text-text-tertiary">
+ {localize('com_ui_context_tool_breakdown')}
+ </p>
+ {toolBreakdown.map((tool) => (
+ <Row key={tool.name} label={tool.name} value={tool.tokens} />
+ ))}
+ </div>
+ )}
+ {id === 'system' && dynamicInstructionTokens > 0 && (
+ <div className="pl-6">
+ <Row
+ label={localize('com_ui_context_dynamic_instructions')}
+ value={dynamicInstructionTokens}
+ />
+ </div>
+ )}
+ </Fragment>
+ );
+ })}
+ {/** The reconciling call's cached prompt share is already inside
+ * the segments above (reconciliation counted it in `usedTokens`),
+ * so it renders indented, like the estimate path's tool-call
+ * share — as peer rows a fully cached prompt would show its
+ * tokens twice and the visible rows would sum past the meter. */}
+ {(normalizeTokenCount(view.cacheRead) > 0 ||
+ normalizeTokenCount(view.cacheWrite) > 0) && (
+ <div className="space-y-1.5 pl-6">
+ {normalizeTokenCount(view.cacheRead) > 0 && (
<Row
- key={id}
- label={label}
- value={value}
- max={maxTokens}
- segment={segment}
- id={id}
- onHoverChange={setHoveredSegment}
+ label={localize('com_ui_context_cached')}
+ value={normalizeTokenCount(view.cacheRead)}
/>
- ),
+ )}
+ {normalizeTokenCount(view.cacheWrite) > 0 && (
+ <Row
+ label={localize('com_ui_context_cache_write')}
+ value={normalizeTokenCount(view.cacheWrite)}
+ />
+ )}
+ </div>
)}
{freeTokens != null && (
<Row
@@ -260,7 +530,7 @@ export default function Breakdown({
</>
) : (
<>
- {view.branchTotals.summaryBaseline > 0 && (
+ {normalizeTokenCount(view.branchTotals.summaryBaseline) > 0 && (
<Row
label={localize('com_ui_context_summary')}
value={view.branchTotals.summaryBaseline}
@@ -282,7 +552,7 @@ export default function Breakdown({
label={localize('com_ui_output')}
value={view.branchTotals.output + view.liveTokens}
/>
- {view.estimatedTokens > 0 && (
+ {normalizeTokenCount(view.estimatedTokens) > 0 && (
<Row
label={localize('com_ui_context_estimated')}
value={view.estimatedTokens}
@@ -290,6 +560,21 @@ export default function Breakdown({
)}
</>
)}
+ {/** Retained tool traffic is already inside the message rows above
+ * (their clamped tool-content share), so it renders as an indented
+ * subtotal — as a peer row the visible rows would sum past
+ * `usedTokens`. The snapshot path instead subtracts it from
+ * Messages, which is exact there; here the counted Input/Output
+ * rows are provider counts and this share is a char estimate, so
+ * subtracting it would corrupt them. */}
+ {normalizeTokenCount(view.toolCallTokens) > 0 && (
+ <div className="pl-6">
+ <Row
+ label={localize('com_ui_context_tool_calls')}
+ value={normalizeTokenCount(view.toolCallTokens)}
+ />
+ </div>
+ )}
{view.overheadTokens > 0 && (
<Row label={localize('com_ui_context_system')} value={view.overheadTokens} />
)}
@@ -314,12 +599,19 @@ export default function Breakdown({
</h3>
<Row label={localize('com_ui_input')} value={branchUsage.input} />
<Row label={localize('com_ui_output')} value={branchUsage.output} />
- {branchUsage.cacheRead > 0 && (
+ {normalizeTokenCount(branchUsage.cacheRead) > 0 && (
<Row label={localize('com_ui_cache_read')} value={branchUsage.cacheRead} />
)}
- {branchUsage.cacheWrite > 0 && (
+ {normalizeTokenCount(branchUsage.cacheWrite) > 0 && (
<Row label={localize('com_ui_cache_write')} value={branchUsage.cacheWrite} />
)}
+ {/** Subagent calls are accumulated per conversation for the session
+ * and are not attributed to a response, so they cannot be scoped to
+ * the viewed branch like the rows above; label them all-branches
+ * rather than imply branch scope. */}
+ {subagentTokens > 0 && (
+ <Row label={localize('com_ui_context_subagents_all')} value={subagentTokens} />
+ )}
</div>
</>
)}
diff --git a/client/src/components/Chat/Input/TokenUsage/index.tsx b/client/src/components/Chat/Input/TokenUsage/index.tsx
index c755694b81..41b3ad8ce0 100644
--- a/client/src/components/Chat/Input/TokenUsage/index.tsx
+++ b/client/src/components/Chat/Input/TokenUsage/index.tsx
@@ -43,6 +43,7 @@ function TokenUsageIndicator({
/** Owned here, not in the popover: `unmountOnHide` would otherwise lose the
* in-flight state the moment the pointer leaves. */
const compaction = useCompactConversation();
+ const compactionAvailable = compactionEnabled && supportsCompaction(conversation?.endpoint);
const popover = Ariakit.usePopoverStore({ placement: 'top' });
const popoverOpen = Ariakit.useStoreState(popover, 'open');
const disclosureRef = useRef<HTMLButtonElement>(null);
@@ -243,10 +244,11 @@ function TokenUsageIndicator({
<Breakdown
view={view}
showCost={showCost}
+ compactionAvailable={compactionAvailable}
currency={currency}
langfuseSessionUrl={langfuseSession?.url ?? undefined}
/>
- {compactionEnabled && supportsCompaction(conversation?.endpoint) && (
+ {compactionAvailable && (
<>
<div className="border-t border-border-light" role="separator" />
<CompactAction
diff --git a/client/src/hooks/Chat/__tests__/useTokenUsage.spec.tsx b/client/src/hooks/Chat/__tests__/useTokenUsage.spec.tsx
new file mode 100644
index 0000000000..70daf163d2
--- /dev/null
+++ b/client/src/hooks/Chat/__tests__/useTokenUsage.spec.tsx
@@ -0,0 +1,283 @@
+import { getDefaultStore } from 'jotai';
+import { renderHook } from '@testing-library/react';
+import { QueryKeys } from 'librechat-data-provider';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import type { TMessage, TConversation } from 'librechat-data-provider';
+import type { ContextSnapshot } from '~/store/usage';
+import { contextSnapshotFamily, snapshotsByAnchorFamily } from '~/store/usage';
+import useTokenUsage from '~/hooks/Chat/useTokenUsage';
+
+jest.mock('~/hooks/Messages/useLatestMessage', () => ({
+ useLatestMessageId: () => 'a2',
+}));
+
+jest.mock('~/hooks/Chat/useTokenLimits', () => ({
+ __esModule: true,
+ default: () => ({ maxContextTokens: 200000, endpoint: 'agents', model: 'test-model' }),
+}));
+
+const convo = 'convo-post-snapshot';
+
+/** Two completed turns: the tail response `a2` answers `u2`. */
+const messages = [
+ {
+ messageId: 'u1',
+ parentMessageId: null,
+ conversationId: convo,
+ isCreatedByUser: true,
+ tokenCount: 400,
+ text: 'first ask',
+ },
+ {
+ messageId: 'a1',
+ parentMessageId: 'u1',
+ conversationId: convo,
+ isCreatedByUser: false,
+ tokenCount: 1500,
+ text: 'first answer',
+ },
+ {
+ messageId: 'u2',
+ parentMessageId: 'a1',
+ conversationId: convo,
+ isCreatedByUser: true,
+ tokenCount: 500,
+ text: 'second ask',
+ },
+ {
+ messageId: 'a2',
+ parentMessageId: 'u2',
+ conversationId: convo,
+ isCreatedByUser: false,
+ tokenCount: 2000,
+ text: 'second answer',
+ },
+] as unknown as TMessage[];
+
+/** Persisted per-turn snapshots: used grows 1000 tokens per call
+ * (196000 → 195000 remaining of a 200000 budget). */
+const anchorSnapshot = (remaining: number): ContextSnapshot =>
+ ({
+ anchorMessageId: null,
+ model: 'test-model',
+ provider: 'openAI',
+ contextBudget: 200000,
+ remainingContextTokens: remaining,
+ breakdown: { maxContextTokens: 200000, instructionTokens: 4000 },
+ }) as unknown as ContextSnapshot;
+
+/** The live snapshot for the tail call: pre-invoke, so its remaining headroom
+ * and message total both predate `a2`'s 2000 output tokens. */
+const tailSnapshot: ContextSnapshot = {
+ anchorMessageId: 'u2',
+ model: 'test-model',
+ provider: 'openAI',
+ contextBudget: 200000,
+ remainingContextTokens: 5000,
+ completedOutputTokens: 2000,
+ breakdown: {
+ maxContextTokens: 200000,
+ instructionTokens: 4000,
+ messageTokens: 10000,
+ },
+} as unknown as ContextSnapshot;
+
+const renderTokenUsage = (
+ anchors: Map<string, ContextSnapshot> = new Map([
+ ['a1', anchorSnapshot(196000)],
+ ['a2', anchorSnapshot(195000)],
+ ]),
+ overrides: { messages?: TMessage[]; snapshot?: ContextSnapshot } = {},
+) => {
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ queryClient.setQueryData([QueryKeys.messages, convo], overrides.messages ?? messages);
+ const store = getDefaultStore();
+ store.set(contextSnapshotFamily(convo), overrides.snapshot ?? tailSnapshot);
+ store.set(snapshotsByAnchorFamily(convo), anchors);
+
+ return renderHook(
+ () =>
+ useTokenUsage({
+ index: 0,
+ conversation: { conversationId: convo, endpoint: 'agents' } as TConversation,
+ isSubmitting: false,
+ }),
+ {
+ wrapper: ({ children }) => (
+ <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+ ),
+ },
+ );
+};
+
+describe('useTokenUsage — post-snapshot output', () => {
+ it('charges the finalized output against the runway projection', () => {
+ const { result } = renderTokenUsage();
+
+ /** 5000 pre-invoke remaining − 2000 already generated = 3000 of real
+ * headroom at 1000 tokens per call. Using the stale remaining would
+ * promise 5 more turns. */
+ expect(result.current.runwayTurns).toBe(3);
+ });
+
+ it('counts the finalized output in what a summarization could reclaim', () => {
+ const { result } = renderTokenUsage();
+
+ /** 10000 pre-invoke message tokens + 2000 finalized output − the kept
+ * latest exchange (500 + 2000) = 9500. Omitting the output would
+ * under-report the reclaim by the size of the final answer. */
+ expect(result.current.compactionReclaim).toBe(9500);
+ });
+
+ /** The older persisted shape: a budget and a breakdown, no remaining count. */
+ const legacySnapshot = (messageTokens: number): ContextSnapshot =>
+ ({
+ anchorMessageId: null,
+ model: 'test-model',
+ provider: 'openAI',
+ contextBudget: 200000,
+ breakdown: { maxContextTokens: 200000, instructionTokens: 4000, messageTokens },
+ }) as unknown as ContextSnapshot;
+
+ it('projects a branch whose snapshots predate the remaining-token field', () => {
+ /** Both readings are instruction+messages sums — 13000 then 14000, so the
+ * call grew 1000. Reading the absent remaining as zero would score both
+ * turns as having spent the entire 200000 window and hide the projection. */
+ const { result } = renderTokenUsage(
+ new Map([
+ ['a1', legacySnapshot(9000)],
+ ['a2', legacySnapshot(10000)],
+ ]),
+ );
+
+ expect(result.current.runwayTurns).toBe(3);
+ });
+
+ it('withholds the projection when the two readings were measured differently', () => {
+ /** `a1` reports remaining headroom (4000 used of 200000) and `a2` only a
+ * breakdown (14000). Their difference is the content a breakdown omits,
+ * not what the last call added, so no per-call growth can be read from
+ * the pair — a 10000-token "growth" would report zero turns left. */
+ const { result } = renderTokenUsage(
+ new Map([
+ ['a1', anchorSnapshot(196000)],
+ ['a2', legacySnapshot(10000)],
+ ]),
+ );
+
+ expect(result.current.runwayTurns).toBeUndefined();
+ });
+
+ it.each([
+ { model: 'other-model' },
+ { provider: 'anthropic' },
+ { agentId: 'other-agent' },
+ { contextBudget: 100000 },
+ { breakdown: { maxContextTokens: 200000, instructionTokens: 8000 } },
+ { breakdown: { maxContextTokens: 200000, toolSchemaTokens: 8000 } },
+ { model: undefined },
+ { provider: undefined },
+ ])('withholds runway across a configuration change: %j', (change) => {
+ const { result } = renderTokenUsage(
+ new Map([
+ [
+ 'a1',
+ {
+ ...anchorSnapshot(196000),
+ ...change,
+ breakdown: { ...anchorSnapshot(196000).breakdown, ...change.breakdown },
+ },
+ ],
+ ['a2', anchorSnapshot(195000)],
+ ]),
+ );
+ expect(result.current.runwayTurns).toBeUndefined();
+ });
+
+ it('withholds old runway history during a newly configured run', () => {
+ const { result } = renderTokenUsage(undefined, {
+ snapshot: { ...tailSnapshot, model: 'new-model' },
+ });
+ expect(result.current.runwayTurns).toBeUndefined();
+ });
+
+ it('restores cache rows and call identity from persisted snapshots', () => {
+ const persisted = {
+ ...anchorSnapshot(195000),
+ cacheRead: 800,
+ cacheWrite: 200,
+ completedOutputTokens: 50,
+ };
+ const persistedById: Record<string, ContextSnapshot> = {
+ a1: anchorSnapshot(196000),
+ a2: persisted,
+ };
+ const { result } = renderTokenUsage(new Map(), {
+ snapshot: { ...tailSnapshot, anchorMessageId: 'unrelated-branch' },
+ messages: messages.map((message) => ({
+ ...message,
+ metadata: {
+ contextUsage: persistedById[message.messageId],
+ },
+ })),
+ });
+ expect(result.current.cacheRead).toBe(800);
+ expect(result.current.cacheWrite).toBe(200);
+ expect(result.current.snapshot?.model).toBe('test-model');
+ expect(result.current.runwayTurns).toBe(194);
+ });
+
+ it('excludes the retained latest tool result from compaction savings', () => {
+ const { result } = renderTokenUsage(undefined, {
+ messages: messages.map((message) =>
+ message.messageId === 'a2'
+ ? ({
+ ...message,
+ content: [
+ {
+ type: 'tool_call',
+ tool_call: {
+ name: 'read_file',
+ args: 'path',
+ output: 'r'.repeat(20000),
+ },
+ },
+ ],
+ } as TMessage)
+ : message,
+ ),
+ });
+ expect(result.current.compactionReclaim).toBe(4500);
+ });
+
+ it('leaves a summarizing turn’s summary completion out of the reclaim estimate', () => {
+ /** The tail turn compacted: its `tokenCount` carries the 700-token
+ * summarization completion the backend folded in, while the snapshot holds
+ * those tokens in `summaryTokens` rather than `messageTokens`. Subtracting
+ * the whole response would understate the reclaim by that summary.
+ * 10000 messages + 2000 finalized output − (500 user + 2000 answer − 700
+ * summary) = 10200. */
+ const summarizedMessages = messages.map((message) =>
+ (message as TMessage).messageId === 'a2'
+ ? ({ ...message, metadata: { summaryUsedTokens: 8000 } } as TMessage)
+ : message,
+ );
+
+ /** After finalize the live snapshot is re-anchored to the response id, so
+ * the compacting turn's own snapshot still describes the viewed branch. */
+ const summarizedSnapshot = {
+ ...tailSnapshot,
+ anchorMessageId: 'a2',
+ breakdown: { ...tailSnapshot.breakdown, summaryTokens: 700 },
+ } as unknown as ContextSnapshot;
+
+ const { result } = renderTokenUsage(undefined, {
+ messages: summarizedMessages,
+ snapshot: summarizedSnapshot,
+ });
+
+ expect(result.current.compactionReclaim).toBe(10200);
+ });
+});
diff --git a/client/src/hooks/Chat/useTokenUsage.ts b/client/src/hooks/Chat/useTokenUsage.ts
index 1f4a474d3f..8cffbf407d 100644
--- a/client/src/hooks/Chat/useTokenUsage.ts
+++ b/client/src/hooks/Chat/useTokenUsage.ts
@@ -13,6 +13,8 @@ import {
removeUsageAtoms,
hydrateSnapshots,
pendingUsageFamily,
+ subagentUsageFamily,
+ pendingSubagentUsageFamily,
branchTotalsFamily,
contextSnapshotFamily,
snapshotsByAnchorFamily,
@@ -24,7 +26,11 @@ import {
mergeUsage,
sumTotalUsage,
prunedBranchTokens,
+ collectAnchorSeries,
+ snapshotConfiguration,
+ latestExchangeTokens,
findBranchSnapshotAnchor,
+ normalizeTokenCount,
} from '~/utils';
import { useLatestMessageId } from '~/hooks/Messages/useLatestMessage';
import useTokenLimits from './useTokenLimits';
@@ -68,6 +74,23 @@ export interface TokenUsageView {
/** True when over-window pruning replaced the raw message sum, so the breakdown
* 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. */
+ toolCallTokens?: number;
+ /** Cache split of the reconciling call's prompt (live or persisted) — a
+ * share of the used context, not an addition. */
+ cacheRead?: number;
+ cacheWrite?: number;
+ /** Per-tool result-token counts, when provided by the usage snapshot */
+ toolMessageTokenCounts?: Record<string, number>;
+ /** Turns of headroom at the current per-call growth (undefined when unknown) */
+ runwayTurns?: number;
+ /** Tokens a summarization could reclaim ≈ context − latest exchange */
+ compactionReclaim?: number;
+ /** Live subagent model-call usage — a subset of Totals */
+ subagentUsage?: BranchUsage;
rates?: TModelTokenomics;
}
@@ -90,6 +113,8 @@ export default function useTokenUsage({
const totalUsageBase = useAtomValue(totalUsageFamily(conversationKey));
const branchTotals = useAtomValue(branchTotalsFamily(conversationKey));
const liveTokens = useAtomValue(liveTokensFamily(conversationKey));
+ const committedSubagentUsage = useAtomValue(subagentUsageFamily(conversationKey));
+ const pendingSubagentUsage = useAtomValue(pendingSubagentUsageFamily(conversationKey));
const setBranchTotals = useSetAtom(branchTotalsFamily(conversationKey));
const setTotalUsage = useSetAtom(totalUsageFamily(conversationKey));
const limits = useTokenLimits(conversation);
@@ -115,12 +140,17 @@ export default function useTokenUsage({
* call (premium tiers, cache rates), so cost sums authoritatively. */
const pendingAsUsage: BranchUsage = useMemo(
() => ({
- input: pendingUsage.input,
- output: pendingUsage.output,
- cacheWrite: pendingUsage.cacheWrite,
- cacheRead: pendingUsage.cacheRead,
- cost: pendingUsage.costUSD,
- costKnown: pendingUsage.costKnown,
+ input: normalizeTokenCount(pendingUsage.input),
+ output: normalizeTokenCount(pendingUsage.output),
+ cacheWrite: normalizeTokenCount(pendingUsage.cacheWrite),
+ cacheRead: normalizeTokenCount(pendingUsage.cacheRead),
+ cost:
+ typeof pendingUsage.costUSD === 'number' &&
+ Number.isFinite(pendingUsage.costUSD) &&
+ pendingUsage.costUSD > 0
+ ? pendingUsage.costUSD
+ : 0,
+ costKnown: pendingUsage.costKnown === true,
}),
[pendingUsage],
);
@@ -132,6 +162,13 @@ export default function useTokenUsage({
() => mergeUsage(totalUsageBase, pendingAsUsage),
[totalUsageBase, pendingAsUsage],
);
+ /** The subagent figure mirrors that split: what earlier runs committed plus
+ * the in-flight run's share, which settles or is discarded with the pending
+ * usage it sits inside. */
+ const subagentUsage = useMemo(
+ () => mergeUsage(committedSubagentUsage, pendingSubagentUsage),
+ [committedSubagentUsage, pendingSubagentUsage],
+ );
const hasUsage =
branchUsage.input + branchUsage.output + branchUsage.cacheRead + branchUsage.cacheWrite > 0;
@@ -222,19 +259,62 @@ export default function useTokenUsage({
* history, imports, never-generated branches) entirely client-side. */
const effective: ContextSnapshot | null = currentActive ? snapshot : branchSnapshot;
+ /** Branch analysis: the snapshot series (oldest → newest) drives the runway
+ * projection. Walks use the branch tail, capped at summary markers,
+ * mirroring `sumBranch`. */
+ const tailId = branchTotals.tailId;
+ 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. */
+ const completedOutput = normalizeTokenCount(effective?.completedOutputTokens);
+ const liveOutput = normalizeTokenCount(liveTokens);
+ const remainingForRunway =
+ effective?.remainingContextTokens != null
+ ? Math.max(
+ 0,
+ normalizeTokenCount(effective.remainingContextTokens) - completedOutput - liveOutput,
+ )
+ : null;
+ let runwayTurns: number | undefined;
+ if (anchorSeries.length >= 2 && remainingForRunway != null) {
+ const latest = anchorSeries[anchorSeries.length - 1];
+ const previous = anchorSeries[anchorSeries.length - 2];
+ /** Growth is only a per-call delta when both readings were measured the
+ * same way; a remaining-based reading next to a breakdown-derived one
+ * (a snapshot saved before `remainingContextTokens` existed) differs by
+ * the content the breakdown omits, not by what the last call added. The
+ * projection stays unavailable rather than reporting that difference. */
+ const comparable =
+ latest.basis === previous.basis &&
+ latest.configuration != null &&
+ latest.configuration === previous.configuration &&
+ effective != null &&
+ latest.configuration === snapshotConfiguration(effective);
+ const perCallGrowth = comparable ? latest.used - previous.used : 0;
+ if (perCallGrowth > 0) {
+ runwayTurns = Math.max(0, Math.floor(remainingForRunway / perCallGrowth));
+ }
+ }
if (effective != null) {
const breakdown = effective.breakdown;
- const maxTokens = effective.contextBudget ?? breakdown.maxContextTokens;
- const instructionTokens = effective.effectiveInstructionTokens ?? breakdown.instructionTokens;
- const baseUsed =
+ const maxTokens = normalizeTokenCount(effective.contextBudget ?? breakdown.maxContextTokens);
+ const instructionTokens = normalizeTokenCount(
+ effective.effectiveInstructionTokens ?? breakdown.instructionTokens,
+ );
+ const remainingContextTokens =
effective.remainingContextTokens != null
- ? maxTokens - effective.remainingContextTokens
- : instructionTokens + breakdown.messageTokens;
+ ? normalizeTokenCount(effective.remainingContextTokens)
+ : null;
+ const baseUsed =
+ remainingContextTokens != null
+ ? maxTokens - remainingContextTokens
+ : 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 =
- Math.max(0, baseUsed) + liveTokens + (effective.completedOutputTokens ?? 0);
+ const usedTokens = normalizeTokenCount(Math.max(0, baseUsed) + liveOutput + completedOutput);
return {
usedTokens,
maxTokens,
@@ -248,11 +328,42 @@ export default function useTokenUsage({
hasUsage,
branchCost: branchUsage.cost,
totalCost: totalUsage.cost,
- liveTokens,
+ liveTokens: liveOutput,
estimatedTokens: 0,
overheadTokens: 0,
messageTokens: 0,
messagesPruned: false,
+ toolCallTokens:
+ breakdown.toolMessageTokens != null
+ ? Math.min(
+ normalizeTokenCount(breakdown.toolMessageTokens),
+ normalizeTokenCount(breakdown.messageTokens),
+ )
+ : undefined,
+ cacheRead: normalizeTokenCount(effective.cacheRead),
+ cacheWrite: normalizeTokenCount(effective.cacheWrite),
+ toolMessageTokenCounts: breakdown.toolMessageTokenCounts,
+ runwayTurns,
+ /** Both sides are measured after the tail call: `breakdown.messageTokens`
+ * is pre-invoke, so add the finalized output that `latestExchangeTokens`
+ * already counts in the exchange a summarization would keep, and hand it
+ * 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`). */
+ compactionReclaim: Math.max(
+ 0,
+ normalizeTokenCount(breakdown.messageTokens) +
+ completedOutput -
+ latestExchangeTokens(
+ conversationKey,
+ tailId,
+ liveTokens > 0,
+ normalizeTokenCount(breakdown.summaryTokens),
+ ),
+ ),
+ subagentUsage,
rates: limits.rates,
};
}
@@ -266,8 +377,9 @@ export default function useTokenUsage({
* there, so input/output are post-summary only — adding it keeps the estimate
* from re-summing the discarded pre-summary history (which otherwise pins the
* gauge at 100% after a compaction). */
- const maxTokens = limits.maxContextTokens;
- const liveOnTail = liveTokens > 0;
+ const maxTokens =
+ limits.maxContextTokens != null ? normalizeTokenCount(limits.maxContextTokens) : undefined;
+ const liveOnTail = normalizeTokenCount(liveTokens) > 0;
/** Fixed instruction + tool-schema overhead for this agent/model (the latter is
* already folded into `instructionTokens`), cached from live usage events. The
* client can't otherwise know it for a snapshot-less branch, so reserve it from
@@ -279,11 +391,13 @@ export default function useTokenUsage({
const overheadTokens =
branchTotals.summaryBaseline > 0
? 0
- : getModelOverhead(
- overheadKey(
- limits.endpoint ?? conversation?.endpoint,
- limits.model ?? conversation?.model,
- conversation?.agent_id,
+ : normalizeTokenCount(
+ getModelOverhead(
+ overheadKey(
+ limits.endpoint ?? conversation?.endpoint,
+ limits.model ?? conversation?.model,
+ conversation?.agent_id,
+ ),
),
);
/** When a stream is live the tail is the in-flight response, already counted
@@ -291,10 +405,23 @@ export default function useTokenUsage({
* isn't double-counted on the estimate path. */
const estimatedTokens = Math.max(
0,
- branchTotals.estTokens - (liveOnTail ? branchTotals.tailEstTokens : 0),
+ normalizeTokenCount(branchTotals.estTokens) -
+ (liveOnTail ? normalizeTokenCount(branchTotals.tailEstTokens) : 0),
);
- const rawMessageTokens = branchTotals.input + branchTotals.output + estimatedTokens;
+ const rawMessageTokens =
+ normalizeTokenCount(branchTotals.input) +
+ normalizeTokenCount(branchTotals.output) +
+ estimatedTokens;
let messageTokens = rawMessageTokens;
+ /** Tool-call share of the same walk (a subset of input/output/estimated).
+ * Mirrors the tail exclusion so a live in-flight response's tool tokens
+ * aren't counted before its content lands. */
+ const estimatedToolTokens = Math.max(
+ 0,
+ normalizeTokenCount(branchTotals.estToolTokens) -
+ (liveOnTail ? normalizeTokenCount(branchTotals.tailEstToolTokens) : 0),
+ );
+ let toolTokens = Math.min(estimatedToolTokens, messageTokens);
/** The send path prunes an over-window branch oldest-first before calling the
* model, so the next call can sit well under the window even when the full
* branch exceeds it. Mirror that: when the raw sum overflows the message window
@@ -302,21 +429,35 @@ export default function useTokenUsage({
* the newest messages that actually fit instead of clamping the whole branch to
* 100%. */
if (maxTokens != null && maxTokens > 0) {
- const messageBudget = Math.max(0, maxTokens - branchTotals.summaryBaseline - overheadTokens);
+ const messageBudget = Math.max(
+ 0,
+ maxTokens - normalizeTokenCount(branchTotals.summaryBaseline) - overheadTokens,
+ );
if (messageTokens > messageBudget) {
- messageTokens = prunedBranchTokens(
+ const pruned = prunedBranchTokens(
conversationKey,
branchTotals.tailId,
messageBudget,
liveOnTail,
);
+ messageTokens = normalizeTokenCount(pruned.tokens);
+ toolTokens = Math.min(normalizeTokenCount(pruned.toolTokens), messageTokens);
}
}
/** When pruning replaced the raw sum, the per-category input/output/estimated
- * rows no longer describe what's sent, so the breakdown collapses them into a
- * single pruned Messages row to stay consistent with the gauge. */
+ * rows no longer describe what's sent, so the breakdown collapses them into
+ * a single pruned Messages row to stay consistent with the gauge. */
const messagesPruned = messageTokens < rawMessageTokens;
- const usedTokens = overheadTokens + branchTotals.summaryBaseline + messageTokens + liveTokens;
+ const compactionReclaim = Math.max(
+ 0,
+ messageTokens - latestExchangeTokens(conversationKey, branchTotals.tailId, liveOnTail),
+ );
+ const usedTokens = normalizeTokenCount(
+ overheadTokens +
+ normalizeTokenCount(branchTotals.summaryBaseline) +
+ messageTokens +
+ normalizeTokenCount(liveTokens),
+ );
return {
usedTokens,
maxTokens,
@@ -331,11 +472,14 @@ export default function useTokenUsage({
hasUsage,
branchCost: branchUsage.cost,
totalCost: totalUsage.cost,
- liveTokens,
+ liveTokens: normalizeTokenCount(liveTokens),
estimatedTokens,
overheadTokens,
messageTokens,
messagesPruned,
+ toolCallTokens: toolTokens > 0 ? toolTokens : undefined,
+ compactionReclaim,
+ subagentUsage,
rates: limits.rates,
};
}, [
@@ -348,6 +492,8 @@ export default function useTokenUsage({
liveTokens,
limits,
branchSnapshot,
+ snapshotsByAnchor,
+ subagentUsage,
conversationKey,
conversation,
]);
diff --git a/client/src/hooks/SSE/__tests__/useUsageHandler.spec.tsx b/client/src/hooks/SSE/__tests__/useUsageHandler.spec.tsx
index 41ba9e3511..d571c4d676 100644
--- a/client/src/hooks/SSE/__tests__/useUsageHandler.spec.tsx
+++ b/client/src/hooks/SSE/__tests__/useUsageHandler.spec.tsx
@@ -1,8 +1,14 @@
import { getDefaultStore } from 'jotai';
import { renderHook } from '@testing-library/react';
+import { Constants, reconcileContextUsageFromEvent } from 'librechat-data-provider';
import type { TContextUsageEvent, TTokenUsageEvent } from 'librechat-data-provider';
+import {
+ contextSnapshotFamily,
+ liveTokensFamily,
+ subagentUsageFamily,
+ pendingSubagentUsageFamily,
+} from '~/store/usage';
import useUsageHandler from '~/hooks/SSE/useUsageHandler';
-import { contextSnapshotFamily } from '~/store/usage';
/** Mirrors a real web-search + summarization turn: calibration pinned at 5
* inflated messageTokens to 187471 (used 213375), while the call's true prompt
@@ -33,6 +39,7 @@ const primaryUsage = (over?: Partial<TTokenUsageEvent>): TTokenUsageEvent => ({
total_tokens: 59553,
input_token_details: { cache_read: 2071, cache_creation: 0 },
provider: 'anthropic',
+ model: 'primary-model',
runId: 'run-1',
seq: 1,
...over,
@@ -60,6 +67,47 @@ describe('useUsageHandler — live snapshot reconciliation', () => {
/** instructions/summary stay raw; the anchor is preserved */
expect(snap?.breakdown.instructionTokens).toBe(4205);
expect(snap?.anchorMessageId).toBe('u1');
+ expect(snap).toMatchObject({
+ cacheRead: 2071,
+ cacheWrite: 0,
+ model: 'primary-model',
+ provider: 'anthropic',
+ });
+ });
+
+ it('keeps resumed completed output once through text seeding, replay, and finalize', () => {
+ const convo = 'convo-resume-completed';
+ const submission = {
+ userMessage: { messageId: 'u-completed', conversationId: convo },
+ conversation: { conversationId: convo },
+ };
+ const { result } = renderHook(() => useUsageHandler());
+ const store = getDefaultStore();
+ const usage = primaryUsage();
+ const { completedOutputTokens, ...reconciled } = reconcileContextUsageFromEvent(
+ inflatedSnapshot(),
+ usage,
+ );
+ const snapshot = { ...reconciled, resumedOutputTokens: completedOutputTokens };
+ result.current.backfillUsage([usage], submission);
+ result.current.contextHandler(snapshot, submission);
+ result.current.seedLive(12000, submission);
+ result.current.usageHandler(usage, submission);
+ expect(store.get(liveTokensFamily(convo))).toBe(0);
+ expect(store.get(contextSnapshotFamily(convo))?.completedOutputTokens).toBe(3780);
+ result.current.finalizeUsage(
+ {
+ conversation: { conversationId: convo },
+ responseMessage: { messageId: 'a-completed', conversationId: convo },
+ },
+ submission,
+ );
+ expect(store.get(contextSnapshotFamily(convo))?.completedOutputTokens).toBe(3780);
+
+ result.current.contextHandler(inflatedSnapshot(), submission);
+ result.current.seedLive(400, submission);
+ expect(store.get(contextSnapshotFamily(convo))?.completedOutputTokens).toBeUndefined();
+ expect(store.get(liveTokensFamily(convo))).toBe(500);
});
it('does not reconcile a replayed (already-folded) primary usage', () => {
@@ -113,4 +161,85 @@ describe('useUsageHandler — live snapshot reconciliation', () => {
expect(store.get(contextSnapshotFamily(convo))?.breakdown.messageTokens).toBe(187471);
});
+
+ it('carries subagent totals through the new-conversation id handoff', () => {
+ /** The first turn of a new chat accumulates under `new`; `finalizeUsage`
+ * migrates the usage atoms to the persisted id and drops the temporary
+ * ones, so a subagent total left behind would vanish on completion. */
+ const newConvo: string = Constants.NEW_CONVO;
+ const submission = {
+ userMessage: { messageId: 'u-sub', conversationId: newConvo },
+ conversation: { conversationId: newConvo },
+ };
+ const { result } = renderHook(() => useUsageHandler());
+ const store = getDefaultStore();
+
+ result.current.usageHandler(
+ primaryUsage({ usage_type: 'subagent', runId: 'run-sub', seq: 11 }),
+ submission,
+ );
+ expect(store.get(pendingSubagentUsageFamily(newConvo)).output).toBe(3780);
+
+ result.current.finalizeUsage(
+ {
+ conversation: { conversationId: 'convo-sub-real' },
+ responseMessage: { messageId: 'r-sub', conversationId: 'convo-sub-real' },
+ },
+ submission,
+ );
+
+ const migrated = store.get(subagentUsageFamily('convo-sub-real'));
+ expect(migrated.input).toBe(53702);
+ expect(migrated.output).toBe(3780);
+ expect(store.get(pendingSubagentUsageFamily('convo-sub-real')).output).toBe(0);
+ });
+
+ it('drops a failed run’s subagent share with the usage it belonged to', () => {
+ /** Terminal error with no salvageable response: the pending usage is
+ * discarded, so the Totals row must not keep advertising tokens that no
+ * longer appear in the branch or conversation rollups. */
+ const convo = 'convo-sub-failed';
+ const submission = {
+ userMessage: { messageId: 'u-fail', conversationId: convo },
+ conversation: { conversationId: convo },
+ };
+ const { result } = renderHook(() => useUsageHandler());
+ const store = getDefaultStore();
+
+ result.current.usageHandler(
+ primaryUsage({ usage_type: 'subagent', runId: 'run-fail', seq: 21 }),
+ submission,
+ );
+ result.current.resetLive(submission);
+
+ expect(store.get(pendingSubagentUsageFamily(convo)).output).toBe(0);
+ expect(store.get(subagentUsageFamily(convo)).output).toBe(0);
+ });
+
+ it('counts a resumed run’s subagent events once', () => {
+ /** `resetLive` forgets the folded identities so a resume can rebuild
+ * pending; re-folding the same subagent event must not add its tokens a
+ * second time. */
+ const convo = 'convo-sub-resume';
+ const submission = {
+ userMessage: { messageId: 'u-resume', conversationId: convo },
+ conversation: { conversationId: convo },
+ };
+ const { result } = renderHook(() => useUsageHandler());
+ const store = getDefaultStore();
+ const event = primaryUsage({ usage_type: 'subagent', runId: 'run-resume', seq: 31 });
+
+ result.current.usageHandler(event, submission);
+ result.current.resetLive(submission);
+ result.current.backfillUsage([event], submission);
+ result.current.finalizeUsage(
+ {
+ conversation: { conversationId: convo },
+ responseMessage: { messageId: 'r-resume', conversationId: convo },
+ },
+ submission,
+ );
+
+ expect(store.get(subagentUsageFamily(convo)).output).toBe(3780);
+ });
});
diff --git a/client/src/hooks/SSE/useUsageHandler.ts b/client/src/hooks/SSE/useUsageHandler.ts
index 268d0153c1..ab6bea2c4b 100644
--- a/client/src/hooks/SSE/useUsageHandler.ts
+++ b/client/src/hooks/SSE/useUsageHandler.ts
@@ -1,6 +1,6 @@
import { useRef, useMemo } from 'react';
import { getDefaultStore } from 'jotai';
-import { Constants, reconcileContextUsage, promptTokensFromUsage } from 'librechat-data-provider';
+import { Constants, reconcileContextUsageFromEvent } from 'librechat-data-provider';
import type {
TMessage,
TConversation,
@@ -11,6 +11,7 @@ import type { ContextSnapshot } from '~/store/usage';
import {
overheadKey,
markUsageFolded,
+ migrateUsageFolded,
liveTokensFamily,
totalUsageFamily,
removeUsageAtoms,
@@ -19,13 +20,16 @@ import {
calibrationFamily,
pendingUsageFamily,
branchTotalsFamily,
- migrateUsageFolded,
+ subagentUsageFamily,
+ pendingSubagentUsageFamily,
EMPTY_USAGE_TOTALS,
contextSnapshotFamily,
snapshotsByAnchorFamily,
} from '~/store/usage';
import {
sumBranch,
+ mergeUsage,
+ EMPTY_USAGE,
setEntryUsage,
upsertEntries,
migrateIndex,
@@ -130,7 +134,8 @@ export default function useUsageHandler(): UsageHandlers {
const flushPendingInto = (convoKey: string, responseId: string | null) => {
const pendingAtom = pendingUsageFamily(convoKey);
const pending = jotai.get(pendingAtom);
- if (responseId != null && pending.eventCount > 0) {
+ const keep = responseId != null && pending.eventCount > 0;
+ if (keep) {
setEntryUsage(convoKey, responseId, {
input: pending.input,
output: pending.output,
@@ -140,6 +145,16 @@ export default function useUsageHandler(): UsageHandlers {
costKnown: pending.costKnown,
});
}
+ /** The run's subagent share settles with the usage it is a subset of:
+ * committed to the conversation figure when the response keeps that
+ * usage, dropped with it otherwise. */
+ const pendingSubAtom = pendingSubagentUsageFamily(convoKey);
+ const pendingSub = jotai.get(pendingSubAtom);
+ if (keep) {
+ const committedAtom = subagentUsageFamily(convoKey);
+ jotai.set(committedAtom, mergeUsage(jotai.get(committedAtom), pendingSub));
+ }
+ jotai.set(pendingSubAtom, EMPTY_USAGE);
jotai.set(pendingAtom, EMPTY_USAGE_TOTALS);
};
@@ -147,6 +162,7 @@ export default function useUsageHandler(): UsageHandlers {
const convoKey = getConvoKey(submission);
jotai.set(contextSnapshotFamily(convoKey), {
...data,
+ completedOutputTokens: data.resumedOutputTokens ?? data.completedOutputTokens,
anchorMessageId: submission.userMessage?.messageId ?? null,
});
if (data.calibrationRatio != null && data.calibrationRatio > 0) {
@@ -187,6 +203,9 @@ export default function useUsageHandler(): UsageHandlers {
/** Displayed counts use the same normalized units billing does: input is
* the uncached portion, output includes repaired completion tokens */
const units = normalizeUsageUnits(data);
+ const rawCost = data.cost;
+ const costKnown = typeof rawCost === 'number' && Number.isFinite(rawCost) && rawCost >= 0;
+ const cost = costKnown ? rawCost : 0;
const pendingAtom = pendingUsageFamily(convoKey);
const prev = jotai.get(pendingAtom);
@@ -198,10 +217,27 @@ export default function useUsageHandler(): UsageHandlers {
eventCount: prev.eventCount + 1,
/** Authoritative per-event cost from the backend (premium tiers, cache
* rates); absent when contextCost is disabled — sums to 0 then */
- costUSD: prev.costUSD + (data.cost ?? 0),
+ costUSD: prev.costUSD + cost,
/** Coverage is complete only if EVERY folded event carried a cost */
- costKnown: prev.costKnown && data.cost != null,
+ costKnown: prev.costKnown && costKnown,
});
+ /** Subagent calls are inside the rollup above (the backend's persisted
+ * rollup includes them too) — track this run's share beside the pending
+ * usage it is a subset of, so the Totals row settles with that usage
+ * instead of surviving a discarded run or being folded twice by a
+ * resume. */
+ if (data.usage_type === 'subagent') {
+ const subAtom = pendingSubagentUsageFamily(convoKey);
+ const subPrev = jotai.get(subAtom);
+ jotai.set(subAtom, {
+ input: subPrev.input + units.input,
+ output: subPrev.output + units.output,
+ cacheWrite: subPrev.cacheWrite + units.cacheWrite,
+ cacheRead: subPrev.cacheRead + units.cacheRead,
+ cost: subPrev.cost + cost,
+ costKnown: subPrev.costKnown && costKnown,
+ });
+ }
return true;
};
@@ -222,8 +258,12 @@ export default function useUsageHandler(): UsageHandlers {
if (snapshot.runId != null && data.runId != null && snapshot.runId !== data.runId) {
return;
}
- const reconciled = reconcileContextUsage(snapshot, promptTokensFromUsage(data));
- jotai.set(snapshotAtom, { ...reconciled, anchorMessageId: snapshot.anchorMessageId });
+ jotai.set(snapshotAtom, {
+ ...reconcileContextUsageFromEvent(snapshot, data),
+ /** Live output is held in confirmedRef until finalization. */
+ completedOutputTokens: undefined,
+ anchorMessageId: snapshot.anchorMessageId,
+ });
};
const usageHandler: UsageHandlers['usageHandler'] = (data, submission) => {
@@ -286,12 +326,15 @@ export default function useUsageHandler(): UsageHandlers {
const convoKey = getConvoKey(submission);
setLive(convoKey, 0);
/** Terminal path with no salvageable response (stream error / intentional
- * close): discard the in-flight pending usage so it can't merge into the
- * next response. The user-stop path uses `attributePending` to keep it on
- * the partial reply. Also forget the folded-event identities so a resume's
- * `backfillUsage` can rebuild pending — otherwise it sees them as already
- * folded and the response's usage stays missing until a full reload. */
+ * close): discard the in-flight pending usage — and the subagent share
+ * inside it — so neither can merge into the next response nor outlive the
+ * rollups it belongs to. The user-stop path uses `attributePending` to
+ * keep it on the partial reply. Also forget the folded-event identities
+ * so a resume's `backfillUsage` can rebuild pending — otherwise it sees
+ * them as already folded and the response's usage stays missing until a
+ * full reload. */
jotai.set(pendingUsageFamily(convoKey), EMPTY_USAGE_TOTALS);
+ jotai.set(pendingSubagentUsageFamily(convoKey), EMPTY_USAGE);
clearUsageFolded(convoKey);
};
@@ -320,10 +363,12 @@ export default function useUsageHandler(): UsageHandlers {
};
const seedLive: UsageHandlers['seedLive'] = (chars, submission) => {
- if (chars <= 0) {
+ const convoKey = getConvoKey(submission);
+ /** A completed resumed call already carries exact output in its snapshot.
+ * Trailing text is the same output, not a new streaming delta. */
+ if (chars <= 0 || jotai.get(contextSnapshotFamily(convoKey))?.completedOutputTokens != null) {
return;
}
- const convoKey = getConvoKey(submission);
streamCharsRef.current = chars;
confirmedRef.current = 0;
setLive(convoKey, estimateTokens(chars, jotai.get(calibrationFamily(convoKey))));
@@ -346,6 +391,11 @@ export default function useUsageHandler(): UsageHandlers {
jotai.set(snapshotsByAnchorFamily(realId), jotai.get(snapshotsByAnchorFamily(fromKey)));
jotai.set(pendingUsageFamily(realId), jotai.get(pendingUsageFamily(fromKey)));
jotai.set(calibrationFamily(realId), jotai.get(calibrationFamily(fromKey)));
+ jotai.set(subagentUsageFamily(realId), jotai.get(subagentUsageFamily(fromKey)));
+ jotai.set(
+ pendingSubagentUsageFamily(realId),
+ jotai.get(pendingSubagentUsageFamily(fromKey)),
+ );
removeUsageAtoms(fromKey);
}
diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json
index 99516df07c..63b2b06f53 100644
--- a/client/src/locales/en/translation.json
+++ b/client/src/locales/en/translation.json
@@ -1116,8 +1116,20 @@
"com_ui_context_estimated": "Estimated",
"com_ui_context_filter_sort": "Filter and Sort by Context",
"com_ui_context_free": "Free space",
+ "com_ui_context_cached": "Cached",
+ "com_ui_context_cache_write": "Cache write",
+ "com_ui_context_dynamic_instructions": "Agent instructions",
+ "com_ui_context_pressure_warn": "Context window is filling up",
+ "com_ui_context_pressure_danger": "Context window is almost full",
+ "com_ui_context_largest_tool": "Largest tool: {{0}} ({{1}})",
+ "com_ui_context_runway": "≈{{0}} more turns at this growth",
+ "com_ui_context_compaction": "Summarizing now could reclaim ≈{{0}} tokens",
+ "com_ui_context_insights": "Context insights",
+ "com_ui_context_tool_breakdown": "By tool",
"com_ui_context_messages": "Messages",
"com_ui_context_subagents": "Subagents",
+ "com_ui_context_subagents_all": "Subagents (all branches)",
+ "com_ui_context_tool_calls": "Tool calls",
"com_ui_context_summary": "Summary",
"com_ui_context_system": "System prompt",
"com_ui_context_tools": "Tool schemas",
diff --git a/client/src/store/usage.ts b/client/src/store/usage.ts
index 15eeaffd89..157c9cb82a 100644
--- a/client/src/store/usage.ts
+++ b/client/src/store/usage.ts
@@ -86,6 +86,30 @@ export const totalUsageFamily = atomFamily((_conversationId: string) =>
/** Throttled in-flight output token estimate for the current model call */
export const liveTokensFamily = atomFamily((_conversationId: string) => atom<number>(0));
+/**
+ * Subagent model calls COMMITTED to the conversation, accumulated from
+ * `usage_type: 'subagent'` events once their run settles. Deliberately excluded
+ * from branch/total provider usage (they bill separately and would double-count
+ * a turn), so they surface as their own Totals row. Session-scoped: not
+ * persisted, cleared on convo switch.
+ */
+export const subagentUsageFamily = atomFamily((_conversationId: string) =>
+ atom<BranchUsage>(EMPTY_USAGE),
+);
+
+/**
+ * The in-flight run's subagent share, held beside `pendingUsageFamily` and
+ * settled with it: committed into `subagentUsageFamily` when the response is
+ * finalized or a stop is attributed, discarded when the run ends with no
+ * salvageable response. Committing on arrival instead would leave a failed
+ * run's subagent tokens in the Totals after its usage was discarded from every
+ * rollup they are a subset of, and would count them twice when a resume
+ * re-folds the same events.
+ */
+export const pendingSubagentUsageFamily = atomFamily((_conversationId: string) =>
+ atom<BranchUsage>(EMPTY_USAGE),
+);
+
/** Last known provider-vs-estimate calibration ratio for the conversation */
export const calibrationFamily = atomFamily((_conversationId: string) => atom<number>(1));
@@ -180,6 +204,8 @@ export function removeUsageAtoms(conversationId: string): void {
pendingUsageFamily.remove(conversationId);
totalUsageFamily.remove(conversationId);
liveTokensFamily.remove(conversationId);
+ subagentUsageFamily.remove(conversationId);
+ pendingSubagentUsageFamily.remove(conversationId);
calibrationFamily.remove(conversationId);
foldedUsageKeys.delete(conversationId);
}
diff --git a/client/src/style.css b/client/src/style.css
index 281578894b..0acb2f2e59 100644
--- a/client/src/style.css
+++ b/client/src/style.css
@@ -229,6 +229,7 @@ html {
--series-5: 216 90 142;
--series-6: 126 35 205;
--series-7: 1 131 1;
+ --series-8: 63 81 181;
/* Code syntax highlighting */
--syntax-text: var(--gray-800);
@@ -347,6 +348,7 @@ html {
--series-5: 213 82 130;
--series-6: 171 104 254;
--series-7: 80 167 49;
+ --series-8: 120 130 190;
/* Code syntax highlighting. Comment and meta are the flattened equivalents of
the 50% and 60% alpha whites this palette used before it was tokenized. */
diff --git a/client/src/utils/tokens.spec.ts b/client/src/utils/tokens.spec.ts
index ed4c865a4a..6f5dcef76d 100644
--- a/client/src/utils/tokens.spec.ts
+++ b/client/src/utils/tokens.spec.ts
@@ -11,9 +11,12 @@ import {
setEntryUsage,
sumTotalUsage,
prunedBranchTokens,
+ collectAnchorSeries,
+ latestExchangeTokens,
findBranchSnapshotAnchor,
estimateTokens,
normalizeUsageUnits,
+ formatTokens,
formatCost,
groupToolTokens,
countTrailingOutputChars,
@@ -219,6 +222,69 @@ describe('token index', () => {
expect(totals.tailEstTokens).toBe(5);
});
+ it('splits the tool-call share out of counted and count-less messages', () => {
+ buildIndex(CONVO, [
+ /** Counted assistant turn: text 80 + tool payload (3+2+38=43 chars).
+ * Tool share 43/4 = 11, clamped to the entry's 30-token count → 11. */
+ {
+ messageId: 'a1',
+ parentMessageId: Constants.NO_PARENT,
+ isCreatedByUser: false,
+ conversationId: CONVO,
+ tokenCount: 30,
+ content: [
+ { type: 'text', text: 't'.repeat(80) },
+ { type: 'tool_call', tool_call: { name: 'run', args: 'aa', output: 'o'.repeat(38) } },
+ ],
+ } as unknown as TMessage,
+ /** Counted user turn with no tool parts: contributes nothing. */
+ msg('u1', 'a1', true, 12),
+ /** Count-less assistant turn: tool chars 3+2+7=12 → 3 (≤ its est 8). */
+ {
+ messageId: 'a2',
+ parentMessageId: 'u1',
+ isCreatedByUser: false,
+ conversationId: CONVO,
+ text: 'z'.repeat(20),
+ content: [
+ { type: 'tool_call', tool_call: { name: 'sub', args: 'aa', output: 'o'.repeat(7) } },
+ ],
+ } as unknown as TMessage,
+ ]);
+
+ const totals = sumBranch(CONVO, 'a2');
+ expect(totals.estToolTokens).toBe(14);
+ /** a2 is the tail */
+ expect(totals.tailEstToolTokens).toBe(3);
+ });
+
+ it('keeps a counted tail out of both tail estimates', () => {
+ /** A resumed partial response that already carries a `tokenCount` stays in
+ * `output`, so the estimate path may drop neither its estimate nor its tool
+ * share — dropping the share alone left the message total holding tokens
+ * whose tool traffic had been removed from the split. */
+ buildIndex(CONVO, [
+ msg('u1', Constants.NO_PARENT, true, 12),
+ {
+ messageId: 'a1',
+ parentMessageId: 'u1',
+ isCreatedByUser: false,
+ conversationId: CONVO,
+ tokenCount: 40,
+ content: [
+ { type: 'text', text: 't'.repeat(60) },
+ { type: 'tool_call', tool_call: { name: 'run', args: 'aa', output: 'o'.repeat(38) } },
+ ],
+ } as unknown as TMessage,
+ ]);
+
+ const totals = sumBranch(CONVO, 'a1');
+ expect(totals.output).toBe(40);
+ expect(totals.estToolTokens).toBe(11);
+ expect(totals.tailEstTokens).toBe(0);
+ expect(totals.tailEstToolTokens).toBe(0);
+ });
+
describe('prunedBranchTokens (over-window mirror of getMessagesWithinTokenLimit)', () => {
/** u1 ← a1(huge, old) ← u2 ← a2(tail). */
const buildChain = () =>
@@ -232,18 +298,47 @@ describe('token index', () => {
it('keeps the newest messages that fit and stops at the first overflow', () => {
buildChain();
/** Budget 8: a2(2)+u2(2)=4 fit; a1(10) would overflow → pruned. */
- expect(prunedBranchTokens(CONVO, 'a2', 8, false)).toBe(4);
+ expect(prunedBranchTokens(CONVO, 'a2', 8, false)).toEqual({ tokens: 4, toolTokens: 0 });
});
it('returns the full branch sum when it fits the budget', () => {
buildChain();
- expect(prunedBranchTokens(CONVO, 'a2', 100, false)).toBe(16);
+ expect(prunedBranchTokens(CONVO, 'a2', 100, false)).toEqual({
+ tokens: 16,
+ toolTokens: 0,
+ });
});
it('skips the in-flight tail when excludeTail is set', () => {
buildChain();
/** Skip a2; a1(10)+u2(2)+u1(2)=14 all fit under 100. */
- expect(prunedBranchTokens(CONVO, 'a2', 100, true)).toBe(14);
+ expect(prunedBranchTokens(CONVO, 'a2', 100, true)).toEqual({
+ tokens: 14,
+ toolTokens: 0,
+ });
+ });
+
+ it('returns the tool-call share of the kept messages', () => {
+ /** u1(counted, 4) ← a2(tail): content-only estimate 11/4 = 3, tool chars
+ * 3+2+6=11 → 3. Kept total 7, tool share 3. */
+ buildIndex(CONVO, [
+ msg('u1', Constants.NO_PARENT, true, 4),
+ {
+ messageId: 'a2',
+ parentMessageId: 'u1',
+ isCreatedByUser: false,
+ conversationId: CONVO,
+ text: 'z'.repeat(4),
+ content: [
+ { type: 'tool_call', tool_call: { name: 'sub', args: 'aa', output: 'o'.repeat(6) } },
+ ],
+ } as unknown as TMessage,
+ ]);
+
+ expect(prunedBranchTokens(CONVO, 'a2', 100, false)).toEqual({
+ tokens: 7,
+ toolTokens: 3,
+ });
});
});
@@ -438,6 +533,12 @@ describe('estimateTokens', () => {
expect(estimateTokens(0)).toBe(0);
expect(estimateTokens(100, 0)).toBe(25);
});
+
+ it('renders malformed token counts as a bounded zero', () => {
+ expect(formatTokens(Number.NaN)).toBe('0');
+ expect(formatTokens(Number.POSITIVE_INFINITY)).toBe('0');
+ expect(formatTokens(-10)).toBe('0');
+ });
});
describe('normalizeUsageUnits', () => {
@@ -615,6 +716,19 @@ describe('groupToolTokens', () => {
expect(groupToolTokens(undefined)).toBe(EMPTY_TOOL_GROUPS);
expect(groupToolTokens({ execute_code: 0 })).toEqual(EMPTY_TOOL_GROUPS);
});
+
+ it('handles prototype-sensitive names and malformed tool counts safely', () => {
+ const counts = Object.fromEntries([
+ ['__proto__', 7],
+ ['constructor', 5],
+ ['web_search', Number.NaN],
+ ]);
+
+ expect(groupToolTokens(counts)).toEqual({
+ ...EMPTY_TOOL_GROUPS,
+ system: 12,
+ });
+ });
});
describe('countTrailingOutputChars', () => {
@@ -702,6 +816,28 @@ describe('per-message usage index (branch + total)', () => {
expect(usage.input).toBe(100);
});
+ it('ignores malformed persisted usage values instead of poisoning totals', () => {
+ buildIndex(CONVO, [
+ msg('u1', Constants.NO_PARENT, true, 10),
+ responseMsg('a1', 'u1', 50, {
+ input: Number.NaN,
+ output: Number.POSITIVE_INFINITY,
+ cacheWrite: -2,
+ cacheRead: 4.8,
+ cost: Number.NaN,
+ }),
+ ]);
+
+ expect(sumBranch(CONVO, 'a1').usage).toEqual({
+ input: 0,
+ output: 0,
+ cacheWrite: 0,
+ cacheRead: 4,
+ cost: 0,
+ costKnown: false,
+ });
+ });
+
it('messages without metadata.usage contribute zero (backward compat)', () => {
buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10), msg('a1', 'u1', false, 50)]);
expect(sumBranch(CONVO, 'a1').usage).toEqual(EMPTY_USAGE);
@@ -835,4 +971,119 @@ describe('per-message usage index (branch + total)', () => {
expect(sumBranch('missing-convo', 'x')).toBe(EMPTY_BRANCH);
expect(EMPTY_BRANCH.usage).toEqual(EMPTY_USAGE);
});
+
+ it('collectAnchorSeries reads used tokens per anchor, oldest → newest', () => {
+ buildIndex(CONVO, [
+ msg('u1', Constants.NO_PARENT, true, 4),
+ msg('a1', 'u1', false, 10),
+ msg('u2', 'a1', true, 4),
+ msg('a2', 'u2', false, 20),
+ msg('u3', 'a2', true, 4),
+ msg('a3', 'u3', false, 30),
+ ]);
+ const snap = (remaining: number) => ({
+ contextBudget: 1000,
+ remainingContextTokens: remaining,
+ breakdown: { maxContextTokens: 1000 },
+ });
+ const anchors = new Map([
+ ['a1', snap(960)],
+ ['a2', snap(920)],
+ ['a3', snap(860)],
+ ]);
+
+ const series = collectAnchorSeries(CONVO, 'a3', anchors);
+ /** used = budget − remaining: 40 → 80 → 140, oldest first */
+ expect(series).toEqual([
+ { used: 40, basis: 'remaining' },
+ { used: 80, basis: 'remaining' },
+ { used: 140, basis: 'remaining' },
+ ]);
+ expect(collectAnchorSeries(CONVO, 'a3', new Map())).toEqual([]);
+ });
+
+ it('collectAnchorSeries derives a snapshot saved without remaining headroom', () => {
+ buildIndex(CONVO, [
+ msg('u1', Constants.NO_PARENT, true, 4),
+ msg('a1', 'u1', false, 10),
+ msg('u2', 'a1', true, 4),
+ msg('a2', 'u2', false, 20),
+ ]);
+ const anchors = new Map<string, unknown>([
+ /** The older shape: a budget and a breakdown, no remaining count. Read as
+ * zero remaining it would claim the whole 1000-token window was spent. */
+ [
+ 'a1',
+ {
+ contextBudget: 1000,
+ breakdown: { maxContextTokens: 1000, instructionTokens: 100, messageTokens: 60 },
+ },
+ ],
+ /** Nothing to read at all — skipped rather than counted as a full window. */
+ ['a2', { contextBudget: 1000, breakdown: { maxContextTokens: 1000 } }],
+ ]);
+
+ expect(collectAnchorSeries(CONVO, 'a2', anchors)).toEqual([{ used: 160, basis: 'breakdown' }]);
+ });
+
+ it('latestExchangeTokens sums the tail response and its user turn', () => {
+ buildIndex(CONVO, [
+ msg('u1', Constants.NO_PARENT, true, 12),
+ msg('a1', 'u1', false, 40),
+ msg('u2', 'a1', true, 9),
+ msg('a2', 'u2', false, 50),
+ ]);
+
+ expect(latestExchangeTokens(CONVO, 'a2', false)).toBe(59);
+ /** In-flight tail rides liveTokens — only the user turn remains */
+ expect(latestExchangeTokens(CONVO, 'a2', true)).toBe(9);
+ });
+
+ it('keeps tool results outside model completion counts in the latest exchange', () => {
+ const response = {
+ messageId: 'a1',
+ parentMessageId: 'u1',
+ conversationId: CONVO,
+ isCreatedByUser: false,
+ tokenCount: 40,
+ content: [
+ {
+ type: 'tool_call',
+ tool_call: {
+ name: 'read_file',
+ args: 'a'.repeat(80),
+ output: 'r'.repeat(2000),
+ },
+ },
+ ],
+ } as TMessage;
+ buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10), response]);
+ expect(latestExchangeTokens(CONVO, 'a1', false)).toBe(550);
+ expect(latestExchangeTokens(CONVO, 'a1', true)).toBe(10);
+ buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10), { ...response, tokenCount: 0 }]);
+ expect(latestExchangeTokens(CONVO, 'a1', false)).toBe(532);
+ });
+
+ it('latestExchangeTokens drops a summarizing turn’s summary completion', () => {
+ /** The backend folds the summarization pass into the response's
+ * `tokenCount`, while the snapshot holds those tokens in `summaryTokens`
+ * instead of `messageTokens`. Subtracting the whole tail would remove a
+ * summary the message total never carried. */
+ buildIndex(CONVO, [
+ msg('u1', Constants.NO_PARENT, true, 9),
+ {
+ messageId: 'a1',
+ parentMessageId: 'u1',
+ isCreatedByUser: false,
+ conversationId: CONVO,
+ tokenCount: 500,
+ text: 'answer',
+ metadata: { summaryUsedTokens: 4000 },
+ } as unknown as TMessage,
+ ]);
+
+ expect(latestExchangeTokens(CONVO, 'a1', false, 300)).toBe(209);
+ /** A turn that did not summarize keeps its whole response. */
+ expect(latestExchangeTokens(CONVO, 'a1', false)).toBe(509);
+ });
});
diff --git a/client/src/utils/tokens.ts b/client/src/utils/tokens.ts
index 8ee65cc3dc..c7205e15d1 100644
--- a/client/src/utils/tokens.ts
+++ b/client/src/utils/tokens.ts
@@ -1,5 +1,11 @@
import { Tools, Constants, inputTokensIncludesCache } from 'librechat-data-provider';
-import type { TMessage, TResponseUsage, TTokenUsageEvent } from 'librechat-data-provider';
+import type {
+ TMessage,
+ TResponseUsage,
+ TTokenUsageEvent,
+ TContextUsageEvent,
+ TTokenBudgetBreakdown,
+} from 'librechat-data-provider';
/** Provider-reported usage of one response, in display units (post-normalize). */
export interface BranchUsage {
@@ -24,6 +30,17 @@ export const EMPTY_USAGE: BranchUsage = {
cost: 0,
costKnown: true,
};
+/** Token counts come from persisted/provider payloads. Keep malformed values
+ * out of every aggregate so one bad event cannot turn the meter into NaN. */
+export function normalizeTokenCount(value: unknown): number {
+ return typeof value === 'number' && Number.isFinite(value) && value > 0
+ ? Math.min(Math.floor(value), Number.MAX_SAFE_INTEGER)
+ : 0;
+}
+
+function hasKnownCost(value: unknown): value is number {
+ return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
export interface TokenEntry {
tokenCount: number;
@@ -32,6 +49,12 @@ export interface TokenEntry {
* text+quotes, since the send path ignores their stored count). Includes
* tool-call name/args/output. Mutually exclusive with a counted `tokenCount`. */
estTokens: number;
+ /** Char/4 estimate of the tool-call share of the body (tool_call parts'
+ * name/args/output), for the estimate path's "Tool calls" split. Raw — sum
+ * sites clamp it to the entry's actual contribution. */
+ estToolTokens: number;
+ /** Tool results are outside a counted response’s model-completion total. */
+ estToolResultTokens: number;
isCreatedByUser: boolean;
parentMessageId: string | null;
/** Per-response provider usage from `metadata.usage` (response messages only) */
@@ -54,10 +77,18 @@ export interface BranchTotals {
/** Uncalibrated estimate sum for count-less branch messages (imports /
* pre-feature). Kept separate so known counts aren't re-estimated. */
estTokens: number;
- /** The tail (latest) message's own `estTokens`. When a stream is live the tail
- * is the in-flight response, already covered by `liveTokens`, so the estimate
- * path excludes this to avoid double-counting a resumed/partial response. */
+ /** The tail (latest) message's UNCOUNTED estimate — its own `estTokens` when
+ * it has no `tokenCount`, else 0. A live tail rides on `liveTokens`, so the
+ * estimate path drops this; a resumed partial that already carries a count
+ * stays in `output`, so nothing may be dropped for it. */
tailEstTokens: number;
+ /** Tool-call share of the branch estimate (`estToolTokens`, clamped per
+ * message to its contribution) — the estimate path's "Tool calls" split. */
+ estToolTokens: number;
+ /** The tail's clamped tool share on the same basis as `tailEstTokens`: 0 for a
+ * counted tail, so the split never drops tool traffic whose tokens the
+ * message total keeps. */
+ tailEstToolTokens: number;
tailId: string | null;
/** Whether the latest run's anchor message is on this branch */
containsAnchor: boolean;
@@ -77,6 +108,8 @@ export const EMPTY_BRANCH: BranchTotals = {
total: 0,
estTokens: 0,
tailEstTokens: 0,
+ estToolTokens: 0,
+ tailEstToolTokens: 0,
tailId: null,
containsAnchor: false,
usage: EMPTY_USAGE,
@@ -112,13 +145,14 @@ function readPersistedUsage(message: Partial<TMessage>): BranchUsage | undefined
}
const persisted = usage as TResponseUsage;
return {
- input: persisted.input ?? 0,
- output: persisted.output ?? 0,
- cacheWrite: persisted.cacheWrite ?? 0,
- cacheRead: persisted.cacheRead ?? 0,
- cost: persisted.cost ?? 0,
- /** Cost is omitted when saved with `contextCost` off — don't render $0.00 */
- costKnown: typeof persisted.cost === 'number',
+ input: normalizeTokenCount(persisted.input),
+ output: normalizeTokenCount(persisted.output),
+ cacheWrite: normalizeTokenCount(persisted.cacheWrite),
+ cacheRead: normalizeTokenCount(persisted.cacheRead),
+ cost: hasKnownCost(persisted.cost) ? persisted.cost : 0,
+ /** Cost is omitted (or malformed) when saved with `contextCost` off — don't
+ * render a misleading $0.00. */
+ costKnown: hasKnownCost(persisted.cost),
};
}
@@ -152,8 +186,8 @@ function addUsage(target: BranchUsage, usage?: BranchUsage): void {
}
/** Chars of a content part's text, handling both the string and `{ value }` forms.
- * Reasoning (`think`) and error parts are excluded — the send path strips them
- * before counting, so they aren't part of the next call's context. */
+ * Reasoning (`think`) and error parts are excluded — the send path strips them
+ * before counting, so they aren't part of the next call's context. */
function partTextChars(part: unknown): number {
if (part == null || typeof part !== 'object') {
return 0;
@@ -172,7 +206,10 @@ function partTextChars(part: unknown): number {
if (typeof call.args === 'string') {
chars += call.args.length;
} else if (call.args != null) {
- chars += JSON.stringify(call.args).length;
+ const serialized = JSON.stringify(call.args);
+ if (typeof serialized === 'string') {
+ chars += serialized.length;
+ }
}
if (typeof call.output === 'string') {
chars += call.output.length;
@@ -193,6 +230,46 @@ function partTextChars(part: unknown): number {
return 0;
}
+/** Char length of a message's tool-call payload — tool_call parts' name, args
+ * and output — the estimate path's split of message body into conversation vs
+ * tool-call usage. Zero for plain-text bodies. */
+function messageToolChars(message: Partial<TMessage>): { chars: number; resultChars: number } {
+ if (!Array.isArray(message.content)) {
+ return { chars: 0, resultChars: 0 };
+ }
+ let chars = 0;
+ let resultChars = 0;
+ for (const part of message.content) {
+ if (part == null || typeof part !== 'object') {
+ continue;
+ }
+ if ('type' in part && part.type === 'tool_call' && 'tool_call' in part) {
+ const call = part.tool_call;
+ if (call == null || typeof call !== 'object') {
+ continue;
+ }
+ if ('name' in call && typeof call.name === 'string') {
+ chars += call.name.length;
+ }
+ if ('args' in call) {
+ if (typeof call.args === 'string') {
+ chars += call.args.length;
+ } else {
+ const serialized = JSON.stringify(call.args ?? null);
+ if (typeof serialized === 'string') {
+ chars += serialized.length;
+ }
+ }
+ }
+ if ('output' in call && typeof call.output === 'string') {
+ chars += call.output.length;
+ resultChars += call.output.length;
+ }
+ }
+ }
+ return { chars, resultChars };
+}
+
/** Char length of a message's rendered text, for estimating count-less messages.
* Prefer structured `content` when present — the send path formats from it (incl.
* tool calls), so a message carrying both `text` and `content` (e.g. a stopped
@@ -226,8 +303,8 @@ function quoteChars(message: Partial<TMessage>): number {
}
function toEntry(message: Partial<TMessage>): TokenEntry {
- const summaryUsedTokens = message.metadata?.summaryUsedTokens;
- const tokenCount = typeof message.tokenCount === 'number' ? message.tokenCount : 0;
+ const summaryUsedTokens = normalizeTokenCount(message.metadata?.summaryUsedTokens);
+ const tokenCount = normalizeTokenCount(message.tokenCount);
const isCreatedByUser = message.isCreatedByUser === true;
const quoted = isCreatedByUser && Array.isArray(message.quotes) && message.quotes.length > 0;
/** A quoted user turn's stored `tokenCount` is unreliable: a text-only Save edit
@@ -242,16 +319,16 @@ function toEntry(message: Partial<TMessage>): TokenEntry {
} else if (tokenCount === 0) {
estTokens = Math.round(messageChars(message) / 4);
}
+ const toolChars = messageToolChars(message);
return {
tokenCount: quoted ? 0 : tokenCount,
estTokens,
+ estToolTokens: Math.round(toolChars.chars / 4),
+ estToolResultTokens: Math.round(toolChars.resultChars / 4),
isCreatedByUser,
parentMessageId: message.parentMessageId ?? null,
usage: readPersistedUsage(message),
- summaryUsedTokens:
- typeof summaryUsedTokens === 'number' && summaryUsedTokens > 0
- ? summaryUsedTokens
- : undefined,
+ summaryUsedTokens: summaryUsedTokens > 0 ? summaryUsedTokens : undefined,
};
}
@@ -335,12 +412,30 @@ export function sumBranch(
return EMPTY_BRANCH;
}
- const totals = { input: 0, output: 0, counted: 0, total: 0, estTokens: 0, containsAnchor: false };
- /** The in-flight response, when streaming, is the branch tail and is covered by
- * `liveTokens`; expose its estimate so the estimate path can drop it. */
- const tailEstTokens = index.get(tailId)?.estTokens ?? 0;
- const usage: BranchUsage = { ...EMPTY_USAGE };
+ const totals = {
+ input: 0,
+ output: 0,
+ counted: 0,
+ total: 0,
+ estTokens: 0,
+ estToolTokens: 0,
+ containsAnchor: false,
+ };
+ /** The in-flight response, when streaming, is the branch tail and is covered
+ * by `liveTokens`; expose its estimate so the estimate path can drop it. A
+ * tail that already carries a `tokenCount` (a resumed partial response) is
+ * counted in `input`/`output` instead, and its tool share is inside
+ * `estToolTokens` clamped to that count — dropping either would leave the
+ * message total holding tokens whose tool share had been removed, so both
+ * tail figures are zero for a counted tail. */
+ const tailEntry = index.get(tailId);
+ const tailCounted = tailEntry != null && tailEntry.tokenCount > 0;
+ const tailEstTokens = tailCounted ? 0 : (tailEntry?.estTokens ?? 0);
+ const tailEstToolTokens = tailCounted
+ ? 0
+ : Math.min(tailEntry?.estToolTokens ?? 0, tailEntry?.estTokens ?? 0);
let summaryBaseline = 0;
+ const usage: BranchUsage = { ...EMPTY_USAGE };
/** Once a summary marker is crossed, older turns are out of the CONTEXT WINDOW
* (subsumed by the baseline) — but their provider spend still happened, so the
* usage/cost walk continues to the root while context counting stops. */
@@ -372,6 +467,12 @@ export function sumBranch(
} else if (!contextCapped && entry.estTokens > 0) {
totals.estTokens += entry.estTokens;
}
+ /** Tool-call share of this entry's contribution — a subset of the
+ * input/output/estimated rows, so it never adds to the gauge. */
+ if (!contextCapped) {
+ const contribution = entry.tokenCount > 0 ? entry.tokenCount : entry.estTokens;
+ totals.estToolTokens += Math.min(entry.estToolTokens, contribution);
+ }
/** Cost/usage is cumulative spend — never truncated at the summary boundary. */
addUsage(usage, entry.usage);
/** This response's turn compacted the history: its own output is counted
@@ -384,7 +485,7 @@ export function sumBranch(
currentId = entry.parentMessageId;
}
- return { ...totals, tailEstTokens, tailId, usage, summaryBaseline };
+ return { ...totals, tailEstTokens, tailEstToolTokens, tailId, usage, summaryBaseline };
}
/**
@@ -398,20 +499,22 @@ export function sumBranch(
* `budget` is the message window (max minus the always-sent summary baseline);
* when `excludeTail`, the in-flight tail response is skipped (it rides on
* `liveTokens`). Per-message contribution matches `sumBranch`: stored `tokenCount`
- * when counted, else the char-based `estTokens`.
+ * when counted, else the char-based `estTokens`. Returns the kept total plus the
+ * tool-call share of what was kept, so the estimate can split the Messages row.
*/
export function prunedBranchTokens(
conversationId: string,
tailId: string | null | undefined,
budget: number,
excludeTail: boolean,
-): number {
+): { tokens: number; toolTokens: number } {
const index = registry.get(conversationId);
if (!index || !tailId || budget <= 0) {
- return 0;
+ return { tokens: 0, toolTokens: 0 };
}
let total = 0;
+ let toolTotal = 0;
let currentId: string | null = tailId;
let guard = index.size;
let isTail = true;
@@ -429,6 +532,7 @@ export function prunedBranchTokens(
break;
}
total += contribution;
+ toolTotal += Math.min(entry.estToolTokens, contribution);
}
/** Pre-summary turns are subsumed by the baseline the caller already reserved,
* so stop after counting the summarizing turn — mirrors `sumBranch`. */
@@ -437,7 +541,182 @@ export function prunedBranchTokens(
}
currentId = entry.parentMessageId;
}
- return total;
+ return { tokens: total, toolTokens: toolTotal };
+}
+
+/**
+ * One persisted snapshot's used-context reading, with the basis it was measured
+ * on. `remaining` is the authoritative pre-invoke figure (`budget − remaining`);
+ * `breakdown` is the instruction+messages sum a snapshot saved before
+ * `remainingContextTokens` existed still supports. The two measure different
+ * quantities (the backend's remaining covers content the breakdown does not),
+ * so a growth delta may only compare readings of the same basis.
+ */
+export interface AnchorReading {
+ used: number;
+ basis: 'remaining' | 'breakdown';
+ configuration?: string;
+}
+
+/** Compare the measured call configuration, including fixed prompt overhead.
+ * Older snapshots without call identity cannot establish comparability. */
+export function snapshotConfiguration(
+ snapshot: Pick<TContextUsageEvent, 'model' | 'provider' | 'agentId' | 'contextBudget'> & {
+ breakdown?: Partial<TTokenBudgetBreakdown>;
+ },
+): string | undefined {
+ if (!snapshot.model || !snapshot.provider) {
+ return undefined;
+ }
+ return JSON.stringify([
+ snapshot.model,
+ snapshot.provider,
+ snapshot.agentId,
+ snapshot.contextBudget ?? snapshot.breakdown?.maxContextTokens,
+ snapshot.breakdown?.instructionTokens,
+ snapshot.breakdown?.toolSchemaTokens,
+ ]);
+}
+
+/**
+ * Used-token readings for every persisted snapshot on the viewed branch, oldest
+ * → newest (the walk is tail→root, so results are reversed). Drives the growth
+ * sparkline and the runway projection in the breakdown. Stops after a summarized
+ * response — older snapshots describe discarded history, mirroring `sumBranch`.
+ * A snapshot that carries neither basis is skipped rather than reported as
+ * having consumed its entire budget.
+ */
+export function collectAnchorSeries(
+ conversationId: string,
+ tailId: string | null | undefined,
+ anchors: ReadonlyMap<string, unknown>,
+): AnchorReading[] {
+ const index = registry.get(conversationId);
+ if (!index || !tailId || anchors.size === 0) {
+ return [];
+ }
+
+ const series: AnchorReading[] = [];
+ let currentId: string | null = tailId;
+ let guard = index.size;
+
+ while (currentId && currentId !== Constants.NO_PARENT && guard-- > 0) {
+ const entry: TokenEntry | undefined = index.get(currentId);
+ if (!entry) {
+ break;
+ }
+ const snapshot = anchors.get(currentId) as
+ | (Partial<Omit<TContextUsageEvent, 'breakdown'>> & {
+ breakdown?: Partial<TTokenBudgetBreakdown>;
+ })
+ | undefined;
+ if (snapshot != null) {
+ const budget = normalizeTokenCount(
+ snapshot.contextBudget ?? snapshot.breakdown?.maxContextTokens,
+ );
+ const configuration = snapshotConfiguration(snapshot);
+ /** Same precedence as the render path's `baseUsed`: the backend's
+ * remaining headroom when it was saved, else the breakdown sum. */
+ if (snapshot.remainingContextTokens != null && budget > 0) {
+ const remaining = normalizeTokenCount(snapshot.remainingContextTokens);
+ series.push({ used: Math.max(0, budget - remaining), basis: 'remaining', configuration });
+ } else {
+ const used =
+ normalizeTokenCount(
+ snapshot.effectiveInstructionTokens ?? snapshot.breakdown?.instructionTokens,
+ ) + normalizeTokenCount(snapshot.breakdown?.messageTokens);
+ if (used > 0) {
+ series.push({ used, basis: 'breakdown', configuration });
+ }
+ }
+ }
+ if (entry.summaryUsedTokens != null && entry.summaryUsedTokens > 0) {
+ break;
+ }
+ currentId = entry.parentMessageId;
+ }
+ return series.reverse();
+}
+
+/**
+ * The branch's largest messages (context contributions), largest first — the
+ * "what is eating my window" list. Same contribution rule as `sumBranch`:
+ * stored `tokenCount` when counted, else the char-based `estTokens`.
+ */
+export function topBranchMessages(
+ conversationId: string,
+ tailId: string | null | undefined,
+ limit = 3,
+): Array<{ role: 'user' | 'assistant'; tokens: number }> {
+ const index = registry.get(conversationId);
+ if (!index || !tailId) {
+ return [];
+ }
+
+ const items: Array<{ role: 'user' | 'assistant'; tokens: number }> = [];
+ let currentId: string | null = tailId;
+ let guard = index.size;
+ let contextCapped = false;
+
+ while (currentId && currentId !== Constants.NO_PARENT && guard-- > 0) {
+ const entry: TokenEntry | undefined = index.get(currentId);
+ if (!entry) {
+ break;
+ }
+ if (!contextCapped) {
+ const contribution = entry.tokenCount > 0 ? entry.tokenCount : entry.estTokens;
+ if (contribution > 0) {
+ items.push({ role: entry.isCreatedByUser ? 'user' : 'assistant', tokens: contribution });
+ }
+ }
+ if (!contextCapped && entry.summaryUsedTokens != null && entry.summaryUsedTokens > 0) {
+ contextCapped = true;
+ }
+ currentId = entry.parentMessageId;
+ }
+ return items.sort((a, b) => b.tokens - a.tokens).slice(0, limit);
+}
+
+/**
+ * Tokens of the most recent exchange (the tail response plus the user turn it
+ * answers) — what a summarization would KEEP. `excludeTail` skips an in-flight
+ * tail (it rides on `liveTokens`), leaving the previous complete exchange.
+ * The compaction preview is context tokens minus this.
+ *
+ * `summaryOutputTokens` removes an internal summarization's completion from a
+ * tail whose turn compacted: the backend folds that pass into the response's
+ * `tokenCount`, while the snapshot keeps it in `breakdown.summaryTokens` rather
+ * than `messageTokens`. Leaving it in would subtract a summary the message
+ * total never carried, understating the reclaim by the size of the summary.
+ */
+export function latestExchangeTokens(
+ conversationId: string,
+ tailId: string | null | undefined,
+ excludeTail: boolean,
+ summaryOutputTokens = 0,
+): number {
+ const index = registry.get(conversationId);
+ if (!index || !tailId) {
+ return 0;
+ }
+ const contribution = (entry: TokenEntry | undefined): number => {
+ if (entry == null) {
+ return 0;
+ }
+ /** Completion counts include call arguments, but tool results are separate.
+ * Count-less content already estimates both. */
+ return entry.tokenCount > 0 ? entry.tokenCount + entry.estToolResultTokens : entry.estTokens;
+ };
+
+ const tailEntry = index.get(tailId);
+ const parentEntry = index.get(tailEntry?.parentMessageId ?? '');
+ let tail = excludeTail ? 0 : contribution(tailEntry);
+ /** Only a turn that actually summarized carries that completion; the marker
+ * persists on the response whose turn compacted. */
+ if (tail > 0 && tailEntry?.summaryUsedTokens != null && tailEntry.summaryUsedTokens > 0) {
+ tail = Math.max(0, tail - normalizeTokenCount(summaryOutputTokens));
+ }
+ return tail + contribution(parentEntry);
}
/**
@@ -465,6 +744,19 @@ export function sumTotalUsage(conversationId: string): BranchUsage {
* that, including a sibling transiently dropped from the cache on regenerate).
*/
export function setEntryUsage(conversationId: string, messageId: string, usage: BranchUsage): void {
+ const costKnown =
+ usage.costKnown === true &&
+ typeof usage.cost === 'number' &&
+ Number.isFinite(usage.cost) &&
+ usage.cost >= 0;
+ const safeUsage: BranchUsage = {
+ input: normalizeTokenCount(usage.input),
+ output: normalizeTokenCount(usage.output),
+ cacheWrite: normalizeTokenCount(usage.cacheWrite),
+ cacheRead: normalizeTokenCount(usage.cacheRead),
+ cost: costKnown ? usage.cost : 0,
+ costKnown,
+ };
/** Remember it durably first so a later rebuild — or a transient cache drop
* during regenerate — can restore it even when the entry isn't present yet. */
let history = usageHistory.get(conversationId);
@@ -472,10 +764,10 @@ export function setEntryUsage(conversationId: string, messageId: string, usage:
history = new Map<string, BranchUsage>();
usageHistory.set(conversationId, history);
}
- history.set(messageId, usage);
+ history.set(messageId, safeUsage);
const entry = registry.get(conversationId)?.get(messageId);
if (entry) {
- entry.usage = usage;
+ entry.usage = safeUsage;
}
}
@@ -550,8 +842,9 @@ export function groupToolTokens(
}
const deferred = new Set(deferredToolNames ?? []);
const groups = { ...EMPTY_TOOL_GROUPS };
- for (const [name, tokens] of Object.entries(toolTokenCounts)) {
- if (tokens <= 0) {
+ for (const [name, rawTokens] of Object.entries(toolTokenCounts)) {
+ const tokens = normalizeTokenCount(rawTokens);
+ if (tokens === 0) {
continue;
}
if (name === Tools.skill) {
@@ -614,11 +907,14 @@ export function countTrailingOutputChars(content?: unknown[] | null): number {
/** Rough live estimate for streaming text, calibrated by the last known provider ratio */
export function estimateTokens(charCount: number, calibrationRatio = 1): number {
- if (charCount <= 0) {
- return 0;
- }
- const ratio = calibrationRatio > 0 ? calibrationRatio : 1;
- return Math.round((charCount / 4) * ratio);
+ const chars = normalizeTokenCount(charCount);
+ const ratio =
+ typeof calibrationRatio === 'number' &&
+ Number.isFinite(calibrationRatio) &&
+ calibrationRatio > 0
+ ? calibrationRatio
+ : 1;
+ return normalizeTokenCount(Math.round((chars / 4) * ratio));
}
/** Billable token quantities of one or more model calls, normalized for pricing */
@@ -633,20 +929,20 @@ export interface CostUnits {
* Normalizes one call's usage into billable units, mirroring the backend's
* authoritative `splitUsage`/`resolveCompletionTokens`
* (packages/api/src/agents/usage.ts):
- * - cache classification is by provider, not magnitude — Anthropic/Bedrock
- * keep cache additive (input is uncached-only); subset providers fold
- * cache into `input_tokens`. Falls back to a magnitude heuristic only when
+ * - cache classification is by provider, not magnitude — Bedrock keeps cache
+ * additive (input is uncached-only); Anthropic and OpenAI fold cache into
+ * `input_tokens`. Falls back to a magnitude heuristic only when
* the provider is unknown.
* - completion is repaired for providers (e.g. Vertex) that under-report
* `output_tokens` but carry the gap in `total_tokens`.
* Applied per event so units stay correct when summed across calls.
*/
export function normalizeUsageUnits(usage: TTokenUsageEvent): CostUnits {
- const rawInput = usage.input_tokens ?? 0;
- const rawOutput = usage.output_tokens ?? 0;
- const total = usage.total_tokens ?? 0;
- const cacheWrite = usage.input_token_details?.cache_creation ?? 0;
- const cacheRead = usage.input_token_details?.cache_read ?? 0;
+ const rawInput = normalizeTokenCount(usage.input_tokens);
+ const rawOutput = normalizeTokenCount(usage.output_tokens);
+ const total = normalizeTokenCount(usage.total_tokens);
+ const cacheWrite = normalizeTokenCount(usage.input_token_details?.cache_creation);
+ const cacheRead = normalizeTokenCount(usage.input_token_details?.cache_read);
const includesCache =
usage.provider != null
@@ -665,11 +961,13 @@ export function normalizeUsageUnits(usage: TTokenUsageEvent): CostUnits {
};
}
+const tokenFormatter = new Intl.NumberFormat(undefined, {
+ notation: 'compact',
+ maximumFractionDigits: 1,
+});
+
export function formatTokens(count: number): string {
- const formatted = new Intl.NumberFormat(undefined, {
- notation: 'compact',
- maximumFractionDigits: 1,
- }).format(count);
+ const formatted = tokenFormatter.format(normalizeTokenCount(count));
return formatted.replace(/\.0(?=[A-Za-z]|$)/, '');
}
@@ -753,7 +1051,7 @@ export function formatCost(usd: number, currency: CurrencyConfig = DEFAULT_CURRE
}
const base = maxFractionDigits(code);
- const amount = usd * rate;
+ const amount = (Number.isFinite(usd) && usd > 0 ? usd : 0) * rate;
/** The currency's own minor unit — USD/EUR→0.01, JPY→1, KWD→0.001. */
const smallest = Math.pow(10, -base);
diff --git a/e2e/specs/mock/scenarios/persisted-context-usage.spec.ts b/e2e/specs/mock/scenarios/persisted-context-usage.spec.ts
new file mode 100644
index 0000000000..9b81a5a9ca
--- /dev/null
+++ b/e2e/specs/mock/scenarios/persisted-context-usage.spec.ts
@@ -0,0 +1,261 @@
+import { randomUUID } from 'crypto';
+import { expect, test } from '@playwright/test';
+import { getE2EUser } from '../../../setup/user';
+import { deleteConversations, deleteMessagesByConversation, withMongo } from '../db';
+
+const NO_PARENT = '00000000-0000-0000-0000-000000000000';
+const userEmail = getE2EUser().email;
+const cleanupConversationIds: string[] = [];
+
+async function insertConversation(
+ conversationId: string,
+ title: string,
+ messages: Record<string, unknown>[],
+): Promise<void> {
+ await withMongo(async (db) => {
+ const user = await db.collection('users').findOne({ email: userEmail });
+ if (!user) {
+ throw new Error(`E2E seed: user "${userEmail}" not found`);
+ }
+
+ const now = new Date();
+ await db.collection('conversations').insertOne({
+ conversationId,
+ title,
+ user: user._id.toString(),
+ endpoint: 'Mock Provider A',
+ model: 'mock-model-a',
+ maxContextTokens: 300,
+ isArchived: false,
+ createdAt: now,
+ updatedAt: now,
+ __v: 0,
+ });
+
+ await db.collection('messages').insertMany(
+ messages.map((message, index) => ({
+ ...message,
+ conversationId,
+ user: user._id.toString(),
+ endpoint: 'Mock Provider A',
+ model: 'mock-model-a',
+ error: false,
+ unfinished: false,
+ isTemporary: false,
+ createdAt: new Date(now.getTime() + index * 1000),
+ updatedAt: new Date(now.getTime() + index * 1000),
+ __v: 0,
+ })),
+ );
+ });
+}
+
+test.afterEach(async () => {
+ const conversationIds = cleanupConversationIds.splice(0);
+ if (conversationIds.length === 0) {
+ return;
+ }
+
+ try {
+ await deleteMessagesByConversation(conversationIds);
+ } finally {
+ await deleteConversations(conversationIds);
+ }
+});
+
+test.describe('persisted context usage', () => {
+ /** A snapshot persisted before `remainingContextTokens` existed carries only a
+ * budget and a breakdown. Reading the absent remaining count as zero scored
+ * such a snapshot as having spent its whole window, so an old conversation
+ * opened to a full meter. The used figure has to come from the breakdown
+ * instead: instructions + messages of the deepest snapshot on the branch. */
+ test('reads used context from a legacy snapshot’s breakdown @scenario:legacy-snapshot-shows-derived-used-context', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ const conversationId = randomUUID();
+ cleanupConversationIds.push(conversationId);
+
+ await insertConversation(conversationId, 'Legacy context runway fixture', [
+ {
+ messageId: 'legacy-user-1',
+ parentMessageId: NO_PARENT,
+ text: 'First legacy prompt',
+ isCreatedByUser: true,
+ sender: 'User',
+ tokenCount: 8,
+ },
+ {
+ messageId: 'legacy-assistant-1',
+ parentMessageId: 'legacy-user-1',
+ text: 'First legacy reply',
+ isCreatedByUser: false,
+ sender: 'Assistant',
+ tokenCount: 4,
+ metadata: {
+ usage: { input: 10, output: 4, cacheRead: 0, cacheWrite: 0 },
+ contextUsage: {
+ runId: 'legacy-run-1',
+ contextBudget: 300,
+ breakdown: {
+ maxContextTokens: 300,
+ instructionTokens: 20,
+ systemMessageTokens: 0,
+ dynamicInstructionTokens: 0,
+ toolSchemaTokens: 0,
+ summaryTokens: 0,
+ toolCount: 0,
+ messageCount: 2,
+ messageTokens: 100,
+ availableForMessages: 280,
+ },
+ },
+ },
+ },
+ {
+ messageId: 'legacy-user-2',
+ parentMessageId: 'legacy-assistant-1',
+ text: 'Second legacy prompt',
+ isCreatedByUser: true,
+ sender: 'User',
+ tokenCount: 8,
+ },
+ {
+ messageId: 'legacy-assistant-2',
+ parentMessageId: 'legacy-user-2',
+ text: 'Second legacy reply',
+ isCreatedByUser: false,
+ sender: 'Assistant',
+ tokenCount: 4,
+ metadata: {
+ usage: { input: 14, output: 5, cacheRead: 0, cacheWrite: 0 },
+ contextUsage: {
+ runId: 'legacy-run-2',
+ contextBudget: 300,
+ breakdown: {
+ maxContextTokens: 300,
+ instructionTokens: 20,
+ systemMessageTokens: 0,
+ dynamicInstructionTokens: 0,
+ toolSchemaTokens: 0,
+ summaryTokens: 0,
+ toolCount: 0,
+ messageCount: 4,
+ messageTokens: 160,
+ availableForMessages: 280,
+ },
+ },
+ },
+ },
+ ]);
+
+ await page.goto(`/c/${conversationId}`, { timeout: 30000 });
+ await expect(page.getByText('Second legacy reply')).toBeVisible({ timeout: 30000 });
+
+ const gauge = page.getByTestId('token-usage');
+ await expect(gauge).toBeVisible({ timeout: 30000 });
+ await gauge.click();
+ const popover = page.getByRole('region', { name: 'Context usage' });
+ await expect(popover).toBeVisible({ timeout: 10000 });
+
+ const breakdownToggle = popover.getByTestId('context-breakdown-toggle');
+ if ((await breakdownToggle.getAttribute('aria-expanded')) === 'false') {
+ await breakdownToggle.click();
+ }
+ await expect(breakdownToggle).toHaveAttribute('aria-expanded', 'true');
+
+ /** 20 instruction + 160 message tokens of the 300-token budget: the deepest
+ * legacy snapshot on the branch, derived from its breakdown. Scoring the
+ * missing remaining count as zero would read 300 / 300 (100%) here. */
+ await expect(breakdownToggle).toContainText('180 / 300 (60%)');
+ await expect(popover.getByRole('progressbar')).toHaveAttribute('aria-valuenow', '60');
+
+ /** The snapshot path renders, so the reading really is the persisted
+ * snapshot and not the client-side estimate, and the untouched remainder
+ * is the budget minus that derived total. */
+ const breakdown = popover.getByTestId('context-breakdown');
+ await expect(breakdown).toBeVisible({ timeout: 10000 });
+ await expect(popover.getByTestId('context-estimate')).toHaveCount(0);
+ const freeSpace = breakdown.locator('div.flex', { hasText: 'Free space' }).first();
+ await expect(freeSpace).toContainText('120');
+ });
+
+ test('nests estimated tool traffic beneath message totals @scenario:estimate-path-nests-the-tool-share', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ const conversationId = randomUUID();
+ cleanupConversationIds.push(conversationId);
+
+ await insertConversation(conversationId, 'Estimated tool share fixture', [
+ {
+ messageId: 'estimate-user-1',
+ parentMessageId: NO_PARENT,
+ text: 'Estimate prompt',
+ isCreatedByUser: true,
+ sender: 'User',
+ tokenCount: 8,
+ },
+ {
+ messageId: 'estimate-assistant-1',
+ parentMessageId: 'estimate-user-1',
+ text: 'Tool result',
+ isCreatedByUser: false,
+ sender: 'Assistant',
+ tokenCount: 20,
+ content: [
+ {
+ type: 'tool_call',
+ tool_call: {
+ id: 'estimate-call-1',
+ name: 'lookup',
+ args: '{"q":"x"}',
+ output: 'result value',
+ },
+ },
+ ],
+ metadata: {
+ usage: { input: 7, output: 5, cacheRead: 0, cacheWrite: 0 },
+ },
+ },
+ ]);
+
+ await page.goto(`/c/${conversationId}`, { timeout: 30000 });
+ await expect(page.getByText('Estimate prompt')).toBeVisible({ timeout: 30000 });
+
+ const gauge = page.getByTestId('token-usage');
+ await expect(gauge).toBeVisible({ timeout: 30000 });
+ await gauge.click();
+ const popover = page.getByRole('region', { name: 'Context usage' });
+ await expect(popover).toBeVisible({ timeout: 10000 });
+
+ const breakdownToggle = popover.getByTestId('context-breakdown-toggle');
+ if ((await breakdownToggle.getAttribute('aria-expanded')) === 'false') {
+ await breakdownToggle.click();
+ }
+ await expect(breakdownToggle).toHaveAttribute('aria-expanded', 'true');
+
+ const estimate = popover.getByTestId('context-estimate');
+ await expect(estimate).toBeVisible({ timeout: 10000 });
+ const toolRow = estimate.locator('div.pl-6').getByText('Tool calls', { exact: true });
+ await expect(toolRow).toBeVisible();
+
+ // Tool traffic is already included in the counted assistant total, so the Tool calls subtotal must be nested rather than a peer that would double-count the meter.
+ const peerRows = estimate.locator(':scope > div.flex');
+ await expect(peerRows).toHaveCount(2);
+ const peerText = await peerRows.allTextContents();
+ expect(peerText.some((text) => text.includes('Tool calls'))).toBe(false);
+
+ // All fixture values stay below 1000, so the compact formatter leaves each peer value parseable and their sum can be compared with the gauge readout.
+ const peerSum = await peerRows.evaluateAll((rows) =>
+ rows.reduce((sum, row) => {
+ const value = row.lastElementChild?.textContent?.match(/\d+/)?.[0];
+ return sum + (value == null ? 0 : Number(value));
+ }, 0),
+ );
+ const readout = await breakdownToggle.textContent();
+ const used = readout?.match(/Context window\s*(\d+)/)?.[1];
+ expect(used).toBeDefined();
+ expect(peerSum).toBe(Number(used));
+ });
+});
diff --git a/e2e/specs/mock/scenarios/series-eight-theme.spec.ts b/e2e/specs/mock/scenarios/series-eight-theme.spec.ts
new file mode 100644
index 0000000000..e0301e0bb8
--- /dev/null
+++ b/e2e/specs/mock/scenarios/series-eight-theme.spec.ts
@@ -0,0 +1,134 @@
+import { expect, test } from '@playwright/test';
+import type { Page } from '@playwright/test';
+import {
+ MOCK_ENDPOINTS,
+ mockReply,
+ NEW_CHAT_PATH,
+ selectMockEndpoint,
+ sendMessage,
+} from '../helpers';
+import { deleteConversations, deleteMessagesByConversation } from '../db';
+
+/**
+ * Pin the stored mode to light in both tests. This keeps the desktop-dark
+ * project's browser colorScheme from selecting a different mode, while the
+ * payload still follows the reference theme's intent: it owns its seven-slot
+ * scale, its surfaces, and its secondary text.
+ */
+const OWNED_SCALE_COLORS = {
+ 'rgb-text-primary': '250 250 250',
+ 'rgb-text-secondary': '215 215 215',
+ 'rgb-surface-secondary': '18 18 24',
+ 'rgb-surface-tertiary': '30 30 38',
+ 'rgb-series-1': '120 200 255',
+ 'rgb-series-2': '255 160 90',
+ 'rgb-series-3': '110 230 210',
+ 'rgb-series-4': '240 200 100',
+ 'rgb-series-5': '250 150 200',
+ 'rgb-series-6': '190 160 255',
+ 'rgb-series-7': '130 220 120',
+} as const;
+
+const OWNED_SCALE_THEME = {
+ version: 1,
+ name: 'e2e-owned-scale',
+ modes: {
+ light: {
+ colors: OWNED_SCALE_COLORS,
+ },
+ },
+} as const;
+
+const NAMED_SCALE_THEME = {
+ ...OWNED_SCALE_THEME,
+ name: 'e2e-named-scale',
+ modes: {
+ light: {
+ colors: {
+ ...OWNED_SCALE_COLORS,
+ 'rgb-series-8': '10 20 30',
+ },
+ },
+ },
+} as const;
+
+async function installTheme(page: Page, theme: unknown) {
+ await page.addInitScript((definition) => {
+ localStorage.setItem('color-theme', 'light');
+ localStorage.setItem('theme-definition', JSON.stringify(definition));
+ localStorage.setItem('theme-source', 'definition');
+ localStorage.removeItem('theme-colors');
+ localStorage.removeItem('theme-name');
+ }, theme);
+}
+
+async function resolvedSeriesEight(page: Page) {
+ return page.evaluate(() =>
+ getComputedStyle(document.documentElement).getPropertyValue('--series-8').trim(),
+ );
+}
+
+test.afterEach(async ({ page }) => {
+ const match = new URL(page.url()).pathname.match(/^\/c\/([^/]+)\/?$/);
+ if (!match || match[1] === 'new') {
+ return;
+ }
+ const conversationId = decodeURIComponent(match[1]);
+ // Remove the real turn so this theme-focused spec does not leak user data
+ // into later projects or reruns.
+ await deleteMessagesByConversation([conversationId]);
+ await deleteConversations([conversationId]);
+});
+
+test.describe('series-eight theme resolution', () => {
+ test('owned theme keeps summary stop visible @scenario:owned-theme-keeps-summary-stop-visible', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ await installTheme(page, OWNED_SCALE_THEME);
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ await expect(page.locator('html')).toHaveAttribute('data-theme', OWNED_SCALE_THEME.name);
+
+ // A real mock turn supplies the live context snapshot that paints the gauge.
+ await selectMockEndpoint(page, MOCK_ENDPOINTS[0]);
+ const response = await sendMessage(page, 'hello');
+ expect(response.ok()).toBeTruthy();
+ await expect(mockReply(page)).toBeVisible({ timeout: 20000 });
+ await expect(page).toHaveURL(/\/c\/(?!new)/, { timeout: 15000 });
+
+ await expect(page.getByTestId('token-usage')).toBeVisible({ timeout: 20000 });
+ await page.getByTestId('token-usage').click();
+ const popover = page.getByRole('region', { name: 'Context usage' });
+ await expect(popover).toBeVisible({ timeout: 10000 });
+ const toggle = popover.getByTestId('context-breakdown-toggle');
+ await expect(toggle).toBeVisible({ timeout: 10000 });
+ if ((await toggle.getAttribute('aria-expanded')) === 'false') {
+ await toggle.click();
+ }
+ await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+ await expect(popover.getByTestId('context-breakdown')).toBeVisible({ timeout: 10000 });
+
+ await expect.poll(() => resolvedSeriesEight(page)).toBe('215 215 215');
+ // The bundled light-theme indigo must not leak into a theme-owned scale.
+ await expect.poll(() => resolvedSeriesEight(page)).not.toBe('63 81 181');
+
+ // The ordinary mock snapshot has summaryTokens === 0, so its slot-8 Summary
+ // legend is absent. The rendered Messages swatch proves the custom scale is
+ // painted in the real popover; the --series-8 assertions above cover its
+ // summary-stop fallback even when no summary segment is present.
+ const messagesSwatch = popover.locator('span.bg-series-1');
+ await expect(messagesSwatch).toHaveCount(1);
+ await expect(messagesSwatch).toHaveCSS('background-color', 'rgb(120, 200, 255)');
+ });
+
+ test('named series eight overrides fallback @scenario:named-series-eight-overrides-fallback', async ({
+ page,
+ }) => {
+ test.setTimeout(120000);
+ await installTheme(page, NAMED_SCALE_THEME);
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ await expect(page.locator('html')).toHaveAttribute('data-theme', NAMED_SCALE_THEME.name);
+
+ await expect.poll(() => resolvedSeriesEight(page)).toBe('10 20 30');
+ });
+});
diff --git a/e2e/specs/mock/scenarios/subagent-context-total.spec.ts b/e2e/specs/mock/scenarios/subagent-context-total.spec.ts
new file mode 100644
index 0000000000..1fab174ecc
--- /dev/null
+++ b/e2e/specs/mock/scenarios/subagent-context-total.spec.ts
@@ -0,0 +1,118 @@
+import { expect, test } from '@playwright/test';
+import type { Page } from '@playwright/test';
+import type { AgentDetail } from '../agents.helpers';
+import { cleanupAgent, openAgentBuilder, uniqueAgentName } from '../agents.helpers';
+import {
+ MOCK_ENDPOINTS,
+ NEW_CHAT_PATH,
+ getAccessToken,
+ requestJson,
+ sendMessageAndWaitForCompletion,
+} from '../helpers';
+
+async function createAgent(
+ page: Page,
+ token: string,
+ name: string,
+ subagents?: AgentDetail['subagents'],
+): Promise<AgentDetail> {
+ return requestJson<AgentDetail>(page, {
+ path: '/api/agents',
+ token,
+ method: 'POST',
+ body: {
+ name,
+ description: 'Playwright verification of subagent context usage totals.',
+ instructions: 'Follow the test request exactly.',
+ provider: MOCK_ENDPOINTS[0].label,
+ model: MOCK_ENDPOINTS[0].model,
+ subagents,
+ },
+ });
+}
+
+async function selectAgent(page: Page, name: string): Promise<void> {
+ const form = await openAgentBuilder(page);
+ await form.getByRole('combobox', { name: 'Agent', exact: true }).click();
+ await page.getByRole('option', { name }).click();
+ await expect(form.getByLabel('Agent name')).toHaveValue(name);
+ await form.getByRole('button', { name: 'Select Agent' }).click();
+}
+
+test.describe('subagent context usage totals', () => {
+ /** Selecting a parent agent needs the Agent Builder side panel, which the
+ * phone layout does not render, so the subagent run cannot be started from a
+ * touch viewport at all. */
+ test.skip(({ isMobile }) => isMobile === true, 'Agent Builder panel is desktop-only');
+
+ test('shows subagent usage across all branches separately from branch totals @scenario:subagents-row-reads-all-branches', async ({
+ page,
+ }) => {
+ test.setTimeout(180000);
+ const label = `context-total-${Date.now()}`;
+ const childName = uniqueAgentName('E2E Child');
+ const parentName = uniqueAgentName('E2E Parent');
+ let childId: string | undefined;
+ let parentId: string | undefined;
+
+ try {
+ await page.goto(NEW_CHAT_PATH);
+ const token = await getAccessToken(page);
+ const child = await createAgent(page, token, childName);
+ childId = child.id;
+ const parent = await createAgent(page, token, parentName, {
+ enabled: true,
+ allowSelf: false,
+ agent_ids: [child.id],
+ });
+ parentId = parent.id;
+
+ await selectAgent(page, parentName);
+ const response = await sendMessageAndWaitForCompletion(
+ page,
+ `E2E_SUBAGENT_RESULT:${child.id}:${label}`,
+ );
+ expect(response.ok()).toBeTruthy();
+
+ const gauge = page.getByTestId('token-usage');
+ await expect(gauge).toBeVisible({ timeout: 30000 });
+ await gauge.click();
+ const popover = page.getByRole('region', { name: 'Context usage' });
+ await expect(popover).toBeVisible({ timeout: 10000 });
+
+ const toggle = popover.getByTestId('context-breakdown-toggle');
+ if ((await toggle.getAttribute('aria-expanded')) === 'false') {
+ await toggle.click();
+ }
+ await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+
+ // A real subagent emits a context snapshot, so this scope comparison is
+ // against the rendered context rows rather than an estimate fallback.
+ const contextRows = popover.getByTestId('context-breakdown');
+ await expect(contextRows).toBeVisible({ timeout: 10000 });
+ await expect(contextRows.getByText('Subagents (all branches)', { exact: true })).toHaveCount(
+ 0,
+ );
+
+ const totals = popover.getByTestId('token-usage-totals');
+ await expect(totals).toBeVisible({ timeout: 10000 });
+ await expect(totals.getByRole('heading', { name: 'Totals' })).toBeVisible();
+ await expect(totals.getByText('Input', { exact: true })).toBeVisible();
+ await expect(totals.getByText('Output', { exact: true })).toBeVisible();
+
+ const subagentRow = totals
+ .locator('div.flex.w-full.items-center.justify-between')
+ .filter({ hasText: 'Subagents (all branches)' });
+ await expect(subagentRow).toHaveCount(1);
+ await expect(
+ subagentRow.locator(':scope > span').nth(1),
+ // The value is compact-formatted when large; a leading non-zero digit
+ // proves the all-branches usage emitted by the child is not zero.
+ ).toHaveText(/^[1-9]\d*(?:\.\d+)?[KMB]?$/);
+ await expect(totals.getByText('Subagents', { exact: true })).toHaveCount(0);
+ } finally {
+ await cleanupAgent(page, parentId);
+ await cleanupAgent(page, childId);
+ }
+ });
+});
diff --git a/e2e/specs/mock/scenarios/tool-context-split.spec.ts b/e2e/specs/mock/scenarios/tool-context-split.spec.ts
new file mode 100644
index 0000000000..6264aceba1
--- /dev/null
+++ b/e2e/specs/mock/scenarios/tool-context-split.spec.ts
@@ -0,0 +1,236 @@
+import { expect, test } from '@playwright/test';
+import type { Locator, Page } from '@playwright/test';
+import {
+ MOCK_ENDPOINTS,
+ NEW_CHAT_PATH,
+ escapeRegExp,
+ messagesView,
+ selectMockEndpoint,
+ sendMessageAndWaitForCompletion,
+} from '../helpers';
+
+const MCP_SERVER_TITLE = 'E2E Memory';
+const TOOL_FINAL_TEXT = 'E2E steer tool reply done';
+
+const uniqueLabel = (prefix: string) =>
+ `${prefix}-${Date.now()}-${Math.floor(Math.random() * 1e4)}`;
+
+const gauge = (page: Page) => page.getByTestId('token-usage');
+const gaugeMeter = (page: Page) => gauge(page).getByRole('meter');
+
+async function expectGaugeAboveZero(page: Page) {
+ await expect(gauge(page)).toBeVisible({ timeout: 20000 });
+ await expect(gaugeMeter(page)).toHaveAttribute('aria-valuenow', /[1-9]/, { timeout: 20000 });
+}
+
+/** Select the ephemeral MCP server whose real remember_fact tool creates the
+ * tool boundary and causes the fake model to take its tool-response path. */
+async function selectEphemeralMCP(page: Page) {
+ await page.getByRole('button', { name: 'MCP Servers', exact: true }).click();
+ const serverItem = page.getByRole('menuitemcheckbox', { name: new RegExp(MCP_SERVER_TITLE) });
+ await expect(serverItem).toBeVisible();
+ await serverItem.click();
+ await expect(serverItem).toHaveAttribute('aria-checked', 'true');
+ await page.keyboard.press('Escape');
+ await expect(page.getByRole('button', { name: new RegExp(MCP_SERVER_TITLE) })).toBeVisible();
+}
+
+/** The popover opens with only the meter visible; its detail is a remembered
+ * disclosure, so this helper is deliberately idempotent across reloads. */
+async function expandBreakdown(popover: Locator) {
+ const toggle = popover.getByTestId('context-breakdown-toggle');
+ await expect(toggle).toBeVisible({ timeout: 10000 });
+ if ((await toggle.getAttribute('aria-expanded')) === 'false') {
+ await toggle.click();
+ }
+ await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+}
+
+/** Opens the click-pinned popover and expands its context detail. Hover is not
+ * used because it is unavailable on the touch project. */
+async function openBreakdown(page: Page) {
+ await expectGaugeAboveZero(page);
+ await gauge(page).click();
+ const popover = page.getByRole('region', { name: 'Context usage' });
+ await expect(popover).toBeVisible({ timeout: 10000 });
+ await expandBreakdown(popover);
+ return popover;
+}
+
+async function runToolTurn(page: Page, prefix: string) {
+ const label = uniqueLabel(prefix);
+ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
+ // The endpoint must be committed before the ephemeral agent is selected.
+ await selectMockEndpoint(page, MOCK_ENDPOINTS[0]);
+ await selectEphemeralMCP(page);
+ const response = await sendMessageAndWaitForCompletion(page, `E2E_STEER_TOOL_REPLY:${label}`, {
+ timeout: 120000,
+ });
+ expect(response.ok()).toBeTruthy();
+ await expect(
+ messagesView(page).getByText(new RegExp(`${TOOL_FINAL_TEXT} ${escapeRegExp(label)}`)),
+ ).toBeVisible({ timeout: 30000 });
+}
+
+function directPeerRows(breakdown: Locator) {
+ return breakdown.locator(':scope > *:not(.pl-6)');
+}
+
+function rowValue(row: Locator) {
+ return row.locator(':scope > span').last();
+}
+
+test.describe('retained tool context split', () => {
+ /** Every test here needs a real tool boundary, and the only affordance that
+ * attaches one to an ephemeral conversation is the composer's MCP Servers
+ * picker, which the phone layout does not render (its narrow composer keeps
+ * the tool pickers behind a sidebar that overlays the input). The split
+ * itself is viewport-independent: it is computed by the hook, and the mobile
+ * project still exercises the same rows through the persisted fixtures in
+ * `persisted-context-usage.spec.ts`. */
+ test.skip(({ isMobile }) => isMobile === true, 'composer MCP picker is desktop-only');
+
+ test('splits retained tool traffic out of the message total @scenario:tool-calls-split-from-messages', async ({
+ page,
+ }) => {
+ test.setTimeout(180000);
+ await runToolTurn(page, 'context-split');
+
+ const popover = await openBreakdown(page);
+ const breakdown = popover.getByTestId('context-breakdown');
+ await expect(breakdown).toBeVisible({ timeout: 10000 });
+ await expect(popover.getByTestId('context-estimate')).toHaveCount(0);
+
+ const peers = directPeerRows(breakdown);
+ const toolRow = peers.filter({ hasText: 'Tool calls' });
+ const messageRow = peers.filter({ hasText: 'Messages' });
+ await expect(toolRow).toHaveCount(1);
+ await expect(messageRow).toHaveCount(1);
+ // Tool calls and Messages are meter peers, not an indented subset row.
+ await expect(toolRow.locator('xpath=ancestor::*[contains(@class, "pl-6")]')).toHaveCount(0);
+ await expect(messageRow.locator('xpath=ancestor::*[contains(@class, "pl-6")]')).toHaveCount(0);
+
+ const toolValue = (await rowValue(toolRow).innerText()).split('(')[0].trim();
+ const messageValue = (await rowValue(messageRow).innerText()).split('(')[0].trim();
+ // The real tool round-trip contributes a non-zero retained share, shown
+ // separately from Messages; values are compact-formatted by the UI.
+ expect(toolValue).not.toBe('0');
+ expect(toolValue).not.toBe(messageValue);
+ await expect(toolRow.locator('span.bg-series-2')).toHaveCount(1);
+ });
+
+ test('discloses per-tool counts with keyboard controls @scenario:per-tool-counts-keyboard-disclosure', async ({
+ page,
+ }) => {
+ test.setTimeout(180000);
+ await runToolTurn(page, 'keyboard-disclosure');
+
+ const popover = await openBreakdown(page);
+ const breakdown = popover.getByTestId('context-breakdown');
+ const toolRow = directPeerRows(breakdown).filter({ hasText: 'Tool calls' });
+ // Selecting the native button directly proves this row is keyboard-operable,
+ // rather than merely looking like a clickable div.
+ const toolButton = breakdown.locator(':scope > button').filter({ hasText: 'Tool calls' });
+ await expect(toolButton).toHaveCount(1);
+ await expect(toolButton).toHaveAttribute('aria-expanded', 'false');
+ await expect(toolRow).toHaveCount(1);
+
+ await toolButton.focus();
+ await expect(toolButton).toBeFocused();
+ await page.keyboard.press('Enter');
+ await expect(toolButton).toHaveAttribute('aria-expanded', 'true');
+ await expect(toolButton).toBeFocused();
+
+ const panelId = await toolButton.getAttribute('aria-controls');
+ expect(panelId).toBeTruthy();
+ const toolPanel = popover.locator(`[id="${panelId}"]`);
+ await expect(toolPanel.getByText('By tool', { exact: true })).toBeVisible();
+ const namedToolRow = toolPanel.locator(':scope > *').filter({ hasText: /remember_fact/ });
+ await expect(namedToolRow).toHaveCount(1);
+ await expect(namedToolRow).toHaveText(/remember_fact[\s\S]*(?:[1-9]\d{0,2}|\d+(?:\.\d+)?K)/);
+
+ await page.keyboard.press('Space');
+ await expect(toolButton).toHaveAttribute('aria-expanded', 'false');
+ await expect(toolButton).toBeFocused();
+ await expect(toolPanel.getByText('By tool', { exact: true })).toHaveCount(0);
+ });
+
+ test('keeps visible context peers within the meter @scenario:context-rows-never-exceed-the-meter', async ({
+ page,
+ }) => {
+ test.setTimeout(180000);
+ await runToolTurn(page, 'meter-bound');
+
+ const popover = await openBreakdown(page);
+ const breakdown = popover.getByTestId('context-breakdown');
+ const meter = popover.getByRole('progressbar');
+ await expect(breakdown).toBeVisible({ timeout: 10000 });
+ const usedPercent = Number(await meter.getAttribute('aria-valuenow'));
+ expect(Number.isFinite(usedPercent)).toBeTruthy();
+ expect(usedPercent).toBeGreaterThan(0);
+
+ const peers = directPeerRows(breakdown);
+ await expect(peers.filter({ hasText: 'Messages' })).toHaveCount(1);
+ await expect(peers.filter({ hasText: 'Tool calls' })).toHaveCount(1);
+
+ const toolButton = breakdown.locator(':scope > button').filter({ hasText: 'Tool calls' });
+ await toolButton.focus();
+ await page.keyboard.press('Enter');
+ await expect(toolButton).toHaveAttribute('aria-expanded', 'true');
+ // Since compact values can be 1.5K, use the UI's subset relation instead
+ // of parsing rounded values: only segment peers may count toward the meter.
+ // Per-tool, cached, and instruction rows are always indented subsets.
+ await expect(peers.filter({ hasText: /remember_fact/ })).toHaveCount(0);
+ await expect(peers.filter({ hasText: 'Agent instructions' })).toHaveCount(0);
+ await expect(peers.filter({ hasText: 'Cached' })).toHaveCount(0);
+ await expect(peers.filter({ hasText: 'Cache write' })).toHaveCount(0);
+ });
+
+ test('rehydrates the tool split after reload @scenario:tool-split-survives-reload', async ({
+ page,
+ }) => {
+ test.setTimeout(180000);
+ await runToolTurn(page, 'reload-split');
+
+ const initialPopover = await openBreakdown(page);
+ const initialBreakdown = initialPopover.getByTestId('context-breakdown');
+ const initialToolRow = directPeerRows(initialBreakdown).filter({ hasText: 'Tool calls' });
+ await expect(initialToolRow).toHaveCount(1);
+ const initialToolButton = initialBreakdown
+ .locator(':scope > button')
+ .filter({ hasText: 'Tool calls' });
+ await initialToolButton.click();
+ const initialPanelId = await initialToolButton.getAttribute('aria-controls');
+ expect(initialPanelId).toBeTruthy();
+ const initialPanel = initialPopover.locator(`[id="${initialPanelId}"]`);
+ const initialNamedTool = initialPanel
+ .locator(':scope > *')
+ .filter({ hasText: /remember_fact/ });
+ await expect(initialNamedTool).toHaveCount(1);
+ const initialToolName = (await initialNamedTool.innerText()).trim().split(/\s+/)[0];
+ expect(initialToolName).toMatch(/remember_fact/);
+
+ await page.reload({ timeout: 15000 });
+ await expectGaugeAboveZero(page);
+ await expect(messagesView(page).getByText(/E2E steer tool reply done/)).toBeVisible({
+ timeout: 20000,
+ });
+ const reloadedPopover = await openBreakdown(page);
+ const reloadedBreakdown = reloadedPopover.getByTestId('context-breakdown');
+ await expect(reloadedBreakdown).toBeVisible({ timeout: 10000 });
+ await expect(reloadedPopover.getByTestId('context-estimate')).toHaveCount(0);
+ const reloadedToolButton = reloadedBreakdown
+ .locator(':scope > button')
+ .filter({ hasText: 'Tool calls' });
+ await expect(reloadedToolButton).toHaveCount(1);
+ await reloadedToolButton.click();
+ const reloadedPanelId = await reloadedToolButton.getAttribute('aria-controls');
+ expect(reloadedPanelId).toBeTruthy();
+ const reloadedPanel = reloadedPopover.locator(`[id="${reloadedPanelId}"]`);
+ await expect(reloadedPanel.getByText('By tool', { exact: true })).toBeVisible();
+ await expect(reloadedPanel.getByText(initialToolName, { exact: true })).toBeVisible();
+ await expect(
+ reloadedPanel.locator(':scope > *').filter({ hasText: /remember_fact/ }),
+ ).toHaveText(/remember_fact[\s\S]*(?:[1-9]\d{0,2}|\d+(?:\.\d+)?K)/);
+ });
+});
diff --git a/packages/api/src/agents/usage.spec.ts b/packages/api/src/agents/usage.spec.ts
index b8b748c61e..d80c882a1b 100644
--- a/packages/api/src/agents/usage.spec.ts
+++ b/packages/api/src/agents/usage.spec.ts
@@ -1935,13 +1935,13 @@ describe('buildPersistedContextUsage', () => {
contextBudget: 7800,
};
- it('trims zero-valued per-tool counts', () => {
+ it('persists positive per-tool schema counts', () => {
const result = buildPersistedContextUsage(baseSnapshot);
expect(result.breakdown.toolTokenCounts).toEqual({ add: 15 });
expect(result.contextBudget).toBe(7800);
});
- it('drops the tool counts object entirely when all are zero', () => {
+ it('omits a schema-count record with no positive counts', () => {
const result = buildPersistedContextUsage({
...baseSnapshot,
breakdown: { ...baseSnapshot.breakdown, toolTokenCounts: { add: 0 } },
@@ -1956,6 +1956,88 @@ describe('buildPersistedContextUsage', () => {
expect(result.breakdown.messageTokens).toBe(500);
});
+ it('passes a non-zero toolMessageTokens split through to the blob', () => {
+ const result = buildPersistedContextUsage({
+ ...baseSnapshot,
+ breakdown: { ...baseSnapshot.breakdown, toolMessageTokens: 220 },
+ });
+ expect(result.breakdown.toolMessageTokens).toBe(220);
+ expect(result.breakdown.messageTokens).toBe(500);
+ });
+
+ it('keeps invocation-inclusive totals separate from per-tool result shares', () => {
+ const result = buildPersistedContextUsage({
+ ...baseSnapshot,
+ breakdown: {
+ ...baseSnapshot.breakdown,
+ toolMessageTokens: 10,
+ toolMessageTokenCounts: { search: 4 },
+ },
+ });
+ expect(result.breakdown.toolMessageTokens).toBe(10);
+ expect(result.breakdown.toolMessageTokenCounts).toEqual({ search: 4 });
+ expect(
+ Object.values(result.breakdown.toolMessageTokenCounts ?? {}).reduce(
+ (total, count) => total + count,
+ 0,
+ ),
+ ).toBeLessThan(result.breakdown.toolMessageTokens ?? 0);
+ });
+
+ it('trims zero-valued result-message entries and clamps their sum', () => {
+ const result = buildPersistedContextUsage({
+ ...baseSnapshot,
+ breakdown: {
+ ...baseSnapshot.breakdown,
+ toolMessageTokens: 2,
+ toolMessageTokenCounts: { grep: 180, read_file: 0 },
+ },
+ });
+ expect(result.breakdown.toolMessageTokenCounts).toEqual({ grep: 2 });
+ expect(
+ Object.values(result.breakdown.toolMessageTokenCounts ?? {}).reduce(
+ (total, count) => total + count,
+ 0,
+ ),
+ ).toBeLessThanOrEqual(result.breakdown.toolMessageTokens ?? 0);
+ });
+
+ it('preserves a known-zero tool-message total', () => {
+ const result = buildPersistedContextUsage({
+ ...baseSnapshot,
+ breakdown: { ...baseSnapshot.breakdown, toolMessageTokens: 0 },
+ });
+ expect(result.breakdown.toolMessageTokens).toBe(0);
+ expect(Object.prototype.hasOwnProperty.call(result.breakdown, 'toolMessageTokens')).toBe(true);
+ });
+ it('safely persists prototype-sensitive names and ignores malformed counts', () => {
+ const counts = JSON.parse('{"__proto__":3,"constructor":3,"invalid":"4"}') as Record<
+ string,
+ number
+ >;
+ const sdkExtension = {
+ nested: { source: 'retained-sdk-field', flags: ['opaque'] },
+ invocation: { estimated: 4, providerOnly: true },
+ };
+ const snapshot = {
+ ...baseSnapshot,
+ breakdown: {
+ ...baseSnapshot.breakdown,
+ toolMessageTokens: 5,
+ toolMessageTokenCounts: counts,
+ sdkExtension,
+ },
+ };
+ const result = buildPersistedContextUsage(snapshot);
+ const persistedCounts = result.breakdown.toolMessageTokenCounts;
+ expect(persistedCounts?.['__proto__']).toBe(3);
+ expect(persistedCounts?.constructor).toBe(2);
+ expect(persistedCounts?.invalid).toBeUndefined();
+ expect(Object.keys(persistedCounts ?? {})).toEqual(['__proto__', 'constructor']);
+ expect(result.breakdown).toMatchObject({ sdkExtension });
+ expect(snapshot.breakdown.toolMessageTokenCounts).toBe(counts);
+ });
+
it('records the final primary call output as completedOutputTokens', () => {
/** The latest snapshot precedes the final call, so its post-snapshot delta
* is that call's output — not the full multi-call response tokenCount. */
@@ -1974,6 +2056,40 @@ describe('buildPersistedContextUsage', () => {
expect(result.completedOutputTokens).toBe(25);
});
+ 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 } },
+ {
+ runId: 'run-1',
+ provider,
+ model: 'primary-model',
+ input_tokens: 200,
+ output_tokens: 25,
+ input_token_details: { cache_read: 80, cache_creation: 40 },
+ },
+ { runId: 'run-2', input_tokens: 900, input_token_details: { cache_read: 900 } },
+ { usage_type: 'summarization', input_tokens: 500, input_token_details: { cache_read: 500 } },
+ { usage_type: 'subagent', input_tokens: 600, input_token_details: { cache_read: 600 } },
+ ];
+ const result = buildPersistedContextUsage(baseSnapshot, events);
+ expect(result).toMatchObject({
+ cacheRead: 80,
+ cacheWrite: 40,
+ model: 'primary-model',
+ provider,
+ completedOutputTokens: 25,
+ });
+ });
+
+ it('replaces an earlier cache split with a final uncached call', () => {
+ const result = buildPersistedContextUsage({ ...baseSnapshot, cacheRead: 80, cacheWrite: 40 }, [
+ { input_tokens: 200, output_tokens: 25 },
+ ]);
+ expect(result).toMatchObject({ cacheRead: 0, cacheWrite: 0 });
+ expect(buildPersistedContextUsage(baseSnapshot).cacheRead).toBeUndefined();
+ expect(buildPersistedContextUsage(baseSnapshot).model).toBeUndefined();
+ });
+
it('omits completedOutputTokens when there are no primary calls', () => {
expect(buildPersistedContextUsage(baseSnapshot, []).completedOutputTokens).toBeUndefined();
});
diff --git a/packages/api/src/agents/usage.ts b/packages/api/src/agents/usage.ts
index c1c6ac4111..d0614361c8 100644
--- a/packages/api/src/agents/usage.ts
+++ b/packages/api/src/agents/usage.ts
@@ -1,9 +1,5 @@
import { logger } from '@librechat/data-schemas';
-import {
- inputTokensIncludesCache,
- reconcileContextUsage,
- promptTokensFromUsage,
-} from 'librechat-data-provider';
+import { inputTokensIncludesCache, reconcileContextUsageFromEvent } from 'librechat-data-provider';
import type {
TCustomConfig,
TResponseUsage,
@@ -352,41 +348,93 @@ function finalPrimaryCall(
return undefined;
}
+const finiteNonNegativeInteger = (value: unknown): number | undefined => {
+ if (typeof value !== 'number' || !Number.isFinite(value)) {
+ return undefined;
+ }
+ return Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, Math.floor(value)));
+};
+
+/**
+ * Sanitizes persisted per-tool counts and drops zero entries. Null-prototype
+ * records keep tool names as data keys; the cap bounds each result-message share.
+ */
+const normalizePersistedTokenRecord = (
+ value: unknown,
+ maxTotal?: number,
+): Record<string, number> | undefined => {
+ if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+ return undefined;
+ }
+ const normalized: Record<string, number> = Object.create(null);
+ let remaining = maxTotal;
+ let found = false;
+ for (const [name, rawCount] of Object.entries(value)) {
+ const count = finiteNonNegativeInteger(rawCount);
+ if (count == null) {
+ continue;
+ }
+ const bounded = remaining == null ? count : Math.min(count, remaining);
+ if (bounded === 0) {
+ continue;
+ }
+ normalized[name] = bounded;
+ found = true;
+ if (remaining != null) {
+ remaining -= bounded;
+ }
+ }
+ return found ? normalized : undefined;
+};
+
/**
* Projects the latest live context snapshot into the blob persisted on
* `responseMessage.metadata.contextUsage`. Reconciles the calibrated estimate to
* the final call's ACTUAL prompt tokens (the SDK multiplier over-inflates
* `messageTokens`, badly so when a provider injects server-side content like web
* search), so a reloaded turn shows the real context — not a several×-too-high
- * number. Trims zero-valued per-tool counts (privacy/size) and records the final
- * call's output as `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.
+ * number. Sanitizes malformed optional token fields, bounds each result-message
+ * share by the parent total, and records the final call's output as
+ * `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.
*/
export function buildPersistedContextUsage(
snapshot: TContextUsageEvent,
usageEvents: ReadonlyArray<TTokenUsageEvent> = [],
): TContextUsageEvent {
const finalCall = finalPrimaryCall(usageEvents, snapshot.runId);
- const completedOutputTokens = finalCall ? normalizeEventUnits(finalCall).output : 0;
- const reconciled = finalCall
- ? reconcileContextUsage(snapshot, promptTokensFromUsage(finalCall))
- : snapshot;
+ const reconciled = finalCall ? reconcileContextUsageFromEvent(snapshot, finalCall) : snapshot;
const { breakdown } = reconciled;
- let toolTokenCounts = breakdown.toolTokenCounts;
- if (toolTokenCounts != null) {
- const trimmed: Record<string, number> = {};
- for (const [name, count] of Object.entries(toolTokenCounts)) {
- if (count > 0) {
- trimmed[name] = count;
- }
+ const messageTokens = finiteNonNegativeInteger(breakdown.messageTokens) ?? 0;
+ const toolTokenCounts = normalizePersistedTokenRecord(breakdown.toolTokenCounts);
+ const rawToolMessageTokens = finiteNonNegativeInteger(breakdown.toolMessageTokens);
+ const toolMessageTokens =
+ rawToolMessageTokens == null ? undefined : Math.min(rawToolMessageTokens, messageTokens);
+ const toolMessageTokenCounts =
+ toolMessageTokens != null
+ ? normalizePersistedTokenRecord(breakdown.toolMessageTokenCounts, toolMessageTokens)
+ : undefined;
+ const persistedBreakdown = { ...breakdown, messageTokens };
+ if (toolTokenCounts == null) {
+ delete persistedBreakdown.toolTokenCounts;
+ } else {
+ persistedBreakdown.toolTokenCounts = toolTokenCounts;
+ }
+ if (toolMessageTokens == null) {
+ delete persistedBreakdown.toolMessageTokens;
+ delete persistedBreakdown.toolMessageTokenCounts;
+ } else {
+ persistedBreakdown.toolMessageTokens = toolMessageTokens;
+ if (toolMessageTokenCounts == null) {
+ delete persistedBreakdown.toolMessageTokenCounts;
+ } else {
+ persistedBreakdown.toolMessageTokenCounts = toolMessageTokenCounts;
}
- toolTokenCounts = Object.keys(trimmed).length > 0 ? trimmed : undefined;
}
return {
...reconciled,
- breakdown: { ...breakdown, toolTokenCounts },
- ...(completedOutputTokens > 0 && { completedOutputTokens }),
+ breakdown: persistedBreakdown,
};
}
diff --git a/packages/api/src/stream/GenerationJobManager.ts b/packages/api/src/stream/GenerationJobManager.ts
index 65873fd734..869b1571f2 100644
--- a/packages/api/src/stream/GenerationJobManager.ts
+++ b/packages/api/src/stream/GenerationJobManager.ts
@@ -8,8 +8,7 @@ import {
ApprovalEvents,
SteerEvents,
parseTextParts,
- reconcileContextUsage,
- promptTokensFromUsage,
+ reconcileContextUsageFromEvent,
} from 'librechat-data-provider';
import type {
TMessageContentParts,
@@ -7714,9 +7713,14 @@ class GenerationJobManagerClass {
snapshot != null &&
(snapshot.runId == null || usage.runId == null || snapshot.runId === usage.runId)
) {
- update.contextUsage = JSON.stringify(
- reconcileContextUsage(snapshot, promptTokensFromUsage(usage)),
+ const { completedOutputTokens, ...reconciled } = reconcileContextUsageFromEvent(
+ snapshot,
+ usage,
);
+ update.contextUsage = JSON.stringify({
+ ...reconciled,
+ resumedOutputTokens: completedOutputTokens,
+ });
}
} catch {
/* leave the stored snapshot as-is on parse failure */
diff --git a/packages/api/src/stream/__tests__/usageResume.spec.ts b/packages/api/src/stream/__tests__/usageResume.spec.ts
index 59564730f9..978c9cbaf7 100644
--- a/packages/api/src/stream/__tests__/usageResume.spec.ts
+++ b/packages/api/src/stream/__tests__/usageResume.spec.ts
@@ -15,6 +15,28 @@ function createInMemoryManager(): GenerationJobManagerClass {
return manager;
}
+const makeSnapshot = (messageTokens: number) => ({
+ runId: 'run-1',
+ agentId: 'agent-1',
+ breakdown: {
+ maxContextTokens: 200000,
+ instructionTokens: 1500,
+ systemMessageTokens: 1000,
+ dynamicInstructionTokens: 0,
+ toolSchemaTokens: 500,
+ summaryTokens: 0,
+ toolCount: 3,
+ messageCount: 4,
+ messageTokens,
+ availableForMessages: 188500,
+ },
+ contextBudget: 190000,
+ effectiveInstructionTokens: 1500,
+ prePruneContextTokens: messageTokens,
+ remainingContextTokens: 190000 - 1500 - messageTokens,
+ calibrationRatio: 1.05,
+});
+
describe('GenerationJobManager usage resume state', () => {
let manager: GenerationJobManagerClass | undefined;
@@ -60,32 +82,61 @@ describe('GenerationJobManager usage resume state', () => {
expect(resumeState?.contextUsage).toBeUndefined();
});
- test('persists the latest context usage snapshot for resume', async () => {
+ test('restores final primary call details without replaying usage', async () => {
manager = createInMemoryManager();
- const streamId = `context-resume-${Date.now()}`;
+ const streamId = `context-call-resume-${Date.now()}`;
await manager.createJob(streamId, 'user-1', streamId);
-
- const makeSnapshot = (messageTokens: number) => ({
+ await manager.emitChunk(streamId, { event: 'on_context_usage', data: makeSnapshot(9000) });
+ const primary = {
runId: 'run-1',
- agentId: 'agent-1',
- breakdown: {
- maxContextTokens: 200000,
- instructionTokens: 1500,
- systemMessageTokens: 1000,
- dynamicInstructionTokens: 0,
- toolSchemaTokens: 500,
- summaryTokens: 0,
- toolCount: 3,
- messageCount: 4,
- messageTokens,
- availableForMessages: 188500,
- },
- contextBudget: 190000,
- effectiveInstructionTokens: 1500,
- prePruneContextTokens: messageTokens,
- remainingContextTokens: 190000 - 1500 - messageTokens,
- calibrationRatio: 1.05,
+ input_tokens: 10000,
+ output_tokens: 300,
+ input_token_details: { cache_creation: 100, cache_read: 800 },
+ model: 'primary-model',
+ provider: 'anthropic',
+ };
+ await manager.emitChunk(streamId, { event: 'on_token_usage', data: primary });
+ await manager.emitChunk(streamId, {
+ event: 'on_token_usage',
+ data: { ...primary, runId: 'other-run', model: 'other-model' },
+ });
+ await manager.emitChunk(streamId, {
+ event: 'on_token_usage',
+ data: { ...primary, usage_type: 'subagent', model: 'child-model' },
+ });
+
+ const resumeState = await manager.getResumeState(streamId);
+ expect(resumeState?.contextUsage).toMatchObject({
+ model: 'primary-model',
+ provider: 'anthropic',
+ resumedOutputTokens: 300,
+ cacheRead: 800,
+ cacheWrite: 100,
+ remainingContextTokens: 180000,
+ breakdown: { messageTokens: 8500 },
+ });
+ expect(resumeState?.contextUsage?.completedOutputTokens).toBeUndefined();
+ expect(resumeState?.collectedUsage).toHaveLength(3);
+
+ await manager.emitChunk(streamId, { event: 'on_context_usage', data: makeSnapshot(12000) });
+ const midCall = await manager.getResumeState(streamId);
+ expect(midCall?.contextUsage).toEqual(makeSnapshot(12000));
+ await manager.emitChunk(streamId, {
+ event: 'on_token_usage',
+ data: { ...primary, input_token_details: {}, model: 'next-model' },
+ });
+ const nextCall = await manager.getResumeState(streamId);
+ expect(nextCall?.contextUsage).toMatchObject({
+ cacheRead: 0,
+ cacheWrite: 0,
+ model: 'next-model',
});
+ });
+
+ test('persists the latest context usage snapshot for resume', async () => {
+ manager = createInMemoryManager();
+ const streamId = `context-resume-${Date.now()}`;
+ await manager.createJob(streamId, 'user-1', streamId);
await manager.emitChunk(streamId, { event: 'on_context_usage', data: makeSnapshot(4000) });
await manager.emitChunk(streamId, { event: 'on_context_usage', data: makeSnapshot(9000) });
diff --git a/packages/client/src/components/SegmentedMeter.tsx b/packages/client/src/components/SegmentedMeter.tsx
index 37445e5abf..047c0b1193 100644
--- a/packages/client/src/components/SegmentedMeter.tsx
+++ b/packages/client/src/components/SegmentedMeter.tsx
@@ -10,6 +10,7 @@ const SERIES_FILL = [
'bg-series-5',
'bg-series-6',
'bg-series-7',
+ 'bg-series-8',
] as const;
const SERIES_TINT = [
@@ -20,6 +21,7 @@ const SERIES_TINT = [
'bg-series-5/25',
'bg-series-6/25',
'bg-series-7/25',
+ 'bg-series-8/25',
] as const;
const SERIES_EDGE = [
@@ -30,6 +32,7 @@ const SERIES_EDGE = [
'ring-series-5',
'ring-series-6',
'ring-series-7',
+ 'ring-series-8',
] as const;
export const SERIES_SLOT_COUNT: number = SERIES_FILL.length;
diff --git a/packages/client/src/theme/registry.spec.ts b/packages/client/src/theme/registry.spec.ts
index a6216c02e0..5407c4e085 100644
--- a/packages/client/src/theme/registry.spec.ts
+++ b/packages/client/src/theme/registry.spec.ts
@@ -211,6 +211,89 @@ describe('theme registry', () => {
expect(resolved.colors['rgb-chart-widget-stroke']).toBe('50 51 52');
});
+ /** A deliberately different reference theme: it paints the whole seven-slot
+ * scale and its own surfaces, so it predates slot 8 and cannot name it.
+ * Falling back to the bundled indigo would paint a stop whose 3:1 mark
+ * contrast was only ever measured against LibreChat's surfaces. */
+ const ownedScaleTheme: ThemeDefinition = {
+ version: 1,
+ name: 'owned-scale-reference',
+ modes: {
+ light: {
+ colors: {
+ 'rgb-text-primary': '250 250 250',
+ 'rgb-text-secondary': '215 215 215',
+ 'rgb-surface-secondary': '18 18 24',
+ 'rgb-surface-tertiary': '30 30 38',
+ 'rgb-series-1': '120 200 255',
+ 'rgb-series-2': '255 160 90',
+ 'rgb-series-3': '110 230 210',
+ 'rgb-series-4': '240 200 100',
+ 'rgb-series-5': '250 150 200',
+ 'rgb-series-6': '190 160 255',
+ 'rgb-series-7': '130 220 120',
+ },
+ },
+ },
+ };
+
+ it('derives an omitted eighth series slot from an owned scale’s neutral text', () => {
+ const owned = resolveTheme(ownedScaleTheme, 'light');
+
+ expect(owned.colors['rgb-series-8']).toBe('215 215 215');
+ expect(owned.colors['rgb-series-7']).toBe('130 220 120');
+ });
+
+ it('derives it from the inherited text of an owned scale that names no text', () => {
+ /** The same reference theme minus its text overrides: it repaints the scale
+ * and its surfaces but reads body copy in LibreChat's own colours, so the
+ * stop tracks the text it will actually sit beside instead of reverting to
+ * the bundled indigo. */
+ const inheritedText = resolveTheme(
+ {
+ ...ownedScaleTheme,
+ modes: {
+ light: {
+ colors: {
+ 'rgb-surface-secondary': '18 18 24',
+ 'rgb-surface-tertiary': '30 30 38',
+ 'rgb-series-1': '120 200 255',
+ 'rgb-series-7': '130 220 120',
+ },
+ },
+ },
+ },
+ 'light',
+ );
+
+ expect(inheritedText.colors['rgb-series-8']).toBe(defaultTheme['rgb-text-secondary']);
+ });
+
+ it('lets an owned scale name the eighth slot itself', () => {
+ const named = resolveTheme(
+ {
+ ...ownedScaleTheme,
+ modes: {
+ light: {
+ colors: { ...ownedScaleTheme.modes.light?.colors, 'rgb-series-8': '10 20 30' },
+ },
+ },
+ },
+ 'light',
+ );
+
+ expect(named.colors['rgb-series-8']).toBe('10 20 30');
+ });
+
+ it('keeps the bundled eighth slot for a theme that paints no series colors', () => {
+ expect(resolveTheme(compactTheme, 'dark').colors['rgb-series-8']).toBe(
+ darkTheme['rgb-series-8'],
+ );
+ expect(resolveTheme(compactTheme, 'light').colors['rgb-series-8']).toBe(
+ defaultTheme['rgb-series-8'],
+ );
+ });
+
it('resolves provider brand tokens and lets a theme override them', () => {
const defaults = resolveTheme(libreChatTheme, 'light');
expect(defaults.brands['provider-anthropic']).toBe('#d09a74');
diff --git a/packages/client/src/theme/registry.ts b/packages/client/src/theme/registry.ts
index 8220b2fd4d..b2fd084315 100644
--- a/packages/client/src/theme/registry.ts
+++ b/packages/client/src/theme/registry.ts
@@ -18,7 +18,7 @@ export const THEME_VERSION = 1 as const;
* hand-maintained token maps, so a slot added to one and missed in another
* fails the build rather than surfacing as a broken theme downstream.
*/
-type SeriesSlot = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+type SeriesSlot = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
type Assert<Declared extends true> = Declared;
type DeclaredIn<Keys extends PropertyKey, Tokens> = [Keys] extends [keyof Tokens] ? true : false;
@@ -391,6 +391,30 @@ export function resolveTheme(theme: ThemeDefinition, mode: ThemeMode): ResolvedT
customColors?.['rgb-border-light'] !== undefined
? { 'rgb-chart-widget-stroke': customColors['rgb-border-light'] }
: {};
+ /**
+ * Slot 8 arrived after the seven-slot scale shipped, so a stored or
+ * environment theme that paints its own scale cannot name it. Filling the
+ * omission from the bundled base would drop LibreChat's indigo onto that
+ * theme's own surfaces — the one pairing it never checked, since the stop's
+ * 3:1 mark contrast is a claim about the bundled surfaces only. The RESOLVED
+ * secondary text is the one colour that tracks whatever the theme reads its
+ * body copy against, whether it names its own or inherits ours, so slot 8
+ * stays exactly as visible as that text; hue-neutral, it cannot collide with
+ * a custom slot 1–7 under protanopia/deuteranopia either. A theme that wants
+ * a hue for slot 8 names it, the way `rgb-surface-composer-hover` opts out of
+ * its own fallback.
+ */
+ const ownsSeriesScale =
+ customColors != null &&
+ ([1, 2, 3, 4, 5, 6, 7] as const).some(
+ (slot) => customColors[`rgb-series-${slot}`] !== undefined,
+ );
+ const seriesEightFallback =
+ customColors?.['rgb-series-8'] === undefined && ownsSeriesScale
+ ? {
+ 'rgb-series-8': customColors?.['rgb-text-secondary'] ?? baseColors['rgb-text-secondary'],
+ }
+ : {};
return {
version: THEME_VERSION,
@@ -405,6 +429,7 @@ export function resolveTheme(theme: ThemeDefinition, mode: ThemeMode): ResolvedT
...textMutedFallback,
...chartWidgetSurfaceFallback,
...chartWidgetStrokeFallback,
+ ...seriesEightFallback,
} as Required<IThemeRGB>,
appearance: { ...defaultAppearance, ...definition?.appearance },
/** Mode last: a mode override is more specific than the theme-wide set. */
diff --git a/packages/client/src/theme/semanticTokens.spec.ts b/packages/client/src/theme/semanticTokens.spec.ts
index 1073a0e923..ffe1459a94 100644
--- a/packages/client/src/theme/semanticTokens.spec.ts
+++ b/packages/client/src/theme/semanticTokens.spec.ts
@@ -264,7 +264,7 @@ describe.each([
* checked capability badges sit on `surface-chat`; dialog option toggles sit
* on `surface-dialog`. All have to clear the 3:1 mark-contrast floor. */
const seriesTokens = Array.from(
- { length: 7 },
+ { length: 8 },
(_, index) => `rgb-series-${index + 1}` as keyof IThemeRGB,
);
const seriesSurfaces: Array<keyof IThemeRGB> = [
diff --git a/packages/client/src/theme/themes/dark.ts b/packages/client/src/theme/themes/dark.ts
index d16ecc3d61..65dcf7786e 100644
--- a/packages/client/src/theme/themes/dark.ts
+++ b/packages/client/src/theme/themes/dark.ts
@@ -112,8 +112,12 @@ export const darkTheme: IThemeRGB = {
'rgb-syntax-attr': '223 48 121', // #df3079
'rgb-syntax-title': '242 44 61', // #f22c3d
- /** Categorical series scale — the same seven hues stepped for the #212121
- * surface: worst adjacent CVD ΔE 13.0, normal-vision ΔE 19.0, all ≥ 3:1. */
+ /** Categorical series scale — the same eight hues stepped for the #212121
+ * surface: worst adjacent CVD ΔE 13.0, normal-vision ΔE 19.0, all ≥ 3:1.
+ * Slot 8 is muted rather than the light mode's saturated indigo because a
+ * slot also fills a badge chip under `text-on-status` white: #8c98e6 carried
+ * that glyph at only 2.71:1, this reads 3.66:1 and still clears 3.66:1 on
+ * every series surface. */
'rgb-series-1': '9 140 238', // #098cee (cerulean)
'rgb-series-2': '217 87 35', // #d95723 (orange)
'rgb-series-3': '6 158 152', // #069e98 (aqua)
@@ -121,6 +125,7 @@ export const darkTheme: IThemeRGB = {
'rgb-series-5': '213 82 130', // #d55282 (magenta)
'rgb-series-6': '171 104 254', // #ab68fe (violet)
'rgb-series-7': '80 167 49', // #50a731 (green)
+ 'rgb-series-8': '120 130 190', // #8082be (indigo)
/** Unchecked switch track. 3.38:1 against the page and the `surface-primary`
* thumb, 5.74:1 against the checked `surface-inverted` track. */
diff --git a/packages/client/src/theme/themes/default.ts b/packages/client/src/theme/themes/default.ts
index 9e688ff446..a21426d622 100644
--- a/packages/client/src/theme/themes/default.ts
+++ b/packages/client/src/theme/themes/default.ts
@@ -106,7 +106,9 @@ export const defaultTheme: IThemeRGB = {
/** Categorical series scale. Steps clear 3:1 against BOTH the popover surface
* and the #ececec meter track, with worst adjacent CVD ΔE 12.4 and worst
- * adjacent normal-vision ΔE 19.0. Slot order is the CVD-safety mechanism. */
+ * adjacent normal-vision ΔE 19.0. Slot order is the CVD-safety mechanism:
+ * indigo(8) sits beside green(7) because blue separates from green under
+ * protanopia/deuteranopia where red would not. */
'rgb-series-1': '5 110 189', // #056ebd (cerulean)
'rgb-series-2': '233 86 13', // #e9560d (orange)
'rgb-series-3': '0 148 142', // #00948e (aqua)
@@ -114,6 +116,7 @@ export const defaultTheme: IThemeRGB = {
'rgb-series-5': '216 90 142', // #d85a8e (magenta)
'rgb-series-6': '126 35 205', // #7e23cd (violet)
'rgb-series-7': '1 131 1', // #018301 (green)
+ 'rgb-series-8': '63 81 181', // #3f51b5 (indigo)
/** Unchecked switch track. 3.03:1 against the white page and the
* `surface-primary` thumb, 5.91:1 against the checked `surface-inverted`
diff --git a/packages/client/src/theme/themes/highContrast.ts b/packages/client/src/theme/themes/highContrast.ts
index fd07d37d54..5140c07b74 100644
--- a/packages/client/src/theme/themes/highContrast.ts
+++ b/packages/client/src/theme/themes/highContrast.ts
@@ -141,8 +141,12 @@ export const highContrastLightTheme: IThemeRGB = {
'rgb-syntax-title': '143 26 16', // #8f1a10
/** Categorical series scale. Every slot clears 7:1 on the white canvas and no
- * two adjacent slots sit closer than CIE76 dE 50 under normal vision or dE 45
- * under simulated deuteranopia. */
+ * two adjacent chromatic slots sit closer than CIE76 dE 50 under normal
+ * vision or dE 45 under simulated deuteranopia. Seven saturated hues is all
+ * this canvas affords at that separation, so slot 8 is the palette's own
+ * neutral text — the stop `resolveTheme` also derives for a theme that
+ * paints its own scale — separated by lightness (21:1 on the canvas, dE 22.9
+ * from its neighbour under deuteranopia) rather than by hue. */
'rgb-series-1': '11 79 160', // #0b4fa0
'rgb-series-2': '143 59 0', // #8f3b00
'rgb-series-3': '0 82 79', // #00524f
@@ -150,6 +154,7 @@ export const highContrastLightTheme: IThemeRGB = {
'rgb-series-5': '148 0 92', // #94005c
'rgb-series-6': '77 26 153', // #4d1a99
'rgb-series-7': '15 92 15', // #0f5c0f
+ 'rgb-series-8': '0 0 0', // #000000 (neutral text stop)
/** Unchecked switch track. The stock 58%/40% greys land at 2.9:1 and 2.2:1
* against these canvases. This clears 3:1 three ways at once: 5.74:1 against
@@ -272,9 +277,12 @@ export const highContrastDarkTheme: IThemeRGB = {
'rgb-syntax-attr': '255 153 194', // #ff99c2
'rgb-syntax-title': '255 143 143', // #ff8f8f
- /** Categorical series scale. Every slot clears 9.9:1 on the black canvas and no
- * two adjacent slots sit closer than CIE76 dE 37 under normal vision or dE 42
- * under simulated deuteranopia. */
+ /** Categorical series scale. Every slot clears 9.9:1 on the black canvas and
+ * no two adjacent chromatic slots sit closer than CIE76 dE 37 under normal
+ * vision or dE 42 under simulated deuteranopia. As in the light palette,
+ * slot 8 is the neutral text stop rather than an eighth pastel this canvas
+ * cannot separate: 21:1 on the canvas and dE 26.8 from the nearest slot
+ * under deuteranopia, distinguished by lightness rather than hue. */
'rgb-series-1': '107 184 255', // #6bb8ff
'rgb-series-2': '255 179 102', // #ffb366
'rgb-series-3': '92 230 219', // #5ce6db
@@ -282,6 +290,7 @@ export const highContrastDarkTheme: IThemeRGB = {
'rgb-series-5': '255 153 194', // #ff99c2
'rgb-series-6': '200 163 255', // #c8a3ff
'rgb-series-7': '140 230 140', // #8ce68c
+ 'rgb-series-8': '255 255 255', // #ffffff (neutral text stop)
/** Unchecked switch track: 5.32:1 against the page and the `surface-primary`
* thumb, 3.95:1 against the checked `surface-inverted` track. */
diff --git a/packages/client/src/theme/types/index.ts b/packages/client/src/theme/types/index.ts
index 94fde9189a..7582c558c9 100644
--- a/packages/client/src/theme/types/index.ts
+++ b/packages/client/src/theme/types/index.ts
@@ -121,6 +121,7 @@ export interface IThemeRGB {
'rgb-series-5'?: string;
'rgb-series-6'?: string;
'rgb-series-7'?: string;
+ 'rgb-series-8'?: string;
/**
* Unchecked track of the shared `Switch`. A control state rather than a
@@ -232,6 +233,7 @@ export interface IThemeVariables {
'--series-5': string;
'--series-6': string;
'--series-7': string;
+ '--series-8': string;
'--switch-unchecked': string;
@@ -322,6 +324,7 @@ export interface IThemeColors {
'series-6'?: string;
'series-7'?: string;
'switch-unchecked'?: string;
+ 'series-8'?: string;
presentation?: string;
// Retained for excluded SidePanel/Agents + SidePanel/Builder (pending migration)
diff --git a/packages/client/src/theme/utils/createTailwindColors.js b/packages/client/src/theme/utils/createTailwindColors.js
index c4e31cfe25..050868fb56 100644
--- a/packages/client/src/theme/utils/createTailwindColors.js
+++ b/packages/client/src/theme/utils/createTailwindColors.js
@@ -149,6 +149,7 @@ function createTailwindColors() {
'series-5': cssVar('--series-5'),
'series-6': cssVar('--series-6'),
'series-7': cssVar('--series-7'),
+ 'series-8': cssVar('--series-8'),
'switch-unchecked': cssVar('--switch-unchecked'),
};
diff --git a/packages/data-provider/src/types/runs.spec.ts b/packages/data-provider/src/types/runs.spec.ts
index e35d1a03c2..cd00f9a40b 100644
--- a/packages/data-provider/src/types/runs.spec.ts
+++ b/packages/data-provider/src/types/runs.spec.ts
@@ -1,5 +1,5 @@
import type { TContextUsageEvent, TTokenUsageEvent } from './runs';
-import { promptTokensFromUsage, reconcileContextUsage } from './runs';
+import { promptTokensFromUsage, outputTokensFromUsage, reconcileContextUsage } from './runs';
describe('promptTokensFromUsage', () => {
it('adds cache reads/writes for additive providers (Bedrock)', () => {
@@ -32,6 +32,15 @@ describe('promptTokensFromUsage', () => {
it('handles missing fields', () => {
expect(promptTokensFromUsage({ provider: 'anthropic' })).toBe(0);
});
+ it('ignores malformed numeric usage fields', () => {
+ expect(
+ promptTokensFromUsage({
+ input_tokens: Number.NaN,
+ input_token_details: { cache_read: Number.POSITIVE_INFINITY, cache_creation: '4' as never },
+ provider: 'bedrock',
+ }),
+ ).toBe(0);
+ });
it('accepts the activity-label usage bucket emitted on the wire', () => {
/** Type-level pin: the backend emits this literal for fast-model header
@@ -76,6 +85,30 @@ describe('promptTokensFromUsage', () => {
});
});
+describe('outputTokensFromUsage', () => {
+ it('repairs omitted reasoning while excluding additive prompt-cache tokens', () => {
+ expect(
+ outputTokensFromUsage({
+ provider: 'bedrock',
+ input_tokens: 200,
+ output_tokens: 30,
+ total_tokens: 450,
+ input_token_details: { cache_read: 100, cache_creation: 50 },
+ }),
+ ).toBe(100);
+ expect(
+ outputTokensFromUsage({
+ provider: 'bedrock',
+ input_tokens: 200,
+ output_tokens: 30,
+ total_tokens: 380,
+ input_token_details: { cache_read: 100, cache_creation: 50 },
+ }),
+ ).toBe(30);
+ expect(outputTokensFromUsage({ output_tokens: NaN, total_tokens: Infinity })).toBe(0);
+ });
+});
+
describe('reconcileContextUsage', () => {
/** The exact over-reporting case from a real web-search + summarization turn:
* calibrationRatio pinned at 5 inflated messageTokens to 187471 → used 213375,
@@ -121,6 +154,133 @@ describe('reconcileContextUsage', () => {
expect(result.remainingContextTokens).toBe(237500 - 3000);
});
+ it('rescales toolMessageTokens proportionally to the corrected messageTokens', () => {
+ const snapshot: TContextUsageEvent = {
+ ...inflatedSnapshot,
+ breakdown: { ...inflatedSnapshot.breakdown, toolMessageTokens: 46868 },
+ };
+ const result = reconcileContextUsage(snapshot, 55773);
+ const messageTokens = 55773 - 4205 - 1938;
+ const toolMessageTokens = Math.round((46868 / 187471) * messageTokens);
+ expect(result.breakdown.messageTokens).toBe(messageTokens);
+ expect(result.breakdown.toolMessageTokens).toBe(toolMessageTokens);
+ /** the split stays a subset of the corrected total */
+ expect(result.breakdown.toolMessageTokens).toBeLessThanOrEqual(result.breakdown.messageTokens);
+ /** rows still sum to the real total */
+ expect(
+ result.breakdown.messageTokens +
+ result.breakdown.instructionTokens +
+ result.breakdown.summaryTokens,
+ ).toBe(55773);
+ });
+
+ it('rescales toolMessageTokenCounts with the reconciled total', () => {
+ const snapshot: TContextUsageEvent = {
+ ...inflatedSnapshot,
+ breakdown: {
+ ...inflatedSnapshot.breakdown,
+ toolMessageTokens: 46868,
+ toolMessageTokenCounts: { grep: 40000, read_file: 6868, zero: 0 },
+ },
+ };
+ const result = reconcileContextUsage(snapshot, 55773);
+ const factor = result.breakdown.toolMessageTokens! / 46868;
+ expect(result.breakdown.toolMessageTokenCounts?.grep).toBe(Math.round(40000 * factor));
+ expect(result.breakdown.toolMessageTokenCounts?.read_file).toBe(Math.round(6868 * factor));
+ });
+
+ it('rescales toolMessageTokenCounts without rounding past the total', () => {
+ const snapshot: TContextUsageEvent = {
+ ...inflatedSnapshot,
+ breakdown: {
+ ...inflatedSnapshot.breakdown,
+ messageTokens: 10,
+ toolMessageTokens: 10,
+ toolMessageTokenCounts: { first: 5, second: 5 },
+ },
+ };
+ const result = reconcileContextUsage(snapshot, 4205 + 1938 + 1);
+ expect(result.breakdown.toolMessageTokens).toBe(1);
+ expect(
+ Object.values(result.breakdown.toolMessageTokenCounts ?? {}).reduce(
+ (total, count) => total + count,
+ 0,
+ ),
+ ).toBeLessThanOrEqual(result.breakdown.toolMessageTokens ?? 0);
+ });
+
+ it('sanitizes malformed counts and preserves prototype-sensitive names', () => {
+ const counts = JSON.parse('{"__proto__":2,"constructor":2,"invalid":"3"}') as Record<
+ string,
+ number
+ >;
+ const snapshot: TContextUsageEvent = {
+ ...inflatedSnapshot,
+ breakdown: {
+ ...inflatedSnapshot.breakdown,
+ messageTokens: 10,
+ toolMessageTokens: 4,
+ toolMessageTokenCounts: counts,
+ },
+ };
+ const result = reconcileContextUsage(snapshot, 4205 + 1938 + 10);
+ const resultCounts = result.breakdown.toolMessageTokenCounts;
+ expect(resultCounts?.['__proto__']).toBe(2);
+ expect(resultCounts?.constructor).toBe(2);
+ expect(resultCounts?.invalid).toBeUndefined();
+ expect(Object.keys(resultCounts ?? {})).toEqual(['__proto__', 'constructor']);
+ });
+
+ it('keeps a supplied zero tool split distinct from an absent split', () => {
+ const snapshot: TContextUsageEvent = {
+ ...inflatedSnapshot,
+ breakdown: { ...inflatedSnapshot.breakdown, toolMessageTokens: 0 },
+ };
+ const result = reconcileContextUsage(snapshot, 55773);
+ expect(result.breakdown.toolMessageTokens).toBe(0);
+ expect(Object.prototype.hasOwnProperty.call(result.breakdown, 'toolMessageTokens')).toBe(true);
+ });
+
+ it('keeps toolMessageTokenCounts absent when the tool total is absent', () => {
+ const snapshot: TContextUsageEvent = {
+ ...inflatedSnapshot,
+ breakdown: { ...inflatedSnapshot.breakdown, toolMessageTokenCounts: { grep: 100 } },
+ };
+ const result = reconcileContextUsage(snapshot, 55773);
+ expect(result.breakdown.toolMessageTokenCounts).toBeUndefined();
+ });
+
+ it('keeps toolMessageTokens absent on snapshots without the field (older SDK)', () => {
+ const result = reconcileContextUsage(inflatedSnapshot, 55773);
+ expect(result.breakdown.toolMessageTokens).toBeUndefined();
+ });
+
+ it('does not mutate the snapshot while sanitizing malformed values', () => {
+ const snapshot: TContextUsageEvent = {
+ ...inflatedSnapshot,
+ breakdown: {
+ ...inflatedSnapshot.breakdown,
+ toolMessageTokens: Number.NaN,
+ toolMessageTokenCounts: { grep: Number.POSITIVE_INFINITY },
+ },
+ };
+ const result = reconcileContextUsage(snapshot, 55773);
+ expect(snapshot.breakdown.toolMessageTokens).toBeNaN();
+ expect(snapshot.breakdown.toolMessageTokenCounts?.grep).toBe(Infinity);
+ expect(result.breakdown.toolMessageTokens).toBeUndefined();
+ expect(result.breakdown.toolMessageTokenCounts).toBeUndefined();
+ });
+
+ it('clamps an over-sized tool share to the corrected messageTokens', () => {
+ const snapshot: TContextUsageEvent = {
+ ...inflatedSnapshot,
+ breakdown: { ...inflatedSnapshot.breakdown, toolMessageTokens: 187471 },
+ };
+ const result = reconcileContextUsage(snapshot, 6144);
+ expect(result.breakdown.messageTokens).toBe(1);
+ expect(result.breakdown.toolMessageTokens).toBe(1);
+ });
+
it('is a no-op for an unusable prompt count', () => {
expect(reconcileContextUsage(inflatedSnapshot, 0)).toBe(inflatedSnapshot);
expect(reconcileContextUsage(inflatedSnapshot, -5)).toBe(inflatedSnapshot);
diff --git a/packages/data-provider/src/types/runs.ts b/packages/data-provider/src/types/runs.ts
index e05f5cec8c..4ab53c8251 100644
--- a/packages/data-provider/src/types/runs.ts
+++ b/packages/data-provider/src/types/runs.ts
@@ -260,6 +260,10 @@ export type TTokenBudgetBreakdown = {
toolTokenCounts?: Record<string, number>;
/** Names of counted tools that are deferred (`defer_loading`) and discovered */
deferredToolNames?: string[];
+ /** Calibrated retained tool traffic: tool results plus assistant turns made only of tool calls, inline provider tool results and reasoning. A subset of messageTokens, not an additional budget category. */
+ toolMessageTokens?: number;
+ /** Per-tool result-message share; excludes assistant invocation overhead. */
+ toolMessageTokenCounts?: Record<string, number>;
};
/** Per-model-call context snapshot, dispatched after pruning and before the LLM call. */
@@ -276,12 +280,21 @@ export type TContextUsageEvent = {
/** Tokens still free after instructions + pruned messages */
remainingContextTokens?: number;
calibrationRatio?: number;
+ /** Model and provider of the reconciling primary call, retained across reloads. */
+ model?: string;
+ provider?: string;
+ /** Cache portions of that call's prompt, in normalized display units. */
+ cacheRead?: number;
+ cacheWrite?: number;
/** Output tokens of the response's final model call (the call this pre-invoke
- * snapshot precedes). Populated only on the persisted `metadata.contextUsage`
- * blob so a reloaded multi-call turn adds the same post-snapshot delta the
+ * snapshot precedes). Saved in message metadata and used by the client so a
+ * reloaded multi-call turn adds the same post-snapshot delta the
* live finalizer did — not the full response `tokenCount`, which the snapshot
* already includes for earlier steps. */
completedOutputTokens?: number;
+ /** 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;
};
/**
@@ -332,6 +345,13 @@ export type TTokenUsageEvent = {
cost?: number;
};
+const finiteNonNegativeInteger = (value: unknown): number | undefined => {
+ if (typeof value !== 'number' || !Number.isFinite(value)) {
+ return undefined;
+ }
+ return Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, Math.floor(value)));
+};
+
/**
* Full prompt token count for one completed model call — the EXACT context the
* model saw, provider-aware: additive providers (Bedrock) report `input_tokens`
@@ -343,26 +363,66 @@ export type TTokenUsageEvent = {
* gauge reconciles its calibrated estimate to.
*/
export const promptTokensFromUsage = (event: TTokenUsageEvent): number => {
- const input = event.input_tokens ?? 0;
+ const input = finiteNonNegativeInteger(event.input_tokens) ?? 0;
const details = event.input_token_details ?? {};
- const cacheRead = details.cache_read ?? 0;
- const cacheCreation = details.cache_creation ?? 0;
+ const cacheRead = finiteNonNegativeInteger(details.cache_read) ?? 0;
+ const cacheCreation = finiteNonNegativeInteger(details.cache_creation) ?? 0;
const includesCache =
event.provider != null
? inputTokensIncludesCache(event.provider)
: cacheRead + cacheCreation <= input;
- return includesCache ? input : input + cacheRead + cacheCreation;
+ return includesCache
+ ? input
+ : Math.min(Number.MAX_SAFE_INTEGER, input + cacheRead + cacheCreation);
+};
+
+/**
+ * Scales per-tool result-message counts while bounding both malformed input and
+ * rounding error. Null-prototype records keep tool names as ordinary data keys;
+ * cumulative apportionment preserves the scaled sum in one linear pass.
+ */
+const scaleToolMessageTokenCounts = (
+ value: unknown,
+ oldTotal: number,
+ newTotal: number,
+): Record<string, number> | undefined => {
+ if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+ return undefined;
+ }
+ const scaled: Record<string, number> = Object.create(null);
+ let remaining = oldTotal;
+ let cumulative = 0;
+ let allocated = 0;
+ let found = false;
+ for (const [name, rawCount] of Object.entries(value)) {
+ const count = finiteNonNegativeInteger(rawCount);
+ if (count == null || count === 0) {
+ continue;
+ }
+ const bounded = Math.min(count, remaining);
+ remaining -= bounded;
+ cumulative += bounded;
+ const target = oldTotal > 0 ? Math.round((cumulative / oldTotal) * newTotal) : 0;
+ const apportioned = target - allocated;
+ allocated = target;
+ if (apportioned > 0) {
+ scaled[name] = apportioned;
+ found = true;
+ }
+ }
+ return found ? scaled : undefined;
};
/**
* Reconciles a pre-invoke context snapshot's CALIBRATED estimate to a call's
* ACTUAL prompt tokens. The SDK's calibration multiplier scales only
- * `messageTokens` (instructions/summary are raw tiktoken counts), and it can
+ * `messageTokens` (instructions/summary are raw tiktoken counts) and can
* over-shoot badly when a provider injects server-side content the SDK never
* counted (e.g. Anthropic web search) — pinning the gauge several× too high and
* persisting it. Trust the provider's own prompt count: keep the raw
- * instruction/summary rows, set `messageTokens` to the remainder, and recompute
- * the free space. No-op when `promptTokens` is unusable.
+ * instruction/summary rows, set `messageTokens` to the remainder, recompute the
+ * free space, and rescale the `toolMessageTokens` share to the new message
+ * total. No-op when `promptTokens` is unusable.
*/
export const reconcileContextUsage = (
snapshot: TContextUsageEvent,
@@ -371,18 +431,100 @@ export const reconcileContextUsage = (
if (!Number.isFinite(promptTokens) || promptTokens <= 0) {
return snapshot;
}
+ const normalizedPromptTokens = Math.min(Number.MAX_SAFE_INTEGER, Math.floor(promptTokens));
+ if (normalizedPromptTokens <= 0) {
+ return snapshot;
+ }
const { breakdown } = snapshot;
- const budget = snapshot.contextBudget ?? breakdown.maxContextTokens;
- const nonMessageTokens = (breakdown.instructionTokens ?? 0) + (breakdown.summaryTokens ?? 0);
- const messageTokens = Math.max(0, promptTokens - nonMessageTokens);
- return {
+ const instructionTokens = finiteNonNegativeInteger(breakdown.instructionTokens) ?? 0;
+ const summaryTokens = finiteNonNegativeInteger(breakdown.summaryTokens) ?? 0;
+ const budget =
+ finiteNonNegativeInteger(snapshot.contextBudget) ??
+ finiteNonNegativeInteger(breakdown.maxContextTokens);
+ const nonMessageTokens = instructionTokens + summaryTokens;
+ const messageTokens = Math.max(0, normalizedPromptTokens - nonMessageTokens);
+ /** `toolMessageTokens` is a subset of the OLD (calibrated) `messageTokens`;
+ * rescale it by the same proportion so the split tracks the provider's real
+ * total. A supplied zero remains a known-zero split; absent fields stay absent
+ * for older snapshots. */
+ const priorMessageTokens = finiteNonNegativeInteger(breakdown.messageTokens) ?? 0;
+ const priorToolMessageTokens = finiteNonNegativeInteger(breakdown.toolMessageTokens);
+ let toolMessageTokens: number | undefined;
+ if (priorToolMessageTokens != null) {
+ toolMessageTokens = 0;
+ if (priorMessageTokens > 0 && priorToolMessageTokens > 0) {
+ toolMessageTokens = Math.min(
+ messageTokens,
+ Math.round(
+ (Math.min(priorToolMessageTokens, priorMessageTokens) / priorMessageTokens) *
+ messageTokens,
+ ),
+ );
+ }
+ }
+ const toolMessageTokenCounts =
+ toolMessageTokens != null
+ ? scaleToolMessageTokenCounts(
+ breakdown.toolMessageTokenCounts,
+ Math.min(priorToolMessageTokens ?? 0, priorMessageTokens),
+ toolMessageTokens,
+ )
+ : undefined;
+
+ const nextBreakdown = {
+ ...breakdown,
+ instructionTokens,
+ summaryTokens,
+ messageTokens,
+ };
+ if (toolMessageTokens == null) {
+ delete nextBreakdown.toolMessageTokens;
+ delete nextBreakdown.toolMessageTokenCounts;
+ } else {
+ nextBreakdown.toolMessageTokens = toolMessageTokens;
+ if (toolMessageTokenCounts == null) {
+ delete nextBreakdown.toolMessageTokenCounts;
+ } else {
+ nextBreakdown.toolMessageTokenCounts = toolMessageTokenCounts;
+ }
+ }
+ const result = {
...snapshot,
- breakdown: { ...breakdown, messageTokens },
- remainingContextTokens:
- budget != null ? Math.max(0, budget - promptTokens) : snapshot.remainingContextTokens,
+ breakdown: nextBreakdown,
};
+ if (budget != null) {
+ result.remainingContextTokens = Math.max(0, budget - normalizedPromptTokens);
+ } else {
+ const remaining = finiteNonNegativeInteger(snapshot.remainingContextTokens);
+ if (remaining == null) {
+ delete result.remainingContextTokens;
+ } else {
+ result.remainingContextTokens = remaining;
+ }
+ }
+ return result;
+};
+
+/** Provider output, including reasoning omitted from an under-reported output count. */
+export const outputTokensFromUsage = (event: TTokenUsageEvent): number => {
+ const output = finiteNonNegativeInteger(event.output_tokens) ?? 0;
+ const total = finiteNonNegativeInteger(event.total_tokens) ?? 0;
+ return Math.max(output, total - promptTokensFromUsage(event));
};
+/** Reconcile and retain the primary call details on live, saved, and resumable snapshots. */
+export const reconcileContextUsageFromEvent = (
+ snapshot: TContextUsageEvent,
+ event: TTokenUsageEvent,
+): TContextUsageEvent => ({
+ ...reconcileContextUsage(snapshot, promptTokensFromUsage(event)),
+ model: event.model,
+ provider: event.provider,
+ completedOutputTokens: outputTokensFromUsage(event),
+ cacheRead: finiteNonNegativeInteger(event.input_token_details?.cache_read) ?? 0,
+ cacheWrite: finiteNonNegativeInteger(event.input_token_details?.cache_creation) ?? 0,
+});
+
/** Lifecycle phase carried on subagent-progress envelopes (mirrors SDK SubagentUpdatePhase). */
export type SubagentUpdatePhase =
| 'start'
diff --git a/packages/data-schemas/src/methods/message.spec.ts b/packages/data-schemas/src/methods/message.spec.ts
index 033c94bbc3..bf3c9d20a2 100644
--- a/packages/data-schemas/src/methods/message.spec.ts
+++ b/packages/data-schemas/src/methods/message.spec.ts
@@ -158,6 +158,85 @@ describe('Message Operations', () => {
expect(savedMessage?.isUserSubmitted).toBeUndefined();
});
+ it('round-trips context usage metadata without narrowing tool fields or unknown data', async () => {
+ const contextUsage = {
+ runId: 'run-context-rich',
+ breakdown: {
+ messageTokens: 120,
+ toolMessageTokens: 18,
+ toolMessageTokenCounts: { search: 11, read_file: 4 },
+ sdkExtension: {
+ providerOnly: true,
+ nested: { invocationOverhead: 3, labels: ['retained'] },
+ },
+ },
+ sdkExtension: {
+ source: 'retained-snapshot-field',
+ nested: { calibration: { mode: 'provider' } },
+ },
+ };
+ const knownZero = {
+ ...contextUsage,
+ breakdown: {
+ ...contextUsage.breakdown,
+ toolMessageTokens: 0,
+ toolMessageTokenCounts: { search: 0 },
+ },
+ };
+ const {
+ toolMessageTokens: _missingToolMessageTokens,
+ toolMessageTokenCounts: _missingToolMessageTokenCounts,
+ ...missingBreakdown
+ } = contextUsage.breakdown;
+ const missing = { ...contextUsage, breakdown: missingBreakdown };
+
+ await Promise.all([
+ saveMessage(mockCtx, {
+ ...mockMessageData,
+ messageId: 'msg-context-rich',
+ metadata: { contextUsage },
+ }),
+ saveMessage(mockCtx, {
+ ...mockMessageData,
+ messageId: 'msg-context-zero',
+ metadata: { contextUsage: knownZero },
+ }),
+ saveMessage(mockCtx, {
+ ...mockMessageData,
+ messageId: 'msg-context-missing',
+ metadata: { contextUsage: missing },
+ }),
+ ]);
+
+ const persisted = await Message.find({
+ user: 'user123',
+ messageId: { $in: ['msg-context-rich', 'msg-context-zero', 'msg-context-missing'] },
+ }).lean();
+ const byId = new Map(persisted.map((message) => [message.messageId, message]));
+
+ expect(byId.get('msg-context-rich')?.metadata?.contextUsage).toEqual(contextUsage);
+ expect(byId.get('msg-context-zero')?.metadata?.contextUsage).toEqual(knownZero);
+ expect(byId.get('msg-context-missing')?.metadata?.contextUsage).toEqual(missing);
+
+ const zeroBreakdown = (
+ byId.get('msg-context-zero')?.metadata?.contextUsage as typeof knownZero
+ ).breakdown;
+ expect(zeroBreakdown.toolMessageTokens).toBe(0);
+ expect(Object.prototype.hasOwnProperty.call(zeroBreakdown, 'toolMessageTokens')).toBe(true);
+
+ const missingBreakdownRecord = (
+ byId.get('msg-context-missing')?.metadata?.contextUsage as typeof missing
+ ).breakdown;
+ expect(
+ Object.prototype.hasOwnProperty.call(missingBreakdownRecord, 'toolMessageTokens'),
+ ).toBe(false);
+ expect(missingBreakdownRecord.sdkExtension).toEqual(contextUsage.breakdown.sdkExtension);
+ expect(
+ (byId.get('msg-context-rich')?.metadata?.contextUsage as typeof contextUsage).sdkExtension
+ .nested,
+ ).toEqual({ calibration: { mode: 'provider' } });
+ });
+
it('unsets a previously stored context meta in the same update as the terminal save', async () => {
await saveMessage(mockCtx, {
...mockMessageData,