Skip to content

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

🧮 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.ts
index 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 (live
diff --git a/client/src/hooks/Chat/useTokenUsage.ts b/client/src/hooks/Chat/useTokenUsage.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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,
+ };
+}