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
💰 fix: Bill Stopped Agent Turns From Provider Usage (#15889)
Danny Avilaf6335cb9d715
diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.jsindex e37693d986..9e7e4d5017 100644--- a/api/server/controllers/agents/client.js+++ b/api/server/controllers/agents/client.js@@ -26,6 +26,8 @@ const {applyContextToAgent,isMemoryAgentEnabled,recordCollectedUsage,+ resolveRunUsageContext,+ recordFallbackTokenUsage,createDetachedSubagentUsageRecorder,sendEvent,computeUsageCostUSD,@@ -5170,20 +5172,14 @@ class AgentClient extends BaseClient {this.artifactPromises.push(...attachments);}- /** Skip token spending if aborted - the abort handler (abortMiddleware.js) handles it- This prevents double-spending when user aborts via `/api/agents/chat/abort` */- const wasAborted = abortController?.signal?.aborted;- if (!wasAborted) {- await this.recordCollectedUsage({- context: 'message',- balance: balanceConfig,- transactions: transactionsConfig,- });- } else {- logger.debug(- '[api/server/controllers/agents/client.js #chatCompletion] Skipping token spending - handled by abort middleware',- );- }+ /** The run owns its usage even when stopped: `/api/agents/chat/abort`+ * only signals the abort, so nothing else records what was consumed.+ * A stopped turn is labelled as such on its transactions. */+ await this.recordCollectedUsage({+ context: resolveRunUsageContext(abortController?.signal?.aborted === true),+ balance: balanceConfig,+ transactions: transactionsConfig,+ });} catch (err) {logger.error('[api/server/controllers/agents/client.js #chatCompletion] Error in cleanup phase',@@ -5840,14 +5836,11 @@ class AgentClient extends BaseClient {}try {- const wasAborted = abortController?.signal?.aborted;- if (!wasAborted) {- await this.recordCollectedUsage({- context: 'message',- balance: balanceConfig,- transactions: transactionsConfig,- });- }+ await this.recordCollectedUsage({+ context: resolveRunUsageContext(abortController?.signal?.aborted === true),+ balance: balanceConfig,+ transactions: transactionsConfig,+ });} catch (err) {logger.error('[api/server/controllers/agents/client.js #resumeCompletion] Error in cleanup phase',@@ -6155,13 +6148,19 @@ class AgentClient extends BaseClient {transactions,promptTokens,completionTokens,- context = 'message',+ context,}) {- try {- await db.spendTokens(- {+ await recordFallbackTokenUsage(+ { spendTokens: db.spendTokens },+ {+ usage,+ context,+ collectedUsage: this.collectedUsage,+ aborted: this.abortController?.signal?.aborted === true,+ promptTokens,+ completionTokens,+ txMetadata: {model,- context,balance,transactions,messageId: this.responseMessageId,@@ -6169,35 +6168,8 @@ class AgentClient extends BaseClient {user: this.user ?? this.options.req.user?.id,endpointTokenConfig: this.options.endpointTokenConfig,},- { promptTokens, completionTokens },- );-- if (- usage &&- typeof usage === 'object' &&- 'reasoning_tokens' in usage &&- typeof usage.reasoning_tokens === 'number'- ) {- await db.spendTokens(- {- model,- balance,- transactions,- context: 'reasoning',- messageId: this.responseMessageId,- conversationId: this.conversationId,- user: this.user ?? this.options.req.user?.id,- endpointTokenConfig: this.options.endpointTokenConfig,- },- { completionTokens: usage.reasoning_tokens },- );- }- } catch (error) {- logger.error(- '[api/server/controllers/agents/client.js #recordTokenUsage] Error recording token usage',- getSafeErrorMetadata(error),- );- }+ },+ );}/** Anthropic Claude models use a distinct BPE tokenizer; all others default to o200k_base. */diff --git a/api/server/controllers/agents/client.test.js b/api/server/controllers/agents/client.test.jsindex 54b869ca88..8c1065a72e 100644--- a/api/server/controllers/agents/client.test.js+++ b/api/server/controllers/agents/client.test.js@@ -1512,6 +1512,56 @@ describe('AgentClient - interrupt discovery persistence', () => {expect(metaWhenResumed).toEqual(seed);});+ it('records collected usage as an abort when a resumed run is stopped', async () => {+ jest.clearAllMocks();+ const streamId = 'conversation-resume-stopped';+ const job = await GenerationJobManager.createJob(streamId, 'user-123', streamId);+ const abortController = new AbortController();+ mockCreateRun.mockImplementationOnce(async () => ({+ Graph: null,+ resume: jest.fn(async () => {+ abortController.abort();+ }),+ processStream: jest.fn().mockResolvedValue(),+ getCalibrationRatio: jest.fn(() => 0),+ getInterrupt: jest.fn(() => undefined),+ }));+ const client = new AgentClient({+ req: {+ user: { id: 'user-123' },+ body: { endpoint: EModelEndpoint.agents, agent_id: 'agent-123', isTemporary: true },+ config: { endpoints: { [EModelEndpoint.agents]: {} } },+ _resumableStreamId: streamId,+ },+ res: {},+ agent: {+ id: 'agent-123',+ endpoint: EModelEndpoint.openAI,+ provider: EModelEndpoint.openAI,+ model_parameters: { model: 'gpt-4' },+ },+ contentParts: [],+ collectedUsage: [{ input_tokens: 10, output_tokens: 5 }],+ artifactPromises: [],+ jobCreatedAt: job.createdAt,+ });+ client.conversationId = streamId;+ client.responseMessageId = 'response-resume-stopped';+ client.recordCollectedUsage = jest.fn().mockResolvedValue();++ await client.resumeCompletion({+ resumeValue: { decisions: [] },+ streamId,+ checkpointNamespace: 'resume-stopped',+ abortController,+ });++ expect(client.recordCollectedUsage).toHaveBeenCalledTimes(1);+ expect(client.recordCollectedUsage).toHaveBeenCalledWith(+ expect.objectContaining({ context: 'abort' }),+ );+ });+it('publishes the inherited context meta before a fresh run streams', async () => {const streamId = 'conversation-context-meta-stream-seed';const job = await GenerationJobManager.createJob(streamId, 'user-123', streamId);@@ -2886,6 +2936,93 @@ describe('AgentClient - startup telemetry', () => {);});+ it('records collected usage as an abort when the run is stopped', async () => {+ jest.clearAllMocks();+ const abortController = new AbortController();+ mockCreateRun.mockResolvedValue({+ Graph: null,+ processStream: jest.fn(async () => {+ abortController.abort();+ }),+ getCalibrationRatio: jest.fn(() => 0),+ });+ mockIsHITLEnabled.mockReturnValue(false);+ const client = new AgentClient({+ req: {+ user: { id: 'user-123' },+ body: {},+ config: { endpoints: { [EModelEndpoint.agents]: {} } },+ _resumableStreamId: 'conversation-stopped',+ },+ res: {},+ agent: {+ id: 'agent-123',+ endpoint: EModelEndpoint.openAI,+ provider: EModelEndpoint.openAI,+ model_parameters: { model: 'gpt-4' },+ hide_sequential_outputs: false,+ },+ endpointTokenConfig: {},+ eventHandlers: {},+ contentParts: [],+ collectedUsage: [{ input_tokens: 10, output_tokens: 5 }],+ artifactPromises: [],+ });+ client.conversationId = 'conversation-stopped';+ client.responseMessageId = 'response-conversation-stopped';+ client.parentMessageId = 'parent-conversation-stopped';+ client.recordCollectedUsage = jest.fn().mockResolvedValue();++ await client.chatCompletion({ payload: [], abortController });++ expect(client.recordCollectedUsage).toHaveBeenCalledTimes(1);+ expect(client.recordCollectedUsage).toHaveBeenCalledWith(+ expect.objectContaining({ context: 'abort' }),+ );+ });++ it('records collected usage as a message when the run completes', async () => {+ jest.clearAllMocks();+ mockCreateRun.mockResolvedValue({+ Graph: null,+ processStream: jest.fn().mockResolvedValue(),+ getCalibrationRatio: jest.fn(() => 0),+ });+ mockIsHITLEnabled.mockReturnValue(false);+ const client = new AgentClient({+ req: {+ user: { id: 'user-123' },+ body: {},+ config: { endpoints: { [EModelEndpoint.agents]: {} } },+ _resumableStreamId: 'conversation-completed',+ },+ res: {},+ agent: {+ id: 'agent-123',+ endpoint: EModelEndpoint.openAI,+ provider: EModelEndpoint.openAI,+ model_parameters: { model: 'gpt-4' },+ hide_sequential_outputs: false,+ },+ endpointTokenConfig: {},+ eventHandlers: {},+ contentParts: [],+ collectedUsage: [{ input_tokens: 10, output_tokens: 5 }],+ artifactPromises: [],+ });+ client.conversationId = 'conversation-completed';+ client.responseMessageId = 'response-conversation-completed';+ client.parentMessageId = 'parent-conversation-completed';+ client.recordCollectedUsage = jest.fn().mockResolvedValue();++ await client.chatCompletion({ payload: [], abortController: new AbortController() });++ expect(client.recordCollectedUsage).toHaveBeenCalledTimes(1);+ expect(client.recordCollectedUsage).toHaveBeenCalledWith(+ expect.objectContaining({ context: 'message' }),+ );+ });+it('classifies a terminal chat-model failure without logging provider content', async () => {jest.clearAllMocks();const { logger } = require('@librechat/data-schemas');diff --git a/api/server/controllers/agents/recordCollectedUsage.spec.js b/api/server/controllers/agents/recordCollectedUsage.spec.jsindex 009c5b262c..6e00904107 100644--- a/api/server/controllers/agents/recordCollectedUsage.spec.js+++ b/api/server/controllers/agents/recordCollectedUsage.spec.js@@ -89,6 +89,77 @@ describe('AgentClient - recordCollectedUsage', () => {client.user = 'user-123';});+ describe('recordTokenUsage fallback', () => {+ const estimate = { promptTokens: 40, completionTokens: 7 };++ it('does not bill the estimate when provider usage was already recorded', async () => {+ await client.recordTokenUsage({+ ...estimate,+ usage: { input_tokens: 40, output_tokens: 0 },+ model: 'gpt-4',+ });++ expect(mockSpendTokens).not.toHaveBeenCalled();+ });++ it('bills the estimate when no provider usage was recorded', async () => {+ await client.recordTokenUsage({ ...estimate, usage: undefined, model: 'gpt-4' });++ expect(mockSpendTokens).toHaveBeenCalledTimes(1);+ expect(mockSpendTokens).toHaveBeenCalledWith(+ expect.objectContaining({ model: 'gpt-4', context: 'message' }),+ estimate,+ );+ });++ it('labels the estimate as an abort when the run was stopped and no context is given', async () => {+ client.abortController = { signal: { aborted: true } };++ await client.recordTokenUsage({ ...estimate, usage: undefined, model: 'gpt-4' });++ expect(mockSpendTokens).toHaveBeenCalledWith(+ expect.objectContaining({ context: 'abort' }),+ estimate,+ );+ });++ it('labels the estimate as a message when the run completed and no context is given', async () => {+ client.abortController = { signal: { aborted: false } };++ await client.recordTokenUsage({ ...estimate, usage: undefined, model: 'gpt-4' });++ expect(mockSpendTokens).toHaveBeenCalledWith(+ expect.objectContaining({ context: 'message' }),+ estimate,+ );+ });++ it('does not bill the estimate when a later primary call was billed but the aggregate hides it', async () => {+ client.collectedUsage = [+ { input_tokens: 0, output_tokens: 0 },+ { input_tokens: 5, output_tokens: 0 },+ ];++ await client.recordTokenUsage({+ ...estimate,+ usage: { input_tokens: 0, output_tokens: 0 },+ model: 'gpt-4',+ });++ expect(mockSpendTokens).not.toHaveBeenCalled();+ });++ it('still bills the estimate when the recorded report is all zero', async () => {+ await client.recordTokenUsage({+ ...estimate,+ usage: { input_tokens: 0, output_tokens: 0 },+ model: 'gpt-4',+ });++ expect(mockSpendTokens).toHaveBeenCalledTimes(1);+ });+ });+describe('basic functionality', () => {it('should delegate to recordCollectedUsage with full deps', async () => {const collectedUsage = [{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' }];diff --git a/api/server/middleware/abortMiddleware.js b/api/server/middleware/abortMiddleware.jsindex 76c9cb1f07..532c748a7a 100644--- a/api/server/middleware/abortMiddleware.js+++ b/api/server/middleware/abortMiddleware.js@@ -6,8 +6,6 @@ const {countTokens,isAbortError,GenerationJobManager,- recordCollectedUsage,- getTransactionsConfig,sanitizeMessageForTransmit,buildAbortedResponseMetadata,} = require('@librechat/api');@@ -17,58 +15,6 @@ const { sendError } = require('~/server/middleware/error');const { abortRun } = require('./abortRun');const db = require('~/models');-/**- * Spend tokens for all models from collected usage.- * This handles both sequential and parallel agent execution.- *- * IMPORTANT: After spending, this function clears the collectedUsage array- * to prevent double-spending. The array is shared with AgentClient.collectedUsage,- * so clearing it here prevents the finally block from also spending tokens.- *- * @param {Object} params- * @param {string} params.userId - User ID- * @param {string} params.conversationId - Conversation ID- * @param {Array<Object>} params.collectedUsage - Usage metadata from all models- * @param {string} [params.fallbackModel] - Fallback model name if not in usage- * @param {string} [params.messageId] - The response message ID for transaction correlation- * @param {AppConfig['transactions']} [params.transactions] - Resolved transactions config- */-async function spendCollectedUsage({- userId,- conversationId,- collectedUsage,- fallbackModel,- messageId,- transactions,-}) {- if (!collectedUsage || collectedUsage.length === 0) {- return;- }-- await recordCollectedUsage(- {- spendTokens: db.spendTokens,- spendStructuredTokens: db.spendStructuredTokens,- pricing: { getMultiplier: db.getMultiplier, getCacheMultiplier: db.getCacheMultiplier },- bulkWriteOps: { insertMany: db.bulkInsertTransactions, updateBalance: db.updateBalance },- },- {- user: userId,- conversationId,- collectedUsage,- context: 'abort',- messageId,- model: fallbackModel,- transactions,- },- );-- // Clear the array to prevent double-spending from the AgentClient finally block.- // The collectedUsage array is shared by reference with AgentClient.collectedUsage,- // so clearing it here ensures recordCollectedUsage() sees an empty array and returns early.- collectedUsage.length = 0;-}-/*** Abort an active message generation.* Uses GenerationJobManager for all agent requests.@@ -94,10 +40,9 @@ async function abortMessage(req, res) {return;}- const { jobData, content, text, collectedUsage } = abortResult;+ const { jobData, content, text } = abortResult;const completionTokens = await countTokens(text);- const promptTokens = jobData?.promptTokens ?? 0;const responseMessage = {messageId: jobData?.responseMessageId,@@ -129,25 +74,9 @@ async function abortMessage(req, res) {responseMessage.metadata = abortMetadata;}- const transactions = getTransactionsConfig(req.config);-- // Spend tokens for ALL models from collectedUsage (handles parallel agents/addedConvo)- if (collectedUsage && collectedUsage.length > 0) {- await spendCollectedUsage({- userId,- conversationId: jobData?.conversationId,- collectedUsage,- fallbackModel: jobData?.model,- messageId: jobData?.responseMessageId,- transactions,- });- } else {- // Fallback: no collected usage, use text-based token counting for primary model only- await db.spendTokens(- { ...responseMessage, context: 'incomplete', user: userId, transactions },- { promptTokens, completionTokens },- );- }+ /** The run that produced this response records its own usage on exit+ * (`AgentClient` labels a stopped turn `'abort'`), so billing here would+ * charge it a second time. This route only stops and persists. */await db.saveMessage({@@ -302,5 +231,4 @@ const handleAbortError = async (res, req, error, data) => {module.exports = {handleAbort,handleAbortError,- spendCollectedUsage,};diff --git a/api/server/middleware/abortMiddleware.spec.js b/api/server/middleware/abortMiddleware.spec.jsindex 8a64feae89..ee7ec98c20 100644--- a/api/server/middleware/abortMiddleware.spec.js+++ b/api/server/middleware/abortMiddleware.spec.js@@ -1,14 +1,9 @@/**- * Tests for abortMiddleware - spendCollectedUsage function+ * Tests for abortMiddleware.*- * This tests the token spending logic for abort scenarios,- * particularly for parallel agents (addedConvo) where multiple- * models need their tokens spent.- *- * spendCollectedUsage delegates to recordCollectedUsage from @librechat/api,- * passing pricing + bulkWriteOps deps, with context: 'abort'.- * After spending, it clears the collectedUsage array to prevent double-spending- * from the AgentClient finally block (which shares the same array reference).+ * The run that produced a stopped response records its own usage on exit+ * (AgentClient labels it 'abort'), so this route must not bill: it only stops+ * the job and persists the partial response.*/const mockSpendTokens = jest.fn().mockResolvedValue();@@ -86,7 +81,7 @@ const { logger } = require('@librechat/data-schemas');const { sendError } = require('~/server/middleware/error');const { GenerationJobManager } = require('@librechat/api');const db = require('~/models');-const { handleAbort, handleAbortError, spendCollectedUsage } = require('./abortMiddleware');+const { handleAbort, handleAbortError } = require('./abortMiddleware');const buildAbortRequest = () => ({body: {@@ -97,169 +92,6 @@ const buildAbortRequest = () => ({},});-describe('abortMiddleware - spendCollectedUsage', () => {- beforeEach(() => {- jest.clearAllMocks();- });-- describe('spendCollectedUsage delegation', () => {- it('should return early if collectedUsage is empty', async () => {- await spendCollectedUsage({- userId: 'user-123',- conversationId: 'convo-123',- collectedUsage: [],- fallbackModel: 'gpt-4',- });-- expect(mockRecordCollectedUsage).not.toHaveBeenCalled();- });-- it('should return early if collectedUsage is null', async () => {- await spendCollectedUsage({- userId: 'user-123',- conversationId: 'convo-123',- collectedUsage: null,- fallbackModel: 'gpt-4',- });-- expect(mockRecordCollectedUsage).not.toHaveBeenCalled();- });-- it('should call recordCollectedUsage with abort context and full deps', async () => {- const collectedUsage = [{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' }];-- await spendCollectedUsage({- userId: 'user-123',- conversationId: 'convo-123',- collectedUsage,- fallbackModel: 'gpt-4',- messageId: 'msg-123',- });-- expect(mockRecordCollectedUsage).toHaveBeenCalledTimes(1);- expect(mockRecordCollectedUsage).toHaveBeenCalledWith(- {- spendTokens: expect.any(Function),- spendStructuredTokens: expect.any(Function),- pricing: {- getMultiplier: mockGetMultiplier,- getCacheMultiplier: mockGetCacheMultiplier,- },- bulkWriteOps: {- insertMany: mockBulkInsertTransactions,- updateBalance: mockUpdateBalance,- },- },- {- user: 'user-123',- conversationId: 'convo-123',- collectedUsage,- context: 'abort',- messageId: 'msg-123',- model: 'gpt-4',- },- );- });-- it('should pass context abort for multiple models (parallel agents)', async () => {- const collectedUsage = [- { input_tokens: 100, output_tokens: 50, model: 'gpt-4' },- { input_tokens: 80, output_tokens: 40, model: 'claude-3' },- { input_tokens: 120, output_tokens: 60, model: 'gemini-pro' },- ];-- await spendCollectedUsage({- userId: 'user-123',- conversationId: 'convo-123',- collectedUsage,- fallbackModel: 'gpt-4',- });-- expect(mockRecordCollectedUsage).toHaveBeenCalledTimes(1);- expect(mockRecordCollectedUsage).toHaveBeenCalledWith(- expect.any(Object),- expect.objectContaining({- context: 'abort',- collectedUsage,- }),- );- });-- it('should handle real-world parallel agent abort scenario', async () => {- const collectedUsage = [- { input_tokens: 31596, output_tokens: 151, model: 'gemini-3-flash-preview' },- { input_tokens: 28000, output_tokens: 120, model: 'gpt-5.2' },- ];-- await spendCollectedUsage({- userId: 'user-123',- conversationId: 'convo-123',- collectedUsage,- fallbackModel: 'gemini-3-flash-preview',- });-- expect(mockRecordCollectedUsage).toHaveBeenCalledTimes(1);- expect(mockRecordCollectedUsage).toHaveBeenCalledWith(- expect.any(Object),- expect.objectContaining({- user: 'user-123',- conversationId: 'convo-123',- context: 'abort',- model: 'gemini-3-flash-preview',- }),- );- });-- /**- * Race condition prevention: after abort middleware spends tokens,- * the collectedUsage array is cleared so AgentClient.recordCollectedUsage()- * (which shares the same array reference) sees an empty array and returns early.- */- it('should clear collectedUsage array after spending to prevent double-spending', async () => {- const collectedUsage = [- { input_tokens: 100, output_tokens: 50, model: 'gpt-4' },- { input_tokens: 80, output_tokens: 40, model: 'claude-3' },- ];-- expect(collectedUsage.length).toBe(2);-- await spendCollectedUsage({- userId: 'user-123',- conversationId: 'convo-123',- collectedUsage,- fallbackModel: 'gpt-4',- });-- expect(mockRecordCollectedUsage).toHaveBeenCalledTimes(1);- expect(collectedUsage.length).toBe(0);- });-- it('should await recordCollectedUsage before clearing array', async () => {- let resolved = false;- mockRecordCollectedUsage.mockImplementation(async () => {- await new Promise((resolve) => setTimeout(resolve, 10));- resolved = true;- return { input_tokens: 100, output_tokens: 50 };- });-- const collectedUsage = [- { input_tokens: 100, output_tokens: 50, model: 'gpt-4' },- { input_tokens: 80, output_tokens: 40, model: 'claude-3' },- ];-- await spendCollectedUsage({- userId: 'user-123',- conversationId: 'convo-123',- collectedUsage,- fallbackModel: 'gpt-4',- });-- expect(resolved).toBe(true);- expect(collectedUsage.length).toBe(0);- });- });-});-describe('abortMiddleware - handleAbortError', () => {beforeEach(() => {jest.clearAllMocks();@@ -328,7 +160,7 @@ describe('abortMiddleware - handleAbortError', () => {* caller-supplied data, so an omitted value is indistinguishable from enabled and* the write proceeds even when `transactions.enabled` is false.*/-describe('abortMiddleware - transactions config', () => {+describe('abortMiddleware - handleAbort billing', () => {const buildJobData = () => ({model: 'gpt-4',responseMessageId: 'msg-123',@@ -363,25 +195,7 @@ describe('abortMiddleware - transactions config', () => {db.getConvo.mockResolvedValue({ title: 'Test Chat' });});- it('forwards transactions through spendCollectedUsage to recordCollectedUsage', async () => {- const collectedUsage = [{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' }];-- await spendCollectedUsage({- userId: 'user-123',- conversationId: 'convo-123',- collectedUsage,- fallbackModel: 'gpt-4',- transactions: { enabled: false },- });-- expect(mockRecordCollectedUsage).toHaveBeenCalledTimes(1);- expect(mockRecordCollectedUsage).toHaveBeenCalledWith(- expect.any(Object),- expect.objectContaining({ context: 'abort', transactions: { enabled: false } }),- );- });-- it('resolves the config from req and forwards it on the collected-usage path', async () => {+ it('leaves billing to the run even when the stopped job collected usage', async () => {const collectedUsage = [{ input_tokens: 100, output_tokens: 50, model: 'gpt-4' }];GenerationJobManager.abortJob.mockResolvedValue({success: true,@@ -391,16 +205,14 @@ describe('abortMiddleware - transactions config', () => {collectedUsage,});- const req = buildReq();- await handleAbort()(req, buildRes());+ await handleAbort()(buildReq(), buildRes());expect(logger.error).not.toHaveBeenCalled();- expect(mockGetTransactionsConfig).toHaveBeenCalledWith(req.config);- expect(mockRecordCollectedUsage).toHaveBeenCalledTimes(1);- expect(mockRecordCollectedUsage).toHaveBeenCalledWith(- expect.any(Object),- expect.objectContaining({ context: 'abort', transactions: { enabled: false } }),- );+ expect(mockRecordCollectedUsage).not.toHaveBeenCalled();+ expect(mockSpendTokens).not.toHaveBeenCalled();+ expect(mockSpendStructuredTokens).not.toHaveBeenCalled();+ expect(collectedUsage).toHaveLength(1);+ expect(db.saveMessage).toHaveBeenCalledTimes(1);});it('carries the context meta the run published onto the job into the stopped response', async () => {@@ -444,7 +256,7 @@ describe('abortMiddleware - transactions config', () => {expect(savedMessage.contextMeta).toBeNull();});- it('resolves the config from req and forwards it on the token-count fallback path', async () => {+ it('does not bill a stopped response by token count either', async () => {GenerationJobManager.abortJob.mockResolvedValue({success: true,jobData: buildJobData(),@@ -453,16 +265,11 @@ describe('abortMiddleware - transactions config', () => {collectedUsage: [],});- const req = buildReq();- await handleAbort()(req, buildRes());+ await handleAbort()(buildReq(), buildRes());expect(logger.error).not.toHaveBeenCalled();- expect(mockGetTransactionsConfig).toHaveBeenCalledWith(req.config);expect(mockRecordCollectedUsage).not.toHaveBeenCalled();- expect(mockSpendTokens).toHaveBeenCalledTimes(1);- expect(mockSpendTokens).toHaveBeenCalledWith(- expect.objectContaining({ context: 'incomplete', transactions: { enabled: false } }),- expect.any(Object),- );+ expect(mockSpendTokens).not.toHaveBeenCalled();+ expect(db.saveMessage).toHaveBeenCalledTimes(1);});});diff --git a/packages/api/src/agents/usage.spec.ts b/packages/api/src/agents/usage.spec.tsindex d80c882a1b..f567344953 100644--- a/packages/api/src/agents/usage.spec.ts+++ b/packages/api/src/agents/usage.spec.ts@@ -10,6 +10,10 @@ import {aggregateCollectedUsage,recordCollectedUsage,resolveAgentTokenConfig,+ resolveRunUsageContext,+ hasRecordedProviderUsage,+ hasRecordedPrimaryUsage,+ recordFallbackTokenUsage,buildPersistedContextUsage,buildAbortedResponseMetadata,computeSummaryUsedTokens,@@ -2504,3 +2508,174 @@ describe('createDetachedSubagentUsageRecorder', () => {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);+ });+});diff --git a/packages/api/src/agents/usage.ts b/packages/api/src/agents/usage.tsindex d0614361c8..e3f9467858 100644--- a/packages/api/src/agents/usage.ts+++ b/packages/api/src/agents/usage.ts@@ -24,6 +24,7 @@ import {prepareTokenSpend,} from './transactions';import { collectDetachedSubagentUsage } from './subagentTaskContext';+import { getSafeErrorMetadata } from '~/utils/errors';type SpendTokensFn = (txData: TxMetadata, tokenUsage: TokenUsage) => Promise<unknown>;type SpendStructuredTokensFn = (@@ -604,6 +605,109 @@ export function resolveAgentTokenConfig({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;