Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

💰 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.ts
index 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.ts
index 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;