🧩 feat: Compose the Background Responses Host (#17606)

* 🧩 feat: Compose the Background Responses Host

* fix: reconcile background response host boundaries

* test: Exercise Canonical Response Input History Through HTTP

* fix: Keep Background Retrieval Journal-Owned

* test: load compiled response host before timed assertions
This commit is contained in:
Dustin Healy 2026-11-10 21:04:01 -08:00 • committed by GitHub
parent a1ac175544
commit 59f54d982f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 2068 additions and 23 deletions

View file

@ -153,7 +153,22 @@ export function createBackgroundResponseService(deps: BackgroundResponseDependen
: { ok: false, status: 404, code: 'response_not_found' };
}
/** Null is absence of a readable journal, never an authorization denial or storage failure. */
async function lookup(
owner: ResponseOwner,
responseId: string,
): Promise<BackgroundResponseResult | null> {
const record = await deps.storage.read(owner, responseId);
if (!record) return null;
if (!(await deps.authorize(owner, record.agentId, record.sourceKeyId)))
return { ok: false, status: 404, code: 'response_not_found' };
return responseResult(record);
}
return {
lookup(owner: ResponseOwner, responseId: string): Promise<BackgroundResponseResult | null> {
return lookup(owner, responseId);
},
async create(
envelope: ResponsesRunEnvelope,
idempotencyKey?: string,
@ -199,9 +214,13 @@ export function createBackgroundResponseService(deps: BackgroundResponseDependen
: { ok: true, response: view(record) };
},
async retrieve(owner: ResponseOwner, responseId: string): Promise<BackgroundResponseResult> {
const record = await readAuthorized(owner, responseId);
if (!record) return { ok: false, status: 404, code: 'response_not_found' };
return responseResult(record);
return (
(await lookup(owner, responseId)) ?? {
ok: false,
status: 404,
code: 'response_not_found',
}
);
},
async cancel(owner: ResponseOwner, responseId: string): Promise<BackgroundResponseResult> {
const authorized = await readAuthorized(owner, responseId);

View file

@ -134,6 +134,26 @@ function appFor(
return app;
}
it.each([conversationId, responseId])(
'does not project background history through an ordinary %s read',
(id) =>
scoped(async () => {
await save({ ...result(), background: true });
await request(appFor())
.get('/' + id)
.expect(404);
// A damaged full receipt cannot make its server-written background marker disappear.
await mongoose.models.Message.updateOne(
{ user: owner.userId, messageId: responseId },
{ $set: { 'metadata.responseReceipt': { background: true } } },
);
const rejected = await request(appFor())
.get('/' + id)
.expect(404);
expect(JSON.stringify(rejected.body)).not.toContain('tool-result-only-in-canonical-content');
}),
);
it.each([conversationId, responseId])('preserves legacy tokenCount usage for %s', (id) =>
scoped(async () => {
await db.saveConvo({ userId: owner.userId }, { conversationId, endpoint: 'agents' });

File diff suppressed because it is too large Load diff

View file

@ -0,0 +1,330 @@
import {
AGENT_TRIGGER_WORKER_CAPABILITY_RESPONSES_RESUME_V1,
createChatExpirationDate,
createFallbackRetentionDate,
} from '@librechat/data-schemas';
import type {
IUser,
ResponseOwner,
ResponseStorage,
StoredResponseRecord,
ConversationMethods,
} from '@librechat/data-schemas';
import type { ResponseReviewView } from 'librechat-data-provider';
import type { Request, RequestHandler } from 'express';
import type { ResponseDecisionDependencies, ResponseDecisionSubmission } from './decision';
import type { GenerationJobManagerClass } from '~/stream/GenerationJobManager';
import type { BackgroundResponseAuthorityDependencies } from './authority';
import type { BackgroundResponseTransportDependencies } from './transport';
import type { BackgroundResponseWorkerDependencies } from './worker';
import type { AgentTriggerService } from '../triggers/service';
import type { BackgroundResponseResult } from './background';
import type { BackgroundResponseQueue } from './queue';
import type { ServerRequest } from '~/types/http';
import type { BoundAddress } from '~/app/origin';
import {
createResponseCompletion,
createResponseExecutionRelease,
createResponseExecutionConfirmation,
} from './completion';
import { createBackgroundResponseWorkerAuth, getBackgroundResponseWorkerRecord } from './worker';
import { createBackgroundResponseTransport, createResponseResumeTransport } from './transport';
import { resolveImportRetentionFields, isTemporaryRecord } from '~/conversations/retention';
import { createBackgroundResponseQueue, createResponseResumeQueue } from './queue';
import { createBackgroundResponseAuthority } from './authority';
import { createBackgroundResponseService } from './background';
import { createBackgroundResponseHttpHandlers } from './http';
import { createResponseDecisionSubmission } from './decision';
import { resolveResponseContinuation } from './persistence';
import { cleanupResponseCheckpoint } from './checkpoint';
import { createResponseRetirement } from './retirement';
import { createResponseReview } from './review';
import { responseTenantId } from './scope';
export interface BackgroundResponsesHostDependencies
extends BackgroundResponseAuthorityDependencies {
storage: ResponseStorage;
enqueue: AgentTriggerService['enqueue'];
jobs: Pick<
GenerationJobManagerClass,
'getJob' | 'abortJob' | 'getResumeState' | 'finishProviderTerminalPersistence'
>;
publicBaseURL?: string;
getMessage: Parameters<typeof resolveResponseContinuation>[2]['getMessage'];
getConvoRetention: ConversationMethods['getConvoRetention'];
signingSecret: () => string;
onError: (error: unknown) => void;
fetch?: BackgroundResponseTransportDependencies['fetch'];
decisions?: Pick<ResponseDecisionDependencies, 'validate' | 'enqueue'>;
/** Install together: owner validation, durable dispatch, and same-checkpoint worker admission. */
interactive?: {
validate: ResponseDecisionDependencies['validate'];
admitResume: NonNullable<BackgroundResponseWorkerDependencies['admitResume']>;
};
}
export interface BackgroundResponsesHost {
/** Trusted transports must derive this owner from current actor/source authority. Never expose directly as service-token authority. */
readInteractiveReview: (
owner: ResponseOwner,
responseId: string,
) => Promise<ResponseReviewView | null>;
submitInteractiveReview: ResponseDecisionSubmission;
review: RequestHandler;
submitReview: RequestHandler;
cancelReview: RequestHandler;
retireResponse: (owner: ResponseOwner, responseId: string) => Promise<'stopped' | 'pending'>;
readResponse: (owner: ResponseOwner, responseId: string) => Promise<BackgroundResponseResult>;
cancelResponse: (owner: ResponseOwner, responseId: string) => Promise<BackgroundResponseResult>;
sourceDispatchers: BackgroundResponseQueue['sourceDispatchers'];
initialize: (address: BoundAddress | string | null) => void;
authenticate: (ordinary: RequestHandler) => RequestHandler;
handlers: (ordinary: { create: RequestHandler; retrieve: RequestHandler }) => {
create: RequestHandler;
retrieve: RequestHandler;
cancel: RequestHandler;
};
}
/** A scoped execution credential is not the owner's interactive browser authority. */
function ownerReviewUser(req: Request): IUser | undefined {
if (
getBackgroundResponseWorkerRecord(req) ||
('_isAgentTrigger' in req && req._isAgentTrigger === true) ||
('apiKeyId' in req && req.apiKeyId != null)
)
return;
return (req as ServerRequest).user;
}
export function createBackgroundResponsesHost(
deps: BackgroundResponsesHostDependencies,
): BackgroundResponsesHost {
if (deps.decisions && deps.interactive)
throw new Error('Response decision transport must have one owner');
let listener: BoundAddress | undefined;
const authorize = createBackgroundResponseAuthority(deps);
const review = createResponseReview(deps);
const completion = createResponseCompletion({
storage: deps.storage,
cleanupCheckpoint: cleanupResponseCheckpoint,
releaseExecution: createResponseExecutionRelease(deps.jobs),
confirmExecution: createResponseExecutionConfirmation(deps.jobs),
});
const retire = createResponseRetirement({
storage: deps.storage,
jobs: deps.jobs,
now: deps.now,
cleanupCheckpoint: cleanupResponseCheckpoint,
recoverTerminal: completion.finish,
});
const transportDependencies: BackgroundResponseTransportDependencies = {
storage: deps.storage,
signingSecret: deps.signingSecret,
fetch: deps.fetch,
getOrigin: () => {
if (!listener) throw new Error('Background Responses local listener is not initialized');
return listener;
},
acknowledgementTimeoutMs: async (record) => {
const user = await deps.findUser(record.userId);
if (!user || responseTenantId(user.tenantId) !== responseTenantId(record.tenantId))
throw new Error('Response principal unavailable');
const timeout = (await deps.getConfig(user)).endpoints?.agents?.remoteApi?.background
?.acknowledgementTimeoutMs;
if (timeout == null)
throw new Error('Background response acknowledgement policy unavailable');
return timeout;
},
};
const transport = createBackgroundResponseTransport(transportDependencies);
const queue = createBackgroundResponseQueue({
storage: deps.storage,
enqueue: deps.enqueue,
authorize: (record) => authorize(record, record.agentId, record.sourceKeyId),
execute: transport,
workerCapability: deps.interactive
? AGENT_TRIGGER_WORKER_CAPABILITY_RESPONSES_RESUME_V1
: undefined,
});
const resumeQueue = deps.interactive
? createResponseResumeQueue({
storage: deps.storage,
enqueue: deps.enqueue,
authorize: (record) => authorize(record, record.agentId, record.sourceKeyId),
resume: createResponseResumeTransport({ ...transportDependencies, jobs: deps.jobs }),
})
: undefined;
const decisions =
deps.interactive && resumeQueue
? { validate: deps.interactive.validate, enqueue: resumeQueue.enqueue }
: deps.decisions;
const submitInteractiveReview: ResponseDecisionSubmission = async (owner, responseId, input) => {
if (!decisions) return { ok: false, status: 409, code: 'response_decision_unavailable' };
return createResponseDecisionSubmission({
storage: deps.storage,
jobs: deps.jobs,
now: deps.now,
...decisions,
authorize: (record) => authorize(record, record.agentId, record.sourceKeyId),
})(owner, responseId, input);
};
function service(req?: Request) {
const user = (req as ServerRequest | undefined)?.user;
return createBackgroundResponseService({
storage: deps.storage,
enqueue: queue.enqueue,
deliveryKey: queue.deliveryKey,
authorize: (owner, agentId, keyId) => authorize(owner, agentId, keyId, user),
resolveContinuation: async (owner, previous) => {
const continuation = await resolveResponseContinuation(previous, owner.userId, {
getMessage: deps.getMessage,
});
const stored = previous
? await deps.getConvoRetention(owner.userId, continuation.conversationId)
: null;
if (previous && !stored) throw new Error('Response continuation is unavailable');
const principal = user ?? (await deps.findUser(owner.userId));
if (!principal) throw new Error('Response principal unavailable');
const config = await deps.getConfig(principal);
const policy = resolveImportRetentionFields(
config.interfaceConfig,
{
createChatExpirationDate,
createFallbackRetentionDate,
},
{ sourceIsTemporary: isTemporaryRecord(stored ?? {}) },
);
let expiredAt = stored?.expiredAt ?? policy.expiredAt;
if (policy.expiredAt && (!expiredAt || policy.expiredAt < expiredAt))
expiredAt = policy.expiredAt;
if (!expiredAt && stored && isTemporaryRecord(stored))
expiredAt = createChatExpirationDate(config.interfaceConfig, true);
return {
...continuation,
...(expiredAt ? { expiredAt } : {}),
isTemporary: policy.isTemporary ?? isTemporaryRecord(stored ?? {}),
};
},
// Runtime publication is authoritative; observers never reconstruct a terminal reply from progress.
observe: review.observe,
recoverTerminal: completion.finish,
cancel: async (record) => {
await retire(record, record.responseId);
},
});
}
return {
submitInteractiveReview,
readInteractiveReview: async (owner, responseId) => {
const record = await deps.storage.read(owner, responseId);
if (!record || !(await authorize(record, record.agentId, record.sourceKeyId))) return null;
const view = await review.privateView(await completion.finish(record));
// OAuth URLs stay behind the existing owner-authenticated browser flow.
return {
responseId: view.responseId,
status: view.status,
...(view.recovery ? { recovery: view.recovery } : {}),
oauth: [],
pendingAction: view.pendingAction,
pendingDecision: view.pendingDecision,
canSubmitDecision: decisions != null,
};
},
review: async (req, res) => {
res.set('Cache-Control', 'no-store');
res.set('Referrer-Policy', 'no-referrer');
const user = ownerReviewUser(req);
if (!user?.id) return void res.status(401).json({ error: 'unauthorized' });
try {
const owner = { userId: user.id, tenantId: responseTenantId(user.tenantId) };
const record = await deps.storage.read(owner, req.params.id);
if (!record || !(await authorize(owner, record.agentId, record.sourceKeyId, user)))
return void res.status(404).json({ error: 'response_not_found' });
const recovered = await completion.finish(record);
res.json({
...(await review.privateView(recovered)),
canSubmitDecision: decisions != null,
});
} catch (error) {
deps.onError(error);
res.status(503).json({ error: 'response_service_unavailable' });
}
},
submitReview: async (req, res) => {
res.set('Cache-Control', 'no-store');
res.set('Referrer-Policy', 'no-referrer');
const user = ownerReviewUser(req);
if (!user?.id) return void res.status(401).json({ error: 'unauthorized' });
if (!decisions) return void res.status(503).json({ error: 'response_decision_unavailable' });
const submit = createResponseDecisionSubmission({
storage: deps.storage,
jobs: deps.jobs,
now: deps.now,
...decisions,
authorize: (record) => authorize(record, record.agentId, record.sourceKeyId, user),
});
try {
const result = await submit(
{ userId: user.id, tenantId: responseTenantId(user.tenantId) },
req.params.id,
req.body,
);
if (!result.ok) return void res.status(result.status).json({ error: result.code });
res.status(202).json(result.receipt);
} catch (error) {
deps.onError(error);
res.status(503).json({ error: 'response_service_unavailable' });
}
},
cancelReview: async (req, res) => {
res.set('Cache-Control', 'no-store');
res.set('Referrer-Policy', 'no-referrer');
const user = ownerReviewUser(req);
if (!user?.id) return void res.status(401).json({ error: 'unauthorized' });
try {
const result = await service(req).cancel(
{ userId: user.id, tenantId: responseTenantId(user.tenantId) },
req.params.id,
);
if (!result.ok) return void res.status(result.status).json({ error: result.code });
res.json(result.response);
} catch (error) {
deps.onError(error);
res.status(503).json({ error: 'response_service_unavailable' });
}
},
retireResponse: retire,
readResponse: (owner, responseId) => service().retrieve(owner, responseId),
cancelResponse: (owner, responseId) => service().cancel(owner, responseId),
sourceDispatchers: new Map([
...queue.sourceDispatchers,
...(resumeQueue?.sourceDispatchers ?? []),
]),
initialize: (address: BoundAddress | string | null) => {
listener = address != null && typeof address !== 'string' ? { ...address } : undefined;
},
authenticate: (ordinary: RequestHandler) =>
createBackgroundResponseWorkerAuth(
{
storage: deps.storage,
signingSecret: deps.signingSecret,
findUser: deps.findUser,
onError: deps.onError,
admitResume: deps.interactive?.admitResume,
authorize: (record: StoredResponseRecord, user: IUser) =>
authorize(record, record.agentId, record.sourceKeyId, user),
},
ordinary,
),
handlers: (ordinary: { create: RequestHandler; retrieve: RequestHandler }) =>
createBackgroundResponseHttpHandlers({
service,
ordinary,
onError: deps.onError,
}),
};
}

View file

@ -0,0 +1,127 @@
import { randomUUID } from 'node:crypto';
import type { Request, RequestHandler, Response as HttpResponse } from 'express';
import type { ResponseOwner } from '@librechat/data-schemas';
import type { createBackgroundResponseService, BackgroundResponseResult } from './background';
import type { ServerRequest } from '~/types/http';
import { validateResponseRequest, sendResponsesErrorResponse } from './service';
import { createAgentRunEnvelope, AgentRunEnvelopeError } from '../envelope';
import { getBackgroundResponseWorkerRecord } from './worker';
import { responseTenantId } from './scope';
export interface BackgroundResponseHttpDependencies {
service: (req: Request) => ReturnType<typeof createBackgroundResponseService>;
/** Foreground-only fallback; canonical background history remains journal-owned. */
ordinary: { create: RequestHandler; retrieve: RequestHandler };
onError: (error: unknown) => void;
}
function owner(req: Request): ResponseOwner | null {
const user = (req as ServerRequest).user;
return user?.id ? { userId: user.id, tenantId: responseTenantId(user.tenantId) } : null;
}
function send(res: HttpResponse, result: BackgroundResponseResult, accepted = false): void {
if (result.ok) return void res.status(accepted ? 202 : 200).json(result.response);
return void sendResponsesErrorResponse(
res,
result.status,
result.status === 404 ? 'Response not found.' : 'The response request could not be accepted.',
result.status === 404 ? 'not_found' : 'invalid_request',
result.code,
);
}
/** Install behind the existing remote auth, terms, config and feature/Agent permission checks. */
export function createBackgroundResponseHttpHandlers(deps: BackgroundResponseHttpDependencies): {
create: RequestHandler;
retrieve: RequestHandler;
cancel: RequestHandler;
} {
const unavailable = (res: HttpResponse, error: unknown) => {
deps.onError(error);
return void sendResponsesErrorResponse(
res,
503,
'Response service is unavailable.',
'server_error',
'response_service_unavailable',
);
};
return {
create: async (req, res, next) => {
if (getBackgroundResponseWorkerRecord(req) || req.body?.background !== true)
return deps.ordinary.create(req, res, next);
const validation = validateResponseRequest(req.body);
if (!validation.valid || !validation.request)
return void sendResponsesErrorResponse(
res,
400,
validation.error ?? 'Invalid response request.',
'invalid_request',
);
const principal = owner(req);
const key = (req as Request & { apiKeyId?: { toString(): string } }).apiKeyId;
if (!principal || !key)
return void sendResponsesErrorResponse(
res,
400,
'Background execution requires an Agent API key.',
'invalid_request',
'background_api_key_required',
);
const idempotency = req.headers['idempotency-key'];
if (idempotency != null && typeof idempotency !== 'string')
return void sendResponsesErrorResponse(
res,
400,
'Invalid Idempotency-Key.',
'invalid_request',
);
try {
const envelope = createAgentRunEnvelope({
protocol: 'responses',
requestId: randomUUID(),
receivedAt: Date.now(),
principal: { id: principal.userId, tenantId: principal.tenantId },
payload: validation.request,
});
return send(
res,
await deps.service(req).create(envelope, idempotency, key.toString()),
true,
);
} catch (error) {
if (error instanceof AgentRunEnvelopeError)
return void sendResponsesErrorResponse(
res,
400,
'Invalid response request.',
'invalid_request',
);
return unavailable(res, error);
}
},
retrieve: async (req, res, next) => {
const principal = owner(req);
if (!principal)
return void sendResponsesErrorResponse(res, 401, 'Unauthorized', 'invalid_request');
try {
const result = await deps.service(req).lookup(principal, req.params.id);
if (result == null) return deps.ordinary.retrieve(req, res, next);
return send(res, result);
} catch (error) {
return unavailable(res, error);
}
},
cancel: async (req, res) => {
const principal = owner(req);
if (!principal)
return void sendResponsesErrorResponse(res, 401, 'Unauthorized', 'invalid_request');
try {
return send(res, await deps.service(req).cancel(principal, req.params.id));
} catch (error) {
return unavailable(res, error);
}
},
};
}

View file

@ -14,7 +14,7 @@ export {
resolveResponseContinuation,
} from './persistence';
export { createBackgroundResponseService } from './background';
export { createBackgroundResponsesHost } from './host';
export { createResponseExecutionRuntime } from './runtime';
export { createResponseDecisionSubmission } from './decision';
export { createResponseResumeValidation, createResponseResumeAdmission } from './resume';

View file

@ -97,6 +97,7 @@ const receiptSchema = z.object({
createdAt: z.number(),
completedAt: z.number().nullable(),
});
const backgroundReceiptSchema = z.object({ background: z.literal(true) });
const textPart = z.object({ type: z.literal(ContentTypes.TEXT), text: z.string() });
const toolPart = z.object({
type: z.literal(ContentTypes.TOOL_CALL),
@ -120,6 +121,10 @@ interface SavedConversation {
agent_id?: string;
model?: string;
}
function isBackgroundMessage(message: SavedMessage): boolean {
return backgroundReceiptSchema.safeParse(message.metadata?.responseReceipt).success;
}
export interface StoredForegroundResponseDependencies {
getMessage: (query: { user: string; messageId: string }) => Promise<SavedMessage | null>;
getConvo: (userId: string, conversationId: string) => Promise<SavedConversation | null>;
@ -216,7 +221,7 @@ function restoreOutputIdentity(
return output;
}
/** Both response-ID and legacy conversation-ID reads remain owner/tenant scoped. */
/** Foreground-only response-ID and legacy conversation-ID reads remain owner/tenant scoped. */
export function createStoredForegroundResponseReader(
deps: StoredForegroundResponseDependencies,
): RequestHandler {
@ -239,7 +244,10 @@ export function createStoredForegroundResponseReader(
: undefined;
if (
selected &&
(selected.isCreatedByUser || selected.isUserSubmitted || !selected.conversationId)
(selected.isCreatedByUser ||
selected.isUserSubmitted ||
!selected.conversationId ||
isBackgroundMessage(selected))
)
return missing();
const conversationId = selected?.conversationId ?? responseId;
@ -248,7 +256,7 @@ export function createStoredForegroundResponseReader(
selected ? Promise.resolve([selected]) : deps.getMessages({ user: userId, conversationId }),
]);
const message = selectStoredResponse(messages ?? [], responseId, selected != null)[0];
if (!conversation || !message) return missing();
if (!conversation || !message || isBackgroundMessage(message)) return missing();
const receipt = receiptSchema.safeParse(message.metadata?.responseReceipt);
const context = createResponseContext(
{
@ -281,7 +289,6 @@ export function createStoredForegroundResponseReader(
: createResponseAccountingCollector().snapshot();
if (receipt.success) {
response.status = receipt.data.status ?? response.status;
response.background = receipt.data.background ?? response.background;
response.error = receipt.data.error ?? null;
}
response.previous_response_id = receipt.success ? receipt.data.previousResponseId : null;

View file

@ -8,6 +8,7 @@ import {
} from '@librechat/data-schemas';
import type { ResponseStorage, StoredResponseRecord } from '@librechat/data-schemas';
import type { BackgroundResponseTransportDependencies } from './transport';
import type { BoundAddress } from '~/app/origin';
import { createBackgroundResponseTransport } from './transport';
let mongo: MongoMemoryReplSet;
@ -65,7 +66,7 @@ async function enroll() {
);
if (!result.ok) throw new Error('Enrollment failed');
}
function transport(fetch: Fetch, origin = 'http://127.0.0.1:3088') {
function transport(fetch: Fetch, origin: string | BoundAddress = 'http://127.0.0.1:3088') {
return createBackgroundResponseTransport({
storage,
fetch,
@ -170,3 +171,25 @@ it('refuses remote or credential-bearing worker origins before making a request'
}
expect(calls).toBe(0);
});
it('uses an initialized concrete listener capability without accepting the equivalent arbitrary URL', async () => {
const fetch: Fetch = async (url) => {
expect(String(url)).toBe('http://192.0.2.7:3088/api/agents/v1/responses');
await enroll();
return Response.json(ack, { status: 202 });
};
await expect(scoped(() => transport(fetch, 'http://192.0.2.7:3088')(record))).rejects.toThrow(
'capable local listener',
);
await expect(
scoped(() => transport(fetch, { address: '192.0.2.7', family: 'IPv4', port: 3088 })(record)),
).resolves.toEqual({ status: 'started', generationCreatedAt: 1234 });
});
it('rejects a hostname masquerading as a bound listener before dispatch', async () => {
const fetch = jest.fn<ReturnType<Fetch>, Parameters<Fetch>>();
await expect(
scoped(() => transport(fetch, { address: 'example.test', port: 3088 })(record)),
).rejects.toThrow('capable local listener');
expect(fetch).not.toHaveBeenCalled();
});

View file

@ -1,18 +1,22 @@
import { z } from 'zod';
import { isIP } from 'node:net';
import type { StoredResponseRecord, ResponseStorage } from '@librechat/data-schemas';
import type { GenerationJobManagerClass } from '~/stream/GenerationJobManager';
import type { BackgroundResponseQueueDependencies } from './queue';
import type { BoundAddress } from '~/app/origin';
import {
mintBackgroundResponseWorkerToken,
mintResponseResumeWorkerToken,
RESPONSE_WORKER_TOKEN_EXPIRED,
} from './worker';
import { AgentTriggerExecutionError } from '../triggers/host';
import { selfOriginFromAddress } from '~/app/origin';
import { responseTenantId } from './scope';
export interface BackgroundResponseTransportDependencies {
storage: ResponseStorage;
getOrigin: () => string;
/** A BoundAddress must come from the capable process's initialized server.address(). */
getOrigin: () => string | BoundAddress;
signingSecret: () => string;
acknowledgementTimeoutMs: (record: StoredResponseRecord) => Promise<number>;
fetch?: (
@ -96,12 +100,17 @@ function createResponseWorkerTransport(
status: 'started' | 'resumed' | 'settled';
generationCreatedAt?: number;
}> => {
const origin = new URL(deps.getOrigin());
const listener = deps.getOrigin();
const initialized = typeof listener !== 'string';
const localOrigin = initialized ? selfOriginFromAddress(listener) : listener;
if (!localOrigin || (initialized && !isIP(listener.address)))
throw new Error('Background Responses requires the capable local listener');
const origin = new URL(localOrigin);
if (
!['http:', 'https:'].includes(origin.protocol) ||
origin.username ||
origin.password ||
!['127.0.0.1', '::1', '[::1]', 'localhost'].includes(origin.hostname)
(!initialized && !['127.0.0.1', '::1', '[::1]', 'localhost'].includes(origin.hostname))
)
throw new Error('Background Responses requires the capable local listener');
const timeoutMs = await deps.acknowledgementTimeoutMs(record);

View file

@ -2,8 +2,8 @@ import express from 'express';
import jwt from 'jsonwebtoken';
import request from 'supertest';
import mongoose from 'mongoose';
import { FileSources } from 'librechat-data-provider';
import { MongoMemoryReplSet } from 'mongodb-memory-server';
import { FileSources, PermissionBits } from 'librechat-data-provider';
import {
createModels,
createMethods,
@ -43,7 +43,10 @@ import { GenerationJobManager } from '~/stream';
import { createResponseTurn } from './turn';
// Load the compiled entry as a suite dependency, outside the settlement test's deadline.
jest.requireActual('@librechat/api');
const compiled = jest.requireActual<{
createStoredForegroundResponseReader: typeof import('./stored').createStoredForegroundResponseReader;
createBackgroundResponsesHost: typeof import('./host').createBackgroundResponsesHost;
}>('@librechat/api');
let mongo: MongoMemoryReplSet;
let storage: ResponseStorage;
@ -1348,17 +1351,49 @@ describe('background Responses execution handoff', () => {
const readApp = express();
const methods = createMethods(mongoose);
readApp.use((req, _res, next) => {
Object.assign(req, { user: { id: owner.userId } });
Object.assign(req, { user });
tenantStorage.run(owner, next);
});
// Exercise the built export wired by the CJS controller, against the actual committed rows.
const compiled = jest.requireActual<{
createStoredForegroundResponseReader: typeof import('./stored').createStoredForegroundResponseReader;
}>('@librechat/api');
readApp.get(
'/:id',
compiled.createStoredForegroundResponseReader({ ...methods, logger: { error: jest.fn() } }),
);
// Exercise the compiled host and its actual foreground fallback over committed history.
const readHost = compiled.createBackgroundResponsesHost({
storage,
jobs: GenerationJobManager,
findUser: async () => user,
getKey: async () => ({}),
getRole: async () =>
new mongoose.models.Role({ name: 'USER', permissions: { REMOTE_AGENTS: { USE: true } } }),
getConfig: async () => ({
config: {},
fileStrategy: FileSources.local,
imageOutputType: 'png',
endpoints: {
agents: {
remoteApi: { background: { enabled: true, acknowledgementTimeoutMs: 1000 } },
},
},
}),
isPrincipalActive: async () => true,
getAgentPermissions: async () => PermissionBits.VIEW,
getMessage: methods.getMessage,
getConvoRetention: methods.getConvoRetention,
enqueue: async () => {
throw new Error('Retrieval must not enqueue another provider');
},
signingSecret: () => secret,
onError: (error) => {
errors.push(error);
},
});
const readHandlers = readHost.handlers({
create: (_req, res) => {
res.sendStatus(500);
},
retrieve: compiled.createStoredForegroundResponseReader({
...methods,
logger: { error: jest.fn() },
}),
});
readApp.get('/:id', readHandlers.retrieve);
const read = await request(readApp)
.get('/' + record.responseId)
.expect(200);
@ -1367,6 +1402,17 @@ describe('background Responses execution handoff', () => {
expect(read.body.error).toEqual(JSON.parse(saved.responseJSON!).error);
expect(JSON.stringify(read.body)).not.toContain('private provider diagnostics');
await scope(() => mongoose.models.ResponseScope.updateMany({}, { $set: { closed: true } }));
await request(readApp)
.get('/' + record.responseId)
.expect(404);
await scope(() =>
mongoose.models.StoredResponse.deleteOne({ responseId: record.responseId }),
);
await request(readApp)
.get('/' + record.responseId)
.expect(404);
expect(
await scope(() =>
mongoose.models.Message.findOne({