Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import type { TContextUsageEvent, TTokenUsageEvent } from 'librechat-data-provider';
import type { RecordUsageDeps, RecordUsageParams, SubagentUsageEvent } from './usage';
import type { UsageMetadata } from '../stream/interfaces/IJobStore';
import type { BulkWriteDeps, PricingFns } from './transactions';
import {
getModelEndUsage,
computeUsageCostUSD,
aggregateEmittedUsage,
createDetachedSubagentUsageRecorder,
createSubagentUsageSink,
aggregateCollectedUsage,
recordCollectedUsage,
resolveAgentTokenConfig,
resolveRunUsageContext,
hasRecordedProviderUsage,
hasRecordedPrimaryUsage,
recordFallbackTokenUsage,
buildPersistedContextUsage,
buildAbortedResponseMetadata,
computeSummaryUsedTokens,
priorRunOutputTokens,
resolveRetainedToolTokens,
} from './usage';
import { runWithDetachedSubagentUsage } from './subagentTaskContext';
import Tokenizer from '~/utils/tokenizer';
describe('resolveRetainedToolTokens', () => {
const toolPart = (id: string, output: string) => ({
type: 'tool_call',
tool_call: { id, name: 'read_file', args: '{"path":"a"}', output },
});
beforeAll(async () => {
await Tokenizer.initEncoding('o200k_base');
});
it('counts the results retained past the snapshot when the tool limit stopped the turn', () => {
/** Left to its default, the counter is the run's own tokenizer — the one the
* snapshot was measured with — so the figure is the real token count of the
* retained result and nothing else. */
const retained = resolveRetainedToolTokens({
stoppedAtToolLimit: true,
contentParts: [
toolPart('call_1', 'the result the snapshot counted'),
toolPart('call_2', 'the retained result'),
],
priorToolCallIds: new Set(['call_1']),
encoding: 'o200k_base',
});
expect(retained).toBe(Tokenizer.countExactTokens('the retained result', 'o200k_base'));
});
it('reports nothing for every other ending, whatever the turn produced', () => {
/** Its tools were followed by another model call, hence another snapshot that
* already counts them as kept-message context. */
expect(
resolveRetainedToolTokens({
stoppedAtToolLimit: false,
contentParts: [toolPart('call_1', 'a result the next call re-counted')],
priorToolCallIds: new Set(),
encoding: 'o200k_base',
}),
).toBeUndefined();
});
it('passes the deployment ceiling on to the counter', () => {
/** `endpoints.agents.maxRetainedToolCountChars`: past it the figure is withdrawn
* rather than estimated, so the gauge under-reports instead of stalling a save. */
expect(
resolveRetainedToolTokens({
stoppedAtToolLimit: true,
contentParts: [toolPart('call_1', 'a result longer than the ceiling allows')],
priorToolCallIds: new Set(),
encoding: 'o200k_base',
maxCountChars: 4,
}),
).toBeUndefined();
});
it('takes a supplied counter instead of reaching for the shared tokenizer', () => {
const countExact = jest.fn((text: string) => text.length);
expect(
resolveRetainedToolTokens({
stoppedAtToolLimit: true,
contentParts: [toolPart('call_1', 'result')],
priorToolCallIds: new Set(),
encoding: 'claude',
countExact,
}),
).toBe(Math.ceil('result'.length * 1.1));
expect(countExact).toHaveBeenCalledWith('result');
});
});
describe('aggregateCollectedUsage', () => {
it('preserves the no-child baseline and ignores absent entries', () => {
expect(
aggregateCollectedUsage([{ input_tokens: 100, output_tokens: 40, provider: 'openai' }, null]),
).toEqual({
total: {
inputTokens: 100,
outputTokens: 40,
totalTokens: 140,
cacheReadTokens: 0,
reasoningTokens: 0,
},
primary: {
inputTokens: 100,
outputTokens: 40,
totalTokens: 140,
cacheReadTokens: 0,
reasoningTokens: 0,
},
subagent: {
inputTokens: 0,
outputTokens: 0,
totalTokens: 0,
cacheReadTokens: 0,
reasoningTokens: 0,
},
});
});
it('includes multiple child calls once in the combined and subagent totals', () => {
const result = aggregateCollectedUsage([
{ input_tokens: 100, output_tokens: 40, provider: 'openai' },
{
input_tokens: 25,
output_tokens: 10,
provider: 'openai',
usage_type: 'subagent',
},
{
input_tokens: 35,
output_tokens: 15,
provider: 'openai',
usage_type: 'subagent',
},
]);
expect(result.total).toEqual(
expect.objectContaining({ inputTokens: 160, outputTokens: 65, totalTokens: 225 }),
);
expect(result.subagent).toEqual(
expect.objectContaining({ inputTokens: 60, outputTokens: 25, totalTokens: 85 }),
);
});
it('uses provider-aware cache normalization for primary and child calls', () => {
const result = aggregateCollectedUsage([
{
input_tokens: 200,
output_tokens: 80,
provider: 'anthropic',
input_token_details: { cache_creation: 60, cache_read: 30 },
},
{
input_tokens: 100,
output_tokens: 50,
provider: 'bedrock',
usage_type: 'subagent',
input_token_details: { cache_creation: 20, cache_read: 10 },
},
]);
expect(result.primary.inputTokens).toBe(200);
expect(result.subagent.inputTokens).toBe(130);
expect(result.total.cacheReadTokens).toBe(40);
});
it('repairs provider output undercounts and aggregates reasoning details', () => {
const result = aggregateCollectedUsage([
{
input_tokens: 64,
output_tokens: 2674,
total_tokens: 3379,
provider: 'vertexai',
output_token_details: { reasoning: 641 },
},
{
input_tokens: 20,
output_tokens: 10,
provider: 'openai',
usage_type: 'subagent',
output_token_details: { reasoning_tokens: 3 },
},
]);
expect(result.total.outputTokens).toBe(3325);
expect(result.total.reasoningTokens).toBe(644);
});
});
describe('recordCollectedUsage', () => {
let mockSpendTokens: jest.Mock;
let mockSpendStructuredTokens: jest.Mock;
let deps: RecordUsageDeps;
const baseParams: Omit<RecordUsageParams, 'collectedUsage'> = {
user: 'user-123',
conversationId: 'convo-123',
model: 'gpt-4',
context: 'message',
balance: { enabled: true },
transactions: { enabled: true },
};
beforeEach(() => {
jest.clearAllMocks();
mockSpendTokens = jest.fn().mockResolvedValue(undefined);
mockSpendStructuredTokens = jest.fn().mockResolvedValue(undefined);
deps = {
spendTokens: mockSpendTokens,
spendStructuredTokens: mockSpendStructuredTokens,
};
});
describe('basic functionality', () => {
it('should return undefined if collectedUsage is empty', async () => {
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage: [],
});
expect(result).toBeUndefined();
expect(mockSpendTokens).not.toHaveBeenCalled();
expect(mockSpendStructuredTokens).not.toHaveBeenCalled();
});
it('should return undefined if collectedUsage is null-ish', async () => {
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage: null as unknown as UsageMetadata[],
});
expect(result).toBeUndefined();
expect(mockSpendTokens).not.toHaveBeenCalled();
});
it('should handle single usage entry correctly', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledTimes(1);
expect(mockSpendTokens).toHaveBeenCalledWith(
expect.objectContaining({
user: 'user-123',
conversationId: 'convo-123',
model: 'gpt-4',
context: 'message',
}),
{ promptTokens: 100, completionTokens: 50 },
);
expect(result).toEqual({ input_tokens: 100, output_tokens: 50 });
});
it('should skip null entries in collectedUsage', async () => {
const collectedUsage = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
null,
{ input_tokens: 200, output_tokens: 60, model: 'gpt-4' },
] as UsageMetadata[];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledTimes(2);
expect(result).toEqual({ input_tokens: 100, output_tokens: 110 });
});
});
describe('sequential execution (tool calls)', () => {
it('should calculate tokens correctly for sequential tool calls', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
{ input_tokens: 150, output_tokens: 30, model: 'gpt-4' },
{ input_tokens: 180, output_tokens: 20, model: 'gpt-4' },
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledTimes(3);
expect(result?.output_tokens).toBe(100); // 50 + 30 + 20
expect(result?.input_tokens).toBe(100); // First entry's input
});
});
describe('summarization usage segregation', () => {
it('includes summarization output tokens in total while billing under separate context', async () => {
const collectedUsage: UsageMetadata[] = [
{
usage_type: 'message',
input_tokens: 120,
output_tokens: 40,
model: 'gpt-4',
},
{
usage_type: 'summarization',
input_tokens: 30,
output_tokens: 12,
model: 'gpt-4.1-mini',
},
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(result).toEqual({ input_tokens: 120, output_tokens: 52 });
expect(mockSpendTokens).toHaveBeenCalledTimes(2);
expect(mockSpendTokens).toHaveBeenNthCalledWith(
1,
expect.objectContaining({ context: 'message', model: 'gpt-4' }),
expect.any(Object),
);
expect(mockSpendTokens).toHaveBeenNthCalledWith(
2,
expect.objectContaining({
context: 'summarization',
model: 'gpt-4.1-mini',
}),
expect.any(Object),
);
});
});
describe('subagent usage segregation', () => {
it('bills subagent entries under separate context while excluding them from reported totals', async () => {
const collectedUsage: UsageMetadata[] = [
{
usage_type: 'message',
input_tokens: 120,
output_tokens: 40,
model: 'gpt-4',
},
{
usage_type: 'subagent',
input_tokens: 900,
output_tokens: 700,
model: 'claude-haiku-4-5',
provider: 'anthropic',
},
{
usage_type: 'subagent',
input_tokens: 1100,
output_tokens: 300,
model: 'claude-haiku-4-5',
provider: 'anthropic',
},
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
/**
* `input_tokens` comes from the first MESSAGE usage; `output_tokens`
* excludes subagent completions — the result becomes the parent
* response message's tokenCount, and child output the parent never
* saw must not distort next-turn context accounting.
*/
expect(result).toEqual({ input_tokens: 120, output_tokens: 40 });
/** ...but every subagent call is still billed against balance. */
expect(mockSpendTokens).toHaveBeenCalledTimes(3);
expect(mockSpendTokens).toHaveBeenNthCalledWith(
2,
expect.objectContaining({
context: 'subagent',
model: 'claude-haiku-4-5',
}),
{ promptTokens: 900, completionTokens: 700 },
);
expect(mockSpendTokens).toHaveBeenNthCalledWith(
3,
expect.objectContaining({
context: 'subagent',
model: 'claude-haiku-4-5',
}),
{ promptTokens: 1100, completionTokens: 300 },
);
});
it('bills hidden sequential-agent usage but excludes it from reported totals', async () => {
const collectedUsage: UsageMetadata[] = [
{ usage_type: 'message', input_tokens: 120, output_tokens: 40, model: 'gpt-4' },
{ usage_type: 'sequential', input_tokens: 800, output_tokens: 250, model: 'gpt-4' },
];
const result = await recordCollectedUsage(deps, { ...baseParams, collectedUsage });
/** Hidden intermediate output stays out of the parent's tokenCount... */
expect(result).toEqual({ input_tokens: 120, output_tokens: 40 });
/** ...but is still billed under its own context. */
expect(mockSpendTokens).toHaveBeenCalledTimes(2);
expect(mockSpendTokens).toHaveBeenNthCalledWith(
2,
expect.objectContaining({ context: 'sequential', model: 'gpt-4' }),
{ promptTokens: 800, completionTokens: 250 },
);
});
it('does not let a leading subagent entry hijack reported input_tokens', async () => {
const collectedUsage: UsageMetadata[] = [
{
usage_type: 'subagent',
input_tokens: 5000,
output_tokens: 900,
model: 'claude-haiku-4-5',
},
{
input_tokens: 120,
output_tokens: 40,
model: 'gpt-4',
},
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(result).toEqual({ input_tokens: 120, output_tokens: 40 });
expect(mockSpendTokens).toHaveBeenCalledTimes(2);
});
it('uses structured spend for subagent entries with cache tokens', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
{
usage_type: 'subagent',
input_tokens: 200,
output_tokens: 80,
model: 'claude-haiku-4-5',
provider: 'anthropic',
input_token_details: { cache_creation: 60, cache_read: 30 },
},
];
await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendStructuredTokens).toHaveBeenCalledTimes(1);
/** Anthropic input_tokens is cache-inclusive, so cache is subtracted out
* of the billed input: 200 − 60 − 30 = 110 (not double-charged). */
expect(mockSpendStructuredTokens).toHaveBeenCalledWith(
expect.objectContaining({
context: 'subagent',
model: 'claude-haiku-4-5',
}),
{
promptTokens: { input: 110, write: 60, read: 30 },
completionTokens: 80,
},
);
});
});
describe('parallel execution (multiple agents)', () => {
it('should handle parallel agents with independent input tokens', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
{ input_tokens: 80, output_tokens: 40, model: 'gpt-4' },
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledTimes(2);
expect(result?.output_tokens).toBe(90); // 50 + 40
expect(result?.output_tokens).toBeGreaterThan(0);
});
it('should NOT produce negative output_tokens for parallel execution', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 200, output_tokens: 100, model: 'gpt-4' },
{ input_tokens: 50, output_tokens: 30, model: 'gpt-4' },
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(result?.output_tokens).toBeGreaterThan(0);
expect(result?.output_tokens).toBe(130); // 100 + 30
});
it('should calculate correct total output for multiple parallel agents', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
{ input_tokens: 120, output_tokens: 60, model: 'gpt-4-turbo' },
{ input_tokens: 80, output_tokens: 40, model: 'claude-3' },
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledTimes(3);
expect(result?.output_tokens).toBe(150); // 50 + 60 + 40
});
});
describe('cache token handling - subset providers (input_tokens already includes cache)', () => {
it('subtracts cache from input_tokens for OpenAI to avoid double-counting', async () => {
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 100,
output_tokens: 50,
model: 'gpt-4',
provider: 'openAI',
input_token_details: {
cache_creation: 20,
cache_read: 10,
},
},
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendStructuredTokens).toHaveBeenCalledTimes(1);
expect(mockSpendTokens).not.toHaveBeenCalled();
expect(mockSpendStructuredTokens).toHaveBeenCalledWith(
expect.objectContaining({ model: 'gpt-4' }),
{
promptTokens: { input: 70, write: 20, read: 10 },
completionTokens: 50,
},
);
expect(result?.input_tokens).toBe(100);
});
it('does not double-count cache_read for Gemini — issue #12855', async () => {
// Real numbers from the issue report
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 11125,
output_tokens: 20,
model: 'gemini-3-flash-preview',
provider: 'google',
input_token_details: { cache_read: 7441 },
},
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendStructuredTokens).toHaveBeenCalledTimes(1);
expect(mockSpendStructuredTokens).toHaveBeenCalledWith(
expect.objectContaining({ model: 'gemini-3-flash-preview' }),
{
promptTokens: { input: 3684, write: 0, read: 7441 },
completionTokens: 20,
},
);
expect(result?.input_tokens).toBe(11125);
});
it('also applies to Vertex AI', async () => {
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 5000,
output_tokens: 100,
model: 'gemini-2.5-pro',
provider: 'vertexai',
input_token_details: { cache_read: 4000 },
},
];
await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendStructuredTokens).toHaveBeenCalledWith(
expect.objectContaining({ model: 'gemini-2.5-pro' }),
{
promptTokens: { input: 1000, write: 0, read: 4000 },
completionTokens: 100,
},
);
});
it('handles cache_read >= input_tokens defensively (clamps inputOnly to 0)', async () => {
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 1000,
output_tokens: 30,
model: 'gemini-2.5-pro',
provider: 'google',
input_token_details: { cache_read: 1000 },
},
];
await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendStructuredTokens).toHaveBeenCalledWith(
expect.objectContaining({ model: 'gemini-2.5-pro' }),
{
promptTokens: { input: 0, write: 0, read: 1000 },
completionTokens: 30,
},
);
});
it('falls through to additive (historical default) when provider is missing', async () => {
// Defensive: an unclassified or pre-this-PR usage entry should keep old behavior
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 100,
output_tokens: 50,
model: 'gpt-4',
input_token_details: { cache_creation: 20, cache_read: 10 },
},
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendStructuredTokens).toHaveBeenCalledWith(
expect.objectContaining({ model: 'gpt-4' }),
{
promptTokens: { input: 100, write: 20, read: 10 },
completionTokens: 50,
},
);
expect(result?.input_tokens).toBe(130);
});
});
describe('cache token handling - Anthropic format', () => {
it('should use spendStructuredTokens for cache tokens (cache_*_input_tokens)', async () => {
/** Cache-inclusive input_tokens (140 = 100 fresh + 25 write + 15 read). */
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 140,
output_tokens: 50,
model: 'claude-3',
provider: 'anthropic',
cache_creation_input_tokens: 25,
cache_read_input_tokens: 15,
},
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendStructuredTokens).toHaveBeenCalledTimes(1);
expect(mockSpendTokens).not.toHaveBeenCalled();
expect(mockSpendStructuredTokens).toHaveBeenCalledWith(
expect.objectContaining({ model: 'claude-3' }),
{
promptTokens: { input: 100, write: 25, read: 15 },
completionTokens: 50,
},
);
expect(result?.input_tokens).toBe(140);
});
});
describe('cache token handling - Anthropic 1-hour writes', () => {
it('passes the 1-hour share of the writes to spendStructuredTokens', async () => {
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 3600,
output_tokens: 50,
model: 'claude-sonnet-5-5',
provider: 'anthropic',
input_token_details: { cache_creation: 3000, cache_creation_1h: 2000, cache_read: 500 },
},
];
await recordCollectedUsage(deps, { ...baseParams, collectedUsage });
expect(mockSpendStructuredTokens).toHaveBeenCalledWith(
expect.objectContaining({ model: 'claude-sonnet-5-5' }),
{
promptTokens: { input: 100, write: 3000, write1h: 2000, read: 500 },
completionTokens: 50,
},
);
});
it('caps the 1-hour share at the reported writes', async () => {
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 1100,
output_tokens: 10,
model: 'claude-sonnet-5-5',
provider: 'anthropic',
input_token_details: { cache_creation: 1000, cache_creation_1h: 4000 },
},
];
await recordCollectedUsage(deps, { ...baseParams, collectedUsage });
expect(mockSpendStructuredTokens.mock.calls[0][1].promptTokens).toEqual({
input: 100,
write: 1000,
write1h: 1000,
read: 0,
});
});
});
describe('reasoning token handling - issue #13006', () => {
it('uses total - input when output_tokens undercounts (Vertex stream undercount with details present)', async () => {
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 80657,
output_tokens: 766,
total_tokens: 83265,
output_token_details: { reasoning: 1842 },
model: 'gemini-3-flash-preview',
provider: 'vertexai',
},
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledWith(
expect.objectContaining({ model: 'gemini-3-flash-preview' }),
{ promptTokens: 80657, completionTokens: 2608 },
);
expect(result?.output_tokens).toBe(2608);
});
it('uses total - input even when output_token_details is missing (raw langchain google-common path)', async () => {
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 12,
output_tokens: 135,
total_tokens: 309,
model: 'gemini-3-flash-preview',
provider: 'vertexai',
},
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledWith(
expect.objectContaining({ model: 'gemini-3-flash-preview' }),
{ promptTokens: 12, completionTokens: 297 },
);
expect(result?.output_tokens).toBe(297);
});
it('does not change output when invariant already holds (OpenAI o-series, reasoning already a subset)', async () => {
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 100,
output_tokens: 500,
total_tokens: 600,
output_token_details: { reasoning: 200 },
model: 'o1-preview',
provider: 'openAI',
},
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledWith(
expect.objectContaining({ model: 'o1-preview' }),
{ promptTokens: 100, completionTokens: 500 },
);
expect(result?.output_tokens).toBe(500);
});
it('routes correction through structured spend when cache tokens are present', async () => {
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 80657,
output_tokens: 766,
total_tokens: 83265,
output_token_details: { reasoning: 1842 },
input_token_details: { cache_read: 30000 },
model: 'gemini-3-flash-preview',
provider: 'vertexai',
},
];
await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendStructuredTokens).toHaveBeenCalledWith(
expect.objectContaining({ model: 'gemini-3-flash-preview' }),
{
promptTokens: { input: 50657, write: 0, read: 30000 },
completionTokens: 2608,
},
);
});
it('no-op when total_tokens is absent or zero', async () => {
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 100,
output_tokens: 50,
model: 'gpt-4',
provider: 'openAI',
},
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledWith(expect.anything(), {
promptTokens: 100,
completionTokens: 50,
});
expect(result?.output_tokens).toBe(50);
});
});
describe('mixed cache and non-cache entries', () => {
it('should handle mixed entries correctly', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
{
input_tokens: 150,
output_tokens: 30,
model: 'gpt-4',
input_token_details: { cache_creation: 10, cache_read: 5 },
},
{ input_tokens: 200, output_tokens: 20, model: 'gpt-4' },
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledTimes(2);
expect(mockSpendStructuredTokens).toHaveBeenCalledTimes(1);
expect(result?.output_tokens).toBe(100); // 50 + 30 + 20
});
});
describe('model fallback', () => {
it('should use usage.model when available', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4-turbo' },
];
await recordCollectedUsage(deps, {
...baseParams,
model: 'fallback-model',
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledWith(
expect.objectContaining({ model: 'gpt-4-turbo' }),
expect.any(Object),
);
});
it('should fallback to param model when usage.model is missing', async () => {
const collectedUsage: UsageMetadata[] = [{ input_tokens: 100, output_tokens: 50 }];
await recordCollectedUsage(deps, {
...baseParams,
model: 'param-model',
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledWith(
expect.objectContaining({ model: 'param-model' }),
expect.any(Object),
);
});
});
describe('real-world scenarios', () => {
it('should correctly sum output tokens for sequential tool calls with growing context', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 31596, output_tokens: 151, model: 'claude-opus' },
{ input_tokens: 35368, output_tokens: 150, model: 'claude-opus' },
{ input_tokens: 58362, output_tokens: 295, model: 'claude-opus' },
{ input_tokens: 112604, output_tokens: 193, model: 'claude-opus' },
{ input_tokens: 257440, output_tokens: 2217, model: 'claude-opus' },
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(result?.input_tokens).toBe(31596);
expect(result?.output_tokens).toBe(3006); // 151 + 150 + 295 + 193 + 2217
expect(mockSpendTokens).toHaveBeenCalledTimes(5);
});
it('should handle cache tokens with multiple tool calls', async () => {
/** Cache-inclusive Anthropic wire: input_tokens = fresh + write + read. */
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 31596, // 788 fresh + 30808 write
output_tokens: 163,
model: 'claude-opus',
provider: 'anthropic',
input_token_details: { cache_read: 0, cache_creation: 30808 },
},
{
input_tokens: 35378, // 3802 fresh + 30808 read + 768 write
output_tokens: 149,
model: 'claude-opus',
provider: 'anthropic',
input_token_details: { cache_read: 30808, cache_creation: 768 },
},
{
input_tokens: 58384, // 26808 fresh + 31576 read
output_tokens: 225,
model: 'claude-opus',
provider: 'anthropic',
input_token_details: { cache_read: 31576, cache_creation: 0 },
},
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
// input_tokens = total prompt of first call (cache-inclusive)
expect(result?.input_tokens).toBe(31596);
// output_tokens = 163 + 149 + 225 = 537
expect(result?.output_tokens).toBe(537);
expect(mockSpendStructuredTokens).toHaveBeenCalledTimes(3);
expect(mockSpendTokens).not.toHaveBeenCalled();
});
});
describe('error handling', () => {
it('should catch and log errors from spendTokens without throwing', async () => {
mockSpendTokens.mockRejectedValue(new Error('DB error'));
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
expect(result).toEqual({ input_tokens: 100, output_tokens: 50 });
});
it('should catch and log errors from spendStructuredTokens without throwing', async () => {
mockSpendStructuredTokens.mockRejectedValue(new Error('DB error'));
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 100,
output_tokens: 50,
model: 'gpt-4',
provider: 'openAI',
input_token_details: { cache_creation: 20, cache_read: 10 },
},
];
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
});
// openAI is a subset provider → input_tokens already includes cache
expect(result).toEqual({ input_tokens: 100, output_tokens: 50 });
});
});
describe('transaction metadata', () => {
it('should pass all metadata fields to spend functions', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
];
const endpointTokenConfig = { 'gpt-4': { prompt: 0.01, completion: 0.03, context: 8192 } };
await recordCollectedUsage(deps, {
...baseParams,
messageId: 'msg-123',
endpointTokenConfig,
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledWith(
{
user: 'user-123',
conversationId: 'convo-123',
model: 'gpt-4',
context: 'message',
messageId: 'msg-123',
balance: { enabled: true },
transactions: { enabled: true },
endpointTokenConfig,
},
{ promptTokens: 100, completionTokens: 50 },
);
});
it('prices each usage with its agent endpoint config (multi-endpoint graph)', async () => {
/** Two endpoints share a model id but bill at different rates. */
const primaryConfig = { 'shared-model': { prompt: 0.01, completion: 0.03, context: 8192 } };
const subagentConfig = { 'shared-model': { prompt: 0.05, completion: 0.15, context: 8192 } };
const byAgent: Record<string, typeof primaryConfig> = {
primary: primaryConfig,
sub: subagentConfig,
};
const collectedUsage: UsageMetadata[] = [
{
usage_type: 'message',
agentId: 'primary',
input_tokens: 100,
output_tokens: 50,
model: 'shared-model',
},
{
usage_type: 'subagent',
agentId: 'sub',
input_tokens: 200,
output_tokens: 80,
model: 'shared-model',
},
];
await recordCollectedUsage(deps, {
...baseParams,
collectedUsage,
endpointTokenConfig: primaryConfig,
resolveEndpointTokenConfig: (usage) =>
usage.agentId != null ? byAgent[usage.agentId] : undefined,
});
expect(mockSpendTokens).toHaveBeenCalledWith(
expect.objectContaining({
context: 'message',
model: 'shared-model',
endpointTokenConfig: primaryConfig,
}),
{ promptTokens: 100, completionTokens: 50 },
);
expect(mockSpendTokens).toHaveBeenCalledWith(
expect.objectContaining({
context: 'subagent',
model: 'shared-model',
endpointTokenConfig: subagentConfig,
}),
{ promptTokens: 200, completionTokens: 80 },
);
});
it('trusts the resolver result, including undefined (built-in pricing for known agents)', async () => {
const batch = { 'gpt-4': { prompt: 0.01, completion: 0.03, context: 8192 } };
await recordCollectedUsage(deps, {
...baseParams,
collectedUsage: [
{ agentId: 'known-openai', input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
],
endpointTokenConfig: batch,
/** A known agent with no configured rates: the resolver returns undefined
* and the billing path must honor it (built-in pricing), NOT re-apply
* the batch/primary config. */
resolveEndpointTokenConfig: () => undefined,
});
expect(mockSpendTokens).toHaveBeenCalledWith(
expect.objectContaining({ endpointTokenConfig: undefined }),
{ promptTokens: 100, completionTokens: 50 },
);
});
it('should use default context "message" when not provided', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
];
await recordCollectedUsage(deps, {
user: 'user-123',
conversationId: 'convo-123',
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledWith(
expect.objectContaining({ context: 'message' }),
expect.any(Object),
);
});
it('should allow custom context like "title"', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
];
await recordCollectedUsage(deps, {
...baseParams,
context: 'title',
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledWith(
expect.objectContaining({ context: 'title' }),
expect.any(Object),
);
});
});
describe('messageId propagation', () => {
it('should pass messageId to spendTokens', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 10, output_tokens: 5, model: 'gpt-4' },
];
await recordCollectedUsage(deps, {
...baseParams,
messageId: 'msg-1',
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledWith(
expect.objectContaining({ messageId: 'msg-1' }),
expect.any(Object),
);
});
it('should pass messageId to spendStructuredTokens for cache paths', async () => {
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 100,
output_tokens: 50,
model: 'claude-3',
cache_creation_input_tokens: 25,
cache_read_input_tokens: 15,
},
];
await recordCollectedUsage(deps, {
...baseParams,
messageId: 'msg-cache-1',
collectedUsage,
});
expect(mockSpendStructuredTokens).toHaveBeenCalledWith(
expect.objectContaining({ messageId: 'msg-cache-1' }),
expect.any(Object),
);
expect(mockSpendTokens).not.toHaveBeenCalled();
});
it('should pass undefined messageId when not provided', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 10, output_tokens: 5, model: 'gpt-4' },
];
await recordCollectedUsage(deps, {
user: 'user-123',
conversationId: 'convo-123',
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledWith(
expect.objectContaining({ messageId: undefined }),
expect.any(Object),
);
});
it('should propagate messageId across multiple usage entries', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
{ input_tokens: 200, output_tokens: 60, model: 'gpt-4' },
{
input_tokens: 150,
output_tokens: 30,
model: 'gpt-4',
input_token_details: { cache_creation: 10, cache_read: 5 },
},
];
await recordCollectedUsage(deps, {
...baseParams,
messageId: 'msg-multi',
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledTimes(2);
expect(mockSpendStructuredTokens).toHaveBeenCalledTimes(1);
for (const call of mockSpendTokens.mock.calls) {
expect(call[0]).toEqual(expect.objectContaining({ messageId: 'msg-multi' }));
}
expect(mockSpendStructuredTokens.mock.calls[0][0]).toEqual(
expect.objectContaining({ messageId: 'msg-multi' }),
);
});
});
describe('bulk write path', () => {
let mockInsertMany: jest.Mock;
let mockUpdateBalance: jest.Mock;
let mockPricing: PricingFns;
let mockBulkWriteOps: BulkWriteDeps;
let bulkDeps: RecordUsageDeps;
beforeEach(() => {
mockInsertMany = jest.fn().mockResolvedValue(undefined);
mockUpdateBalance = jest.fn().mockResolvedValue({});
mockPricing = {
getMultiplier: jest.fn().mockReturnValue(1),
getCacheMultiplier: jest.fn().mockReturnValue(null),
};
mockBulkWriteOps = {
insertMany: mockInsertMany,
updateBalance: mockUpdateBalance,
};
bulkDeps = {
spendTokens: mockSpendTokens,
spendStructuredTokens: mockSpendStructuredTokens,
pricing: mockPricing,
bulkWriteOps: mockBulkWriteOps,
};
});
it('should use bulk path when pricing and bulkWriteOps are provided', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
];
const result = await recordCollectedUsage(bulkDeps, {
...baseParams,
collectedUsage,
});
expect(mockInsertMany).toHaveBeenCalledTimes(1);
expect(mockSpendTokens).not.toHaveBeenCalled();
expect(mockSpendStructuredTokens).not.toHaveBeenCalled();
expect(result).toEqual({ input_tokens: 100, output_tokens: 50 });
});
it('should batch all entries into a single insertMany call', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
{ input_tokens: 200, output_tokens: 60, model: 'gpt-4' },
{ input_tokens: 300, output_tokens: 70, model: 'gpt-4' },
];
await recordCollectedUsage(bulkDeps, {
...baseParams,
collectedUsage,
});
expect(mockInsertMany).toHaveBeenCalledTimes(1);
const insertedDocs = mockInsertMany.mock.calls[0][0];
expect(insertedDocs.length).toBe(6); // 2 per entry (prompt + completion)
});
it('should call updateBalance once when balance is enabled', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
{ input_tokens: 200, output_tokens: 60, model: 'gpt-4' },
];
await recordCollectedUsage(bulkDeps, {
...baseParams,
balance: { enabled: true },
collectedUsage,
});
expect(mockUpdateBalance).toHaveBeenCalledTimes(1);
expect(mockUpdateBalance).toHaveBeenCalledWith(
expect.objectContaining({
user: 'user-123',
incrementValue: expect.any(Number),
}),
);
});
it('should not call updateBalance when balance is disabled', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
];
await recordCollectedUsage(bulkDeps, {
...baseParams,
balance: { enabled: false },
collectedUsage,
});
expect(mockInsertMany).toHaveBeenCalledTimes(1);
expect(mockUpdateBalance).not.toHaveBeenCalled();
});
it('should handle cache tokens via bulk path', async () => {
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 100,
output_tokens: 50,
model: 'gpt-4',
input_token_details: { cache_creation: 20, cache_read: 10 },
},
];
const result = await recordCollectedUsage(bulkDeps, {
...baseParams,
collectedUsage,
});
expect(mockInsertMany).toHaveBeenCalledTimes(1);
expect(mockSpendStructuredTokens).not.toHaveBeenCalled();
expect(result).toBeDefined();
});
it('should handle mixed cache and non-cache entries in bulk', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
{
input_tokens: 150,
output_tokens: 30,
model: 'gpt-4',
input_token_details: { cache_creation: 10, cache_read: 5 },
},
];
const result = await recordCollectedUsage(bulkDeps, {
...baseParams,
collectedUsage,
});
expect(mockInsertMany).toHaveBeenCalledTimes(1);
expect(mockSpendTokens).not.toHaveBeenCalled();
expect(mockSpendStructuredTokens).not.toHaveBeenCalled();
expect(result?.output_tokens).toBe(80);
});
it('should fall back to legacy path when pricing is missing', async () => {
const legacyDeps: RecordUsageDeps = {
spendTokens: mockSpendTokens,
spendStructuredTokens: mockSpendStructuredTokens,
bulkWriteOps: mockBulkWriteOps,
// no pricing
};
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
];
await recordCollectedUsage(legacyDeps, {
...baseParams,
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledTimes(1);
expect(mockInsertMany).not.toHaveBeenCalled();
});
it('should fall back to legacy path when bulkWriteOps is missing', async () => {
const legacyDeps: RecordUsageDeps = {
spendTokens: mockSpendTokens,
spendStructuredTokens: mockSpendStructuredTokens,
pricing: mockPricing,
// no bulkWriteOps
};
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
];
await recordCollectedUsage(legacyDeps, {
...baseParams,
collectedUsage,
});
expect(mockSpendTokens).toHaveBeenCalledTimes(1);
expect(mockInsertMany).not.toHaveBeenCalled();
});
it('should handle errors in bulk write gracefully', async () => {
mockInsertMany.mockRejectedValue(new Error('DB error'));
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
];
const result = await recordCollectedUsage(bulkDeps, {
...baseParams,
collectedUsage,
});
expect(result).toEqual({ input_tokens: 100, output_tokens: 50 });
});
});
describe('Bedrock prompt caching — completion token inflation regression', () => {
it('does not fold cache_creation into completion on the first cached step', async () => {
// Bedrock: total = input + output + cache_creation (additive, not subset).
// Before fix: resolveCompletionTokens returned output + cache_creation (5500)
// instead of output (500).
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 100,
output_tokens: 500,
total_tokens: 5600,
cache_creation_input_tokens: 5000,
cache_read_input_tokens: 0,
model: 'claude-sonnet-4-6',
},
];
const result = await recordCollectedUsage(deps, { ...baseParams, collectedUsage });
expect(mockSpendStructuredTokens).toHaveBeenCalledWith(
expect.objectContaining({ model: 'claude-sonnet-4-6' }),
{
promptTokens: { input: 100, write: 5000, read: 0 },
completionTokens: 500,
},
);
expect(result?.output_tokens).toBe(500);
});
it('does not fold cache_read into completion on subsequent cached steps', async () => {
// Bedrock: total = input + output + cache_read on every read step.
// Before fix: each step returned output + cache_read instead of output.
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 200,
output_tokens: 300,
total_tokens: 4500,
cache_read_input_tokens: 4000,
cache_creation_input_tokens: 0,
model: 'claude-sonnet-4-6',
},
];
const result = await recordCollectedUsage(deps, { ...baseParams, collectedUsage });
expect(mockSpendStructuredTokens).toHaveBeenCalledWith(
expect.objectContaining({ model: 'claude-sonnet-4-6' }),
{
promptTokens: { input: 200, write: 0, read: 4000 },
completionTokens: 300,
},
);
expect(result?.output_tokens).toBe(300);
});
it('handles cache tokens in input_token_details format (alternate field path)', async () => {
const collectedUsage: UsageMetadata[] = [
{
input_tokens: 200,
output_tokens: 300,
total_tokens: 4500,
input_token_details: { cache_read: 4000, cache_creation: 0 },
model: 'claude-sonnet-4-6',
},
];
const result = await recordCollectedUsage(deps, { ...baseParams, collectedUsage });
expect(result?.output_tokens).toBe(300);
});
it('accumulates only true output across a multi-step cached agent run', async () => {
// 1 write step + 4 read steps. Without the fix, each step folds its
// cache tokens into completion, inflating the total by the full cache size.
const writeStep: UsageMetadata = {
input_tokens: 100,
output_tokens: 500,
total_tokens: 5600,
cache_creation_input_tokens: 5000,
cache_read_input_tokens: 0,
model: 'claude-sonnet-4-6',
};
const readSteps: UsageMetadata[] = Array.from({ length: 4 }, (_, i) => ({
input_tokens: 200,
output_tokens: 300 + i * 50,
total_tokens: 200 + (300 + i * 50) + 5000,
cache_read_input_tokens: 5000,
cache_creation_input_tokens: 0,
model: 'claude-sonnet-4-6',
}));
const result = await recordCollectedUsage(deps, {
...baseParams,
collectedUsage: [writeStep, ...readSteps],
});
// True output: 500 + 300 + 350 + 400 + 450 = 2000
const trueOutput = 500 + readSteps.reduce((sum, s) => sum + (s.output_tokens ?? 0), 0);
expect(result?.output_tokens).toBe(trueOutput);
});
});
describe('bulk write with summarization usage', () => {
let mockInsertMany: jest.Mock;
let mockUpdateBalance: jest.Mock;
let mockPricing: PricingFns;
let mockBulkWriteOps: BulkWriteDeps;
let bulkDeps: RecordUsageDeps;
beforeEach(() => {
mockInsertMany = jest.fn().mockResolvedValue(undefined);
mockUpdateBalance = jest.fn().mockResolvedValue({});
mockPricing = {
getMultiplier: jest.fn().mockReturnValue(1),
getCacheMultiplier: jest.fn().mockReturnValue(null),
};
mockBulkWriteOps = {
insertMany: mockInsertMany,
updateBalance: mockUpdateBalance,
};
bulkDeps = {
spendTokens: mockSpendTokens,
spendStructuredTokens: mockSpendStructuredTokens,
pricing: mockPricing,
bulkWriteOps: mockBulkWriteOps,
};
});
it('combines message and summarization docs into a single bulk write', async () => {
const collectedUsage: UsageMetadata[] = [
{
usage_type: 'message',
input_tokens: 200,
output_tokens: 80,
model: 'gpt-4',
},
{
usage_type: 'summarization',
input_tokens: 50,
output_tokens: 20,
model: 'gpt-4.1-mini',
},
];
const result = await recordCollectedUsage(bulkDeps, {
...baseParams,
collectedUsage,
});
expect(mockInsertMany).toHaveBeenCalledTimes(1);
expect(mockUpdateBalance).toHaveBeenCalledTimes(1);
expect(mockSpendTokens).not.toHaveBeenCalled();
expect(mockSpendStructuredTokens).not.toHaveBeenCalled();
const insertedDocs = mockInsertMany.mock.calls[0][0];
// 2 docs per entry (prompt + completion) x 2 entries = 4 docs
expect(insertedDocs).toHaveLength(4);
const messageContextDocs = insertedDocs.filter(
(d: Record<string, unknown>) => d.context === 'message',
);
const summarizationContextDocs = insertedDocs.filter(
(d: Record<string, unknown>) => d.context === 'summarization',
);
expect(messageContextDocs).toHaveLength(2);
expect(summarizationContextDocs).toHaveLength(2);
expect(result).toEqual({ input_tokens: 200, output_tokens: 100 });
});
it('handles summarization-only usage in bulk mode', async () => {
const collectedUsage: UsageMetadata[] = [
{
usage_type: 'summarization',
input_tokens: 60,
output_tokens: 25,
model: 'gpt-4.1-mini',
},
];
const result = await recordCollectedUsage(bulkDeps, {
...baseParams,
collectedUsage,
});
expect(mockInsertMany).toHaveBeenCalledTimes(1);
expect(mockSpendTokens).not.toHaveBeenCalled();
expect(mockSpendStructuredTokens).not.toHaveBeenCalled();
const insertedDocs = mockInsertMany.mock.calls[0][0];
expect(insertedDocs).toHaveLength(2);
const summarizationContextDocs = insertedDocs.filter(
(d: Record<string, unknown>) => d.context === 'summarization',
);
expect(summarizationContextDocs).toHaveLength(2);
expect(result).toEqual({ input_tokens: 0, output_tokens: 25 });
});
it('handles message-only usage in bulk mode', async () => {
const collectedUsage: UsageMetadata[] = [
{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' },
{ input_tokens: 200, output_tokens: 60, model: 'gpt-4' },
];
const result = await recordCollectedUsage(bulkDeps, {
...baseParams,
collectedUsage,
});
expect(mockInsertMany).toHaveBeenCalledTimes(1);
expect(mockSpendTokens).not.toHaveBeenCalled();
expect(mockSpendStructuredTokens).not.toHaveBeenCalled();
const insertedDocs = mockInsertMany.mock.calls[0][0];
// 2 docs per entry x 2 entries = 4 docs
expect(insertedDocs).toHaveLength(4);
const messageContextDocs = insertedDocs.filter(
(d: Record<string, unknown>) => d.context === 'message',
);
expect(messageContextDocs).toHaveLength(4);
expect(result).toEqual({ input_tokens: 100, output_tokens: 110 });
});
});
});
describe('createSubagentUsageSink', () => {
const makeEvent = (overrides: Partial<SubagentUsageEvent> = {}): SubagentUsageEvent => ({
usage: { input_tokens: 900, output_tokens: 700, total_tokens: 1600 },
model: 'claude-haiku-4-5',
provider: 'anthropic',
subagentType: 'researcher',
subagentRunId: 'run-1_sub_abc',
subagentAgentId: 'researcher',
runId: 'run-1',
...overrides,
});
it('pushes usage tagged with usage_type subagent and the child model/provider', () => {
const collectedUsage: UsageMetadata[] = [];
const sink = createSubagentUsageSink(collectedUsage);
sink(makeEvent());
expect(collectedUsage).toEqual([
{
usage_type: 'subagent',
input_tokens: 900,
output_tokens: 700,
total_tokens: 1600,
model: 'claude-haiku-4-5',
provider: 'anthropic',
agentId: 'researcher',
},
]);
});
it('tags the child agent id so the host can price with the subagent endpoint config', () => {
const collectedUsage: UsageMetadata[] = [];
const emitted: UsageMetadata[] = [];
const sink = createSubagentUsageSink(collectedUsage, (u) => {
emitted.push(u);
});
sink(makeEvent({ subagentAgentId: 'agent_xyz' }));
expect(collectedUsage[0].agentId).toBe('agent_xyz');
/** The same tagged object is handed to onUsage (the live emitter). */
expect(emitted[0]).toBe(collectedUsage[0]);
expect(emitted[0].agentId).toBe('agent_xyz');
});
it('prices graph usage with the member agent instead of the synthetic execution subject', () => {
const collectedUsage: UsageMetadata[] = [];
const sink = createSubagentUsageSink(collectedUsage);
sink(
makeEvent({
subagentKind: 'graph',
subagentAgentId: 'graph:research_team',
memberAgentId: 'agent_writer',
}),
);
expect(collectedUsage[0].agentId).toBe('agent_writer');
});
it('falls back to the execution subject when the member agent id is empty', () => {
const collectedUsage: UsageMetadata[] = [];
const sink = createSubagentUsageSink(collectedUsage);
sink(makeEvent({ subagentAgentId: 'agent_researcher', memberAgentId: '' }));
expect(collectedUsage[0].agentId).toBe('agent_researcher');
});
it('preserves cache token details from the child call', () => {
const collectedUsage: UsageMetadata[] = [];
const sink = createSubagentUsageSink(collectedUsage);
sink(
makeEvent({
usage: {
input_tokens: 200,
output_tokens: 80,
total_tokens: 280,
input_token_details: { cache_creation: 60, cache_read: 30 },
} as SubagentUsageEvent['usage'],
}),
);
expect(collectedUsage[0].input_token_details).toEqual({
cache_creation: 60,
cache_read: 30,
});
});
it('omits model/provider tags when the event carries none', () => {
const collectedUsage: UsageMetadata[] = [];
const sink = createSubagentUsageSink(collectedUsage);
sink(makeEvent({ model: undefined, provider: undefined }));
expect(collectedUsage).toHaveLength(1);
expect(collectedUsage[0].usage_type).toBe('subagent');
expect(collectedUsage[0]).not.toHaveProperty('model');
expect(collectedUsage[0]).not.toHaveProperty('provider');
});
it('ignores events without usage', () => {
const collectedUsage: UsageMetadata[] = [];
const sink = createSubagentUsageSink(collectedUsage);
sink(makeEvent({ usage: undefined as unknown as SubagentUsageEvent['usage'] }));
expect(collectedUsage).toEqual([]);
});
it('routes detached usage to its awaited billing and durable child collectors', async () => {
const collectedUsage: UsageMetadata[] = [];
const detachedUsage: UsageMetadata[] = [];
const emitted: UsageMetadata[] = [];
const recordDetachedUsage = jest.fn().mockResolvedValue(undefined);
const sink = createSubagentUsageSink(
collectedUsage,
(usage) => {
emitted.push(usage);
},
recordDetachedUsage,
);
await runWithDetachedSubagentUsage(detachedUsage, async () => {
await sink(makeEvent());
});
expect(collectedUsage).toEqual([]);
expect(detachedUsage).toHaveLength(1);
expect(emitted[0]).toBe(detachedUsage[0]);
expect(recordDetachedUsage).toHaveBeenCalledWith(detachedUsage[0]);
/** The same sink still batches ordinary foreground subagents with the parent. */
await sink(makeEvent({ subagentRunId: 'foreground-child' }));
expect(collectedUsage).toHaveLength(1);
expect(recordDetachedUsage).toHaveBeenCalledTimes(1);
});
it('still records detached usage when the auxiliary emitter throws', async () => {
const collectedUsage: UsageMetadata[] = [];
const detachedUsage: UsageMetadata[] = [];
const recordDetachedUsage = jest.fn().mockResolvedValue(undefined);
const sink = createSubagentUsageSink(
collectedUsage,
() => {
throw new Error('parent transport was disposed');
},
recordDetachedUsage,
);
await runWithDetachedSubagentUsage(detachedUsage, async () => {
await sink(makeEvent());
});
expect(collectedUsage).toEqual([]);
expect(detachedUsage).toHaveLength(1);
expect(recordDetachedUsage).toHaveBeenCalledWith(detachedUsage[0]);
});
it('round-trips into recordCollectedUsage as billed subagent transactions', async () => {
const collectedUsage: UsageMetadata[] = [];
const sink = createSubagentUsageSink(collectedUsage);
/** Parent's own call, collected by ModelEndHandler as usual. */
collectedUsage.push({ input_tokens: 120, output_tokens: 40, model: 'gpt-4' });
/** Child calls reported through the sink mid-run. */
sink(makeEvent());
sink(
makeEvent({
usage: { input_tokens: 1100, output_tokens: 300, total_tokens: 1400 },
}),
);
const spendTokens = jest.fn().mockResolvedValue(undefined);
const spendStructuredTokens = jest.fn().mockResolvedValue(undefined);
const result = await recordCollectedUsage(
{ spendTokens, spendStructuredTokens },
{
user: 'user-123',
conversationId: 'convo-123',
model: 'gpt-4',
collectedUsage,
},
);
/** All three calls billed; child output excluded from reported totals. */
expect(spendTokens).toHaveBeenCalledTimes(3);
expect(spendTokens).toHaveBeenNthCalledWith(
2,
expect.objectContaining({ context: 'subagent', model: 'claude-haiku-4-5' }),
{ promptTokens: 900, completionTokens: 700 },
);
expect(result).toEqual({ input_tokens: 120, output_tokens: 40 });
});
});
describe('computeUsageCostUSD', () => {
/** Stub pricing: base prompt 3 / completion 15, cache write 3.75 / read 0.3;
* a premium tier above 200k input prompt tokens (8 / 40). Mirrors the
* shape of the real getMultiplier(inputTokenCount) premium switch. */
const pricing: PricingFns = {
getMultiplier: ({ tokenType, inputTokenCount }) => {
const premium = (inputTokenCount ?? 0) > 200000;
if (tokenType === 'completion') {
return premium ? 40 : 15;
}
return premium ? 8 : 3;
},
getCacheMultiplier: ({ cacheType }) => (cacheType === 'write' ? 3.75 : 0.3),
};
it('prices a standard call at base rates', () => {
const cost = computeUsageCostUSD(
{ input_tokens: 1000, output_tokens: 500, model: 'gpt-4', provider: 'openAI' },
pricing,
);
expect(cost).toBeCloseTo((1000 * 3 + 500 * 15) / 1e6);
});
it('applies the premium tier when the call exceeds the input threshold', () => {
/** The exact gap finding A flagged: a long-context call bills premium */
const cost = computeUsageCostUSD(
{ input_tokens: 300000, output_tokens: 1000, model: 'gpt-5.5', provider: 'openAI' },
pricing,
);
expect(cost).toBeCloseTo((300000 * 8 + 1000 * 40) / 1e6);
});
it('prices cache-inclusive Anthropic input by subtracting cache, then cache at its own rates', () => {
/** input_tokens is cache-inclusive (13000 = 1000 fresh + 2000 write + 10000
* read). The fresh 1000 is billed at the input rate, the cache at its own
* rates — never the cache portion at the input rate too (LibreChat#13795). */
const cost = computeUsageCostUSD(
{
input_tokens: 13000,
output_tokens: 500,
model: 'claude-haiku-4-5',
provider: 'anthropic',
input_token_details: { cache_creation: 2000, cache_read: 10000 },
},
pricing,
);
expect(cost).toBeCloseTo((1000 * 3 + 2000 * 3.75 + 10000 * 0.3 + 500 * 15) / 1e6);
});
it('routes nested cache_write_tokens to the write bucket, not the input rate', () => {
/** OpenAI GPT-5.6 reports cache writes as `cache_write_tokens`. Those 2000
* tokens must bill at the write rate (3.75), not fold into input (3);
* inputOnly = 13000 - 2000 write - 10000 read = 1000. */
const cost = computeUsageCostUSD(
{
input_tokens: 13000,
output_tokens: 500,
model: 'gpt-5.6',
provider: 'openAI',
input_token_details: { cache_read: 10000, cache_write_tokens: 2000 },
},
pricing,
);
expect(cost).toBeCloseTo((1000 * 3 + 2000 * 3.75 + 10000 * 0.3 + 500 * 15) / 1e6);
});
it('routes top-level cache_write_tokens to the write bucket alongside the premium input tier', () => {
/** Top-level `cache_write_tokens` (Chat/Responses flattened shape) is also
* recognized; inputOnly = 280000 - 5000 - 15000 = 260000, above the premium
* threshold so input/completion price at the premium tier (8 / 40). */
const cost = computeUsageCostUSD(
{
input_tokens: 280000,
output_tokens: 500,
model: 'gpt-5.6',
provider: 'openAI',
input_token_details: { cache_read: 15000 },
cache_write_tokens: 5000,
},
pricing,
);
expect(cost).toBeCloseTo((260000 * 8 + 5000 * 3.75 + 15000 * 0.3 + 500 * 40) / 1e6);
});
it('prices the 1-hour share of Anthropic cache writes at the 1-hour rate', () => {
/** 13000 = 1000 fresh + 2000 write (1500 of them 1-hour) + 10000 read */
const cost = computeUsageCostUSD(
{
input_tokens: 13000,
output_tokens: 500,
model: 'claude-sonnet-5-5',
provider: 'anthropic',
input_token_details: { cache_creation: 2000, cache_creation_1h: 1500, cache_read: 10000 },
},
{
...pricing,
getCacheMultiplier: ({ cacheType }) => ({ write: 3.75, write1h: 6, read: 0.3 })[cacheType],
},
);
expect(cost).toBeCloseTo((1000 * 3 + 500 * 3.75 + 1500 * 6 + 10000 * 0.3 + 500 * 15) / 1e6);
});
});
describe('getModelEndUsage', () => {
const usage_metadata: UsageMetadata = {
input_tokens: 3510,
output_tokens: 40,
total_tokens: 3550,
input_token_details: { cache_creation: 3000, cache_read: 500 },
};
it('folds the Anthropic 1-hour write count into the usage', () => {
const usage = getModelEndUsage({
usage_metadata,
response_metadata: {
usage: {
cache_creation: { ephemeral_5m_input_tokens: 1000, ephemeral_1h_input_tokens: 2000 },
},
},
});
expect(usage?.input_token_details).toEqual({
cache_creation: 3000,
cache_creation_1h: 2000,
cache_read: 500,
});
expect(usage_metadata.input_token_details).not.toHaveProperty('cache_creation_1h');
});
it('reads the 1-hour writes from Bedrock cacheDetails, streamed or not', () => {
const cacheDetails = [
{ ttl: '1h', inputTokens: 2000 },
{ ttl: '5m', inputTokens: 1000 },
];
for (const response_metadata of [
{ usage: { cacheDetails } },
{ metadata: { usage: { cacheDetails } } },
]) {
expect(getModelEndUsage({ usage_metadata, response_metadata })?.input_token_details).toEqual({
cache_creation: 3000,
cache_creation_1h: 2000,
cache_read: 500,
});
}
});
it('returns the usage unchanged without a 1-hour breakdown', () => {
expect(getModelEndUsage({ usage_metadata })).toBe(usage_metadata);
expect(
getModelEndUsage({
usage_metadata,
response_metadata: { usage: { cache_creation: { ephemeral_1h_input_tokens: 0 } } },
}),
).toBe(usage_metadata);
});
it('returns undefined when the call reported no usage', () => {
expect(getModelEndUsage(undefined)).toBeUndefined();
expect(getModelEndUsage({ response_metadata: null })).toBeUndefined();
});
});
describe('aggregateEmittedUsage', () => {
it('returns null for no emitted events', () => {
expect(aggregateEmittedUsage([])).toBeNull();
});
it('normalizes each call into display units (input excludes cache) and sums cost', () => {
const events: TTokenUsageEvent[] = [
{
input_tokens: 100,
output_tokens: 20,
total_tokens: 120,
model: 'gpt-4o-mini',
provider: 'openAI',
cost: 0.001,
},
{
input_tokens: 150,
output_tokens: 10,
total_tokens: 160,
input_token_details: { cache_creation: 30, cache_read: 50 },
model: 'gpt-4o-mini',
provider: 'openAI',
cost: 0.002,
},
];
/** openAI is cache-subset: input excludes cache (150−30−50=70) */
expect(aggregateEmittedUsage(events)).toEqual({
input: 170,
output: 30,
cacheWrite: 30,
cacheRead: 50,
cost: 0.003,
});
});
it('omits cost when no event carried it (contextCost off)', () => {
const rollup = aggregateEmittedUsage([
{ input_tokens: 100, output_tokens: 20, total_tokens: 120, provider: 'openAI' },
]);
expect(rollup).toEqual({ input: 100, output: 20, cacheWrite: 0, cacheRead: 0 });
expect(rollup?.cost).toBeUndefined();
});
it('omits cost when any call lacked it (partial pricing failure)', () => {
/** One call priced, one missing cost (e.g. computeUsageCostUSD threw) →
* the sum would under-report, so coverage is incomplete and cost omitted. */
const rollup = aggregateEmittedUsage([
{ input_tokens: 100, output_tokens: 20, provider: 'openAI', cost: 0.01 },
{ input_tokens: 50, output_tokens: 10, provider: 'openAI' },
]);
expect(rollup?.cost).toBeUndefined();
expect(rollup?.input).toBe(150);
expect(rollup?.output).toBe(30);
});
it('normalizes mixed-provider calls per their own provider before summing', () => {
/** bedrock is additive (cache separate from input), openAI is subset */
const rollup = aggregateEmittedUsage([
{
input_tokens: 100,
output_tokens: 20,
provider: 'bedrock',
input_token_details: { cache_read: 40 },
cost: 0.01,
},
{
input_tokens: 90,
output_tokens: 5,
usage_type: 'subagent',
provider: 'openAI',
input_token_details: { cache_read: 30 },
cost: 0.02,
},
]);
/** bedrock input stays 100 (additive); openAI input 90−30=60 → 160 */
expect(rollup?.input).toBe(160);
expect(rollup?.output).toBe(25);
expect(rollup?.cacheRead).toBe(70);
expect(rollup?.cost).toBeCloseTo(0.03);
});
it('uses the magnitude fallback for provider-less cached events (matches live)', () => {
/** No provider: the client's normalizeUsageUnits uses a magnitude heuristic
* (cache ≤ input ⇒ input includes cache), so the rollup must too — billing
* splitUsage would treat it as additive and leave input at 1000, diverging
* from the live display after reload. */
const rollup = aggregateEmittedUsage([
{ input_tokens: 1000, output_tokens: 100, input_token_details: { cache_read: 400 } },
]);
expect(rollup).toEqual({ input: 600, output: 100, cacheWrite: 0, cacheRead: 400 });
});
});
describe('buildPersistedContextUsage', () => {
const baseSnapshot: TContextUsageEvent = {
runId: 'run-1',
breakdown: {
maxContextTokens: 8000,
instructionTokens: 100,
systemMessageTokens: 80,
dynamicInstructionTokens: 20,
toolSchemaTokens: 30,
summaryTokens: 0,
toolCount: 2,
messageCount: 3,
messageTokens: 500,
availableForMessages: 7000,
toolTokenCounts: { add: 15, noop: 0 },
},
contextBudget: 7800,
};
it('persists positive per-tool schema counts', () => {
const result = buildPersistedContextUsage(baseSnapshot);
expect(result.breakdown.toolTokenCounts).toEqual({ add: 15 });
expect(result.contextBudget).toBe(7800);
});
it('omits a schema-count record with no positive counts', () => {
const result = buildPersistedContextUsage({
...baseSnapshot,
breakdown: { ...baseSnapshot.breakdown, toolTokenCounts: { add: 0 } },
});
expect(result.breakdown.toolTokenCounts).toBeUndefined();
});
it('passes through a snapshot without tool counts', () => {
const { toolTokenCounts: _omit, ...breakdown } = baseSnapshot.breakdown;
const result = buildPersistedContextUsage({ ...baseSnapshot, breakdown });
expect(result.breakdown.toolTokenCounts).toBeUndefined();
expect(result.breakdown.messageTokens).toBe(500);
});
it('passes a non-zero toolMessageTokens split through to the blob', () => {
const result = buildPersistedContextUsage({
...baseSnapshot,
breakdown: { ...baseSnapshot.breakdown, toolMessageTokens: 220 },
});
expect(result.breakdown.toolMessageTokens).toBe(220);
expect(result.breakdown.messageTokens).toBe(500);
});
it('keeps invocation-inclusive totals separate from per-tool result shares', () => {
const result = buildPersistedContextUsage({
...baseSnapshot,
breakdown: {
...baseSnapshot.breakdown,
toolMessageTokens: 10,
toolMessageTokenCounts: { search: 4 },
},
});
expect(result.breakdown.toolMessageTokens).toBe(10);
expect(result.breakdown.toolMessageTokenCounts).toEqual({ search: 4 });
expect(
Object.values(result.breakdown.toolMessageTokenCounts ?? {}).reduce(
(total, count) => total + count,
0,
),
).toBeLessThan(result.breakdown.toolMessageTokens ?? 0);
});
it('trims zero-valued result-message entries and clamps their sum', () => {
const result = buildPersistedContextUsage({
...baseSnapshot,
breakdown: {
...baseSnapshot.breakdown,
toolMessageTokens: 2,
toolMessageTokenCounts: { grep: 180, read_file: 0 },
},
});
expect(result.breakdown.toolMessageTokenCounts).toEqual({ grep: 2 });
expect(
Object.values(result.breakdown.toolMessageTokenCounts ?? {}).reduce(
(total, count) => total + count,
0,
),
).toBeLessThanOrEqual(result.breakdown.toolMessageTokens ?? 0);
});
it('preserves a known-zero tool-message total', () => {
const result = buildPersistedContextUsage({
...baseSnapshot,
breakdown: { ...baseSnapshot.breakdown, toolMessageTokens: 0 },
});
expect(result.breakdown.toolMessageTokens).toBe(0);
expect(Object.prototype.hasOwnProperty.call(result.breakdown, 'toolMessageTokens')).toBe(true);
});
it('safely persists prototype-sensitive names and ignores malformed counts', () => {
const counts = JSON.parse('{"__proto__":3,"constructor":3,"invalid":"4"}') as Record<
string,
number
>;
const sdkExtension = {
nested: { source: 'retained-sdk-field', flags: ['opaque'] },
invocation: { estimated: 4, providerOnly: true },
};
const snapshot = {
...baseSnapshot,
breakdown: {
...baseSnapshot.breakdown,
toolMessageTokens: 5,
toolMessageTokenCounts: counts,
sdkExtension,
},
};
const result = buildPersistedContextUsage(snapshot);
const persistedCounts = result.breakdown.toolMessageTokenCounts;
expect(persistedCounts?.['__proto__']).toBe(3);
expect(persistedCounts?.constructor).toBe(2);
expect(persistedCounts?.invalid).toBeUndefined();
expect(Object.keys(persistedCounts ?? {})).toEqual(['__proto__', 'constructor']);
expect(result.breakdown).toMatchObject({ sdkExtension });
expect(snapshot.breakdown.toolMessageTokenCounts).toBe(counts);
});
it('records the final primary call output as completedOutputTokens', () => {
/** The latest snapshot precedes the final call, so its post-snapshot delta
* is that call's output — not the full multi-call response tokenCount. */
const events: TTokenUsageEvent[] = [
{ input_tokens: 100, output_tokens: 40, total_tokens: 140, provider: 'openAI' },
{ input_tokens: 200, output_tokens: 25, total_tokens: 225, provider: 'openAI' },
{
input_tokens: 50,
output_tokens: 12,
usage_type: 'subagent',
provider: 'openAI',
},
];
const result = buildPersistedContextUsage(baseSnapshot, events);
/** Last PRIMARY call's completion (25), skipping the trailing subagent event */
expect(result.completedOutputTokens).toBe(25);
});
it('carries a counted retained tool figure as a second post-snapshot delta', () => {
/** A turn stopped at the tool-call limit keeps the results of the tools its
* final call ran. They are outside the pre-invoke breakdown AND outside the
* final call's output, so they ride as their own field — never folded into
* the provider-reconciled `messageTokens`. */
const events: TTokenUsageEvent[] = [
{ input_tokens: 200, output_tokens: 25, total_tokens: 225, provider: 'openAI' },
];
const result = buildPersistedContextUsage(baseSnapshot, events, { retainedToolTokens: 640 });
expect(result.retainedToolTokens).toBe(640);
expect(result.completedOutputTokens).toBe(25);
/** The provider-reconciled message total is untouched: the retained result is
* an addend the client applies, not part of the exact accounting. */
expect(result.breakdown).toEqual(buildPersistedContextUsage(baseSnapshot, events).breakdown);
});
it.each([
['a normal turn passes nothing', undefined],
['no tool result was retained', 0],
['the count is negative', -5],
['the count is not finite', Number.NaN],
])('omits the retained tool figure when %s', (_label, retainedToolTokens) => {
const result = buildPersistedContextUsage(baseSnapshot, [], { retainedToolTokens });
expect(Object.prototype.hasOwnProperty.call(result, 'retainedToolTokens')).toBe(false);
});
it.each(['openAI', 'bedrock'])('persists the final primary cache split for %s', (provider) => {
const events: TTokenUsageEvent[] = [
{ runId: 'run-1', input_tokens: 100, input_token_details: { cache_read: 10 } },
{
runId: 'run-1',
provider,
model: 'primary-model',
input_tokens: 200,
output_tokens: 25,
input_token_details: { cache_read: 80, cache_creation: 40 },
},
{ runId: 'run-2', input_tokens: 900, input_token_details: { cache_read: 900 } },
{ usage_type: 'summarization', input_tokens: 500, input_token_details: { cache_read: 500 } },
{ usage_type: 'subagent', input_tokens: 600, input_token_details: { cache_read: 600 } },
];
const result = buildPersistedContextUsage(baseSnapshot, events);
expect(result).toMatchObject({
cacheRead: 80,
cacheWrite: 40,
model: 'primary-model',
provider,
completedOutputTokens: 25,
});
});
it('replaces an earlier cache split with a final uncached call', () => {
const result = buildPersistedContextUsage({ ...baseSnapshot, cacheRead: 80, cacheWrite: 40 }, [
{ input_tokens: 200, output_tokens: 25 },
]);
expect(result).toMatchObject({ cacheRead: 0, cacheWrite: 0 });
expect(buildPersistedContextUsage(baseSnapshot).cacheRead).toBeUndefined();
expect(buildPersistedContextUsage(baseSnapshot).model).toBeUndefined();
});
it('omits completedOutputTokens when there are no primary calls', () => {
expect(buildPersistedContextUsage(baseSnapshot, []).completedOutputTokens).toBeUndefined();
});
it('reconciles the inflated estimate to the final call’s real prompt tokens', () => {
/** Real web-search + summarization turn: calibration pinned at 5 inflated
* messageTokens to 187471 (used 213375), but the answer call's true prompt was
* 55773 (Anthropic input_tokens is cache-inclusive; 2071 of it is cache read).
* The persisted blob must show the real context so a reload isn't stuck
* several× too high. */
const inflated: TContextUsageEvent = {
runId: 'run-1',
breakdown: {
maxContextTokens: 250000,
instructionTokens: 4205,
systemMessageTokens: 384,
dynamicInstructionTokens: 1525,
toolSchemaTokens: 2296,
summaryTokens: 1938,
toolCount: 1,
messageCount: 2,
messageTokens: 187471,
availableForMessages: 233295,
},
contextBudget: 237500,
remainingContextTokens: 24125,
calibrationRatio: 5,
};
const events: TTokenUsageEvent[] = [
{
input_tokens: 55773, // cache-inclusive: 53702 fresh + 2071 read
output_tokens: 3780,
input_token_details: { cache_read: 2071, cache_creation: 0 },
provider: 'anthropic',
runId: 'run-1',
},
];
const result = buildPersistedContextUsage(inflated, events);
expect(237500 - (result.remainingContextTokens ?? 0)).toBe(55773);
expect(result.breakdown.messageTokens).toBe(55773 - 4205 - 1938);
expect(result.completedOutputTokens).toBe(3780);
});
it('attributes completedOutputTokens to the snapshot run, not a parallel run', () => {
/** Parallel/direct runs interleave: this snapshot is run-1, but run-2 emits a
* later primary usage. The persisted delta must be run-1's own output (40),
* never run-2's trailing output (99). */
const events: TTokenUsageEvent[] = [
{
input_tokens: 100,
output_tokens: 40,
total_tokens: 140,
provider: 'openAI',
runId: 'run-1',
},
{
input_tokens: 200,
output_tokens: 99,
total_tokens: 299,
provider: 'openAI',
runId: 'run-2',
},
];
const result = buildPersistedContextUsage(baseSnapshot, events);
expect(result.completedOutputTokens).toBe(40);
});
it('omits completedOutputTokens when only other runs emitted usage', () => {
/** The snapshot run never completed (no matching primary); a sibling run's
* output must not be borrowed — fall back to the per-message estimate. */
const events: TTokenUsageEvent[] = [
{
input_tokens: 200,
output_tokens: 99,
total_tokens: 299,
provider: 'openAI',
runId: 'run-2',
},
];
expect(buildPersistedContextUsage(baseSnapshot, events).completedOutputTokens).toBeUndefined();
});
it('matches untagged usage events for back-compat (older lib / resume)', () => {
/** Events without a runId predate run tagging; they match any snapshot so the
* last primary (25) is still recorded. */
const events: TTokenUsageEvent[] = [
{ input_tokens: 100, output_tokens: 40, total_tokens: 140, provider: 'openAI' },
{ input_tokens: 200, output_tokens: 25, total_tokens: 225, provider: 'openAI' },
];
expect(buildPersistedContextUsage(baseSnapshot, events).completedOutputTokens).toBe(25);
});
});
describe('computeSummaryUsedTokens', () => {
const summarized = (over?: Partial<TContextUsageEvent>): TContextUsageEvent => ({
runId: 'run-1',
breakdown: {
maxContextTokens: 1000,
instructionTokens: 50,
systemMessageTokens: 50,
dynamicInstructionTokens: 0,
toolSchemaTokens: 0,
summaryTokens: 80,
toolCount: 0,
messageCount: 1,
messageTokens: 20,
availableForMessages: 900,
},
contextBudget: 1000,
remainingContextTokens: 700,
effectiveInstructionTokens: 50,
...over,
});
it('uses contextBudget − remainingContextTokens when available', () => {
expect(computeSummaryUsedTokens(summarized())).toBe(300);
});
it('falls back to instructions + summary + messages, including summaryTokens', () => {
/** summaryTokens is a separate breakdown field, so the no-remaining fallback
* must add it: 50 + 80 + 20 = 150, not 70. */
expect(computeSummaryUsedTokens(summarized({ remainingContextTokens: undefined }))).toBe(150);
});
it('returns undefined when the turn did not summarize', () => {
expect(
computeSummaryUsedTokens(
summarized({ breakdown: { ...summarized().breakdown, summaryTokens: 0 } }),
),
).toBeUndefined();
expect(computeSummaryUsedTokens(null)).toBeUndefined();
expect(computeSummaryUsedTokens(undefined)).toBeUndefined();
});
it('subtracts the response’s earlier tool-loop outputs from the marker', () => {
/** 300 baseUsed − 90 earlier outputs = 210, so the client estimate
* (summaryBaseline + full response tokenCount) doesn’t double-count them. */
expect(computeSummaryUsedTokens(summarized(), 90)).toBe(210);
});
it('clamps to undefined when the prior outputs exceed the baseline', () => {
expect(computeSummaryUsedTokens(summarized(), 5000)).toBeUndefined();
});
});
describe('priorRunOutputTokens', () => {
const ev = (over: Partial<TTokenUsageEvent>): TTokenUsageEvent => ({
input_tokens: 10,
output_tokens: 0,
total_tokens: 10,
provider: 'openAI',
...over,
});
it('sums primary outputs before the index for the matching run', () => {
const events = [
ev({ output_tokens: 20, runId: 'run-1' }),
ev({ output_tokens: 30, runId: 'run-1' }),
ev({ output_tokens: 99, runId: 'run-1' }), // at/after the index — excluded
];
expect(priorRunOutputTokens(events, 2, 'run-1')).toBe(50);
});
it('counts run-matched primary + summarization, skips subagent/sequential and other runs', () => {
/** Both the primary and the summarization output are in this run's tokenCount
* AND baseline, so both are subtracted; subagent/sequential are excluded from
* the reported output total; a parallel run's primary is not this snapshot's. */
const events = [
ev({ output_tokens: 20, runId: 'run-1' }), // primary, matches
ev({ output_tokens: 8, runId: 'run-1', usage_type: 'summarization' }), // counted
ev({ output_tokens: 5, runId: 'run-1', usage_type: 'subagent' }), // skipped
ev({ output_tokens: 7, runId: 'run-1', usage_type: 'sequential' }), // skipped
ev({ output_tokens: 40, runId: 'run-2' }), // other-run primary — skipped
];
expect(priorRunOutputTokens(events, 5, 'run-1')).toBe(28);
});
it('does not subtract a parallel sibling run’s summarization output', () => {
/** The summarize detour inherits the graph run id (traceConfig), so a sibling
* run's summary carries a DIFFERENT runId; its summary is in the sibling's
* baseline, not this snapshot's, so subtracting it would under-report. */
const events = [
ev({ output_tokens: 20, runId: 'run-1' }),
ev({ output_tokens: 8, runId: 'run-2', usage_type: 'summarization' }), // sibling — skipped
];
expect(priorRunOutputTokens(events, 2, 'run-1')).toBe(20);
});
it('matches untagged events for back-compat and returns 0 with no prior calls', () => {
const events = [ev({ output_tokens: 20 }), ev({ output_tokens: 30 })];
expect(priorRunOutputTokens(events, 2, 'run-1')).toBe(50);
expect(priorRunOutputTokens(events, 0, 'run-1')).toBe(0);
});
});
describe('buildAbortedResponseMetadata', () => {
it('returns undefined for an empty job', () => {
expect(buildAbortedResponseMetadata(undefined)).toBeUndefined();
expect(buildAbortedResponseMetadata({})).toBeUndefined();
expect(buildAbortedResponseMetadata({ tokenUsage: 'not json' })).toBeUndefined();
});
it('rebuilds the usage/cost rollup from the job’s persisted emitted usage', () => {
const events: TTokenUsageEvent[] = [
{ input_tokens: 100, output_tokens: 20, total_tokens: 120, provider: 'openAI', cost: 0.001 },
];
const result = buildAbortedResponseMetadata({ tokenUsage: JSON.stringify(events) });
expect(result?.usage).toEqual({
input: 100,
output: 20,
cacheWrite: 0,
cacheRead: 0,
cost: 0.001,
});
});
it('never persists a breakdown for a stopped response (avoids final-call over-count)', () => {
const events: TTokenUsageEvent[] = [
{ input_tokens: 100, output_tokens: 20, total_tokens: 120, provider: 'openAI' },
];
const result = buildAbortedResponseMetadata({ tokenUsage: JSON.stringify(events) });
expect(result).toEqual({ usage: { input: 100, output: 20, cacheWrite: 0, cacheRead: 0 } });
expect((result as { contextUsage?: unknown }).contextUsage).toBeUndefined();
});
const abortSnapshot: TContextUsageEvent = {
runId: 'run-1',
breakdown: {
maxContextTokens: 1000,
instructionTokens: 50,
systemMessageTokens: 50,
dynamicInstructionTokens: 0,
toolSchemaTokens: 0,
summaryTokens: 80,
toolCount: 0,
messageCount: 1,
messageTokens: 20,
availableForMessages: 900,
},
contextBudget: 1000,
remainingContextTokens: 700,
};
it('persists the summary marker (but not the full snapshot) for a stopped summarized turn', () => {
/** A single-call stopped turn: the interrupted call emitted no usage, so the
* marker is the full baseUsed (300) with nothing to subtract. */
const result = buildAbortedResponseMetadata({
tokenUsage: JSON.stringify([]),
contextUsage: JSON.stringify(abortSnapshot),
});
expect(result?.summaryUsedTokens).toBe(300);
/** The full snapshot stays off the abort path (completedOutputTokens ambiguity). */
expect((result as { contextUsage?: unknown }).contextUsage).toBeUndefined();
});
it('does not subtract any output from the marker on a stopped turn', () => {
/** The abort tokenCount comes from countTokens(text) or is absent — it does
* NOT fold in summarization/earlier-call output the way recordCollectedUsage
* does. So the marker is the full baseUsed (300); subtracting the summarization
* (8) or the primary (20) here would under-report after reload. */
const events: TTokenUsageEvent[] = [
{
input_tokens: 100,
output_tokens: 20,
total_tokens: 120,
provider: 'openAI',
runId: 'run-1',
},
{
input_tokens: 60,
output_tokens: 8,
total_tokens: 68,
provider: 'openAI',
runId: 'run-1',
usage_type: 'summarization',
},
];
const result = buildAbortedResponseMetadata({
tokenUsage: JSON.stringify(events),
contextUsage: JSON.stringify(abortSnapshot),
});
expect(result?.summaryUsedTokens).toBe(300);
});
});
describe('resolveAgentTokenConfig', () => {
const primary = { 'gpt-4': { prompt: 0.01, completion: 0.03, context: 8192 } };
const subagent = { 'gpt-4': { prompt: 0.05, completion: 0.15, context: 8192 } };
it('returns the producing agent’s own config', () => {
const byAgentId = new Map([
['primary', primary],
['sub', subagent],
]);
expect(resolveAgentTokenConfig({ agentId: 'sub', byAgentId, fallback: primary })).toBe(
subagent,
);
});
it('observes a selected lazy subagent added after the resolver is created', () => {
const byAgentId = new Map([['primary', primary]]);
const resolveForUsage = (agentId: string) =>
resolveAgentTokenConfig({ agentId, byAgentId, fallback: primary });
byAgentId.set('lazy-subagent', subagent);
expect(resolveForUsage('lazy-subagent')).toBe(subagent);
});
it('returns undefined for a known agent with no configured rates (built-in pricing)', () => {
/** A known non-custom agent (e.g. a normal OpenAI agent) is recorded with an
* undefined config; it must NOT inherit the custom-primary rates. */
const byAgentId = new Map<string, typeof primary | undefined>([
['primary', primary],
['known-openai', undefined],
]);
expect(
resolveAgentTokenConfig({ agentId: 'known-openai', byAgentId, fallback: primary }),
).toBeUndefined();
});
it('falls back to the primary config for an untagged usage', () => {
const byAgentId = new Map([['primary', primary]]);
expect(resolveAgentTokenConfig({ agentId: undefined, byAgentId, fallback: primary })).toBe(
primary,
);
});
it('falls back to the primary config for an unknown agent id', () => {
const byAgentId = new Map([['primary', primary]]);
expect(resolveAgentTokenConfig({ agentId: 'ghost', byAgentId, fallback: primary })).toBe(
primary,
);
});
it('returns the fallback when there is no per-agent map (single-endpoint graphs)', () => {
expect(resolveAgentTokenConfig({ agentId: 'primary', fallback: primary })).toBe(primary);
});
});
describe('createDetachedSubagentUsageRecorder', () => {
it('snapshots per-agent pricing and records each call as subagent usage', async () => {
const spendTokens = jest.fn().mockResolvedValue(undefined);
const childConfig = { 'child-model': { prompt: 0.01, completion: 0.02, context: 4096 } };
const configs = new Map([['child-agent', childConfig]]);
const recorder = createDetachedSubagentUsageRecorder(
{
spendTokens,
spendStructuredTokens: jest.fn().mockResolvedValue(undefined),
},
{
user: 'user-1',
conversationId: 'parent-1',
messageId: 'response-1',
model: 'parent-model',
endpointTokenConfigByAgentId: configs,
},
);
configs.set('child-agent', {
'child-model': { prompt: 99, completion: 99, context: 4096 },
});
await recorder({
usage_type: 'subagent',
input_tokens: 12,
output_tokens: 4,
model: 'child-model',
agentId: 'child-agent',
});
expect(spendTokens).toHaveBeenCalledWith(
expect.objectContaining({
user: 'user-1',
conversationId: 'parent-1',
messageId: 'response-1',
context: 'subagent',
model: 'child-model',
endpointTokenConfig: childConfig,
}),
{ promptTokens: 12, completionTokens: 4 },
);
});
it('does not recreate billing records after the owning principal is fenced or deleted', async () => {
const spendTokens = jest.fn().mockResolvedValue(undefined);
const updateBalance = jest.fn().mockResolvedValue(undefined);
const insertMany = jest.fn().mockResolvedValue(undefined);
const recorder = createDetachedSubagentUsageRecorder(
{
spendTokens,
spendStructuredTokens: jest.fn().mockResolvedValue(undefined),
bulkWriteOps: { updateBalance, insertMany },
isPrincipalActive: jest.fn().mockResolvedValue(false),
},
{
user: 'deleted-user',
conversationId: 'parent-1',
messageId: 'response-1',
model: 'child-model',
},
);
await recorder({
usage_type: 'subagent',
input_tokens: 12,
output_tokens: 4,
model: 'child-model',
});
expect(spendTokens).not.toHaveBeenCalled();
expect(updateBalance).not.toHaveBeenCalled();
expect(insertMany).not.toHaveBeenCalled();
});
});
describe('resolveRunUsageContext', () => {
it('labels a stopped run as an abort and a completed run as a message', () => {
expect(resolveRunUsageContext(true)).toBe('abort');
expect(resolveRunUsageContext(false)).toBe('message');
});
});
describe('hasRecordedProviderUsage', () => {
it('is true once the provider reported any consumption, even with no output', () => {
expect(hasRecordedProviderUsage({ input_tokens: 10, output_tokens: 0 })).toBe(true);
expect(hasRecordedProviderUsage({ input_tokens: 0, output_tokens: 5 })).toBe(true);
});
it('is false when nothing was recorded or the report is all zero', () => {
expect(hasRecordedProviderUsage(undefined)).toBe(false);
expect(hasRecordedProviderUsage(null)).toBe(false);
expect(hasRecordedProviderUsage({ input_tokens: 0, output_tokens: 0 })).toBe(false);
expect(hasRecordedProviderUsage({})).toBe(false);
});
});
describe('recordFallbackTokenUsage', () => {
const txMetadata = {
user: 'user-1',
conversationId: 'convo-1',
messageId: 'msg-1',
model: 'gpt-4',
balance: { enabled: true },
transactions: { enabled: true },
};
const estimate = { promptTokens: 40, completionTokens: 7 };
it('records nothing once provider usage was recorded, even with no output', async () => {
const spendTokens = jest.fn().mockResolvedValue(undefined);
await recordFallbackTokenUsage(
{ spendTokens },
{ ...estimate, usage: { input_tokens: 40, output_tokens: 0 }, txMetadata },
);
expect(spendTokens).not.toHaveBeenCalled();
});
it('bills the estimate under the given context when nothing was recorded', async () => {
const spendTokens = jest.fn().mockResolvedValue(undefined);
await recordFallbackTokenUsage({ spendTokens }, { ...estimate, txMetadata, context: 'abort' });
expect(spendTokens).toHaveBeenCalledTimes(1);
expect(spendTokens).toHaveBeenCalledWith({ ...txMetadata, context: 'abort' }, estimate);
});
it('labels the estimate from the stop state when no context is given', async () => {
const spendTokens = jest.fn().mockResolvedValue(undefined);
await recordFallbackTokenUsage({ spendTokens }, { ...estimate, txMetadata, aborted: true });
await recordFallbackTokenUsage({ spendTokens }, { ...estimate, txMetadata, aborted: false });
await recordFallbackTokenUsage({ spendTokens }, { ...estimate, txMetadata });
expect(spendTokens.mock.calls.map(([tx]) => tx.context)).toEqual([
'abort',
'message',
'message',
]);
});
it('lets an explicit context override the stop state', async () => {
const spendTokens = jest.fn().mockResolvedValue(undefined);
await recordFallbackTokenUsage(
{ spendTokens },
{ ...estimate, txMetadata, aborted: true, context: 'incomplete' },
);
expect(spendTokens).toHaveBeenCalledWith({ ...txMetadata, context: 'incomplete' }, estimate);
});
it('records nothing when a later primary call was billed but the aggregate hides it', async () => {
const spendTokens = jest.fn().mockResolvedValue(undefined);
await recordFallbackTokenUsage(
{ spendTokens },
{
...estimate,
usage: { input_tokens: 0, output_tokens: 0 },
collectedUsage: [
{ input_tokens: 0, output_tokens: 0 },
{ input_tokens: 5, output_tokens: 0 },
],
txMetadata,
},
);
expect(spendTokens).not.toHaveBeenCalled();
});
it('still bills the estimate when only non-primary calls were collected', async () => {
const spendTokens = jest.fn().mockResolvedValue(undefined);
await recordFallbackTokenUsage(
{ spendTokens },
{
...estimate,
usage: { input_tokens: 0, output_tokens: 0 },
collectedUsage: [
{ input_tokens: 9, output_tokens: 3, usage_type: 'summarization' },
{ input_tokens: 9, output_tokens: 3, usage_type: 'subagent' },
],
txMetadata,
},
);
expect(spendTokens).toHaveBeenCalledTimes(1);
});
it('bills a reasoning count the estimate cannot see as its own row', async () => {
const spendTokens = jest.fn().mockResolvedValue(undefined);
await recordFallbackTokenUsage(
{ spendTokens },
{
...estimate,
usage: { input_tokens: 0, output_tokens: 0, reasoning_tokens: 12 },
txMetadata,
},
);
expect(spendTokens).toHaveBeenCalledTimes(2);
expect(spendTokens).toHaveBeenLastCalledWith(
{ ...txMetadata, context: 'reasoning' },
{ completionTokens: 12 },
);
});
it('logs a billing failure instead of throwing', async () => {
const spendTokens = jest.fn().mockRejectedValue(new Error('db down'));
await expect(
recordFallbackTokenUsage({ spendTokens }, { ...estimate, txMetadata }),
).resolves.toBeUndefined();
});
});
describe('hasRecordedPrimaryUsage', () => {
it('finds a billed primary call anywhere in the collected entries', () => {
expect(
hasRecordedPrimaryUsage([
{ input_tokens: 0, output_tokens: 0 },
null,
{ input_tokens: 5, output_tokens: 0 },
]),
).toBe(true);
expect(
hasRecordedPrimaryUsage([{ input_tokens: 0, output_tokens: 7, usage_type: 'message' }]),
).toBe(true);
});
it('ignores non-primary entries and empty input', () => {
expect(
hasRecordedPrimaryUsage([
{ input_tokens: 9, output_tokens: 3, usage_type: 'summarization' },
{ input_tokens: 9, output_tokens: 3, usage_type: 'subagent' },
{ input_tokens: 9, output_tokens: 3, usage_type: 'sequential' },
]),
).toBe(false);
expect(hasRecordedPrimaryUsage([{ input_tokens: 0, output_tokens: 0 }])).toBe(false);
expect(hasRecordedPrimaryUsage([])).toBe(false);
expect(hasRecordedPrimaryUsage(undefined)).toBe(false);
});
});