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

💓 feat: Keep Quiet Chat Streams Alive Behind Idle-Timeout Proxies (#16904)

Marco Beretta4afd5e17f85e
diff --git a/api/server/middleware/config/app.js b/api/server/middleware/config/app.js
index 6b7a969bed..baebe301da 100644
--- a/api/server/middleware/config/app.js
+++ b/api/server/middleware/config/app.js
@@ -1,5 +1,10 @@
const { logger } = require('@librechat/data-schemas');
-const { getAppConfigOptionsFromUser, resolveStrictAppConfig } = require('@librechat/api');
+const {
+ getSafeErrorMetadata,
+ resolveStrictAppConfig,
+ getAppConfigOptionsFromUser,
+ createStreamKeepaliveLoader,
+} = require('@librechat/api');
const { getAppConfig } = require('~/server/services/Config');
const configMiddleware = async (req, res, next) => {
@@ -9,7 +14,7 @@ const configMiddleware = async (req, res, next) => {
next();
} catch (error) {
logger.error('Config middleware error:', {
- error: error.message,
+ error: getSafeErrorMetadata(error),
userRole: req.user?.role,
path: req.path,
});
@@ -18,7 +23,7 @@ const configMiddleware = async (req, res, next) => {
req.config = await getAppConfig({ tenantId: req.user?.tenantId });
next();
} catch (fallbackError) {
- logger.error('Fallback config middleware error:', fallbackError);
+ logger.error('Fallback config middleware error:', getSafeErrorMetadata(fallbackError));
next(fallbackError);
}
}
@@ -31,7 +36,7 @@ const strictConfigMiddleware = async (req, res, next) => {
next();
} catch (error) {
logger.error('Strict config middleware error:', {
- error: error.message,
+ error: getSafeErrorMetadata(error),
userRole: req.user?.role,
path: req.path,
});
@@ -41,3 +46,4 @@ const strictConfigMiddleware = async (req, res, next) => {
module.exports = configMiddleware;
module.exports.strictConfigMiddleware = strictConfigMiddleware;
+module.exports.loadStreamKeepaliveMs = createStreamKeepaliveLoader(getAppConfig);
diff --git a/api/server/middleware/config/app.spec.js b/api/server/middleware/config/app.spec.js
new file mode 100644
index 0000000000..f211445c66
--- /dev/null
+++ b/api/server/middleware/config/app.spec.js
@@ -0,0 +1,48 @@
+const mockGetAppConfig = jest.fn();
+const mockLogger = { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn() };
+
+jest.mock('@librechat/data-schemas', () => ({
+ ...jest.requireActual('@librechat/data-schemas'),
+ logger: mockLogger,
+}));
+
+jest.mock('~/server/services/Config', () => ({
+ getAppConfig: (...args) => mockGetAppConfig(...args),
+}));
+
+const configMiddleware = require('./app');
+
+describe('configMiddleware logging', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
+ it('never logs the raw error when both config reads fail', async () => {
+ const secretError = Object.assign(new Error('mongodb://admin:secret@db failed'), {
+ query: { secret: 'value' },
+ });
+ mockGetAppConfig.mockRejectedValue(secretError);
+ const next = jest.fn();
+
+ await configMiddleware({ user: { id: 'user-1', role: 'USER' }, path: '/x' }, {}, next);
+
+ expect(next).toHaveBeenCalledWith(secretError);
+ expect(mockLogger.error).toHaveBeenCalled();
+ expect(JSON.stringify(mockLogger.error.mock.calls)).not.toContain('secret');
+ });
+
+ it('never logs the raw error from the strict config read', async () => {
+ const secretError = new Error('mongodb://admin:secret@db failed');
+ mockGetAppConfig.mockRejectedValue(secretError);
+ const next = jest.fn();
+
+ await configMiddleware.strictConfigMiddleware(
+ { user: { id: 'user-1', role: 'USER' }, path: '/x' },
+ {},
+ next,
+ );
+
+ expect(next).toHaveBeenCalledWith(expect.any(Error));
+ expect(JSON.stringify(mockLogger.error.mock.calls)).not.toContain('secret');
+ });
+});
diff --git a/api/server/middleware/index.js b/api/server/middleware/index.js
index ca0ca7c367..d0cc553a57 100644
--- a/api/server/middleware/index.js
+++ b/api/server/middleware/index.js
@@ -25,7 +25,7 @@ const checkInviteUser = require('./checkInviteUser');
const requireJwtAuth = require('./requireJwtAuth');
const { requireRumProxyAuth } = require('./requireJwtAuth');
const configMiddleware = require('./config/app');
-const { strictConfigMiddleware } = require('./config/app');
+const { strictConfigMiddleware, loadStreamKeepaliveMs } = require('./config/app');
const validateModel = require('./validateModel');
const moderateText = require('./moderateText');
const logHeaders = require('./logHeaders');
@@ -64,6 +64,7 @@ module.exports = {
canDeleteAccount,
configMiddleware,
strictConfigMiddleware,
+ loadStreamKeepaliveMs,
checkDomainAllowed,
validateMessageReq,
canReadActiveJobConversation,
diff --git a/api/server/routes/agents/__tests__/streamTenant.spec.js b/api/server/routes/agents/__tests__/streamTenant.spec.js
index abb6f1240c..e41c67cb8d 100644
--- a/api/server/routes/agents/__tests__/streamTenant.spec.js
+++ b/api/server/routes/agents/__tests__/streamTenant.spec.js
@@ -17,6 +17,7 @@ const mockGenerationJobManager = {
const mockCaptureAgentCheckpointGeneration = jest.fn();
const mockDeleteAgentCheckpoint = jest.fn();
const mockSaveMessage = jest.fn();
+const mockLoadPlainAppConfig = jest.fn().mockResolvedValue({});
jest.mock('@librechat/data-schemas', () => ({
...jest.requireActual('@librechat/data-schemas'),
@@ -54,6 +55,10 @@ jest.mock('~/server/middleware', () => ({
moderateText: (req, res, next) => next(),
messageIpLimiter: (req, res, next) => next(),
configMiddleware: (req, res, next) => next(),
+ loadStreamKeepaliveMs: (req) =>
+ jest
+ .requireActual('@librechat/api')
+ .createStreamKeepaliveLoader((...args) => mockLoadPlainAppConfig(...args))(req),
messageUserLimiter: (req, res, next) => next(),
}));
@@ -397,6 +402,129 @@ describe('SSE stream tenant isolation', () => {
expect(mockGenerationJobManager.markSyncSent).toHaveBeenCalledWith('stream-123', 1000);
});
+ it('keeps a silent stream alive with SSE comment frames', async () => {
+ jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate'] });
+ try {
+ mockGenerationJobManager.getJob.mockResolvedValue({
+ metadata: { userId: 'user-123' },
+ status: 'running',
+ createdAt: 1000,
+ });
+ let finish;
+ mockGenerationJobManager.subscribe.mockImplementation(
+ async (_streamId, _writeEvent, onDone) => {
+ finish = onDone;
+ return { unsubscribe: jest.fn() };
+ },
+ );
+
+ const pending = request(app)
+ .get('/agents/chat/stream/stream-123')
+ .then((res) => res);
+ await jest.advanceTimersByTimeAsync(0);
+ await new Promise((resolve) => setImmediate(resolve));
+ await jest.advanceTimersByTimeAsync(60_000);
+ finish({ final: true });
+ const res = await pending;
+
+ expect(res.status).toBe(200);
+ expect(res.text.startsWith(':\n\n')).toBe(true);
+ } finally {
+ jest.useRealTimers();
+ }
+ });
+
+ it('does not load the app config for a stream it refuses', async () => {
+ mockGenerationJobManager.getJob.mockResolvedValue(null);
+
+ const res = await request(app).get('/agents/chat/stream/stream-123');
+
+ expect(res.status).toBe(404);
+ expect(mockLoadPlainAppConfig).not.toHaveBeenCalled();
+ });
+
+ it('reads the keepalive interval without runtime config augmentation', async () => {
+ mockSubscribeSuccess();
+ mockGenerationJobManager.getJob.mockResolvedValue({
+ metadata: { userId: 'user-123' },
+ status: 'running',
+ createdAt: 1000,
+ });
+
+ const res = await request(app).get('/agents/chat/stream/stream-123');
+
+ expect(res.status).toBe(200);
+ expect(mockLoadPlainAppConfig).toHaveBeenCalledTimes(1);
+ expect(mockLoadPlainAppConfig).toHaveBeenCalledWith(
+ expect.objectContaining({ userId: 'user-123', skipRuntimeAugmentation: true }),
+ );
+ });
+
+ it('keeps the default keepalive when the config read fails', async () => {
+ jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate'] });
+ mockLoadPlainAppConfig.mockRejectedValueOnce(new Error('config store unavailable'));
+ try {
+ mockGenerationJobManager.getJob.mockResolvedValue({
+ metadata: { userId: 'user-123' },
+ status: 'running',
+ createdAt: 1000,
+ });
+ let finish;
+ mockGenerationJobManager.subscribe.mockImplementation(
+ async (_streamId, _writeEvent, onDone) => {
+ finish = onDone;
+ return { unsubscribe: jest.fn() };
+ },
+ );
+
+ const pending = request(app)
+ .get('/agents/chat/stream/stream-123')
+ .then((res) => res);
+ await jest.advanceTimersByTimeAsync(0);
+ await new Promise((resolve) => setImmediate(resolve));
+ await jest.advanceTimersByTimeAsync(60_000);
+ finish({ final: true });
+ const res = await pending;
+
+ expect(res.text.startsWith(':\n\n')).toBe(true);
+ } finally {
+ jest.useRealTimers();
+ }
+ });
+
+ it('subscribes and keeps the stream alive while the app config never loads', async () => {
+ jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate'] });
+ mockLoadPlainAppConfig.mockReturnValueOnce(new Promise(() => undefined));
+ try {
+ mockGenerationJobManager.getJob.mockResolvedValue({
+ metadata: { userId: 'user-123' },
+ status: 'running',
+ createdAt: 1000,
+ });
+ let finish;
+ mockGenerationJobManager.subscribe.mockImplementation(
+ async (_streamId, _writeEvent, onDone) => {
+ finish = onDone;
+ return { unsubscribe: jest.fn() };
+ },
+ );
+
+ const pending = request(app)
+ .get('/agents/chat/stream/stream-123')
+ .then((res) => res);
+ await jest.advanceTimersByTimeAsync(0);
+ await new Promise((resolve) => setImmediate(resolve));
+ await jest.advanceTimersByTimeAsync(60_000);
+
+ expect(mockGenerationJobManager.subscribe).toHaveBeenCalled();
+ finish({ final: true });
+ const res = await pending;
+ expect(res.text.startsWith(':\n\n')).toBe(true);
+ } finally {
+ jest.useRealTimers();
+ }
+ });
+
it('detaches a paused resume subscription when the response ends before activation', async () => {
mockGenerationJobManager.getJob.mockResolvedValue({
metadata: { userId: 'user-123' },
diff --git a/api/server/routes/agents/index.js b/api/server/routes/agents/index.js
index 04e22c246a..e1ea153581 100644
--- a/api/server/routes/agents/index.js
+++ b/api/server/routes/agents/index.js
@@ -29,6 +29,7 @@ const {
isConfirmedGenerationRetry,
generationRetryProbeLimiter,
generationRetryLimiter,
+ startSseKeepalive,
} = require('@librechat/api');
const { createSseStreamTelemetry } = require('@librechat/api/telemetry');
const { logger } = require('@librechat/data-schemas');
@@ -40,6 +41,7 @@ const {
messageIpLimiter,
configMiddleware,
messageUserLimiter,
+ loadStreamKeepaliveMs,
} = require('~/server/middleware');
const SteerController = require('~/server/controllers/agents/steer');
const {
@@ -286,6 +288,9 @@ router.get('/chat/stream/:streamId', async (req, res) => {
res.setHeader(GENERATION_PROTOCOL_HEADER, String(generationProtocolVersion));
res.flushHeaders();
streamTelemetry.recordHeadersFlushed();
+ /** Started only for an authorized attachment, and never awaited: the keepalive runs at
+ * the default interval until the narrow config read resolves. */
+ startSseKeepalive(res, loadStreamKeepaliveMs(req));
logger.debug(`[AgentStream] Client subscribed to ${streamId}, resume: ${isResume}`);
diff --git a/librechat.example.yaml b/librechat.example.yaml
index f1c89cf082..3932f7ae19 100644
--- a/librechat.example.yaml
+++ b/librechat.example.yaml
@@ -716,6 +716,10 @@ endpoints:
# modelResponseBodyTimeoutMs: 900000
# # Maximum wait for provider response headers. Defaults to 5 minutes; 0 disables.
# modelResponseHeadersTimeoutMs: 300000
+ # # Interval between keepalive comments on a chat stream that is quiet (for example while a
+ # # long tool runs), so proxies with an idle timeout (Cloudflare 100 s, nginx 60 s) keep it
+ # # open. Defaults to 25000 ms; 0 disables.
+ # streamKeepaliveIntervalMs: 25000
# # (optional) Default recursion depth for agents, defaults to 25
# recursionLimit: 50
# # Maximum provider error characters retained without content protection (0 hides detail).
diff --git a/packages/api/src/stream/__tests__/keepalive.spec.ts b/packages/api/src/stream/__tests__/keepalive.spec.ts
new file mode 100644
index 0000000000..8aef878416
--- /dev/null
+++ b/packages/api/src/stream/__tests__/keepalive.spec.ts
@@ -0,0 +1,243 @@
+import v8 from 'v8';
+import vm from 'vm';
+import { EventEmitter } from 'events';
+import { logger } from '@librechat/data-schemas';
+import { DEFAULT_STREAM_KEEPALIVE_INTERVAL_MS } from 'librechat-data-provider';
+import type { SseKeepaliveResponse } from '../keepalive';
+import {
+ SSE_KEEPALIVE_FRAME,
+ startSseKeepalive,
+ loadStreamKeepaliveMs,
+ resolveStreamKeepaliveMs,
+ createStreamKeepaliveLoader,
+} from '../keepalive';
+
+class FakeResponse extends EventEmitter implements SseKeepaliveResponse {
+ writableEnded = false;
+ writes: string[] = [];
+ flush = jest.fn();
+ write(chunk: string): boolean {
+ this.writes.push(chunk);
+ return true;
+ }
+}
+
+describe('startSseKeepalive', () => {
+ beforeEach(() => {
+ jest.useFakeTimers();
+ });
+
+ afterEach(() => {
+ jest.useRealTimers();
+ });
+
+ it('writes an SSE comment frame on every interval while the response is open', () => {
+ const res = new FakeResponse();
+ startSseKeepalive(res, 1_000);
+
+ jest.advanceTimersByTime(2_500);
+
+ expect(res.writes).toEqual([SSE_KEEPALIVE_FRAME, SSE_KEEPALIVE_FRAME]);
+ expect(res.flush).toHaveBeenCalledTimes(2);
+ });
+
+ it('stops when the response closes', () => {
+ const res = new FakeResponse();
+ startSseKeepalive(res, 1_000);
+
+ res.emit('close');
+ jest.advanceTimersByTime(5_000);
+
+ expect(res.writes).toEqual([]);
+ });
+
+ it('stops when the returned handle is called', () => {
+ const res = new FakeResponse();
+ const stop = startSseKeepalive(res, 1_000);
+
+ stop();
+ jest.advanceTimersByTime(5_000);
+
+ expect(res.writes).toEqual([]);
+ });
+
+ it('never writes after the response has ended', () => {
+ const res = new FakeResponse();
+ startSseKeepalive(res, 1_000);
+
+ res.writableEnded = true;
+ jest.advanceTimersByTime(5_000);
+
+ expect(res.writes).toEqual([]);
+ });
+
+ it('does nothing when the interval is 0', () => {
+ const res = new FakeResponse();
+ startSseKeepalive(res, 0);
+
+ jest.advanceTimersByTime(60_000);
+
+ expect(res.writes).toEqual([]);
+ });
+});
+
+describe('resolveStreamKeepaliveMs', () => {
+ it('defaults below the shortest common proxy idle timeout', () => {
+ expect(resolveStreamKeepaliveMs(undefined)).toBe(DEFAULT_STREAM_KEEPALIVE_INTERVAL_MS);
+ expect(DEFAULT_STREAM_KEEPALIVE_INTERVAL_MS).toBeLessThan(60_000);
+ });
+
+ it('honors a configured interval, including 0 to disable', () => {
+ expect(resolveStreamKeepaliveMs({ streamKeepaliveIntervalMs: 10_000 })).toBe(10_000);
+ expect(resolveStreamKeepaliveMs({ streamKeepaliveIntervalMs: 0 })).toBe(0);
+ });
+});
+
+describe('loadStreamKeepaliveMs', () => {
+ it('reuses a config already on the request without loading', async () => {
+ const load = jest.fn();
+ const config = { endpoints: { agents: { streamKeepaliveIntervalMs: 5_000 } } };
+
+ await expect(loadStreamKeepaliveMs(config, load)).resolves.toBe(5_000);
+ expect(load).not.toHaveBeenCalled();
+ });
+
+ it('loads the config when the request has none', async () => {
+ const load = jest
+ .fn()
+ .mockResolvedValue({ endpoints: { agents: { streamKeepaliveIntervalMs: 0 } } });
+
+ await expect(loadStreamKeepaliveMs(undefined, load)).resolves.toBe(0);
+ });
+
+ it('falls back to the default when loading fails', async () => {
+ const load = jest.fn().mockRejectedValue(new Error('config unavailable'));
+
+ await expect(loadStreamKeepaliveMs(undefined, load)).resolves.toBe(
+ DEFAULT_STREAM_KEEPALIVE_INTERVAL_MS,
+ );
+ });
+
+ it('logs only safe metadata when loading fails', async () => {
+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
+ const error = Object.assign(new Error('mongodb://admin:secret@db/config failed'), {
+ query: { secret: 'value' },
+ });
+
+ await loadStreamKeepaliveMs(undefined, () => Promise.reject(error));
+
+ expect(JSON.stringify(warn.mock.calls)).not.toContain('secret');
+ warn.mockRestore();
+ });
+});
+
+describe('createStreamKeepaliveLoader', () => {
+ it('reads the principal config without runtime augmentation', async () => {
+ const getAppConfig = jest
+ .fn()
+ .mockResolvedValue({ endpoints: { agents: { streamKeepaliveIntervalMs: 4_000 } } });
+ const load = createStreamKeepaliveLoader(getAppConfig);
+
+ await expect(load({ user: { id: 'user-1', role: 'USER' } })).resolves.toBe(4_000);
+ expect(getAppConfig).toHaveBeenCalledWith(
+ expect.objectContaining({ userId: 'user-1', role: 'USER', skipRuntimeAugmentation: true }),
+ );
+ });
+
+ it('asks the config service to reject failures so they are logged safely', async () => {
+ const getAppConfig = jest.fn().mockResolvedValue({});
+ const load = createStreamKeepaliveLoader(getAppConfig);
+
+ await load({ user: { id: 'user-1', role: 'USER' } });
+
+ expect(getAppConfig).toHaveBeenCalledWith(expect.objectContaining({ failClosed: true }));
+ });
+
+ it('uses a config already on the request', async () => {
+ const getAppConfig = jest.fn();
+ const load = createStreamKeepaliveLoader(getAppConfig);
+
+ await expect(
+ load({ config: { endpoints: { agents: { streamKeepaliveIntervalMs: 0 } } } }),
+ ).resolves.toBe(0);
+ expect(getAppConfig).not.toHaveBeenCalled();
+ });
+});
+
+describe('startSseKeepalive with a pending interval', () => {
+ beforeEach(() => {
+ jest.useFakeTimers();
+ });
+
+ afterEach(() => {
+ jest.useRealTimers();
+ });
+
+ it('keeps the stream alive at the default interval while the interval is unresolved', () => {
+ const res = new FakeResponse();
+ startSseKeepalive(res, new Promise<number>(() => undefined));
+
+ jest.advanceTimersByTime(DEFAULT_STREAM_KEEPALIVE_INTERVAL_MS);
+
+ expect(res.writes).toEqual([SSE_KEEPALIVE_FRAME]);
+ });
+
+ it('switches to the resolved interval once it is known', async () => {
+ const res = new FakeResponse();
+ startSseKeepalive(res, Promise.resolve(1_000));
+ await Promise.resolve();
+
+ jest.advanceTimersByTime(3_500);
+
+ expect(res.writes).toHaveLength(3);
+ });
+
+ it('counts the time already waited when a longer interval resolves', async () => {
+ const res = new FakeResponse();
+ let resolveInterval: (ms: number) => void = () => undefined;
+ startSseKeepalive(
+ res,
+ new Promise<number>((resolve) => {
+ resolveInterval = resolve;
+ }),
+ );
+
+ jest.advanceTimersByTime(20_000);
+ resolveInterval(50_000);
+ await Promise.resolve();
+ jest.advanceTimersByTime(30_000);
+
+ expect(res.writes).toEqual([SSE_KEEPALIVE_FRAME]);
+ });
+
+ it('releases a closed response while its interval is still pending', async () => {
+ jest.useRealTimers();
+ v8.setFlagsFromString('--expose-gc');
+ const gc = vm.runInNewContext('gc') as () => void;
+ const pending = new Promise<number>(() => undefined);
+ const attach = (): WeakRef<FakeResponse> => {
+ const res = new FakeResponse();
+ startSseKeepalive(res, pending);
+ res.emit('close');
+ return new WeakRef(res);
+ };
+ const ref = attach();
+
+ for (let i = 0; i < 5 && ref.deref() != null; i += 1) {
+ await new Promise((resolve) => setImmediate(resolve));
+ gc();
+ }
+
+ expect(ref.deref()).toBeUndefined();
+ });
+
+ it('stops when the resolved interval disables the keepalive', async () => {
+ const res = new FakeResponse();
+ startSseKeepalive(res, Promise.resolve(0));
+ await Promise.resolve();
+
+ jest.advanceTimersByTime(DEFAULT_STREAM_KEEPALIVE_INTERVAL_MS * 3);
+
+ expect(res.writes).toEqual([]);
+ });
+});
diff --git a/packages/api/src/stream/index.ts b/packages/api/src/stream/index.ts
index fc95d5972f..c26c310b7c 100644
--- a/packages/api/src/stream/index.ts
+++ b/packages/api/src/stream/index.ts
@@ -71,6 +71,18 @@ export { createStreamServices } from './createStreamServices';
export type { StreamServicesConfig, StreamServices } from './createStreamServices';
export { filterPersistableAbortContent, hasPersistableAbortContent } from './abortContent';
export { getGenerationElapsedMs } from './elapsed';
+export {
+ SSE_KEEPALIVE_FRAME,
+ startSseKeepalive,
+ loadStreamKeepaliveMs,
+ resolveStreamKeepaliveMs,
+ createStreamKeepaliveLoader,
+} from './keepalive';
+export type {
+ SseKeepaliveResponse,
+ StreamKeepaliveConfig,
+ StreamKeepaliveRequest,
+} from './keepalive';
export {
projectTerminalEvent,
TRANSIENT_MESSAGE_FIELDS,
diff --git a/packages/api/src/stream/keepalive.ts b/packages/api/src/stream/keepalive.ts
new file mode 100644
index 0000000000..b81abaac46
--- /dev/null
+++ b/packages/api/src/stream/keepalive.ts
@@ -0,0 +1,140 @@
+import { logger } from '@librechat/data-schemas';
+import { DEFAULT_STREAM_KEEPALIVE_INTERVAL_MS } from 'librechat-data-provider';
+import type { TAgentsEndpoint } from 'librechat-data-provider';
+import type { AppConfigUserLike, GetAppConfigOptions } from '~/app/service';
+import { getAppConfigOptionsFromUser } from '~/app/service';
+import { getSafeErrorMetadata } from '~/utils/errors';
+
+/** An SSE comment line: clients skip it, intermediaries see bytes on the wire. */
+export const SSE_KEEPALIVE_FRAME = ':\n\n';
+
+type KeepaliveAgentsConfig = Pick<Partial<TAgentsEndpoint>, 'streamKeepaliveIntervalMs'>;
+
+export interface StreamKeepaliveConfig {
+ endpoints?: { agents?: KeepaliveAgentsConfig };
+}
+
+export interface SseKeepaliveResponse {
+ readonly writableEnded: boolean;
+ readonly destroyed?: boolean;
+ write(chunk: string): boolean;
+ flush?: () => void;
+ once(event: 'close', listener: () => void): unknown;
+}
+
+export function resolveStreamKeepaliveMs(agentsConfig: KeepaliveAgentsConfig | undefined): number {
+ return agentsConfig?.streamKeepaliveIntervalMs ?? DEFAULT_STREAM_KEEPALIVE_INTERVAL_MS;
+}
+
+/**
+ * Resolves the interval from the request's config, or loads it when absent. A failed load
+ * keeps the default instead of failing the stream, and logs only safe error metadata.
+ */
+export async function loadStreamKeepaliveMs(
+ config: StreamKeepaliveConfig | undefined,
+ load: () => Promise<StreamKeepaliveConfig | undefined | null>,
+): Promise<number> {
+ if (config != null) {
+ return resolveStreamKeepaliveMs(config.endpoints?.agents);
+ }
+ try {
+ const loaded = await load();
+ return resolveStreamKeepaliveMs(loaded?.endpoints?.agents);
+ } catch (error) {
+ logger.warn(
+ '[streamKeepalive] Could not load config; using the default interval',
+ getSafeErrorMetadata(error),
+ );
+ return DEFAULT_STREAM_KEEPALIVE_INTERVAL_MS;
+ }
+}
+
+export interface StreamKeepaliveRequest {
+ config?: StreamKeepaliveConfig;
+ user?: AppConfigUserLike | null;
+}
+
+/**
+ * Builds the request-scoped interval reader for the stream route. Only YAML settings are
+ * needed here, so the principal's config is read without runtime augmentation: a stream
+ * attach or reconnect never pays for code-environment merges or their database reads.
+ * `failClosed` makes the service reject instead of logging and swallowing, so every
+ * failure reaches the sanitized fallback in `loadStreamKeepaliveMs`.
+ */
+export function createStreamKeepaliveLoader(
+ getAppConfig: (options: GetAppConfigOptions) => Promise<StreamKeepaliveConfig | undefined | null>,
+): (req: StreamKeepaliveRequest) => Promise<number> {
+ return (req) =>
+ loadStreamKeepaliveMs(req.config, () =>
+ getAppConfig({
+ ...getAppConfigOptionsFromUser(req.user),
+ skipRuntimeAugmentation: true,
+ failClosed: true,
+ }),
+ );
+}
+
+const isClosed = (res: SseKeepaliveResponse): boolean =>
+ res.writableEnded || res.destroyed === true;
+
+/**
+ * Writes a comment frame whenever the response has been quiet for the interval, until it
+ * closes, so a proxy idle timeout (Cloudflare drops a response after 100 s without bytes)
+ * cannot cut a stream that is silent while a long tool call runs.
+ *
+ * The interval may be a promise: the default applies until it resolves, so neither the
+ * caller nor the first frame waits on a config read. A late interval counts the time
+ * already waited, so switching never pushes the next frame past its deadline. `0` stops it.
+ * Stopping drops the response reference, so a pending interval that never settles cannot
+ * keep a closed response alive.
+ */
+export function startSseKeepalive(
+ res: SseKeepaliveResponse,
+ intervalMs: number | Promise<number>,
+): () => void {
+ if (isClosed(res)) {
+ return () => undefined;
+ }
+ let currentMs =
+ typeof intervalMs === 'number' ? intervalMs : DEFAULT_STREAM_KEEPALIVE_INTERVAL_MS;
+ let lastFrameAt = Date.now();
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ let target: SseKeepaliveResponse | null = res;
+
+ const stop = (): void => {
+ target = null;
+ clearTimeout(timer);
+ };
+ const schedule = (): void => {
+ clearTimeout(timer);
+ if (target == null || !(currentMs > 0)) {
+ return;
+ }
+ const delay = Math.max(0, currentMs - (Date.now() - lastFrameAt));
+ timer = setTimeout(beat, delay);
+ timer.unref?.();
+ };
+ const beat = (): void => {
+ if (target == null || isClosed(target)) {
+ stop();
+ return;
+ }
+ target.write(SSE_KEEPALIVE_FRAME);
+ target.flush?.();
+ lastFrameAt = Date.now();
+ schedule();
+ };
+
+ res.once('close', stop);
+ schedule();
+ if (typeof intervalMs !== 'number') {
+ void intervalMs.then(
+ (resolvedMs) => {
+ currentMs = resolvedMs;
+ schedule();
+ },
+ () => undefined,
+ );
+ }
+ return stop;
+}
diff --git a/packages/data-provider/src/config.spec.ts b/packages/data-provider/src/config.spec.ts
index d375cf4875..161e92b83c 100644
--- a/packages/data-provider/src/config.spec.ts
+++ b/packages/data-provider/src/config.spec.ts
@@ -69,6 +69,19 @@ describe('host-side file edit limits', () => {
});
});
+describe('stream keepalive interval', () => {
+ it('defaults to 25 seconds and accepts 0 to disable', () => {
+ expect(agentsEndpointSchema.parse({}).streamKeepaliveIntervalMs).toBe(25_000);
+ expect(
+ agentsEndpointSchema.parse({ streamKeepaliveIntervalMs: 0 }).streamKeepaliveIntervalMs,
+ ).toBe(0);
+ });
+
+ it.each([1, 999])('rejects a sub-second interval of %p ms', (streamKeepaliveIntervalMs) => {
+ expect(agentsEndpointSchema.safeParse({ streamKeepaliveIntervalMs }).success).toBe(false);
+ });
+});
+
describe('authenticated 2FA management rate limits', () => {
it('accepts an account budget and defaults an empty configuration to seven requests', () => {
for (const [input, expected] of [
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index 63d859210b..3fd6d94a64 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -1480,6 +1480,9 @@ export const DEFAULT_AVATAR_REFRESH_COVERAGE_LIMIT = 1000;
export const DEFAULT_MAX_PROVIDER_ERROR_CHARS = 2000;
export const DEFAULT_AGENT_MODEL_RESPONSE_BODY_TIMEOUT_MS = 900_000;
export const DEFAULT_AGENT_MODEL_RESPONSE_HEADERS_TIMEOUT_MS = 300_000;
+/** Below the idle cutoff of common proxies (nginx 60 s, Cloudflare 100 s), so a
+ * stream that is silent while a tool runs is not closed underneath the client. */
+export const DEFAULT_STREAM_KEEPALIVE_INTERVAL_MS = 25_000;
export const DEFAULT_CACHE_CLEAR_TIMEOUT_MS = 1000;
export const HOST_FILE_EDIT_HARD_MAX_COUNT = 100;
@@ -1547,6 +1550,17 @@ export const agentsEndpointSchema = baseEndpointSchema
.min(0)
.max(86_400_000)
.default(DEFAULT_AGENT_MODEL_RESPONSE_HEADERS_TIMEOUT_MS),
+ /** Interval between SSE comment frames on an otherwise silent chat stream, so
+ * proxies with an idle timeout keep it open; 0 disables the keepalive. */
+ streamKeepaliveIntervalMs: z
+ .number()
+ .int()
+ .min(0)
+ .max(3_600_000)
+ .refine((ms) => ms === 0 || ms >= 1_000, {
+ message: 'Use 0 to disable, or at least 1000 ms',
+ })
+ .default(DEFAULT_STREAM_KEEPALIVE_INTERVAL_MS),
recursionLimit: z.number().optional(),
disableBuilder: z.boolean().optional().default(false),
/** Optional workspace guidance acquisition budget, separate from command execution. */