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> = {}) => render( @@ -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 ( -
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 = ( + <> {segment != null && } {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" /> )} - {label} + {label} - - {formatTokens(value)} + + {formatTokens(safeValue)} {percent != null && ( )} + + ); + 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 ? ( + + ) : ( +
+ {content}
); } @@ -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(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({
@@ -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. */} - +
+ {(pressure !== 'none' || insights.length > 0) && ( +
+ {pressure !== 'none' ? ( +

+

+ ) : ( + + )} + {insights.length > 0 && ( + + + + + + + {insights.map((insight, index) => ( +

+ {insight} +

+ ))} +
+
+
+ )} +
+ )}
{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 ( + + {id === 'tool-calls' && hasToolCounts ? ( + setToolsExpanded((open) => !open)} + expanded={toolsExpanded} + controls={toolsExpanded ? toolBreakdownId : undefined} + /> + ) : ( + + )} + {id === 'tool-calls' && toolsExpanded && hasToolCounts && ( +
+

+ {localize('com_ui_context_tool_breakdown')} +

+ {toolBreakdown.map((tool) => ( + + ))} +
+ )} + {id === 'system' && dynamicInstructionTokens > 0 && ( +
+ +
+ )} +
+ ); + })} + {/** 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) && ( +
+ {normalizeTokenCount(view.cacheRead) > 0 && ( - ), + )} + {normalizeTokenCount(view.cacheWrite) > 0 && ( + + )} +
)} {freeTokens != null && ( ) : ( <> - {view.branchTotals.summaryBaseline > 0 && ( + {normalizeTokenCount(view.branchTotals.summaryBaseline) > 0 && ( - {view.estimatedTokens > 0 && ( + {normalizeTokenCount(view.estimatedTokens) > 0 && ( )} + {/** 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 && ( +
+ +
+ )} {view.overheadTokens > 0 && ( )} @@ -314,12 +599,19 @@ export default function Breakdown({ - {branchUsage.cacheRead > 0 && ( + {normalizeTokenCount(branchUsage.cacheRead) > 0 && ( )} - {branchUsage.cacheWrite > 0 && ( + {normalizeTokenCount(branchUsage.cacheWrite) > 0 && ( )} + {/** 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 && ( + + )}
)} 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(null); @@ -243,10 +244,11 @@ function TokenUsageIndicator({ - {compactionEnabled && supportsCompaction(conversation?.endpoint) && ( + {compactionAvailable && ( <>
({ + 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 = 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 }) => ( + {children} + ), + }, + ); +}; + +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 = { + 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; + /** 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 => ({ 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(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(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(EMPTY_USAGE), +); + /** Last known provider-vs-estimate calibration ratio for the conversation */ export const calibrationFamily = atomFamily((_conversationId: string) => atom(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([ + /** 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): 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): { 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): number { } function toEntry(message: Partial): 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): 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 & { + breakdown?: Partial; + }, +): 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, +): 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> & { + breakdown?: Partial; + }) + | 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(); 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[], +): Promise { + 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 { + return requestJson(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 { + 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 | undefined => { + if (value == null || typeof value !== 'object' || Array.isArray(value)) { + return undefined; + } + const normalized: Record = 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 = [], ): 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 = {}; - 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,33 +82,62 @@ describe('GenerationJobManager usage resume state', () => { expect(resumeState?.contextUsage).toBeUndefined(); }); + test('restores final primary call details without replaying usage', async () => { + manager = createInMemoryManager(); + const streamId = `context-call-resume-${Date.now()}`; + await manager.createJob(streamId, 'user-1', streamId); + await manager.emitChunk(streamId, { event: 'on_context_usage', data: makeSnapshot(9000) }); + const primary = { + runId: 'run-1', + 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); - 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, - }); - 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; type DeclaredIn = [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, 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 = [ 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; /** 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; }; /** 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 | undefined => { + if (value == null || typeof value !== 'object' || Array.isArray(value)) { + return undefined; + } + const scaled: Record = 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 { - ...snapshot, - breakdown: { ...breakdown, messageTokens }, - remainingContextTokens: - budget != null ? Math.max(0, budget - promptTokens) : snapshot.remainingContextTokens, + 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: 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,