📉 feat: Add Token Usage Tracking for Agents API Routes (#11600)

* feat: Implement token usage tracking for OpenAI and Responses controllers

- Added functionality to record token usage against user balances in OpenAIChatCompletionController and createResponse functions.
- Introduced new utility functions for managing token spending and structured token usage.
- Enhanced error handling for token recording to improve logging and debugging capabilities.
- Updated imports to include new usage tracking methods and configurations.

* test: Add unit tests for recordCollectedUsage function in usage.spec.ts

- Introduced comprehensive tests for the recordCollectedUsage function, covering various scenarios including handling empty and null collectedUsage, single and multiple usage entries, and sequential and parallel execution cases.
- Enhanced token handling tests to ensure correct calculations for both OpenAI and Anthropic formats, including cache token management.
- Improved overall test coverage for usage tracking functionality, ensuring robust validation of expected behaviors and outcomes.

* test: Add unit tests for OpenAI and Responses API controllers

- Introduced comprehensive unit tests for the OpenAIChatCompletionController and createResponse functions, focusing on the correct invocation of recordCollectedUsage for token spending.
- Enhanced tests to validate the passing of balance and transactions configuration to the recordCollectedUsage function.
- Ensured proper dependency injection of spendTokens and spendStructuredTokens in the usage recording process.
- Improved overall test coverage for token usage tracking, ensuring robust validation of expected behaviors and outcomes.

api/server/controllers/agents/openai.js

@@ -16,16 +16,20 @@ const {
   createSafeUser,
   validateRequest,
   initializeAgent,
+  getBalanceConfig,
   createErrorResponse,
+  recordCollectedUsage,
+  getTransactionsConfig,
+  createToolExecuteHandler,
   buildNonStreamingResponse,
   createOpenAIStreamTracker,
   createOpenAIContentAggregator,
-  createToolExecuteHandler,
   isChatCompletionValidationFailure,
 } = require('@librechat/api');
 const { loadAgentTools, loadToolsForExecution } = require('~/server/services/ToolService');
 const { createToolEndCallback } = require('~/server/controllers/agents/callbacks');
 const { findAccessibleResources } = require('~/server/services/PermissionService');
+const { spendTokens, spendStructuredTokens } = require('~/models/spendTokens');
 const { getConvoFiles } = require('~/models/Conversation');
 const { getAgent, getAgents } = require('~/models/Agent');
 const db = require('~/models');
@@ -497,6 +501,24 @@ const OpenAIChatCompletionController = async (req, res) => {
       },
     });
 
+    // Record token usage against balance
+    const balanceConfig = getBalanceConfig(appConfig);
+    const transactionsConfig = getTransactionsConfig(appConfig);
+    recordCollectedUsage(
+      { spendTokens, spendStructuredTokens },
+      {
+        user: userId,
+        conversationId,
+        collectedUsage,
+        context: 'message',
+        balance: balanceConfig,
+        transactions: transactionsConfig,
+        model: primaryConfig.model || agent.model_parameters?.model,
+      },
+    ).catch((err) => {
+      logger.error('[OpenAI API] Error recording usage:', err);
+    });
+
     // Finalize response
     const duration = Date.now() - requestStartTime;
     if (isStreaming) {