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 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.ts
index 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.tsx
index 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.tsx
index 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 prompt
diff --git a/client/src/hooks/SSE/events.ts b/client/src/hooks/SSE/events.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
similarity index 99%
rename from client/src/components/Chat/Input/TokenUsage/store.spec.ts
rename to packages/chat/src/react/__tests__/usage.spec.ts
index 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.ts
index 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.ts
similarity index 93%
rename from client/src/hooks/SSE/usage/__tests__/handlers.spec.ts
rename to packages/chat/src/react/stream/usage/__tests__/handlers.spec.ts
index 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.ts
similarity index 100%
rename from client/src/hooks/SSE/usage/events.ts
rename to packages/chat/src/react/stream/usage/events.ts
diff --git a/client/src/hooks/SSE/usage/handlers.ts b/packages/chat/src/react/stream/usage/handlers.ts
similarity index 99%
rename from client/src/hooks/SSE/usage/handlers.ts
rename to packages/chat/src/react/stream/usage/handlers.ts
index 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.ts
similarity index 68%
rename from client/src/hooks/SSE/useUsageHandler.ts
rename to packages/chat/src/react/stream/usage/index.ts
index 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.ts
new file mode 100644
index 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);
+ }
+}