Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
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,
};
}