Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🧮 refactor: Move Token Usage Math Into the Chat Package (#17106)
Marco Beretta86c2ac7dcea5
diff --git a/client/src/components/Chat/Input/TokenUsage/store.ts b/client/src/components/Chat/Input/TokenUsage/store.tsindex 20c6fa2b66..ae2cc1c785 100644--- a/client/src/components/Chat/Input/TokenUsage/store.ts+++ b/client/src/components/Chat/Input/TokenUsage/store.ts@@ -1,8 +1,8 @@import { atomFamily } from 'jotai/utils';import { atom, getDefaultStore } from 'jotai';+import { EMPTY_BRANCH, EMPTY_USAGE, EMPTY_USAGE_TOTALS } from '@librechat/chat';+import type { BranchTotals, BranchUsage, ContextSnapshot, UsageTotals } from '@librechat/chat';import type { TMessage, TContextUsageEvent } from 'librechat-data-provider';-import type { BranchTotals, BranchUsage } from '~/utils/tokens';-import { EMPTY_BRANCH, EMPTY_USAGE } from '~/utils/tokens';import { createStorageAtom } from '~/store/jotai-utils';/** Sticky preference: does the context popover open with the breakdown showing?@@ -12,45 +12,8 @@ export const contextBreakdownExpandedAtom = createStorageAtom<boolean>(false,);-/** Latest backend context snapshot, anchored to the run's user message for staleness checks */-export interface ContextSnapshot extends TContextUsageEvent {- anchorMessageId: string | null;- /** Response owning a live snapshot; user-message anchors are shared by siblings. */- responseMessageId?: string | null;- /** Output tokens finalized after this pre-call snapshot (the last call's response) */- completedOutputTokens?: number;-}--/**- * In-flight usage for the streaming response only — a single-response pending- * holder. `foldUsage` accumulates the current response's `on_token_usage`- * events here; `finalizeUsage` flushes it into the per-message index and resets- * it. Branch/total figures are otherwise derived by summing the index, so this- * is the only live add (counted exactly once at finalize).- */-export interface UsageTotals {- input: number;- output: number;- cacheWrite: number;- cacheRead: number;- eventCount: number;- /** Summed authoritative per-event cost from the backend (premium tiers,- * cache rates). Populated only when `interface.contextCost` is enabled. */- costUSD: number;- /** Whether cost coverage is complete — every folded event carried a cost- * (ANDed, vacuously true when empty); gates the cost row. */- costKnown: boolean;-}--export const EMPTY_USAGE_TOTALS: UsageTotals = {- input: 0,- output: 0,- cacheWrite: 0,- cacheRead: 0,- eventCount: 0,- costUSD: 0,- costKnown: true,-};+export type { ContextSnapshot, UsageTotals } from '@librechat/chat';+export { EMPTY_USAGE_TOTALS } from '@librechat/chat';/*** Split into small per-conversation atoms so high-frequency writes (livediff --git a/client/src/hooks/Chat/useTokenUsage.ts b/client/src/hooks/Chat/useTokenUsage.tsindex 87cccb3a33..14d6ea5eed 100644--- a/client/src/hooks/Chat/useTokenUsage.ts+++ b/client/src/hooks/Chat/useTokenUsage.ts@@ -2,12 +2,10 @@ import { useEffect, useMemo, useRef } from 'react';import { useQueryClient } from '@tanstack/react-query';import { useStore, useAtomValue, useSetAtom } from 'jotai';import { Constants, QueryKeys } from 'librechat-data-provider';-import type { TMessage, TConversation, TModelTokenomics } from 'librechat-data-provider';-import type { ContextSnapshot } from '~/components/Chat/Input/TokenUsage/store';-import type { BranchTotals, BranchUsage } from '~/utils/tokens';+import { deriveTokenUsageView, pendingToBranchUsage } from '@librechat/chat';+import type { TMessage, TConversation } from 'librechat-data-provider';+import type { TokenUsageView } from '@librechat/chat';import {- overheadKey,- getModelOverhead,liveTokensFamily,totalUsageFamily,removeUsageAtoms,@@ -17,6 +15,8 @@ import {subagentUsageFamily,pendingSubagentUsageFamily,branchTotalsFamily,+ overheadKey,+ getModelOverhead,contextSnapshotFamily,snapshotsByAnchorFamily,} from '~/components/Chat/Input/TokenUsage/store';@@ -27,80 +27,19 @@ import {clearIndex,mergeUsage,sumTotalUsage,- prunedBranchTokens,- collectAnchorSeries,- snapshotConfiguration,- latestExchangeTokens,findBranchSnapshotAnchor,- normalizeTokenCount,} from '~/utils';import { useLatestMessageId } from '~/hooks/Messages/useLatestMessage';import useTokenLimits from './useTokenLimits';+export type { TokenUsageView };+export interface TokenUsageParams {index: number;conversation: TConversation | null;isSubmitting: boolean;}-export interface TokenUsageView {- usedTokens: number;- maxTokens?: number;- /** 0–100, clamped; 0 when max is unknown */- percent: number;- /** True when derived from per-message counts instead of a backend snapshot */- isEstimate: boolean;- snapshot: ContextSnapshot | null;- snapshotActive: boolean;- branchTotals: BranchTotals;- /** Provider usage along the active branch (matches the gauge), incl. in-flight */- branchUsage: BranchUsage;- /** Provider usage across all branches of the conversation */- totalUsage: BranchUsage;- /** Usage of the selected response, or completed calls in the in-flight turn. */- lastTurnUsage?: BranchUsage;- /** Distinguishes incomplete in-flight usage from a completed saved turn. */- turnInProgress: boolean;- /** Whether any usage is available to display (branch has token usage) */- hasUsage: boolean;- /** Authoritative branch cost; the cost row is gated on `interface.contextCost` at render */- branchCost: number;- /** Authoritative cost across all branches (shown when it differs from branch) */- totalCost: number;- liveTokens: number;- /** Estimated tokens for count-less messages (in-flight tail excluded while- * streaming); 0 on snapshots. Rendered as its own breakdown row. */- estimatedTokens: number;- /** Cached instruction + tool overhead applied to a snapshot-less estimate; 0 on- * snapshots (which carry their own breakdown) and until the agent has run. */- overheadTokens: number;- /** Final message-token portion of a snapshot-less estimate (pruned when over- * window, excludes live); 0 on snapshots. */- messageTokens: number;- /** 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, plus retained post-snapshot tool results; the clamped- * branch walk share on the estimate path. Undefined when the producing SDK- * doesn't report it (older snapshots) or the estimate is zero — the row stays- * hidden. */- toolCallTokens?: number;- /** Cache split of the reconciling call's prompt (live or persisted) — a- * share of the used context, not an addition. */- cacheRead?: number;- cacheWrite?: number;- /** Per-tool result-token counts, when provided by the usage snapshot */- toolMessageTokenCounts?: Record<string, number>;- /** Turns of headroom at the current per-call growth (undefined when unknown) */- runwayTurns?: number;- /** Tokens a summarization could reclaim ≈ context − latest exchange */- compactionReclaim?: number;- /** Live subagent model-call usage — a subset of Totals */- subagentUsage?: BranchUsage;- rates?: TModelTokenomics;-}-/*** View-model for the context usage indicator. Mount only inside the* indicator so its subscriptions never re-render the chat tree.@@ -155,25 +94,10 @@ export default function useTokenUsage({}, [conversationKey, branchTotals.tailId, snapshotsByAnchor]);/** Branch/total provider usage is index-derived; the in-flight response is- * the only live add (the pending holder), counted into both — it sits on the+ * the only live add (the pending holder), counted into both, it sits on the* active branch tail and inside the conversation. The backend prices each* call (premium tiers, cache rates), so cost sums authoritatively. */- const pendingAsUsage: BranchUsage = useMemo(- () => ({- 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],- );+ const pendingAsUsage = useMemo(() => pendingToBranchUsage(pendingUsage), [pendingUsage]);const branchUsage = useMemo(() => (turnInProgress ? mergeUsage(branchTotals.usage, pendingAsUsage) : branchTotals.usage),[branchTotals.usage, pendingAsUsage, turnInProgress],@@ -274,292 +198,49 @@ export default function useTokenUsage({[conversationKey],);- return useMemo(() => {- /** The granular snapshot is for one specific generation. Show the live one- * while streaming, or when its (response-message) anchor is on the viewed- * branch. A null-anchor snapshot must NOT match every branch — that leaked- * one branch's breakdown onto its siblings. */- const currentActive =- snapshot != null &&- (isSubmitting- ? turnInProgress && snapshot.responseMessageId === activeResponseId- : snapshot.anchorMessageId != null &&- branchTotals.containsAnchor &&- (snapshot.responseMessageId == null ||- snapshot.anchorMessageId === snapshot.responseMessageId));-- /** Precedence: live/active snapshot → persisted branch snapshot →- * per-message estimate. The first two are authoritative (real runs with the- * feature on); the estimate covers snapshot-less branches (pre-feature- * 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, any retained tool result, and any in-flight- * output. All already ate that headroom (`usedTokens` adds them), so the- * projection must too. */- const completedOutput = normalizeTokenCount(effective?.completedOutputTokens);- const retainedToolTokens = normalizeTokenCount(effective?.retainedToolTokens);- const liveOutput = turnInProgress ? normalizeTokenCount(liveTokens) : 0;- const remainingForRunway =- effective?.remainingContextTokens != null- ? Math.max(- 0,- normalizeTokenCount(effective.remainingContextTokens) -- completedOutput -- retainedToolTokens -- 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 = normalizeTokenCount(effective.contextBudget ?? breakdown.maxContextTokens);- const instructionTokens = normalizeTokenCount(- effective.effectiveInstructionTokens ?? breakdown.instructionTokens,- );- const remainingContextTokens =- effective.remainingContextTokens != null- ? normalizeTokenCount(effective.remainingContextTokens)- : null;- const breakdownUsed =- instructionTokens +- normalizeTokenCount(breakdown.summaryTokens) +- normalizeTokenCount(breakdown.messageTokens);- /** A remaining count measured against a smaller instruction total than the- * snapshot publishes would put used below the instruction and summary- * shares the breakdown subtracts, hiding the Messages row. */- const baseUsed =- remainingContextTokens != null- ? Math.max(maxTokens - remainingContextTokens, breakdownUsed)- : breakdownUsed;- /** The snapshot is pre-invoke: in-flight output rides on `liveTokens` (0- * unless streaming this branch), the last call's finalized output on- * `completedOutputTokens`, and retained tool results on- * `retainedToolTokens`. */- const usedTokens = normalizeTokenCount(- Math.max(0, baseUsed) + liveOutput + completedOutput + retainedToolTokens,- );- return {- usedTokens,- maxTokens,- percent: maxTokens > 0 ? Math.min((usedTokens / maxTokens) * 100, 100) : 0,- isEstimate: false,- snapshot: effective,- snapshotActive: true,+ return useMemo(+ () =>+ deriveTokenUsageView({+ snapshot,+ isSubmitting,+ turnInProgress,+ activeResponseId,branchTotals,branchUsage,totalUsage,lastTurnUsage,- turnInProgress,hasUsage,- branchCost: branchUsage.cost,- totalCost: totalUsage.cost,- liveTokens: liveOutput,- estimatedTokens: 0,- overheadTokens: 0,- messageTokens: 0,- messagesPruned: false,- /** Retained tool results sit outside `messageTokens`, so widen the- * reported tool-call share without clipping it back to that pre-invoke- * total. Keep older snapshots unsplit when no split was reported. */- toolCallTokens:- breakdown.toolMessageTokens != null- ? Math.min(- normalizeTokenCount(breakdown.toolMessageTokens),- normalizeTokenCount(breakdown.messageTokens),- ) + retainedToolTokens- : undefined,- cacheRead: normalizeTokenCount(effective.cacheRead),- cacheWrite: normalizeTokenCount(effective.cacheWrite),- 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. A retained tool result is added for the same reason: the kept- * exchange counts it, so leaving it out of the total would subtract- * content that was never in it and understate the savings — on a large- * final result, down to zero. While a response streams, `completedOutput`- * is 0 and the in-flight tail is excluded from both sides (it rides on- * `liveTokens`). */- compactionReclaim: Math.max(- 0,- normalizeTokenCount(breakdown.messageTokens) +- completedOutput +- retainedToolTokens -- latestExchangeTokens(- conversationKey,- tailId,- liveOutput > 0,- normalizeTokenCount(breakdown.summaryTokens),- ),- ),+ liveTokens,+ limits,+ branchSnapshot,+ snapshotsByAnchor,subagentUsage,- rates: limits.rates,- };- }-- /** Snapshot-less estimate, computed from the in-memory message index — no- * server round-trip. All terms are local per-message counts / char estimates- * (uncalibrated): the learned calibration ratio reconciles provider-injected- * context that isn't present in this visible text, so applying it here would- * over-inflate. `summaryBaseline` is the compacted-context size from the- * deepest summarized response on the branch (0 if none); the walk stops- * 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 != null ? normalizeTokenCount(limits.maxContextTokens) : undefined;- const liveOnTail = liveOutput > 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- * the prune budget and add it to used — making over-window pruning faithful and- * the gauge consistent with snapshots. Skipped when a summary baseline exists:- * `computeSummaryUsedTokens` already folds the overhead into that marker, so- * adding it again would double-count. 0 until the agent has run once this- * session (then falls back to message-only, as before). */- const overheadTokens =- branchTotals.summaryBaseline > 0- ? 0- : 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- * by `liveTokens`; drop its static estimate so a resumed/partial response- * isn't double-counted on the estimate path. */- const estimatedTokens = Math.max(- 0,- normalizeTokenCount(branchTotals.estTokens) -- (liveOnTail ? normalizeTokenCount(branchTotals.tailEstTokens) : 0),- );- 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- * (max minus the always-sent summary baseline and instruction overhead), report- * 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 - normalizeTokenCount(branchTotals.summaryBaseline) - overheadTokens,- );- if (messageTokens > messageBudget) {- 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. */- const messagesPruned = messageTokens < rawMessageTokens;- const compactionReclaim = Math.max(- 0,- messageTokens - latestExchangeTokens(conversationKey, branchTotals.tailId, liveOnTail),- );- const usedTokens = normalizeTokenCount(- overheadTokens +- normalizeTokenCount(branchTotals.summaryBaseline) +- messageTokens +- liveOutput,- );- return {- usedTokens,- maxTokens,- percent:- maxTokens != null && maxTokens > 0 ? Math.min((usedTokens / maxTokens) * 100, 100) : 0,- isEstimate: true,- snapshot: null,- snapshotActive: false,+ conversationKey,+ modelOverhead: getModelOverhead(+ overheadKey(+ limits.endpoint ?? conversation?.endpoint,+ limits.model ?? conversation?.model,+ conversation?.agent_id,+ ),+ ),+ }),+ [+ snapshot,+ isSubmitting,+ turnInProgress,+ activeResponseId,branchTotals,branchUsage,totalUsage,lastTurnUsage,- turnInProgress,hasUsage,- branchCost: branchUsage.cost,- totalCost: totalUsage.cost,- liveTokens: liveOutput,- estimatedTokens,- overheadTokens,- messageTokens,- messagesPruned,- toolCallTokens: toolTokens > 0 ? toolTokens : undefined,- compactionReclaim,+ liveTokens,+ limits,+ branchSnapshot,+ snapshotsByAnchor,subagentUsage,- rates: limits.rates,- };- }, [- snapshot,- isSubmitting,- turnInProgress,- activeResponseId,- branchTotals,- branchUsage,- totalUsage,- lastTurnUsage,- hasUsage,- liveTokens,- limits,- branchSnapshot,- snapshotsByAnchor,- subagentUsage,- conversationKey,- conversation,- ]);+ conversationKey,+ conversation,+ ],+ );}diff --git a/client/src/hooks/SSE/usage/__tests__/handlers.spec.ts b/client/src/hooks/SSE/usage/__tests__/handlers.spec.tsnew file mode 100644index 0000000000..059ffe3a4c--- /dev/null+++ b/client/src/hooks/SSE/usage/__tests__/handlers.spec.ts@@ -0,0 +1,48 @@+import { createStore } from 'jotai';+import type { TTokenUsageEvent } from 'librechat-data-provider';+import type { UsageSubmissionLike } from '../events';+import {+ pendingUsageFamily,+ liveTokensFamily,+ activeUsageResponseIdFamily,+} from '~/components/Chat/Input/TokenUsage/store';+import { createUsageCounters, createUsageHandlers } from '../handlers';++const submission: UsageSubmissionLike = {+ userMessage: { messageId: 'u1', conversationId: 'c1' },+ initialResponse: { messageId: 'r1', parentMessageId: 'u1' },+ conversation: { conversationId: 'c1' },+};++const usage = (fields: Partial<TTokenUsageEvent>): TTokenUsageEvent =>+ ({ runId: 'run', seq: 0, input_tokens: 10, output_tokens: 5, ...fields }) as TTokenUsageEvent;++describe('createUsageHandlers', () => {+ it('binds the response and folds a usage event exactly once', () => {+ const store = createStore();+ const handlers = createUsageHandlers(store, createUsageCounters());+ handlers.usageHandler(usage({}), submission);+ handlers.usageHandler(usage({}), submission);+ expect(store.get(activeUsageResponseIdFamily('c1'))).toBe('r1');+ expect(store.get(pendingUsageFamily('c1')).eventCount).toBe(1);+ });++ it('resetLive clears pending usage and the live estimate', () => {+ const store = createStore();+ const handlers = createUsageHandlers(store, createUsageCounters());+ handlers.usageHandler(usage({}), submission);+ handlers.resetLive(submission);+ expect(store.get(pendingUsageFamily('c1')).eventCount).toBe(0);+ expect(store.get(liveTokensFamily('c1'))).toBe(0);+ });++ it('keeps separate counters per handler set', () => {+ const store = createStore();+ const counters = createUsageCounters();+ const handlers = createUsageHandlers(store, counters);+ handlers.seedLive(400, submission);+ expect(counters.streamChars).toBe(400);+ expect(store.get(liveTokensFamily('c1'))).toBeGreaterThan(0);+ expect(createUsageCounters().streamChars).toBe(0);+ });+});diff --git a/client/src/hooks/SSE/usage/events.ts b/client/src/hooks/SSE/usage/events.tsnew file mode 100644index 0000000000..df0004478f--- /dev/null+++ b/client/src/hooks/SSE/usage/events.ts@@ -0,0 +1,79 @@+import { Constants } from 'librechat-data-provider';+import type {+ TMessage,+ TConversation,+ TTokenUsageEvent,+ TContextUsageEvent,+} from 'librechat-data-provider';++export const FLUSH_INTERVAL_MS = 250;++export interface UsageSubmissionLike {+ userMessage?: Pick<TMessage, 'messageId' | 'conversationId'> | null;+ initialResponse?: Pick<TMessage, 'messageId' | 'parentMessageId'> | null;+ conversation?: Partial<Pick<TConversation, 'conversationId' | 'endpoint' | 'model'>> | null;+}++export interface FinalDataLike {+ requestMessage?: Partial<TMessage> | null;+ responseMessage?: Partial<TMessage> | null;+ conversation?: Partial<TConversation> | null;+}++export interface UsageHandlers {+ /** Bind an optimistic, created, or resumed response without inventing usage. */+ bindResponse: (submission: UsageSubmissionLike) => string | null;+ contextHandler: (data: TContextUsageEvent, submission: UsageSubmissionLike) => void;+ usageHandler: (data: TTokenUsageEvent, submission: UsageSubmissionLike) => void;+ tapStream: (data: { delta?: { content?: unknown } }, submission: UsageSubmissionLike) => void;+ /** Live estimate for the legacy content path, which streams cumulative+ * (not incremental) text per part, sets rather than accumulates */+ tapContent: (text: unknown, submission: UsageSubmissionLike) => void;+ finalizeUsage: (data: FinalDataLike, submission: UsageSubmissionLike) => void;+ resetLive: (submission: UsageSubmissionLike) => void;+ /** Terminal stop: attribute the in-flight pending usage to the stopped partial+ * response (so its billed tokens aren't dropped), then reset pending so it+ * can't leak into the next response. Discards when no response id is known. */+ attributePending: (responseId: string | null, submission: UsageSubmissionLike) => void;+ /** Idempotently folds the resumed run's collected usage into the totals */+ backfillUsage: (entries: TTokenUsageEvent[], submission: UsageSubmissionLike) => void;+ /** Seeds the live estimate from already-streamed output chars on resume */+ seedLive: (chars: number, submission: UsageSubmissionLike) => void;+}++export function getConvoKey(submission: UsageSubmissionLike): string {+ /** On a new chat's first turn the `created` event stamps the real id onto+ * the user message while the submission's conversation is still `new`;+ * prefer the real id so live writes land where TokenUsage is subscribed */+ const fromUserMessage = submission.userMessage?.conversationId;+ if (fromUserMessage != null && fromUserMessage !== Constants.NEW_CONVO) {+ return fromUserMessage;+ }+ return submission.conversation?.conversationId ?? Constants.NEW_CONVO;+}++/** Cumulative text of a content-path part: a raw string or a `{ value }` part */+export function extractContentText(text: unknown): string {+ if (typeof text === 'string') {+ return text;+ }+ const value = (text as { value?: unknown })?.value;+ return typeof value === 'string' ? value : '';+}++export function countDeltaChars(content: unknown): number {+ const parts = Array.isArray(content) ? content : [content];+ let chars = 0;+ for (const part of parts) {+ if (part == null || typeof part !== 'object') {+ continue;+ }+ const { text, think } = part as { text?: unknown; think?: unknown };+ if (typeof text === 'string') {+ chars += text.length;+ } else if (typeof think === 'string') {+ chars += think.length;+ }+ }+ return chars;+}diff --git a/client/src/hooks/SSE/usage/handlers.ts b/client/src/hooks/SSE/usage/handlers.tsnew file mode 100644index 0000000000..2c2b0a935f--- /dev/null+++ b/client/src/hooks/SSE/usage/handlers.ts@@ -0,0 +1,488 @@+import { Constants, reconcileContextUsageFromEvent } from 'librechat-data-provider';+import type { TTokenUsageEvent, TContextUsageEvent } from 'librechat-data-provider';+import type { getDefaultStore } from 'jotai';+import type { ContextSnapshot } from '~/components/Chat/Input/TokenUsage/store';+import type { UsageHandlers, UsageSubmissionLike } from './events';+import {+ overheadKey,+ markUsageFolded,+ migrateUsageFolded,+ liveTokensFamily,+ totalUsageFamily,+ removeUsageAtoms,+ setModelOverhead,+ clearUsageFolded,+ calibrationFamily,+ pendingUsageFamily,+ activeUsageResponseIdFamily,+ branchTotalsFamily,+ subagentUsageFamily,+ pendingSubagentUsageFamily,+ EMPTY_USAGE_TOTALS,+ contextSnapshotFamily,+ snapshotsByAnchorFamily,+} from '~/components/Chat/Input/TokenUsage/store';+import {+ sumBranch,+ mergeUsage,+ EMPTY_USAGE,+ setEntryUsage,+ upsertEntries,+ migrateIndex,+ sumTotalUsage,+ estimateTokens,+ normalizeUsageUnits,+} from '~/utils';+import { FLUSH_INTERVAL_MS, getConvoKey, extractContentText, countDeltaChars } from './events';++export type { UsageHandlers };++export interface UsageCounters {+ /** Streamed chars since the last snapshot or model end (current call only) */+ streamChars: number;+ /** Provider-confirmed output tokens since the last snapshot (current run) */+ confirmed: number;+ lastFlush: number;+}++export const createUsageCounters = (): UsageCounters => ({+ streamChars: 0,+ confirmed: 0,+ lastFlush: 0,+});++/**+ * Imperative writers for the per-conversation token usage atoms, driven by SSE events. The+ * handlers close over `jotai` and `counters` only, so they never cause re-renders themselves.+ */+export function createUsageHandlers(+ jotai: ReturnType<typeof getDefaultStore>,+ counters: UsageCounters,+): UsageHandlers {+ let liveConversationKey: string | null = null;+ /** Some terminal callbacks retain the original unsaved submission after+ * CREATED has already moved its state. Never move an empty `new` bucket+ * back over the live conversation in those callbacks. */+ const resolveUsageKey = (submission: UsageSubmissionLike) => {+ const key = getConvoKey(submission);+ return key === Constants.NEW_CONVO && liveConversationKey != null ? liveConversationKey : key;+ };+ const moveConversation = (from: string, to: string) => {+ if (from === to) {+ return;+ }+ migrateIndex(from, to);+ migrateUsageFolded(from, to);+ jotai.set(contextSnapshotFamily(to), jotai.get(contextSnapshotFamily(from)));+ jotai.set(snapshotsByAnchorFamily(to), jotai.get(snapshotsByAnchorFamily(from)));+ jotai.set(pendingUsageFamily(to), jotai.get(pendingUsageFamily(from)));+ jotai.set(activeUsageResponseIdFamily(to), jotai.get(activeUsageResponseIdFamily(from)));+ jotai.set(liveTokensFamily(to), jotai.get(liveTokensFamily(from)));+ jotai.set(branchTotalsFamily(to), jotai.get(branchTotalsFamily(from)));+ jotai.set(totalUsageFamily(to), sumTotalUsage(to));+ jotai.set(calibrationFamily(to), jotai.get(calibrationFamily(from)));+ jotai.set(subagentUsageFamily(to), jotai.get(subagentUsageFamily(from)));+ jotai.set(pendingSubagentUsageFamily(to), jotai.get(pendingSubagentUsageFamily(from)));+ // Atom-family eviction alone does not notify a still-mounted /c/new view.+ jotai.set(activeUsageResponseIdFamily(from), null);+ jotai.set(pendingUsageFamily(from), EMPTY_USAGE_TOTALS);+ jotai.set(liveTokensFamily(from), 0);+ removeUsageAtoms(from);+ liveConversationKey = to;+ };++ /** The transport owns response-id normalization. Use the same response it+ * renders, including durable IDs assigned by legacy text and resume events. */+ const bindResponse: UsageHandlers['bindResponse'] = (submission) => {+ const convoKey = getConvoKey(submission);+ if (liveConversationKey === Constants.NEW_CONVO && convoKey !== liveConversationKey) {+ moveConversation(liveConversationKey, convoKey);+ }+ liveConversationKey = convoKey;+ const responseId = submission.initialResponse?.messageId ?? null;+ const ownerAtom = activeUsageResponseIdFamily(convoKey);+ const previousId = jotai.get(ownerAtom);+ jotai.set(ownerAtom, responseId);+ /** A server ID remap doesn't invalidate this turn's pending usage or its+ * live context. Only move a snapshot owned by the previous response. */+ const snapshotAtom = contextSnapshotFamily(convoKey);+ const snapshot = jotai.get(snapshotAtom);+ if (+ previousId != null &&+ responseId != null &&+ previousId !== responseId &&+ snapshot?.responseMessageId === previousId+ ) {+ jotai.set(snapshotAtom, { ...snapshot, responseMessageId: responseId });+ }+ return responseId;+ };++ const setLive = (convoKey: string, value: number) => {+ jotai.set(liveTokensFamily(convoKey), value);+ };++ /** Settle observed usage and clear live state. Pending supplies a response+ * rollup only when the server supplied none (legacy FINAL or local stop).+ * Session-only subagent usage still settles once, independently of which+ * source supplied the whole-turn rollup. */+ const flushPendingInto = (+ convoKey: string,+ responseId: string | null,+ hasPersistedUsage = false,+ ) => {+ const pendingAtom = pendingUsageFamily(convoKey);+ const pending = jotai.get(pendingAtom);+ const keep = responseId != null && pending.eventCount > 0;+ /** FINAL's persisted rollup covers the whole run; this subscriber may+ * have observed only the last calls. Pending is a legacy/stop fallback,+ * never a replacement for the response just upserted from the server. */+ if (keep && !hasPersistedUsage) {+ setEntryUsage(convoKey, responseId, {+ input: pending.input,+ output: pending.output,+ cacheWrite: pending.cacheWrite,+ cacheRead: pending.cacheRead,+ cost: pending.costUSD,+ 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);+ jotai.set(activeUsageResponseIdFamily(convoKey), null);+ };++ const contextHandler: UsageHandlers['contextHandler'] = (data, submission) => {+ const responseMessageId = bindResponse(submission);+ const convoKey = resolveUsageKey(submission);+ jotai.set(contextSnapshotFamily(convoKey), {+ ...data,+ completedOutputTokens: data.resumedOutputTokens ?? data.completedOutputTokens,+ anchorMessageId: submission.userMessage?.messageId ?? null,+ responseMessageId,+ });+ if (data.calibrationRatio != null && data.calibrationRatio > 0) {+ jotai.set(calibrationFamily(convoKey), data.calibrationRatio);+ }+ /** Cache the fixed instruction+tool overhead (already inclusive of tool+ * schemas) per agent/model so a snapshot-less branch of the same config can+ * reserve it in its prune budget and gauge. */+ const overhead = data.effectiveInstructionTokens ?? data.breakdown?.instructionTokens ?? 0;+ setModelOverhead(+ overheadKey(submission.conversation?.endpoint, submission.conversation?.model, data.agentId),+ overhead,+ );+ counters.streamChars = 0;+ counters.confirmed = 0;+ setLive(convoKey, 0);+ };++ /** Folds one usage event into the in-flight pending holder exactly once per+ * conversation. Returns false when the event was already counted (live then+ * replayed on resume), so callers can skip the live-estimate bump too.+ * `finalizeUsage` flushes the accumulated pending into the per-message index+ * and resets it, so branch/total stay index-derived (no double count). */+ const foldUsage = (data: TTokenUsageEvent, submission: UsageSubmissionLike): boolean => {+ bindResponse(submission);+ const convoKey = resolveUsageKey(submission);+ /** runId+seq is unique per model call; fall back to the payload when a+ * source predates the sequence tag */+ const usageKey =+ data.runId != null && data.seq != null ? `${data.runId}:${data.seq}` : JSON.stringify(data);+ if (!markUsageFolded(convoKey, usageKey)) {+ return false;+ }++ /** 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);+ jotai.set(pendingAtom, {+ input: prev.input + units.input,+ output: prev.output + units.output,+ cacheWrite: prev.cacheWrite + units.cacheWrite,+ cacheRead: prev.cacheRead + units.cacheRead,+ 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 + cost,+ /** Coverage is complete only if EVERY folded event carried a cost */+ 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;+ };++ /** Reconcile the live snapshot's calibrated estimate to a primary call's+ * ACTUAL prompt tokens. The snapshot is pre-invoke for that call; this usage+ * is its post-invoke truth, so the gauge stops showing the SDK multiplier's+ * inflation (severe when a provider injects server-side content like web+ * search). Resume is handled server-side (the job-store snapshot is reconciled+ * when the call's usage is persisted), so no backfill reconcile is needed. */+ const reconcileLiveSnapshot = (data: TTokenUsageEvent, submission: UsageSubmissionLike) => {+ const convoKey = resolveUsageKey(submission);+ const snapshotAtom = contextSnapshotFamily(convoKey);+ const snapshot = jotai.get(snapshotAtom);+ if (snapshot == null) {+ return;+ }+ /** The snapshot precedes this call, so it must belong to the same run */+ if (snapshot.runId != null && data.runId != null && snapshot.runId !== data.runId) {+ return;+ }+ 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) => {+ const folded = foldUsage(data, submission);++ /** Only a NEWLY folded primary call drives the live gauge. A replayed+ * duplicate (folded=false on resume) can be an EARLIER tool-loop call that+ * shares this run's id, reconciling with it would overwrite the latest+ * snapshot with an earlier, smaller prompt. Tagged buckets (summarization,+ * subagent) never touch the context gauge. */+ if (!folded || data.usage_type != null) {+ return;+ }+ /** This primary's provider-reported prompt is the post-invoke truth for the+ * call the latest snapshot precedes, reconcile the gauge to it. */+ reconcileLiveSnapshot(data, submission);+ /** Use the repaired completion count (not raw output_tokens) so the+ * snapshot gauge keeps the full response for under-reporting providers */+ counters.confirmed += normalizeUsageUnits(data).output;+ counters.streamChars = 0;+ setLive(resolveUsageKey(submission), counters.confirmed);+ };++ const tapStream: UsageHandlers['tapStream'] = (data, submission) => {+ bindResponse(submission);+ const chars = countDeltaChars(data?.delta?.content);+ if (chars <= 0) {+ return;+ }+ counters.streamChars += chars;+ const now = Date.now();+ if (now - counters.lastFlush < FLUSH_INTERVAL_MS) {+ return;+ }+ counters.lastFlush = now;+ const convoKey = resolveUsageKey(submission);+ const ratio = jotai.get(calibrationFamily(convoKey));+ setLive(convoKey, counters.confirmed + estimateTokens(counters.streamChars, ratio));+ };++ const tapContent: UsageHandlers['tapContent'] = (text, submission) => {+ bindResponse(submission);+ const value = extractContentText(text);+ if (value.length === 0) {+ return;+ }+ /** Cumulative per part, replace the running char count, don't add */+ counters.streamChars = value.length;+ const now = Date.now();+ if (now - counters.lastFlush < FLUSH_INTERVAL_MS) {+ return;+ }+ counters.lastFlush = now;+ const convoKey = resolveUsageKey(submission);+ const ratio = jotai.get(calibrationFamily(convoKey));+ setLive(convoKey, counters.confirmed + estimateTokens(counters.streamChars, ratio));+ };++ const resetLive: UsageHandlers['resetLive'] = (submission) => {+ counters.streamChars = 0;+ counters.confirmed = 0;+ const convoKey = resolveUsageKey(submission);+ setLive(convoKey, 0);+ /** Terminal path with no salvageable response (stream error / intentional+ * 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(activeUsageResponseIdFamily(convoKey), null);+ jotai.set(pendingSubagentUsageFamily(convoKey), EMPTY_USAGE);+ clearUsageFolded(convoKey);+ };++ /** Both local stop and FINAL retain the same branch-owned context. Capture+ * output from refs before resetting live state, including throttled text.+ * Never promote a snapshot from a different response sharing the user. */+ const retainSnapshot = (+ convoKey: string,+ responseId: string | null,+ userMsgId: string | null,+ output: number,+ retainedToolTokens?: number,+ ) => {+ if (responseId == null) {+ return;+ }+ const snapshotAtom = contextSnapshotFamily(convoKey);+ const snapshot = jotai.get(snapshotAtom);+ if (+ snapshot == null ||+ (snapshot.responseMessageId != null+ ? snapshot.responseMessageId !== responseId+ : snapshot.anchorMessageId !== userMsgId)+ ) {+ return;+ }+ const retained: ContextSnapshot = {+ ...snapshot,+ anchorMessageId: responseId,+ responseMessageId: responseId,+ ...(output > 0 && { completedOutputTokens: output }),+ ...(retainedToolTokens != null &&+ Number.isFinite(retainedToolTokens) &&+ retainedToolTokens > 0 && { retainedToolTokens }),+ };+ jotai.set(snapshotAtom, retained);+ const historyAtom = snapshotsByAnchorFamily(convoKey);+ const next = new Map(jotai.get(historyAtom));+ next.set(responseId, retained);+ jotai.set(historyAtom, next);+ };++ const attributePending: UsageHandlers['attributePending'] = (responseId, submission) => {+ const convoKey = resolveUsageKey(submission);+ retainSnapshot(+ convoKey,+ responseId,+ submission.userMessage?.messageId ?? null,+ counters.confirmed ++ estimateTokens(counters.streamChars, jotai.get(calibrationFamily(convoKey))),+ );+ /** Flush the billed-but-uncommitted usage onto the stopped partial reply+ * (when its id is known and events were folded), then reset pending and+ * the live estimate. Index-derived branch/total then reflect it. */+ flushPendingInto(convoKey, responseId);+ if (responseId != null) {+ jotai.set(branchTotalsFamily(convoKey), sumBranch(convoKey, responseId, responseId));+ jotai.set(totalUsageFamily(convoKey), sumTotalUsage(convoKey));+ }+ counters.streamChars = 0;+ counters.confirmed = 0;+ setLive(convoKey, 0);+ };++ const backfillUsage: UsageHandlers['backfillUsage'] = (entries, submission) => {+ bindResponse(submission);+ /** Fold the resumed run's persisted events idempotently, never reset+ * the conversation totals, or a reconnect mid-stream would drop the+ * usage of prompts already completed earlier in the session */+ for (const entry of entries) {+ foldUsage(entry, submission);+ }+ };++ const seedLive: UsageHandlers['seedLive'] = (chars, submission) => {+ bindResponse(submission);+ const convoKey = resolveUsageKey(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;+ }+ counters.streamChars = chars;+ counters.confirmed = 0;+ setLive(convoKey, estimateTokens(chars, jotai.get(calibrationFamily(convoKey))));+ };++ const finalizeUsage: UsageHandlers['finalizeUsage'] = (data, submission) => {+ const fromKey = resolveUsageKey(submission);+ const realId = data.conversation?.conversationId ?? fromKey;+ /** From the refs, not the atom, the throttle may not have flushed */+ const liveAtFinalize =+ counters.confirmed ++ estimateTokens(counters.streamChars, jotai.get(calibrationFamily(fromKey)));++ upsertEntries(fromKey, [data.requestMessage, data.responseMessage]);++ moveConversation(fromKey, realId);++ const responseMeta = data.responseMessage?.contextMeta;+ if (responseMeta?.calibrationRatio != null && responseMeta.calibrationRatio > 0) {+ jotai.set(calibrationFamily(realId), responseMeta.calibrationRatio);+ }++ const userMsgId = submission.userMessage?.messageId ?? null;+ const responseId = data.responseMessage?.messageId ?? null;++ /** Flush the in-flight response's pending usage into its index entry, then+ * reset pending. Branch/total are summed from the index, so this single+ * add is counted exactly once; the persisted `metadata.usage` reproduces+ * it on reload. */+ flushPendingInto(realId, responseId, data.responseMessage?.metadata?.usage != null);++ const tailId = responseId ?? data.requestMessage?.messageId ?? null;+ if (tailId) {+ jotai.set(branchTotalsFamily(realId), sumBranch(realId, tailId, responseId ?? userMsgId));+ }+ jotai.set(totalUsageFamily(realId), sumTotalUsage(realId));++ retainSnapshot(+ realId,+ responseId,+ userMsgId,+ liveAtFinalize,+ (data.responseMessage?.metadata?.contextUsage as TContextUsageEvent | undefined)+ ?.retainedToolTokens,+ );++ counters.streamChars = 0;+ counters.confirmed = 0;+ setLive(realId, 0);+ };++ return {+ bindResponse,+ contextHandler,+ usageHandler,+ tapStream,+ tapContent,+ finalizeUsage,+ resetLive,+ attributePending,+ backfillUsage,+ seedLive,+ };+}diff --git a/client/src/hooks/SSE/useUsageHandler.ts b/client/src/hooks/SSE/useUsageHandler.tsindex cd0d95b616..13f9ebd4f2 100644--- a/client/src/hooks/SSE/useUsageHandler.ts+++ b/client/src/hooks/SSE/useUsageHandler.ts@@ -1,560 +1,15 @@import { useRef, useMemo } from 'react';import { getDefaultStore } from 'jotai';-import { Constants, reconcileContextUsageFromEvent } from 'librechat-data-provider';-import type {- TMessage,- TConversation,- TTokenUsageEvent,- TContextUsageEvent,-} from 'librechat-data-provider';-import type { ContextSnapshot } from '~/components/Chat/Input/TokenUsage/store';-import {- overheadKey,- markUsageFolded,- migrateUsageFolded,- liveTokensFamily,- totalUsageFamily,- removeUsageAtoms,- setModelOverhead,- clearUsageFolded,- calibrationFamily,- pendingUsageFamily,- activeUsageResponseIdFamily,- branchTotalsFamily,- subagentUsageFamily,- pendingSubagentUsageFamily,- EMPTY_USAGE_TOTALS,- contextSnapshotFamily,- snapshotsByAnchorFamily,-} from '~/components/Chat/Input/TokenUsage/store';-import {- sumBranch,- mergeUsage,- EMPTY_USAGE,- setEntryUsage,- upsertEntries,- migrateIndex,- sumTotalUsage,- estimateTokens,- normalizeUsageUnits,-} from '~/utils';+import type { UsageHandlers } from '~/hooks/SSE/usage/handlers';+import { createUsageCounters, createUsageHandlers } from '~/hooks/SSE/usage/handlers';-const FLUSH_INTERVAL_MS = 250;--interface UsageSubmissionLike {- userMessage?: Pick<TMessage, 'messageId' | 'conversationId'> | null;- initialResponse?: Pick<TMessage, 'messageId' | 'parentMessageId'> | null;- conversation?: Partial<Pick<TConversation, 'conversationId' | 'endpoint' | 'model'>> | null;-}--interface FinalDataLike {- requestMessage?: Partial<TMessage> | null;- responseMessage?: Partial<TMessage> | null;- conversation?: Partial<TConversation> | null;-}--export interface UsageHandlers {- /** Bind an optimistic, created, or resumed response without inventing usage. */- bindResponse: (submission: UsageSubmissionLike) => string | null;- contextHandler: (data: TContextUsageEvent, submission: UsageSubmissionLike) => void;- usageHandler: (data: TTokenUsageEvent, submission: UsageSubmissionLike) => void;- tapStream: (data: { delta?: { content?: unknown } }, submission: UsageSubmissionLike) => void;- /** Live estimate for the legacy content path, which streams cumulative- * (not incremental) text per part — sets rather than accumulates */- tapContent: (text: unknown, submission: UsageSubmissionLike) => void;- finalizeUsage: (data: FinalDataLike, submission: UsageSubmissionLike) => void;- resetLive: (submission: UsageSubmissionLike) => void;- /** Terminal stop: attribute the in-flight pending usage to the stopped partial- * response (so its billed tokens aren't dropped), then reset pending so it- * can't leak into the next response. Discards when no response id is known. */- attributePending: (responseId: string | null, submission: UsageSubmissionLike) => void;- /** Idempotently folds the resumed run's collected usage into the totals */- backfillUsage: (entries: TTokenUsageEvent[], submission: UsageSubmissionLike) => void;- /** Seeds the live estimate from already-streamed output chars on resume */- seedLive: (chars: number, submission: UsageSubmissionLike) => void;-}--function getConvoKey(submission: UsageSubmissionLike): string {- /** On a new chat's first turn the `created` event stamps the real id onto- * the user message while the submission's conversation is still `new`;- * prefer the real id so live writes land where TokenUsage is subscribed */- const fromUserMessage = submission.userMessage?.conversationId;- if (fromUserMessage != null && fromUserMessage !== Constants.NEW_CONVO) {- return fromUserMessage;- }- return submission.conversation?.conversationId ?? Constants.NEW_CONVO;-}--/** Cumulative text of a content-path part: a raw string or a `{ value }` part */-function extractContentText(text: unknown): string {- if (typeof text === 'string') {- return text;- }- const value = (text as { value?: unknown })?.value;- return typeof value === 'string' ? value : '';-}--function countDeltaChars(content: unknown): number {- const parts = Array.isArray(content) ? content : [content];- let chars = 0;- for (const part of parts) {- if (part == null || typeof part !== 'object') {- continue;- }- const { text, think } = part as { text?: unknown; think?: unknown };- if (typeof text === 'string') {- chars += text.length;- } else if (typeof think === 'string') {- chars += think.length;- }- }- return chars;-}+export type { UsageHandlers };/**- * Imperative writers for the per-conversation token usage atoms, driven by- * SSE events. All state lives in refs/atoms — the returned handlers are- * stable and never cause re-renders themselves.+ * Stable writers for the per-conversation token usage atoms, driven by SSE events. All state+ * lives in the counters ref and the atoms, so the returned handlers never re-render the caller.*/export default function useUsageHandler(): UsageHandlers {- /** Streamed chars since the last snapshot or model end (current call only) */- const streamCharsRef = useRef(0);- /** Provider-confirmed output tokens since the last snapshot (current run) */- const confirmedRef = useRef(0);- const lastFlushRef = useRef(0);-- return useMemo<UsageHandlers>(() => {- const jotai = getDefaultStore();-- let liveConversationKey: string | null = null;- /** Some terminal callbacks retain the original unsaved submission after- * CREATED has already moved its state. Never move an empty `new` bucket- * back over the live conversation in those callbacks. */- const resolveUsageKey = (submission: UsageSubmissionLike) => {- const key = getConvoKey(submission);- return key === Constants.NEW_CONVO && liveConversationKey != null ? liveConversationKey : key;- };- const moveConversation = (from: string, to: string) => {- if (from === to) {- return;- }- migrateIndex(from, to);- migrateUsageFolded(from, to);- jotai.set(contextSnapshotFamily(to), jotai.get(contextSnapshotFamily(from)));- jotai.set(snapshotsByAnchorFamily(to), jotai.get(snapshotsByAnchorFamily(from)));- jotai.set(pendingUsageFamily(to), jotai.get(pendingUsageFamily(from)));- jotai.set(activeUsageResponseIdFamily(to), jotai.get(activeUsageResponseIdFamily(from)));- jotai.set(liveTokensFamily(to), jotai.get(liveTokensFamily(from)));- jotai.set(branchTotalsFamily(to), jotai.get(branchTotalsFamily(from)));- jotai.set(totalUsageFamily(to), sumTotalUsage(to));- jotai.set(calibrationFamily(to), jotai.get(calibrationFamily(from)));- jotai.set(subagentUsageFamily(to), jotai.get(subagentUsageFamily(from)));- jotai.set(pendingSubagentUsageFamily(to), jotai.get(pendingSubagentUsageFamily(from)));- // Atom-family eviction alone does not notify a still-mounted /c/new view.- jotai.set(activeUsageResponseIdFamily(from), null);- jotai.set(pendingUsageFamily(from), EMPTY_USAGE_TOTALS);- jotai.set(liveTokensFamily(from), 0);- removeUsageAtoms(from);- liveConversationKey = to;- };-- /** The transport owns response-id normalization. Use the same response it- * renders, including durable IDs assigned by legacy text and resume events. */- const bindResponse: UsageHandlers['bindResponse'] = (submission) => {- const convoKey = getConvoKey(submission);- if (liveConversationKey === Constants.NEW_CONVO && convoKey !== liveConversationKey) {- moveConversation(liveConversationKey, convoKey);- }- liveConversationKey = convoKey;- const responseId = submission.initialResponse?.messageId ?? null;- const ownerAtom = activeUsageResponseIdFamily(convoKey);- const previousId = jotai.get(ownerAtom);- jotai.set(ownerAtom, responseId);- /** A server ID remap doesn't invalidate this turn's pending usage or its- * live context. Only move a snapshot owned by the previous response. */- const snapshotAtom = contextSnapshotFamily(convoKey);- const snapshot = jotai.get(snapshotAtom);- if (- previousId != null &&- responseId != null &&- previousId !== responseId &&- snapshot?.responseMessageId === previousId- ) {- jotai.set(snapshotAtom, { ...snapshot, responseMessageId: responseId });- }- return responseId;- };-- const setLive = (convoKey: string, value: number) => {- jotai.set(liveTokensFamily(convoKey), value);- };-- /** Settle observed usage and clear live state. Pending supplies a response- * rollup only when the server supplied none (legacy FINAL or local stop).- * Session-only subagent usage still settles once, independently of which- * source supplied the whole-turn rollup. */- const flushPendingInto = (- convoKey: string,- responseId: string | null,- hasPersistedUsage = false,- ) => {- const pendingAtom = pendingUsageFamily(convoKey);- const pending = jotai.get(pendingAtom);- const keep = responseId != null && pending.eventCount > 0;- /** FINAL's persisted rollup covers the whole run; this subscriber may- * have observed only the last calls. Pending is a legacy/stop fallback,- * never a replacement for the response just upserted from the server. */- if (keep && !hasPersistedUsage) {- setEntryUsage(convoKey, responseId, {- input: pending.input,- output: pending.output,- cacheWrite: pending.cacheWrite,- cacheRead: pending.cacheRead,- cost: pending.costUSD,- 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);- jotai.set(activeUsageResponseIdFamily(convoKey), null);- };-- const contextHandler: UsageHandlers['contextHandler'] = (data, submission) => {- const responseMessageId = bindResponse(submission);- const convoKey = resolveUsageKey(submission);- jotai.set(contextSnapshotFamily(convoKey), {- ...data,- completedOutputTokens: data.resumedOutputTokens ?? data.completedOutputTokens,- anchorMessageId: submission.userMessage?.messageId ?? null,- responseMessageId,- });- if (data.calibrationRatio != null && data.calibrationRatio > 0) {- jotai.set(calibrationFamily(convoKey), data.calibrationRatio);- }- /** Cache the fixed instruction+tool overhead (already inclusive of tool- * schemas) per agent/model so a snapshot-less branch of the same config can- * reserve it in its prune budget and gauge. */- const overhead = data.effectiveInstructionTokens ?? data.breakdown?.instructionTokens ?? 0;- setModelOverhead(- overheadKey(- submission.conversation?.endpoint,- submission.conversation?.model,- data.agentId,- ),- overhead,- );- streamCharsRef.current = 0;- confirmedRef.current = 0;- setLive(convoKey, 0);- };-- /** Folds one usage event into the in-flight pending holder exactly once per- * conversation. Returns false when the event was already counted (live then- * replayed on resume), so callers can skip the live-estimate bump too.- * `finalizeUsage` flushes the accumulated pending into the per-message index- * and resets it, so branch/total stay index-derived (no double count). */- const foldUsage = (data: TTokenUsageEvent, submission: UsageSubmissionLike): boolean => {- bindResponse(submission);- const convoKey = resolveUsageKey(submission);- /** runId+seq is unique per model call; fall back to the payload when a- * source predates the sequence tag */- const usageKey =- data.runId != null && data.seq != null ? `${data.runId}:${data.seq}` : JSON.stringify(data);- if (!markUsageFolded(convoKey, usageKey)) {- return false;- }-- /** 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);- jotai.set(pendingAtom, {- input: prev.input + units.input,- output: prev.output + units.output,- cacheWrite: prev.cacheWrite + units.cacheWrite,- cacheRead: prev.cacheRead + units.cacheRead,- 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 + cost,- /** Coverage is complete only if EVERY folded event carried a cost */- 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;- };-- /** Reconcile the live snapshot's calibrated estimate to a primary call's- * ACTUAL prompt tokens. The snapshot is pre-invoke for that call; this usage- * is its post-invoke truth, so the gauge stops showing the SDK multiplier's- * inflation (severe when a provider injects server-side content like web- * search). Resume is handled server-side (the job-store snapshot is reconciled- * when the call's usage is persisted), so no backfill reconcile is needed. */- const reconcileLiveSnapshot = (data: TTokenUsageEvent, submission: UsageSubmissionLike) => {- const convoKey = resolveUsageKey(submission);- const snapshotAtom = contextSnapshotFamily(convoKey);- const snapshot = jotai.get(snapshotAtom);- if (snapshot == null) {- return;- }- /** The snapshot precedes this call, so it must belong to the same run */- if (snapshot.runId != null && data.runId != null && snapshot.runId !== data.runId) {- return;- }- 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) => {- const folded = foldUsage(data, submission);-- /** Only a NEWLY folded primary call drives the live gauge. A replayed- * duplicate (folded=false on resume) can be an EARLIER tool-loop call that- * shares this run's id — reconciling with it would overwrite the latest- * snapshot with an earlier, smaller prompt. Tagged buckets (summarization,- * subagent) never touch the context gauge. */- if (!folded || data.usage_type != null) {- return;- }- /** This primary's provider-reported prompt is the post-invoke truth for the- * call the latest snapshot precedes — reconcile the gauge to it. */- reconcileLiveSnapshot(data, submission);- /** Use the repaired completion count (not raw output_tokens) so the- * snapshot gauge keeps the full response for under-reporting providers */- confirmedRef.current += normalizeUsageUnits(data).output;- streamCharsRef.current = 0;- setLive(resolveUsageKey(submission), confirmedRef.current);- };-- const tapStream: UsageHandlers['tapStream'] = (data, submission) => {- bindResponse(submission);- const chars = countDeltaChars(data?.delta?.content);- if (chars <= 0) {- return;- }- streamCharsRef.current += chars;- const now = Date.now();- if (now - lastFlushRef.current < FLUSH_INTERVAL_MS) {- return;- }- lastFlushRef.current = now;- const convoKey = resolveUsageKey(submission);- const ratio = jotai.get(calibrationFamily(convoKey));- setLive(convoKey, confirmedRef.current + estimateTokens(streamCharsRef.current, ratio));- };-- const tapContent: UsageHandlers['tapContent'] = (text, submission) => {- bindResponse(submission);- const value = extractContentText(text);- if (value.length === 0) {- return;- }- /** Cumulative per part — replace the running char count, don't add */- streamCharsRef.current = value.length;- const now = Date.now();- if (now - lastFlushRef.current < FLUSH_INTERVAL_MS) {- return;- }- lastFlushRef.current = now;- const convoKey = resolveUsageKey(submission);- const ratio = jotai.get(calibrationFamily(convoKey));- setLive(convoKey, confirmedRef.current + estimateTokens(streamCharsRef.current, ratio));- };-- const resetLive: UsageHandlers['resetLive'] = (submission) => {- streamCharsRef.current = 0;- confirmedRef.current = 0;- const convoKey = resolveUsageKey(submission);- setLive(convoKey, 0);- /** Terminal path with no salvageable response (stream error / intentional- * 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(activeUsageResponseIdFamily(convoKey), null);- jotai.set(pendingSubagentUsageFamily(convoKey), EMPTY_USAGE);- clearUsageFolded(convoKey);- };-- /** Both local stop and FINAL retain the same branch-owned context. Capture- * output from refs before resetting live state, including throttled text.- * Never promote a snapshot from a different response sharing the user. */- const retainSnapshot = (- convoKey: string,- responseId: string | null,- userMsgId: string | null,- output: number,- retainedToolTokens?: number,- ) => {- if (responseId == null) {- return;- }- const snapshotAtom = contextSnapshotFamily(convoKey);- const snapshot = jotai.get(snapshotAtom);- if (- snapshot == null ||- (snapshot.responseMessageId != null- ? snapshot.responseMessageId !== responseId- : snapshot.anchorMessageId !== userMsgId)- ) {- return;- }- const retained: ContextSnapshot = {- ...snapshot,- anchorMessageId: responseId,- responseMessageId: responseId,- ...(output > 0 && { completedOutputTokens: output }),- ...(retainedToolTokens != null &&- Number.isFinite(retainedToolTokens) &&- retainedToolTokens > 0 && { retainedToolTokens }),- };- jotai.set(snapshotAtom, retained);- const historyAtom = snapshotsByAnchorFamily(convoKey);- const next = new Map(jotai.get(historyAtom));- next.set(responseId, retained);- jotai.set(historyAtom, next);- };-- const attributePending: UsageHandlers['attributePending'] = (responseId, submission) => {- const convoKey = resolveUsageKey(submission);- retainSnapshot(- convoKey,- responseId,- submission.userMessage?.messageId ?? null,- confirmedRef.current +- estimateTokens(streamCharsRef.current, jotai.get(calibrationFamily(convoKey))),- );- /** Flush the billed-but-uncommitted usage onto the stopped partial reply- * (when its id is known and events were folded), then reset pending and- * the live estimate. Index-derived branch/total then reflect it. */- flushPendingInto(convoKey, responseId);- if (responseId != null) {- jotai.set(branchTotalsFamily(convoKey), sumBranch(convoKey, responseId, responseId));- jotai.set(totalUsageFamily(convoKey), sumTotalUsage(convoKey));- }- streamCharsRef.current = 0;- confirmedRef.current = 0;- setLive(convoKey, 0);- };-- const backfillUsage: UsageHandlers['backfillUsage'] = (entries, submission) => {- bindResponse(submission);- /** Fold the resumed run's persisted events idempotently — never reset- * the conversation totals, or a reconnect mid-stream would drop the- * usage of prompts already completed earlier in the session */- for (const entry of entries) {- foldUsage(entry, submission);- }- };-- const seedLive: UsageHandlers['seedLive'] = (chars, submission) => {- bindResponse(submission);- const convoKey = resolveUsageKey(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;- }- streamCharsRef.current = chars;- confirmedRef.current = 0;- setLive(convoKey, estimateTokens(chars, jotai.get(calibrationFamily(convoKey))));- };-- const finalizeUsage: UsageHandlers['finalizeUsage'] = (data, submission) => {- const fromKey = resolveUsageKey(submission);- const realId = data.conversation?.conversationId ?? fromKey;- /** From the refs, not the atom — the throttle may not have flushed */- const liveAtFinalize =- confirmedRef.current +- estimateTokens(streamCharsRef.current, jotai.get(calibrationFamily(fromKey)));-- upsertEntries(fromKey, [data.requestMessage, data.responseMessage]);-- moveConversation(fromKey, realId);-- const responseMeta = data.responseMessage?.contextMeta;- if (responseMeta?.calibrationRatio != null && responseMeta.calibrationRatio > 0) {- jotai.set(calibrationFamily(realId), responseMeta.calibrationRatio);- }-- const userMsgId = submission.userMessage?.messageId ?? null;- const responseId = data.responseMessage?.messageId ?? null;-- /** Flush the in-flight response's pending usage into its index entry, then- * reset pending. Branch/total are summed from the index, so this single- * add is counted exactly once; the persisted `metadata.usage` reproduces- * it on reload. */- flushPendingInto(realId, responseId, data.responseMessage?.metadata?.usage != null);-- const tailId = responseId ?? data.requestMessage?.messageId ?? null;- if (tailId) {- jotai.set(branchTotalsFamily(realId), sumBranch(realId, tailId, responseId ?? userMsgId));- }- jotai.set(totalUsageFamily(realId), sumTotalUsage(realId));-- retainSnapshot(- realId,- responseId,- userMsgId,- liveAtFinalize,- (data.responseMessage?.metadata?.contextUsage as TContextUsageEvent | undefined)- ?.retainedToolTokens,- );-- streamCharsRef.current = 0;- confirmedRef.current = 0;- setLive(realId, 0);- };-- return {- bindResponse,- contextHandler,- usageHandler,- tapStream,- tapContent,- finalizeUsage,- resetLive,- attributePending,- backfillUsage,- seedLive,- };- }, []);+ const countersRef = useRef(createUsageCounters());+ return useMemo(() => createUsageHandlers(getDefaultStore(), countersRef.current), []);}diff --git a/client/src/utils/tokens.spec.ts b/client/src/utils/tokens.spec.tsindex 8ed5b01333..4f29f6841f 100644--- a/client/src/utils/tokens.spec.ts+++ b/client/src/utils/tokens.spec.ts@@ -1,568 +1,6 @@-import { Constants, Providers } from 'librechat-data-provider';-import type { TMessage, TResponseUsage } from 'librechat-data-provider';-import {- buildIndex,- upsertEntries,- migrateIndex,- clearIndex,- sumBranch,- mergeUsage,- setEntryUsage,- sumTotalUsage,- prunedBranchTokens,- collectAnchorSeries,- latestExchangeTokens,- findBranchSnapshotAnchor,- estimateTokens,- normalizeUsageUnits,- formatTokens,- formatCost,- groupToolTokens,- countTrailingOutputChars,- EMPTY_BRANCH,- EMPTY_USAGE,- EMPTY_TOOL_GROUPS,-} from './tokens';--const CONVO = 'convo-1';--function msg(- messageId: string,- parentMessageId: string | null,- isCreatedByUser: boolean,- tokenCount?: number,-): TMessage {- return {- messageId,- parentMessageId,- isCreatedByUser,- tokenCount,- conversationId: CONVO,- text: '',- } as TMessage;-}--/** Response message carrying a persisted `metadata.usage` rollup (the backend- * persists already-normalized display units). */-function responseMsg(- messageId: string,- parentMessageId: string | null,- tokenCount: number,- usage: TResponseUsage,-): TMessage {- return {- messageId,- parentMessageId,- isCreatedByUser: false,- tokenCount,- conversationId: CONVO,- text: '',- metadata: { usage },- } as TMessage;-}--const USAGE_A: TResponseUsage = { input: 100, output: 50, cacheWrite: 0, cacheRead: 0, cost: 0.01 };-const USAGE_B: TResponseUsage = { input: 200, output: 80, cacheWrite: 0, cacheRead: 0, cost: 0.02 };--describe('token index', () => {- afterEach(() => {- clearIndex(CONVO);- clearIndex('convo-2');- clearIndex(Constants.NEW_CONVO);- });-- it('sums only the active branch via the parent chain', () => {- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 10),- msg('a1', 'u1', false, 20),- msg('u2', 'a1', true, 30),- msg('a2', 'u2', false, 40),- /** Sibling branch that must not be counted */- msg('a2-alt', 'u2', false, 999),- ]);-- const totals = sumBranch(CONVO, 'a2');- expect(totals.input).toBe(40);- expect(totals.output).toBe(60);- expect(totals.total).toBe(4);- expect(totals.counted).toBe(4);-- const altTotals = sumBranch(CONVO, 'a2-alt');- expect(altTotals.output).toBe(1019);- });-- it('estimates count-less messages by text length without inflating counted totals', () => {- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 12),- /** Imported message with no `tokenCount`: 40 chars of text → ~10 est tokens. */- {- messageId: 'a1',- parentMessageId: 'u1',- isCreatedByUser: false,- conversationId: CONVO,- text: 'x'.repeat(40),- } as TMessage,- ]);-- const totals = sumBranch(CONVO, 'a1');- /** Known counts feed input/output/counted; the count-less message stays out- * of those and lands in the separate (uncalibrated) estimate bucket. */- expect(totals.input).toBe(12);- expect(totals.output).toBe(0);- expect(totals.counted).toBe(1);- expect(totals.total).toBe(2);- expect(totals.estTokens).toBe(10);- });-- it('estimates object-form content text and merged quote excerpts', () => {- buildIndex(CONVO, [- /** Assistant body lives only in object-form content (`text.value`). */- {- messageId: 'a1',- parentMessageId: Constants.NO_PARENT,- isCreatedByUser: false,- conversationId: CONVO,- content: [{ type: 'text', text: { value: 'y'.repeat(20) } }],- } as unknown as TMessage,- /** User turn whose quotes are merged into the prompt at send time. */- {- messageId: 'u1',- parentMessageId: 'a1',- isCreatedByUser: true,- conversationId: CONVO,- text: 'z'.repeat(16),- quotes: ['q'.repeat(8)],- } as TMessage,- ]);-- /** a1: 20 content chars / 4 = 5; u1: (16 text + 8 quote) / 4 = 6. */- const totals = sumBranch(CONVO, 'u1');- expect(totals.counted).toBe(0);- expect(totals.estTokens).toBe(11);- });-- it('recounts quoted user turns (ignoring stale counts), counts tool calls, skips reasoning', () => {- buildIndex(CONVO, [- /** Quoted user turn with a stale text-only stored count: the send path- * recounts the merged prompt every turn, so the estimate ignores the count- * and recounts from text+quotes. */- {- messageId: 'u1',- parentMessageId: Constants.NO_PARENT,- isCreatedByUser: true,- conversationId: CONVO,- tokenCount: 999,- text: 'hi',- quotes: ['q'.repeat(38)],- } as TMessage,- /** Count-less assistant turn: tool-call name/args/output count toward the- * estimate (sent back as context); reasoning does not. */- {- messageId: 'a1',- parentMessageId: 'u1',- isCreatedByUser: false,- conversationId: CONVO,- content: [- { type: 'think', think: 'r'.repeat(40) },- { type: 'tool_call', tool_call: { name: 'sub', args: 'aa', output: 'o'.repeat(11) } },- ],- } as unknown as TMessage,- ]);-- const totals = sumBranch(CONVO, 'a1');- /** u1 quoted: stored 999 ignored; (2 text + 38 quote) / 4 = 10. a1 tool_call- * name 3 + args 2 + output 11 = 16 / 4 = 4 (think skipped). */- expect(totals.input).toBe(0);- expect(totals.counted).toBe(0);- expect(totals.estTokens).toBe(14);- });-- it('prefers content over text for count-less messages carrying both', () => {- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 8),- /** Stopped agent response: saved with both a short `text` and structured- * `content` (a tool call). The send path formats from content, so the- * estimate must use content (tool tokens), not the shorter text. */- {- messageId: 'a1',- parentMessageId: 'u1',- isCreatedByUser: false,- conversationId: CONVO,- text: 'hi',- content: [- { type: 'tool_call', tool_call: { name: 'run', args: 'aa', output: 'o'.repeat(13) } },- ],- } as unknown as TMessage,- ]);-- const totals = sumBranch(CONVO, 'a1');- /** a1 uses content (name 3 + args 2 + output 13 = 18 / 4 = 5), not text 'hi'. */- expect(totals.input).toBe(8);- expect(totals.estTokens).toBe(5);- });-- it('estimates a previewed tool call from its stored lengths, not the preview', () => {- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 12),- {- messageId: 'a1',- parentMessageId: 'u1',- isCreatedByUser: false,- conversationId: CONVO,- text: '',- content: [- {- type: 'tool_call',- tool_call: {- name: 'run',- args: 'aa',- argsTruncated: true,- argsLength: 17,- output: 'o…o',- outputTruncated: true,- outputLength: 20,- },- },- ],- } as unknown as TMessage,- ]);-- /** name 3 + stored args 17 + stored output 20 = 40 chars / 4 = 10. */- expect(sumBranch(CONVO, 'a1').estTokens).toBe(10);- });-- it('exposes the count-less tail estimate so live output is not double-counted', () => {- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 12),- /** In-flight / resumed response: count-less, so it lands in estTokens; it is- * also covered by liveTokens, so the estimate path drops tailEstTokens. */- {- messageId: 'a1',- parentMessageId: 'u1',- isCreatedByUser: false,- conversationId: CONVO,- text: 'o'.repeat(20),- } as TMessage,- ]);-- const totals = sumBranch(CONVO, 'a1');- /** a1 is the tail: 20 / 4 = 5, surfaced both in estTokens and tailEstTokens. */- expect(totals.estTokens).toBe(5);- 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 = () =>- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 2),- msg('a1', 'u1', false, 10),- msg('u2', 'a1', true, 2),- msg('a2', 'u2', false, 2),- ]);-- 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)).toEqual({ tokens: 4, toolTokens: 0 });- });-- it('returns the full branch sum when it fits the budget', () => {- buildChain();- 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)).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,- });- });- });-- it('caps the branch at a summary marker instead of re-summing compacted history', () => {- const summarized = {- messageId: 'a2',- parentMessageId: 'u2',- isCreatedByUser: false,- tokenCount: 40,- conversationId: CONVO,- text: '',- /** a2's turn compacted the history; pre-invoke context was 500 tokens. */- metadata: { summaryUsedTokens: 500 },- } as TMessage;- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 100),- msg('a1', 'u1', false, 9000) /** huge pre-summary history, now discarded */,- msg('u2', 'a1', true, 200),- summarized,- msg('u3', 'a2', true, 15),- msg('a3', 'u3', false, 25),- ]);-- const totals = sumBranch(CONVO, 'a3');- /** Walk stops at a2: only its output + the post-summary turn are summed. */- expect(totals.summaryBaseline).toBe(500);- expect(totals.input).toBe(15);- expect(totals.output).toBe(65); // a3 (25) + a2 (40)- /** Estimate used = post-summary + compacted baseline = 580, not the 9380- * raw history sum that pinned the gauge at 100%. */- expect(totals.input + totals.output + totals.summaryBaseline).toBe(580);- });-- it('keeps provider usage/cost across the full branch even past a summary marker', () => {- const summarized = {- messageId: 'a2',- parentMessageId: 'u2',- isCreatedByUser: false,- tokenCount: 40,- conversationId: CONVO,- text: '',- metadata: { usage: USAGE_B, summaryUsedTokens: 500 },- } as TMessage;- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 10),- responseMsg('a1', 'u1', 9000, USAGE_A) /** pre-summary spend */,- msg('u2', 'a1', true, 200),- summarized,- msg('u3', 'a2', true, 15),- responseMsg('a3', 'u3', 25, USAGE_A) /** post-summary spend */,- ]);-- const totals = sumBranch(CONVO, 'a3');- /** Context is capped at the marker... */- expect(totals.summaryBaseline).toBe(500);- /** ...but cost/usage is cumulative spend and spans the WHOLE branch- * (a1 + a2 + a3 = 0.01 + 0.02 + 0.01), not truncated at the summary boundary. */- expect(totals.usage.cost).toBeCloseTo(0.04);- expect(totals.usage.input).toBe(400); // 100 + 200 + 100- });-- it('flags whether the anchor message is on the branch', () => {- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 10),- msg('a1', 'u1', false, 20),- msg('a1-alt', 'u1', false, 25),- ]);-- expect(sumBranch(CONVO, 'a1', 'a1').containsAnchor).toBe(true);- expect(sumBranch(CONVO, 'a1-alt', 'a1').containsAnchor).toBe(false);- });-- it('stops matching the anchor once the context is capped at a summary marker', () => {- const summarized = {- messageId: 'a2',- parentMessageId: 'u2',- isCreatedByUser: false,- tokenCount: 40,- conversationId: CONVO,- text: '',- metadata: { summaryUsedTokens: 500 },- } as TMessage;- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 100),- msg('a1', 'u1', false, 20),- msg('u2', 'a1', true, 200),- summarized,- msg('u3', 'a2', true, 15),- msg('a3', 'u3', false, 25),- ]);- /** a1 is older than the summary marker (a2): a snapshot anchored there is- * pre-summary, so it must NOT count as on-branch — else useTokenUsage revives- * that stale breakdown over the summary-baseline estimate. */- expect(sumBranch(CONVO, 'a3', 'a1').containsAnchor).toBe(false);- /** The summarized response's own (post-summary) snapshot still matches... */- expect(sumBranch(CONVO, 'a3', 'a2').containsAnchor).toBe(true);- /** ...as does a snapshot from a newer turn. */- expect(sumBranch(CONVO, 'a3', 'a3').containsAnchor).toBe(true);- });-- it('tracks uncounted messages and tolerates missing parents', () => {- buildIndex(CONVO, [msg('u2', 'missing-parent', true, undefined), msg('a2', 'u2', false, 15)]);-- const totals = sumBranch(CONVO, 'a2');- expect(totals.total).toBe(2);- expect(totals.counted).toBe(1);- expect(totals.output).toBe(15);- });-- it('returns EMPTY_BRANCH without an index or tail', () => {- expect(sumBranch('unknown', 'x')).toBe(EMPTY_BRANCH);- buildIndex(CONVO, []);- expect(sumBranch(CONVO, null)).toBe(EMPTY_BRANCH);- });-- it('upserts incrementally and overwrites by messageId', () => {- buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10)]);- upsertEntries(CONVO, [msg('a1', 'u1', false, 20), null, undefined]);- expect(sumBranch(CONVO, 'a1').output).toBe(20);-- upsertEntries(CONVO, [msg('a1', 'u1', false, 35)]);- expect(sumBranch(CONVO, 'a1').output).toBe(35);- });-- it('migrates the index to a new conversation id', () => {- buildIndex(Constants.NEW_CONVO, [msg('u1', Constants.NO_PARENT, true, 10)]);- migrateIndex(Constants.NEW_CONVO, 'convo-2');-- expect(sumBranch(Constants.NEW_CONVO, 'u1').input).toBe(0);- expect(sumBranch('convo-2', 'u1').input).toBe(10);- });-});--describe('findBranchSnapshotAnchor', () => {- afterEach(() => clearIndex(CONVO));-- it('returns the deepest stored anchor on the viewed branch', () => {- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 10),- msg('a1', 'u1', false, 20),- msg('u2', 'a1', true, 30),- msg('a2', 'u2', false, 40),- msg('a2-alt', 'u2', false, 50),- ]);- /** Both a1 and a2 stored; walking from a2 must return the nearer one (a2). */- const anchors = new Map([- ['a1', 1],- ['a2', 1],- ]);- expect(findBranchSnapshotAnchor(CONVO, 'a2', anchors)).toBe('a2');- /** From the sibling branch tail, the only on-branch anchor is a1. */- expect(findBranchSnapshotAnchor(CONVO, 'a2-alt', anchors)).toBe('a1');- });-- it('returns null when no stored anchor sits on the branch', () => {- buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10), msg('a1', 'u1', false, 20)]);- expect(findBranchSnapshotAnchor(CONVO, 'a1', new Map([['other', 1]]))).toBeNull();- expect(findBranchSnapshotAnchor(CONVO, 'a1', new Map())).toBeNull();- expect(findBranchSnapshotAnchor('unknown', 'a1', new Map([['a1', 1]]))).toBeNull();- });-- it('does not cross a summary marker to recover a stale pre-summary snapshot', () => {- const summarized = {- messageId: 'a2',- parentMessageId: 'u2',- isCreatedByUser: false,- tokenCount: 40,- conversationId: CONVO,- text: '',- metadata: { summaryUsedTokens: 500 },- } as TMessage;- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 10),- msg('a1', 'u1', false, 20) /** has a snapshot, but pre-summary */,- msg('u2', 'a1', true, 30),- summarized /** compacted here, no snapshot of its own */,- msg('u3', 'a2', true, 15),- msg('a3', 'u3', false, 25),- ]);- /** a1 is the only stored anchor, but it sits before the summary — the walk- * must stop at a2 and return null so the summary-baseline estimate is used. */- expect(findBranchSnapshotAnchor(CONVO, 'a3', new Map([['a1', 1]]))).toBeNull();- /** When the summarized response itself has a snapshot, return it. */- expect(findBranchSnapshotAnchor(CONVO, 'a3', new Map([['a2', 1]]))).toBe('a2');- });-});--describe('estimateTokens', () => {- it('estimates chars/4 scaled by calibration ratio', () => {- expect(estimateTokens(400)).toBe(100);- expect(estimateTokens(400, 1.1)).toBe(110);- expect(estimateTokens(0)).toBe(0);- expect(estimateTokens(100, 0)).toBe(25);- });+import { formatCost, formatTokens } from './tokens';+describe('formatTokens', () => {it('renders malformed token counts as a bounded zero', () => {expect(formatTokens(Number.NaN)).toBe('0');expect(formatTokens(Number.POSITIVE_INFINITY)).toBe('0');@@ -570,94 +8,6 @@ describe('estimateTokens', () => {});});-describe('normalizeUsageUnits', () => {- it('subtracts cache from input for Anthropic (input_tokens is cache-inclusive)', () => {- /** The agents SDK folds cache into Anthropic input_tokens, so cache is a- * subset of input and must be subtracted: 900 − 100 read = 800. */- expect(- normalizeUsageUnits({- input_tokens: 900,- output_tokens: 100,- provider: Providers.ANTHROPIC,- input_token_details: { cache_read: 100 },- }),- ).toEqual({ input: 800, output: 100, cacheWrite: 0, cacheRead: 100 });- });-- it('keeps cache additive for Bedrock (Converse input_tokens excludes cache)', () => {- expect(- normalizeUsageUnits({- input_tokens: 900,- output_tokens: 100,- provider: Providers.BEDROCK,- input_token_details: { cache_read: 100 },- }),- ).toEqual({ input: 900, output: 100, cacheWrite: 0, cacheRead: 100 });- });-- it('keeps subset semantics for OpenAI regardless of magnitude', () => {- expect(- normalizeUsageUnits({- input_tokens: 900,- output_tokens: 100,- provider: Providers.OPENAI,- input_token_details: { cache_read: 100 },- }),- ).toEqual({ input: 800, output: 100, cacheWrite: 0, cacheRead: 100 });- });-- it('falls back to a magnitude heuristic when provider is unknown', () => {- /** cacheSum (12000) > input (1000) ⇒ additive */- expect(- normalizeUsageUnits({- input_tokens: 1000,- output_tokens: 500,- input_token_details: { cache_creation: 2000, cache_read: 10000 },- }),- ).toEqual({ input: 1000, output: 500, cacheWrite: 2000, cacheRead: 10000 });- });-- it('repairs under-reported completion tokens (Vertex thinking)', () => {- /** total - input = 500 recovers the dropped thinking tokens */- expect(- normalizeUsageUnits({- input_tokens: 1000,- output_tokens: 200,- total_tokens: 1500,- provider: Providers.VERTEXAI,- }).output,- ).toBe(500);- });-- it('does not mistake additive cache for missing completion tokens (Bedrock)', () => {- /** Bedrock keeps cache separate, so total = input + output + cache (1700).- * Without the cache adjustment the repair would falsely inflate completion. */- expect(- normalizeUsageUnits({- input_tokens: 1000,- output_tokens: 200,- total_tokens: 1700,- provider: Providers.BEDROCK,- input_token_details: { cache_creation: 300, cache_read: 200 },- }).output,- ).toBe(200);- });-- it('does not inflate completion for cache-inclusive Anthropic totals', () => {- /** Anthropic total already includes cache (input 1000 covers the 500 cache),- * so total 1200 leaves output at 200 — no false repair. */- expect(- normalizeUsageUnits({- input_tokens: 1000,- output_tokens: 200,- total_tokens: 1200,- provider: Providers.ANTHROPIC,- input_token_details: { cache_creation: 300, cache_read: 200 },- }).output,- ).toBe(200);- });-});-describe('formatCost', () => {it('formats across magnitude bands (USD default, unchanged)', () => {expect(formatCost(0)).toBe('$0.00');@@ -716,450 +66,3 @@ describe('formatCost', () => {expect(formatCost(10, { code: 'USD', rate: Number.NaN })).toBe('$10.00');});});--describe('groupToolTokens', () => {- it('classifies tools into system, mcp, skills, and subagent groups', () => {- const groups = groupToolTokens(- {- execute_code: 500,- web_search: 300,- skill: 200,- subagent: 150,- 'search_mcp_Google-Workspace': 400,- fetch_mcp_Github: 250,- },- ['fetch_mcp_Github', 'web_search'],- );-- expect(groups).toEqual({- system: 500,- mcp: 400,- skills: 200,- subagents: 150,- systemDeferred: 300,- mcpDeferred: 250,- });- });-- it('returns empty groups without counts and skips zero entries', () => {- 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', () => {- const text = (value: string) => ({ type: 'text', text: value });- const think = (value: string) => ({ type: 'think', think: value });- const tool = () => ({ type: 'tool_call', tool_call: { id: 'tc' } });-- it('counts the trailing run of text and think parts', () => {- expect(countTrailingOutputChars([text('aaaa'), tool(), think('bb'), text('ccc')])).toBe(5);- });-- it('returns 0 when the latest part is a tool call (no in-flight output)', () => {- /** Once a tool call is emitted, its preceding text is folded into the next- * snapshot's messageTokens — counting it here would double-count. */- expect(countTrailingOutputChars([text('aaaa'), tool(), text('ccc'), tool()])).toBe(0);- });-- it('stops at the previous tool boundary', () => {- expect(countTrailingOutputChars([text('aaaa'), tool(), text('ccc')])).toBe(3);- });-- it('handles empty and non-output content', () => {- expect(countTrailingOutputChars(undefined)).toBe(0);- expect(countTrailingOutputChars([])).toBe(0);- expect(countTrailingOutputChars([tool()])).toBe(0);- });-});--describe('per-message usage index (branch + total)', () => {- afterEach(() => {- clearIndex(CONVO);- });-- it('reads metadata.usage onto entries and sums it along the branch', () => {- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 10),- responseMsg('a1', 'u1', 50, USAGE_A),- msg('u2', 'a1', true, 30),- responseMsg('a2', 'u2', 80, USAGE_B),- ]);-- const { usage } = sumBranch(CONVO, 'a2');- expect(usage).toEqual({- input: 300,- output: 130,- cacheWrite: 0,- cacheRead: 0,- cost: 0.03,- costKnown: true,- });- });-- it('reads persisted display units (incl. cache) directly', () => {- /** The backend already normalized per-event; the client reads as-is */- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 10),- responseMsg('a1', 'u1', 100, {- input: 600,- output: 100,- cacheWrite: 0,- cacheRead: 400,- cost: 0.03,- }),- ]);-- const { usage } = sumBranch(CONVO, 'a1');- expect(usage).toEqual({- input: 600,- output: 100,- cacheWrite: 0,- cacheRead: 400,- cost: 0.03,- costKnown: true,- });- });-- it('marks cost unknown when persisted usage omits cost (contextCost off)', () => {- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 10),- responseMsg('a1', 'u1', 50, { input: 100, output: 50, cacheWrite: 0, cacheRead: 0 }),- ]);- const { usage } = sumBranch(CONVO, 'a1');- expect(usage.costKnown).toBe(false);- expect(usage.cost).toBe(0);- 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);- expect(sumTotalUsage(CONVO)).toEqual(EMPTY_USAGE);- });-- it('selects only the viewed response as the last turn across compaction and regeneration', () => {- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 10),- responseMsg('a1', 'u1', 50, USAGE_A),- msg('u2', 'a1', true, 20),- {- ...responseMsg('a2', 'u2', 80, { ...USAGE_B, cacheRead: 400, cacheWrite: 30 }),- metadata: {- usage: { ...USAGE_B, cacheRead: 400, cacheWrite: 30 },- summaryUsedTokens: 500,- },- },- responseMsg('a2-alt', 'u2', 60, { ...USAGE_A, cost: 0 }),- ]);-- expect(sumBranch(CONVO, 'a2').lastTurnUsage).toEqual({- input: 200,- output: 80,- cacheRead: 400,- cacheWrite: 30,- cost: 0.02,- costKnown: true,- });- expect(sumBranch(CONVO, 'a2').usage.input).toBe(300);- expect(sumBranch(CONVO, 'a2-alt').lastTurnUsage?.cost).toBe(0);- expect(sumBranch(CONVO, 'u2').lastTurnUsage).toBeUndefined();- expect(sumTotalUsage(CONVO).cacheRead).toBe(400);- });-- it('does not borrow an ancestor response when the selected tail has no usage', () => {- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 10),- responseMsg('a1', 'u1', 50, USAGE_A),- msg('u2', 'a1', true, 10),- msg('a2', 'u2', false, 20),- ]);- expect(sumBranch(CONVO, 'a2').lastTurnUsage).toBeUndefined();- expect(sumBranch(CONVO, 'a2').usage.cost).toBe(0.01);- expect(sumBranch(CONVO, 'u2').lastTurnUsage).toBeUndefined();- });-- it('preserves a prior entry usage when a rebuilt message lacks metadata.usage', () => {- /** Live finalize flushes usage into the index before persisted metadata- * reaches the cache; a mid-session rebuild from a cache message without- * metadata.usage must not wipe it (regenerate keeps the sibling's cost). */- buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10), msg('a1', 'u1', false, 50)]);- setEntryUsage(CONVO, 'a1', {- input: 100,- output: 50,- cacheWrite: 0,- cacheRead: 0,- cost: 0.01,- costKnown: true,- });- /** Rebuild from the same cache (still no metadata.usage on a1) */- buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10), msg('a1', 'u1', false, 50)]);- expect(sumBranch(CONVO, 'a1').usage.cost).toBeCloseTo(0.01);- expect(sumBranch(CONVO, 'a1').usage.input).toBe(100);- expect(sumBranch(CONVO, 'a1').lastTurnUsage?.cost).toBeCloseTo(0.01);- });-- it('restores branch cost from sticky history after regenerate drops then re-adds a sibling', () => {- /** a1 generated live; its cache message never carries metadata.usage */- buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10), msg('a1', 'u1', false, 50)]);- setEntryUsage(CONVO, 'a1', {- input: 100,- output: 50,- cacheWrite: 0,- cacheRead: 0,- cost: 0.01,- costKnown: true,- });-- /** Regenerate streaming shows only the active branch — a1 is dropped */- buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10), msg('a1-alt', 'u1', false, 60)]);- expect(sumBranch(CONVO, 'a1').usage).toEqual(EMPTY_USAGE);-- /** Post-regenerate full rebuild re-adds a1 (still no metadata.usage) */- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 10),- msg('a1', 'u1', false, 50),- msg('a1-alt', 'u1', false, 60),- ]);-- /** Switching back to branch A must still show its cost (the reported bug) */- expect(sumBranch(CONVO, 'a1').usage.cost).toBeCloseTo(0.01);- expect(sumBranch(CONVO, 'a1').usage.input).toBe(100);- });-- it('scopes branch usage to the active thread while total spans all branches', () => {- /** Regenerate: a1 and a1-alt are sibling responses under the same user msg */- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 10),- responseMsg('a1', 'u1', 50, USAGE_A),- responseMsg('a1-alt', 'u1', 80, USAGE_B),- ]);-- /** Viewing branch B (the regenerated response) */- expect(sumBranch(CONVO, 'a1-alt').usage.cost).toBeCloseTo(0.02);- /** Viewing branch A (the original) */- expect(sumBranch(CONVO, 'a1').usage.cost).toBeCloseTo(0.01);- /** Total spans both abandoned + active branches */- const total = sumTotalUsage(CONVO);- expect(total.cost).toBeCloseTo(0.03);- expect(total.input).toBe(300);- expect(total.output).toBe(130);- });-- it('is idempotent across rebuilds', () => {- const messages = [- msg('u1', Constants.NO_PARENT, true, 10),- responseMsg('a1', 'u1', 50, USAGE_A),- responseMsg('a1-alt', 'u1', 80, USAGE_B),- ];- buildIndex(CONVO, messages);- const first = sumTotalUsage(CONVO);- buildIndex(CONVO, messages);- const second = sumTotalUsage(CONVO);- expect(second).toEqual(first);- });-- it('flushes a live response usage via setEntryUsage (no metadata yet)', () => {- buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10), msg('a1', 'u1', false, 50)]);- /** Live response entry has no metadata.usage until persisted; finalize flushes it */- expect(sumBranch(CONVO, 'a1').usage).toEqual(EMPTY_USAGE);- setEntryUsage(CONVO, 'a1', {- input: 100,- output: 50,- cacheWrite: 0,- cacheRead: 0,- cost: 0.01,- costKnown: true,- });- expect(sumBranch(CONVO, 'a1').usage.cost).toBeCloseTo(0.01);- expect(sumBranch(CONVO, 'a1').usage.input).toBe(100);- });-- it('mergeUsage sums records and ANDs costKnown (incomplete coverage wins)', () => {- const a = { input: 1, output: 2, cacheWrite: 3, cacheRead: 4, cost: 0.5, costKnown: false };- const b = { input: 10, output: 20, cacheWrite: 30, cacheRead: 40, cost: 1.5, costKnown: true };- expect(mergeUsage(a, b)).toEqual({- input: 11,- output: 22,- cacheWrite: 33,- cacheRead: 44,- cost: 2,- costKnown: false,- });- });-- it('marks branch cost incomplete when any usage-bearing entry lacks cost', () => {- /** A turn saved before cost display was on (no cost) alongside one with cost- * → the summed cost under-reports, so coverage is incomplete. */- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 10),- responseMsg('a1', 'u1', 50, { input: 100, output: 50, cacheWrite: 0, cacheRead: 0 }),- responseMsg('a2', 'a1', 60, USAGE_B),- ]);- const { usage } = sumBranch(CONVO, 'a2');- expect(usage.costKnown).toBe(false);- /** Cost still sums what it can, but coverage is flagged incomplete */- expect(usage.cost).toBeCloseTo(0.02);- expect(sumTotalUsage(CONVO).costKnown).toBe(false);- });-- it('EMPTY_BRANCH carries an empty usage record', () => {- expect(sumBranch('missing-convo', 'x')).toBe(EMPTY_BRANCH);- expect(EMPTY_BRANCH.usage).toEqual(EMPTY_USAGE);- });-- it('collectAnchorSeries reads used tokens per anchor, oldest → newest', () => {- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 4),- msg('a1', 'u1', false, 10),- msg('u2', 'a1', true, 4),- msg('a2', 'u2', false, 20),- msg('u3', 'a2', true, 4),- msg('a3', 'u3', false, 30),- ]);- const snap = (remaining: number) => ({- contextBudget: 1000,- remainingContextTokens: remaining,- breakdown: { maxContextTokens: 1000 },- });- const anchors = new Map([- ['a1', snap(960)],- ['a2', snap(920)],- ['a3', snap(860)],- ]);-- const series = collectAnchorSeries(CONVO, 'a3', anchors);- /** used = budget − remaining: 40 → 80 → 140, oldest first */- expect(series).toEqual([- { used: 40, basis: 'remaining' },- { used: 80, basis: 'remaining' },- { used: 140, basis: 'remaining' },- ]);- expect(collectAnchorSeries(CONVO, 'a3', new Map())).toEqual([]);- });-- it('collectAnchorSeries derives a snapshot saved without remaining headroom', () => {- buildIndex(CONVO, [- msg('u1', Constants.NO_PARENT, true, 4),- msg('a1', 'u1', false, 10),- msg('u2', 'a1', true, 4),- msg('a2', 'u2', false, 20),- ]);- const anchors = new Map<string, unknown>([- /** The older shape: a budget and a breakdown, no remaining count. Read as- * zero remaining it would claim the whole 1000-token window was spent. */- [- 'a1',- {- contextBudget: 1000,- breakdown: {- maxContextTokens: 1000,- instructionTokens: 100,- summaryTokens: 25,- 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: 185, 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.tsindex 3b4f614138..ad1be39856 100644--- a/client/src/utils/tokens.ts+++ b/client/src/utils/tokens.ts@@ -1,940 +1,49 @@-import { Tools, Constants, inputTokensIncludesCache } 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 {- input: number;- output: number;- cacheWrite: number;- cacheRead: number;- /** Authoritative USD cost; 0 when `interface.contextCost` was off at save */- cost: number;- /** Whether cost coverage is COMPLETE — every usage-bearing response summed- * here carried a cost. Gates the cost row so a partial sum (some turns saved- * before cost display was on) never renders an under-reported total. Starts- * true (vacuous) and is ANDed; pair with `hasUsage` to require ≥1 entry. */- costKnown: boolean;-}--export const EMPTY_USAGE: BranchUsage = {- input: 0,- output: 0,- cacheWrite: 0,- cacheRead: 0,- 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;- /** Char/4 token estimate used in place of `tokenCount`: count-less (imported /- * pre-feature) message bodies, plus quoted user turns (recounted from merged- * 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) */- usage?: BranchUsage;- /** Pre-invoke compacted context size (`metadata.summaryUsedTokens`) for a- * response whose turn summarized. Caps the estimate so it stops re-summing- * the now-discarded pre-summary history. */- summaryUsedTokens?: number;-}--export interface BranchTotals {- /** Sum of user-message token counts on the active branch */- input: number;- /** Sum of assistant-message token counts on the active branch */- output: number;- /** Messages on the branch with a known tokenCount */- counted: number;- /** Total messages on the branch */- total: number;- /** 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 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;- /** Provider usage/cost summed along the active branch */- usage: BranchUsage;- /** Recorded usage of the selected response, never an earlier ancestor's usage. */- lastTurnUsage?: BranchUsage;- /** Compacted-context baseline from the deepest summarized response on the- * branch (0 if none). The branch walk stops there, so `input`/`output` cover- * only the post-summary messages; the estimate adds this to avoid counting- * the discarded pre-summary history. */- summaryBaseline: number;-}--export const EMPTY_BRANCH: BranchTotals = {- input: 0,- output: 0,- counted: 0,- total: 0,- estTokens: 0,- tailEstTokens: 0,- estToolTokens: 0,- tailEstToolTokens: 0,- tailId: null,- containsAnchor: false,- usage: EMPTY_USAGE,- summaryBaseline: 0,-};--/** Module-level token index: conversationId → messageId → entry. Not render state. */-const registry = new Map<string, Map<string, TokenEntry>>();--/**- * Sticky per-response usage: conversationId → messageId → usage. Written only by- * the live finalize/stop flush (`setEntryUsage`) and never rebuilt from the- * messages cache, so a response's usage survives mid-session index rebuilds even- * when its cache message lacks `metadata.usage` AND it was transiently dropped- * from the cache (e.g. a sibling branch during a regenerate). `buildIndex`- * restores from here so branch cost persists across branch switches — the cost- * analog of `snapshotsByAnchorFamily` for the breakdown. Cleared on convo switch.- */-const usageHistory = new Map<string, Map<string, BranchUsage>>();--function stickyUsage(conversationId: string, messageId: string): BranchUsage | undefined {- return usageHistory.get(conversationId)?.get(messageId);-}--/** Reads the persisted per-response usage rollup off a message's metadata.- * The backend already normalized per-event into display units, so this reads- * them directly. Absent for user messages and pre-feature responses (they- * contribute 0 to branch/total). */-function readPersistedUsage(message: Partial<TMessage>): BranchUsage | undefined {- const usage = message.metadata?.usage;- if (usage == null || typeof usage !== 'object') {- return undefined;- }- const persisted = usage as TResponseUsage;- return {- 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),- };-}--/** Pure sum of two usage records — for combining branch/total with pending. */-export function mergeUsage(a: BranchUsage, b: BranchUsage): BranchUsage {- return {- input: a.input + b.input,- output: a.output + b.output,- cacheWrite: a.cacheWrite + b.cacheWrite,- cacheRead: a.cacheRead + b.cacheRead,- cost: a.cost + b.cost,- /** Coverage stays complete only if BOTH sides are complete */- costKnown: a.costKnown && b.costKnown,- };-}--/** Accumulates one entry's usage into a running total (in place). */-function addUsage(target: BranchUsage, usage?: BranchUsage): void {- if (usage == null) {- return;- }- target.input += usage.input;- target.output += usage.output;- target.cacheWrite += usage.cacheWrite;- target.cacheRead += usage.cacheRead;- target.cost += usage.cost;- /** A usage-bearing entry without a cost breaks complete coverage */- if (!usage.costKnown) {- target.costKnown = false;- }-}--type ToolCallLengthFields = {- args?: unknown;- output?: unknown;- argsLength?: unknown;- outputLength?: unknown;-};--/** Stored lengths of a tool call's arguments and output. A preview carries the full lengths in- * `argsLength`/`outputLength`, so estimates match the conversation the model actually sees. */-function toolCallLengths(call: ToolCallLengthFields): { args: number; output: number } {- let args = 0;- if (typeof call.argsLength === 'number') {- args = call.argsLength;- } else if (typeof call.args === 'string') {- args = call.args.length;- } else if (call.args != null) {- args = JSON.stringify(call.args)?.length ?? 0;- }- let output = 0;- if (typeof call.outputLength === 'number') {- output = call.outputLength;- } else if (typeof call.output === 'string') {- output = call.output.length;- }- return { args, output };-}--/** 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. */-function partTextChars(part: unknown): number {- if (part == null || typeof part !== 'object') {- return 0;- }- const type = (part as { type?: unknown }).type;- if (type === 'think' || type === 'error') {- return 0;- }- if (type === 'tool_call') {- const call = (part as { tool_call?: ToolCallLengthFields & { name?: unknown } }).tool_call;- if (call == null) {- return 0;- }- const lengths = toolCallLengths(call);- return (typeof call.name === 'string' ? call.name.length : 0) + lengths.args + lengths.output;- }- const text = (part as { text?: unknown }).text;- if (typeof text === 'string') {- return text.length;- }- if (- text != null &&- typeof text === 'object' &&- typeof (text as { value?: unknown }).value === 'string'- ) {- return (text as { value: string }).value.length;- }- return 0;-}--/** Char length of a message's tool-call payload — tool_call parts' name, args- * and output — the estimate path's split of message body into conversation vs- * tool-call usage. Zero for plain-text bodies. */-function messageToolChars(message: Partial<TMessage>): { chars: number; resultChars: number } {- if (!Array.isArray(message.content)) {- return { chars: 0, resultChars: 0 };- }- let chars = 0;- let resultChars = 0;- for (const part of message.content) {- if (part == null || typeof part !== 'object') {- continue;- }- if ('type' in part && part.type === 'tool_call' && 'tool_call' in part) {- const call = part.tool_call;- if (call == null || typeof call !== 'object') {- continue;- }- if ('name' in call && typeof call.name === 'string') {- chars += call.name.length;- }- const lengths = toolCallLengths(call as ToolCallLengthFields);- chars += 'args' in call && call.args == null ? 4 : lengths.args;- chars += lengths.output;- resultChars += lengths.output;- }- }- 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- * agent response) would otherwise drop its content/tool-call tokens. */-function messageChars(message: Partial<TMessage>): number {- if (Array.isArray(message.content) && message.content.length > 0) {- let chars = 0;- for (const part of message.content) {- chars += partTextChars(part);- }- return chars;- }- if (typeof message.text === 'string') {- return message.text.length;- }- return 0;-}--/** Quoted excerpts the send path merges into a user message's prompt. */-function quoteChars(message: Partial<TMessage>): number {- if (!Array.isArray(message.quotes)) {- return 0;- }- let chars = 0;- for (const quote of message.quotes) {- if (typeof quote === 'string') {- chars += quote.length;- }- }- return chars;-}--function toEntry(message: Partial<TMessage>): TokenEntry {- 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- * recomputes it from `text` alone, and the send path recounts the quote-merged- * prompt every turn regardless (`needsCanonicalTokenCount` in agents/client.js).- * So mirror the server — estimate quoted turns from the merged text+quotes and- * ignore the stored count. Other count-less imports / pre-feature messages- * estimate from text. */- let estTokens = 0;- if (quoted) {- estTokens = Math.round((messageChars(message) + quoteChars(message)) / 4);- } 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: summaryUsedTokens > 0 ? summaryUsedTokens : undefined,- };-}--/** Full O(n) rebuild — only on discrete cache replacements (load, refetch, edits).- * Restores a response's `usage` from the sticky history when the rebuilt message- * carries none: per-message usage is immutable and the live finalize flushes it- * into the index (`setEntryUsage`) before the persisted `metadata.usage` reaches- * the cache, so a mid-session rebuild (e.g. during regenerate) must not wipe an- * earlier branch's flushed usage — which would drop its branch cost on switch. */-export function buildIndex(conversationId: string, messages?: TMessage[] | null): void {- const index = new Map<string, TokenEntry>();- if (messages != null) {- for (const message of messages) {- if (message?.messageId) {- const entry = toEntry(message);- if (entry.usage == null) {- entry.usage = stickyUsage(conversationId, message.messageId);- }- index.set(message.messageId, entry);- }- }- }- registry.set(conversationId, index);-}--/** Incremental upsert — final SSE events touch at most two entries */-export function upsertEntries(- conversationId: string,- messages: (Partial<TMessage> | null | undefined)[],-): void {- let index = registry.get(conversationId);- if (!index) {- index = new Map<string, TokenEntry>();- registry.set(conversationId, index);- }- for (const message of messages) {- if (message?.messageId) {- const entry = toEntry(message);- if (entry.usage == null) {- entry.usage = stickyUsage(conversationId, message.messageId);- }- index.set(message.messageId, entry);- }- }-}--/** Re-keys the index when `new` resolves to a real conversation id */-export function migrateIndex(fromId: string, toId: string): void {- if (fromId === toId) {- return;- }- const index = registry.get(fromId);- if (index) {- registry.delete(fromId);- registry.set(toId, index);- }- const usage = usageHistory.get(fromId);- if (usage) {- usageHistory.delete(fromId);- usageHistory.set(toId, usage);- }-}--export function clearIndex(conversationId: string): void {- registry.delete(conversationId);- usageHistory.delete(conversationId);-}--/** O(depth) walk from the branch tail up the parent chain */-export function sumBranch(- conversationId: string,- tailId: string | null | undefined,- anchorId?: string | null,-): BranchTotals {- const index = registry.get(conversationId);- if (!index || !tailId) {- return EMPTY_BRANCH;- }-- 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 lastTurnUsage = tailEntry?.isCreatedByUser === false ? tailEntry.usage : undefined;- 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. */- let contextCapped = false;- 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;- }- totals.total += 1;- /** Only match the anchor while still inside the active context window. An- * anchor OLDER than the deepest summary marker belongs to a pre-summary- * snapshot; treating it as on-branch would let `useTokenUsage` revive that- * stale breakdown (discarded history) over the summary-baseline estimate- * that `findBranchSnapshotAnchor` correctly refuses to recover. */- if (!contextCapped && anchorId != null && currentId === anchorId) {- totals.containsAnchor = true;- }- if (!contextCapped && entry.tokenCount > 0) {- totals.counted += 1;- if (entry.isCreatedByUser) {- totals.input += entry.tokenCount;- } else {- totals.output += entry.tokenCount;- }- } 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- * above; record the pre-invoke compacted baseline and stop counting context- * tokens for older (summarized-away) turns, but keep walking for cost. */- if (!contextCapped && entry.summaryUsedTokens != null) {- summaryBaseline = entry.summaryUsedTokens;- contextCapped = true;- }- currentId = entry.parentMessageId;- }-- return {- ...totals,- tailEstTokens,- tailEstToolTokens,- tailId,- usage,- lastTurnUsage,- summaryBaseline,- };-}--/**- * Message tokens that would actually be sent for an over-window branch. The send- * path prunes oldest-first to fit (`getMessagesWithinTokenLimit`), so walk the- * branch newest→oldest and stop once the next message would exceed `budget`,- * mirroring its "newest-that-fits" behavior for the gauge. Approximation: it omits- * the instruction/tool-schema overhead and tool-call pairing the real pruner also- * accounts for, which the client can't know for a snapshot-less branch — close- * enough for an estimate, and superseded by an exact snapshot once generated.- * `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`. 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,-): { tokens: number; toolTokens: number } {- const index = registry.get(conversationId);- if (!index || !tailId || budget <= 0) {- return { tokens: 0, toolTokens: 0 };- }-- let total = 0;- let toolTotal = 0;- let currentId: string | null = tailId;- let guard = index.size;- let isTail = true;-- while (currentId && currentId !== Constants.NO_PARENT && guard-- > 0) {- const entry: TokenEntry | undefined = index.get(currentId);- if (!entry) {- break;- }- const skip = isTail && excludeTail;- isTail = false;- if (!skip) {- const contribution = entry.tokenCount > 0 ? entry.tokenCount : entry.estTokens;- if (total + contribution > budget) {- 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`. */- if (entry.summaryUsedTokens != null && entry.summaryUsedTokens > 0) {- break;- }- currentId = entry.parentMessageId;- }- 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 instructions+summary+messages sum a snapshot saved before- * `remainingContextTokens` existed still supports. The two measure different- * quantities (the backend's remaining covers content the breakdown does not),- * so a growth delta may only compare readings of the same basis.- */-export interface AnchorReading {- used: number;- basis: 'remaining' | 'breakdown';- configuration?: string;-}--/** Compare the measured call configuration, including fixed prompt overhead.- * Older snapshots without call identity cannot establish comparability. */-export function snapshotConfiguration(- snapshot: Pick<TContextUsageEvent, 'model' | 'provider' | 'agentId' | 'contextBudget'> & {- breakdown?: Partial<TTokenBudgetBreakdown>;- },-): string | undefined {- if (!snapshot.model || !snapshot.provider) {- return undefined;- }- return JSON.stringify([- snapshot.model,- snapshot.provider,- snapshot.agentId,- snapshot.contextBudget ?? snapshot.breakdown?.maxContextTokens,- snapshot.breakdown?.instructionTokens,- snapshot.breakdown?.toolSchemaTokens,- ]);-}--/**- * Used-token readings for every persisted snapshot on the viewed branch, oldest- * → newest (the walk is tail→root, so results are reversed). Drives the growth- * sparkline and the runway projection in the breakdown. Stops after a summarized- * response — older snapshots describe discarded history, mirroring `sumBranch`.- * A snapshot that carries neither basis is skipped rather than reported as- * having consumed its entire budget.- */-export function collectAnchorSeries(- conversationId: string,- tailId: string | null | undefined,- anchors: ReadonlyMap<string, unknown>,-): AnchorReading[] {- const index = registry.get(conversationId);- if (!index || !tailId || anchors.size === 0) {- return [];- }-- const series: AnchorReading[] = [];- let currentId: string | null = tailId;- let guard = index.size;-- while (currentId && currentId !== Constants.NO_PARENT && guard-- > 0) {- const entry: TokenEntry | undefined = index.get(currentId);- if (!entry) {- break;- }- const snapshot = anchors.get(currentId) as- | (Partial<Omit<TContextUsageEvent, 'breakdown'>> & {- breakdown?: Partial<TTokenBudgetBreakdown>;- })- | undefined;- if (snapshot != null) {- const budget = normalizeTokenCount(- snapshot.contextBudget ?? snapshot.breakdown?.maxContextTokens,- );- const configuration = snapshotConfiguration(snapshot);- /** Runway growth keeps the raw remaining basis, even if the gauge floors- * that reading to the breakdown; older snapshots use all breakdown parts. */- 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?.summaryTokens) +- 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();-}--/**- * 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);-}--/**- * Sums provider usage/cost across EVERY message in the conversation (all- * branches, including regenerated/abandoned responses) — the conversation- * total, shown alongside the branch figure when they differ.- */-export function sumTotalUsage(conversationId: string): BranchUsage {- const usage: BranchUsage = { ...EMPTY_USAGE };- const index = registry.get(conversationId);- if (!index) {- return usage;- }- for (const entry of index.values()) {- addUsage(usage, entry.usage);- }- return usage;-}--/**- * Attaches a response's usage to its index entry AND the sticky usage history.- * Used by the live finalize/stop flush. The history copy lets `buildIndex`- * restore the usage after a rebuild (the persisted `metadata.usage` reaches- * `buildIndex` on reload; the sticky copy covers the in-session window before- * 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);- if (!history) {- history = new Map<string, BranchUsage>();- usageHistory.set(conversationId, history);- }- history.set(messageId, safeUsage);- const entry = registry.get(conversationId)?.get(messageId);- if (entry) {- entry.usage = safeUsage;- }-}--/**- * Walks the branch tail up the parent chain and returns the first message id- * present in `anchors` — i.e. the deepest (most recent) stored snapshot anchor- * on the viewed branch. Used to recover a branch's granular breakdown after a- * later generation on a sibling branch overwrote the live snapshot.- */-export function findBranchSnapshotAnchor(- conversationId: string,- tailId: string | null | undefined,- anchors: ReadonlyMap<string, unknown>,-): string | null {- const index = registry.get(conversationId);- if (!index || !tailId || anchors.size === 0) {- return null;- }-- let currentId: string | null = tailId;- let guard = index.size;-- while (currentId && currentId !== Constants.NO_PARENT && guard-- > 0) {- if (anchors.has(currentId)) {- return currentId;- }- const entry: TokenEntry | undefined = index.get(currentId);- if (!entry) {- break;- }- /** Stop at a summarized response that has no snapshot of its own: crossing it- * would recover an older PRE-summary snapshot (discarded history), which the- * summary-baseline estimate is meant to replace. */- if (entry.summaryUsedTokens != null) {- return null;- }- currentId = entry.parentMessageId;- }-- return null;-}--export interface ToolTokenGroups {- system: number;- mcp: number;- skills: number;- subagents: number;- systemDeferred: number;- mcpDeferred: number;-}--export const EMPTY_TOOL_GROUPS: ToolTokenGroups = {- system: 0,- mcp: 0,- skills: 0,- subagents: 0,- systemDeferred: 0,- mcpDeferred: 0,-};--/**- * Classifies per-tool schema tokens into display groups: built-in system- * tools, MCP tools, skills, and subagents — with deferred (on-demand) tools- * split out for the system/MCP groups.- */-export function groupToolTokens(- toolTokenCounts?: Record<string, number>,- deferredToolNames?: string[],-): ToolTokenGroups {- if (toolTokenCounts == null) {- return EMPTY_TOOL_GROUPS;- }- const deferred = new Set(deferredToolNames ?? []);- const groups = { ...EMPTY_TOOL_GROUPS };- for (const [name, rawTokens] of Object.entries(toolTokenCounts)) {- const tokens = normalizeTokenCount(rawTokens);- if (tokens === 0) {- continue;- }- if (name === Tools.skill) {- groups.skills += tokens;- } else if (name === Constants.SUBAGENT) {- groups.subagents += tokens;- } else if (name.includes(Constants.mcp_delimiter)) {- if (deferred.has(name)) {- groups.mcpDeferred += tokens;- } else {- groups.mcp += tokens;- }- } else if (deferred.has(name)) {- groups.systemDeferred += tokens;- } else {- groups.system += tokens;- }- }- return groups;-}--function getOutputChars(part: unknown): number | null {- if (part == null || typeof part !== 'object') {- return null;- }- const { text, think } = part as { text?: unknown; think?: unknown };- if (typeof text === 'string') {- return text.length;- }- if (typeof think === 'string') {- return think.length;- }- return null;-}--/**- * Chars of the contiguous text/think parts at the very END of aggregated- * content — the output the model is actively producing on the current call,- * which the latest pre-invoke context snapshot does not yet account for.- *- * Crucially this does NOT skip a trailing tool-call part: once the model has- * emitted a tool call, that call's text is already folded into the next- * snapshot's `messageTokens`, so counting it would double-count against the- * snapshot. A tool call at the end therefore yields 0 (nothing new in flight).- */-export function countTrailingOutputChars(content?: unknown[] | null): number {- if (!Array.isArray(content) || content.length === 0) {- return 0;- }- let chars = 0;- for (let i = content.length - 1; i >= 0; i--) {- const partChars = getOutputChars(content[i]);- if (partChars == null) {- break;- }- chars += partChars;- }- return chars;-}--/** Rough live estimate for streaming text, calibrated by the last known provider ratio */-export function estimateTokens(charCount: number, calibrationRatio = 1): number {- 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 */-export interface CostUnits {- input: number;- output: number;- cacheWrite: number;- cacheRead: number;-}--/**- * 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 — 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 = 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- ? inputTokensIncludesCache(usage.provider)- : cacheWrite + cacheRead <= rawInput;-- const cacheAdjustment = includesCache ? 0 : cacheRead + cacheWrite;- const output =- total > rawInput + rawOutput + cacheAdjustment ? total - rawInput - cacheAdjustment : rawOutput;-- return {- input: includesCache ? Math.max(0, rawInput - cacheRead - cacheWrite) : rawInput,- output,- cacheWrite,- cacheRead,- };-}+import { normalizeTokenCount } from '@librechat/chat';++export type {+ AnchorReading,+ BranchTotals,+ BranchUsage,+ CostUnits,+ TokenEntry,+ ToolTokenGroups,+} from '@librechat/chat';+export {+ EMPTY_BRANCH,+ EMPTY_TOOL_GROUPS,+ EMPTY_USAGE,+ addUsage,+ buildIndex,+ clearIndex,+ collectAnchorSeries,+ countTrailingOutputChars,+ estimateTokens,+ findBranchSnapshotAnchor,+ getOutputChars,+ groupToolTokens,+ hasKnownCost,+ latestExchangeTokens,+ mergeUsage,+ messageChars,+ messageToolChars,+ migrateIndex,+ normalizeTokenCount,+ normalizeUsageUnits,+ partTextChars,+ prunedBranchTokens,+ quoteChars,+ readPersistedUsage,+ registry,+ setEntryUsage,+ snapshotConfiguration,+ stickyUsage,+ sumBranch,+ sumTotalUsage,+ toEntry,+ toolCallLengths,+ upsertEntries,+ usageHistory,+} from '@librechat/chat';const tokenFormatter = new Intl.NumberFormat(undefined, {notation: 'compact',diff --git a/packages/chat/src/core/index.ts b/packages/chat/src/core/index.tsindex b1315a0e77..2c531f4964 100644--- a/packages/chat/src/core/index.ts+++ b/packages/chat/src/core/index.ts@@ -6,3 +6,4 @@ export * from './files';export * from './reducer';export * from './protocol';export * from './transport';+export * from './usage';diff --git a/packages/chat/src/core/usage/__tests__/tokens.spec.ts b/packages/chat/src/core/usage/__tests__/tokens.spec.tsnew file mode 100644index 0000000000..45f9ea7126--- /dev/null+++ b/packages/chat/src/core/usage/__tests__/tokens.spec.ts@@ -0,0 +1,1095 @@+import { Constants, Providers } from 'librechat-data-provider';+import type { TMessage, TResponseUsage } from 'librechat-data-provider';+import {+ sumBranch,+ setEntryUsage,+ sumTotalUsage,+ prunedBranchTokens,+ collectAnchorSeries,+ latestExchangeTokens,+ findBranchSnapshotAnchor,+} from '../branch';+import {+ estimateTokens,+ normalizeUsageUnits,+ groupToolTokens,+ countTrailingOutputChars,+ EMPTY_TOOL_GROUPS,+} from '../estimate';+import { buildIndex, upsertEntries, migrateIndex, clearIndex, mergeUsage } from '../registry';+import { EMPTY_BRANCH, EMPTY_USAGE } from '../types';++const CONVO = 'convo-1';++function msg(+ messageId: string,+ parentMessageId: string | null,+ isCreatedByUser: boolean,+ tokenCount?: number,+): TMessage {+ return {+ messageId,+ parentMessageId,+ isCreatedByUser,+ tokenCount,+ conversationId: CONVO,+ text: '',+ } as TMessage;+}++/** Response message carrying a persisted `metadata.usage` rollup (the backend+ * persists already-normalized display units). */+function responseMsg(+ messageId: string,+ parentMessageId: string | null,+ tokenCount: number,+ usage: TResponseUsage,+): TMessage {+ return {+ messageId,+ parentMessageId,+ isCreatedByUser: false,+ tokenCount,+ conversationId: CONVO,+ text: '',+ metadata: { usage },+ } as TMessage;+}++const USAGE_A: TResponseUsage = { input: 100, output: 50, cacheWrite: 0, cacheRead: 0, cost: 0.01 };+const USAGE_B: TResponseUsage = { input: 200, output: 80, cacheWrite: 0, cacheRead: 0, cost: 0.02 };++describe('token index', () => {+ afterEach(() => {+ clearIndex(CONVO);+ clearIndex('convo-2');+ clearIndex(Constants.NEW_CONVO);+ });++ it('sums only the active branch via the parent chain', () => {+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 10),+ msg('a1', 'u1', false, 20),+ msg('u2', 'a1', true, 30),+ msg('a2', 'u2', false, 40),+ /** Sibling branch that must not be counted */+ msg('a2-alt', 'u2', false, 999),+ ]);++ const totals = sumBranch(CONVO, 'a2');+ expect(totals.input).toBe(40);+ expect(totals.output).toBe(60);+ expect(totals.total).toBe(4);+ expect(totals.counted).toBe(4);++ const altTotals = sumBranch(CONVO, 'a2-alt');+ expect(altTotals.output).toBe(1019);+ });++ it('estimates count-less messages by text length without inflating counted totals', () => {+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 12),+ /** Imported message with no `tokenCount`: 40 chars of text → ~10 est tokens. */+ {+ messageId: 'a1',+ parentMessageId: 'u1',+ isCreatedByUser: false,+ conversationId: CONVO,+ text: 'x'.repeat(40),+ } as TMessage,+ ]);++ const totals = sumBranch(CONVO, 'a1');+ /** Known counts feed input/output/counted; the count-less message stays out+ * of those and lands in the separate (uncalibrated) estimate bucket. */+ expect(totals.input).toBe(12);+ expect(totals.output).toBe(0);+ expect(totals.counted).toBe(1);+ expect(totals.total).toBe(2);+ expect(totals.estTokens).toBe(10);+ });++ it('estimates object-form content text and merged quote excerpts', () => {+ buildIndex(CONVO, [+ /** Assistant body lives only in object-form content (`text.value`). */+ {+ messageId: 'a1',+ parentMessageId: Constants.NO_PARENT,+ isCreatedByUser: false,+ conversationId: CONVO,+ content: [{ type: 'text', text: { value: 'y'.repeat(20) } }],+ } as unknown as TMessage,+ /** User turn whose quotes are merged into the prompt at send time. */+ {+ messageId: 'u1',+ parentMessageId: 'a1',+ isCreatedByUser: true,+ conversationId: CONVO,+ text: 'z'.repeat(16),+ quotes: ['q'.repeat(8)],+ } as TMessage,+ ]);++ /** a1: 20 content chars / 4 = 5; u1: (16 text + 8 quote) / 4 = 6. */+ const totals = sumBranch(CONVO, 'u1');+ expect(totals.counted).toBe(0);+ expect(totals.estTokens).toBe(11);+ });++ it('recounts quoted user turns (ignoring stale counts), counts tool calls, skips reasoning', () => {+ buildIndex(CONVO, [+ /** Quoted user turn with a stale text-only stored count: the send path+ * recounts the merged prompt every turn, so the estimate ignores the count+ * and recounts from text+quotes. */+ {+ messageId: 'u1',+ parentMessageId: Constants.NO_PARENT,+ isCreatedByUser: true,+ conversationId: CONVO,+ tokenCount: 999,+ text: 'hi',+ quotes: ['q'.repeat(38)],+ } as TMessage,+ /** Count-less assistant turn: tool-call name/args/output count toward the+ * estimate (sent back as context); reasoning does not. */+ {+ messageId: 'a1',+ parentMessageId: 'u1',+ isCreatedByUser: false,+ conversationId: CONVO,+ content: [+ { type: 'think', think: 'r'.repeat(40) },+ { type: 'tool_call', tool_call: { name: 'sub', args: 'aa', output: 'o'.repeat(11) } },+ ],+ } as unknown as TMessage,+ ]);++ const totals = sumBranch(CONVO, 'a1');+ /** u1 quoted: stored 999 ignored; (2 text + 38 quote) / 4 = 10. a1 tool_call+ * name 3 + args 2 + output 11 = 16 / 4 = 4 (think skipped). */+ expect(totals.input).toBe(0);+ expect(totals.counted).toBe(0);+ expect(totals.estTokens).toBe(14);+ });++ it('prefers content over text for count-less messages carrying both', () => {+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 8),+ /** Stopped agent response: saved with both a short `text` and structured+ * `content` (a tool call). The send path formats from content, so the+ * estimate must use content (tool tokens), not the shorter text. */+ {+ messageId: 'a1',+ parentMessageId: 'u1',+ isCreatedByUser: false,+ conversationId: CONVO,+ text: 'hi',+ content: [+ { type: 'tool_call', tool_call: { name: 'run', args: 'aa', output: 'o'.repeat(13) } },+ ],+ } as unknown as TMessage,+ ]);++ const totals = sumBranch(CONVO, 'a1');+ /** a1 uses content (name 3 + args 2 + output 13 = 18 / 4 = 5), not text 'hi'. */+ expect(totals.input).toBe(8);+ expect(totals.estTokens).toBe(5);+ });++ it('estimates a previewed tool call from its stored lengths, not the preview', () => {+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 12),+ {+ messageId: 'a1',+ parentMessageId: 'u1',+ isCreatedByUser: false,+ conversationId: CONVO,+ text: '',+ content: [+ {+ type: 'tool_call',+ tool_call: {+ name: 'run',+ args: 'aa',+ argsTruncated: true,+ argsLength: 17,+ output: 'o…o',+ outputTruncated: true,+ outputLength: 20,+ },+ },+ ],+ } as unknown as TMessage,+ ]);++ /** name 3 + stored args 17 + stored output 20 = 40 chars / 4 = 10. */+ expect(sumBranch(CONVO, 'a1').estTokens).toBe(10);+ });++ it('exposes the count-less tail estimate so live output is not double-counted', () => {+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 12),+ /** In-flight / resumed response: count-less, so it lands in estTokens; it is+ * also covered by liveTokens, so the estimate path drops tailEstTokens. */+ {+ messageId: 'a1',+ parentMessageId: 'u1',+ isCreatedByUser: false,+ conversationId: CONVO,+ text: 'o'.repeat(20),+ } as TMessage,+ ]);++ const totals = sumBranch(CONVO, 'a1');+ /** a1 is the tail: 20 / 4 = 5, surfaced both in estTokens and tailEstTokens. */+ expect(totals.estTokens).toBe(5);+ 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 = () =>+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 2),+ msg('a1', 'u1', false, 10),+ msg('u2', 'a1', true, 2),+ msg('a2', 'u2', false, 2),+ ]);++ 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)).toEqual({ tokens: 4, toolTokens: 0 });+ });++ it('returns the full branch sum when it fits the budget', () => {+ buildChain();+ 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)).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,+ });+ });+ });++ it('caps the branch at a summary marker instead of re-summing compacted history', () => {+ const summarized = {+ messageId: 'a2',+ parentMessageId: 'u2',+ isCreatedByUser: false,+ tokenCount: 40,+ conversationId: CONVO,+ text: '',+ /** a2's turn compacted the history; pre-invoke context was 500 tokens. */+ metadata: { summaryUsedTokens: 500 },+ } as TMessage;+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 100),+ msg('a1', 'u1', false, 9000) /** huge pre-summary history, now discarded */,+ msg('u2', 'a1', true, 200),+ summarized,+ msg('u3', 'a2', true, 15),+ msg('a3', 'u3', false, 25),+ ]);++ const totals = sumBranch(CONVO, 'a3');+ /** Walk stops at a2: only its output + the post-summary turn are summed. */+ expect(totals.summaryBaseline).toBe(500);+ expect(totals.input).toBe(15);+ expect(totals.output).toBe(65); // a3 (25) + a2 (40)+ /** Estimate used = post-summary + compacted baseline = 580, not the 9380+ * raw history sum that pinned the gauge at 100%. */+ expect(totals.input + totals.output + totals.summaryBaseline).toBe(580);+ });++ it('keeps provider usage/cost across the full branch even past a summary marker', () => {+ const summarized = {+ messageId: 'a2',+ parentMessageId: 'u2',+ isCreatedByUser: false,+ tokenCount: 40,+ conversationId: CONVO,+ text: '',+ metadata: { usage: USAGE_B, summaryUsedTokens: 500 },+ } as TMessage;+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 10),+ responseMsg('a1', 'u1', 9000, USAGE_A) /** pre-summary spend */,+ msg('u2', 'a1', true, 200),+ summarized,+ msg('u3', 'a2', true, 15),+ responseMsg('a3', 'u3', 25, USAGE_A) /** post-summary spend */,+ ]);++ const totals = sumBranch(CONVO, 'a3');+ /** Context is capped at the marker... */+ expect(totals.summaryBaseline).toBe(500);+ /** ...but cost/usage is cumulative spend and spans the WHOLE branch+ * (a1 + a2 + a3 = 0.01 + 0.02 + 0.01), not truncated at the summary boundary. */+ expect(totals.usage.cost).toBeCloseTo(0.04);+ expect(totals.usage.input).toBe(400); // 100 + 200 + 100+ });++ it('flags whether the anchor message is on the branch', () => {+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 10),+ msg('a1', 'u1', false, 20),+ msg('a1-alt', 'u1', false, 25),+ ]);++ expect(sumBranch(CONVO, 'a1', 'a1').containsAnchor).toBe(true);+ expect(sumBranch(CONVO, 'a1-alt', 'a1').containsAnchor).toBe(false);+ });++ it('stops matching the anchor once the context is capped at a summary marker', () => {+ const summarized = {+ messageId: 'a2',+ parentMessageId: 'u2',+ isCreatedByUser: false,+ tokenCount: 40,+ conversationId: CONVO,+ text: '',+ metadata: { summaryUsedTokens: 500 },+ } as TMessage;+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 100),+ msg('a1', 'u1', false, 20),+ msg('u2', 'a1', true, 200),+ summarized,+ msg('u3', 'a2', true, 15),+ msg('a3', 'u3', false, 25),+ ]);+ /** a1 is older than the summary marker (a2): a snapshot anchored there is+ * pre-summary, so it must NOT count as on-branch, else useTokenUsage revives+ * that stale breakdown over the summary-baseline estimate. */+ expect(sumBranch(CONVO, 'a3', 'a1').containsAnchor).toBe(false);+ /** The summarized response's own (post-summary) snapshot still matches... */+ expect(sumBranch(CONVO, 'a3', 'a2').containsAnchor).toBe(true);+ /** ...as does a snapshot from a newer turn. */+ expect(sumBranch(CONVO, 'a3', 'a3').containsAnchor).toBe(true);+ });++ it('tracks uncounted messages and tolerates missing parents', () => {+ buildIndex(CONVO, [msg('u2', 'missing-parent', true, undefined), msg('a2', 'u2', false, 15)]);++ const totals = sumBranch(CONVO, 'a2');+ expect(totals.total).toBe(2);+ expect(totals.counted).toBe(1);+ expect(totals.output).toBe(15);+ });++ it('returns EMPTY_BRANCH without an index or tail', () => {+ expect(sumBranch('unknown', 'x')).toBe(EMPTY_BRANCH);+ buildIndex(CONVO, []);+ expect(sumBranch(CONVO, null)).toBe(EMPTY_BRANCH);+ });++ it('upserts incrementally and overwrites by messageId', () => {+ buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10)]);+ upsertEntries(CONVO, [msg('a1', 'u1', false, 20), null, undefined]);+ expect(sumBranch(CONVO, 'a1').output).toBe(20);++ upsertEntries(CONVO, [msg('a1', 'u1', false, 35)]);+ expect(sumBranch(CONVO, 'a1').output).toBe(35);+ });++ it('migrates the index to a new conversation id', () => {+ buildIndex(Constants.NEW_CONVO, [msg('u1', Constants.NO_PARENT, true, 10)]);+ migrateIndex(Constants.NEW_CONVO, 'convo-2');++ expect(sumBranch(Constants.NEW_CONVO, 'u1').input).toBe(0);+ expect(sumBranch('convo-2', 'u1').input).toBe(10);+ });+});++describe('findBranchSnapshotAnchor', () => {+ afterEach(() => clearIndex(CONVO));++ it('returns the deepest stored anchor on the viewed branch', () => {+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 10),+ msg('a1', 'u1', false, 20),+ msg('u2', 'a1', true, 30),+ msg('a2', 'u2', false, 40),+ msg('a2-alt', 'u2', false, 50),+ ]);+ /** Both a1 and a2 stored; walking from a2 must return the nearer one (a2). */+ const anchors = new Map([+ ['a1', 1],+ ['a2', 1],+ ]);+ expect(findBranchSnapshotAnchor(CONVO, 'a2', anchors)).toBe('a2');+ /** From the sibling branch tail, the only on-branch anchor is a1. */+ expect(findBranchSnapshotAnchor(CONVO, 'a2-alt', anchors)).toBe('a1');+ });++ it('returns null when no stored anchor sits on the branch', () => {+ buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10), msg('a1', 'u1', false, 20)]);+ expect(findBranchSnapshotAnchor(CONVO, 'a1', new Map([['other', 1]]))).toBeNull();+ expect(findBranchSnapshotAnchor(CONVO, 'a1', new Map())).toBeNull();+ expect(findBranchSnapshotAnchor('unknown', 'a1', new Map([['a1', 1]]))).toBeNull();+ });++ it('does not cross a summary marker to recover a stale pre-summary snapshot', () => {+ const summarized = {+ messageId: 'a2',+ parentMessageId: 'u2',+ isCreatedByUser: false,+ tokenCount: 40,+ conversationId: CONVO,+ text: '',+ metadata: { summaryUsedTokens: 500 },+ } as TMessage;+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 10),+ msg('a1', 'u1', false, 20) /** has a snapshot, but pre-summary */,+ msg('u2', 'a1', true, 30),+ summarized /** compacted here, no snapshot of its own */,+ msg('u3', 'a2', true, 15),+ msg('a3', 'u3', false, 25),+ ]);+ /** a1 is the only stored anchor, but it sits before the summary, the walk+ * must stop at a2 and return null so the summary-baseline estimate is used. */+ expect(findBranchSnapshotAnchor(CONVO, 'a3', new Map([['a1', 1]]))).toBeNull();+ /** When the summarized response itself has a snapshot, return it. */+ expect(findBranchSnapshotAnchor(CONVO, 'a3', new Map([['a2', 1]]))).toBe('a2');+ });+});++describe('estimateTokens', () => {+ it('estimates chars/4 scaled by calibration ratio', () => {+ expect(estimateTokens(400)).toBe(100);+ expect(estimateTokens(400, 1.1)).toBe(110);+ expect(estimateTokens(0)).toBe(0);+ expect(estimateTokens(100, 0)).toBe(25);+ });+});++describe('normalizeUsageUnits', () => {+ it('subtracts cache from input for Anthropic (input_tokens is cache-inclusive)', () => {+ /** The agents SDK folds cache into Anthropic input_tokens, so cache is a+ * subset of input and must be subtracted: 900 − 100 read = 800. */+ expect(+ normalizeUsageUnits({+ input_tokens: 900,+ output_tokens: 100,+ provider: Providers.ANTHROPIC,+ input_token_details: { cache_read: 100 },+ }),+ ).toEqual({ input: 800, output: 100, cacheWrite: 0, cacheRead: 100 });+ });++ it('keeps cache additive for Bedrock (Converse input_tokens excludes cache)', () => {+ expect(+ normalizeUsageUnits({+ input_tokens: 900,+ output_tokens: 100,+ provider: Providers.BEDROCK,+ input_token_details: { cache_read: 100 },+ }),+ ).toEqual({ input: 900, output: 100, cacheWrite: 0, cacheRead: 100 });+ });++ it('keeps subset semantics for OpenAI regardless of magnitude', () => {+ expect(+ normalizeUsageUnits({+ input_tokens: 900,+ output_tokens: 100,+ provider: Providers.OPENAI,+ input_token_details: { cache_read: 100 },+ }),+ ).toEqual({ input: 800, output: 100, cacheWrite: 0, cacheRead: 100 });+ });++ it('falls back to a magnitude heuristic when provider is unknown', () => {+ /** cacheSum (12000) > input (1000) ⇒ additive */+ expect(+ normalizeUsageUnits({+ input_tokens: 1000,+ output_tokens: 500,+ input_token_details: { cache_creation: 2000, cache_read: 10000 },+ }),+ ).toEqual({ input: 1000, output: 500, cacheWrite: 2000, cacheRead: 10000 });+ });++ it('repairs under-reported completion tokens (Vertex thinking)', () => {+ /** total - input = 500 recovers the dropped thinking tokens */+ expect(+ normalizeUsageUnits({+ input_tokens: 1000,+ output_tokens: 200,+ total_tokens: 1500,+ provider: Providers.VERTEXAI,+ }).output,+ ).toBe(500);+ });++ it('does not mistake additive cache for missing completion tokens (Bedrock)', () => {+ /** Bedrock keeps cache separate, so total = input + output + cache (1700).+ * Without the cache adjustment the repair would falsely inflate completion. */+ expect(+ normalizeUsageUnits({+ input_tokens: 1000,+ output_tokens: 200,+ total_tokens: 1700,+ provider: Providers.BEDROCK,+ input_token_details: { cache_creation: 300, cache_read: 200 },+ }).output,+ ).toBe(200);+ });++ it('does not inflate completion for cache-inclusive Anthropic totals', () => {+ /** Anthropic total already includes cache (input 1000 covers the 500 cache),+ * so total 1200 leaves output at 200, no false repair. */+ expect(+ normalizeUsageUnits({+ input_tokens: 1000,+ output_tokens: 200,+ total_tokens: 1200,+ provider: Providers.ANTHROPIC,+ input_token_details: { cache_creation: 300, cache_read: 200 },+ }).output,+ ).toBe(200);+ });+});++describe('groupToolTokens', () => {+ it('classifies tools into system, mcp, skills, and subagent groups', () => {+ const groups = groupToolTokens(+ {+ execute_code: 500,+ web_search: 300,+ skill: 200,+ subagent: 150,+ 'search_mcp_Google-Workspace': 400,+ fetch_mcp_Github: 250,+ },+ ['fetch_mcp_Github', 'web_search'],+ );++ expect(groups).toEqual({+ system: 500,+ mcp: 400,+ skills: 200,+ subagents: 150,+ systemDeferred: 300,+ mcpDeferred: 250,+ });+ });++ it('returns empty groups without counts and skips zero entries', () => {+ 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', () => {+ const text = (value: string) => ({ type: 'text', text: value });+ const think = (value: string) => ({ type: 'think', think: value });+ const tool = () => ({ type: 'tool_call', tool_call: { id: 'tc' } });++ it('counts the trailing run of text and think parts', () => {+ expect(countTrailingOutputChars([text('aaaa'), tool(), think('bb'), text('ccc')])).toBe(5);+ });++ it('returns 0 when the latest part is a tool call (no in-flight output)', () => {+ /** Once a tool call is emitted, its preceding text is folded into the next+ * snapshot's messageTokens, counting it here would double-count. */+ expect(countTrailingOutputChars([text('aaaa'), tool(), text('ccc'), tool()])).toBe(0);+ });++ it('stops at the previous tool boundary', () => {+ expect(countTrailingOutputChars([text('aaaa'), tool(), text('ccc')])).toBe(3);+ });++ it('handles empty and non-output content', () => {+ expect(countTrailingOutputChars(undefined)).toBe(0);+ expect(countTrailingOutputChars([])).toBe(0);+ expect(countTrailingOutputChars([tool()])).toBe(0);+ });+});++describe('per-message usage index (branch + total)', () => {+ afterEach(() => {+ clearIndex(CONVO);+ });++ it('reads metadata.usage onto entries and sums it along the branch', () => {+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 10),+ responseMsg('a1', 'u1', 50, USAGE_A),+ msg('u2', 'a1', true, 30),+ responseMsg('a2', 'u2', 80, USAGE_B),+ ]);++ const { usage } = sumBranch(CONVO, 'a2');+ expect(usage).toEqual({+ input: 300,+ output: 130,+ cacheWrite: 0,+ cacheRead: 0,+ cost: 0.03,+ costKnown: true,+ });+ });++ it('reads persisted display units (incl. cache) directly', () => {+ /** The backend already normalized per-event; the client reads as-is */+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 10),+ responseMsg('a1', 'u1', 100, {+ input: 600,+ output: 100,+ cacheWrite: 0,+ cacheRead: 400,+ cost: 0.03,+ }),+ ]);++ const { usage } = sumBranch(CONVO, 'a1');+ expect(usage).toEqual({+ input: 600,+ output: 100,+ cacheWrite: 0,+ cacheRead: 400,+ cost: 0.03,+ costKnown: true,+ });+ });++ it('marks cost unknown when persisted usage omits cost (contextCost off)', () => {+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 10),+ responseMsg('a1', 'u1', 50, { input: 100, output: 50, cacheWrite: 0, cacheRead: 0 }),+ ]);+ const { usage } = sumBranch(CONVO, 'a1');+ expect(usage.costKnown).toBe(false);+ expect(usage.cost).toBe(0);+ 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);+ expect(sumTotalUsage(CONVO)).toEqual(EMPTY_USAGE);+ });++ it('selects only the viewed response as the last turn across compaction and regeneration', () => {+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 10),+ responseMsg('a1', 'u1', 50, USAGE_A),+ msg('u2', 'a1', true, 20),+ {+ ...responseMsg('a2', 'u2', 80, { ...USAGE_B, cacheRead: 400, cacheWrite: 30 }),+ metadata: {+ usage: { ...USAGE_B, cacheRead: 400, cacheWrite: 30 },+ summaryUsedTokens: 500,+ },+ },+ responseMsg('a2-alt', 'u2', 60, { ...USAGE_A, cost: 0 }),+ ]);++ expect(sumBranch(CONVO, 'a2').lastTurnUsage).toEqual({+ input: 200,+ output: 80,+ cacheRead: 400,+ cacheWrite: 30,+ cost: 0.02,+ costKnown: true,+ });+ expect(sumBranch(CONVO, 'a2').usage.input).toBe(300);+ expect(sumBranch(CONVO, 'a2-alt').lastTurnUsage?.cost).toBe(0);+ expect(sumBranch(CONVO, 'u2').lastTurnUsage).toBeUndefined();+ expect(sumTotalUsage(CONVO).cacheRead).toBe(400);+ });++ it('does not borrow an ancestor response when the selected tail has no usage', () => {+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 10),+ responseMsg('a1', 'u1', 50, USAGE_A),+ msg('u2', 'a1', true, 10),+ msg('a2', 'u2', false, 20),+ ]);+ expect(sumBranch(CONVO, 'a2').lastTurnUsage).toBeUndefined();+ expect(sumBranch(CONVO, 'a2').usage.cost).toBe(0.01);+ expect(sumBranch(CONVO, 'u2').lastTurnUsage).toBeUndefined();+ });++ it('preserves a prior entry usage when a rebuilt message lacks metadata.usage', () => {+ /** Live finalize flushes usage into the index before persisted metadata+ * reaches the cache; a mid-session rebuild from a cache message without+ * metadata.usage must not wipe it (regenerate keeps the sibling's cost). */+ buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10), msg('a1', 'u1', false, 50)]);+ setEntryUsage(CONVO, 'a1', {+ input: 100,+ output: 50,+ cacheWrite: 0,+ cacheRead: 0,+ cost: 0.01,+ costKnown: true,+ });+ /** Rebuild from the same cache (still no metadata.usage on a1) */+ buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10), msg('a1', 'u1', false, 50)]);+ expect(sumBranch(CONVO, 'a1').usage.cost).toBeCloseTo(0.01);+ expect(sumBranch(CONVO, 'a1').usage.input).toBe(100);+ expect(sumBranch(CONVO, 'a1').lastTurnUsage?.cost).toBeCloseTo(0.01);+ });++ it('restores branch cost from sticky history after regenerate drops then re-adds a sibling', () => {+ /** a1 generated live; its cache message never carries metadata.usage */+ buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10), msg('a1', 'u1', false, 50)]);+ setEntryUsage(CONVO, 'a1', {+ input: 100,+ output: 50,+ cacheWrite: 0,+ cacheRead: 0,+ cost: 0.01,+ costKnown: true,+ });++ /** Regenerate streaming shows only the active branch, a1 is dropped */+ buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10), msg('a1-alt', 'u1', false, 60)]);+ expect(sumBranch(CONVO, 'a1').usage).toEqual(EMPTY_USAGE);++ /** Post-regenerate full rebuild re-adds a1 (still no metadata.usage) */+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 10),+ msg('a1', 'u1', false, 50),+ msg('a1-alt', 'u1', false, 60),+ ]);++ /** Switching back to branch A must still show its cost (the reported bug) */+ expect(sumBranch(CONVO, 'a1').usage.cost).toBeCloseTo(0.01);+ expect(sumBranch(CONVO, 'a1').usage.input).toBe(100);+ });++ it('scopes branch usage to the active thread while total spans all branches', () => {+ /** Regenerate: a1 and a1-alt are sibling responses under the same user msg */+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 10),+ responseMsg('a1', 'u1', 50, USAGE_A),+ responseMsg('a1-alt', 'u1', 80, USAGE_B),+ ]);++ /** Viewing branch B (the regenerated response) */+ expect(sumBranch(CONVO, 'a1-alt').usage.cost).toBeCloseTo(0.02);+ /** Viewing branch A (the original) */+ expect(sumBranch(CONVO, 'a1').usage.cost).toBeCloseTo(0.01);+ /** Total spans both abandoned + active branches */+ const total = sumTotalUsage(CONVO);+ expect(total.cost).toBeCloseTo(0.03);+ expect(total.input).toBe(300);+ expect(total.output).toBe(130);+ });++ it('is idempotent across rebuilds', () => {+ const messages = [+ msg('u1', Constants.NO_PARENT, true, 10),+ responseMsg('a1', 'u1', 50, USAGE_A),+ responseMsg('a1-alt', 'u1', 80, USAGE_B),+ ];+ buildIndex(CONVO, messages);+ const first = sumTotalUsage(CONVO);+ buildIndex(CONVO, messages);+ const second = sumTotalUsage(CONVO);+ expect(second).toEqual(first);+ });++ it('flushes a live response usage via setEntryUsage (no metadata yet)', () => {+ buildIndex(CONVO, [msg('u1', Constants.NO_PARENT, true, 10), msg('a1', 'u1', false, 50)]);+ /** Live response entry has no metadata.usage until persisted; finalize flushes it */+ expect(sumBranch(CONVO, 'a1').usage).toEqual(EMPTY_USAGE);+ setEntryUsage(CONVO, 'a1', {+ input: 100,+ output: 50,+ cacheWrite: 0,+ cacheRead: 0,+ cost: 0.01,+ costKnown: true,+ });+ expect(sumBranch(CONVO, 'a1').usage.cost).toBeCloseTo(0.01);+ expect(sumBranch(CONVO, 'a1').usage.input).toBe(100);+ });++ it('mergeUsage sums records and ANDs costKnown (incomplete coverage wins)', () => {+ const a = { input: 1, output: 2, cacheWrite: 3, cacheRead: 4, cost: 0.5, costKnown: false };+ const b = { input: 10, output: 20, cacheWrite: 30, cacheRead: 40, cost: 1.5, costKnown: true };+ expect(mergeUsage(a, b)).toEqual({+ input: 11,+ output: 22,+ cacheWrite: 33,+ cacheRead: 44,+ cost: 2,+ costKnown: false,+ });+ });++ it('marks branch cost incomplete when any usage-bearing entry lacks cost', () => {+ /** A turn saved before cost display was on (no cost) alongside one with cost+ * → the summed cost under-reports, so coverage is incomplete. */+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 10),+ responseMsg('a1', 'u1', 50, { input: 100, output: 50, cacheWrite: 0, cacheRead: 0 }),+ responseMsg('a2', 'a1', 60, USAGE_B),+ ]);+ const { usage } = sumBranch(CONVO, 'a2');+ expect(usage.costKnown).toBe(false);+ /** Cost still sums what it can, but coverage is flagged incomplete */+ expect(usage.cost).toBeCloseTo(0.02);+ expect(sumTotalUsage(CONVO).costKnown).toBe(false);+ });++ it('EMPTY_BRANCH carries an empty usage record', () => {+ expect(sumBranch('missing-convo', 'x')).toBe(EMPTY_BRANCH);+ expect(EMPTY_BRANCH.usage).toEqual(EMPTY_USAGE);+ });++ it('collectAnchorSeries reads used tokens per anchor, oldest → newest', () => {+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 4),+ msg('a1', 'u1', false, 10),+ msg('u2', 'a1', true, 4),+ msg('a2', 'u2', false, 20),+ msg('u3', 'a2', true, 4),+ msg('a3', 'u3', false, 30),+ ]);+ const snap = (remaining: number) => ({+ contextBudget: 1000,+ remainingContextTokens: remaining,+ breakdown: { maxContextTokens: 1000 },+ });+ const anchors = new Map([+ ['a1', snap(960)],+ ['a2', snap(920)],+ ['a3', snap(860)],+ ]);++ const series = collectAnchorSeries(CONVO, 'a3', anchors);+ /** used = budget − remaining: 40 → 80 → 140, oldest first */+ expect(series).toEqual([+ { used: 40, basis: 'remaining' },+ { used: 80, basis: 'remaining' },+ { used: 140, basis: 'remaining' },+ ]);+ expect(collectAnchorSeries(CONVO, 'a3', new Map())).toEqual([]);+ });++ it('collectAnchorSeries derives a snapshot saved without remaining headroom', () => {+ buildIndex(CONVO, [+ msg('u1', Constants.NO_PARENT, true, 4),+ msg('a1', 'u1', false, 10),+ msg('u2', 'a1', true, 4),+ msg('a2', 'u2', false, 20),+ ]);+ const anchors = new Map<string, unknown>([+ /** The older shape: a budget and a breakdown, no remaining count. Read as+ * zero remaining it would claim the whole 1000-token window was spent. */+ [+ 'a1',+ {+ contextBudget: 1000,+ breakdown: {+ maxContextTokens: 1000,+ instructionTokens: 100,+ summaryTokens: 25,+ 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: 185, 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/packages/chat/src/core/usage/__tests__/view.spec.ts b/packages/chat/src/core/usage/__tests__/view.spec.tsnew file mode 100644index 0000000000..3ab41ebbf0--- /dev/null+++ b/packages/chat/src/core/usage/__tests__/view.spec.ts@@ -0,0 +1,30 @@+import { pendingToBranchUsage } from '../view';++describe('pendingToBranchUsage', () => {+ it('normalizes counts and marks cost known only when every event carried one', () => {+ const usage = pendingToBranchUsage({+ input: 10,+ output: -3,+ cacheWrite: 1,+ cacheRead: 2,+ eventCount: 2,+ costUSD: 0.5,+ costKnown: true,+ });+ expect(usage).toMatchObject({ input: 10, output: 0, cacheWrite: 1, cacheRead: 2, cost: 0.5 });+ expect(usage.costKnown).toBe(true);+ });++ it('reports zero cost for a non-positive or non-finite figure', () => {+ const base = {+ input: 0,+ output: 0,+ cacheWrite: 0,+ cacheRead: 0,+ eventCount: 1,+ costKnown: false,+ };+ expect(pendingToBranchUsage({ ...base, costUSD: Number.NaN }).cost).toBe(0);+ expect(pendingToBranchUsage({ ...base, costUSD: 0 }).costKnown).toBe(false);+ });+});diff --git a/packages/chat/src/core/usage/branch.ts b/packages/chat/src/core/usage/branch.tsnew file mode 100644index 0000000000..3b9498f60d--- /dev/null+++ b/packages/chat/src/core/usage/branch.ts@@ -0,0 +1,392 @@+import { Constants } from 'librechat-data-provider';+import type { TContextUsageEvent, TTokenBudgetBreakdown } from 'librechat-data-provider';+import {+ BranchTotals,+ BranchUsage,+ EMPTY_BRANCH,+ EMPTY_USAGE,+ TokenEntry,+ normalizeTokenCount,+} from './types';+import { addUsage, registry, usageHistory } from './registry';++/** O(depth) walk from the branch tail up the parent chain */+export function sumBranch(+ conversationId: string,+ tailId: string | null | undefined,+ anchorId?: string | null,+): BranchTotals {+ const index = registry.get(conversationId);+ if (!index || !tailId) {+ return EMPTY_BRANCH;+ }++ 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 lastTurnUsage = tailEntry?.isCreatedByUser === false ? tailEntry.usage : undefined;+ 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. */+ let contextCapped = false;+ 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;+ }+ totals.total += 1;+ /** Only match the anchor while still inside the active context window. An+ * anchor OLDER than the deepest summary marker belongs to a pre-summary+ * snapshot; treating it as on-branch would let `useTokenUsage` revive that+ * stale breakdown (discarded history) over the summary-baseline estimate+ * that `findBranchSnapshotAnchor` correctly refuses to recover. */+ if (!contextCapped && anchorId != null && currentId === anchorId) {+ totals.containsAnchor = true;+ }+ if (!contextCapped && entry.tokenCount > 0) {+ totals.counted += 1;+ if (entry.isCreatedByUser) {+ totals.input += entry.tokenCount;+ } else {+ totals.output += entry.tokenCount;+ }+ } 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+ * above; record the pre-invoke compacted baseline and stop counting context+ * tokens for older (summarized-away) turns, but keep walking for cost. */+ if (!contextCapped && entry.summaryUsedTokens != null) {+ summaryBaseline = entry.summaryUsedTokens;+ contextCapped = true;+ }+ currentId = entry.parentMessageId;+ }++ return {+ ...totals,+ tailEstTokens,+ tailEstToolTokens,+ tailId,+ usage,+ lastTurnUsage,+ summaryBaseline,+ };+}++/**+ * Message tokens that would actually be sent for an over-window branch. The send+ * path prunes oldest-first to fit (`getMessagesWithinTokenLimit`), so walk the+ * branch newest→oldest and stop once the next message would exceed `budget`,+ * mirroring its "newest-that-fits" behavior for the gauge. Approximation: it omits+ * the instruction/tool-schema overhead and tool-call pairing the real pruner also+ * accounts for, which the client can't know for a snapshot-less branch, close+ * enough for an estimate, and superseded by an exact snapshot once generated.+ * `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`. 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,+): { tokens: number; toolTokens: number } {+ const index = registry.get(conversationId);+ if (!index || !tailId || budget <= 0) {+ return { tokens: 0, toolTokens: 0 };+ }++ let total = 0;+ let toolTotal = 0;+ let currentId: string | null = tailId;+ let guard = index.size;+ let isTail = true;++ while (currentId && currentId !== Constants.NO_PARENT && guard-- > 0) {+ const entry: TokenEntry | undefined = index.get(currentId);+ if (!entry) {+ break;+ }+ const skip = isTail && excludeTail;+ isTail = false;+ if (!skip) {+ const contribution = entry.tokenCount > 0 ? entry.tokenCount : entry.estTokens;+ if (total + contribution > budget) {+ 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`. */+ if (entry.summaryUsedTokens != null && entry.summaryUsedTokens > 0) {+ break;+ }+ currentId = entry.parentMessageId;+ }+ 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 instructions+summary+messages sum a snapshot saved before+ * `remainingContextTokens` existed still supports. The two measure different+ * quantities (the backend's remaining covers content the breakdown does not),+ * so a growth delta may only compare readings of the same basis.+ */+export interface AnchorReading {+ used: number;+ basis: 'remaining' | 'breakdown';+ configuration?: string;+}++/** Compare the measured call configuration, including fixed prompt overhead.+ * Older snapshots without call identity cannot establish comparability. */+export function snapshotConfiguration(+ snapshot: Pick<TContextUsageEvent, 'model' | 'provider' | 'agentId' | 'contextBudget'> & {+ breakdown?: Partial<TTokenBudgetBreakdown>;+ },+): string | undefined {+ if (!snapshot.model || !snapshot.provider) {+ return undefined;+ }+ return JSON.stringify([+ snapshot.model,+ snapshot.provider,+ snapshot.agentId,+ snapshot.contextBudget ?? snapshot.breakdown?.maxContextTokens,+ snapshot.breakdown?.instructionTokens,+ snapshot.breakdown?.toolSchemaTokens,+ ]);+}++/**+ * Used-token readings for every persisted snapshot on the viewed branch, oldest+ * → newest (the walk is tail→root, so results are reversed). Drives the growth+ * sparkline and the runway projection in the breakdown. Stops after a summarized+ * response, older snapshots describe discarded history, mirroring `sumBranch`.+ * A snapshot that carries neither basis is skipped rather than reported as+ * having consumed its entire budget.+ */+export function collectAnchorSeries(+ conversationId: string,+ tailId: string | null | undefined,+ anchors: ReadonlyMap<string, unknown>,+): AnchorReading[] {+ const index = registry.get(conversationId);+ if (!index || !tailId || anchors.size === 0) {+ return [];+ }++ const series: AnchorReading[] = [];+ let currentId: string | null = tailId;+ let guard = index.size;++ while (currentId && currentId !== Constants.NO_PARENT && guard-- > 0) {+ const entry: TokenEntry | undefined = index.get(currentId);+ if (!entry) {+ break;+ }+ const snapshot = anchors.get(currentId) as+ | (Partial<Omit<TContextUsageEvent, 'breakdown'>> & {+ breakdown?: Partial<TTokenBudgetBreakdown>;+ })+ | undefined;+ if (snapshot != null) {+ const budget = normalizeTokenCount(+ snapshot.contextBudget ?? snapshot.breakdown?.maxContextTokens,+ );+ const configuration = snapshotConfiguration(snapshot);+ /** Runway growth keeps the raw remaining basis, even if the gauge floors+ * that reading to the breakdown; older snapshots use all breakdown parts. */+ 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?.summaryTokens) ++ 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();+}++/**+ * 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);+}++/**+ * Sums provider usage/cost across EVERY message in the conversation (all+ * branches, including regenerated/abandoned responses), the conversation+ * total, shown alongside the branch figure when they differ.+ */+export function sumTotalUsage(conversationId: string): BranchUsage {+ const usage: BranchUsage = { ...EMPTY_USAGE };+ const index = registry.get(conversationId);+ if (!index) {+ return usage;+ }+ for (const entry of index.values()) {+ addUsage(usage, entry.usage);+ }+ return usage;+}++/**+ * Attaches a response's usage to its index entry AND the sticky usage history.+ * Used by the live finalize/stop flush. The history copy lets `buildIndex`+ * restore the usage after a rebuild (the persisted `metadata.usage` reaches+ * `buildIndex` on reload; the sticky copy covers the in-session window before+ * 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);+ if (!history) {+ history = new Map<string, BranchUsage>();+ usageHistory.set(conversationId, history);+ }+ history.set(messageId, safeUsage);+ const entry = registry.get(conversationId)?.get(messageId);+ if (entry) {+ entry.usage = safeUsage;+ }+}++/**+ * Walks the branch tail up the parent chain and returns the first message id+ * present in `anchors`, i.e. the deepest (most recent) stored snapshot anchor+ * on the viewed branch. Used to recover a branch's granular breakdown after a+ * later generation on a sibling branch overwrote the live snapshot.+ */+export function findBranchSnapshotAnchor(+ conversationId: string,+ tailId: string | null | undefined,+ anchors: ReadonlyMap<string, unknown>,+): string | null {+ const index = registry.get(conversationId);+ if (!index || !tailId || anchors.size === 0) {+ return null;+ }++ let currentId: string | null = tailId;+ let guard = index.size;++ while (currentId && currentId !== Constants.NO_PARENT && guard-- > 0) {+ if (anchors.has(currentId)) {+ return currentId;+ }+ const entry: TokenEntry | undefined = index.get(currentId);+ if (!entry) {+ break;+ }+ /** Stop at a summarized response that has no snapshot of its own: crossing it+ * would recover an older PRE-summary snapshot (discarded history), which the+ * summary-baseline estimate is meant to replace. */+ if (entry.summaryUsedTokens != null) {+ return null;+ }+ currentId = entry.parentMessageId;+ }++ return null;+}diff --git a/packages/chat/src/core/usage/estimate.ts b/packages/chat/src/core/usage/estimate.tsnew file mode 100644index 0000000000..6b06a23360--- /dev/null+++ b/packages/chat/src/core/usage/estimate.ts@@ -0,0 +1,154 @@+import { Tools, Constants, inputTokensIncludesCache } from 'librechat-data-provider';+import type { TTokenUsageEvent } from 'librechat-data-provider';+import { normalizeTokenCount } from './types';++export interface ToolTokenGroups {+ system: number;+ mcp: number;+ skills: number;+ subagents: number;+ systemDeferred: number;+ mcpDeferred: number;+}++export const EMPTY_TOOL_GROUPS: ToolTokenGroups = {+ system: 0,+ mcp: 0,+ skills: 0,+ subagents: 0,+ systemDeferred: 0,+ mcpDeferred: 0,+};++/**+ * Classifies per-tool schema tokens into display groups: built-in system+ * tools, MCP tools, skills, and subagents, with deferred (on-demand) tools+ * split out for the system/MCP groups.+ */+export function groupToolTokens(+ toolTokenCounts?: Record<string, number>,+ deferredToolNames?: string[],+): ToolTokenGroups {+ if (toolTokenCounts == null) {+ return EMPTY_TOOL_GROUPS;+ }+ const deferred = new Set(deferredToolNames ?? []);+ const groups = { ...EMPTY_TOOL_GROUPS };+ for (const [name, rawTokens] of Object.entries(toolTokenCounts)) {+ const tokens = normalizeTokenCount(rawTokens);+ if (tokens === 0) {+ continue;+ }+ if (name === Tools.skill) {+ groups.skills += tokens;+ } else if (name === Constants.SUBAGENT) {+ groups.subagents += tokens;+ } else if (name.includes(Constants.mcp_delimiter)) {+ if (deferred.has(name)) {+ groups.mcpDeferred += tokens;+ } else {+ groups.mcp += tokens;+ }+ } else if (deferred.has(name)) {+ groups.systemDeferred += tokens;+ } else {+ groups.system += tokens;+ }+ }+ return groups;+}++export function getOutputChars(part: unknown): number | null {+ if (part == null || typeof part !== 'object') {+ return null;+ }+ const { text, think } = part as { text?: unknown; think?: unknown };+ if (typeof text === 'string') {+ return text.length;+ }+ if (typeof think === 'string') {+ return think.length;+ }+ return null;+}++/**+ * Chars of the contiguous text/think parts at the very END of aggregated+ * content, the output the model is actively producing on the current call,+ * which the latest pre-invoke context snapshot does not yet account for.+ *+ * Crucially this does NOT skip a trailing tool-call part: once the model has+ * emitted a tool call, that call's text is already folded into the next+ * snapshot's `messageTokens`, so counting it would double-count against the+ * snapshot. A tool call at the end therefore yields 0 (nothing new in flight).+ */+export function countTrailingOutputChars(content?: unknown[] | null): number {+ if (!Array.isArray(content) || content.length === 0) {+ return 0;+ }+ let chars = 0;+ for (let i = content.length - 1; i >= 0; i--) {+ const partChars = getOutputChars(content[i]);+ if (partChars == null) {+ break;+ }+ chars += partChars;+ }+ return chars;+}++/** Rough live estimate for streaming text, calibrated by the last known provider ratio */+export function estimateTokens(charCount: number, calibrationRatio = 1): number {+ 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 */+export interface CostUnits {+ input: number;+ output: number;+ cacheWrite: number;+ cacheRead: number;+}++/**+ * 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, 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 = 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+ ? inputTokensIncludesCache(usage.provider)+ : cacheWrite + cacheRead <= rawInput;++ const cacheAdjustment = includesCache ? 0 : cacheRead + cacheWrite;+ const output =+ total > rawInput + rawOutput + cacheAdjustment ? total - rawInput - cacheAdjustment : rawOutput;++ return {+ input: includesCache ? Math.max(0, rawInput - cacheRead - cacheWrite) : rawInput,+ output,+ cacheWrite,+ cacheRead,+ };+}diff --git a/packages/chat/src/core/usage/index.ts b/packages/chat/src/core/usage/index.tsnew file mode 100644index 0000000000..739f8a3fa8--- /dev/null+++ b/packages/chat/src/core/usage/index.ts@@ -0,0 +1,6 @@+export * from './types';+export * from './registry';+export * from './branch';+export * from './estimate';+export * from './snapshot';+export * from './view';diff --git a/packages/chat/src/core/usage/registry.ts b/packages/chat/src/core/usage/registry.tsnew file mode 100644index 0000000000..b2694fd615--- /dev/null+++ b/packages/chat/src/core/usage/registry.ts@@ -0,0 +1,291 @@+import type { TMessage, TResponseUsage } from 'librechat-data-provider';+import { BranchUsage, TokenEntry, hasKnownCost, normalizeTokenCount } from './types';++/** Module-level token index: conversationId → messageId → entry. Not render state. */+export const registry: Map<string, Map<string, TokenEntry>> = new Map();++/**+ * Sticky per-response usage: conversationId → messageId → usage. Written only by+ * the live finalize/stop flush (`setEntryUsage`) and never rebuilt from the+ * messages cache, so a response's usage survives mid-session index rebuilds even+ * when its cache message lacks `metadata.usage` AND it was transiently dropped+ * from the cache (e.g. a sibling branch during a regenerate). `buildIndex`+ * restores from here so branch cost persists across branch switches, the cost+ * analog of `snapshotsByAnchorFamily` for the breakdown. Cleared on convo switch.+ */+export const usageHistory: Map<string, Map<string, BranchUsage>> = new Map();++export function stickyUsage(conversationId: string, messageId: string): BranchUsage | undefined {+ return usageHistory.get(conversationId)?.get(messageId);+}++/** Reads the persisted per-response usage rollup off a message's metadata.+ * The backend already normalized per-event into display units, so this reads+ * them directly. Absent for user messages and pre-feature responses (they+ * contribute 0 to branch/total). */+export function readPersistedUsage(message: Partial<TMessage>): BranchUsage | undefined {+ const usage = message.metadata?.usage;+ if (usage == null || typeof usage !== 'object') {+ return undefined;+ }+ const persisted = usage as TResponseUsage;+ return {+ 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),+ };+}++/** Pure sum of two usage records, for combining branch/total with pending. */+export function mergeUsage(a: BranchUsage, b: BranchUsage): BranchUsage {+ return {+ input: a.input + b.input,+ output: a.output + b.output,+ cacheWrite: a.cacheWrite + b.cacheWrite,+ cacheRead: a.cacheRead + b.cacheRead,+ cost: a.cost + b.cost,+ /** Coverage stays complete only if BOTH sides are complete */+ costKnown: a.costKnown && b.costKnown,+ };+}++/** Accumulates one entry's usage into a running total (in place). */+export function addUsage(target: BranchUsage, usage?: BranchUsage): void {+ if (usage == null) {+ return;+ }+ target.input += usage.input;+ target.output += usage.output;+ target.cacheWrite += usage.cacheWrite;+ target.cacheRead += usage.cacheRead;+ target.cost += usage.cost;+ /** A usage-bearing entry without a cost breaks complete coverage */+ if (!usage.costKnown) {+ target.costKnown = false;+ }+}++type ToolCallLengthFields = {+ args?: unknown;+ output?: unknown;+ argsLength?: unknown;+ outputLength?: unknown;+};++/** Stored lengths of a tool call's arguments and output. A preview carries the full lengths in+ * `argsLength`/`outputLength`, so estimates match the conversation the model actually sees. */+export function toolCallLengths(call: ToolCallLengthFields): { args: number; output: number } {+ let args = 0;+ if (typeof call.argsLength === 'number') {+ args = call.argsLength;+ } else if (typeof call.args === 'string') {+ args = call.args.length;+ } else if (call.args != null) {+ args = JSON.stringify(call.args)?.length ?? 0;+ }+ let output = 0;+ if (typeof call.outputLength === 'number') {+ output = call.outputLength;+ } else if (typeof call.output === 'string') {+ output = call.output.length;+ }+ return { args, output };+}++/** 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. */+export function partTextChars(part: unknown): number {+ if (part == null || typeof part !== 'object') {+ return 0;+ }+ const type = (part as { type?: unknown }).type;+ if (type === 'think' || type === 'error') {+ return 0;+ }+ if (type === 'tool_call') {+ const call = (part as { tool_call?: ToolCallLengthFields & { name?: unknown } }).tool_call;+ if (call == null) {+ return 0;+ }+ const lengths = toolCallLengths(call);+ return (typeof call.name === 'string' ? call.name.length : 0) + lengths.args + lengths.output;+ }+ const text = (part as { text?: unknown }).text;+ if (typeof text === 'string') {+ return text.length;+ }+ if (+ text != null &&+ typeof text === 'object' &&+ typeof (text as { value?: unknown }).value === 'string'+ ) {+ return (text as { value: string }).value.length;+ }+ 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. */+export function messageToolChars(message: Partial<TMessage>): {+ chars: number;+ resultChars: number;+} {+ if (!Array.isArray(message.content)) {+ return { chars: 0, resultChars: 0 };+ }+ let chars = 0;+ let resultChars = 0;+ for (const part of message.content) {+ if (part == null || typeof part !== 'object') {+ continue;+ }+ if ('type' in part && part.type === 'tool_call' && 'tool_call' in part) {+ const call = part.tool_call;+ if (call == null || typeof call !== 'object') {+ continue;+ }+ if ('name' in call && typeof call.name === 'string') {+ chars += call.name.length;+ }+ const lengths = toolCallLengths(call as ToolCallLengthFields);+ chars += 'args' in call && call.args == null ? 4 : lengths.args;+ chars += lengths.output;+ resultChars += lengths.output;+ }+ }+ 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+ * agent response) would otherwise drop its content/tool-call tokens. */+export function messageChars(message: Partial<TMessage>): number {+ if (Array.isArray(message.content) && message.content.length > 0) {+ let chars = 0;+ for (const part of message.content) {+ chars += partTextChars(part);+ }+ return chars;+ }+ if (typeof message.text === 'string') {+ return message.text.length;+ }+ return 0;+}++/** Quoted excerpts the send path merges into a user message's prompt. */+export function quoteChars(message: Partial<TMessage>): number {+ if (!Array.isArray(message.quotes)) {+ return 0;+ }+ let chars = 0;+ for (const quote of message.quotes) {+ if (typeof quote === 'string') {+ chars += quote.length;+ }+ }+ return chars;+}++export function toEntry(message: Partial<TMessage>): TokenEntry {+ 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+ * recomputes it from `text` alone, and the send path recounts the quote-merged+ * prompt every turn regardless (`needsCanonicalTokenCount` in agents/client.js).+ * So mirror the server, estimate quoted turns from the merged text+quotes and+ * ignore the stored count. Other count-less imports / pre-feature messages+ * estimate from text. */+ let estTokens = 0;+ if (quoted) {+ estTokens = Math.round((messageChars(message) + quoteChars(message)) / 4);+ } 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: summaryUsedTokens > 0 ? summaryUsedTokens : undefined,+ };+}++/** Full O(n) rebuild, only on discrete cache replacements (load, refetch, edits).+ * Restores a response's `usage` from the sticky history when the rebuilt message+ * carries none: per-message usage is immutable and the live finalize flushes it+ * into the index (`setEntryUsage`) before the persisted `metadata.usage` reaches+ * the cache, so a mid-session rebuild (e.g. during regenerate) must not wipe an+ * earlier branch's flushed usage, which would drop its branch cost on switch. */+export function buildIndex(conversationId: string, messages?: TMessage[] | null): void {+ const index = new Map<string, TokenEntry>();+ if (messages != null) {+ for (const message of messages) {+ if (message?.messageId) {+ const entry = toEntry(message);+ if (entry.usage == null) {+ entry.usage = stickyUsage(conversationId, message.messageId);+ }+ index.set(message.messageId, entry);+ }+ }+ }+ registry.set(conversationId, index);+}++/** Incremental upsert, final SSE events touch at most two entries */+export function upsertEntries(+ conversationId: string,+ messages: (Partial<TMessage> | null | undefined)[],+): void {+ let index = registry.get(conversationId);+ if (!index) {+ index = new Map<string, TokenEntry>();+ registry.set(conversationId, index);+ }+ for (const message of messages) {+ if (message?.messageId) {+ const entry = toEntry(message);+ if (entry.usage == null) {+ entry.usage = stickyUsage(conversationId, message.messageId);+ }+ index.set(message.messageId, entry);+ }+ }+}++/** Re-keys the index when `new` resolves to a real conversation id */+export function migrateIndex(fromId: string, toId: string): void {+ if (fromId === toId) {+ return;+ }+ const index = registry.get(fromId);+ if (index) {+ registry.delete(fromId);+ registry.set(toId, index);+ }+ const usage = usageHistory.get(fromId);+ if (usage) {+ usageHistory.delete(fromId);+ usageHistory.set(toId, usage);+ }+}++export function clearIndex(conversationId: string): void {+ registry.delete(conversationId);+ usageHistory.delete(conversationId);+}diff --git a/packages/chat/src/core/usage/snapshot.ts b/packages/chat/src/core/usage/snapshot.tsnew file mode 100644index 0000000000..219ff1a9df--- /dev/null+++ b/packages/chat/src/core/usage/snapshot.ts@@ -0,0 +1,41 @@+import type { TContextUsageEvent } from 'librechat-data-provider';++/** Latest backend context snapshot, anchored to the run's user message for staleness checks */+export interface ContextSnapshot extends TContextUsageEvent {+ anchorMessageId: string | null;+ /** Response owning a live snapshot; user-message anchors are shared by siblings. */+ responseMessageId?: string | null;+ /** Output tokens finalized after this pre-call snapshot (the last call's response) */+ completedOutputTokens?: number;+}++/**+ * In-flight usage for the streaming response only, a single-response pending+ * holder. `foldUsage` accumulates the current response's `on_token_usage`+ * events here; `finalizeUsage` flushes it into the per-message index and resets+ * it. Branch/total figures are otherwise derived by summing the index, so this+ * is the only live add (counted exactly once at finalize).+ */+export interface UsageTotals {+ input: number;+ output: number;+ cacheWrite: number;+ cacheRead: number;+ eventCount: number;+ /** Summed authoritative per-event cost from the backend (premium tiers,+ * cache rates). Populated only when `interface.contextCost` is enabled. */+ costUSD: number;+ /** Whether cost coverage is complete, every folded event carried a cost+ * (ANDed, vacuously true when empty); gates the cost row. */+ costKnown: boolean;+}++export const EMPTY_USAGE_TOTALS: UsageTotals = {+ input: 0,+ output: 0,+ cacheWrite: 0,+ cacheRead: 0,+ eventCount: 0,+ costUSD: 0,+ costKnown: true,+};diff --git a/packages/chat/src/core/usage/types.ts b/packages/chat/src/core/usage/types.tsnew file mode 100644index 0000000000..4300398599--- /dev/null+++ b/packages/chat/src/core/usage/types.ts@@ -0,0 +1,110 @@+/** Provider-reported usage of one response, in display units (post-normalize). */+export interface BranchUsage {+ input: number;+ output: number;+ cacheWrite: number;+ cacheRead: number;+ /** Authoritative USD cost; 0 when `interface.contextCost` was off at save */+ cost: number;+ /** Whether cost coverage is COMPLETE, every usage-bearing response summed+ * here carried a cost. Gates the cost row so a partial sum (some turns saved+ * before cost display was on) never renders an under-reported total. Starts+ * true (vacuous) and is ANDed; pair with `hasUsage` to require ≥1 entry. */+ costKnown: boolean;+}++export const EMPTY_USAGE: BranchUsage = {+ input: 0,+ output: 0,+ cacheWrite: 0,+ cacheRead: 0,+ 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;+}++export function hasKnownCost(value: unknown): value is number {+ return typeof value === 'number' && Number.isFinite(value) && value >= 0;+}++export interface TokenEntry {+ tokenCount: number;+ /** Char/4 token estimate used in place of `tokenCount`: count-less (imported /+ * pre-feature) message bodies, plus quoted user turns (recounted from merged+ * 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) */+ usage?: BranchUsage;+ /** Pre-invoke compacted context size (`metadata.summaryUsedTokens`) for a+ * response whose turn summarized. Caps the estimate so it stops re-summing+ * the now-discarded pre-summary history. */+ summaryUsedTokens?: number;+}++export interface BranchTotals {+ /** Sum of user-message token counts on the active branch */+ input: number;+ /** Sum of assistant-message token counts on the active branch */+ output: number;+ /** Messages on the branch with a known tokenCount */+ counted: number;+ /** Total messages on the branch */+ total: number;+ /** 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 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;+ /** Provider usage/cost summed along the active branch */+ usage: BranchUsage;+ /** Recorded usage of the selected response, never an earlier ancestor's usage. */+ lastTurnUsage?: BranchUsage;+ /** Compacted-context baseline from the deepest summarized response on the+ * branch (0 if none). The branch walk stops there, so `input`/`output` cover+ * only the post-summary messages; the estimate adds this to avoid counting+ * the discarded pre-summary history. */+ summaryBaseline: number;+}++export const EMPTY_BRANCH: BranchTotals = {+ input: 0,+ output: 0,+ counted: 0,+ total: 0,+ estTokens: 0,+ tailEstTokens: 0,+ estToolTokens: 0,+ tailEstToolTokens: 0,+ tailId: null,+ containsAnchor: false,+ usage: EMPTY_USAGE,+ summaryBaseline: 0,+};diff --git a/packages/chat/src/core/usage/view.ts b/packages/chat/src/core/usage/view.tsnew file mode 100644index 0000000000..1899ea7ce1--- /dev/null+++ b/packages/chat/src/core/usage/view.ts@@ -0,0 +1,389 @@+import type { TModelTokenomics } from 'librechat-data-provider';+import type { ContextSnapshot, UsageTotals } from './snapshot';+import type { BranchTotals, BranchUsage } from './types';+import {+ prunedBranchTokens,+ collectAnchorSeries,+ snapshotConfiguration,+ latestExchangeTokens,+} from './branch';+import { normalizeTokenCount } from './types';++export interface TokenUsageView {+ usedTokens: number;+ maxTokens?: number;+ /** 0-100, clamped; 0 when max is unknown */+ percent: number;+ /** True when derived from per-message counts instead of a backend snapshot */+ isEstimate: boolean;+ snapshot: ContextSnapshot | null;+ snapshotActive: boolean;+ branchTotals: BranchTotals;+ /** Provider usage along the active branch (matches the gauge), incl. in-flight */+ branchUsage: BranchUsage;+ /** Provider usage across all branches of the conversation */+ totalUsage: BranchUsage;+ /** Usage of the selected response, or completed calls in the in-flight turn. */+ lastTurnUsage?: BranchUsage;+ /** Distinguishes incomplete in-flight usage from a completed saved turn. */+ turnInProgress: boolean;+ /** Whether any usage is available to display (branch has token usage) */+ hasUsage: boolean;+ /** Authoritative branch cost; the cost row is gated on `interface.contextCost` at render */+ branchCost: number;+ /** Authoritative cost across all branches (shown when it differs from branch) */+ totalCost: number;+ liveTokens: number;+ /** Estimated tokens for count-less messages (in-flight tail excluded while+ * streaming); 0 on snapshots. Rendered as its own breakdown row. */+ estimatedTokens: number;+ /** Cached instruction + tool overhead applied to a snapshot-less estimate; 0 on+ * snapshots (which carry their own breakdown) and until the agent has run. */+ overheadTokens: number;+ /** Final message-token portion of a snapshot-less estimate (pruned when over+ * window, excludes live); 0 on snapshots. */+ messageTokens: number;+ /** 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, plus retained post-snapshot tool results; the clamped+ * branch walk share on the estimate path. Undefined when the producing SDK+ * doesn't report it (older snapshots) or the estimate is zero, the row stays+ * hidden. */+ toolCallTokens?: number;+ /** Cache split of the reconciling call's prompt (live or persisted), a+ * share of the used context, not an addition. */+ cacheRead?: number;+ cacheWrite?: number;+ /** Per-tool result-token counts, when provided by the usage snapshot */+ toolMessageTokenCounts?: Record<string, number>;+ /** Turns of headroom at the current per-call growth (undefined when unknown) */+ runwayTurns?: number;+ /** Tokens a summarization could reclaim ≈ context − latest exchange */+ compactionReclaim?: number;+ /** Live subagent model-call usage, a subset of Totals */+ subagentUsage?: BranchUsage;+ rates?: TModelTokenomics;+}++/** Provider-confirmed usage of the in-flight response, as the branch rollup shape. */+export const pendingToBranchUsage = (pendingUsage: UsageTotals): BranchUsage => ({+ 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,+});++/** The model limits a conversation resolves to; live snapshots override the static maximum. */+export interface TokenLimits {+ maxContextTokens?: number;+ rates?: TModelTokenomics;+ endpoint?: string;+ model?: string;+}++export interface TokenUsageInputs {+ snapshot: ContextSnapshot | null;+ isSubmitting: boolean;+ turnInProgress: boolean;+ activeResponseId: string | null;+ branchTotals: BranchTotals;+ branchUsage: BranchUsage;+ totalUsage: BranchUsage;+ lastTurnUsage?: BranchUsage;+ hasUsage: boolean;+ liveTokens: number;+ limits: TokenLimits;+ branchSnapshot: ContextSnapshot | null;+ snapshotsByAnchor: Map<string, ContextSnapshot>;+ subagentUsage: BranchUsage;+ conversationKey: string;+ /** Cached instruction and tool overhead of the conversation's agent or model, 0 until it ran. */+ modelOverhead: number;+}++/**+ * Derives the usage view from the atoms and caches the hook has already read: the live or+ * persisted snapshot when one applies, otherwise a client-side estimate from the message index.+ */+export function deriveTokenUsageView({+ snapshot,+ isSubmitting,+ turnInProgress,+ activeResponseId,+ branchTotals,+ branchUsage,+ totalUsage,+ lastTurnUsage,+ hasUsage,+ liveTokens,+ limits,+ branchSnapshot,+ snapshotsByAnchor,+ subagentUsage,+ conversationKey,+ modelOverhead,+}: TokenUsageInputs): TokenUsageView {+ /** The granular snapshot is for one specific generation. Show the live one+ * while streaming, or when its (response-message) anchor is on the viewed+ * branch. A null-anchor snapshot must NOT match every branch, that leaked+ * one branch's breakdown onto its siblings. */+ const currentActive =+ snapshot != null &&+ (isSubmitting+ ? turnInProgress && snapshot.responseMessageId === activeResponseId+ : snapshot.anchorMessageId != null &&+ branchTotals.containsAnchor &&+ (snapshot.responseMessageId == null ||+ snapshot.anchorMessageId === snapshot.responseMessageId));++ /** Precedence: live/active snapshot → persisted branch snapshot →+ * per-message estimate. The first two are authoritative (real runs with the+ * feature on); the estimate covers snapshot-less branches (pre-feature+ * 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, any retained tool result, and any in-flight+ * output. All already ate that headroom (`usedTokens` adds them), so the+ * projection must too. */+ const completedOutput = normalizeTokenCount(effective?.completedOutputTokens);+ const retainedToolTokens = normalizeTokenCount(effective?.retainedToolTokens);+ const liveOutput = turnInProgress ? normalizeTokenCount(liveTokens) : 0;+ const remainingForRunway =+ effective?.remainingContextTokens != null+ ? Math.max(+ 0,+ normalizeTokenCount(effective.remainingContextTokens) -+ completedOutput -+ retainedToolTokens -+ 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 = normalizeTokenCount(effective.contextBudget ?? breakdown.maxContextTokens);+ const instructionTokens = normalizeTokenCount(+ effective.effectiveInstructionTokens ?? breakdown.instructionTokens,+ );+ const remainingContextTokens =+ effective.remainingContextTokens != null+ ? normalizeTokenCount(effective.remainingContextTokens)+ : null;+ const breakdownUsed =+ instructionTokens ++ normalizeTokenCount(breakdown.summaryTokens) ++ normalizeTokenCount(breakdown.messageTokens);+ /** A remaining count measured against a smaller instruction total than the+ * snapshot publishes would put used below the instruction and summary+ * shares the breakdown subtracts, hiding the Messages row. */+ const baseUsed =+ remainingContextTokens != null+ ? Math.max(maxTokens - remainingContextTokens, breakdownUsed)+ : breakdownUsed;+ /** The snapshot is pre-invoke: in-flight output rides on `liveTokens` (0+ * unless streaming this branch), the last call's finalized output on+ * `completedOutputTokens`, and retained tool results on+ * `retainedToolTokens`. */+ const usedTokens = normalizeTokenCount(+ Math.max(0, baseUsed) + liveOutput + completedOutput + retainedToolTokens,+ );+ return {+ usedTokens,+ maxTokens,+ percent: maxTokens > 0 ? Math.min((usedTokens / maxTokens) * 100, 100) : 0,+ isEstimate: false,+ snapshot: effective,+ snapshotActive: true,+ branchTotals,+ branchUsage,+ totalUsage,+ lastTurnUsage,+ turnInProgress,+ hasUsage,+ branchCost: branchUsage.cost,+ totalCost: totalUsage.cost,+ liveTokens: liveOutput,+ estimatedTokens: 0,+ overheadTokens: 0,+ messageTokens: 0,+ messagesPruned: false,+ /** Retained tool results sit outside `messageTokens`, so widen the+ * reported tool-call share without clipping it back to that pre-invoke+ * total. Keep older snapshots unsplit when no split was reported. */+ toolCallTokens:+ breakdown.toolMessageTokens != null+ ? Math.min(+ normalizeTokenCount(breakdown.toolMessageTokens),+ normalizeTokenCount(breakdown.messageTokens),+ ) + retainedToolTokens+ : undefined,+ cacheRead: normalizeTokenCount(effective.cacheRead),+ cacheWrite: normalizeTokenCount(effective.cacheWrite),+ 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. A retained tool result is added for the same reason: the kept+ * exchange counts it, so leaving it out of the total would subtract+ * content that was never in it and understate the savings, on a large+ * final result, down to zero. While a response streams, `completedOutput`+ * is 0 and the in-flight tail is excluded from both sides (it rides on+ * `liveTokens`). */+ compactionReclaim: Math.max(+ 0,+ normalizeTokenCount(breakdown.messageTokens) ++ completedOutput ++ retainedToolTokens -+ latestExchangeTokens(+ conversationKey,+ tailId,+ liveOutput > 0,+ normalizeTokenCount(breakdown.summaryTokens),+ ),+ ),+ subagentUsage,+ rates: limits.rates,+ };+ }++ /** Snapshot-less estimate, computed from the in-memory message index, no+ * server round-trip. All terms are local per-message counts / char estimates+ * (uncalibrated): the learned calibration ratio reconciles provider-injected+ * context that isn't present in this visible text, so applying it here would+ * over-inflate. `summaryBaseline` is the compacted-context size from the+ * deepest summarized response on the branch (0 if none); the walk stops+ * 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 != null ? normalizeTokenCount(limits.maxContextTokens) : undefined;+ const liveOnTail = liveOutput > 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+ * the prune budget and add it to used, making over-window pruning faithful and+ * the gauge consistent with snapshots. Skipped when a summary baseline exists:+ * `computeSummaryUsedTokens` already folds the overhead into that marker, so+ * adding it again would double-count. 0 until the agent has run once this+ * session (then falls back to message-only, as before). */+ const overheadTokens = branchTotals.summaryBaseline > 0 ? 0 : normalizeTokenCount(modelOverhead);+ /** When a stream is live the tail is the in-flight response, already counted+ * by `liveTokens`; drop its static estimate so a resumed/partial response+ * isn't double-counted on the estimate path. */+ const estimatedTokens = Math.max(+ 0,+ normalizeTokenCount(branchTotals.estTokens) -+ (liveOnTail ? normalizeTokenCount(branchTotals.tailEstTokens) : 0),+ );+ 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+ * (max minus the always-sent summary baseline and instruction overhead), report+ * 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 - normalizeTokenCount(branchTotals.summaryBaseline) - overheadTokens,+ );+ if (messageTokens > messageBudget) {+ 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. */+ const messagesPruned = messageTokens < rawMessageTokens;+ const compactionReclaim = Math.max(+ 0,+ messageTokens - latestExchangeTokens(conversationKey, branchTotals.tailId, liveOnTail),+ );+ const usedTokens = normalizeTokenCount(+ overheadTokens + normalizeTokenCount(branchTotals.summaryBaseline) + messageTokens + liveOutput,+ );+ return {+ usedTokens,+ maxTokens,+ percent: maxTokens != null && maxTokens > 0 ? Math.min((usedTokens / maxTokens) * 100, 100) : 0,+ isEstimate: true,+ snapshot: null,+ snapshotActive: false,+ branchTotals,+ branchUsage,+ totalUsage,+ lastTurnUsage,+ turnInProgress,+ hasUsage,+ branchCost: branchUsage.cost,+ totalCost: totalUsage.cost,+ liveTokens: liveOutput,+ estimatedTokens,+ overheadTokens,+ messageTokens,+ messagesPruned,+ toolCallTokens: toolTokens > 0 ? toolTokens : undefined,+ compactionReclaim,+ subagentUsage,+ rates: limits.rates,+ };+}