🔄 refactor: Sequential Event Ordering in Redis Streaming Mode (#11650)

* chore: linting image context file

* refactor: Event Emission with Async Handling for Redis Ordering

- Updated emitEvent and related functions to be async, ensuring proper event ordering in Redis mode.
- Refactored multiple handlers to await emitEvent calls, improving reliability for streaming deltas.
- Enhanced GenerationJobManager to await chunk emissions, critical for maintaining sequential event delivery.
- Added tests to verify that events are delivered in strict order when using Redis, addressing previous issues with out-of-order messages.

* refactor: Clear Pending Buffers and Timeouts in RedisEventTransport

- Enhanced the cleanup process in RedisEventTransport by ensuring that pending messages and flush timeouts are cleared when the last subscriber unsubscribes.
- Updated the destroy method to also clear pending messages and flush timeouts for all streams, improving resource management and preventing memory leaks.

* refactor: Update Event Emission to Async for Improved Ordering

- Refactored GenerationJobManager and RedisEventTransport to make emitDone and emitError methods async, ensuring proper event ordering in Redis mode.
- Updated all relevant calls to await these methods, enhancing reliability in event delivery.
- Adjusted tests to verify that events are processed in the correct sequence, addressing previous issues with out-of-order messages.

* refactor: Adjust RedisEventTransport for 0-Indexed Sequence Handling

- Updated sequence handling in RedisEventTransport to be 0-indexed, ensuring consistency across event emissions and buffer management.
- Modified integration tests to reflect the new sequence logic, improving the accuracy of event processing and delivery order.
- Enhanced comments for clarity on sequence management and terminal event handling.

* chore: Add Redis dump file to .gitignore

- Included dump.rdb in .gitignore to prevent accidental commits of Redis database dumps, enhancing repository cleanliness and security.

* test: Increase wait times in RedisEventTransport integration tests for CI stability

- Adjusted wait times for subscription establishment and event propagation from 100ms and 200ms to 500ms to improve reliability in CI environments.
- Enhanced code readability by formatting promise resolution lines for better clarity.

api/server/controllers/agents/callbacks.js

@@ -152,13 +152,15 @@ function checkIfLastAgent(last_agent_id, langgraph_node) {
 
 /**
  * Helper to emit events either to res (standard mode) or to job emitter (resumable mode).
+ * In Redis mode, awaits the emit to guarantee event ordering (critical for streaming deltas).
  * @param {ServerResponse} res - The server response object
  * @param {string | null} streamId - The stream ID for resumable mode, or null for standard mode
  * @param {Object} eventData - The event data to send
+ * @returns {Promise<void>}
  */
-function emitEvent(res, streamId, eventData) {
+async function emitEvent(res, streamId, eventData) {
   if (streamId) {
-    GenerationJobManager.emitChunk(streamId, eventData);
+    await GenerationJobManager.emitChunk(streamId, eventData);
   } else {
     sendEvent(res, eventData);
   }
@@ -206,18 +208,18 @@ function getDefaultHandlers({
        * @param {StreamEventData} data - The event data.
        * @param {GraphRunnableConfig['configurable']} [metadata] The runnable metadata.
        */
-      handle: (event, data, metadata) => {
+      handle: async (event, data, metadata) => {
         if (data?.stepDetails.type === StepTypes.TOOL_CALLS) {
-          emitEvent(res, streamId, { event, data });
+          await emitEvent(res, streamId, { event, data });
         } else if (checkIfLastAgent(metadata?.last_agent_id, metadata?.langgraph_node)) {
-          emitEvent(res, streamId, { event, data });
+          await emitEvent(res, streamId, { event, data });
         } else if (!metadata?.hide_sequential_outputs) {
-          emitEvent(res, streamId, { event, data });
+          await emitEvent(res, streamId, { event, data });
         } else {
           const agentName = metadata?.name ?? 'Agent';
           const isToolCall = data?.stepDetails.type === StepTypes.TOOL_CALLS;
           const action = isToolCall ? 'performing a task...' : 'thinking...';
-          emitEvent(res, streamId, {
+          await emitEvent(res, streamId, {
             event: 'on_agent_update',
             data: {
               runId: metadata?.run_id,
@@ -235,13 +237,13 @@ function getDefaultHandlers({
        * @param {StreamEventData} data - The event data.
        * @param {GraphRunnableConfig['configurable']} [metadata] The runnable metadata.
        */
-      handle: (event, data, metadata) => {
+      handle: async (event, data, metadata) => {
         if (data?.delta.type === StepTypes.TOOL_CALLS) {
-          emitEvent(res, streamId, { event, data });
+          await emitEvent(res, streamId, { event, data });
         } else if (checkIfLastAgent(metadata?.last_agent_id, metadata?.langgraph_node)) {
-          emitEvent(res, streamId, { event, data });
+          await emitEvent(res, streamId, { event, data });
         } else if (!metadata?.hide_sequential_outputs) {
-          emitEvent(res, streamId, { event, data });
+          await emitEvent(res, streamId, { event, data });
         }
         aggregateContent({ event, data });
       },
@@ -253,13 +255,13 @@ function getDefaultHandlers({
        * @param {StreamEventData & { result: ToolEndData }} data - The event data.
        * @param {GraphRunnableConfig['configurable']} [metadata] The runnable metadata.
        */
-      handle: (event, data, metadata) => {
+      handle: async (event, data, metadata) => {
         if (data?.result != null) {
-          emitEvent(res, streamId, { event, data });
+          await emitEvent(res, streamId, { event, data });
         } else if (checkIfLastAgent(metadata?.last_agent_id, metadata?.langgraph_node)) {
-          emitEvent(res, streamId, { event, data });
+          await emitEvent(res, streamId, { event, data });
         } else if (!metadata?.hide_sequential_outputs) {
-          emitEvent(res, streamId, { event, data });
+          await emitEvent(res, streamId, { event, data });
         }
         aggregateContent({ event, data });
       },
@@ -271,11 +273,11 @@ function getDefaultHandlers({
        * @param {StreamEventData} data - The event data.
        * @param {GraphRunnableConfig['configurable']} [metadata] The runnable metadata.
        */
-      handle: (event, data, metadata) => {
+      handle: async (event, data, metadata) => {
         if (checkIfLastAgent(metadata?.last_agent_id, metadata?.langgraph_node)) {
-          emitEvent(res, streamId, { event, data });
+          await emitEvent(res, streamId, { event, data });
         } else if (!metadata?.hide_sequential_outputs) {
-          emitEvent(res, streamId, { event, data });
+          await emitEvent(res, streamId, { event, data });
         }
         aggregateContent({ event, data });
       },
@@ -287,11 +289,11 @@ function getDefaultHandlers({
        * @param {StreamEventData} data - The event data.
        * @param {GraphRunnableConfig['configurable']} [metadata] The runnable metadata.
        */
-      handle: (event, data, metadata) => {
+      handle: async (event, data, metadata) => {
         if (checkIfLastAgent(metadata?.last_agent_id, metadata?.langgraph_node)) {
-          emitEvent(res, streamId, { event, data });
+          await emitEvent(res, streamId, { event, data });
         } else if (!metadata?.hide_sequential_outputs) {
-          emitEvent(res, streamId, { event, data });
+          await emitEvent(res, streamId, { event, data });
         }
         aggregateContent({ event, data });
       },
@@ -307,6 +309,7 @@ function getDefaultHandlers({
 
 /**
  * Helper to write attachment events either to res or to job emitter.
+ * Note: Attachments are not order-sensitive like deltas, so fire-and-forget is acceptable.
  * @param {ServerResponse} res - The server response object
  * @param {string | null} streamId - The stream ID for resumable mode, or null for standard mode
  * @param {Object} attachment - The attachment data

api/server/controllers/agents/request.js

@@ -324,7 +324,7 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTit
             conversationId: conversation?.conversationId,
           });
 
-          GenerationJobManager.emitDone(streamId, finalEvent);
+          await GenerationJobManager.emitDone(streamId, finalEvent);
           GenerationJobManager.completeJob(streamId);
           await decrementPendingRequest(userId);
         } else {
@@ -344,7 +344,7 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTit
             conversationId: conversation?.conversationId,
           });
 
-          GenerationJobManager.emitDone(streamId, finalEvent);
+          await GenerationJobManager.emitDone(streamId, finalEvent);
           GenerationJobManager.completeJob(streamId, 'Request aborted');
           await decrementPendingRequest(userId);
         }
@@ -377,7 +377,7 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTit
           // abortJob already handled emitDone and completeJob
         } else {
           logger.error(`[ResumableAgentController] Generation error for ${streamId}:`, error);
-          GenerationJobManager.emitError(streamId, error.message || 'Generation failed');
+          await GenerationJobManager.emitError(streamId, error.message || 'Generation failed');
           GenerationJobManager.completeJob(streamId, error.message);
         }
 
@@ -406,7 +406,7 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTit
       res.status(500).json({ error: error.message || 'Failed to start generation' });
     } else {
       // JSON already sent, emit error to stream so client can receive it
-      GenerationJobManager.emitError(streamId, error.message || 'Failed to start generation');
+      await GenerationJobManager.emitError(streamId, error.message || 'Failed to start generation');
     }
     GenerationJobManager.completeJob(streamId, error.message);
     await decrementPendingRequest(userId);

api/server/services/ActionService.js

@@ -201,7 +201,7 @@ async function createActionTool({
                   async () => {
                     const eventData = { event: GraphEvents.ON_RUN_STEP_DELTA, data };
                     if (streamId) {
-                      GenerationJobManager.emitChunk(streamId, eventData);
+                      await GenerationJobManager.emitChunk(streamId, eventData);
                     } else {
                       sendEvent(res, eventData);
                     }
@@ -231,7 +231,7 @@ async function createActionTool({
                 data.delta.expires_at = undefined;
                 const successEventData = { event: GraphEvents.ON_RUN_STEP_DELTA, data };
                 if (streamId) {
-                  GenerationJobManager.emitChunk(streamId, successEventData);
+                  await GenerationJobManager.emitChunk(streamId, successEventData);
                 } else {
                   sendEvent(res, successEventData);
                 }

api/server/services/MCP.js

@@ -53,9 +53,9 @@ function isEmptyObjectSchema(jsonSchema) {
 function createRunStepDeltaEmitter({ res, stepId, toolCall, streamId = null }) {
   /**
    * @param {string} authURL - The URL to redirect the user for OAuth authentication.
-   * @returns {void}
+   * @returns {Promise<void>}
    */
-  return function (authURL) {
+  return async function (authURL) {
     /** @type {{ id: string; delta: AgentToolCallDelta }} */
     const data = {
       id: stepId,
@@ -68,7 +68,7 @@ function createRunStepDeltaEmitter({ res, stepId, toolCall, streamId = null }) {
     };
     const eventData = { event: GraphEvents.ON_RUN_STEP_DELTA, data };
     if (streamId) {
-      GenerationJobManager.emitChunk(streamId, eventData);
+      await GenerationJobManager.emitChunk(streamId, eventData);
     } else {
       sendEvent(res, eventData);
     }
@@ -83,9 +83,10 @@ function createRunStepDeltaEmitter({ res, stepId, toolCall, streamId = null }) {
  * @param {ToolCallChunk} params.toolCall - The tool call object containing tool information.
  * @param {number} [params.index]
  * @param {string | null} [params.streamId] - The stream ID for resumable mode.
+ * @returns {() => Promise<void>}
  */
 function createRunStepEmitter({ res, runId, stepId, toolCall, index, streamId = null }) {
-  return function () {
+  return async function () {
     /** @type {import('@librechat/agents').RunStep} */
     const data = {
       runId: runId ?? Constants.USE_PRELIM_RESPONSE_MESSAGE_ID,
@@ -99,7 +100,7 @@ function createRunStepEmitter({ res, runId, stepId, toolCall, index, streamId =
     };
     const eventData = { event: GraphEvents.ON_RUN_STEP, data };
     if (streamId) {
-      GenerationJobManager.emitChunk(streamId, eventData);
+      await GenerationJobManager.emitChunk(streamId, eventData);
     } else {
       sendEvent(res, eventData);
     }
@@ -147,7 +148,7 @@ function createOAuthEnd({ res, stepId, toolCall, streamId = null }) {
     };
     const eventData = { event: GraphEvents.ON_RUN_STEP_DELTA, data };
     if (streamId) {
-      GenerationJobManager.emitChunk(streamId, eventData);
+      await GenerationJobManager.emitChunk(streamId, eventData);
     } else {
       sendEvent(res, eventData);
     }

api/server/services/ToolService.js

@@ -526,8 +526,8 @@ async function loadToolDefinitionsWrapper({ req, res, agent, streamId = null, to
       const runStepDeltaEvent = { event: GraphEvents.ON_RUN_STEP_DELTA, data: runStepDeltaData };
 
       if (streamId) {
-        GenerationJobManager.emitChunk(streamId, runStepEvent);
-        GenerationJobManager.emitChunk(streamId, runStepDeltaEvent);
+        await GenerationJobManager.emitChunk(streamId, runStepEvent);
+        await GenerationJobManager.emitChunk(streamId, runStepDeltaEvent);
       } else if (res && !res.writableEnded) {
         sendEvent(res, runStepEvent);
         sendEvent(res, runStepDeltaEvent);