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 { logger } from '@librechat/data-schemas';
import { inputTokensIncludesCache, reconcileContextUsageFromEvent } from 'librechat-data-provider';
import type {
TCustomConfig,
TResponseUsage,
TTokenUsageEvent,
TContextUsageEvent,
TTransactionsConfig,
} from 'librechat-data-provider';
import type { SubagentUsageEvent as AgentsSubagentUsageEvent } from '@librechat/agents';
import type {
StructuredTokenUsage,
BulkWriteDeps,
PreparedEntry,
TxMetadata,
TokenUsage,
PricingFns,
} from './transactions';
import type { UsageMetadata } from '~/stream/interfaces/IJobStore';
import type { EndpointTokenConfig } from '~/types/tokens';
import {
prepareStructuredTokenSpend,
bulkWriteTransactions,
prepareTokenSpend,
} from './transactions';
import { collectDetachedSubagentUsage } from './subagentTaskContext';
import Tokenizer, { type EncodingName } from '~/utils/tokenizer';
import { getSafeErrorMetadata } from '~/utils/errors';
import { countRetainedToolTokens } from './client';
type SpendTokensFn = (txData: TxMetadata, tokenUsage: TokenUsage) => Promise<unknown>;
type SpendStructuredTokensFn = (
txData: TxMetadata,
tokenUsage: StructuredTokenUsage,
) => Promise<unknown>;
/**
* Cache-creation (write) tokens across provider shapes: langchain's
* `input_token_details.cache_creation`, Anthropic's `cache_creation_input_tokens`,
* and OpenAI GPT-5.6+'s `cache_write_tokens` (nested or top-level). Kept in one
* place so the completion-token and billing splits never diverge.
*/
function getCacheCreationTokens(usage: UsageMetadata): number {
return (
Number(usage.input_token_details?.cache_creation) ||
Number(usage.input_token_details?.cache_write_tokens) ||
Number(usage.cache_creation_input_tokens) ||
Number(usage.cache_write_tokens) ||
0
);
}
/** The 1-hour share of the cache writes, never more than the writes themselves */
function getCacheCreation1hTokens(usage: UsageMetadata, cacheCreation: number): number {
return Math.min(
Math.max(Number(usage.input_token_details?.cache_creation_1h) || 0, 0),
cacheCreation,
);
}
interface RawProviderUsage {
/** Anthropic (direct and Vertex) */
cache_creation?: {
ephemeral_5m_input_tokens?: unknown;
ephemeral_1h_input_tokens?: unknown;
} | null;
/** Bedrock Converse */
cacheDetails?: ReadonlyArray<{ ttl?: string; inputTokens?: unknown } | null> | null;
}
interface ModelEndOutput {
usage_metadata?: UsageMetadata;
response_metadata?: {
usage?: RawProviderUsage | null;
/** Bedrock's streamed `metadata` event */
metadata?: { usage?: RawProviderUsage | null } | null;
} | null;
}
function getOneHourCacheWrites(usage?: RawProviderUsage | null): number {
const anthropic = Number(usage?.cache_creation?.ephemeral_1h_input_tokens);
if (anthropic > 0) {
return anthropic;
}
if (!Array.isArray(usage?.cacheDetails)) {
return 0;
}
let total = 0;
for (const detail of usage.cacheDetails) {
if (detail?.ttl === '1h') {
total += Number(detail.inputTokens) || 0;
}
}
return total;
}
/**
* Usage of one finished model call. Providers split cache writes by TTL only in
* their raw usage (Anthropic's `cache_creation.ephemeral_1h_input_tokens`, Bedrock's
* `cacheDetails`), which the agents SDK keeps on `response_metadata` but leaves out
* of `usage_metadata`. The 1-hour count is folded into
* `input_token_details.cache_creation_1h` so those writes are billed at the 1-hour
* rate; without a breakdown the usage is returned unchanged.
*/
export function getModelEndUsage(output?: ModelEndOutput | null): UsageMetadata | undefined {
const usage = output?.usage_metadata;
if (!usage) {
return undefined;
}
const metadata = output?.response_metadata;
const oneHour =
getOneHourCacheWrites(metadata?.usage) || getOneHourCacheWrites(metadata?.metadata?.usage);
if (!(oneHour > 0)) {
return usage;
}
return {
...usage,
input_token_details: {
...usage.input_token_details,
cache_creation_1h: Math.min(oneHour, getCacheCreationTokens(usage)),
},
};
}
/**
* Resolves `completionTokens` for billing, repairing providers whose
* `usage_metadata.output_tokens` undercounts.
*
* The documented `UsageMetadata` contract (`@langchain/core`) is
* `total_tokens === input_tokens + output_tokens`. Compliant providers
* (OpenAI, Anthropic, Google API via agents' `CustomChatGoogleGenerativeAI`)
* include any reasoning/thinking tokens inside `output_tokens` already,
* so the invariant holds and this function is a no-op for them.
*
* **Vertex AI undercount (issue #13006):** `@langchain/google-common`'s streaming
* path emits `output_tokens = candidatesTokenCount` and drops `thoughtsTokenCount`,
* so `total - input > output`. The gap is recovered as `total - input`.
*
* **Bedrock cache inflation:** additive providers keep cache tokens
* separate from `input_tokens`, making
* `total = input + output + cache_read + cache_creation`. Without adjustment
* the Vertex recovery fires on every cached step and returns
* `output + cache_read + cache_creation` instead of `output`, inflating
* completion counts by orders of magnitude. The fix subtracts the cache
* adjustment before the gap test — but only for additive providers; subset
* providers (Anthropic, Google, OpenAI, …) already include cache inside
* `input_tokens` so their `cacheAdjustment` is zero and the Vertex recovery
* is unaffected.
*/
function resolveCompletionTokens(usage: UsageMetadata): number {
const output = Number(usage.output_tokens) || 0;
const total = Number(usage.total_tokens) || 0;
const input = Number(usage.input_tokens) || 0;
// For additive providers (Bedrock), cache tokens are separate
// from input_tokens and are included in total_tokens, widening the gap
// independently of any missing thinking tokens. Subtract them so the gap
// check only fires when output_tokens genuinely undercounts (Vertex case).
// Subset providers fold cache into input_tokens, so their adjustment is 0.
const cacheRead =
Number(usage.input_token_details?.cache_read) || Number(usage.cache_read_input_tokens) || 0;
const cacheCreation = getCacheCreationTokens(usage);
const cacheAdjustment = inputTokensIncludesCache(usage.provider) ? 0 : cacheRead + cacheCreation;
if (total > input + output + cacheAdjustment) {
return total - input - cacheAdjustment;
}
return output;
}
interface SplitUsage {
/** Non-cached input portion — what gets billed at the standard input rate */
inputOnly: number;
cacheCreation: number;
/** Subset of `cacheCreation` written to the 1-hour cache */
cacheCreation1h: number;
cacheRead: number;
/** Total prompt tokens including cached portion */
totalInput: number;
/** Output tokens for billing (includes reasoning when omitted from `output_tokens`) */
completion: number;
}
export interface CollectedUsageTotals {
inputTokens: number;
outputTokens: number;
totalTokens: number;
cacheReadTokens: number;
reasoningTokens: number;
}
export interface CollectedUsageBreakdown {
total: CollectedUsageTotals;
primary: CollectedUsageTotals;
subagent: CollectedUsageTotals;
}
function splitUsage(usage: UsageMetadata): SplitUsage {
const cacheCreation = getCacheCreationTokens(usage);
const cacheCreation1h = getCacheCreation1hTokens(usage, cacheCreation);
const cacheRead =
Number(usage.input_token_details?.cache_read) || Number(usage.cache_read_input_tokens) || 0;
const rawInput = Number(usage.input_tokens) || 0;
const completion = resolveCompletionTokens(usage);
if (inputTokensIncludesCache(usage.provider)) {
return {
inputOnly: Math.max(0, rawInput - cacheCreation - cacheRead),
cacheCreation,
cacheCreation1h,
cacheRead,
totalInput: rawInput,
completion,
};
}
return {
inputOnly: rawInput,
cacheCreation,
cacheCreation1h,
cacheRead,
totalInput: rawInput + cacheCreation + cacheRead,
completion,
};
}
function emptyCollectedUsageTotals(): CollectedUsageTotals {
return {
inputTokens: 0,
outputTokens: 0,
totalTokens: 0,
cacheReadTokens: 0,
reasoningTokens: 0,
};
}
/**
* Normalizes every billed model call before folding it into API response totals.
* The same provider-aware split used by billing keeps additive cache tokens and
* repaired provider output counts consistent without coupling billing to one
* external wire format.
*/
export function aggregateCollectedUsage(
collectedUsage: ReadonlyArray<UsageMetadata | null | undefined>,
): CollectedUsageBreakdown {
const primary = emptyCollectedUsageTotals();
const subagent = emptyCollectedUsageTotals();
for (const usage of collectedUsage) {
if (usage == null) {
continue;
}
const { totalInput, cacheRead, completion } = splitUsage(usage);
const bucket = usage.usage_type === 'subagent' ? subagent : primary;
const reasoningTokens =
Number(
usage.output_token_details?.reasoning ?? usage.output_token_details?.reasoning_tokens,
) || 0;
bucket.inputTokens += totalInput;
bucket.outputTokens += completion;
bucket.totalTokens += totalInput + completion;
bucket.cacheReadTokens += cacheRead;
bucket.reasoningTokens += reasoningTokens;
}
return {
total: {
inputTokens: primary.inputTokens + subagent.inputTokens,
outputTokens: primary.outputTokens + subagent.outputTokens,
totalTokens: primary.totalTokens + subagent.totalTokens,
cacheReadTokens: primary.cacheReadTokens + subagent.cacheReadTokens,
reasoningTokens: primary.reasoningTokens + subagent.reasoningTokens,
},
primary,
subagent,
};
}
export interface RecordUsageDeps {
spendTokens: SpendTokensFn;
spendStructuredTokens: SpendStructuredTokensFn;
pricing?: PricingFns;
bulkWriteOps?: BulkWriteDeps;
isPrincipalActive?: (userId: string) => Promise<boolean>;
}
/**
* Authoritative USD cost of one model call. Reuses the exact billing
* functions (`prepareTokenSpend`/`prepareStructuredTokenSpend` → `getMultiplier`
* with `inputTokenCount` for premium tiers) so the figure emitted to the
* client matches what is charged against balance — the client must not
* re-derive pricing from base rates. `tokenValue` is credits (USD × 1e6).
*/
export function computeUsageCostUSD(
usage: UsageMetadata,
pricing: PricingFns,
endpointTokenConfig?: EndpointTokenConfig,
): number {
const { inputOnly, cacheCreation, cacheCreation1h, cacheRead, completion } = splitUsage(usage);
/** user/context/conversationId only populate the transaction doc, which is
* discarded here — only `tokenValue` (credits) is summed */
const txData: TxMetadata = {
user: '',
context: 'message',
conversationId: '',
model: usage.model,
endpointTokenConfig,
};
const entries =
cacheCreation > 0 || cacheRead > 0
? prepareStructuredTokenSpend(
txData,
{
promptTokens: {
input: inputOnly,
write: cacheCreation,
...(cacheCreation1h > 0 && { write1h: cacheCreation1h }),
read: cacheRead,
},
completionTokens: completion,
},
pricing,
)
: prepareTokenSpend(
txData,
{ promptTokens: inputOnly, completionTokens: completion },
pricing,
);
const credits = entries.reduce((sum, entry) => sum + Math.abs(entry.tokenValue), 0);
return credits / 1e6;
}
/**
* Aggregates the per-model-call `on_token_usage` payloads emitted for one
* response into a single rollup, persisted on `responseMessage.metadata.usage`.
*
* Each event is normalized into display units with the SAME logic the live
* client uses (`splitUsage`: input excludes cache, output is repaired) BEFORE
* summing, so the rollup reproduces the live branch/total usage exactly even
* when a turn mixes providers (e.g. a summarization or subagent call on a
* different provider than the primary). `cost` is the additive sum of the
* authoritative per-event cost, included only when at least one event carried
* it (i.e. `interface.contextCost` was on).
*/
export function aggregateEmittedUsage(
events: ReadonlyArray<TTokenUsageEvent>,
): TResponseUsage | null {
if (events.length === 0) {
return null;
}
let input = 0;
let output = 0;
let cacheWrite = 0;
let cacheRead = 0;
let cost = 0;
/** Persist cost only with COMPLETE coverage — every call priced. A partial
* sum (e.g. one call's `computeUsageCostUSD` threw and emitted without cost)
* would read back as authoritative and under-report; omitting it makes the
* client treat coverage as unknown and hide the cost, matching the live fold.
* Naturally false when `contextCost` is off (no event carries cost). */
let allHaveCost = true;
for (const event of events) {
const units = normalizeEventUnits(event);
input += units.input;
output += units.output;
cacheWrite += units.cacheWrite;
cacheRead += units.cacheRead;
if (event.cost != null) {
cost += event.cost;
} else {
allHaveCost = false;
}
}
const rollup: TResponseUsage = { input, output, cacheWrite, cacheRead };
if (allHaveCost) {
rollup.cost = cost;
}
return rollup;
}
/**
* Per-event display-unit normalization, mirroring the client's
* `normalizeUsageUnits` EXACTLY — including the magnitude fallback when
* `provider` is absent — so a reloaded rollup matches what the live client
* folded. This is deliberately distinct from billing `splitUsage`, which treats
* a missing provider as additive (no magnitude fallback); the divergence only
* surfaces for provider-less cached events (e.g. some OpenAI-compatible/custom
* payloads), where the client subtracts cache from input but `splitUsage`
* would not. Keep in sync with `normalizeUsageUnits` in client/src/utils/tokens.ts.
*/
function normalizeEventUnits(event: TTokenUsageEvent): {
input: number;
output: number;
cacheWrite: number;
cacheRead: number;
} {
const rawInput = event.input_tokens ?? 0;
const rawOutput = event.output_tokens ?? 0;
const total = event.total_tokens ?? 0;
const cacheWrite = event.input_token_details?.cache_creation ?? 0;
const cacheRead = event.input_token_details?.cache_read ?? 0;
const includesCache =
event.provider != null
? inputTokensIncludesCache(event.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,
};
}
/** The final primary (non-tagged) model call belonging to the snapshot's run —
* the call the latest pre-invoke snapshot precedes. Filtering by `runId` prevents
* a parallel run's later usage from being attributed to this snapshot; untagged
* events (older lib / resume) match any run for back-compat. */
function finalPrimaryCall(
events: ReadonlyArray<TTokenUsageEvent>,
runId?: string,
): TTokenUsageEvent | undefined {
for (let i = events.length - 1; i >= 0; i--) {
const event = events[i];
if (event.usage_type != null) {
continue;
}
if (runId != null && event.runId != null && event.runId !== runId) {
continue;
}
return event;
}
return undefined;
}
const finiteNonNegativeInteger = (value: unknown): number | undefined => {
if (typeof value !== 'number' || !Number.isFinite(value)) {
return undefined;
}
return Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, Math.floor(value)));
};
/**
* Sanitizes persisted per-tool counts and drops zero entries. Null-prototype
* records keep tool names as data keys; the cap bounds each result-message share.
*/
const normalizePersistedTokenRecord = (
value: unknown,
maxTotal?: number,
): Record<string, number> | undefined => {
if (value == null || typeof value !== 'object' || Array.isArray(value)) {
return undefined;
}
const normalized: Record<string, number> = Object.create(null);
let remaining = maxTotal;
let found = false;
for (const [name, rawCount] of Object.entries(value)) {
const count = finiteNonNegativeInteger(rawCount);
if (count == null) {
continue;
}
const bounded = remaining == null ? count : Math.min(count, remaining);
if (bounded === 0) {
continue;
}
normalized[name] = bounded;
found = true;
if (remaining != null) {
remaining -= bounded;
}
}
return found ? normalized : undefined;
};
/**
* The counted tool results a save path attaches to its snapshot, or `undefined`
* when there are none to attach.
*
* Only a turn that stopped at the tool-call limit retains any: it keeps the
* results of the tools its final call requested, and the snapshot describing that
* call precedes them with no further call to produce a new one. Every other
* ending leaves nothing behind — a turn that finishes normally ends on model
* text, and a turn whose tools ran gets another call, hence another snapshot.
* A result that cannot be counted exactly withdraws the whole figure rather than
* contributing a guess (see `countRetainedToolTokens`).
*
* `countExact` is the run's own exact counter. It defaults to the shared
* tokenizer for the given encoding — the same one the SDK counted the snapshot
* with, which is the point — and is a parameter so a caller (or a test) can
* supply its own without reaching into module state. `maxCountChars` is the
* deployment's ceiling on that work (`endpoints.agents.maxRetainedToolCountChars`).
*/
export function resolveRetainedToolTokens({
stoppedAtToolLimit,
contentParts,
priorToolCallIds,
encoding,
maxCountChars,
countExact = (text: string) => Tokenizer.countExactTokens(text, encoding),
}: {
stoppedAtToolLimit: boolean;
contentParts: ReadonlyArray<unknown> | null | undefined;
priorToolCallIds: ReadonlySet<string> | null | undefined;
encoding: EncodingName;
maxCountChars?: number;
countExact?: (text: string) => number | undefined;
}): number | undefined {
if (!stoppedAtToolLimit) {
return undefined;
}
return countRetainedToolTokens({
contentParts,
priorToolCallIds,
countExact,
maxCountChars,
isClaude: encoding === 'claude',
});
}
/**
* Projects the latest live context snapshot into the blob persisted on
* `responseMessage.metadata.contextUsage`. Reconciles the calibrated estimate to
* the final call's ACTUAL prompt tokens (the SDK multiplier over-inflates
* `messageTokens`, badly so when a provider injects server-side content like web
* search), so a reloaded turn shows the real context — not a several×-too-high
* number. Sanitizes malformed optional token fields, bounds each result-message
* share by the parent total, and records the final call's output as
* `completedOutputTokens` so rehydration adds the same post-snapshot delta the
* live gauge did. The client re-anchors the blob to the response message id on
* load.
*
* `retainedToolTokens` is the second post-snapshot delta: the counted tool
* results a turn that stopped at the tool-call limit keeps beyond its last
* snapshot (see `countRetainedToolTokens`). It stays a separate field rather than
* being folded into `breakdown.messageTokens`, which is provider-reconciled — a
* locally counted figure added there would silently become part of the exact
* accounting. Zero and malformed values are dropped, so a normal turn carries
* nothing new.
*/
export function buildPersistedContextUsage(
snapshot: TContextUsageEvent,
usageEvents: ReadonlyArray<TTokenUsageEvent> = [],
options: { retainedToolTokens?: number } = {},
): TContextUsageEvent {
const finalCall = finalPrimaryCall(usageEvents, snapshot.runId);
const reconciled = finalCall ? reconcileContextUsageFromEvent(snapshot, finalCall) : snapshot;
const { breakdown } = reconciled;
const messageTokens = finiteNonNegativeInteger(breakdown.messageTokens) ?? 0;
const toolTokenCounts = normalizePersistedTokenRecord(breakdown.toolTokenCounts);
const rawToolMessageTokens = finiteNonNegativeInteger(breakdown.toolMessageTokens);
const toolMessageTokens =
rawToolMessageTokens == null ? undefined : Math.min(rawToolMessageTokens, messageTokens);
const toolMessageTokenCounts =
toolMessageTokens != null
? normalizePersistedTokenRecord(breakdown.toolMessageTokenCounts, toolMessageTokens)
: undefined;
const persistedBreakdown = { ...breakdown, messageTokens };
if (toolTokenCounts == null) {
delete persistedBreakdown.toolTokenCounts;
} else {
persistedBreakdown.toolTokenCounts = toolTokenCounts;
}
if (toolMessageTokens == null) {
delete persistedBreakdown.toolMessageTokens;
delete persistedBreakdown.toolMessageTokenCounts;
} else {
persistedBreakdown.toolMessageTokens = toolMessageTokens;
if (toolMessageTokenCounts == null) {
delete persistedBreakdown.toolMessageTokenCounts;
} else {
persistedBreakdown.toolMessageTokenCounts = toolMessageTokenCounts;
}
}
const retainedToolTokens = finiteNonNegativeInteger(options.retainedToolTokens);
return {
...reconciled,
breakdown: persistedBreakdown,
...(retainedToolTokens != null && retainedToolTokens > 0 && { retainedToolTokens }),
};
}
/**
* Sum of this response's output tokens already folded into a later snapshot's
* pre-invoke baseline that the response message's `tokenCount` ALSO carries — the
* overlap `computeSummaryUsedTokens` subtracts from the marker so the live-path
* client estimate (`summaryBaseline + responseTokenCount`) doesn't double-count:
* - earlier tool-loop PRIMARY calls: a multi-call turn's first output sits in the
* kept-message context of the next call's snapshot AND in `tokenCount`.
* - the SUMMARIZATION call's generated summary: it sits in the snapshot baseline
* as `summaryTokens` AND in `tokenCount` (`recordCollectedUsage` folds
* summarization completion into the reported output total; subagent/sequential
* are kept out of that total, so they are excluded here too).
*
* Both are matched by `runId` and bounded by `beforeIndex` to the calls that
* preceded the snapshot. The summarize detour inherits the graph run id
* (`traceConfig` spreads `config.metadata.run_id`), so it shares the snapshot's
* `runId`; a parallel sibling run's summary carries a DIFFERENT `runId` and must
* NOT be subtracted (its summary lives in the sibling's baseline, not this one).
* Untagged events (older lib / resume) match any run for back-compat.
*
* Only the live path (which builds `tokenCount` via `recordCollectedUsage`) calls
* this; the abort path subtracts nothing — see {@link buildAbortedResponseMetadata}.
*/
export function priorRunOutputTokens(
events: ReadonlyArray<TTokenUsageEvent>,
beforeIndex: number,
runId?: string,
): number {
let total = 0;
const end = Math.min(beforeIndex, events.length);
for (let i = 0; i < end; i++) {
const event = events[i];
if (event.usage_type != null && event.usage_type !== 'summarization') {
continue;
}
if (runId != null && event.runId != null && event.runId !== runId) {
continue;
}
total += normalizeEventUnits(event).output;
}
return total;
}
/**
* Pre-invoke compacted context size for a summarized turn (instructions +
* summary + kept messages), or `undefined` when the turn did not summarize.
* Persisted as the lightweight `summaryUsedTokens` marker so the client estimate
* fallback caps the discarded pre-summary history instead of re-summing it (the
* gauge otherwise reads 100% in perpetuity after a compaction). Pre-invoke, so
* it carries none of the `completedOutputTokens` ambiguity that keeps the full
* snapshot off some save paths. `summaryTokens` is a SEPARATE breakdown field, so
* the non-`remainingContextTokens` fallback adds it explicitly.
*
* `priorOutputTokens` (this response's earlier tool-loop outputs, see
* {@link priorRunOutputTokens}) is subtracted: those tokens are inside the
* baseline's kept messages AND in the response message's `tokenCount` the client
* adds on top, so leaving them in the marker double-counts them on a tool-loop
* summarized turn. Single-call turns pass 0 and are unaffected.
*/
export function computeSummaryUsedTokens(
snapshot: TContextUsageEvent | null | undefined,
priorOutputTokens = 0,
): number | undefined {
const summaryTokens = snapshot?.breakdown?.summaryTokens ?? 0;
if (!snapshot || summaryTokens <= 0) {
return undefined;
}
const maxTokens = snapshot.contextBudget ?? snapshot.breakdown.maxContextTokens ?? 0;
const baseUsed =
snapshot.remainingContextTokens != null
? maxTokens - snapshot.remainingContextTokens
: (snapshot.effectiveInstructionTokens ?? snapshot.breakdown.instructionTokens ?? 0) +
summaryTokens +
(snapshot.breakdown.messageTokens ?? 0);
const adjusted = baseUsed - Math.max(0, priorOutputTokens);
return adjusted > 0 ? Math.round(adjusted) : undefined;
}
function parseUsageEvents(value?: string | null): TTokenUsageEvent[] {
if (typeof value !== 'string' || value.length === 0) {
return [];
}
try {
const parsed = JSON.parse(value);
return Array.isArray(parsed) ? (parsed as TTokenUsageEvent[]) : [];
} catch {
return [];
}
}
/**
* Builds the response `metadata` for a STOPPED generation from the job's
* persisted emitted usage, so a stopped reply keeps its accurate cost rollup on
* reload (finding: stopped responses otherwise lose cost). Shared by every abort
* save path (agents abort route + legacy abort middleware).
*
* Deliberately omits the full `contextUsage`: unlike the live path, the abort
* path can't tell whether the FINAL call (the one the latest snapshot precedes)
* emitted usage — the job stores only the latest snapshot, not the snapshot
* count. If the final call emitted none, `completedOutputTokens` would reuse an
* earlier call's output the snapshot already counts → reload over-reports. So a
* stopped response falls back to the per-message gauge estimate on reload.
*
* It DOES persist the `summaryUsedTokens` marker when the stopped turn had
* summarized: that marker is pre-invoke (no `completedOutputTokens` ambiguity),
* and without it the fallback estimate re-sums the history the compaction
* discarded — leaving a stopped summarized turn pinned at 100%. Unlike the live
* path, the abort `tokenCount` comes from `countTokens(text)` (abortMiddleware) or
* is absent (agents abort route) — it does NOT fold in the summarization or
* earlier-call output the way `recordCollectedUsage` does. So the marker subtracts
* NOTHING: the full pre-invoke baseline is correct, and the client adds only the
* partial answer text on top (no overlap to cancel).
*/
export function buildAbortedResponseMetadata(
job: { tokenUsage?: string | null; contextUsage?: string | null } | null | undefined,
): { usage?: TResponseUsage; summaryUsedTokens?: number } | undefined {
const events = parseUsageEvents(job?.tokenUsage);
const usage = aggregateEmittedUsage(events);
let snapshot: TContextUsageEvent | null = null;
if (typeof job?.contextUsage === 'string' && job.contextUsage.length > 0) {
try {
snapshot = JSON.parse(job.contextUsage) as TContextUsageEvent;
} catch {
snapshot = null;
}
}
/** Subtract nothing: the abort `tokenCount` (countTokens(text) or absent) does
* not fold in summarization/earlier-call output, so the full baseline is the
* marker and the client's partial-text addition has no overlap to cancel. */
const summaryUsedTokens = computeSummaryUsedTokens(snapshot);
const metadata: { usage?: TResponseUsage; summaryUsedTokens?: number } = {};
if (usage) {
metadata.usage = usage;
}
if (summaryUsedTokens != null) {
metadata.summaryUsedTokens = summaryUsedTokens;
}
return Object.keys(metadata).length > 0 ? metadata : undefined;
}
/**
* Resolves the endpoint token config for a usage item by its producing agent.
* Multi-endpoint graphs tag each call with `agentId`; that agent's resolved
* config is authoritative — including `undefined`, which means "no configured
* rates, use built-in pricing" (e.g. a non-custom agent in a custom-primary
* graph). Only an untagged or unknown agent falls back to `fallback` (the
* primary config), so single-endpoint graphs are unchanged. `byAgentId` must
* hold an entry for every known agent (value may be `undefined`) so `has`
* distinguishes "known, no rates" from "unknown".
*/
export function resolveAgentTokenConfig({
agentId,
byAgentId,
fallback,
}: {
agentId?: string | null;
byAgentId?: Map<string, EndpointTokenConfig | undefined>;
fallback?: EndpointTokenConfig;
}): EndpointTokenConfig | undefined {
if (agentId != null && byAgentId?.has(agentId)) {
return byAgentId.get(agentId);
}
return fallback;
}
/**
* The `context` a run stamps on the usage transactions it records on exit. A stopped run
* still owns what it consumed — the abort route only signals — so it records under
* `'abort'` rather than skipping, and a completed run under `'message'`.
*/
export function resolveRunUsageContext(aborted: boolean): 'abort' | 'message' {
return aborted ? 'abort' : 'message';
}
/**
* Whether a run already recorded provider-reported consumption for this response.
* `BaseClient` falls back to text-count billing whenever the recorded usage has no
* positive output count, which would charge the prompt a second time after
* {@link recordCollectedUsage} debited it — a stopped call may report input tokens
* and no output. An all-zero report is treated as unreported so the estimate still applies.
*/
export function hasRecordedProviderUsage(
usage: Pick<UsageMetadata, 'input_tokens' | 'output_tokens'> | null | undefined,
): boolean {
return usage != null && ((usage.input_tokens ?? 0) > 0 || (usage.output_tokens ?? 0) > 0);
}
const NON_PRIMARY_USAGE_TYPES: ReadonlySet<string> = new Set([
'summarization',
'subagent',
'sequential',
]);
/**
* Whether any primary (response) call in the collected usage reported consumption. The stream
* aggregate {@link recordCollectedUsage} returns takes its input from the first primary entry
* only, so a later cancelled call that reported input alone is billed yet invisible there.
*/
export function hasRecordedPrimaryUsage(
collectedUsage: ReadonlyArray<UsageMetadata | null | undefined> | null | undefined,
): boolean {
return (
collectedUsage?.some(
(usage) =>
usage != null &&
!NON_PRIMARY_USAGE_TYPES.has(usage.usage_type ?? '') &&
hasRecordedProviderUsage(usage),
) === true
);
}
export interface FallbackTokenUsageParams {
/** Usage the run already recorded for this response, when it recorded any. */
usage?:
| (Pick<UsageMetadata, 'input_tokens' | 'output_tokens'> & { reasoning_tokens?: number })
| null;
/** Every entry the run collected; a billed call the aggregate hides still suppresses the estimate. */
collectedUsage?: ReadonlyArray<UsageMetadata | null | undefined> | null;
promptTokens?: number;
completionTokens?: number;
/** Whether the run was stopped; labels the row when no explicit `context` is given. */
aborted?: boolean;
/** Explicit transaction label; otherwise derived from `aborted`. */
context?: string;
/** Transaction fields the caller owns: user, conversation, message, model, config. */
txMetadata: Omit<TxMetadata, 'context'>;
}
/**
* Text-count billing for a response whose provider usage was never recorded — the
* fallback `BaseClient` takes when the recorded usage has no positive output count.
* Once provider usage was recorded it is already billed, so this records nothing
* (see {@link hasRecordedProviderUsage}). A reasoning count the estimate cannot see is
* billed as its own `'reasoning'` row. Failures are logged, never thrown, so a billing
* error cannot fail the response that was already produced.
*/
export async function recordFallbackTokenUsage(
deps: Pick<RecordUsageDeps, 'spendTokens'>,
{
usage,
collectedUsage,
promptTokens,
completionTokens,
aborted = false,
context = resolveRunUsageContext(aborted),
txMetadata,
}: FallbackTokenUsageParams,
): Promise<void> {
if (hasRecordedPrimaryUsage(collectedUsage) || hasRecordedProviderUsage(usage)) {
return;
}
try {
await deps.spendTokens({ ...txMetadata, context }, { promptTokens, completionTokens });
const reasoningTokens = usage?.reasoning_tokens;
if (typeof reasoningTokens === 'number') {
await deps.spendTokens(
{ ...txMetadata, context: 'reasoning' },
{ completionTokens: reasoningTokens },
);
}
} catch (error) {
logger.error(
'[recordFallbackTokenUsage] Error recording token usage',
getSafeErrorMetadata(error),
);
}
}
export interface RecordUsageParams {
user: string;
conversationId: string;
collectedUsage: UsageMetadata[];
model?: string;
context?: string;
messageId?: string;
balance?: Partial<TCustomConfig['balance']> | null;
transactions?: Partial<TTransactionsConfig>;
endpointTokenConfig?: EndpointTokenConfig;
/**
* Per-usage endpoint token config resolver for multi-endpoint graphs. Called
* with each usage item; when provided it is authoritative — its result prices
* that item, including `undefined` (built-in pricing for a known agent with no
* configured rates). It owns its own fallback to the primary config for
* untagged/unknown agents (see {@link resolveAgentTokenConfig}). Single-config
* callers (responses.js / openai.js) omit it and use `endpointTokenConfig`.
*/
resolveEndpointTokenConfig?: (usage: UsageMetadata) => EndpointTokenConfig | undefined;
}
export interface RecordUsageResult {
input_tokens: number;
output_tokens: number;
}
export interface DetachedSubagentUsageRecorderParams {
user: string;
conversationId: string;
model?: string;
messageId?: string;
balance?: Partial<TCustomConfig['balance']> | null;
transactions?: Partial<TTransactionsConfig>;
endpointTokenConfig?: EndpointTokenConfig;
endpointTokenConfigByAgentId?: Map<string, EndpointTokenConfig | undefined>;
}
/**
* Records token usage for collected LLM calls and spends tokens against balance.
* This handles both sequential execution (tool calls) and parallel execution (multiple agents).
*
* When `pricing` and `bulkWriteOps` deps are provided, prepares all transaction documents
* in-memory first, then writes them in a single `insertMany` + one `updateBalance` call.
*/
export async function recordCollectedUsage(
deps: RecordUsageDeps,
params: RecordUsageParams,
): Promise<RecordUsageResult | undefined> {
const {
user,
model,
balance,
messageId,
transactions,
conversationId,
collectedUsage,
endpointTokenConfig,
resolveEndpointTokenConfig,
context = 'message',
} = params;
if (!collectedUsage || !collectedUsage.length) {
return;
}
const messageUsages: UsageMetadata[] = [];
const summarizationUsages: UsageMetadata[] = [];
const subagentUsages: UsageMetadata[] = [];
/** Hidden sequential-agent calls: billed, but excluded from the reported
* output total since their output never reaches the visible message */
const sequentialUsages: UsageMetadata[] = [];
for (const usage of collectedUsage) {
if (usage == null) {
continue;
}
if (usage.usage_type === 'summarization') {
summarizationUsages.push(usage);
} else if (usage.usage_type === 'subagent') {
subagentUsages.push(usage);
} else if (usage.usage_type === 'sequential') {
sequentialUsages.push(usage);
} else {
messageUsages.push(usage);
}
}
const firstUsage = messageUsages[0];
const input_tokens = firstUsage == null ? 0 : splitUsage(firstUsage).totalInput;
let total_output_tokens = 0;
const { pricing, bulkWriteOps } = deps;
const useBulk = pricing && bulkWriteOps;
const processUsageGroup = (
usages: UsageMetadata[],
usageContext: string,
docs: PreparedEntry[],
options?: { excludeFromOutputTotal?: boolean },
): void => {
for (const usage of usages) {
if (!usage) {
continue;
}
const { inputOnly, cacheCreation, cacheCreation1h, cacheRead, completion } =
splitUsage(usage);
if (options?.excludeFromOutputTotal !== true) {
total_output_tokens += completion;
}
const txMetadata: TxMetadata = {
user,
balance,
messageId,
transactions,
conversationId,
/** Price with the producing agent's endpoint config when a resolver is
* provided (multi-endpoint graphs); it owns the fallback to the primary
* config, so `undefined` here means built-in pricing, not the batch one. */
endpointTokenConfig: resolveEndpointTokenConfig
? resolveEndpointTokenConfig(usage)
: endpointTokenConfig,
context: usageContext,
model: usage.model ?? model,
};
if (useBulk) {
const entries =
cacheCreation > 0 || cacheRead > 0
? prepareStructuredTokenSpend(
txMetadata,
{
promptTokens: {
input: inputOnly,
write: cacheCreation,
...(cacheCreation1h > 0 && { write1h: cacheCreation1h }),
read: cacheRead,
},
completionTokens: completion,
},
pricing,
)
: prepareTokenSpend(
txMetadata,
{
promptTokens: inputOnly,
completionTokens: completion,
},
pricing,
);
docs.push(...entries);
continue;
}
if (cacheCreation > 0 || cacheRead > 0) {
deps
.spendStructuredTokens(txMetadata, {
promptTokens: {
input: inputOnly,
write: cacheCreation,
...(cacheCreation1h > 0 && { write1h: cacheCreation1h }),
read: cacheRead,
},
completionTokens: completion,
})
.catch((err) => {
logger.error(
`[packages/api #recordCollectedUsage] Error spending structured ${usageContext} tokens`,
err,
);
});
continue;
}
deps
.spendTokens(txMetadata, {
promptTokens: inputOnly,
completionTokens: completion,
})
.catch((err) => {
logger.error(
`[packages/api #recordCollectedUsage] Error spending ${usageContext} tokens`,
err,
);
});
}
};
const allDocs: PreparedEntry[] = [];
processUsageGroup(messageUsages, context, allDocs);
processUsageGroup(summarizationUsages, 'summarization', allDocs);
/**
* Subagent child-run usage is billed in full (transactions + balance) but
* excluded from the reported output total: the result's `output_tokens`
* becomes the parent response message's `tokenCount` (see BaseClient's
* `getStreamUsage` consumer), and child output the parent never saw would
* distort next-turn context accounting by orders of magnitude.
*/
processUsageGroup(subagentUsages, 'subagent', allDocs, { excludeFromOutputTotal: true });
processUsageGroup(sequentialUsages, 'sequential', allDocs, { excludeFromOutputTotal: true });
if (useBulk && allDocs.length > 0) {
try {
await bulkWriteTransactions({ user, docs: allDocs }, bulkWriteOps);
} catch (err) {
logger.error('[packages/api #recordCollectedUsage] Error in bulk write', err);
}
}
return {
input_tokens,
output_tokens: total_output_tokens,
};
}
/**
* Creates an immutable, request-independent billing adapter for detached child
* calls. The recorder owns pricing selection and failure isolation so legacy
* controllers only provide their database dependencies and request snapshot.
*/
export function createDetachedSubagentUsageRecorder(
deps: RecordUsageDeps,
params: DetachedSubagentUsageRecorderParams,
): (usage: UsageMetadata) => Promise<void> {
const billing = {
...params,
endpointTokenConfigByAgentId:
params.endpointTokenConfigByAgentId == null
? undefined
: new Map(params.endpointTokenConfigByAgentId),
};
return async (usage) => {
try {
if (deps.isPrincipalActive != null && !(await deps.isPrincipalActive(billing.user))) {
return;
}
await recordCollectedUsage(deps, {
user: billing.user,
conversationId: billing.conversationId,
collectedUsage: [usage],
model: billing.model,
context: 'subagent',
messageId: billing.messageId,
balance: billing.balance,
transactions: billing.transactions,
endpointTokenConfig: billing.endpointTokenConfig,
resolveEndpointTokenConfig: (entry) =>
resolveAgentTokenConfig({
agentId: entry.agentId,
byAgentId: billing.endpointTokenConfigByAgentId,
fallback: billing.endpointTokenConfig,
}),
});
} catch (error) {
logger.error('[agents/usage] Failed to record detached subagent usage', error);
}
};
}
/** SDK-owned usage envelope re-exported for host billing consumers. */
export type SubagentUsageEvent = AgentsSubagentUsageEvent;
/**
* Builds the host-side `subagentUsageSink` for `Run.create`. Subagent child
* graphs execute outside the run's `streamEvents` loop, so their model calls
* never reach the `CHAT_MODEL_END` handler (`ModelEndHandler`) — the SDK
* reports them through this sink instead. Each event is tagged
* `usage_type: 'subagent'` with the child's model/provider. Foreground child
* calls join the parent `collectedUsage` batch. Detached calls are recognized
* through their task-local context, billed immediately through
* `recordDetachedUsage`, and persisted with the durable child result instead
* of depending on a parent turn that may already have closed.
*/
export function createSubagentUsageSink(
collectedUsage: UsageMetadata[],
onUsage?: (usage: UsageMetadata) => void | Promise<void>,
recordDetachedUsage?: (usage: UsageMetadata) => void | Promise<void>,
): (event: SubagentUsageEvent) => void | Promise<void> {
return (event) => {
if (event?.usage == null) {
return;
}
const usage: UsageMetadata = { ...event.usage, usage_type: 'subagent' };
if (event.model != null && event.model !== '') {
usage.model = event.model;
}
if (event.provider != null && event.provider !== '') {
usage.provider = event.provider;
}
/** Tag the child's agent id so the host can price this usage with the
* subagent's own endpoint token config (its endpoint may differ from the
* parent's). The same tagged object is pushed AND handed to `onUsage`. */
const billingAgentId =
event.memberAgentId != null && event.memberAgentId !== ''
? event.memberAgentId
: event.subagentAgentId;
if (billingAgentId != null && billingAgentId !== '') {
usage.agentId = billingAgentId;
}
/** Usage emission is observability/UI plumbing. It must never prevent the
* authoritative billing path from running when a detached child outlives
* its parent transport. The host emitter normally contains its own error
* handling; this boundary also protects custom hosts and synchronous
* lifecycle failures. */
const emitUsage = () => {
try {
const emitted = onUsage?.(usage);
if (emitted != null) {
void Promise.resolve(emitted).catch((err) => {
logger.warn('[createSubagentUsageSink] Failed to emit subagent usage', err);
});
}
} catch (err) {
logger.warn('[createSubagentUsageSink] Failed to emit subagent usage', err);
}
};
/** A detached task can finish after its parent turn's one-time billing
* flush. Its AsyncLocalStorage context therefore owns the usage: persist
* it with the child transcript and bill it immediately. Foreground child
* calls retain the existing parent-turn batch path. */
if (recordDetachedUsage != null && collectDetachedSubagentUsage(usage)) {
/** Emission is already retained/flushed by the host and must not add
* transport latency to the child model loop. Billing is the durable
* side effect the SDK needs to await. */
emitUsage();
return Promise.resolve(recordDetachedUsage(usage)).then(() => undefined);
}
collectedUsage.push(usage);
/** Lets the host stream the billed child usage to the client (tagged
* `subagent`, so it folds into session cost/totals but not the live
* gauge) — child runs never reach ModelEndHandler's emit path. */
emitUsage();
};
}