Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🧮 refactor: Move Token Usage State and Its Stream Handlers Into the Chat Package (#17558)
Marco Berettaa493b1a3d7fe
diff --git a/client/src/components/Chat/Input/TokenUsage/store.ts b/client/src/components/Chat/Input/TokenUsage/store.tsindex ae2cc1c785..194918040a 100644--- a/client/src/components/Chat/Input/TokenUsage/store.ts+++ b/client/src/components/Chat/Input/TokenUsage/store.ts@@ -1,8 +1,3 @@-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 { createStorageAtom } from '~/store/jotai-utils';/** Sticky preference: does the context popover open with the breakdown showing?@@ -12,214 +7,25 @@ export const contextBreakdownExpandedAtom = createStorageAtom<boolean>(false,);+export {+ overheadKey,+ liveTokensFamily,+ getModelOverhead,+ markUsageFolded,+ setModelOverhead,+ totalUsageFamily,+ calibrationFamily,+ clearUsageFolded,+ hydrateSnapshots,+ removeUsageAtoms,+ branchTotalsFamily,+ pendingUsageFamily,+ migrateUsageFolded,+ subagentUsageFamily,+ contextSnapshotFamily,+ snapshotsByAnchorFamily,+ pendingSubagentUsageFamily,+ activeUsageResponseIdFamily,+} from '@librechat/chat/react';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- * stream estimates) re-render only the subscribers that draw them.- */-export const branchTotalsFamily = atomFamily((_conversationId: string) =>- atom<BranchTotals>(EMPTY_BRANCH),-);--export const contextSnapshotFamily = atomFamily((_conversationId: string) =>- atom<ContextSnapshot | null>(null),-);--/**- * Finalized snapshots keyed by their (branch-unique) response message id.- * `contextSnapshotFamily` only holds the latest run; this retains each- * generation's breakdown so switching to a branch generated earlier this- * session keeps its granular rows instead of dropping to coarse totals.- * Bounded by the conversation's generation count; cleared on convo switch.- */-export const snapshotsByAnchorFamily = atomFamily((_conversationId: string) =>- atom<Map<string, ContextSnapshot>>(new Map()),-);--/** Response owning live usage, independent of the selected branch. */-export const activeUsageResponseIdFamily = atomFamily((_conversationId: string) =>- atom<string | null>(null),-);--/** In-flight usage of the streaming response; flushed into the index at finalize. */-export const pendingUsageFamily = atomFamily((_conversationId: string) =>- atom<UsageTotals>(EMPTY_USAGE_TOTALS),-);--/** Provider usage/cost summed across all branches of the conversation. */-export const totalUsageFamily = atomFamily((_conversationId: string) =>- atom<BranchUsage>(EMPTY_USAGE),-);--/** Throttled in-flight output token estimate for the current model call */-export const liveTokensFamily = atomFamily((_conversationId: string) => atom<number>(0));--/**- * Subagent model calls COMMITTED to the conversation, accumulated from- * `usage_type: 'subagent'` events once their run settles. Deliberately excluded- * from branch/total provider usage (they bill separately and would double-count- * a turn), so they surface as their own Totals row. Session-scoped: not- * persisted, cleared on convo switch.- */-export const subagentUsageFamily = atomFamily((_conversationId: string) =>- atom<BranchUsage>(EMPTY_USAGE),-);--/**- * The in-flight run's subagent share, held beside `pendingUsageFamily` and- * settled with it: committed into `subagentUsageFamily` when the response is- * finalized or a stop is attributed, discarded when the run ends with no- * salvageable response. Committing on arrival instead would leave a failed- * run's subagent tokens in the Totals after its usage was discarded from every- * rollup they are a subset of, and would count them twice when a resume- * re-folds the same events.- */-export const pendingSubagentUsageFamily = atomFamily((_conversationId: string) =>- atom<BranchUsage>(EMPTY_USAGE),-);--/** Last known provider-vs-estimate calibration ratio for the conversation */-export const calibrationFamily = atomFamily((_conversationId: string) => atom<number>(1));--/**- * Per-conversation set of usage-event identities already folded into the- * totals. Lets the live path and resume backfill fold each model call exactly- * once, so reconnect mid-stream preserves earlier prompts' usage instead of- * resetting the session totals.- */-const foldedUsageKeys = new Map<string, Set<string>>();--/** Records an event identity; returns false if it was already folded. */-export function markUsageFolded(conversationId: string, key: string): boolean {- let seen = foldedUsageKeys.get(conversationId);- if (seen == null) {- seen = new Set<string>();- foldedUsageKeys.set(conversationId, seen);- }- if (seen.has(key)) {- return false;- }- seen.add(key);- return true;-}--/** Moves folded-key tracking from a temporary convo id to the persisted one. */-export function migrateUsageFolded(fromId: string, toId: string): void {- const seen = foldedUsageKeys.get(fromId);- if (seen == null) {- return;- }- const target = foldedUsageKeys.get(toId) ?? new Set<string>();- for (const key of seen) {- target.add(key);- }- foldedUsageKeys.set(toId, target);- foldedUsageKeys.delete(fromId);-}--/**- * Forgets a conversation's folded usage-event identities so a subsequent resume- * can re-fold them. Used when a terminal close discards the in-flight pending- * usage: `backfillUsage` would otherwise treat the persisted events as already- * folded and never rebuild pending after a navigate-away-then-resume.- */-export function clearUsageFolded(conversationId: string): void {- foldedUsageKeys.delete(conversationId);-}--/**- * Per-agent/model instruction+tool overhead — the system prompt + tool-schema- * tokens the next call always sends — cached from the breakdown the live- * `ON_CONTEXT_USAGE` event emits. Keyed by agent/model (NOT per conversation),- * so a snapshot-less branch (import / never-generated) can reuse the overhead- * once the same agent has run anywhere this session, making its prune budget and- * gauge account for the fixed overhead the client can't otherwise know. Never- * cleared on convo switch; bounded by the number of distinct configs used.- */-const modelOverhead = new Map<string, number>();--/** Stable cache key the writer (usage handler) and reader (estimate) build- * identically. An agent resolves to its real provider/model only after its data- * loads, so the reader (resolved) and writer (raw `agents` submission) would key- * differently — key by `agentId` when present so both agree; non-agent configs- * key by endpoint:model. */-export function overheadKey(- endpoint?: string | null,- model?: string | null,- agentId?: string | null,-): string {- if (agentId != null && agentId !== '') {- return `agent:${agentId}`;- }- return `${endpoint ?? ''}::${model ?? ''}`;-}--export function setModelOverhead(key: string, tokens: number): void {- if (tokens > 0) {- modelOverhead.set(key, tokens);- }-}--export function getModelOverhead(key: string): number {- return modelOverhead.get(key) ?? 0;-}--/** Jotai atomFamily entries are never GC'd — call on conversation switch/cleanup */-export function removeUsageAtoms(conversationId: string): void {- branchTotalsFamily.remove(conversationId);- contextSnapshotFamily.remove(conversationId);- snapshotsByAnchorFamily.remove(conversationId);- pendingUsageFamily.remove(conversationId);- activeUsageResponseIdFamily.remove(conversationId);- totalUsageFamily.remove(conversationId);- liveTokensFamily.remove(conversationId);- subagentUsageFamily.remove(conversationId);- pendingSubagentUsageFamily.remove(conversationId);- calibrationFamily.remove(conversationId);- foldedUsageKeys.delete(conversationId);-}--/**- * Rehydrates per-branch context breakdowns from persisted `metadata.contextUsage`- * into the snapshot-history map so the granular gauge survives a reload / opening- * an existing conversation. Merges, never clobbers — a live finalized snapshot- * for the same response id wins. Re-anchors each blob to its (branch-unique)- * response message id and reads the response's `tokenCount` as completed output.- */-export function hydrateSnapshots(conversationId: string, messages?: TMessage[] | null): void {- if (messages == null || messages.length === 0) {- return;- }- const store = getDefaultStore();- const historyAtom = snapshotsByAnchorFamily(conversationId);- const current = store.get(historyAtom);- let next: Map<string, ContextSnapshot> | null = null;- for (const message of messages) {- const id = message?.messageId;- if (!id || current.has(id)) {- continue;- }- const blob = message.metadata?.contextUsage;- if (blob == null || typeof blob !== 'object') {- continue;- }- const event = blob as TContextUsageEvent;- /** Use ONLY the persisted post-snapshot delta (the final call's output). Do- * NOT fall back to the full response `tokenCount`: the snapshot already- * counts earlier steps' output for multi-call turns, so adding the whole- * tokenCount would double-count after reload. Absent (rare: no usage event)- * contributes 0, matching the snapshot's pre-final-call base. */- const snapshot: ContextSnapshot = {- ...event,- anchorMessageId: id,- completedOutputTokens: event.completedOutputTokens,- };- next ??= new Map(current);- next.set(id, snapshot);- }- if (next != null) {- store.set(historyAtom, next);- }-}diff --git a/client/src/hooks/Chat/__tests__/useTokenUsage.spec.tsx b/client/src/hooks/Chat/__tests__/useTokenUsage.spec.tsxindex 3c945e5647..10d61be055 100644--- a/client/src/hooks/Chat/__tests__/useTokenUsage.spec.tsx+++ b/client/src/hooks/Chat/__tests__/useTokenUsage.spec.tsx@@ -1,4 +1,5 @@import { getDefaultStore } from 'jotai';+import { useUsageHandler } from '@librechat/chat/react';import { act, renderHook } from '@testing-library/react';import { Constants, QueryKeys } from 'librechat-data-provider';import { QueryClient, QueryClientProvider } from '@tanstack/react-query';@@ -15,7 +16,6 @@ import {} from '~/components/Chat/Input/TokenUsage/store';import { getRegenerateSubmissionMessages } from '~/hooks/Chat/useChatFunctions';import { useLatestMessageId } from '~/hooks/Messages/useLatestMessage';-import useUsageHandler from '~/hooks/SSE/useUsageHandler';import useTokenUsage from '~/hooks/Chat/useTokenUsage';jest.mock('~/hooks/Messages/useLatestMessage', () => ({diff --git a/client/src/hooks/SSE/__tests__/useUsageHandler.spec.tsx b/client/src/hooks/SSE/__tests__/useUsageHandler.spec.tsxindex 29d072e039..2b7bd6866b 100644--- a/client/src/hooks/SSE/__tests__/useUsageHandler.spec.tsx+++ b/client/src/hooks/SSE/__tests__/useUsageHandler.spec.tsx@@ -1,5 +1,6 @@import { getDefaultStore } from 'jotai';import { renderHook } from '@testing-library/react';+import { useUsageHandler } from '@librechat/chat/react';import { Constants, reconcileContextUsageFromEvent } from 'librechat-data-provider';import type { TMessage, TContextUsageEvent, TTokenUsageEvent } from 'librechat-data-provider';import {@@ -15,7 +16,6 @@ import {pendingSubagentUsageFamily,} from '~/components/Chat/Input/TokenUsage/store';import { buildIndex, sumTotalUsage, sumBranch, clearIndex } from '~/utils/tokens';-import useUsageHandler from '~/hooks/SSE/useUsageHandler';/** Mirrors a real web-search + summarization turn: calibration pinned at 5* inflated messageTokens to 187471 (used 213375), while the call's true promptdiff --git a/client/src/hooks/SSE/events.ts b/client/src/hooks/SSE/events.tsindex 66a693e184..f497f459ca 100644--- a/client/src/hooks/SSE/events.ts+++ b/client/src/hooks/SSE/events.ts@@ -2,7 +2,7 @@ import { useMemo, useState, useCallback } from 'react';import { useSetAtom } from 'jotai';import { useQueryClient } from '@tanstack/react-query';import { getStreamStartFailureText } from '@librechat/chat';-import { showStopButtonByIndex } from '@librechat/chat/react';+import { useUsageHandler, showStopButtonByIndex } from '@librechat/chat/react';import type { ResumableRun, ResumableEvents, ResumableUsage } from '@librechat/chat';import type { EventSubmission } from 'librechat-data-provider';import type { EventHandlerParams } from './useEventHandlers';@@ -10,7 +10,6 @@ import type { TResData, TFinalResData } from '~/common';import { countTrailingOutputChars, markStreamStartFailedMetadata } from '~/utils';import { reopenTermsOnRefusal } from '~/utils/terms';import useEventHandlers from './useEventHandlers';-import useUsageHandler from './useUsageHandler';import useLocalize from '~/hooks/useLocalize';const getStreamStartFailureData = (errorData?: unknown, termsRefusalText?: string): TResData =>diff --git a/client/src/hooks/SSE/index.ts b/client/src/hooks/SSE/index.tsindex a2d68c10e4..d3081d1894 100644--- a/client/src/hooks/SSE/index.ts+++ b/client/src/hooks/SSE/index.ts@@ -2,6 +2,6 @@ export { default as useSSE } from './useSSE';export { useResumableSSE, useAdaptiveSSE } from '@librechat/chat/react';export { default as useResumeOnLoad } from './useResumeOnLoad';export { useStepHandler } from '@librechat/chat/react';-export { default as useUsageHandler } from './useUsageHandler';+export { useUsageHandler } from '@librechat/chat/react';export { default as useContentHandler } from './useContentHandler';export { default as useAttachmentHandler } from './useAttachmentHandler';diff --git a/client/src/hooks/SSE/useSSE.ts b/client/src/hooks/SSE/useSSE.tsindex 99538fdc64..192bb11bc1 100644--- a/client/src/hooks/SSE/useSSE.ts+++ b/client/src/hooks/SSE/useSSE.ts@@ -2,9 +2,9 @@ import { useEffect, useState } from 'react';import { v4 } from 'uuid';import { useStore, useSetAtom } from 'jotai';import { useQueryClient } from '@tanstack/react-query';-import { abortScrollFamily, showStopButtonByIndex } from '@librechat/chat/react';import { startedAsNewConversation, buildCreatedInitialResponse } from '@librechat/chat';import { StepEvents, createPayload, removeNullishValues } from 'librechat-data-provider';+import { useUsageHandler, abortScrollFamily, showStopButtonByIndex } from '@librechat/chat/react';import type {Agents,TMessage,@@ -25,7 +25,6 @@ import { useChatSettings } from '~/Providers/ChatSettingsContext';import { reopenTermsOnRefusal } from '~/utils/terms';import { useGetUserBalance } from '~/data-provider';import useEventHandlers from './useEventHandlers';-import useUsageHandler from './useUsageHandler';import useLocalize from '~/hooks/useLocalize';import { activeRunFamily } from './atoms';diff --git a/packages/chat/src/react.ts b/packages/chat/src/react.tsindex 15a9589664..0b167974de 100644--- a/packages/chat/src/react.ts+++ b/packages/chat/src/react.ts@@ -2,6 +2,7 @@export * from './react/chat';export * from './react/stream';export * from './react/subagents';+export * from './react/usage';export { MessageContext, MessagePartIndex, useMessageContext } from './react/message';export {useMessagePartsHost,diff --git a/client/src/components/Chat/Input/TokenUsage/store.spec.ts b/packages/chat/src/react/__tests__/usage.spec.tssimilarity index 99%rename from client/src/components/Chat/Input/TokenUsage/store.spec.tsrename to packages/chat/src/react/__tests__/usage.spec.tsindex 0dc1d9684e..31a42adc77 100644--- a/client/src/components/Chat/Input/TokenUsage/store.spec.ts+++ b/packages/chat/src/react/__tests__/usage.spec.ts@@ -1,4 +1,4 @@-import { overheadKey, setModelOverhead, getModelOverhead } from './store';+import { overheadKey, setModelOverhead, getModelOverhead } from '../usage';describe('model overhead cache', () => {it('keys agents by agentId so the resolved reader and raw writer agree', () => {diff --git a/packages/chat/src/react/stream/index.ts b/packages/chat/src/react/stream/index.tsindex 5ac49fe7d8..fc609d77b8 100644--- a/packages/chat/src/react/stream/index.ts+++ b/packages/chat/src/react/stream/index.ts@@ -2,6 +2,8 @@ export { default as useAdaptiveSSE } from './adaptive';export { default as useResumableSSE } from './resumable';export { StreamHostProvider, useStreamHost } from './host';export { useStepHandler } from './step';+export { useUsageHandler } from './usage';+export type { UsageHandlers } from './usage';export type { StepHandlers } from './step';export { sandboxStartingByToolCallId } from './sandbox';export { ptcTraceKey, ptcTraceByToolCallId, EMPTY_PTC_TRACE, PTC_TRACE_MAX_ENTRIES } from './ptc';diff --git a/client/src/hooks/SSE/usage/__tests__/handlers.spec.ts b/packages/chat/src/react/stream/usage/__tests__/handlers.spec.tssimilarity index 93%rename from client/src/hooks/SSE/usage/__tests__/handlers.spec.tsrename to packages/chat/src/react/stream/usage/__tests__/handlers.spec.tsindex 059ffe3a4c..a6f50b31a5 100644--- a/client/src/hooks/SSE/usage/__tests__/handlers.spec.ts+++ b/packages/chat/src/react/stream/usage/__tests__/handlers.spec.ts@@ -1,11 +1,7 @@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 { pendingUsageFamily, liveTokensFamily, activeUsageResponseIdFamily } from '../../../usage';import { createUsageCounters, createUsageHandlers } from '../handlers';const submission: UsageSubmissionLike = {diff --git a/client/src/hooks/SSE/usage/events.ts b/packages/chat/src/react/stream/usage/events.tssimilarity index 100%rename from client/src/hooks/SSE/usage/events.tsrename to packages/chat/src/react/stream/usage/events.tsdiff --git a/client/src/hooks/SSE/usage/handlers.ts b/packages/chat/src/react/stream/usage/handlers.tssimilarity index 99%rename from client/src/hooks/SSE/usage/handlers.tsrename to packages/chat/src/react/stream/usage/handlers.tsindex 2c2b0a935f..73ed7c71e9 100644--- a/client/src/hooks/SSE/usage/handlers.ts+++ b/packages/chat/src/react/stream/usage/handlers.ts@@ -1,8 +1,8 @@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 type { ContextSnapshot } from '../../../core';import {overheadKey,markUsageFolded,@@ -18,21 +18,21 @@ import {branchTotalsFamily,subagentUsageFamily,pendingSubagentUsageFamily,- EMPTY_USAGE_TOTALS,contextSnapshotFamily,snapshotsByAnchorFamily,-} from '~/components/Chat/Input/TokenUsage/store';+} from '../../usage';import {sumBranch,mergeUsage,EMPTY_USAGE,+ EMPTY_USAGE_TOTALS,setEntryUsage,upsertEntries,migrateIndex,sumTotalUsage,estimateTokens,normalizeUsageUnits,-} from '~/utils';+} from '../../../core';import { FLUSH_INTERVAL_MS, getConvoKey, extractContentText, countDeltaChars } from './events';export type { UsageHandlers };diff --git a/client/src/hooks/SSE/useUsageHandler.ts b/packages/chat/src/react/stream/usage/index.tssimilarity index 68%rename from client/src/hooks/SSE/useUsageHandler.tsrename to packages/chat/src/react/stream/usage/index.tsindex 13f9ebd4f2..cfc900031b 100644--- a/client/src/hooks/SSE/useUsageHandler.ts+++ b/packages/chat/src/react/stream/usage/index.ts@@ -1,7 +1,7 @@import { useRef, useMemo } from 'react';import { getDefaultStore } from 'jotai';-import type { UsageHandlers } from '~/hooks/SSE/usage/handlers';-import { createUsageCounters, createUsageHandlers } from '~/hooks/SSE/usage/handlers';+import type { UsageHandlers } from './handlers';+import { createUsageCounters, createUsageHandlers } from './handlers';export type { UsageHandlers };@@ -9,7 +9,7 @@ export type { UsageHandlers };* 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 {+export function useUsageHandler(): UsageHandlers {const countersRef = useRef(createUsageCounters());return useMemo(() => createUsageHandlers(getDefaultStore(), countersRef.current), []);}diff --git a/packages/chat/src/react/usage.ts b/packages/chat/src/react/usage.tsnew file mode 100644index 0000000000..4c5e35ab2a--- /dev/null+++ b/packages/chat/src/react/usage.ts@@ -0,0 +1,219 @@+import { atomFamily } from 'jotai/utils';+import { atom, getDefaultStore } from 'jotai';+import type { TMessage, TContextUsageEvent } from 'librechat-data-provider';+import type { BranchTotals, BranchUsage, ContextSnapshot, UsageTotals } from '../core';+import type { Family } from './steer/family';+import { EMPTY_BRANCH, EMPTY_USAGE, EMPTY_USAGE_TOTALS } from '../core';++/**+ * Split into small per-conversation atoms so high-frequency writes (live+ * stream estimates) re-render only the subscribers that draw them.+ */+export const branchTotalsFamily: Family<BranchTotals> = atomFamily((_conversationId: string) =>+ atom<BranchTotals>(EMPTY_BRANCH),+);++export const contextSnapshotFamily: Family<ContextSnapshot | null> = atomFamily(+ (_conversationId: string) => atom<ContextSnapshot | null>(null),+);++/**+ * Finalized snapshots keyed by their (branch-unique) response message id.+ * `contextSnapshotFamily` only holds the latest run; this retains each+ * generation's breakdown so switching to a branch generated earlier this+ * session keeps its granular rows instead of dropping to coarse totals.+ * Bounded by the conversation's generation count; cleared on convo switch.+ */+export const snapshotsByAnchorFamily: Family<Map<string, ContextSnapshot>> = atomFamily(+ (_conversationId: string) => atom<Map<string, ContextSnapshot>>(new Map()),+);++/** Response owning live usage, independent of the selected branch. */+export const activeUsageResponseIdFamily: Family<string | null> = atomFamily(+ (_conversationId: string) => atom<string | null>(null),+);++/** In-flight usage of the streaming response; flushed into the index at finalize. */+export const pendingUsageFamily: Family<UsageTotals> = atomFamily((_conversationId: string) =>+ atom<UsageTotals>(EMPTY_USAGE_TOTALS),+);++/** Provider usage/cost summed across all branches of the conversation. */+export const totalUsageFamily: Family<BranchUsage> = atomFamily((_conversationId: string) =>+ atom<BranchUsage>(EMPTY_USAGE),+);++/** Throttled in-flight output token estimate for the current model call */+export const liveTokensFamily: Family<number> = atomFamily((_conversationId: string) =>+ atom<number>(0),+);++/**+ * Subagent model calls COMMITTED to the conversation, accumulated from+ * `usage_type: 'subagent'` events once their run settles. Deliberately excluded+ * from branch/total provider usage (they bill separately and would double-count+ * a turn), so they surface as their own Totals row. Session-scoped: not+ * persisted, cleared on convo switch.+ */+export const subagentUsageFamily: Family<BranchUsage> = atomFamily((_conversationId: string) =>+ atom<BranchUsage>(EMPTY_USAGE),+);++/**+ * The in-flight run's subagent share, held beside `pendingUsageFamily` and+ * settled with it: committed into `subagentUsageFamily` when the response is+ * finalized or a stop is attributed, discarded when the run ends with no+ * salvageable response. Committing on arrival instead would leave a failed+ * run's subagent tokens in the Totals after its usage was discarded from every+ * rollup they are a subset of, and would count them twice when a resume+ * re-folds the same events.+ */+export const pendingSubagentUsageFamily: Family<BranchUsage> = atomFamily(+ (_conversationId: string) => atom<BranchUsage>(EMPTY_USAGE),+);++/** Last known provider-vs-estimate calibration ratio for the conversation */+export const calibrationFamily: Family<number> = atomFamily((_conversationId: string) =>+ atom<number>(1),+);++/**+ * Per-conversation set of usage-event identities already folded into the+ * totals. Lets the live path and resume backfill fold each model call exactly+ * once, so reconnect mid-stream preserves earlier prompts' usage instead of+ * resetting the session totals.+ */+const foldedUsageKeys = new Map<string, Set<string>>();++/** Records an event identity; returns false if it was already folded. */+export function markUsageFolded(conversationId: string, key: string): boolean {+ let seen = foldedUsageKeys.get(conversationId);+ if (seen == null) {+ seen = new Set<string>();+ foldedUsageKeys.set(conversationId, seen);+ }+ if (seen.has(key)) {+ return false;+ }+ seen.add(key);+ return true;+}++/** Moves folded-key tracking from a temporary convo id to the persisted one. */+export function migrateUsageFolded(fromId: string, toId: string): void {+ const seen = foldedUsageKeys.get(fromId);+ if (seen == null) {+ return;+ }+ const target = foldedUsageKeys.get(toId) ?? new Set<string>();+ for (const key of seen) {+ target.add(key);+ }+ foldedUsageKeys.set(toId, target);+ foldedUsageKeys.delete(fromId);+}++/**+ * Forgets a conversation's folded usage-event identities so a subsequent resume+ * can re-fold them. Used when a terminal close discards the in-flight pending+ * usage: `backfillUsage` would otherwise treat the persisted events as already+ * folded and never rebuild pending after a navigate-away-then-resume.+ */+export function clearUsageFolded(conversationId: string): void {+ foldedUsageKeys.delete(conversationId);+}++/**+ * Per-agent/model instruction+tool overhead (the system prompt + tool-schema+ * tokens the next call always sends), cached from the breakdown the live+ * `ON_CONTEXT_USAGE` event emits. Keyed by agent/model (NOT per conversation),+ * so a snapshot-less branch (import / never-generated) can reuse the overhead+ * once the same agent has run anywhere this session, making its prune budget and+ * gauge account for the fixed overhead the client can't otherwise know. Never+ * cleared on convo switch; bounded by the number of distinct configs used.+ */+const modelOverhead = new Map<string, number>();++/** Stable cache key the writer (usage handler) and reader (estimate) build+ * identically. An agent resolves to its real provider/model only after its data+ * loads, so the reader (resolved) and writer (raw `agents` submission) would key+ * differently: key by `agentId` when present so both agree; non-agent configs+ * key by endpoint:model. */+export function overheadKey(+ endpoint?: string | null,+ model?: string | null,+ agentId?: string | null,+): string {+ if (agentId != null && agentId !== '') {+ return `agent:${agentId}`;+ }+ return `${endpoint ?? ''}::${model ?? ''}`;+}++export function setModelOverhead(key: string, tokens: number): void {+ if (tokens > 0) {+ modelOverhead.set(key, tokens);+ }+}++export function getModelOverhead(key: string): number {+ return modelOverhead.get(key) ?? 0;+}++/** Jotai atomFamily entries are never GC'd; call on conversation switch/cleanup */+export function removeUsageAtoms(conversationId: string): void {+ branchTotalsFamily.remove(conversationId);+ contextSnapshotFamily.remove(conversationId);+ snapshotsByAnchorFamily.remove(conversationId);+ pendingUsageFamily.remove(conversationId);+ activeUsageResponseIdFamily.remove(conversationId);+ totalUsageFamily.remove(conversationId);+ liveTokensFamily.remove(conversationId);+ subagentUsageFamily.remove(conversationId);+ pendingSubagentUsageFamily.remove(conversationId);+ calibrationFamily.remove(conversationId);+ foldedUsageKeys.delete(conversationId);+}++/**+ * Rehydrates per-branch context breakdowns from persisted `metadata.contextUsage`+ * into the snapshot-history map so the granular gauge survives a reload / opening+ * an existing conversation. Merges, never clobbers: a live finalized snapshot+ * for the same response id wins. Re-anchors each blob to its (branch-unique)+ * response message id and reads the response's `tokenCount` as completed output.+ */+export function hydrateSnapshots(conversationId: string, messages?: TMessage[] | null): void {+ if (messages == null || messages.length === 0) {+ return;+ }+ const store = getDefaultStore();+ const historyAtom = snapshotsByAnchorFamily(conversationId);+ const current = store.get(historyAtom);+ let next: Map<string, ContextSnapshot> | null = null;+ for (const message of messages) {+ const id = message?.messageId;+ if (!id || current.has(id)) {+ continue;+ }+ const blob = message.metadata?.contextUsage;+ if (blob == null || typeof blob !== 'object') {+ continue;+ }+ const event = blob as TContextUsageEvent;+ /** Use ONLY the persisted post-snapshot delta (the final call's output). Do+ * NOT fall back to the full response `tokenCount`: the snapshot already+ * counts earlier steps' output for multi-call turns, so adding the whole+ * tokenCount would double-count after reload. Absent (rare: no usage event)+ * contributes 0, matching the snapshot's pre-final-call base. */+ const snapshot: ContextSnapshot = {+ ...event,+ anchorMessageId: id,+ completedOutputTokens: event.completedOutputTokens,+ };+ next ??= new Map(current);+ next.set(id, snapshot);+ }+ if (next != null) {+ store.set(historyAtom, next);+ }+}