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

🛝 refactor: Route Packaged Chat Completion Frames Through a Writer (#16267)

lia-by-librechat[bot]89effb97936c
diff --git a/api/server/controllers/agents/openai.js b/api/server/controllers/agents/openai.js
index 2a40bd0567..76d60a7c45 100644
--- a/api/server/controllers/agents/openai.js
+++ b/api/server/controllers/agents/openai.js
@@ -821,7 +821,7 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
// Create handler config for OpenAI streaming (only used when streaming)
const handlerConfig = isStreaming
? {
- res,
+ writer: res,
context,
tracker,
}
diff --git a/packages/api/src/agents/openai/handlers.spec.ts b/packages/api/src/agents/openai/handlers.spec.ts
index 1117ede4a6..00bc3d321b 100644
--- a/packages/api/src/agents/openai/handlers.spec.ts
+++ b/packages/api/src/agents/openai/handlers.spec.ts
@@ -1,4 +1,5 @@
import type { Response as ServerResponse } from 'express';
+import type { OpenAIStreamHandlerConfig, OpenAIStreamWriterConfig } from './handlers';
import type { UsageMetadata } from '~/stream/interfaces/IJobStore';
import type { OpenAIResponseContext } from './types';
import {
@@ -6,6 +7,9 @@ import {
buildCompletionUsage,
OpenAIModelEndHandler,
createOpenAIStreamTracker,
+ createOpenAIHandlers,
+ createChunk,
+ writeSSE,
} from './handlers';
describe('OpenAI-compatible agent stream handlers', () => {
@@ -15,6 +19,78 @@ describe('OpenAI-compatible agent stream handlers', () => {
model: 'anthropic/claude-sonnet-4.6',
};
+ it('projects the same ordered frames through a plain writer and the legacy res option', () => {
+ const replay = (legacy: boolean): string[] => {
+ const frames: string[] = [];
+ const writer = {
+ write: (frame: string): void => {
+ frames.push(frame);
+ },
+ };
+ const tracker = createOpenAIStreamTracker();
+ const config: OpenAIStreamHandlerConfig | OpenAIStreamWriterConfig = legacy
+ ? { res: writer, context, tracker }
+ : { writer, context, tracker };
+ const handlers = createOpenAIHandlers(config);
+ writeSSE(writer, createChunk(context, { role: 'assistant' }));
+ handlers.on_message_delta.handle('on_message_delta', {
+ delta: { content: [{ type: 'text', text: 'hello' }] },
+ });
+ handlers.on_reasoning_delta.handle('on_reasoning_delta', {
+ delta: { content: [{ type: 'think', think: 'reasoning' }] },
+ });
+ handlers.on_run_step.handle('on_run_step', {
+ id: 'step-1',
+ stepDetails: {
+ type: 'tool_calls',
+ tool_calls: [{ id: 'call-1', name: 'lookup', args: '{"city":"Madrid"}' }],
+ },
+ });
+ expect(frames).toHaveLength(3);
+ sendFinalChunk(config, 'stop', {
+ prompt_tokens: 12,
+ completion_tokens: 3,
+ total_tokens: 15,
+ primary: { prompt_tokens: 10, completion_tokens: 2, total_tokens: 12 },
+ subagent: { prompt_tokens: 2, completion_tokens: 1, total_tokens: 3 },
+ });
+ return frames;
+ };
+
+ const current = replay(false);
+ expect(current).toEqual(replay(true));
+ const chunks = current.slice(0, -1).map((frame) => JSON.parse(frame.slice(6)));
+ expect(chunks.map((chunk) => chunk.choices[0].delta)).toEqual([
+ { role: 'assistant' },
+ { content: 'hello' },
+ { reasoning: 'reasoning' },
+ { tool_calls: [expect.objectContaining({ id: 'call-1', index: 0 })] },
+ {
+ tool_calls: [
+ expect.objectContaining({ index: 0, function: { arguments: '{"city":"Madrid"}' } }),
+ ],
+ },
+ {},
+ ]);
+ expect(chunks[chunks.length - 1].choices[0].finish_reason).toBe('stop');
+ expect(chunks[chunks.length - 1].usage).toMatchObject({
+ total_tokens: 15,
+ subagent: { total_tokens: 3 },
+ });
+ expect(current[current.length - 1]).toBe('data: [DONE]\n\n');
+ });
+
+ it('propagates a synchronous transport failure instead of claiming completion', () => {
+ const writer = {
+ write: (): never => {
+ throw new Error('connection closed');
+ },
+ };
+ expect(() => writeSSE(writer, createChunk(context, { content: 'hello' }))).toThrow(
+ 'connection closed',
+ );
+ });
+
it('preserves reasoning token usage from model end metadata', () => {
const tracker = createOpenAIStreamTracker();
const write = jest.fn();
diff --git a/packages/api/src/agents/openai/handlers.ts b/packages/api/src/agents/openai/handlers.ts
index 3c5de3fb07..8d63de6119 100644
--- a/packages/api/src/agents/openai/handlers.ts
+++ b/packages/api/src/agents/openai/handlers.ts
@@ -4,7 +4,6 @@
* These handlers convert LibreChat's internal graph events into OpenAI-compatible
* streaming format (SSE with chat.completion.chunk objects).
*/
-import type { Response as ServerResponse } from 'express';
import type { Agents } from 'librechat-data-provider';
import type { Graph } from '@librechat/agents';
import type {
@@ -44,15 +43,14 @@ export function createChunk(
};
}
-/**
- * Write an SSE event to the response
- */
-export function writeSSE(res: ServerResponse, data: ChatCompletionChunk | string): void {
- if (typeof data === 'string') {
- res.write(`data: ${data}\n\n`);
- } else {
- res.write(`data: ${JSON.stringify(data)}\n\n`);
- }
+/** One synchronous output frame; HTTP connection and lifecycle stay with the caller. */
+export interface OpenAIWriter {
+ write(frame: string): boolean | void;
+}
+
+/** Write one Chat Completions frame through a caller-owned transport. */
+export function writeSSE(writer: OpenAIWriter, data: ChatCompletionChunk | string): void {
+ writer.write(`data: ${typeof data === 'string' ? data : JSON.stringify(data)}\n\n`);
}
/**
@@ -158,16 +156,26 @@ export function createOpenAIContentAggregator(): OpenAIContentAggregator {
};
}
-/**
- * Handler configuration for OpenAI streaming
- */
+/** Legacy stream configuration; retained for existing package consumers. */
export interface OpenAIStreamHandlerConfig {
signal?: AbortSignal;
- res: ServerResponse;
+ res: OpenAIWriter;
context: OpenAIResponseContext;
tracker: OpenAIStreamTracker;
}
+/** Transport-neutral stream configuration for new callers. */
+export type OpenAIStreamWriterConfig = Omit<OpenAIStreamHandlerConfig, 'res'> & {
+ writer: OpenAIWriter;
+ res?: never;
+};
+
+type OpenAIContentStreamConfig = OpenAIStreamHandlerConfig | OpenAIStreamWriterConfig;
+
+function getStreamWriter(config: OpenAIContentStreamConfig): OpenAIWriter {
+ return 'writer' in config ? config.writer : config.res;
+}
+
/**
* Graph event types from @librechat/agents
*/
@@ -639,7 +647,7 @@ export class OpenAIMessageDeltaHandler implements EventHandler {
}
this.config.tracker.addText();
const chunk = createChunk(this.config.context, { content: part.text });
- writeSSE(this.config.res, chunk);
+ writeSSE(getStreamWriter(this.config), chunk);
}
}
}
@@ -742,7 +750,7 @@ export class OpenAIReasoningDeltaHandler implements EventHandler {
// Stream as delta.reasoning (OpenRouter convention)
const chunk = createChunk(this.config.context, { reasoning: text });
- writeSSE(this.config.res, chunk);
+ writeSSE(getStreamWriter(this.config), chunk);
}
}
}
@@ -756,7 +764,7 @@ export interface OpenAIAggregationHandlerConfig {
signal?: AbortSignal;
}
-type OpenAIContentHandlerConfig = OpenAIStreamHandlerConfig | OpenAIAggregationHandlerConfig;
+type OpenAIContentHandlerConfig = OpenAIContentStreamConfig | OpenAIAggregationHandlerConfig;
export function createOpenAIHandlers(
config: OpenAIContentHandlerConfig,
@@ -769,7 +777,7 @@ export function createOpenAIHandlers(
emit:
'aggregator' in config
? undefined
- : (delta) => writeSSE(config.res, createChunk(config.context, delta)),
+ : (delta) => writeSSE(getStreamWriter(config), createChunk(config.context, delta)),
});
const target = 'aggregator' in config ? config.aggregator : config.tracker;
target.finishToolCalls = toolCallStream.finish;
@@ -796,11 +804,12 @@ export function createOpenAIHandlers(
* Send the final chunk with finish_reason and optional usage
*/
export function sendFinalChunk(
- config: OpenAIStreamHandlerConfig,
+ config: OpenAIContentStreamConfig,
finishReason: ChatCompletionChunkChoice['finish_reason'] = 'stop',
usageOverride?: CompletionUsage,
): void {
- const { res, context, tracker } = config;
+ const { context, tracker } = config;
+ const writer = getStreamWriter(config);
tracker.finishToolCalls?.();
// Determine finish reason based on content
@@ -824,10 +833,10 @@ export function sendFinalChunk(
}
const finalChunk = createChunk(context, {}, reason, usage);
- writeSSE(res, finalChunk);
+ writeSSE(writer, finalChunk);
// Send [DONE] marker
- writeSSE(res, '[DONE]');
+ writeSSE(writer, '[DONE]');
}
/** Build provider-normalized chat-completion usage from every billed call. */
diff --git a/packages/api/src/agents/openai/service.ts b/packages/api/src/agents/openai/service.ts
index 1cfb002865..6d4204eb50 100644
--- a/packages/api/src/agents/openai/service.ts
+++ b/packages/api/src/agents/openai/service.ts
@@ -46,7 +46,7 @@ import type {
FileContentInput,
} from '~/protection';
import type { InitializeAgentParams as CoreInitializeAgentParams } from '../initialize';
-import type { OpenAIStreamHandlerConfig, EventHandler } from './handlers';
+import type { OpenAIStreamWriterConfig, EventHandler } from './handlers';
import type { LangfuseTraceContext } from '~/langfuse/identity';
import type { MCPRuntimeRequestBody } from '~/mcp/request';
import type { ToolExecuteOptions } from '../handlers';
@@ -824,10 +824,10 @@ export async function createAgentChatCompletion(
}
// Create handler config (only used for streaming)
- const handlerConfig: OpenAIStreamHandlerConfig | null =
+ const handlerConfig: OpenAIStreamWriterConfig | null =
isStreaming && tracker
? {
- res,
+ writer: res,
context,
tracker,
}