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: Resolve Native and Langfuse Prompts by Source (#16909)

Atef Bellaaj02613ce2122e
diff --git a/api/server/middleware/limiters/index.js b/api/server/middleware/limiters/index.js
index 757afc6018..59679ec099 100644
--- a/api/server/middleware/limiters/index.js
+++ b/api/server/middleware/limiters/index.js
@@ -11,6 +11,7 @@ const registerLimiter = require('./registerLimiter');
const toolCallLimiter = require('./toolCallLimiter');
const messageLimiters = require('./messageLimiters');
const promptUsageLimiter = require('./promptUsageLimiter');
+const promptResolveLimiter = require('./promptResolveLimiter');
const verifyEmailLimiter = require('./verifyEmailLimiter');
const emailChangeLimiter = require('./emailChangeLimiter');
const emailChangeSubmissionLimiter = require('./emailChangeSubmissionLimiter');
@@ -30,6 +31,7 @@ module.exports = {
...forkLimiters,
...shareLimiters,
...promptUsageLimiter,
+ ...promptResolveLimiter,
loginLimiter,
passkeyLimiter,
passkeyStepUpLimiter,
diff --git a/api/server/middleware/limiters/promptResolveLimiter.js b/api/server/middleware/limiters/promptResolveLimiter.js
new file mode 100644
index 0000000000..5b63b37486
--- /dev/null
+++ b/api/server/middleware/limiters/promptResolveLimiter.js
@@ -0,0 +1,5 @@
+const { createPromptResolveLimiter } = require('@librechat/api');
+
+const promptResolveLimiter = createPromptResolveLimiter();
+
+module.exports = { promptResolveLimiter };
diff --git a/api/server/routes/agents/actions.contentFilter.spec.js b/api/server/routes/agents/actions.contentFilter.spec.js
index 20c48f631f..dd8093c047 100644
--- a/api/server/routes/agents/actions.contentFilter.spec.js
+++ b/api/server/routes/agents/actions.contentFilter.spec.js
@@ -34,6 +34,9 @@ jest.mock('~/models', () => ({
jest.mock('~/server/middleware', () => ({
canAccessAgentResource: jest.fn(() => (_req, _res, next) => next()),
}));
+jest.mock('~/server/services/Config', () => ({
+ getAppConfig: jest.fn(),
+}));
const router = require('./actions');
const db = require('~/models');
diff --git a/api/server/routes/agents/actions.spec.js b/api/server/routes/agents/actions.spec.js
index 426cdcdece..858537ea66 100644
--- a/api/server/routes/agents/actions.spec.js
+++ b/api/server/routes/agents/actions.spec.js
@@ -50,6 +50,9 @@ jest.mock('~/models', () => ({
jest.mock('~/server/middleware', () => ({
canAccessAgentResource: jest.fn(() => (_req, _res, next) => next()),
}));
+jest.mock('~/server/services/Config', () => ({
+ getAppConfig: jest.fn(),
+}));
const router = require('./actions');
const db = require('~/models');
diff --git a/api/server/routes/prompts.js b/api/server/routes/prompts.js
index 27438f4913..274d306760 100644
--- a/api/server/routes/prompts.js
+++ b/api/server/routes/prompts.js
@@ -15,10 +15,12 @@ const {
canAccessPromptGroupResource,
canAccessPromptViaGroup,
promptUsageLimiter,
+ promptResolveLimiter,
requireJwtAuth,
configMiddleware,
} = require('~/server/middleware');
const { getEffectivePermissions, grantPermission } = require('~/server/services/PermissionService');
+const { getAppConfig } = require('~/server/services/Config');
const { getLogStores } = require('~/cache');
const db = require('~/models');
@@ -28,7 +30,11 @@ const router = express.Router();
const linkedInstructionsCache = getLogStores(CacheKeys.AGENT_LINKED_INSTRUCTIONS);
const handlers = createPromptHandlers({
- service: createPromptService({ db, grantPermission }),
+ service: createPromptService({
+ db,
+ grantPermission,
+ getAppConfig,
+ }),
getPromptGroupAccessContext: db.getPromptGroupAccessContext,
getEffectivePermissions,
invalidateLinkedPrompt: (groupId, promptIds) =>
@@ -55,6 +61,13 @@ router.get(
configMiddleware,
handlers.getPromptGroup,
);
+router.get(
+ '/groups/:groupId/resolve',
+ promptResolveLimiter,
+ canAccessPromptGroupResource({ requiredPermission: PermissionBits.VIEW }),
+ configMiddleware,
+ handlers.resolvePrompt,
+);
router.get('/all', configMiddleware, handlers.listAllPromptGroups);
router.get('/groups', configMiddleware, handlers.listPromptGroups);
diff --git a/api/server/routes/prompts.test.js b/api/server/routes/prompts.test.js
index 0140628b56..047c4fc0a9 100644
--- a/api/server/routes/prompts.test.js
+++ b/api/server/routes/prompts.test.js
@@ -8,15 +8,17 @@ const {
ResourceType,
AccessRoleIds,
PrincipalType,
+ PrincipalModel,
PermissionBits,
} = require('librechat-data-provider');
-const { SystemCapabilities } = require('@librechat/data-schemas');
+const { SystemCapabilities, BASE_CONFIG_PRINCIPAL_ID } = require('@librechat/data-schemas');
let mockAppConfig = {};
// Mock modules before importing
jest.mock('~/server/services/Config', () => ({
getCachedTools: jest.fn().mockResolvedValue({}),
+ getAppConfig: jest.fn().mockResolvedValue({}),
}));
jest.mock('~/models', () => {
@@ -43,6 +45,7 @@ jest.mock('~/server/middleware', () => ({
next();
}),
promptUsageLimiter: (req, res, next) => next(),
+ promptResolveLimiter: (req, res, next) => next(),
canAccessPromptViaGroup: jest.requireActual('~/server/middleware').canAccessPromptViaGroup,
canAccessPromptGroupResource:
jest.requireActual('~/server/middleware').canAccessPromptGroupResource,
@@ -53,9 +56,10 @@ const { configMiddleware } = require('~/server/middleware');
let app;
let mongoServer;
let promptRoutes;
-let Prompt, PromptGroup, AclEntry, AccessRole, User, SystemGrant;
+let Prompt, PromptGroup, AclEntry, AccessRole, User, SystemGrant, Config;
let testUsers, testRoles;
let grantPermission;
+let db;
let currentTestUser; // Track current user for middleware
// Helper function to set user in middleware
@@ -76,6 +80,8 @@ beforeAll(async () => {
AccessRole = dbModels.AccessRole;
User = dbModels.User;
SystemGrant = dbModels.SystemGrant;
+ Config = dbModels.Config;
+ db = require('~/models');
// Import permission service
const permissionService = require('~/server/services/PermissionService');
@@ -1384,6 +1390,244 @@ async function responseOf(pending) {
return { status, body };
}
+describe('GET /api/prompts/groups/:groupId/resolve', () => {
+ afterEach(async () => {
+ await Prompt.deleteMany({});
+ await PromptGroup.deleteMany({});
+ await AclEntry.deleteMany({});
+ });
+
+ it('resolves the production revision for a native group', async () => {
+ const { group, prompt } = await createAccessiblePromptGroup({
+ name: 'Resolve native group',
+ prompt: 'Native production text',
+ });
+
+ const response = await request(app).get(`/api/prompts/groups/${group._id}/resolve`).expect(200);
+
+ expect(response.body).toEqual({
+ source: 'native',
+ groupId: group._id.toString(),
+ promptId: prompt._id.toString(),
+ prompt: 'Native production text',
+ type: 'text',
+ });
+ });
+
+ it('returns 403 without VIEW permission', async () => {
+ const { group } = await createAccessiblePromptGroup({
+ name: 'Resolve forbidden group',
+ prompt: 'Native text',
+ });
+ setTestUser(app, testUsers.noAccess);
+
+ const response = await request(app).get(`/api/prompts/groups/${group._id}/resolve`).expect(403);
+
+ expect(response.body.error).toBe('Forbidden');
+ });
+
+ it('returns 404 for a missing group', async () => {
+ const response = await request(app)
+ .get(`/api/prompts/groups/${new ObjectId()}/resolve`)
+ .expect(404);
+
+ expect(response.body).toEqual({
+ error: 'Not Found',
+ message: `${ResourceType.PROMPTGROUP} not found`,
+ });
+ });
+
+ it('is not captured by GET /:promptId', async () => {
+ const { group, prompt } = await createAccessiblePromptGroup({
+ name: 'Resolve route segments',
+ prompt: 'Native text',
+ });
+
+ const response = await request(app).get(`/api/prompts/groups/${group._id}/resolve`);
+
+ expect(response.status).toBe(200);
+ expect(response.body).toEqual({
+ source: 'native',
+ groupId: group._id.toString(),
+ promptId: prompt._id.toString(),
+ prompt: 'Native text',
+ type: 'text',
+ });
+ });
+
+ describe('a Langfuse-origin group', () => {
+ const langfuseEnv = {
+ LANGFUSE_PROMPT_SYNC_AVAILABLE: 'true',
+ LANGFUSE_PUBLIC_KEY: 'pk-resolve',
+ LANGFUSE_SECRET_KEY: 'sk-resolve',
+ LANGFUSE_PROJECT_ID: 'resolve-project',
+ LANGFUSE_BASE_URL: 'https://langfuse.resolve.test',
+ };
+ let fetchSpy;
+ let group;
+ let previousLangfuseEnv;
+
+ beforeEach(async () => {
+ previousLangfuseEnv = {};
+ for (const key of Object.keys(langfuseEnv)) {
+ previousLangfuseEnv[key] = process.env[key];
+ }
+ Object.assign(process.env, langfuseEnv);
+ await db.upsertConfig(
+ PrincipalType.ROLE,
+ BASE_CONFIG_PRINCIPAL_ID,
+ PrincipalModel.ROLE,
+ { langfuse: { promptSync: { enabled: true } } },
+ 10,
+ );
+ group = await PromptGroup.create({
+ name: 'Langfuse group',
+ category: 'resolve-test',
+ author: testUsers.owner._id,
+ authorName: testUsers.owner.name,
+ source: 'langfuse',
+ sourcePromptName: 'greeting',
+ sourceProjectId: 'resolve-project',
+ sourceDestination: 'env',
+ });
+ await grantPermission({
+ principalType: PrincipalType.USER,
+ principalId: testUsers.owner._id,
+ resourceType: ResourceType.PROMPTGROUP,
+ resourceId: group._id,
+ accessRoleId: AccessRoleIds.PROMPTGROUP_OWNER,
+ grantedBy: testUsers.owner._id,
+ });
+ });
+
+ afterEach(async () => {
+ for (const key of Object.keys(langfuseEnv)) {
+ if (previousLangfuseEnv[key] === undefined) {
+ delete process.env[key];
+ } else {
+ process.env[key] = previousLangfuseEnv[key];
+ }
+ }
+ if (fetchSpy) {
+ fetchSpy.mockRestore();
+ fetchSpy = undefined;
+ }
+ await Config.deleteMany({});
+ });
+
+ function mockLangfuseFetch(responder) {
+ fetchSpy = jest.spyOn(global, 'fetch').mockImplementation(responder);
+ }
+
+ function textPromptResponse(payload, status = 200) {
+ return new Response(JSON.stringify(payload), {
+ status,
+ headers: { 'Content-Type': 'application/json' },
+ });
+ }
+
+ it('resolves the production label', async () => {
+ mockLangfuseFetch(async () =>
+ textPromptResponse({
+ name: 'greeting',
+ version: 1,
+ type: 'text',
+ labels: ['production'],
+ prompt: 'Hello {{name}}',
+ }),
+ );
+
+ const response = await request(app)
+ .get(`/api/prompts/groups/${group._id}/resolve`)
+ .expect(200);
+
+ expect(response.body).toEqual({
+ source: 'langfuse',
+ groupId: group._id.toString(),
+ prompt: 'Hello {{name}}',
+ type: 'text',
+ version: 1,
+ labels: ['production'],
+ });
+ const [url] = fetchSpy.mock.calls[0];
+ expect(url).toContain('label=production');
+ expect(url).not.toContain('version=');
+ });
+
+ it('resolves an exact version and sends it with no label', async () => {
+ mockLangfuseFetch(async () =>
+ textPromptResponse({
+ name: 'greeting',
+ version: 3,
+ type: 'text',
+ labels: [],
+ prompt: 'Hello v3',
+ }),
+ );
+
+ const response = await request(app)
+ .get(`/api/prompts/groups/${group._id}/resolve`)
+ .query({ version: 3 })
+ .expect(200);
+
+ expect(response.body).toEqual({
+ source: 'langfuse',
+ groupId: group._id.toString(),
+ prompt: 'Hello v3',
+ type: 'text',
+ version: 3,
+ labels: [],
+ });
+ const [url] = fetchSpy.mock.calls[0];
+ expect(url).toContain('version=3');
+ expect(url).not.toContain('label=');
+ });
+
+ it('rejects a chat prompt with 422', async () => {
+ mockLangfuseFetch(async () =>
+ textPromptResponse({
+ name: 'greeting',
+ version: 1,
+ type: 'chat',
+ labels: ['production'],
+ prompt: [{ role: 'system', content: 'secret' }],
+ }),
+ );
+
+ const response = await request(app)
+ .get(`/api/prompts/groups/${group._id}/resolve`)
+ .expect(422);
+
+ expect(response.body).toEqual({ code: 'unsupported_type' });
+ });
+
+ it('returns 404 with the Langfuse message for a missing prompt', async () => {
+ mockLangfuseFetch(async () => new Response(null, { status: 404 }));
+
+ const response = await request(app)
+ .get(`/api/prompts/groups/${group._id}/resolve`)
+ .expect(404);
+
+ expect(response.body).toEqual({
+ code: 'not_found',
+ message: 'Prompt not found in Langfuse',
+ });
+ });
+
+ it('returns 404 not_available when prompt sync is gated off', async () => {
+ delete process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE;
+ mockLangfuseFetch(async () => textPromptResponse({}));
+
+ const response = await request(app)
+ .get(`/api/prompts/groups/${group._id}/resolve`)
+ .expect(404);
+
+ expect(response.body).toEqual({ code: 'not_available' });
+ expect(fetchSpy).not.toHaveBeenCalled();
+ });
+ });
+});
+
describe('Prompt Routes - response and failure compatibility', () => {
let consoleErrorSpy;
let group;
diff --git a/api/server/services/Agents/instructionsPrompt.js b/api/server/services/Agents/instructionsPrompt.js
index 6da3a40aff..938e33e9d5 100644
--- a/api/server/services/Agents/instructionsPrompt.js
+++ b/api/server/services/Agents/instructionsPrompt.js
@@ -11,13 +11,21 @@ const {
getResourcePermissionsMap,
} = require('~/server/services/PermissionService');
const { hasCapability } = require('~/server/middleware/roles/capabilities');
+const { getAppConfig } = require('~/server/services/Config');
const db = require('~/models');
-/** Wiring only: the write/present decision logic lives in `@librechat/api` (`createInstructionsPromptAccess`, `checkInstructionsPromptWrite`). */
+/**
+ * Wiring only: the write/present decision logic lives in `@librechat/api`
+ * (`createInstructionsPromptAccess`, `checkInstructionsPromptWrite`).
+ */
const instructionsPromptAccess = createInstructionsPromptAccess({
getResourcePermissionsMap,
canManagePrompts: (user) => hasCapability(user, SystemCapabilities.MANAGE_PROMPTS),
- promptService: createPromptService({ db, grantPermission }),
+ promptService: createPromptService({
+ db,
+ grantPermission,
+ getAppConfig,
+ }),
assertAgentInstructionsContent: ({ instructions, filters }) =>
assertModelBoundContent({ filters, agents: [{ instructions }] }),
/** The same role-level gate `checkPromptAccess` applies to every `/prompts` route
diff --git a/api/server/services/Endpoints/agents/linkedInstructions.js b/api/server/services/Endpoints/agents/linkedInstructions.js
index a105867fdf..db506a6646 100644
--- a/api/server/services/Endpoints/agents/linkedInstructions.js
+++ b/api/server/services/Endpoints/agents/linkedInstructions.js
@@ -2,6 +2,7 @@ const { logger } = require('@librechat/data-schemas');
const { CacheKeys } = require('librechat-data-provider');
const { createPromptService, createLinkedInstructionsResolver } = require('@librechat/api');
const { grantPermission } = require('~/server/services/PermissionService');
+const { getAppConfig } = require('~/server/services/Config');
const { getLogStores } = require('~/cache');
const db = require('~/models');
@@ -12,7 +13,11 @@ const db = require('~/models');
* `AGENT_LINKED_INSTRUCTIONS` cache namespace (`~/cache/getLogStores.js`).
*/
const linkedInstructionsResolver = createLinkedInstructionsResolver({
- promptService: createPromptService({ db, grantPermission }),
+ promptService: createPromptService({
+ db,
+ grantPermission,
+ getAppConfig,
+ }),
cache: getLogStores(CacheKeys.AGENT_LINKED_INSTRUCTIONS),
logger,
});
diff --git a/packages/api/src/admin/langfuse.ts b/packages/api/src/admin/langfuse.ts
index ae45cf0159..8f7e6409a1 100644
--- a/packages/api/src/admin/langfuse.ts
+++ b/packages/api/src/admin/langfuse.ts
@@ -19,13 +19,9 @@ import type {
TLangfusePromptGetResponse,
TLangfusePromptErrorBody,
} from 'librechat-data-provider';
-import type { AppConfig, ConfigRecord, MessageMethods } from '@librechat/data-schemas';
+import type { ConfigRecord, MessageMethods } from '@librechat/data-schemas';
import type { Response } from 'express';
-import type {
- LangfusePromptConnection,
- LangfuseTextPromptSelector,
- LangfusePromptRequestErrorCode,
-} from '~/langfuse/prompts';
+import type { LangfusePromptConnection, LangfuseTextPromptSelector } from '~/langfuse/prompts';
import type { LangfuseTenantDestination } from '~/langfuse/tenantDestinations';
import type { ServerRequest } from '~/types/http';
import type { RecordAuditEntry } from './audit';
@@ -36,15 +32,19 @@ import {
getLangfuseConnectionAvailability,
} from '~/langfuse/policy';
import {
- resolveLangfusePromptConnection,
- listLangfusePrompts,
- getLangfuseTextPrompt,
- LangfusePromptRequestError,
-} from '~/langfuse/prompts';
+ readStoredLangfuse,
+ buildPromptSyncConnection,
+ toLangfusePromptErrorResponse,
+} from '~/langfuse/promptSync';
import {
getLangfuseTenantDestinations,
resolveLangfuseTenantDestination,
} from '~/langfuse/tenantDestinations';
+import {
+ listLangfusePrompts,
+ getLangfuseTextPrompt,
+ LangfusePromptRequestError,
+} from '~/langfuse/prompts';
import { redirectPolicyFor, resolveLangfuseHeaders } from '~/langfuse/utils';
import { decryptConfigSecret, encryptConfigSecretFields } from './secrets';
import { scopeHeadersToDestination } from '~/langfuse/destinations';
@@ -110,14 +110,6 @@ function getTenantId(req: ServerRequest): string | undefined {
return (req.user as { tenantId?: string } | undefined)?.tenantId;
}
-/** Reads from the stored override tree, so this is `TCustomConfig`'s
- * `DeepPartial` view of the section rather than the standalone
- * `LangfuseConfig` — record-valued fields carry optional values here. */
-function readStoredLangfuse(config: ConfigRecord | null): TCustomConfig['langfuse'] {
- const overrides = config?.overrides as Partial<TCustomConfig> | undefined;
- return overrides?.langfuse;
-}
-
function buildStatus(config: ConfigRecord | null): TLangfuseConnectionStatus {
const stored = readStoredLangfuse(config);
const configured = Boolean(stored?.publicKey && stored?.secretKey);
@@ -208,13 +200,6 @@ const promptVersionQuerySchema = z.coerce
.max(Number.MAX_SAFE_INTEGER)
.optional();
-/** HTTP status for a `LangfusePromptRequestError`. A Langfuse `unauthorized`
- * never maps to 401/403: the LibreChat client treats either as its own
- * session expiring and reacts by refreshing the token or signing out. */
-function promptRequestErrorStatus(code: LangfusePromptRequestErrorCode): number {
- return code === 'timeout' ? 504 : 502;
-}
-
/** Maps a thrown Langfuse prompt request failure to the stable `{ code }`
* contract. Never forwards the upstream body, headers or credentials; logs
* only the error's own code/status/message, which `prompts.ts` guarantees
@@ -222,11 +207,8 @@ function promptRequestErrorStatus(code: LangfusePromptRequestErrorCode): number
function respondToPromptRequestError(res: Response, error: unknown, logPrefix: string): Response {
if (error instanceof LangfusePromptRequestError) {
logger.error(logPrefix, error);
- const body: TLangfusePromptErrorBody =
- error.code === 'upstream' && error.status != null
- ? { code: error.code, status: error.status }
- : { code: error.code };
- return res.status(promptRequestErrorStatus(error.code)).json(body);
+ const { status, body } = toLangfusePromptErrorResponse(error);
+ return res.status(status).json(body);
}
logger.error(logPrefix, error);
@@ -455,11 +437,7 @@ export function createAdminLangfuseHandlers(deps: AdminLangfuseDeps): {
req: ServerRequest,
stored: TCustomConfig['langfuse'],
): LangfusePromptConnection | null {
- const appConfig = {
- ...req.config,
- langfuse: { ...stored, headers: req.config?.langfuse?.headers },
- } as AppConfig;
- return resolveLangfusePromptConnection(appConfig, { tenantId: getTenantId(req) });
+ return buildPromptSyncConnection(req.config, stored, getTenantId(req));
}
async function getConnection(req: ServerRequest, res: Response): Promise<Response> {
diff --git a/packages/api/src/agents/instructions/access.spec.ts b/packages/api/src/agents/instructions/access.spec.ts
index 4e5328ee20..3555525c69 100644
--- a/packages/api/src/agents/instructions/access.spec.ts
+++ b/packages/api/src/agents/instructions/access.spec.ts
@@ -67,7 +67,16 @@ function buildAccess({
});
const resolve = jest.fn(async () =>
resolvePromptOk
- ? { ok: true as const, value: { groupId, promptId, prompt: 'hi', type: 'text' as const } }
+ ? {
+ ok: true as const,
+ value: {
+ source: 'native' as const,
+ groupId,
+ promptId,
+ prompt: 'hi',
+ type: 'text' as const,
+ },
+ }
: {
ok: false as const,
error: { type: 'unavailable_selection' as const, reason: 'production' as const },
@@ -311,6 +320,29 @@ describe('createInstructionsPromptAccess', () => {
});
});
+ it('rejects a link to a non-native group (unavailable)', async () => {
+ const resolvePrompt = jest.fn(async () => ({
+ ok: false as const,
+ error: { type: 'unsupported_source' as const, source: 'langfuse' as const },
+ }));
+ const { access, resolve } = buildAccess({
+ visibleGroupIds: new Set([groupId]),
+ resolvePrompt,
+ });
+ const result = await access.validateLinkWrite({ user, previous: null, next: exactLink });
+ expect(result).toEqual({
+ ok: false,
+ status: 400,
+ code: InstructionsPromptErrorCode.UNAVAILABLE,
+ });
+ expect(resolve).toHaveBeenCalledWith({
+ groupId,
+ selection: exactLink.selection,
+ filters: undefined,
+ allowedSources: ['native'],
+ });
+ });
+
it('accepts a viewable, resolvable new link (happy path)', async () => {
const { access, resolve } = buildAccess({ visibleGroupIds: new Set([groupId]) });
const result = await access.validateLinkWrite({ user, previous: null, next: exactLink });
@@ -319,6 +351,7 @@ describe('createInstructionsPromptAccess', () => {
groupId,
selection: exactLink.selection,
filters: undefined,
+ allowedSources: ['native'],
});
});
@@ -340,6 +373,7 @@ describe('createInstructionsPromptAccess', () => {
groupId,
selection: productionLink.selection,
filters,
+ allowedSources: ['native'],
});
});
diff --git a/packages/api/src/agents/instructions/access.ts b/packages/api/src/agents/instructions/access.ts
index a7ab0968d2..601ada0fc5 100644
--- a/packages/api/src/agents/instructions/access.ts
+++ b/packages/api/src/agents/instructions/access.ts
@@ -355,6 +355,7 @@ export function createInstructionsPromptAccess(deps: {
groupId: next.groupId,
selection: next.selection,
filters,
+ allowedSources: ['native'],
});
if (!resolved.ok) {
return { ok: false, status: 400, code: InstructionsPromptErrorCode.UNAVAILABLE };
diff --git a/packages/api/src/agents/instructions/linked.spec.ts b/packages/api/src/agents/instructions/linked.spec.ts
index eb6b5cdb91..66b53c88ae 100644
--- a/packages/api/src/agents/instructions/linked.spec.ts
+++ b/packages/api/src/agents/instructions/linked.spec.ts
@@ -1,6 +1,6 @@
import type { FiltersConfig, AgentInstructionsPrompt } from 'librechat-data-provider';
import type { LinkedInstructionsCache, LinkedInstructionsLogger } from './linked';
-import type { PromptService, ResolvedPrompt } from '~/prompts';
+import type { PromptService, NativeResolvedPrompt } from '~/prompts';
import { createLinkedInstructionsResolver, invalidateLinkedPrompt } from './linked';
import { ContentTraversalLimitError } from '~/protection/adapters/nested';
import { assertModelBoundContent } from '~/middleware/modelBoundContent';
@@ -88,8 +88,9 @@ const exactLink: AgentInstructionsPrompt = {
selection: { type: 'exact', promptId },
};
-function makeResolvedPrompt(overrides: Partial<ResolvedPrompt> = {}): ResolvedPrompt {
+function makeResolvedPrompt(overrides: Partial<NativeResolvedPrompt> = {}): NativeResolvedPrompt {
return {
+ source: 'native',
groupId,
promptId,
prompt: 'You are a helpful assistant.',
@@ -137,6 +138,7 @@ describe('createLinkedInstructionsResolver', () => {
groupId,
selection: { type: 'production' },
filters: undefined,
+ allowedSources: ['native'],
});
await expect(cache.get(`native:${groupId}:production`)).resolves.toMatchObject({
groupId,
@@ -158,6 +160,7 @@ describe('createLinkedInstructionsResolver', () => {
groupId,
selection: { type: 'exact', promptId },
filters: undefined,
+ allowedSources: ['native'],
});
await expect(cache.get(`native:${groupId}:exact:${promptId}`)).resolves.toBeDefined();
});
@@ -507,6 +510,48 @@ describe('createLinkedInstructionsResolver', () => {
});
});
+ it('calls resolvePrompt with allowedSources native-only and maps a rejected non-native group (unsupported_source) to unavailable_selection', async () => {
+ const cache = new FakeCache();
+ const promptService = makePromptService({
+ resolvePrompt: jest.fn().mockResolvedValue({
+ ok: false,
+ error: { type: 'unsupported_source', source: 'langfuse' },
+ }),
+ });
+ const logger = makeLogger();
+ const resolver = createLinkedInstructionsResolver({ promptService, cache, logger });
+
+ await expect(resolver({ link: productionLink })).resolves.toEqual({
+ status: 'unavailable',
+ reason: 'unavailable_selection',
+ });
+ expect(promptService.resolvePrompt).toHaveBeenCalledWith({
+ groupId,
+ selection: { type: 'production' },
+ filters: undefined,
+ allowedSources: ['native'],
+ });
+ });
+
+ it.each([
+ ['unsupported_selection', { type: 'unsupported_selection', source: 'native' }],
+ ['source_unavailable', { type: 'source_unavailable', source: 'langfuse', reason: 'disabled' }],
+ ['source_not_found', { type: 'source_not_found', source: 'langfuse' }],
+ ['unsupported_content', { type: 'unsupported_content', reason: 'chat_prompt' }],
+ ] as const)('maps the service error "%s" to the generic "error" reason', async (_name, error) => {
+ const cache = new FakeCache();
+ const promptService = makePromptService({
+ resolvePrompt: jest.fn().mockResolvedValue({ ok: false, error }),
+ });
+ const logger = makeLogger();
+ const resolver = createLinkedInstructionsResolver({ promptService, cache, logger });
+
+ await expect(resolver({ link: productionLink })).resolves.toEqual({
+ status: 'unavailable',
+ reason: 'error',
+ });
+ });
+
it('throws the abort reason when already aborted before any work starts', async () => {
const cache = new FakeCache();
const getSpy = jest.spyOn(cache, 'get');
diff --git a/packages/api/src/agents/instructions/linked.ts b/packages/api/src/agents/instructions/linked.ts
index 2d68ba09a7..e4f026d5ce 100644
--- a/packages/api/src/agents/instructions/linked.ts
+++ b/packages/api/src/agents/instructions/linked.ts
@@ -5,8 +5,8 @@ import type {
AgentInstructionsPromptSelection,
RestrictedAgentInstructionsPrompt,
} from 'librechat-data-provider';
+import type { NativeResolvedPrompt, PromptServiceError } from '~/prompts/types';
import type { PromptService } from '~/prompts/service';
-import type { ResolvedPrompt } from '~/prompts/types';
import { assertModelBoundContent } from '~/middleware/modelBoundContent';
import { isContentFilterError } from '~/middleware/contentFilter';
import { inspectPromptContent } from '~/prompts/protection';
@@ -102,7 +102,7 @@ interface CachedLinkedPrompt {
readonly groupId: string;
readonly promptId: string;
readonly prompt: string;
- readonly type: ResolvedPrompt['type'];
+ readonly type: NativeResolvedPrompt['type'];
}
class LinkedInstructionsTimeoutError extends Error {
@@ -157,10 +157,26 @@ function errorName(error: unknown): string {
return error instanceof Error ? error.name : typeof error;
}
+/**
+ * Agent links stay native only (`allowedSources: ['native']` on every `resolvePrompt`
+ * call in this module). `blocked_content` and `unavailable_selection` map directly, and
+ * `unsupported_source` — returned by that `allowedSources` check when a link's group
+ * has since become a Langfuse group — maps to `unavailable_selection`, the same reason
+ * a missing native selection gets. The remaining source-routing types
+ * (`unsupported_selection`, `source_unavailable`, `source_not_found`,
+ * `unsupported_content`) never reach a native-only caller and map to the generic
+ * `'error'` reason only as a fallback.
+ */
function mapServiceErrorReason(
- type: 'invalid_input' | 'blocked_content' | 'unavailable_selection' | 'unsupported',
+ type: PromptServiceError['type'],
): LinkedInstructionsUnavailableReason {
- return type === 'blocked_content' || type === 'unavailable_selection' ? type : 'error';
+ if (type === 'blocked_content' || type === 'unavailable_selection') {
+ return type;
+ }
+ if (type === 'unsupported_source') {
+ return 'unavailable_selection';
+ }
+ return 'error';
}
/**
@@ -375,10 +391,15 @@ export function createLinkedInstructionsResolver(
};
}
- let fetched: ResolvedPrompt;
+ let fetched: NativeResolvedPrompt;
try {
const result = await runBounded(
- promptService.resolvePrompt({ groupId: link.groupId, selection: link.selection, filters }),
+ promptService.resolvePrompt({
+ groupId: link.groupId,
+ selection: link.selection,
+ filters,
+ allowedSources: ['native'],
+ }),
remainingMs(deadline),
signal,
);
@@ -386,6 +407,12 @@ export function createLinkedInstructionsResolver(
if (!result.ok) {
return { status: 'unavailable', reason: mapServiceErrorReason(result.error.type) };
}
+ if (result.value.source !== 'native') {
+ /* allowedSources: ['native'] above means the service only ever resolves
+ * a native group here; this check narrows the type for the compiler
+ * and cannot be reached at runtime. */
+ return { status: 'unavailable', reason: 'error' };
+ }
fetched = result.value;
} catch (error) {
signal?.throwIfAborted();
diff --git a/packages/api/src/app/checks.spec.ts b/packages/api/src/app/checks.spec.ts
index 3f2d5e3775..c51cbe228f 100644
--- a/packages/api/src/app/checks.spec.ts
+++ b/packages/api/src/app/checks.spec.ts
@@ -389,4 +389,16 @@ describe('handleRateLimits', () => {
expect(process.env.AGENT_EVENT_USER_MAX).toEqual('80');
expect(process.env.AGENT_EVENT_USER_WINDOW).toEqual('2');
});
+
+ it('should set the prompt resolve rate limit', () => {
+ handleRateLimits({
+ promptResolve: {
+ userMax: 30,
+ userWindowInMinutes: 2,
+ },
+ });
+
+ expect(process.env.PROMPT_RESOLVE_USER_MAX).toEqual('30');
+ expect(process.env.PROMPT_RESOLVE_USER_WINDOW).toEqual('2');
+ });
});
diff --git a/packages/api/src/app/limits.ts b/packages/api/src/app/limits.ts
index d50fd6fc84..3de482efe2 100644
--- a/packages/api/src/app/limits.ts
+++ b/packages/api/src/app/limits.ts
@@ -12,6 +12,7 @@ export const handleRateLimits = (rateLimits?: TCustomConfig['rateLimits']): void
const rateLimitKeys = {
agentEvents: 'AGENT_EVENT',
+ promptResolve: 'PROMPT_RESOLVE',
fileUploads: RateLimitPrefix.FILE_UPLOAD,
conversationsImport: RateLimitPrefix.IMPORT,
tts: RateLimitPrefix.TTS,
diff --git a/packages/api/src/langfuse/destinations.spec.ts b/packages/api/src/langfuse/destinations.spec.ts
new file mode 100644
index 0000000000..75749837e3
--- /dev/null
+++ b/packages/api/src/langfuse/destinations.spec.ts
@@ -0,0 +1,343 @@
+process.env.CREDS_KEY =
+ process.env.CREDS_KEY ?? '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+
+const langfuseEnvKeys = [
+ 'LANGFUSE_PUBLIC_KEY',
+ 'LANGFUSE_SECRET_KEY',
+ 'LANGFUSE_PROJECT_ID',
+ 'LANGFUSE_BASE_URL',
+ 'LANGFUSE_HOST',
+ 'LANGFUSE_BASEURL',
+];
+
+function clearLangfuseEnv() {
+ for (const key of langfuseEnvKeys) {
+ delete process.env[key];
+ }
+}
+
+// Cleared before the module graph loads: another spec file running earlier in
+// this worker may have left Langfuse env vars set, and `./destinations` reads
+// them at import time for its own warm-up lookup.
+clearLangfuseEnv();
+
+jest.mock(
+ '@librechat/data-schemas',
+ () => ({
+ logger: { debug: jest.fn(), error: jest.fn(), warn: jest.fn(), info: jest.fn() },
+ }),
+ { virtual: true },
+);
+
+let fetchMock: jest.SpiedFunction<typeof fetch>;
+
+/** A fresh module instance per test, so each test's project-id cache (keyed by
+ * base URL and credentials) starts empty instead of reusing another test's
+ * resolved id or retry window. */
+async function loadDestinations(): Promise<typeof import('./destinations')> {
+ jest.resetModules();
+ return import('./destinations');
+}
+
+function timeoutError(): Error {
+ const error = new Error('The operation was aborted due to timeout');
+ error.name = 'TimeoutError';
+ return error;
+}
+
+describe('resolveCentralProjectIdOutcome', () => {
+ beforeEach(() => {
+ clearLangfuseEnv();
+ fetchMock = jest.spyOn(global, 'fetch');
+ });
+
+ afterEach(() => {
+ clearLangfuseEnv();
+ jest.restoreAllMocks();
+ });
+
+ it('uses the default project-lookup timeout when no timeoutMs is given', async () => {
+ const { resolveCentralProjectIdOutcome } = await loadDestinations();
+ const timeoutSpy = jest.spyOn(AbortSignal, 'timeout');
+ fetchMock.mockResolvedValue(
+ new Response(JSON.stringify({ data: [{ id: 'project-default-timeout' }] }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ }),
+ );
+
+ await resolveCentralProjectIdOutcome(
+ 'https://cloud.langfuse.com',
+ 'public-key',
+ 'secret-key',
+ true,
+ );
+
+ expect(timeoutSpy).toHaveBeenCalledWith(10_000);
+ });
+
+ it('reports a lookup timeout as timedOut, distinct from any other failure', async () => {
+ const { resolveCentralProjectIdOutcome } = await loadDestinations();
+ fetchMock.mockRejectedValue(timeoutError());
+
+ await expect(
+ resolveCentralProjectIdOutcome(
+ 'https://cloud.langfuse.com',
+ 'public-key',
+ 'secret-key',
+ true,
+ undefined,
+ 50,
+ ),
+ ).resolves.toEqual({ ok: false, timedOut: true });
+ });
+
+ it('reports a non-200 response as a failure that is not a timeout', async () => {
+ const { resolveCentralProjectIdOutcome } = await loadDestinations();
+ fetchMock.mockResolvedValue(new Response(null, { status: 503 }));
+
+ await expect(
+ resolveCentralProjectIdOutcome(
+ 'https://cloud.langfuse.com',
+ 'public-key',
+ 'secret-key',
+ true,
+ undefined,
+ 50,
+ ),
+ ).resolves.toEqual({ ok: false, timedOut: false });
+ });
+
+ it('reports a network error that is not a timeout as not timed out', async () => {
+ const { resolveCentralProjectIdOutcome } = await loadDestinations();
+ fetchMock.mockRejectedValue(new Error('socket hang up'));
+
+ await expect(
+ resolveCentralProjectIdOutcome(
+ 'https://cloud.langfuse.com',
+ 'public-key',
+ 'secret-key',
+ true,
+ undefined,
+ 50,
+ ),
+ ).resolves.toEqual({ ok: false, timedOut: false });
+ });
+
+ it('resolves immediately from a pinned LANGFUSE_PROJECT_ID without a network call', async () => {
+ process.env.LANGFUSE_PROJECT_ID = 'pinned-project';
+ const { resolveCentralProjectIdOutcome } = await loadDestinations();
+
+ await expect(
+ resolveCentralProjectIdOutcome(
+ 'https://cloud.langfuse.com',
+ 'public-key',
+ 'secret-key',
+ true,
+ ),
+ ).resolves.toEqual({ ok: true, projectId: 'pinned-project' });
+ expect(fetchMock).not.toHaveBeenCalled();
+ });
+
+ it('starts the shared fetch with the deployment timeout even when the only caller passes a shorter one', async () => {
+ const { resolveCentralProjectIdOutcome } = await loadDestinations();
+ const timeoutSpy = jest.spyOn(AbortSignal, 'timeout');
+ fetchMock.mockResolvedValue(
+ new Response(JSON.stringify({ data: [{ id: 'project-short-caller' }] }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ }),
+ );
+
+ await resolveCentralProjectIdOutcome(
+ 'https://cloud.langfuse.com',
+ 'public-key',
+ 'secret-key',
+ true,
+ undefined,
+ 50,
+ );
+
+ // The fetch itself always uses the 10 s deployment-wide timeout; `50` only
+ // bounded this call's own wait on it, below.
+ expect(timeoutSpy).toHaveBeenCalledWith(10_000);
+ });
+
+ it('shares one fetch between a short- and a long-timeout caller: the short caller times out without touching the cache, the long caller still gets the id', async () => {
+ const { resolveCentralProjectIdOutcome } = await loadDestinations();
+ let resolveFetch!: (value: Response) => void;
+ fetchMock.mockImplementation(
+ () =>
+ new Promise<Response>((resolve) => {
+ resolveFetch = resolve;
+ }),
+ );
+
+ const shortCall = resolveCentralProjectIdOutcome(
+ 'https://cloud.langfuse.com',
+ 'public-key',
+ 'secret-key',
+ true,
+ undefined,
+ 20,
+ );
+ const longCall = resolveCentralProjectIdOutcome(
+ 'https://cloud.langfuse.com',
+ 'public-key',
+ 'secret-key',
+ true,
+ undefined,
+ 5_000,
+ );
+
+ await expect(shortCall).resolves.toEqual({ ok: false, timedOut: true });
+
+ resolveFetch(
+ new Response(JSON.stringify({ data: [{ id: 'shared-project' }] }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ }),
+ );
+
+ await expect(longCall).resolves.toEqual({ ok: true, projectId: 'shared-project' });
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+
+ // The short caller's timeout never touched the cache: the resolved id is
+ // served from it without a second fetch.
+ await expect(
+ resolveCentralProjectIdOutcome(
+ 'https://cloud.langfuse.com',
+ 'public-key',
+ 'secret-key',
+ true,
+ ),
+ ).resolves.toEqual({ ok: true, projectId: 'shared-project' });
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ });
+
+ it('leaves the score path unaffected by a shorter prompt-sync caller sharing the same fetch', async () => {
+ const { resolveCentralProjectIdOutcome, resolveCentralProjectId } = await loadDestinations();
+ let resolveFetch!: (value: Response) => void;
+ fetchMock.mockImplementation(
+ () =>
+ new Promise<Response>((resolve) => {
+ resolveFetch = resolve;
+ }),
+ );
+
+ const promptSyncCall = resolveCentralProjectIdOutcome(
+ 'https://cloud.langfuse.com',
+ 'public-key',
+ 'secret-key',
+ true,
+ undefined,
+ 20,
+ );
+ const scorePathCall = resolveCentralProjectId(
+ 'https://cloud.langfuse.com',
+ 'public-key',
+ 'secret-key',
+ true,
+ );
+
+ await expect(promptSyncCall).resolves.toEqual({ ok: false, timedOut: true });
+
+ resolveFetch(
+ new Response(JSON.stringify({ data: [{ id: 'score-project' }] }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ }),
+ );
+
+ await expect(scorePathCall).resolves.toBe('score-project');
+ });
+
+ it('reports timedOut inside the retry window a timeout opened', async () => {
+ const { resolveCentralProjectIdOutcome } = await loadDestinations();
+ fetchMock.mockRejectedValue(timeoutError());
+
+ await expect(
+ resolveCentralProjectIdOutcome(
+ 'https://cloud.langfuse.com',
+ 'public-key',
+ 'secret-key',
+ true,
+ undefined,
+ 50,
+ ),
+ ).resolves.toEqual({ ok: false, timedOut: true });
+
+ fetchMock.mockClear();
+ await expect(
+ resolveCentralProjectIdOutcome(
+ 'https://cloud.langfuse.com',
+ 'public-key',
+ 'secret-key',
+ true,
+ ),
+ ).resolves.toEqual({ ok: false, timedOut: true });
+ expect(fetchMock).not.toHaveBeenCalled();
+ });
+
+ it('reports not timedOut inside the retry window a non-timeout failure opened', async () => {
+ const { resolveCentralProjectIdOutcome } = await loadDestinations();
+ fetchMock.mockResolvedValue(new Response(null, { status: 503 }));
+
+ await expect(
+ resolveCentralProjectIdOutcome(
+ 'https://cloud.langfuse.com',
+ 'public-key',
+ 'secret-key',
+ true,
+ ),
+ ).resolves.toEqual({ ok: false, timedOut: false });
+
+ fetchMock.mockClear();
+ await expect(
+ resolveCentralProjectIdOutcome(
+ 'https://cloud.langfuse.com',
+ 'public-key',
+ 'secret-key',
+ true,
+ ),
+ ).resolves.toEqual({ ok: false, timedOut: false });
+ expect(fetchMock).not.toHaveBeenCalled();
+ });
+});
+
+describe('resolveCentralProjectId', () => {
+ beforeEach(() => {
+ clearLangfuseEnv();
+ fetchMock = jest.spyOn(global, 'fetch');
+ });
+
+ afterEach(() => {
+ clearLangfuseEnv();
+ jest.restoreAllMocks();
+ });
+
+ it('always uses the default project-lookup timeout, collapsing a timeout to undefined like any other failure', async () => {
+ const { resolveCentralProjectId } = await loadDestinations();
+ const timeoutSpy = jest.spyOn(AbortSignal, 'timeout');
+ fetchMock.mockRejectedValue(timeoutError());
+
+ await expect(
+ resolveCentralProjectId('https://cloud.langfuse.com', 'public-key', 'secret-key', true),
+ ).resolves.toBeUndefined();
+ expect(timeoutSpy).toHaveBeenCalledWith(10_000);
+ });
+
+ it('returns the resolved project id on success', async () => {
+ const { resolveCentralProjectId } = await loadDestinations();
+ fetchMock.mockResolvedValue(
+ new Response(JSON.stringify({ data: [{ id: 'project-via-wrapper' }] }), {
+ status: 200,
+ headers: { 'Content-Type': 'application/json' },
+ }),
+ );
+
+ await expect(
+ resolveCentralProjectId('https://cloud.langfuse.com', 'public-key', 'secret-key', true),
+ ).resolves.toBe('project-via-wrapper');
+ });
+});
diff --git a/packages/api/src/langfuse/destinations.ts b/packages/api/src/langfuse/destinations.ts
index f1c40fa110..97b118ef65 100644
--- a/packages/api/src/langfuse/destinations.ts
+++ b/packages/api/src/langfuse/destinations.ts
@@ -10,6 +10,7 @@ import {
usesLangfuseMultiTenantRouting,
} from './policy';
import {
+ isTimeout,
normalizeBoolean,
redirectPolicyFor,
resolveLangfuseHeaders,
@@ -28,13 +29,45 @@ import { traceIdForMessage } from './trace';
const DEFAULT_BASE_URL = 'https://cloud.langfuse.com';
const PROJECT_LOOKUP_TIMEOUT_MS = 10_000;
const PROJECT_LOOKUP_RETRY_MS = 30_000;
+
+/** Tells a lookup timeout apart from any other failure (a non-200 response, an
+ * unparsable body, or a network error other than the deadline firing), so a
+ * caller that needs to can report the two differently. */
+export type CentralProjectIdLookupOutcome =
+ | { ok: true; projectId: string }
+ | { ok: false; timedOut: boolean };
+
type CentralProjectIdCacheEntry = {
projectId?: string;
- lookup?: Promise<string | undefined>;
+ lookup?: Promise<CentralProjectIdLookupOutcome>;
retryAt: number;
+ /** Why the lookup that opened the current retry window failed, so a caller
+ * hitting the window reports `timedOut` consistently with that failure
+ * instead of always reporting `false`. */
+ retryReason?: 'timeout' | 'other';
};
const centralProjectIdCache = new Map<string, CentralProjectIdCacheEntry>();
+/** Waits for the shared `lookup` for at most `timeoutMs`, without affecting the
+ * lookup itself: the local timer only decides what this call returns, and is
+ * always cleared, so the lookup keeps running — and still updates the cache
+ * entry and retry window on completion — for any other caller still waiting
+ * on it. */
+async function waitWithTimeout(
+ lookup: Promise<CentralProjectIdLookupOutcome>,
+ timeoutMs: number,
+): Promise<CentralProjectIdLookupOutcome> {
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const localTimeout = new Promise<CentralProjectIdLookupOutcome>((resolve) => {
+ timer = setTimeout(() => resolve({ ok: false, timedOut: true }), timeoutMs);
+ });
+ try {
+ return await Promise.race([lookup, localTimeout]);
+ } finally {
+ clearTimeout(timer);
+ }
+}
+
export type LangfuseScoreDestination = {
id?: string;
name: 'central' | 'tenant' | 'connection';
@@ -93,16 +126,35 @@ export function getCentralEnvBaseUrl(): string {
);
}
-async function resolveCentralProjectId(
+/**
+ * The deployment's own Langfuse project id for its env credentials, cached and
+ * looked up at most once per retry window. `waitForLookup` awaits an in-flight
+ * lookup instead of returning a not-ok outcome while it resolves, for a caller
+ * that needs a definitive answer rather than best-effort warm cache data.
+ * The underlying fetch always runs with the deployment-wide
+ * `PROJECT_LOOKUP_TIMEOUT_MS`, and owns the cache entry and retry window exactly
+ * as if `timeoutMs` were never passed. `timeoutMs` only bounds how long this
+ * call itself waits for that shared fetch: when it elapses first, this call
+ * returns `{ ok: false, timedOut: true }` without touching the cache entry or
+ * retry window, and the shared fetch keeps running for any other waiter. A
+ * lookup that genuinely fails inside the shared fetch — rather than this call
+ * giving up on waiting for it — keeps reporting `timedOut` from that real
+ * failure. A caller inside the retry window gets the reason recorded by the
+ * failure that opened it. The outcome tells a lookup timeout apart from any
+ * other failure, which `resolveCentralProjectId` collapses for callers that
+ * only need the resolved id.
+ */
+export async function resolveCentralProjectIdOutcome(
baseUrl: string,
publicKey: string,
secretKey: string,
waitForLookup: boolean,
headers?: Record<string, string>,
-): Promise<string | undefined> {
+ timeoutMs: number = PROJECT_LOOKUP_TIMEOUT_MS,
+): Promise<CentralProjectIdLookupOutcome> {
const configuredProjectId = normalizeString(process.env.LANGFUSE_PROJECT_ID);
if (configuredProjectId) {
- return configuredProjectId;
+ return { ok: true, projectId: configuredProjectId };
}
/** Headers participate in the key so the header-less module warm-up below
@@ -114,16 +166,20 @@ async function resolveCentralProjectId(
const cached = centralProjectIdCache.get(cacheKey) ?? { retryAt: 0 };
centralProjectIdCache.set(cacheKey, cached);
if (cached.projectId) {
- return cached.projectId;
+ return { ok: true, projectId: cached.projectId };
}
if (!cached.lookup && Date.now() >= cached.retryAt) {
- cached.lookup = (async () => {
+ cached.lookup = (async (): Promise<CentralProjectIdLookupOutcome> => {
try {
const response = await fetch(`${baseUrl}/api/public/projects`, {
headers: mergeHeaders(headers, {
Authorization: toBasicAuthorization(publicKey, secretKey),
}),
+ // Always the deployment-wide timeout: this lookup is shared by every
+ // caller's cache entry, so it must not inherit the budget of whichever
+ // caller happened to start it. A caller-specific bound is applied only
+ // to that caller's own wait, below.
signal: AbortSignal.timeout(PROJECT_LOOKUP_TIMEOUT_MS),
...redirectPolicyFor(headers),
});
@@ -131,7 +187,7 @@ async function resolveCentralProjectId(
logger.warn(
`[langfuse] Could not resolve central project identity: Langfuse responded with ${response.status}`,
);
- return undefined;
+ return { ok: false, timedOut: false };
}
const projects: unknown = await response.json();
@@ -147,25 +203,56 @@ async function resolveCentralProjectId(
logger.warn(
'[langfuse] Could not resolve central project identity from Langfuse response',
);
- return undefined;
+ return { ok: false, timedOut: false };
}
- return projectId;
+ return { ok: true, projectId };
} catch (error) {
logger.warn('[langfuse] Could not resolve central project identity:', error);
- return undefined;
+ return { ok: false, timedOut: isTimeout(error) };
}
- })().then((projectId) => {
+ })().then((outcome) => {
cached.lookup = undefined;
- if (projectId) {
- cached.projectId = projectId;
+ if (outcome.ok) {
+ cached.projectId = outcome.projectId;
} else {
cached.retryAt = Date.now() + PROJECT_LOOKUP_RETRY_MS;
+ cached.retryReason = outcome.timedOut ? 'timeout' : 'other';
}
- return projectId;
+ return outcome;
});
}
- return waitForLookup && cached.lookup ? cached.lookup : undefined;
+ if (!cached.lookup) {
+ // Inside the retry window a prior failure opened: report the reason that
+ // failure recorded instead of always reporting `timedOut: false`, so
+ // `/resolve` keeps mapping a timeout to 504 for the whole window.
+ return { ok: false, timedOut: cached.retryReason === 'timeout' };
+ }
+ if (!waitForLookup) {
+ return { ok: false, timedOut: false };
+ }
+ return waitWithTimeout(cached.lookup, timeoutMs);
+}
+
+/**
+ * The string-or-undefined view of {@link resolveCentralProjectIdOutcome} for callers that
+ * only need the resolved id and always use the default lookup timeout.
+ */
+export async function resolveCentralProjectId(
+ baseUrl: string,
+ publicKey: string,
+ secretKey: string,
+ waitForLookup: boolean,
+ headers?: Record<string, string>,
+): Promise<string | undefined> {
+ const outcome = await resolveCentralProjectIdOutcome(
+ baseUrl,
+ publicKey,
+ secretKey,
+ waitForLookup,
+ headers,
+ );
+ return outcome.ok ? outcome.projectId : undefined;
}
async function getCentralScoreDestination(
diff --git a/packages/api/src/langfuse/promptSync.spec.ts b/packages/api/src/langfuse/promptSync.spec.ts
new file mode 100644
index 0000000000..3df1d6f3a6
--- /dev/null
+++ b/packages/api/src/langfuse/promptSync.spec.ts
@@ -0,0 +1,659 @@
+jest.mock('~/admin/secrets', () => ({
+ decryptConfigSecret: jest.fn((value: string) =>
+ value === 'v3:test:tenant-secret-key' ? 'tenant-secret-key' : undefined,
+ ),
+}));
+
+import { tenantStorage } from '@librechat/data-schemas';
+import type { AppConfig, IConfig } from '@librechat/data-schemas';
+import type { TCustomConfig } from 'librechat-data-provider';
+import type { LangfuseSourceGroup } from './promptSync';
+import {
+ readStoredLangfuse,
+ buildPromptSyncConnection,
+ toLangfusePromptErrorResponse,
+ getPromptSyncSourceIdentity,
+ createLangfuseSourceResolver,
+} from './promptSync';
+import { LangfusePromptRequestError } from './prompts';
+
+const langfuseEnvKeys = [
+ 'LANGFUSE_PUBLIC_KEY',
+ 'LANGFUSE_SECRET_KEY',
+ 'LANGFUSE_PROJECT_ID',
+ 'LANGFUSE_BASE_URL',
+ 'LANGFUSE_HOST',
+ 'LANGFUSE_BASEURL',
+ 'LANGFUSE_FANOUT_ENABLED',
+ 'LANGFUSE_FANOUT_COLLECTOR_URL',
+ 'LANGFUSE_FANOUT_TENANT_DESTINATIONS',
+ 'LANGFUSE_FANOUT_TENANT_EU_BASE_URL',
+ 'LANGFUSE_FANOUT_TENANT_US_BASE_URL',
+ 'LANGFUSE_FANOUT_TENANT_JP_BASE_URL',
+ 'TENANT_ISOLATION_STRICT',
+ 'LANGFUSE_PROMPT_SYNC_AVAILABLE',
+];
+
+function clearLangfuseEnv() {
+ for (const key of langfuseEnvKeys) {
+ delete process.env[key];
+ }
+}
+
+beforeEach(() => {
+ clearLangfuseEnv();
+});
+
+function baseConfigDoc(langfuse: Record<string, unknown> | undefined): IConfig {
+ return { overrides: langfuse !== undefined ? { langfuse } : {} } as IConfig;
+}
+
+function appConfigWithLangfuse(langfuse?: AppConfig['langfuse']): AppConfig {
+ return { langfuse } as AppConfig;
+}
+
+/** A tenant connection valid enough for `resolveLangfusePromptConnection` to
+ * resolve, with a recorded source identity. */
+function tenantStoredConfig(overrides: Record<string, unknown> = {}): TCustomConfig['langfuse'] {
+ return {
+ publicKey: 'tenant-public-key',
+ secretKey: 'v3:test:tenant-secret-key',
+ destination: 'us',
+ projectId: 'tenant-project-1',
+ promptSync: { enabled: true },
+ ...overrides,
+ };
+}
+
+describe('readStoredLangfuse', () => {
+ it('returns undefined for a missing config', () => {
+ expect(readStoredLangfuse(null)).toBeUndefined();
+ });
+
+ it('reads the langfuse section from the stored override tree', () => {
+ const stored = { destination: 'us', promptSync: { enabled: true } };
+ expect(readStoredLangfuse(baseConfigDoc(stored))).toEqual(stored);
+ });
+});
+
+describe('toLangfusePromptErrorResponse', () => {
+ it('maps timeout to 504', () => {
+ const error = new LangfusePromptRequestError('timeout', 'Langfuse did not respond in time');
+ expect(toLangfusePromptErrorResponse(error)).toEqual({
+ status: 504,
+ body: { code: 'timeout' },
+ });
+ });
+
+ it.each(['unauthorized', 'upstream', 'invalid_response'] as const)('maps %s to 502', (code) => {
+ const error = new LangfusePromptRequestError(code, 'failed');
+ expect(toLangfusePromptErrorResponse(error).status).toBe(502);
+ });
+
+ it('includes the upstream status in the body, never a 401/403 passthrough', () => {
+ const error = new LangfusePromptRequestError('upstream', 'Langfuse responded with 409', 409);
+ expect(toLangfusePromptErrorResponse(error)).toEqual({
+ status: 502,
+ body: { code: 'upstream', status: 409 },
+ });
+ });
+
+ it('omits status when the error carries none', () => {
+ const error = new LangfusePromptRequestError('invalid_response', 'bad body');
+ expect(toLangfusePromptErrorResponse(error)).toEqual({
+ status: 502,
+ body: { code: 'invalid_response' },
+ });
+ });
+});
+
+describe('buildPromptSyncConnection', () => {
+ it.each(['publicKey', 'secretKey', 'destination'] as const)(
+ 'does not restore a deleted %s from cached config',
+ (field) => {
+ const appConfig = appConfigWithLangfuse(tenantStoredConfig() as AppConfig['langfuse']);
+ const stored = { ...tenantStoredConfig() };
+ delete stored[field];
+
+ expect(buildPromptSyncConnection(appConfig, stored, 'tenant-a')).toBeNull();
+ },
+ );
+
+ it('returns null when the stored config has no usable credentials', () => {
+ expect(
+ buildPromptSyncConnection(undefined, { promptSync: { enabled: true } }, undefined),
+ ).toBeNull();
+ });
+
+ it('builds the connection from the stored destination and keys', () => {
+ const connection = buildPromptSyncConnection(undefined, tenantStoredConfig(), 'tenant-a');
+ expect(connection).toEqual({
+ baseUrl: 'https://us.cloud.langfuse.com',
+ authorization: `Basic ${Buffer.from('tenant-public-key:tenant-secret-key').toString('base64')}`,
+ });
+ });
+
+ it('carries the yaml headers from appConfig, scoped to the one configured destination', () => {
+ process.env.LANGFUSE_FANOUT_TENANT_US_BASE_URL = 'https://us.cloud.langfuse.com';
+ const appConfig = appConfigWithLangfuse({ headers: { 'X-Gateway-Token': 'abc' } });
+
+ const connection = buildPromptSyncConnection(appConfig, tenantStoredConfig(), 'tenant-a');
+
+ expect(connection?.headers).toEqual({ 'X-Gateway-Token': 'abc' });
+ });
+});
+
+describe('buildPromptSyncConnection and getPromptSyncSourceIdentity', () => {
+ it('read the same merged config, so a stale appConfig value never outvotes the stored one', async () => {
+ const appConfig = appConfigWithLangfuse({
+ destination: 'eu',
+ projectId: 'stale-project',
+ } as AppConfig['langfuse']);
+ const stored = tenantStoredConfig();
+
+ const connection = buildPromptSyncConnection(appConfig, stored, 'tenant-a');
+ const identity = await getPromptSyncSourceIdentity(appConfig, stored, 'tenant-a');
+
+ expect(connection).toEqual({
+ baseUrl: 'https://us.cloud.langfuse.com',
+ authorization: `Basic ${Buffer.from('tenant-public-key:tenant-secret-key').toString('base64')}`,
+ });
+ expect(identity).toEqual({ destination: 'us', projectId: 'tenant-project-1' });
+ });
+});
+
+describe('getPromptSyncSourceIdentity', () => {
+ it.each(['destination', 'projectId'] as const)(
+ 'does not restore a deleted %s from cached config',
+ async (field) => {
+ const appConfig = appConfigWithLangfuse(tenantStoredConfig() as AppConfig['langfuse']);
+ const stored = { ...tenantStoredConfig() };
+ delete stored[field];
+
+ await expect(getPromptSyncSourceIdentity(appConfig, stored, 'tenant-a')).resolves.toBeNull();
+ },
+ );
+
+ it('returns the stored tenant destination and project id', async () => {
+ await expect(
+ getPromptSyncSourceIdentity(undefined, tenantStoredConfig(), 'tenant-a'),
+ ).resolves.toEqual({
+ destination: 'us',
+ projectId: 'tenant-project-1',
+ });
+ });
+
+ it('normalizes the stored destination instead of returning the raw string', async () => {
+ await expect(
+ getPromptSyncSourceIdentity(undefined, tenantStoredConfig({ destination: 'US' }), 'tenant-a'),
+ ).resolves.toEqual({
+ destination: 'us',
+ projectId: 'tenant-project-1',
+ });
+ });
+
+ it('resolves the env project id for central-env mode, without a network call when it is pinned', async () => {
+ process.env.LANGFUSE_PUBLIC_KEY = 'env-public';
+ process.env.LANGFUSE_SECRET_KEY = 'env-secret';
+ process.env.LANGFUSE_PROJECT_ID = 'central-project-1';
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ await expect(
+ getPromptSyncSourceIdentity(undefined, { promptSync: { enabled: true } }, undefined),
+ ).resolves.toEqual({
+ destination: 'env',
+ projectId: 'central-project-1',
+ });
+ expect(fetchSpy).not.toHaveBeenCalled();
+ });
+
+ it('resolves the env project id over the network, scoping the appConfig headers to the lookup', async () => {
+ process.env.LANGFUSE_BASE_URL = 'http://central-langfuse:3000';
+ process.env.LANGFUSE_PUBLIC_KEY = 'env-public';
+ process.env.LANGFUSE_SECRET_KEY = 'env-secret';
+ const fetchSpy = jest.spyOn(global, 'fetch').mockResolvedValue({
+ ok: true,
+ json: async () => ({ data: [{ id: 'central-project-2' }] }),
+ } as unknown as Response);
+ const appConfig = appConfigWithLangfuse({ headers: { 'X-Gateway-Token': 'abc' } });
+
+ await expect(
+ getPromptSyncSourceIdentity(appConfig, { promptSync: { enabled: true } }, undefined),
+ ).resolves.toEqual({
+ destination: 'env',
+ projectId: 'central-project-2',
+ });
+ const [, init] = fetchSpy.mock.calls[0];
+ expect((init as RequestInit).headers).toMatchObject({ 'X-Gateway-Token': 'abc' });
+ });
+
+ it('throws instead of returning an identity with no project id when the lookup fails', async () => {
+ process.env.LANGFUSE_PUBLIC_KEY = 'env-public';
+ process.env.LANGFUSE_SECRET_KEY = 'env-secret';
+ jest.spyOn(global, 'fetch').mockResolvedValue({ ok: false, status: 500 } as Response);
+
+ await expect(
+ getPromptSyncSourceIdentity(undefined, { promptSync: { enabled: true } }, undefined),
+ ).rejects.toBeInstanceOf(LangfusePromptRequestError);
+ });
+
+ it('throws a timeout error, not upstream, when the lookup itself times out', async () => {
+ process.env.LANGFUSE_PUBLIC_KEY = 'env-public-timeout';
+ process.env.LANGFUSE_SECRET_KEY = 'env-secret-timeout';
+ const timeout = new Error('The operation was aborted due to timeout');
+ timeout.name = 'TimeoutError';
+ jest.spyOn(global, 'fetch').mockRejectedValue(timeout);
+
+ const error: unknown = await getPromptSyncSourceIdentity(
+ undefined,
+ { promptSync: { enabled: true } },
+ undefined,
+ 50,
+ ).catch((caught: unknown) => caught);
+
+ expect(error).toBeInstanceOf(LangfusePromptRequestError);
+ expect((error as LangfusePromptRequestError).code).toBe('timeout');
+ });
+
+ it('throws upstream, not timeout, for a non-timeout lookup failure', async () => {
+ process.env.LANGFUSE_PUBLIC_KEY = 'env-public-upstream';
+ process.env.LANGFUSE_SECRET_KEY = 'env-secret-upstream';
+ jest.spyOn(global, 'fetch').mockResolvedValue({ ok: false, status: 500 } as Response);
+
+ const error: unknown = await getPromptSyncSourceIdentity(
+ undefined,
+ { promptSync: { enabled: true } },
+ undefined,
+ 50,
+ ).catch((caught: unknown) => caught);
+
+ expect(error).toBeInstanceOf(LangfusePromptRequestError);
+ expect((error as LangfusePromptRequestError).code).toBe('upstream');
+ });
+
+ it('bounds this call by the given timeoutMs without shortening the underlying project-lookup fetch', async () => {
+ process.env.LANGFUSE_PUBLIC_KEY = 'env-public-bound';
+ process.env.LANGFUSE_SECRET_KEY = 'env-secret-bound';
+ const timeoutSpy = jest.spyOn(AbortSignal, 'timeout');
+ jest.spyOn(global, 'fetch').mockResolvedValue({
+ ok: true,
+ json: async () => ({ data: [{ id: 'bounded-project' }] }),
+ } as unknown as Response);
+
+ await expect(
+ getPromptSyncSourceIdentity(undefined, { promptSync: { enabled: true } }, undefined, 1_000),
+ ).resolves.toEqual({ destination: 'env', projectId: 'bounded-project' });
+ // The shared fetch always starts with the deployment-wide project-lookup
+ // timeout; the `1_000` above only bounds this call's own wait on it.
+ expect(timeoutSpy).toHaveBeenCalledWith(10_000);
+ });
+
+ it('returns null when the tenant stored config has no project id', async () => {
+ await expect(
+ getPromptSyncSourceIdentity(
+ undefined,
+ tenantStoredConfig({ projectId: undefined }),
+ 'tenant-a',
+ ),
+ ).resolves.toBeNull();
+ });
+
+ it('returns null when the tenant stored config has no destination', async () => {
+ await expect(
+ getPromptSyncSourceIdentity(
+ undefined,
+ tenantStoredConfig({ destination: undefined }),
+ 'tenant-a',
+ ),
+ ).resolves.toBeNull();
+ });
+});
+
+describe('createLangfuseSourceResolver', () => {
+ function createDeps(
+ storedOverrides: Record<string, unknown> = {},
+ langfuseAppConfig?: AppConfig['langfuse'],
+ ) {
+ const findBaseConfig = jest.fn(async () => baseConfigDoc(tenantStoredConfig(storedOverrides)));
+ const getAppConfig = jest.fn(async () => appConfigWithLangfuse(langfuseAppConfig));
+ return { findBaseConfig, getAppConfig };
+ }
+
+ function matchingGroup(overrides: Partial<LangfuseSourceGroup> = {}): LangfuseSourceGroup {
+ return {
+ tenantId: 'tenant-a',
+ sourceDestination: 'us',
+ sourceProjectId: 'tenant-project-1',
+ ...overrides,
+ };
+ }
+
+ async function resolveAsTenant(group: LangfuseSourceGroup, deps: ReturnType<typeof createDeps>) {
+ return tenantStorage.run({ tenantId: group.tenantId }, () =>
+ createLangfuseSourceResolver(deps)(group),
+ );
+ }
+
+ function deferred<T>(): {
+ promise: Promise<T>;
+ resolve: (value: T) => void;
+ reject: (error: unknown) => void;
+ } {
+ let resolveFn!: (value: T) => void;
+ let rejectFn!: (error: unknown) => void;
+ const promise = new Promise<T>((res, rej) => {
+ resolveFn = res;
+ rejectFn = rej;
+ });
+ return { promise, resolve: resolveFn, reject: rejectFn };
+ }
+
+ it('returns disabled when the deployment has not enabled prompt sync at all', async () => {
+ const deps = createDeps();
+
+ const result = await resolveAsTenant(matchingGroup(), deps);
+
+ expect(result).toEqual({ ok: false, reason: 'disabled' });
+ expect(deps.findBaseConfig).not.toHaveBeenCalled();
+ expect(deps.getAppConfig).not.toHaveBeenCalled();
+ });
+
+ it('returns not_configured when the group tenant differs from the active tenant', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ const deps = createDeps();
+
+ const result = await tenantStorage.run({ tenantId: 'tenant-b' }, () =>
+ createLangfuseSourceResolver(deps)(matchingGroup({ tenantId: 'tenant-a' })),
+ );
+
+ expect(result).toEqual({ ok: false, reason: 'not_configured' });
+ expect(deps.findBaseConfig).not.toHaveBeenCalled();
+ });
+
+ it('returns disabled when the tenant has not turned prompt sync on', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ const deps = createDeps({ promptSync: { enabled: false } });
+
+ const result = await resolveAsTenant(matchingGroup(), deps);
+
+ expect(result).toEqual({ ok: false, reason: 'disabled' });
+ // getAppConfig starts concurrently with the stored-config read that finds
+ // prompt sync disabled, so it has already been called by the time this
+ // resolves — its result is simply never used.
+ expect(deps.getAppConfig).toHaveBeenCalledTimes(1);
+ });
+
+ it('returns not_configured when no connection can be built from the stored keys', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ const deps = createDeps({ publicKey: undefined, secretKey: undefined, destination: undefined });
+
+ const result = await resolveAsTenant(matchingGroup(), deps);
+
+ expect(result).toEqual({ ok: false, reason: 'not_configured' });
+ });
+
+ it('returns not_configured when the stored destination has no match, even with usable keys', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ const deps = createDeps({ destination: undefined });
+
+ const result = await resolveAsTenant(matchingGroup(), deps);
+
+ expect(result).toEqual({ ok: false, reason: 'not_configured' });
+ });
+
+ it('returns not_configured when the connection builds but the stored config has no project id', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ const deps = createDeps({ projectId: undefined });
+
+ const result = await resolveAsTenant(matchingGroup(), deps);
+
+ expect(result).toEqual({ ok: false, reason: 'not_configured' });
+ });
+
+ it('returns source_changed when the destination no longer matches', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ const deps = createDeps();
+
+ const result = await resolveAsTenant(matchingGroup({ sourceDestination: 'eu' }), deps);
+
+ expect(result).toEqual({ ok: false, reason: 'source_changed' });
+ });
+
+ it('returns source_changed when the project id no longer matches', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ const deps = createDeps();
+
+ const result = await resolveAsTenant(matchingGroup({ sourceProjectId: 'other-project' }), deps);
+
+ expect(result).toEqual({ ok: false, reason: 'source_changed' });
+ });
+
+ it('returns source_changed when the group has no recorded identity', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ const deps = createDeps();
+
+ const result = await resolveAsTenant(
+ matchingGroup({ sourceDestination: undefined, sourceProjectId: undefined }),
+ deps,
+ );
+
+ expect(result).toEqual({ ok: false, reason: 'source_changed' });
+ });
+
+ it('resolves the connection when the gate, tenant, config and identity all line up', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ const deps = createDeps();
+
+ const result = await resolveAsTenant(matchingGroup(), deps);
+
+ expect(result).toEqual({
+ ok: true,
+ connection: {
+ baseUrl: 'https://us.cloud.langfuse.com',
+ authorization: `Basic ${Buffer.from('tenant-public-key:tenant-secret-key').toString('base64')}`,
+ },
+ });
+ });
+
+ it('builds the connection with the headers getAppConfig supplies', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ process.env.LANGFUSE_FANOUT_TENANT_US_BASE_URL = 'https://us.cloud.langfuse.com';
+ const deps = createDeps({}, { headers: { 'X-Gateway-Token': 'abc' } });
+
+ const result = await resolveAsTenant(matchingGroup(), deps);
+
+ expect(result.ok).toBe(true);
+ expect(result.ok && result.connection.headers).toEqual({ 'X-Gateway-Token': 'abc' });
+ });
+
+ it('resolves a central-env group with no tenantId, matching the env destination and project id', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ process.env.LANGFUSE_PUBLIC_KEY = 'env-public';
+ process.env.LANGFUSE_SECRET_KEY = 'env-secret';
+ process.env.LANGFUSE_PROJECT_ID = 'central-project-1';
+ const findBaseConfig = jest.fn(async () => baseConfigDoc({ promptSync: { enabled: true } }));
+ const getAppConfig = jest.fn(async () => appConfigWithLangfuse(undefined));
+ const group: LangfuseSourceGroup = {
+ tenantId: undefined,
+ sourceDestination: 'env',
+ sourceProjectId: 'central-project-1',
+ };
+
+ const result = await createLangfuseSourceResolver({ findBaseConfig, getAppConfig })(group);
+
+ expect(result).toEqual({
+ ok: true,
+ connection: {
+ baseUrl: 'https://cloud.langfuse.com',
+ authorization: `Basic ${Buffer.from('env-public:env-secret').toString('base64')}`,
+ },
+ });
+ });
+
+ it('uses the env identity, not the stored tenant one, in single-tenant mode with env keys set', async () => {
+ // The connection and the identity must pick the same mode: a single-tenant
+ // deployment with env keys set reads from the env project even though the
+ // admin also stored a tenant destination, so a group recorded against that
+ // stored identity must no longer match.
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ process.env.LANGFUSE_PUBLIC_KEY = 'env-public';
+ process.env.LANGFUSE_SECRET_KEY = 'env-secret';
+ process.env.LANGFUSE_PROJECT_ID = 'central-project-1';
+ const deps = createDeps();
+ const group: LangfuseSourceGroup = {
+ tenantId: undefined,
+ sourceDestination: 'us',
+ sourceProjectId: 'tenant-project-1',
+ };
+
+ const result = await createLangfuseSourceResolver(deps)(group);
+
+ expect(result).toEqual({ ok: false, reason: 'source_changed' });
+ });
+
+ it('propagates a failed env project lookup instead of returning source_changed', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ process.env.LANGFUSE_PUBLIC_KEY = 'env-public';
+ process.env.LANGFUSE_SECRET_KEY = 'env-secret';
+ jest.spyOn(global, 'fetch').mockResolvedValue({ ok: false, status: 500 } as Response);
+ const findBaseConfig = jest.fn(async () => baseConfigDoc({ promptSync: { enabled: true } }));
+ const getAppConfig = jest.fn(async () => appConfigWithLangfuse(undefined));
+ const group: LangfuseSourceGroup = {
+ tenantId: undefined,
+ sourceDestination: 'env',
+ sourceProjectId: 'central-project-1',
+ };
+
+ await expect(
+ createLangfuseSourceResolver({ findBaseConfig, getAppConfig })(group),
+ ).rejects.toBeInstanceOf(LangfusePromptRequestError);
+ });
+
+ it('resolves normally when no getTimeoutMs is injected, against the always-10s project-lookup fetch', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ process.env.LANGFUSE_PUBLIC_KEY = 'env-public-resolver-default';
+ process.env.LANGFUSE_SECRET_KEY = 'env-secret-resolver-default';
+ const timeoutSpy = jest.spyOn(AbortSignal, 'timeout');
+ jest.spyOn(global, 'fetch').mockResolvedValue({
+ ok: true,
+ json: async () => ({ data: [{ id: 'resolver-default-project' }] }),
+ } as unknown as Response);
+ const findBaseConfig = jest.fn(async () => baseConfigDoc({ promptSync: { enabled: true } }));
+ const getAppConfig = jest.fn(async () => appConfigWithLangfuse(undefined));
+ const group: LangfuseSourceGroup = {
+ tenantId: undefined,
+ sourceDestination: 'env',
+ sourceProjectId: 'resolver-default-project',
+ };
+
+ await expect(
+ createLangfuseSourceResolver({ findBaseConfig, getAppConfig })(group),
+ ).resolves.toEqual({ ok: true, connection: expect.anything() });
+
+ // The underlying project-lookup fetch always starts with the fixed
+ // deployment-wide timeout, regardless of what bounds this call's own wait.
+ expect(timeoutSpy).toHaveBeenCalledWith(10_000);
+ });
+
+ it('bounds this call by an injected getTimeoutMs: a fetch slower than that bound reports a timeout', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ process.env.LANGFUSE_PUBLIC_KEY = 'env-public-resolver-custom';
+ process.env.LANGFUSE_SECRET_KEY = 'env-secret-resolver-custom';
+ // Never settles within the test: the injected getTimeoutMs below is what
+ // bounds this call, not the underlying fetch.
+ jest.spyOn(global, 'fetch').mockImplementation(() => new Promise<Response>(() => {}));
+ const findBaseConfig = jest.fn(async () => baseConfigDoc({ promptSync: { enabled: true } }));
+ const getAppConfig = jest.fn(async () => appConfigWithLangfuse(undefined));
+ const group: LangfuseSourceGroup = {
+ tenantId: undefined,
+ sourceDestination: 'env',
+ sourceProjectId: 'resolver-custom-project',
+ };
+
+ const error: unknown = await createLangfuseSourceResolver({
+ findBaseConfig,
+ getAppConfig,
+ getTimeoutMs: () => 20,
+ })(group).catch((caught: unknown) => caught);
+
+ expect(error).toBeInstanceOf(LangfusePromptRequestError);
+ expect((error as LangfusePromptRequestError).code).toBe('timeout');
+ });
+
+ it('starts the base-config and app-config reads together, not one after the other', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ const baseConfigGate = deferred<IConfig | null>();
+ const appConfigGate = deferred<AppConfig>();
+ const findBaseConfig = jest.fn(() => baseConfigGate.promise);
+ const getAppConfig = jest.fn(() => appConfigGate.promise);
+
+ const resultPromise = tenantStorage.run({ tenantId: 'tenant-a' }, () =>
+ createLangfuseSourceResolver({ findBaseConfig, getAppConfig })(matchingGroup()),
+ );
+
+ // Both reads have already started, before either settles.
+ expect(findBaseConfig).toHaveBeenCalledTimes(1);
+ expect(getAppConfig).toHaveBeenCalledTimes(1);
+
+ appConfigGate.resolve(appConfigWithLangfuse(undefined));
+ baseConfigGate.resolve(baseConfigDoc(tenantStoredConfig()));
+
+ await expect(resultPromise).resolves.toEqual({ ok: true, connection: expect.anything() });
+ });
+
+ it('returns disabled with no unhandled rejection when getAppConfig rejects while prompt sync is off', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ const unhandled: unknown[] = [];
+ const onUnhandled = (reason: unknown): void => {
+ unhandled.push(reason);
+ };
+ process.on('unhandledRejection', onUnhandled);
+ try {
+ const findBaseConfig = jest.fn(async () =>
+ baseConfigDoc(tenantStoredConfig({ promptSync: { enabled: false } })),
+ );
+ const getAppConfig = jest.fn(async () => {
+ throw new Error('app config boom');
+ });
+
+ const result = await tenantStorage.run({ tenantId: 'tenant-a' }, () =>
+ createLangfuseSourceResolver({ findBaseConfig, getAppConfig })(matchingGroup()),
+ );
+
+ expect(result).toEqual({ ok: false, reason: 'disabled' });
+
+ await new Promise((resolve) => setTimeout(resolve, 10));
+ expect(unhandled).toHaveLength(0);
+ } finally {
+ process.off('unhandledRejection', onUnhandled);
+ }
+ });
+
+ it('propagates a findBaseConfig rejection', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ const findBaseConfig = jest.fn(async () => {
+ throw new Error('base config boom');
+ });
+ const getAppConfig = jest.fn(async () => appConfigWithLangfuse(undefined));
+
+ await expect(
+ tenantStorage.run({ tenantId: 'tenant-a' }, () =>
+ createLangfuseSourceResolver({ findBaseConfig, getAppConfig })(matchingGroup()),
+ ),
+ ).rejects.toThrow('base config boom');
+ });
+
+ it('propagates a getAppConfig rejection when prompt sync is enabled', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ const findBaseConfig = jest.fn(async () => baseConfigDoc(tenantStoredConfig()));
+ const getAppConfig = jest.fn(async () => {
+ throw new Error('app config boom');
+ });
+
+ await expect(
+ tenantStorage.run({ tenantId: 'tenant-a' }, () =>
+ createLangfuseSourceResolver({ findBaseConfig, getAppConfig })(matchingGroup()),
+ ),
+ ).rejects.toThrow('app config boom');
+ });
+});
diff --git a/packages/api/src/langfuse/promptSync.ts b/packages/api/src/langfuse/promptSync.ts
new file mode 100644
index 0000000000..bdfbe5fb6b
--- /dev/null
+++ b/packages/api/src/langfuse/promptSync.ts
@@ -0,0 +1,251 @@
+import { getTenantId } from '@librechat/data-schemas';
+import type { TCustomConfig, TLangfusePromptErrorBody } from 'librechat-data-provider';
+import type { AppConfig } from '@librechat/data-schemas';
+import type { LangfusePromptConnection, LangfusePromptRequestErrorCode } from './prompts';
+import {
+ resolveLangfusePromptConnection,
+ resolveLangfusePromptMode,
+ LangfusePromptRequestError,
+} from './prompts';
+import {
+ getCentralEnvBaseUrl,
+ resolveCentralProjectIdOutcome,
+ scopeHeadersToDestination,
+} from './destinations';
+import { getLangfusePromptSyncTimeoutMs, isLangfusePromptSyncAvailable } from './policy';
+import { resolveLangfuseTenantDestination } from './tenantDestinations';
+import { resolveLangfuseHeaders } from './utils';
+import { normalizeString } from '~/utils/text';
+
+/** The minimal shape this module needs from a stored base config document —
+ * just its override tree — so this stays a plain structural type instead of
+ * the Mongoose `IConfig` document a caller such as `admin/langfuse.ts` reads
+ * it from. An `IConfig` satisfies this type and still type-checks as a
+ * caller. */
+export type StoredBaseConfig = { overrides?: unknown };
+
+/** Reads from the stored override tree, so this is `TCustomConfig`'s
+ * `DeepPartial` view of the section rather than the standalone
+ * `LangfuseConfig` — record-valued fields carry optional values here. */
+export function readStoredLangfuse(config: StoredBaseConfig | null): TCustomConfig['langfuse'] {
+ const overrides = config?.overrides as Partial<TCustomConfig> | undefined;
+ return overrides?.langfuse;
+}
+
+/** Prompt reads use stored connection fields and deployment proxy headers.
+ * Missing stored fields stay missing even when the request config has cached values. */
+function mergeLangfuseConfig(
+ appConfig: AppConfig | undefined,
+ stored: TCustomConfig['langfuse'],
+): AppConfig {
+ return {
+ ...appConfig,
+ langfuse: { ...stored, headers: appConfig?.langfuse?.headers },
+ } as AppConfig;
+}
+
+export function buildPromptSyncConnection(
+ appConfig: AppConfig | undefined,
+ stored: TCustomConfig['langfuse'],
+ tenantId: string | undefined,
+): LangfusePromptConnection | null {
+ return resolveLangfusePromptConnection(mergeLangfuseConfig(appConfig, stored), { tenantId });
+}
+
+/** HTTP status for a `LangfusePromptRequestError`. A Langfuse `unauthorized`
+ * never maps to 401/403: the LibreChat client treats either as its own
+ * session expiring and reacts by refreshing the token or signing out. */
+function promptRequestErrorStatus(code: LangfusePromptRequestErrorCode): number {
+ return code === 'timeout' ? 504 : 502;
+}
+
+/** Maps a thrown `LangfusePromptRequestError` to the stable `{ status, body }`
+ * contract. Never forwards the upstream body, headers or credentials; the
+ * caller logs only the error's own code/status/message, which `prompts.ts`
+ * guarantees are free of secrets. */
+export function toLangfusePromptErrorResponse(error: LangfusePromptRequestError): {
+ status: number;
+ body: TLangfusePromptErrorBody;
+} {
+ const body: TLangfusePromptErrorBody =
+ error.code === 'upstream' && error.status != null
+ ? { code: error.code, status: error.status }
+ : { code: error.code };
+ return { status: promptRequestErrorStatus(error.code), body };
+}
+
+export type LangfusePromptSyncSourceIdentity = {
+ destination: string;
+ projectId: string;
+};
+
+/**
+ * The complete source identity for a Langfuse-origin prompt group's content read:
+ * the connection's destination key and project id. Returns `null` when the
+ * identity is not configured — tenant mode with no resolvable destination or no
+ * stored project id — rather than an incomplete identity; the resolver maps that
+ * `null` to `{ ok: false, reason: 'not_configured' }`.
+ *
+ * Builds from the same merged config `buildPromptSyncConnection` reads
+ * (`mergeLangfuseConfig`) and picks its branch from the same
+ * `resolveLangfusePromptMode` decision, so the two can never name different
+ * projects for the same request: a tenant connection's identity is its
+ * normalized `destination` key and stored `projectId`. Without tenant
+ * credentials, prompt reads use the deployment's env project instead
+ * (`resolveLangfusePromptConnection` in `./prompts`). `'env'` names that mode,
+ * and its project id is looked up the same way `destinations.ts` resolves one
+ * for env credentials, scoped with the same headers the connection would send —
+ * a network call the first time, which is why this function is async. Env mode
+ * with no usable env credentials throws `LangfusePromptRequestError('upstream')`
+ * rather than returning an incomplete identity, so that case never reads as
+ * `source_changed`. A lookup that cannot resolve a project id throws too, as
+ * `'timeout'` when the lookup itself timed out and `'upstream'` for any other
+ * failure. `timeoutMs` bounds only this call's wait for that lookup — it
+ * defaults to the deployment's 10-second project-lookup timeout, which is too
+ * long for a prompt-sync request — pass `getLangfusePromptSyncTimeoutMs()`, or
+ * inject it the way `createLangfuseSourceResolver` does, so a slow lookup is
+ * reported as `'timeout'` within the prompt-sync budget instead of the longer
+ * one. The identity lookup's wait and the later prompt fetch
+ * (`getLangfuseTextPrompt`) are each bounded by that same prompt-sync timeout,
+ * so the Langfuse part of `/resolve` takes at most about twice that timeout,
+ * plus the config reads around them.
+ */
+export async function getPromptSyncSourceIdentity(
+ appConfig: AppConfig | undefined,
+ stored: TCustomConfig['langfuse'],
+ tenantId: string | undefined,
+ timeoutMs?: number,
+): Promise<LangfusePromptSyncSourceIdentity | null> {
+ const merged = mergeLangfuseConfig(appConfig, stored);
+ if (resolveLangfusePromptMode(tenantId) === 'tenant') {
+ const destination = resolveLangfuseTenantDestination(merged.langfuse?.destination);
+ const projectId = merged.langfuse?.projectId;
+ if (!destination?.key || !projectId) {
+ return null;
+ }
+ return { destination: destination.key, projectId };
+ }
+
+ const publicKey = normalizeString(process.env.LANGFUSE_PUBLIC_KEY);
+ const secretKey = normalizeString(process.env.LANGFUSE_SECRET_KEY);
+ if (!publicKey || !secretKey) {
+ throw new LangfusePromptRequestError(
+ 'upstream',
+ 'Could not resolve the Langfuse project for the env connection',
+ );
+ }
+
+ const baseUrl = getCentralEnvBaseUrl();
+ const headers = scopeHeadersToDestination(
+ resolveLangfuseHeaders(merged.langfuse?.headers),
+ baseUrl,
+ );
+ const outcome = await resolveCentralProjectIdOutcome(
+ baseUrl,
+ publicKey,
+ secretKey,
+ true,
+ headers,
+ timeoutMs,
+ );
+ if (!outcome.ok) {
+ throw new LangfusePromptRequestError(
+ outcome.timedOut ? 'timeout' : 'upstream',
+ outcome.timedOut
+ ? 'Timed out resolving the Langfuse project for the env connection'
+ : 'Could not resolve the Langfuse project for the env connection',
+ );
+ }
+ return { destination: 'env', projectId: outcome.projectId };
+}
+
+export type LangfuseSourceGroup = {
+ tenantId?: string;
+ sourceDestination?: string;
+ sourceProjectId?: string;
+};
+
+export type LangfuseSourceResolution =
+ | { ok: true; connection: LangfusePromptConnection }
+ | { ok: false; reason: 'disabled' | 'not_configured' | 'source_changed' };
+
+export interface CreateLangfuseSourceResolverDeps {
+ findBaseConfig: () => Promise<StoredBaseConfig | null>;
+ getAppConfig: (options?: { tenantId?: string }) => Promise<AppConfig>;
+ /** Bounds the env-mode project lookup inside `getPromptSyncSourceIdentity`.
+ * Defaults to the prompt-sync timeout, so a slow lookup fails as `timeout`
+ * within that budget instead of the longer deployment-wide lookup timeout. */
+ getTimeoutMs?: () => number;
+}
+
+/**
+ * Resolves a Langfuse-origin prompt group to the connection its content read
+ * should use, re-reading the stored config on every call — nothing here is
+ * cached. Checked in order: the deployment gate, the group's tenant against
+ * the active request's tenant, the tenant's own prompt-sync switch, whether a
+ * connection can be built at all, whether a complete source identity can be
+ * resolved for it, and finally whether the group's recorded source identity
+ * still matches the one the connection would read from. The stored base
+ * config and `getAppConfig({ tenantId })` are read concurrently — not series
+ * — because the prompt-sync switch lives only in the stored config: a
+ * disabled tenant returns `{ ok: false, reason: 'disabled' }` without ever
+ * surfacing a `getAppConfig` rejection as an unhandled one.
+ */
+export function createLangfuseSourceResolver({
+ findBaseConfig,
+ getAppConfig,
+ getTimeoutMs = getLangfusePromptSyncTimeoutMs,
+}: CreateLangfuseSourceResolverDeps): (
+ group: LangfuseSourceGroup,
+) => Promise<LangfuseSourceResolution> {
+ return async function resolveLangfuseSource(
+ group: LangfuseSourceGroup,
+ ): Promise<LangfuseSourceResolution> {
+ if (!isLangfusePromptSyncAvailable()) {
+ return { ok: false, reason: 'disabled' };
+ }
+ if (group.tenantId !== getTenantId()) {
+ return { ok: false, reason: 'not_configured' };
+ }
+
+ const [baseConfigResult, appConfigResult] = await Promise.allSettled([
+ findBaseConfig(),
+ getAppConfig({ tenantId: group.tenantId }),
+ ]);
+ if (baseConfigResult.status === 'rejected') {
+ throw baseConfigResult.reason;
+ }
+
+ const stored = readStoredLangfuse(baseConfigResult.value);
+ if (stored?.promptSync?.enabled !== true) {
+ return { ok: false, reason: 'disabled' };
+ }
+ if (appConfigResult.status === 'rejected') {
+ throw appConfigResult.reason;
+ }
+
+ const appConfig = appConfigResult.value;
+ const connection = buildPromptSyncConnection(appConfig, stored, group.tenantId);
+ if (!connection) {
+ return { ok: false, reason: 'not_configured' };
+ }
+
+ const identity = await getPromptSyncSourceIdentity(
+ appConfig,
+ stored,
+ group.tenantId,
+ getTimeoutMs(),
+ );
+ if (!identity) {
+ return { ok: false, reason: 'not_configured' };
+ }
+ const sourceMatches =
+ group.sourceDestination === identity.destination &&
+ group.sourceProjectId === identity.projectId;
+ if (!sourceMatches) {
+ return { ok: false, reason: 'source_changed' };
+ }
+
+ return { ok: true, connection };
+ };
+}
diff --git a/packages/api/src/langfuse/prompts.ts b/packages/api/src/langfuse/prompts.ts
index 89520bad2e..ace4628e43 100644
--- a/packages/api/src/langfuse/prompts.ts
+++ b/packages/api/src/langfuse/prompts.ts
@@ -2,6 +2,7 @@ import { z } from 'zod';
import type { TLangfusePromptListResponse } from 'librechat-data-provider';
import type { AppConfig } from '@librechat/data-schemas';
import {
+ isTimeout,
redirectPolicyFor,
resolveLangfuseHeaders,
resolveTenantCredentials,
@@ -132,30 +133,38 @@ function resolveTenantConnection(
};
}
+export type LangfusePromptMode = 'tenant' | 'env';
+
/**
- * The connection prompt reads use. A request from a tenant user, or any request
- * in multi-tenant mode (`usesLangfuseMultiTenantRouting`), uses only the
+ * Whether a prompt read uses the tenant's own connection or the deployment's
+ * shared env project. A request from a tenant user, or any request in
+ * multi-tenant mode (`usesLangfuseMultiTenantRouting`), always uses the
* tenant's stored connection: prompt reads return data, so a tenant must never
* read the central env project, even while `TENANT_ISOLATION_STRICT` is off.
* Unlike tracing, this does not require `langfuse.enabled` or fanout.
+ *
+ * This is the one place that decision is made. The connection and the source
+ * identity recorded for a group both derive from it, so they can never pick
+ * different projects for the same request.
*/
+export function resolveLangfusePromptMode(tenantId?: string): LangfusePromptMode {
+ if (tenantId || usesLangfuseMultiTenantRouting()) {
+ return 'tenant';
+ }
+ return hasLangfuseEnvCredentials() ? 'env' : 'tenant';
+}
+
+/** The connection prompt reads use. See `resolveLangfusePromptMode` for the mode decision. */
export function resolveLangfusePromptConnection(
appConfig?: AppConfig,
options?: { tenantId?: string },
): LangfusePromptConnection | null {
const headers = resolveLangfuseHeaders(appConfig?.langfuse?.headers);
- if (options?.tenantId || usesLangfuseMultiTenantRouting()) {
- return resolveTenantConnection(appConfig, headers);
- }
- return hasLangfuseEnvCredentials()
+ return resolveLangfusePromptMode(options?.tenantId) === 'env'
? resolveCentralEnvConnection(headers)
: resolveTenantConnection(appConfig, headers);
}
-function isTimeout(error: unknown): boolean {
- return error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError');
-}
-
/** Node's fetch returns a connection to its pool only once the body is consumed or cancelled. */
async function release(response: Response): Promise<void> {
await response.body?.cancel().catch(() => undefined);
diff --git a/packages/api/src/langfuse/utils.ts b/packages/api/src/langfuse/utils.ts
index 1766fe7b5a..785947cb31 100644
--- a/packages/api/src/langfuse/utils.ts
+++ b/packages/api/src/langfuse/utils.ts
@@ -121,6 +121,12 @@ export function toBasicAuthorization(publicKey: string, secretKey: string): stri
return `Basic ${Buffer.from(`${publicKey}:${secretKey}`).toString('base64')}`;
}
+/** True for the error `AbortSignal.timeout` produces when its deadline fires, so a
+ * caller can tell a timed-out request apart from any other request failure. */
+export function isTimeout(error: unknown): boolean {
+ return error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError');
+}
+
/**
* Refuses redirects on requests carrying custom headers.
*
diff --git a/packages/api/src/middleware/index.ts b/packages/api/src/middleware/index.ts
index 80a6c0dfbc..c261e2e11b 100644
--- a/packages/api/src/middleware/index.ts
+++ b/packages/api/src/middleware/index.ts
@@ -33,3 +33,4 @@ export * from './code';
export * from './management';
export * from './twoFactor';
export * from './messageIds';
+export * from './promptResolveLimiter';
diff --git a/packages/api/src/middleware/promptResolveLimiter.spec.ts b/packages/api/src/middleware/promptResolveLimiter.spec.ts
new file mode 100644
index 0000000000..bdaaa34310
--- /dev/null
+++ b/packages/api/src/middleware/promptResolveLimiter.spec.ts
@@ -0,0 +1,75 @@
+import express from 'express';
+import request from 'supertest';
+import type { RequestHandler } from 'express';
+import { createPromptResolveLimiter, windowMsFromMinutes } from './promptResolveLimiter';
+
+jest.mock('~/cache/cacheFactory', () => ({ limiterCache: () => undefined }));
+
+function createApp(limiter: RequestHandler) {
+ const app = express();
+ app.use((req, _res, next) => {
+ Object.assign(req, { user: { id: req.get('x-test-user') } });
+ next();
+ });
+ app.get('/', limiter, (_req, res) => {
+ res.sendStatus(200);
+ });
+ return app;
+}
+
+describe('createPromptResolveLimiter', () => {
+ const originalEnv = process.env;
+
+ beforeEach(() => {
+ process.env = { ...originalEnv };
+ delete process.env.PROMPT_RESOLVE_USER_MAX;
+ delete process.env.PROMPT_RESOLVE_USER_WINDOW;
+ });
+
+ afterEach(() => {
+ process.env = originalEnv;
+ });
+
+ it('defaults to 60 requests per minute per user', async () => {
+ const app = createApp(createPromptResolveLimiter());
+ const response = await request(app).get('/').set('x-test-user', 'default-user').expect(200);
+ expect(response.headers['x-ratelimit-limit']).toBe('60');
+ });
+
+ it('applies a configured override and keeps the original 429 body', async () => {
+ process.env.PROMPT_RESOLVE_USER_MAX = '2';
+ process.env.PROMPT_RESOLVE_USER_WINDOW = '2';
+ const app = createApp(createPromptResolveLimiter());
+ await request(app).get('/').set('x-test-user', 'override-user').expect(200);
+ await request(app).get('/').set('x-test-user', 'override-user').expect(200);
+ const blocked = await request(app).get('/').set('x-test-user', 'override-user').expect(429);
+ expect(blocked.body).toEqual({
+ message: 'Too many prompt resolve requests. Try again later',
+ });
+ });
+
+ it('keys the limit per user', async () => {
+ process.env.PROMPT_RESOLVE_USER_MAX = '1';
+ const app = createApp(createPromptResolveLimiter());
+ await request(app).get('/').set('x-test-user', 'user-a').expect(200);
+ await request(app).get('/').set('x-test-user', 'user-a').expect(429);
+ const otherUser = await request(app).get('/').set('x-test-user', 'user-b').expect(200);
+ expect(otherUser.status).toBe(200);
+ });
+});
+
+describe('windowMsFromMinutes', () => {
+ it('converts a fractional window in minutes to milliseconds, instead of falling back to 1 minute', () => {
+ expect(windowMsFromMinutes('0.5', 1)).toBe(30_000);
+ });
+
+ it('converts a whole number of minutes to milliseconds', () => {
+ expect(windowMsFromMinutes('2', 1)).toBe(120_000);
+ });
+
+ it('falls back to the given minutes for a missing, zero, or negative value', () => {
+ expect(windowMsFromMinutes(undefined, 1)).toBe(60_000);
+ expect(windowMsFromMinutes('0', 1)).toBe(60_000);
+ expect(windowMsFromMinutes('-5', 1)).toBe(60_000);
+ });
+});
diff --git a/packages/api/src/middleware/promptResolveLimiter.ts b/packages/api/src/middleware/promptResolveLimiter.ts
new file mode 100644
index 0000000000..ba67f68889
--- /dev/null
+++ b/packages/api/src/middleware/promptResolveLimiter.ts
@@ -0,0 +1,40 @@
+import { rateLimit } from 'express-rate-limit';
+import type { RequestHandler } from 'express';
+import { limiterCache } from '~/cache/cacheFactory';
+
+type PromptResolveRequest = { user?: { id?: string } };
+
+function positiveInteger(value: string | undefined, fallback: number): number {
+ const parsed = Number(value);
+ return Number.isSafeInteger(parsed) && parsed >= 1 ? parsed : fallback;
+}
+
+/** The window in minutes, converted to milliseconds. `userWindowInMinutes` in the
+ * config schema allows any positive number, not just an integer, so this parses
+ * a fractional value instead of flooring it to the 1-minute fallback. */
+export function windowMsFromMinutes(value: string | undefined, fallbackMinutes: number): number {
+ const parsed = Number(value);
+ const minutes = Number.isFinite(parsed) && parsed > 0 ? parsed : fallbackMinutes;
+ return Math.round(minutes * 60_000);
+}
+
+/**
+ * Builds the per-user limiter for `GET /prompts/groups/:groupId/resolve`.
+ * `librechat.yaml`'s `rateLimits.promptResolve` relays onto
+ * PROMPT_RESOLVE_USER_MAX / PROMPT_RESOLVE_USER_WINDOW at startup (see
+ * `handleRateLimits`), the same way the file upload, import, TTS and STT
+ * limiters pick up their overrides. The caller builds this after that relay
+ * has run. With no override, the defaults below apply: 60 requests per
+ * minute per user.
+ */
+export function createPromptResolveLimiter(): RequestHandler {
+ return rateLimit({
+ windowMs: windowMsFromMinutes(process.env.PROMPT_RESOLVE_USER_WINDOW, 1),
+ max: positiveInteger(process.env.PROMPT_RESOLVE_USER_MAX, 60),
+ keyGenerator: (req) => String((req as PromptResolveRequest).user?.id ?? ''),
+ store: limiterCache('prompt_resolve_limiter'),
+ handler: (_req, res) => {
+ res.status(429).json({ message: 'Too many prompt resolve requests. Try again later' });
+ },
+ });
+}
diff --git a/packages/api/src/prompts/handlers.spec.ts b/packages/api/src/prompts/handlers.spec.ts
index ee11e5e770..405df9d3cd 100644
--- a/packages/api/src/prompts/handlers.spec.ts
+++ b/packages/api/src/prompts/handlers.spec.ts
@@ -2,7 +2,10 @@ import { logger } from '@librechat/data-schemas';
import type { Response } from 'express';
import type { PromptRequest, PromptHandlersDeps } from './handlers';
import type { PromptService } from './service';
+import { contentFilterBlockResponse } from '../middleware/contentFilter';
+import { LangfusePromptRequestError } from '../langfuse/prompts';
import { createPromptHandlers } from './handlers';
+import { PromptStoreError } from './errors';
function mockReq(overrides: Record<string, unknown> = {}): PromptRequest {
return {
@@ -295,6 +298,28 @@ describe('createPromptHandlers linked-instructions cache clearing', () => {
expect(res.statusCode).toBe(200);
expect(invalidateLinkedPrompt).not.toHaveBeenCalled();
});
+
+ it('forwards the group canAccessPromptGroupResource already loaded to savePrompt', async () => {
+ const loadedGroupRecord = { _id: groupId, source: 'native' };
+ const savePrompt = jest.fn().mockResolvedValue({ ok: true, value: { prompt: {} } });
+ const service = makeService({ savePrompt });
+ const handlers = createPromptHandlers(makeDeps({ service }));
+ const res = mockRes();
+
+ await handlers.savePrompt(
+ mockReq({
+ params: { groupId },
+ body: { prompt: { prompt: 'x', type: 'text' } },
+ resourceAccess: { resourceInfo: loadedGroupRecord },
+ }),
+ res,
+ );
+
+ expect(res.statusCode).toBe(200);
+ expect(savePrompt).toHaveBeenCalledWith(
+ expect.objectContaining({ loadedGroup: loadedGroupRecord }),
+ );
+ });
});
describe('cache clear failures', () => {
@@ -445,3 +470,294 @@ describe('createPromptHandlers linked-instructions cache clearing', () => {
});
});
});
+
+describe('createPromptHandlers resolvePrompt', () => {
+ afterEach(() => {
+ jest.restoreAllMocks();
+ });
+
+ function resolveReq(version?: string): PromptRequest {
+ return mockReq({ params: { groupId }, query: version == null ? {} : { version } });
+ }
+
+ it('resolves production when no version is given', async () => {
+ const resolvePrompt = jest.fn().mockResolvedValue({
+ ok: true,
+ value: { source: 'native', groupId, promptId, prompt: 'Hi', type: 'text' },
+ });
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+
+ await handlers.resolvePrompt(resolveReq(), res);
+
+ expect(resolvePrompt).toHaveBeenCalledWith({
+ groupId,
+ selection: { type: 'production' },
+ loadedGroup: undefined,
+ filters: undefined,
+ });
+ expect(res.statusCode).toBe(200);
+ expect(res.body).toEqual({ source: 'native', groupId, promptId, prompt: 'Hi', type: 'text' });
+ });
+
+ it('resolves an exact version for a Langfuse group', async () => {
+ const resolvePrompt = jest.fn().mockResolvedValue({
+ ok: true,
+ value: {
+ source: 'langfuse',
+ groupId,
+ prompt: 'Hi',
+ type: 'text',
+ version: 3,
+ labels: ['production'],
+ },
+ });
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+
+ await handlers.resolvePrompt(resolveReq('3'), res);
+
+ expect(resolvePrompt).toHaveBeenCalledWith({
+ groupId,
+ selection: { type: 'version', version: 3 },
+ loadedGroup: undefined,
+ filters: undefined,
+ });
+ expect(res.statusCode).toBe(200);
+ expect(res.body).toEqual({
+ source: 'langfuse',
+ groupId,
+ prompt: 'Hi',
+ type: 'text',
+ version: 3,
+ labels: ['production'],
+ });
+ });
+
+ it.each(['0', '-1', '1.5', 'abc'])(
+ 'rejects an invalid version %s without calling the service',
+ async (version) => {
+ const resolvePrompt = jest.fn();
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+
+ await handlers.resolvePrompt(resolveReq(version), res);
+
+ expect(res.statusCode).toBe(400);
+ expect(res.body).toEqual({ code: 'invalid_request' });
+ expect(resolvePrompt).not.toHaveBeenCalled();
+ },
+ );
+
+ it('rejects a duplicated ?version query parameter without calling the service', async () => {
+ const resolvePrompt = jest.fn();
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+ const req = mockReq({ params: { groupId }, query: { version: ['3', '4'] } });
+
+ await handlers.resolvePrompt(req, res);
+
+ expect(res.statusCode).toBe(400);
+ expect(res.body).toEqual({ code: 'invalid_request' });
+ expect(resolvePrompt).not.toHaveBeenCalled();
+ });
+
+ it('rejects a bracketed ?version[] query parameter without calling the service', async () => {
+ const resolvePrompt = jest.fn();
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+ const req = mockReq({ params: { groupId }, query: { version: ['3'] } });
+
+ await handlers.resolvePrompt(req, res);
+
+ expect(res.statusCode).toBe(400);
+ expect(res.body).toEqual({ code: 'invalid_request' });
+ expect(resolvePrompt).not.toHaveBeenCalled();
+ });
+
+ it('maps a native group rejecting ?version to 400 invalid_request', async () => {
+ const resolvePrompt = jest.fn().mockResolvedValue({
+ ok: false,
+ error: { type: 'unsupported_selection', source: 'native' },
+ });
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+
+ await handlers.resolvePrompt(resolveReq('2'), res);
+
+ expect(res.statusCode).toBe(400);
+ expect(res.body).toEqual({ code: 'invalid_request' });
+ });
+
+ it('maps blocked_content to the shared content filter response', async () => {
+ const finding = {
+ detectorId: 'pii-pattern',
+ ruleId: 'org-token',
+ label: 'organization token',
+ source: 'prompt' as const,
+ field: 'text' as const,
+ provenance: 'user' as const,
+ fragmentId: 'prompt.text',
+ fragmentPath: '/prompt/text' as const,
+ };
+ const resolvePrompt = jest
+ .fn()
+ .mockResolvedValue({ ok: false, error: { type: 'blocked_content', finding } });
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+
+ await handlers.resolvePrompt(resolveReq(), res);
+
+ expect(res.statusCode).toBe(400);
+ expect(res.body).toEqual(contentFilterBlockResponse(finding));
+ });
+
+ it('maps a native unavailable_selection to 404 not_found', async () => {
+ const resolvePrompt = jest.fn().mockResolvedValue({
+ ok: false,
+ error: { type: 'unavailable_selection', reason: 'production' },
+ });
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+
+ await handlers.resolvePrompt(resolveReq(), res);
+
+ expect(res.statusCode).toBe(404);
+ expect(res.body).toEqual({ code: 'not_found' });
+ });
+
+ it('maps source_not_found to 404 with the Langfuse message', async () => {
+ const resolvePrompt = jest.fn().mockResolvedValue({
+ ok: false,
+ error: { type: 'source_not_found', source: 'langfuse' },
+ });
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+
+ await handlers.resolvePrompt(resolveReq(), res);
+
+ expect(res.statusCode).toBe(404);
+ expect(res.body).toEqual({ code: 'not_found', message: 'Prompt not found in Langfuse' });
+ });
+
+ it('maps unsupported_content to 422 unsupported_type', async () => {
+ const resolvePrompt = jest.fn().mockResolvedValue({
+ ok: false,
+ error: { type: 'unsupported_content', reason: 'chat_prompt' },
+ });
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+
+ await handlers.resolvePrompt(resolveReq(), res);
+
+ expect(res.statusCode).toBe(422);
+ expect(res.body).toEqual({ code: 'unsupported_type' });
+ });
+
+ it.each([
+ ['disabled', 404, { code: 'not_available' }],
+ ['not_configured', 409, { code: 'not_configured' }],
+ ['source_changed', 409, { code: 'source_changed' }],
+ ] as const)('maps source_unavailable reason %s to %i %j', async (reason, status, body) => {
+ const resolvePrompt = jest.fn().mockResolvedValue({
+ ok: false,
+ error: { type: 'source_unavailable', source: 'langfuse', reason },
+ });
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+
+ await handlers.resolvePrompt(resolveReq(), res);
+
+ expect(res.statusCode).toBe(status);
+ expect(res.body).toEqual(body);
+ });
+
+ it('maps a thrown Langfuse timeout to 504', async () => {
+ jest.spyOn(logger, 'error').mockImplementation(() => logger);
+ const resolvePrompt = jest
+ .fn()
+ .mockRejectedValue(new LangfusePromptRequestError('timeout', 'Langfuse request timed out'));
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+
+ await handlers.resolvePrompt(resolveReq(), res);
+
+ expect(res.statusCode).toBe(504);
+ expect(res.body).toEqual({ code: 'timeout' });
+ });
+
+ it('maps a thrown Langfuse 401 to 502, never 401', async () => {
+ const errorSpy = jest.spyOn(logger, 'error').mockImplementation(() => logger);
+ const resolvePrompt = jest
+ .fn()
+ .mockRejectedValue(
+ new LangfusePromptRequestError('unauthorized', 'Langfuse responded with 401', 401),
+ );
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+
+ await handlers.resolvePrompt(resolveReq(), res);
+
+ expect(res.statusCode).toBe(502);
+ expect(res.statusCode).not.toBe(401);
+ expect(res.body).toEqual({ code: 'unauthorized' });
+ expect(errorSpy).toHaveBeenCalled();
+ });
+
+ it('maps a thrown Langfuse upstream error to 502 and relays the upstream status', async () => {
+ jest.spyOn(logger, 'error').mockImplementation(() => logger);
+ const resolvePrompt = jest
+ .fn()
+ .mockRejectedValue(
+ new LangfusePromptRequestError('upstream', 'Langfuse responded with 500', 500),
+ );
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+
+ await handlers.resolvePrompt(resolveReq(), res);
+
+ expect(res.statusCode).toBe(502);
+ expect(res.body).toEqual({ code: 'upstream', status: 500 });
+ });
+
+ it('maps a thrown read PromptStoreError to 404 not_found', async () => {
+ jest.spyOn(logger, 'error').mockImplementation(() => logger);
+ const resolvePrompt = jest
+ .fn()
+ .mockRejectedValue(new PromptStoreError('read', new Error('db down')));
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+
+ await handlers.resolvePrompt(resolveReq(), res);
+
+ expect(res.statusCode).toBe(404);
+ expect(res.body).toEqual({ code: 'not_found' });
+ });
+
+ it('returns 500 for an unexpected thrown error', async () => {
+ const errorSpy = jest.spyOn(logger, 'error').mockImplementation(() => logger);
+ const resolvePrompt = jest.fn().mockRejectedValue(new Error('database unavailable'));
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+
+ await handlers.resolvePrompt(resolveReq(), res);
+
+ expect(res.statusCode).toBe(500);
+ expect(res.body).toEqual({ message: 'Error resolving prompt' });
+ expect(errorSpy).toHaveBeenCalledWith('Error resolving prompt', expect.any(Error));
+ });
+
+ it('falls back to 500 for an unlisted error variant such as unsupported_source', async () => {
+ const resolvePrompt = jest.fn().mockResolvedValue({
+ ok: false,
+ error: { type: 'unsupported_source', source: 'native' },
+ });
+ const handlers = createPromptHandlers(makeDeps({ service: makeService({ resolvePrompt }) }));
+ const res = mockRes();
+
+ await handlers.resolvePrompt(resolveReq(), res);
+
+ expect(res.statusCode).toBe(500);
+ expect(res.body).toEqual({ message: 'Error resolving prompt' });
+ });
+});
diff --git a/packages/api/src/prompts/handlers.ts b/packages/api/src/prompts/handlers.ts
index 8369d8fc75..94fe810e32 100644
--- a/packages/api/src/prompts/handlers.ts
+++ b/packages/api/src/prompts/handlers.ts
@@ -1,3 +1,4 @@
+import { z } from 'zod';
import { logger, isValidObjectIdString } from '@librechat/data-schemas';
import {
PermissionBits,
@@ -5,16 +6,28 @@ import {
DEFAULT_CACHE_CLEAR_TIMEOUT_MS,
} from 'librechat-data-provider';
import type { Response } from 'express';
-import type { PromptGroupRecord, PromptServiceError, StoredId } from './types';
+import type { PromptGroupRecord, PromptSelection, PromptServiceError, StoredId } from './types';
import type { PromptViaGroupResource } from './access';
import type { PromptService } from './service';
import type { ServerRequest } from '~/types';
import { contentFilterBlockResponse } from '~/middleware/contentFilter';
+import { toLangfusePromptErrorResponse } from '~/langfuse/promptSync';
+import { LangfusePromptRequestError } from '~/langfuse/prompts';
import { runBounded } from '~/agents/instructions/linked';
import { formatPromptGroupsResponse } from './format';
import { getSafeErrorMetadata } from '~/utils';
import { isPromptStoreError } from './errors';
+/** Same rule as the admin Langfuse route's `promptVersionQuerySchema`
+ * (`admin/langfuse.ts`): an absent query param resolves `production`. Parses
+ * the raw query value rather than a pre-coerced string, so a repeated or
+ * bracketed `version` query parameter (an array, not a string) fails
+ * validation instead of silently falling back to `production`. */
+const resolveVersionQuerySchema = z.union([
+ z.undefined(),
+ z.string().pipe(z.coerce.number().int().positive().max(Number.MAX_SAFE_INTEGER)),
+]);
+
/** A request after the prompt access middleware stored the resolved record. */
export type PromptRequest = ServerRequest & {
resourceAccess?: { resourceInfo?: unknown };
@@ -46,6 +59,7 @@ export interface PromptHandlersDeps {
export interface PromptHandlers {
getPromptGroup: PromptHandler;
+ resolvePrompt: PromptHandler;
listAllPromptGroups: PromptHandler;
listPromptGroups: PromptHandler;
createPromptGroup: PromptHandler;
@@ -96,6 +110,38 @@ function sendRejection(res: Response, error: PromptServiceError): Response {
return res.status(400).send({ error: 'Prompt operation is not available' });
}
+/**
+ * Maps a `resolvePrompt` rejection to its `/resolve` response. `unsupported_source` only
+ * comes from the `allowedSources` check, which this route never passes, and
+ * `invalid_input`/`unsupported` belong to other operations; none of the three can reach
+ * here through this route, so they fall through to the generic 500 like any other
+ * unexpected failure.
+ */
+function sendResolveRejection(res: Response, error: PromptServiceError): Response {
+ switch (error.type) {
+ case 'blocked_content':
+ return res.status(400).send(contentFilterBlockResponse(error.finding));
+ case 'unsupported_selection':
+ return res.status(400).send({ code: 'invalid_request' });
+ case 'unavailable_selection':
+ return res.status(404).send({ code: 'not_found' });
+ case 'source_not_found':
+ return res.status(404).send({ code: 'not_found', message: 'Prompt not found in Langfuse' });
+ case 'unsupported_content':
+ return res.status(422).send({ code: 'unsupported_type' });
+ case 'source_unavailable':
+ if (error.reason === 'disabled') {
+ return res.status(404).send({ code: 'not_available' });
+ }
+ if (error.reason === 'not_configured') {
+ return res.status(409).send({ code: 'not_configured' });
+ }
+ return res.status(409).send({ code: 'source_changed' });
+ default:
+ return res.status(500).send({ message: 'Error resolving prompt' });
+ }
+}
+
/**
* Clears the linked-instructions cache so a promote or delete reaches linked agents
* on the next request instead of after the cache's TTL. A no-op when no cache is
@@ -172,6 +218,48 @@ export function createPromptHandlers(deps: PromptHandlersDeps): PromptHandlers {
}
},
+ /**
+ * Resolves a group's content for either source: native resolves `production`
+ * (the only selection it accepts), and Langfuse fetches live, by the `production`
+ * label or an exact `version`. Usage is not recorded here — `/use` already does.
+ */
+ async resolvePrompt(req, res) {
+ const groupId = param(req, 'groupId');
+ const parsedVersion = resolveVersionQuerySchema.safeParse(
+ (req.query as { version?: unknown }).version,
+ );
+ if (!parsedVersion.success) {
+ return res.status(400).send({ code: 'invalid_request' });
+ }
+ const selection: PromptSelection =
+ parsedVersion.data == null
+ ? { type: 'production' }
+ : { type: 'version', version: parsedVersion.data };
+ try {
+ const result = await service.resolvePrompt({
+ groupId,
+ selection,
+ loadedGroup: loadedGroup(req),
+ filters: req.config?.filters,
+ });
+ if (!result.ok) {
+ return sendResolveRejection(res, result.error);
+ }
+ return res.status(200).send(result.value);
+ } catch (error) {
+ if (error instanceof LangfusePromptRequestError) {
+ logger.error('[prompts] Langfuse request failed while resolving a prompt', error);
+ const { status, body } = toLangfusePromptErrorResponse(error);
+ return res.status(status).send(body);
+ }
+ logger.error('Error resolving prompt', error);
+ if (isPromptStoreError(error, 'read')) {
+ return res.status(404).send({ code: 'not_found' });
+ }
+ return res.status(500).send({ message: 'Error resolving prompt' });
+ }
+ },
+
async listAllPromptGroups(req, res) {
try {
const result = await service.getListPromptGroupsByAccess({
@@ -258,6 +346,7 @@ export function createPromptHandlers(deps: PromptHandlersDeps): PromptHandlers {
prompt: body(req).prompt,
author: req.user?.id ?? '',
filters: req.config?.filters,
+ loadedGroup: loadedGroup(req),
});
if (!result.ok) {
return sendRejection(res, result.error);
diff --git a/packages/api/src/prompts/index.ts b/packages/api/src/prompts/index.ts
index c0215fdd61..18d4082b19 100644
--- a/packages/api/src/prompts/index.ts
+++ b/packages/api/src/prompts/index.ts
@@ -3,6 +3,7 @@ export * from './artifacts';
export * from './errors';
export * from './format';
export * from './handlers';
+export * from './langfuse';
export * from './migration';
export * from './native';
export * from './protection';
diff --git a/packages/api/src/prompts/langfuse.spec.ts b/packages/api/src/prompts/langfuse.spec.ts
new file mode 100644
index 0000000000..3089b23f36
--- /dev/null
+++ b/packages/api/src/prompts/langfuse.spec.ts
@@ -0,0 +1,296 @@
+process.env.CREDS_KEY =
+ process.env.CREDS_KEY ?? '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+
+const langfuseEnvKeys = [
+ 'LANGFUSE_PUBLIC_KEY',
+ 'LANGFUSE_SECRET_KEY',
+ 'LANGFUSE_PROJECT_ID',
+ 'LANGFUSE_BASE_URL',
+ 'LANGFUSE_HOST',
+ 'LANGFUSE_BASEURL',
+ 'LANGFUSE_FANOUT_ENABLED',
+ 'LANGFUSE_FANOUT_COLLECTOR_URL',
+ 'LANGFUSE_FANOUT_TENANT_DESTINATIONS',
+ 'LANGFUSE_FANOUT_TENANT_EU_BASE_URL',
+ 'LANGFUSE_FANOUT_TENANT_US_BASE_URL',
+ 'LANGFUSE_FANOUT_TENANT_JP_BASE_URL',
+ 'TENANT_ISOLATION_STRICT',
+];
+
+function clearLangfuseEnv() {
+ for (const key of langfuseEnvKeys) {
+ delete process.env[key];
+ }
+}
+
+// Cleared before the module graph loads: another spec file running earlier in
+// this worker may have left Langfuse env vars set, and `../langfuse/destinations`
+// reads them at import time for its own warm-up lookup.
+clearLangfuseEnv();
+
+jest.mock(
+ '@librechat/data-schemas',
+ () => ({
+ logger: { debug: jest.fn(), error: jest.fn(), warn: jest.fn(), info: jest.fn() },
+ }),
+ { virtual: true },
+);
+
+jest.mock('~/admin/secrets', () => ({
+ decryptConfigSecret: jest.fn((value: string) =>
+ value === 'v3:test:tenant-secret-key' ? 'tenant-secret-key' : undefined,
+ ),
+}));
+
+import type { LangfuseSourceResolution } from '../langfuse/promptSync';
+import type { LangfusePromptConnection } from '../langfuse/prompts';
+import type { PromptGroupRecord } from './types';
+import { LangfusePromptRequestError } from '../langfuse/prompts';
+import { createLangfusePromptAdapter } from './langfuse';
+
+function jsonResponse(body: unknown, status = 200): Response {
+ return new Response(JSON.stringify(body), {
+ status,
+ headers: { 'Content-Type': 'application/json' },
+ });
+}
+
+const connection: LangfusePromptConnection = {
+ baseUrl: 'https://cloud.langfuse.test',
+ authorization: 'Basic cGs6c2s=',
+};
+
+function makeGroup(overrides: Partial<PromptGroupRecord> = {}): PromptGroupRecord {
+ return {
+ _id: 'group-1',
+ name: 'Langfuse group',
+ author: 'author-1',
+ authorName: 'Author',
+ source: 'langfuse',
+ sourcePromptName: 'greeting',
+ tenantId: 'tenant-1',
+ ...overrides,
+ };
+}
+
+function okResolution(): LangfuseSourceResolution {
+ return { ok: true, connection };
+}
+
+let fetchMock: jest.SpiedFunction<typeof fetch>;
+
+beforeEach(() => {
+ clearLangfuseEnv();
+ fetchMock = jest.spyOn(global, 'fetch');
+});
+
+afterEach(() => {
+ clearLangfuseEnv();
+ fetchMock.mockRestore();
+ jest.clearAllMocks();
+});
+
+describe('createLangfusePromptAdapter', () => {
+ it('sends label=production and no version for a production selection', async () => {
+ const resolveSource = jest.fn().mockResolvedValue(okResolution());
+ const adapter = createLangfusePromptAdapter({ resolveSource, timeoutMs: () => 5000 });
+ fetchMock.mockResolvedValue(
+ jsonResponse({
+ name: 'greeting',
+ version: 4,
+ type: 'text',
+ labels: ['production'],
+ prompt: 'Hi {{name}}',
+ }),
+ );
+
+ const result = await adapter.resolvePrompt({
+ group: makeGroup(),
+ selection: { type: 'production' },
+ });
+
+ expect(resolveSource).toHaveBeenCalledWith(makeGroup());
+ const [url] = fetchMock.mock.calls[0];
+ expect(url).toBe('https://cloud.langfuse.test/api/public/v2/prompts/greeting?label=production');
+ expect(result).toEqual({
+ ok: true,
+ value: {
+ source: 'langfuse',
+ groupId: 'group-1',
+ prompt: 'Hi {{name}}',
+ type: 'text',
+ version: 4,
+ labels: ['production'],
+ },
+ });
+ });
+
+ it('sends version=N and no label for a version selection', async () => {
+ const resolveSource = jest.fn().mockResolvedValue(okResolution());
+ const adapter = createLangfusePromptAdapter({ resolveSource, timeoutMs: () => 5000 });
+ fetchMock.mockResolvedValue(
+ jsonResponse({ name: 'greeting', version: 3, type: 'text', labels: [], prompt: 'Hi there' }),
+ );
+
+ const result = await adapter.resolvePrompt({
+ group: makeGroup(),
+ selection: { type: 'version', version: 3 },
+ });
+
+ const [url] = fetchMock.mock.calls[0];
+ expect(url).toBe('https://cloud.langfuse.test/api/public/v2/prompts/greeting?version=3');
+ expect(result).toEqual({
+ ok: true,
+ value: {
+ source: 'langfuse',
+ groupId: 'group-1',
+ prompt: 'Hi there',
+ type: 'text',
+ version: 3,
+ labels: [],
+ },
+ });
+ });
+
+ it('returns unsupported_content for a chat prompt without parsing its content', async () => {
+ const resolveSource = jest.fn().mockResolvedValue(okResolution());
+ const adapter = createLangfusePromptAdapter({ resolveSource, timeoutMs: () => 5000 });
+ fetchMock.mockResolvedValue(
+ jsonResponse({
+ name: 'support-chat',
+ version: 1,
+ type: 'chat',
+ labels: ['production'],
+ prompt: [{ role: 'system', content: 'secret system content' }],
+ }),
+ );
+
+ const result = await adapter.resolvePrompt({
+ group: makeGroup(),
+ selection: { type: 'production' },
+ });
+
+ expect(result).toEqual({
+ ok: false,
+ error: { type: 'unsupported_content', reason: 'chat_prompt' },
+ });
+ expect(JSON.stringify(result)).not.toContain('secret system content');
+ });
+
+ it('returns source_not_found on a 404', async () => {
+ const resolveSource = jest.fn().mockResolvedValue(okResolution());
+ const adapter = createLangfusePromptAdapter({ resolveSource, timeoutMs: () => 5000 });
+ fetchMock.mockResolvedValue(new Response(null, { status: 404 }));
+
+ const result = await adapter.resolvePrompt({
+ group: makeGroup(),
+ selection: { type: 'production' },
+ });
+
+ expect(result).toEqual({ ok: false, error: { type: 'source_not_found', source: 'langfuse' } });
+ });
+
+ it('returns unsupported_selection for an exact selection without calling resolveSource or fetch', async () => {
+ const resolveSource = jest.fn();
+ const adapter = createLangfusePromptAdapter({ resolveSource, timeoutMs: () => 5000 });
+
+ const result = await adapter.resolvePrompt({
+ group: makeGroup(),
+ selection: { type: 'exact', promptId: 'prompt-1' },
+ });
+
+ expect(result).toEqual({
+ ok: false,
+ error: { type: 'unsupported_selection', source: 'langfuse' },
+ });
+ expect(resolveSource).not.toHaveBeenCalled();
+ expect(fetchMock).not.toHaveBeenCalled();
+ });
+
+ it('returns source_unavailable not_configured when the group has no sourcePromptName, without calling resolveSource or fetch', async () => {
+ const resolveSource = jest.fn();
+ const adapter = createLangfusePromptAdapter({ resolveSource, timeoutMs: () => 5000 });
+
+ const result = await adapter.resolvePrompt({
+ group: makeGroup({ sourcePromptName: undefined }),
+ selection: { type: 'production' },
+ });
+
+ expect(result).toEqual({
+ ok: false,
+ error: { type: 'source_unavailable', source: 'langfuse', reason: 'not_configured' },
+ });
+ expect(resolveSource).not.toHaveBeenCalled();
+ expect(fetchMock).not.toHaveBeenCalled();
+ });
+
+ it.each(['disabled', 'not_configured', 'source_changed'] as const)(
+ 'passes a resolveSource %s reason through as source_unavailable, without fetching',
+ async (reason) => {
+ const resolveSource = jest.fn().mockResolvedValue({ ok: false, reason });
+ const adapter = createLangfusePromptAdapter({ resolveSource, timeoutMs: () => 5000 });
+
+ const result = await adapter.resolvePrompt({
+ group: makeGroup(),
+ selection: { type: 'production' },
+ });
+
+ expect(result).toEqual({
+ ok: false,
+ error: { type: 'source_unavailable', source: 'langfuse', reason },
+ });
+ expect(fetchMock).not.toHaveBeenCalled();
+ },
+ );
+
+ it('throws LangfusePromptRequestError on an unauthorized response rather than returning a result', async () => {
+ const resolveSource = jest.fn().mockResolvedValue(okResolution());
+ const adapter = createLangfusePromptAdapter({ resolveSource, timeoutMs: () => 5000 });
+ fetchMock.mockResolvedValue(new Response(null, { status: 401 }));
+
+ expect.assertions(2);
+ try {
+ await adapter.resolvePrompt({ group: makeGroup(), selection: { type: 'production' } });
+ } catch (error) {
+ expect(error).toBeInstanceOf(LangfusePromptRequestError);
+ expect(error).toMatchObject({ code: 'unauthorized' });
+ }
+ });
+
+ it('throws LangfusePromptRequestError on a timeout rather than returning a result', async () => {
+ const resolveSource = jest.fn().mockResolvedValue(okResolution());
+ const adapter = createLangfusePromptAdapter({ resolveSource, timeoutMs: () => 5000 });
+ const timeout = new Error('The operation was aborted due to timeout');
+ timeout.name = 'TimeoutError';
+ fetchMock.mockRejectedValue(timeout);
+
+ expect.assertions(2);
+ try {
+ await adapter.resolvePrompt({ group: makeGroup(), selection: { type: 'production' } });
+ } catch (error) {
+ expect(error).toBeInstanceOf(LangfusePromptRequestError);
+ expect(error).toMatchObject({ code: 'timeout' });
+ }
+ });
+
+ it('uses the default timeout when none is supplied', async () => {
+ delete process.env.LANGFUSE_PROMPT_SYNC_TIMEOUT_MS;
+ const resolveSource = jest.fn().mockResolvedValue(okResolution());
+ const adapter = createLangfusePromptAdapter({ resolveSource });
+ fetchMock.mockResolvedValue(
+ jsonResponse({ name: 'greeting', version: 1, type: 'text', labels: [], prompt: 'Hi' }),
+ );
+ const timeoutSpy = jest.spyOn(AbortSignal, 'timeout');
+
+ const result = await adapter.resolvePrompt({
+ group: makeGroup(),
+ selection: { type: 'production' },
+ });
+
+ // No `timeoutMs` override, so the adapter must fall back to the shared
+ // Langfuse prompt-sync default (10 seconds) rather than skip the bound.
+ expect(timeoutSpy).toHaveBeenCalledWith(10_000);
+ expect(result).toMatchObject({ ok: true });
+ timeoutSpy.mockRestore();
+ });
+});
diff --git a/packages/api/src/prompts/langfuse.ts b/packages/api/src/prompts/langfuse.ts
new file mode 100644
index 0000000000..0061801b35
--- /dev/null
+++ b/packages/api/src/prompts/langfuse.ts
@@ -0,0 +1,78 @@
+import type { LangfuseSourceGroup, LangfuseSourceResolution } from '../langfuse/promptSync';
+import type { LangfuseTextPromptSelector } from '../langfuse/prompts';
+import type { PromptSourceAdapter } from './types';
+import { getLangfusePromptSyncTimeoutMs } from '../langfuse/policy';
+import { getLangfuseTextPrompt } from '../langfuse/prompts';
+
+export interface CreateLangfusePromptAdapterDependencies {
+ /** Checks the deployment gate, tenant match and prompt-sync switch; builds the
+ * connection the fetch uses, failing as `not_configured` if that build fails; and
+ * checks the group's recorded source identity against that connection, failing as
+ * `source_changed` on a mismatch. Its failure reasons pass straight through. */
+ readonly resolveSource: (group: LangfuseSourceGroup) => Promise<LangfuseSourceResolution>;
+ readonly getTextPrompt?: typeof getLangfuseTextPrompt;
+ readonly timeoutMs?: () => number;
+}
+
+/**
+ * A read-only content source for a group whose `source` is `langfuse`: it fetches the
+ * group's text prompt from Langfuse on every call, with no cache and no mutations.
+ *
+ * Langfuse resolves a composed prompt's `@@@langfusePrompt:…@@@` references
+ * server-side (`resolve` defaults to `true`), so no code is needed here for that: an
+ * exact parent `version` fixes the parent text and any children pinned by version,
+ * while children pinned by label resolve fresh on each request.
+ *
+ * A thrown `LangfusePromptRequestError`, or an error thrown by `resolveSource`,
+ * propagates to the caller rather than being caught here.
+ */
+export function createLangfusePromptAdapter({
+ resolveSource,
+ getTextPrompt = getLangfuseTextPrompt,
+ timeoutMs = getLangfusePromptSyncTimeoutMs,
+}: CreateLangfusePromptAdapterDependencies): PromptSourceAdapter {
+ return {
+ async resolvePrompt({ group, selection }) {
+ if (selection.type !== 'production' && selection.type !== 'version') {
+ return { ok: false, error: { type: 'unsupported_selection', source: 'langfuse' } };
+ }
+ if (!group.sourcePromptName) {
+ return {
+ ok: false,
+ error: { type: 'source_unavailable', source: 'langfuse', reason: 'not_configured' },
+ };
+ }
+
+ const resolution = await resolveSource(group);
+ if (!resolution.ok) {
+ return {
+ ok: false,
+ error: { type: 'source_unavailable', source: 'langfuse', reason: resolution.reason },
+ };
+ }
+
+ const selector: LangfuseTextPromptSelector =
+ selection.type === 'version' ? { version: selection.version } : { label: 'production' };
+ const result = await getTextPrompt(resolution.connection, group.sourcePromptName, selector, {
+ timeoutMs: timeoutMs(),
+ });
+ if (!result.ok) {
+ return result.error.code === 'not_found'
+ ? { ok: false, error: { type: 'source_not_found', source: 'langfuse' } }
+ : { ok: false, error: { type: 'unsupported_content', reason: 'chat_prompt' } };
+ }
+
+ return {
+ ok: true,
+ value: {
+ source: 'langfuse',
+ groupId: group._id,
+ prompt: result.value.prompt,
+ type: 'text',
+ version: result.value.version,
+ labels: result.value.labels,
+ },
+ };
+ },
+ };
+}
diff --git a/packages/api/src/prompts/native.spec.ts b/packages/api/src/prompts/native.spec.ts
index c7e91e7921..45122db6e7 100644
--- a/packages/api/src/prompts/native.spec.ts
+++ b/packages/api/src/prompts/native.spec.ts
@@ -2,7 +2,7 @@ import mongoose, { Types } from 'mongoose';
import { MongoMemoryServer } from 'mongodb-memory-server';
import { createModels, createMethods } from '@librechat/data-schemas';
import type { PromptDatabase, PromptGroupRecord, PromptRecord } from './types';
-import { createNativePromptAdapter } from './native';
+import { createNativePromptAdapter, createPromptCatalogStore } from './native';
let mongo: MongoMemoryServer;
let db: PromptDatabase;
@@ -32,7 +32,9 @@ beforeEach(async () => {
prompt: { prompt: 'Draft prompt', type: 'chat' },
author,
})) as { prompt: PromptRecord });
- group = (await adapter.getPromptGroup(production.groupId)) as PromptGroupRecord;
+ group = (await createPromptCatalogStore(db).getPromptGroup(
+ production.groupId,
+ )) as PromptGroupRecord;
});
afterEach(async () => {
@@ -52,6 +54,7 @@ describe('createNativePromptAdapter', () => {
expect.objectContaining({
_id: production.groupId,
author,
+ source: 'native',
productionId: production._id,
productionPrompt: expect.objectContaining({
_id: production._id,
@@ -63,51 +66,37 @@ describe('createNativePromptAdapter', () => {
expect(draft).toEqual(expect.objectContaining({ groupId: group._id, author, type: 'chat' }));
});
- it('resolves Production from a loaded group without another read', async () => {
+ it('resolves Production from the group inlined revision without reading it again', async () => {
const adapter = createNativePromptAdapter(db);
- const readGroup = jest.spyOn(db, 'getPromptGroup');
const readPrompt = jest.spyOn(db, 'getPrompt');
await expect(
- adapter.resolvePrompt({
- groupId: group._id,
- selection: { type: 'production' },
- loadedGroup: group,
- }),
+ adapter.resolvePrompt({ group, selection: { type: 'production' } }),
).resolves.toEqual({
- groupId: group._id,
- promptId: production._id,
- prompt: 'Production prompt',
- type: 'text',
+ ok: true,
+ value: {
+ source: 'native',
+ groupId: group._id,
+ promptId: production._id,
+ prompt: 'Production prompt',
+ type: 'text',
+ },
});
- expect(readGroup).not.toHaveBeenCalled();
expect(readPrompt).not.toHaveBeenCalled();
});
- it('reads the group once to resolve Production when no group is loaded', async () => {
+ it('reads the Production revision when the group has no inlined revision', async () => {
const adapter = createNativePromptAdapter(db);
- const readGroup = jest.spyOn(db, 'getPromptGroup');
const readPrompt = jest.spyOn(db, 'getPrompt');
-
- await expect(
- adapter.resolvePrompt({ groupId: group._id, selection: { type: 'production' } }),
- ).resolves.toMatchObject({ promptId: production._id });
- expect(readGroup).toHaveBeenCalledTimes(1);
- expect(readPrompt).not.toHaveBeenCalled();
- });
-
- it('reads the group when the loaded group is a different group', async () => {
- const adapter = createNativePromptAdapter(db);
- const readGroup = jest.spyOn(db, 'getPromptGroup');
+ const { productionPrompt: _productionPrompt, ...groupWithoutInlinedRevision } = group;
await expect(
adapter.resolvePrompt({
- groupId: group._id,
+ group: groupWithoutInlinedRevision,
selection: { type: 'production' },
- loadedGroup: { ...group, _id: new Types.ObjectId().toString() },
}),
- ).resolves.toMatchObject({ promptId: production._id });
- expect(readGroup).toHaveBeenCalledTimes(1);
+ ).resolves.toMatchObject({ ok: true, value: { promptId: production._id } });
+ expect(readPrompt).toHaveBeenCalledTimes(1);
});
it('resolves an exact revision from a loaded revision without another read', async () => {
@@ -116,15 +105,19 @@ describe('createNativePromptAdapter', () => {
await expect(
adapter.resolvePrompt({
- groupId: group._id,
+ group,
selection: { type: 'exact', promptId: draft._id },
loadedRevision: draft,
}),
).resolves.toEqual({
- groupId: group._id,
- promptId: draft._id,
- prompt: 'Draft prompt',
- type: 'chat',
+ ok: true,
+ value: {
+ source: 'native',
+ groupId: group._id,
+ promptId: draft._id,
+ prompt: 'Draft prompt',
+ type: 'chat',
+ },
});
expect(readPrompt).not.toHaveBeenCalled();
});
@@ -135,33 +128,67 @@ describe('createNativePromptAdapter', () => {
await expect(
adapter.resolvePrompt({
- groupId: group._id,
+ group,
selection: { type: 'exact', promptId: draft._id },
loadedRevision: production,
}),
- ).resolves.toMatchObject({ promptId: draft._id });
+ ).resolves.toMatchObject({ ok: true, value: { promptId: draft._id } });
expect(readPrompt).toHaveBeenCalledTimes(1);
});
- it('does not resolve a revision of another group or a missing selection', async () => {
+ it('returns unavailable_selection for a missing revision or group with no Production', async () => {
const adapter = createNativePromptAdapter(db);
- const otherGroupId = new Types.ObjectId().toString();
await expect(
adapter.resolvePrompt({
- groupId: otherGroupId,
- selection: { type: 'exact', promptId: draft._id },
+ group,
+ selection: { type: 'exact', promptId: new Types.ObjectId().toString() },
}),
- ).resolves.toBeNull();
+ ).resolves.toEqual({
+ ok: false,
+ error: { type: 'unavailable_selection', reason: 'revision' },
+ });
await expect(
- adapter.resolvePrompt({ groupId: otherGroupId, selection: { type: 'production' } }),
- ).resolves.toBeNull();
+ adapter.resolvePrompt({
+ group: { ...group, productionId: null, productionPrompt: null },
+ selection: { type: 'production' },
+ }),
+ ).resolves.toEqual({
+ ok: false,
+ error: { type: 'unavailable_selection', reason: 'production' },
+ });
+ });
+
+ it('does not resolve a revision belonging to another group', async () => {
+ const adapter = createNativePromptAdapter(db);
+ const otherGroup = { ...group, _id: new Types.ObjectId().toString() };
+
await expect(
adapter.resolvePrompt({
- groupId: group._id,
- selection: { type: 'exact', promptId: new Types.ObjectId().toString() },
+ group: otherGroup,
+ selection: { type: 'exact', promptId: draft._id },
}),
- ).resolves.toBeNull();
+ ).resolves.toEqual({
+ ok: false,
+ error: { type: 'unavailable_selection', reason: 'revision' },
+ });
+ await expect(
+ adapter.resolvePrompt({ group: otherGroup, selection: { type: 'production' } }),
+ ).resolves.toEqual({
+ ok: false,
+ error: { type: 'unavailable_selection', reason: 'production' },
+ });
+ });
+
+ it('returns unsupported_selection for a version selection', async () => {
+ const adapter = createNativePromptAdapter(db);
+
+ await expect(
+ adapter.resolvePrompt({ group, selection: { type: 'version', version: 1 } }),
+ ).resolves.toEqual({
+ ok: false,
+ error: { type: 'unsupported_selection', source: 'native' },
+ });
});
it('resolves a stored revision without a type as text', async () => {
@@ -170,31 +197,25 @@ describe('createNativePromptAdapter', () => {
{ groupId: new Types.ObjectId(group._id) },
{ $unset: { type: '' } },
);
- const loaded = (await adapter.getPromptGroup(group._id)) as PromptGroupRecord;
+ const loaded = (await createPromptCatalogStore(db).getPromptGroup(
+ group._id,
+ )) as PromptGroupRecord;
await expect(
- adapter.resolvePrompt({ groupId: group._id, selection: { type: 'production' } }),
- ).resolves.toMatchObject({ promptId: production._id, type: 'text' });
+ adapter.resolvePrompt({ group: loaded, selection: { type: 'production' } }),
+ ).resolves.toMatchObject({ ok: true, value: { promptId: production._id, type: 'text' } });
await expect(
adapter.resolvePrompt({
- groupId: group._id,
- selection: { type: 'production' },
- loadedGroup: loaded,
- }),
- ).resolves.toMatchObject({ promptId: production._id, type: 'text' });
- await expect(
- adapter.resolvePrompt({
- groupId: group._id,
+ group: loaded,
selection: { type: 'exact', promptId: draft._id },
}),
- ).resolves.toMatchObject({ promptId: draft._id, type: 'text' });
+ ).resolves.toMatchObject({ ok: true, value: { promptId: draft._id, type: 'text' } });
});
- it('returns null for absent records', async () => {
+ it('returns null for an absent revision', async () => {
const adapter = createNativePromptAdapter(db);
const missing = new Types.ObjectId().toString();
- await expect(adapter.getPromptGroup(missing)).resolves.toBeNull();
await expect(adapter.getPrompt(missing)).resolves.toBeNull();
});
@@ -215,7 +236,7 @@ describe('createNativePromptAdapter', () => {
await adapter.makePromptProduction?.(draft._id);
- await expect(adapter.getPromptGroup(group._id)).resolves.toMatchObject({
+ await expect(createPromptCatalogStore(db).getPromptGroup(group._id)).resolves.toMatchObject({
productionId: draft._id,
});
await expect(adapter.makePromptProduction?.(new Types.ObjectId().toString())).rejects.toThrow(
@@ -237,3 +258,17 @@ describe('createNativePromptAdapter', () => {
});
});
});
+
+describe('createPromptCatalogStore', () => {
+ it('returns a group with string IDs through getPromptGroup', async () => {
+ const catalog = createPromptCatalogStore(db);
+
+ await expect(catalog.getPromptGroup(production.groupId)).resolves.toEqual(group);
+ });
+
+ it('returns null for a missing group', async () => {
+ const catalog = createPromptCatalogStore(db);
+
+ await expect(catalog.getPromptGroup(new Types.ObjectId().toString())).resolves.toBeNull();
+ });
+});
diff --git a/packages/api/src/prompts/native.ts b/packages/api/src/prompts/native.ts
index 12a36ab54e..d90f29b72c 100644
--- a/packages/api/src/prompts/native.ts
+++ b/packages/api/src/prompts/native.ts
@@ -1,17 +1,18 @@
import type {
- PromptRecord,
StoredId,
+ PromptRecord,
PromptDatabase,
- ResolvedPrompt,
- PromptProjection,
PromptSelection,
+ PromptProjection,
PromptGroupRecord,
PromptCatalogStore,
- PromptSourceAdapter,
+ NativePromptAdapter,
+ NativeResolvedPrompt,
} from './types';
import { toPromptGroupRecord, toPromptRecord } from './records';
type ResolvablePrompt = Pick<PromptRecord, '_id' | 'groupId' | 'prompt' | 'type'>;
+type NativeResolvedValue = Omit<NativeResolvedPrompt, 'source'>;
function isMatchingRevision(
revision: PromptRecord | PromptProjection | null | undefined,
@@ -27,7 +28,7 @@ function isMatchingRevision(
}
/** A revision stored without a type is a text prompt, the same default the client uses. */
-function resolveValue(revision: ResolvablePrompt): ResolvedPrompt {
+function resolveValue(revision: ResolvablePrompt): NativeResolvedValue {
return {
groupId: revision.groupId,
promptId: revision._id,
@@ -49,12 +50,14 @@ async function getPromptGroup(
return record == null ? null : toPromptGroupRecord(record);
}
+/** Resolves an exact revision, reading it when `loadedRevision` does not already
+ * match this group and promptId. */
async function resolveExact(
db: PromptDatabase,
groupId: string,
promptId: string,
loadedRevision?: PromptRecord | null,
-): Promise<ResolvedPrompt | null> {
+): Promise<NativeResolvedValue | null> {
let revision = loadedRevision;
if (!isMatchingRevision(revision, groupId, promptId)) {
revision = await getPrompt(db, promptId);
@@ -62,39 +65,54 @@ async function resolveExact(
return isMatchingRevision(revision, groupId, promptId) ? resolveValue(revision) : null;
}
+/**
+ * Resolves a group's Production revision. The caller (the service) has already loaded
+ * `group`, so this only re-reads the revision itself: when the group's inlined
+ * `productionPrompt` is absent or stale it falls back to one `getPrompt` read.
+ */
async function resolveProduction(
db: PromptDatabase,
- groupId: string,
- loadedGroup?: PromptGroupRecord | null,
-): Promise<ResolvedPrompt | null> {
- let group = loadedGroup;
- if (group?._id !== groupId) {
- group = await getPromptGroup(db, groupId);
- }
- if (group == null || group.productionId == null) {
+ group: PromptGroupRecord,
+): Promise<NativeResolvedValue | null> {
+ if (group.productionId == null) {
return null;
}
- if (isMatchingRevision(group.productionPrompt, groupId, group.productionId)) {
+ if (isMatchingRevision(group.productionPrompt, group._id, group.productionId)) {
return resolveValue(group.productionPrompt);
}
const revision = await getPrompt(db, group.productionId);
- return isMatchingRevision(revision, groupId, group.productionId) ? resolveValue(revision) : null;
+ return isMatchingRevision(revision, group._id, group.productionId)
+ ? resolveValue(revision)
+ : null;
}
function toIdString(id: StoredId): string {
return typeof id === 'string' ? id : id.toString();
}
+export function selectionUnavailableReason(selection: PromptSelection): 'production' | 'revision' {
+ return selection.type === 'production' ? 'production' : 'revision';
+}
+
/** Native prompts stored in the LibreChat database. */
-export function createNativePromptAdapter(db: PromptDatabase): PromptSourceAdapter {
+export function createNativePromptAdapter(db: PromptDatabase): NativePromptAdapter {
return {
- resolvePrompt: ({ groupId, selection, loadedGroup, loadedRevision }) => {
- if (selection.type === 'exact') {
- return resolveExact(db, groupId, selection.promptId, loadedRevision);
+ resolvePrompt: async ({ group, selection, loadedRevision }) => {
+ if (selection.type === 'version') {
+ return { ok: false, error: { type: 'unsupported_selection', source: 'native' } };
+ }
+ const resolved =
+ selection.type === 'exact'
+ ? await resolveExact(db, group._id, selection.promptId, loadedRevision)
+ : await resolveProduction(db, group);
+ if (resolved == null) {
+ return {
+ ok: false,
+ error: { type: 'unavailable_selection', reason: selectionUnavailableReason(selection) },
+ };
}
- return resolveProduction(db, groupId, loadedGroup);
+ return { ok: true, value: { source: 'native', ...resolved } };
},
- getPromptGroup: (groupId) => getPromptGroup(db, groupId),
getPrompt: (promptId) => getPrompt(db, promptId),
getPrompts: async (groupId) => (await db.getPrompts({ groupId })).map(toPromptRecord),
createPromptGroup: async ({ prompt, group = {}, author, authorName }) => {
@@ -125,6 +143,7 @@ export function createNativePromptAdapter(db: PromptDatabase): PromptSourceAdapt
/** Local catalog operations over the LibreChat prompt group collection. */
export function createPromptCatalogStore(db: PromptDatabase): PromptCatalogStore {
return {
+ getPromptGroup: (groupId) => getPromptGroup(db, groupId),
getListPromptGroupsByAccess: async ({ accessibleIds, name, category, limit, after }) => {
const result = await db.getListPromptGroupsByAccess({
accessibleIds: [...accessibleIds],
@@ -145,7 +164,3 @@ export function createPromptCatalogStore(db: PromptDatabase): PromptCatalogStore
deletePromptGroup: (groupId) => db.deletePromptGroup({ _id: groupId }),
};
}
-
-export function selectionUnavailableReason(selection: PromptSelection): 'production' | 'revision' {
- return selection.type === 'production' ? 'production' : 'revision';
-}
diff --git a/packages/api/src/prompts/service.spec.ts b/packages/api/src/prompts/service.spec.ts
index 3df42449fe..91013b7cdc 100644
--- a/packages/api/src/prompts/service.spec.ts
+++ b/packages/api/src/prompts/service.spec.ts
@@ -1,13 +1,19 @@
import mongoose, { Types } from 'mongoose';
import { MongoMemoryServer } from 'mongodb-memory-server';
-import { logger, createModels, createMethods } from '@librechat/data-schemas';
import { AccessRoleIds, PrincipalType, ResourceType } from 'librechat-data-provider';
+import {
+ logger,
+ createModels,
+ createMethods,
+ BASE_CONFIG_PRINCIPAL_ID,
+} from '@librechat/data-schemas';
import type { FiltersConfig } from 'librechat-data-provider';
import type {
PromptRecord,
PromptDatabase,
PromptGroupRecord,
CreatePromptGroupInput,
+ LangfuseResolvedPrompt,
} from './types';
import type { PromptServiceDependencies, PromptService } from './service';
import { createPromptServiceFromAdapters, createPromptService } from './service';
@@ -26,6 +32,7 @@ const filters: FiltersConfig = {
let mongo: MongoMemoryServer;
let db: PromptDatabase;
let grantPermission: jest.MockedFunction<PromptServiceDependencies['grantPermission']>;
+let getAppConfig: jest.MockedFunction<PromptServiceDependencies['getAppConfig']>;
let service: PromptService;
let group: PromptGroupRecord;
let production: PromptRecord;
@@ -41,7 +48,8 @@ beforeAll(async () => {
beforeEach(async () => {
grantPermission = jest.fn().mockResolvedValue(undefined);
- service = createPromptService({ db, grantPermission });
+ getAppConfig = jest.fn();
+ service = createPromptService({ db, grantPermission, getAppConfig });
const created = await service.createPromptGroup({
prompt: { prompt: 'Production prompt', type: 'text' },
group: { name: 'Service group' },
@@ -52,7 +60,7 @@ beforeEach(async () => {
throw new Error('Test group was not created');
}
production = created.value.prompt;
- group = (await createNativePromptAdapter(db).getPromptGroup(
+ group = (await createPromptCatalogStore(db).getPromptGroup(
production.groupId,
)) as PromptGroupRecord;
grantPermission.mockClear();
@@ -89,6 +97,7 @@ describe('createPromptService', () => {
).resolves.toEqual({
ok: true,
value: {
+ source: 'native',
groupId: group._id,
promptId: production._id,
prompt: 'Production prompt',
@@ -126,6 +135,97 @@ describe('createPromptService', () => {
error: { type: 'unavailable_selection', reason: 'production' },
});
});
+
+ it('reads the group once when none is loaded', async () => {
+ const read = jest.spyOn(db, 'getPromptGroup');
+
+ await expect(
+ service.resolvePrompt({ groupId: group._id, selection: { type: 'production' } }),
+ ).resolves.toMatchObject({ ok: true, value: { promptId: production._id } });
+ expect(read).toHaveBeenCalledTimes(1);
+ });
+
+ it('reads when the loaded group differs', async () => {
+ const read = jest.spyOn(db, 'getPromptGroup');
+ const otherGroup = { ...group, _id: missingId() };
+
+ await expect(
+ service.resolvePrompt({
+ groupId: group._id,
+ selection: { type: 'production' },
+ loadedGroup: otherGroup,
+ }),
+ ).resolves.toMatchObject({ ok: true, value: { promptId: production._id } });
+ expect(read).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not prefetch a revision for a production selection', async () => {
+ const revisionRead = jest.spyOn(db, 'getPrompt');
+
+ await expect(
+ service.resolvePrompt({ groupId: group._id, selection: { type: 'production' } }),
+ ).resolves.toMatchObject({ ok: true, value: { promptId: production._id } });
+ expect(revisionRead).not.toHaveBeenCalled();
+ });
+
+ it('reads a missing exact revision exactly once', async () => {
+ const revisionRead = jest.spyOn(db, 'getPrompt');
+
+ await expect(
+ service.resolvePrompt({
+ groupId: group._id,
+ selection: { type: 'exact', promptId: missingId() },
+ }),
+ ).resolves.toEqual({
+ ok: false,
+ error: { type: 'unavailable_selection', reason: 'revision' },
+ });
+ expect(revisionRead).toHaveBeenCalledTimes(1);
+ });
+
+ it('resolves an exact revision for an unloaded group', async () => {
+ const groupRead = jest.spyOn(db, 'getPromptGroup');
+
+ await expect(
+ service.resolvePrompt({
+ groupId: group._id,
+ selection: { type: 'exact', promptId: production._id },
+ }),
+ ).resolves.toEqual({
+ ok: true,
+ value: {
+ source: 'native',
+ groupId: group._id,
+ promptId: production._id,
+ prompt: 'Production prompt',
+ type: 'text',
+ },
+ });
+ expect(groupRead).toHaveBeenCalledTimes(1);
+ });
+
+ it('throws a PromptStoreError when the group read fails', async () => {
+ const native = createNativePromptAdapter(db);
+ const catalog = createPromptCatalogStore(db);
+ jest.spyOn(catalog, 'getPromptGroup').mockRejectedValue(new Error('group read failed'));
+ const routed = createPromptServiceFromAdapters({
+ native,
+ langfuse: { resolvePrompt: jest.fn() },
+ catalog,
+ grantCreatorOwnership: jest.fn(),
+ logger: { error: jest.fn() },
+ });
+
+ const rejection: unknown = await routed
+ .resolvePrompt({
+ groupId: group._id,
+ selection: { type: 'exact', promptId: production._id },
+ })
+ .catch((caught: unknown) => caught);
+
+ expect(rejection).toBeInstanceOf(PromptStoreError);
+ expect((rejection as PromptStoreError).stage).toBe('read');
+ });
});
describe('getListPromptGroupsByAccess', () => {
@@ -588,10 +688,11 @@ describe('createPromptService', () => {
savePrompt: _save,
makePromptProduction: _promote,
deletePrompt: _delete,
- ...source
+ ...native
} = createNativePromptAdapter(db);
const readOnly = createPromptServiceFromAdapters({
- source,
+ native,
+ langfuse: { resolvePrompt: jest.fn() },
catalog: createPromptCatalogStore(db),
grantCreatorOwnership: jest.fn(),
logger: { error: jest.fn() },
@@ -610,4 +711,294 @@ describe('createPromptService', () => {
await expect(readOnly.getPrompts({ groupId: group._id })).resolves.toHaveLength(1);
});
});
+
+ describe('routing by source', () => {
+ function makeLangfuseGroup(overrides: Partial<PromptGroupRecord> = {}): PromptGroupRecord {
+ return {
+ _id: missingId(),
+ name: 'Langfuse group',
+ author,
+ authorName: 'Author',
+ source: 'langfuse',
+ sourcePromptName: 'langfuse-prompt',
+ ...overrides,
+ };
+ }
+
+ function makeLangfuseResolved(
+ overrides: Partial<LangfuseResolvedPrompt> & { readonly groupId: string },
+ ): LangfuseResolvedPrompt {
+ return {
+ source: 'langfuse',
+ prompt: 'Langfuse prompt text',
+ type: 'text',
+ version: 3,
+ labels: ['production'],
+ ...overrides,
+ };
+ }
+
+ it('dispatches a Langfuse group to the Langfuse adapter', async () => {
+ const langfuseGroup = makeLangfuseGroup();
+ const resolved = makeLangfuseResolved({ groupId: langfuseGroup._id });
+ const resolvePrompt = jest.fn().mockResolvedValue({ ok: true, value: resolved });
+ const routed = createPromptServiceFromAdapters({
+ native: createNativePromptAdapter(db),
+ langfuse: { resolvePrompt },
+ catalog: createPromptCatalogStore(db),
+ grantCreatorOwnership: jest.fn(),
+ logger: { error: jest.fn() },
+ });
+
+ await expect(
+ routed.resolvePrompt({
+ groupId: langfuseGroup._id,
+ selection: { type: 'production' },
+ loadedGroup: langfuseGroup,
+ }),
+ ).resolves.toEqual({ ok: true, value: resolved });
+ expect(resolvePrompt).toHaveBeenCalledWith({
+ group: langfuseGroup,
+ selection: { type: 'production' },
+ loadedRevision: undefined,
+ });
+ });
+
+ it('rejects a disallowed source before calling the adapter', async () => {
+ const langfuseGroup = makeLangfuseGroup();
+ const resolvePrompt = jest.fn();
+ const routed = createPromptServiceFromAdapters({
+ native: createNativePromptAdapter(db),
+ langfuse: { resolvePrompt },
+ catalog: createPromptCatalogStore(db),
+ grantCreatorOwnership: jest.fn(),
+ logger: { error: jest.fn() },
+ });
+
+ await expect(
+ routed.resolvePrompt({
+ groupId: langfuseGroup._id,
+ selection: { type: 'production' },
+ loadedGroup: langfuseGroup,
+ allowedSources: ['native'],
+ }),
+ ).resolves.toEqual({
+ ok: false,
+ error: { type: 'unsupported_source', source: 'langfuse' },
+ });
+ expect(resolvePrompt).not.toHaveBeenCalled();
+ });
+
+ it('content-filters a resolved Langfuse prompt the same as native content', async () => {
+ const langfuseGroup = makeLangfuseGroup();
+ const resolved = makeLangfuseResolved({
+ groupId: langfuseGroup._id,
+ prompt: 'Contains PRIVATE-VALUE',
+ });
+ const resolvePrompt = jest.fn().mockResolvedValue({ ok: true, value: resolved });
+ const routed = createPromptServiceFromAdapters({
+ native: createNativePromptAdapter(db),
+ langfuse: { resolvePrompt },
+ catalog: createPromptCatalogStore(db),
+ grantCreatorOwnership: jest.fn(),
+ logger: { error: jest.fn() },
+ });
+
+ await expect(
+ routed.resolvePrompt({
+ groupId: langfuseGroup._id,
+ selection: { type: 'production' },
+ loadedGroup: langfuseGroup,
+ filters,
+ }),
+ ).resolves.toMatchObject({ ok: false, error: { type: 'blocked_content' } });
+ });
+
+ it('returns unsupported for savePrompt on a Langfuse group', async () => {
+ const langfuseGroup = makeLangfuseGroup();
+
+ await expect(
+ service.savePrompt({
+ groupId: langfuseGroup._id,
+ prompt: { prompt: 'Text', type: 'text' },
+ author,
+ loadedGroup: langfuseGroup,
+ }),
+ ).resolves.toEqual({ ok: false, error: { type: 'unsupported', operation: 'savePrompt' } });
+ });
+
+ it('returns unsupported_selection for a version selection on a native group', async () => {
+ await expect(
+ service.resolvePrompt({
+ groupId: group._id,
+ selection: { type: 'version', version: 2 },
+ loadedGroup: group,
+ }),
+ ).resolves.toEqual({ ok: false, error: { type: 'unsupported_selection', source: 'native' } });
+ });
+
+ it('rejects a disallowed source for an exact selection with nothing preloaded', async () => {
+ const langfuseGroup = makeLangfuseGroup();
+ const catalog = createPromptCatalogStore(db);
+ jest.spyOn(catalog, 'getPromptGroup').mockResolvedValue(langfuseGroup);
+ const native = createNativePromptAdapter(db);
+ const revisionRead = jest.spyOn(native, 'getPrompt');
+ const resolvePrompt = jest.fn();
+ const routed = createPromptServiceFromAdapters({
+ native,
+ langfuse: { resolvePrompt },
+ catalog,
+ grantCreatorOwnership: jest.fn(),
+ logger: { error: jest.fn() },
+ });
+
+ await expect(
+ routed.resolvePrompt({
+ groupId: langfuseGroup._id,
+ selection: { type: 'exact', promptId: production._id },
+ allowedSources: ['native'],
+ }),
+ ).resolves.toEqual({
+ ok: false,
+ error: { type: 'unsupported_source', source: 'langfuse' },
+ });
+ expect(resolvePrompt).not.toHaveBeenCalled();
+ expect(revisionRead).not.toHaveBeenCalled();
+ });
+
+ it('returns unsupported_selection for an exact selection dispatched to the Langfuse adapter', async () => {
+ const langfuseGroup = makeLangfuseGroup();
+ const catalog = createPromptCatalogStore(db);
+ jest.spyOn(catalog, 'getPromptGroup').mockResolvedValue(langfuseGroup);
+ const resolvePrompt = jest.fn().mockResolvedValue({
+ ok: false,
+ error: { type: 'unsupported_selection', source: 'langfuse' },
+ });
+ const routed = createPromptServiceFromAdapters({
+ native: createNativePromptAdapter(db),
+ langfuse: { resolvePrompt },
+ catalog,
+ grantCreatorOwnership: jest.fn(),
+ logger: { error: jest.fn() },
+ });
+
+ await expect(
+ routed.resolvePrompt({
+ groupId: langfuseGroup._id,
+ selection: { type: 'exact', promptId: production._id },
+ }),
+ ).resolves.toEqual({
+ ok: false,
+ error: { type: 'unsupported_selection', source: 'langfuse' },
+ });
+ expect(resolvePrompt).toHaveBeenCalledWith({
+ group: langfuseGroup,
+ selection: { type: 'exact', promptId: production._id },
+ loadedRevision: undefined,
+ });
+ });
+
+ it('returns no revisions for a Langfuse group', async () => {
+ const langfuseGroup = makeLangfuseGroup();
+
+ await expect(service.getPrompts({ groupId: langfuseGroup._id })).resolves.toEqual([]);
+ });
+
+ it('treats a stored group with no source field as native', async () => {
+ // A group with no `source` field at all, not a `native` value.
+ // `toPromptGroupRecord` is the only place that defaults it, so routing,
+ // `allowedSources` and `savePrompt` must all agree the default is native
+ // rather than treating the absence as unresolved.
+ await mongoose.models.PromptGroup.collection.updateOne(
+ { _id: new Types.ObjectId(group._id) },
+ { $unset: { source: '' } },
+ );
+
+ await expect(
+ service.resolvePrompt({ groupId: group._id, selection: { type: 'production' } }),
+ ).resolves.toMatchObject({ ok: true, value: { source: 'native', promptId: production._id } });
+ await expect(
+ service.resolvePrompt({
+ groupId: group._id,
+ selection: { type: 'production' },
+ allowedSources: ['native'],
+ }),
+ ).resolves.toMatchObject({ ok: true, value: { source: 'native' } });
+ await expect(
+ service.savePrompt({
+ groupId: group._id,
+ prompt: { prompt: 'Mixed-version revision', type: 'text' },
+ author,
+ }),
+ ).resolves.toMatchObject({ ok: true });
+ });
+ });
+
+ describe('the always-built Langfuse adapter', () => {
+ const originalPromptSyncFlag = process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE;
+
+ afterEach(() => {
+ if (originalPromptSyncFlag === undefined) {
+ delete process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE;
+ } else {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = originalPromptSyncFlag;
+ }
+ });
+
+ function makeLangfuseGroup(overrides: Partial<PromptGroupRecord> = {}): PromptGroupRecord {
+ return {
+ _id: missingId(),
+ name: 'Langfuse group',
+ author,
+ authorName: 'Author',
+ source: 'langfuse',
+ sourcePromptName: 'langfuse-prompt',
+ ...overrides,
+ };
+ }
+
+ it('routes a Langfuse group to the Langfuse adapter, whose resolver reads the base config by role', async () => {
+ process.env.LANGFUSE_PROMPT_SYNC_AVAILABLE = 'true';
+ const langfuseGroup = makeLangfuseGroup();
+ const findConfigByPrincipal = jest.spyOn(db, 'findConfigByPrincipal');
+ const withLangfuse = createPromptService({ db, grantPermission, getAppConfig });
+
+ // No stored base config, so the resolver's own `promptSync.enabled` check fails
+ // the request as `disabled`.
+ await expect(
+ withLangfuse.resolvePrompt({
+ groupId: langfuseGroup._id,
+ selection: { type: 'production' },
+ loadedGroup: langfuseGroup,
+ }),
+ ).resolves.toEqual({
+ ok: false,
+ error: { type: 'source_unavailable', source: 'langfuse', reason: 'disabled' },
+ });
+ expect(findConfigByPrincipal).toHaveBeenCalledWith(
+ PrincipalType.ROLE,
+ BASE_CONFIG_PRINCIPAL_ID,
+ );
+ });
+
+ it('rejects a Langfuse group excluded by allowedSources without reading config', async () => {
+ const langfuseGroup = makeLangfuseGroup();
+ const findConfigByPrincipal = jest.spyOn(db, 'findConfigByPrincipal');
+ const nativeOnly = createPromptService({ db, grantPermission, getAppConfig });
+
+ await expect(
+ nativeOnly.resolvePrompt({
+ groupId: langfuseGroup._id,
+ selection: { type: 'production' },
+ loadedGroup: langfuseGroup,
+ allowedSources: ['native'],
+ }),
+ ).resolves.toEqual({
+ ok: false,
+ error: { type: 'unsupported_source', source: 'langfuse' },
+ });
+ expect(findConfigByPrincipal).not.toHaveBeenCalled();
+ expect(getAppConfig).not.toHaveBeenCalled();
+ });
+ });
});
diff --git a/packages/api/src/prompts/service.ts b/packages/api/src/prompts/service.ts
index 70c225e8b5..997a937148 100644
--- a/packages/api/src/prompts/service.ts
+++ b/packages/api/src/prompts/service.ts
@@ -1,4 +1,4 @@
-import { logger } from '@librechat/data-schemas';
+import { logger, BASE_CONFIG_PRINCIPAL_ID } from '@librechat/data-schemas';
import { AccessRoleIds, PrincipalType, ResourceType } from 'librechat-data-provider';
import type { FiltersConfig, TDeletePromptResponse } from 'librechat-data-provider';
import type {
@@ -10,6 +10,7 @@ import type {
PromptGroupRecord,
ResolvePromptInput,
PromptServiceError,
+ PromptSourceAdapter,
PromptServiceResult,
PromptCreationResult,
CreatePromptGroupInput,
@@ -17,6 +18,7 @@ import type {
MakePromptProductionResult,
} from './types';
import type { ProjectedStoredPrompt, ProjectedStoredPromptGroup } from './protection';
+import type { CreateLangfuseSourceResolverDeps } from '../langfuse/promptSync';
import {
inspectPromptContent,
projectStoredPrompts,
@@ -34,6 +36,8 @@ import {
selectionUnavailableReason,
} from './native';
import { safeValidatePromptGroupUpdate, safeValidatePromptPayload } from './schemas';
+import { createLangfuseSourceResolver } from '../langfuse/promptSync';
+import { createLangfusePromptAdapter } from './langfuse';
import { withPromptStage } from './errors';
type WithPromptFilters<T> = T & { readonly filters?: FiltersConfig };
@@ -65,6 +69,7 @@ export interface PromptService {
readonly groupId: string;
readonly prompt: unknown;
readonly author: string;
+ readonly loadedGroup?: PromptGroupRecord | null;
}>,
): Promise<PromptServiceResult<{ readonly prompt: PromptRecord }>>;
/**
@@ -120,28 +125,50 @@ function inspect(
return finding == null ? null : { ok: false, error: { type: 'blocked_content', finding } };
}
-/** Builds the prompt service from a content source, a catalog store and an ownership grant. */
+/** Builds the prompt service from a native adapter, a Langfuse adapter, a catalog
+ * store and an ownership grant. */
export function createPromptServiceFromAdapters(adapters: PromptServiceAdapters): PromptService {
- const { source, catalog, grantCreatorOwnership, logger } = adapters;
+ const { native, langfuse, catalog, grantCreatorOwnership, logger } = adapters;
+ const adaptersBySource: Record<PromptGroupRecord['source'], PromptSourceAdapter> = {
+ native,
+ langfuse,
+ };
const readPrompt = (promptId: string, loaded?: PromptRecord | null) =>
loaded?._id === promptId
? Promise.resolve(loaded)
- : withPromptStage('read', () => source.getPrompt(promptId));
+ : withPromptStage('read', () => native.getPrompt(promptId));
+
+ const readGroup = (groupId: string, loaded?: PromptGroupRecord | null) =>
+ loaded?._id === groupId
+ ? Promise.resolve(loaded)
+ : withPromptStage('read', () => catalog.getPromptGroup(groupId));
return {
- async resolvePrompt({ filters, ...input }) {
- const resolved = await source.resolvePrompt(input);
- if (resolved == null) {
+ async resolvePrompt({
+ groupId,
+ selection,
+ loadedGroup,
+ loadedRevision,
+ filters,
+ allowedSources,
+ }) {
+ const group = await readGroup(groupId, loadedGroup);
+ if (group == null) {
return {
ok: false,
- error: {
- type: 'unavailable_selection',
- reason: selectionUnavailableReason(input.selection),
- },
+ error: { type: 'unavailable_selection', reason: selectionUnavailableReason(selection) },
};
}
- return inspect({ prompt: resolved.prompt }, filters) ?? { ok: true, value: resolved };
+ if (allowedSources != null && !allowedSources.includes(group.source)) {
+ return { ok: false, error: { type: 'unsupported_source', source: group.source } };
+ }
+ const adapter = adaptersBySource[group.source];
+ const resolved = await adapter.resolvePrompt({ group, selection, loadedRevision });
+ if (!resolved.ok) {
+ return resolved;
+ }
+ return inspect({ prompt: resolved.value.prompt }, filters) ?? resolved;
},
async getListPromptGroupsByAccess(input) {
@@ -171,7 +198,9 @@ export function createPromptServiceFromAdapters(adapters: PromptServiceAdapters)
},
async getPrompts({ groupId, filters }) {
- const prompts = await withPromptStage('read', () => source.getPrompts(groupId));
+ // Keyed by groupId against the native `Prompt` collection: a Langfuse group has no
+ // rows there, so this already resolves to `[]` for one without a source check.
+ const prompts = await withPromptStage('read', () => native.getPrompts(groupId));
return projectStoredPrompts(prompts, filters);
},
@@ -202,7 +231,7 @@ export function createPromptServiceFromAdapters(adapters: PromptServiceAdapters)
if (rejection != null) {
return rejection;
}
- const value = await source.createPromptGroup({ ...input, group, prompt: validation.data });
+ const value = await native.createPromptGroup({ ...input, group, prompt: validation.data });
const groupId = value.prompt?.groupId;
if (value.prompt?._id && groupId) {
try {
@@ -217,8 +246,8 @@ export function createPromptServiceFromAdapters(adapters: PromptServiceAdapters)
return { ok: true, value };
},
- async savePrompt({ groupId, prompt, author, filters }) {
- if (!source.savePrompt) {
+ async savePrompt({ groupId, prompt, author, filters, loadedGroup }) {
+ if (!native.savePrompt) {
return unsupported('savePrompt');
}
if (!prompt) {
@@ -228,11 +257,17 @@ export function createPromptServiceFromAdapters(adapters: PromptServiceAdapters)
if (!validation.success) {
return invalidInput(validation.error.issues[0]?.message ?? 'Invalid prompt');
}
+ // A missing group is left to the write below; only a group that is known and not
+ // native blocks a native revision from being added to it.
+ const group = await readGroup(groupId, loadedGroup);
+ if (group != null && group.source !== 'native') {
+ return unsupported('savePrompt');
+ }
const rejection = inspect({ prompt: validation.data }, filters);
if (rejection != null) {
return rejection;
}
- const save = source.savePrompt;
+ const save = native.savePrompt;
const value = await withPromptStage('write', () =>
save({ groupId, prompt: validation.data, author }),
);
@@ -240,10 +275,7 @@ export function createPromptServiceFromAdapters(adapters: PromptServiceAdapters)
},
async getPromptGroup({ groupId, loadedGroup, filters }) {
- const group =
- loadedGroup?._id === groupId
- ? loadedGroup
- : await withPromptStage('read', () => source.getPromptGroup(groupId));
+ const group = await readGroup(groupId, loadedGroup);
if (group == null) {
return null;
}
@@ -281,7 +313,7 @@ export function createPromptServiceFromAdapters(adapters: PromptServiceAdapters)
},
async makePromptProduction({ promptId, loadedRevision, filters }) {
- if (!source.makePromptProduction) {
+ if (!native.makePromptProduction) {
return unsupported('makePromptProduction');
}
const revision = await readPrompt(promptId, loadedRevision);
@@ -289,16 +321,16 @@ export function createPromptServiceFromAdapters(adapters: PromptServiceAdapters)
if (rejection != null) {
return rejection;
}
- const promote = source.makePromptProduction;
+ const promote = native.makePromptProduction;
const value = await withPromptStage('write', () => promote(promptId));
return { ok: true, value, groupId: revision?.groupId };
},
async deletePrompt(input) {
- if (!source.deletePrompt) {
+ if (!native.deletePrompt) {
return unsupported('deletePrompt');
}
- return { ok: true, value: await source.deletePrompt(input) };
+ return { ok: true, value: await native.deletePrompt(input) };
},
deletePromptGroup: (groupId) => catalog.deletePromptGroup(groupId),
@@ -315,15 +347,36 @@ export interface PromptServiceDependencies {
accessRoleId: AccessRoleIds;
grantedBy: string;
}) => Promise<unknown>;
+ /** Reads the app config a Langfuse content read resolves against. Configuration —
+ * the deployment gate, the tenant's prompt-sync switch, and whether a connection
+ * can be built from it — decides at request time whether a Langfuse group's
+ * `resolvePrompt` reaches Langfuse or returns `source_unavailable`; the caller
+ * never decides whether Langfuse exists. */
+ readonly getAppConfig: CreateLangfuseSourceResolverDeps['getAppConfig'];
}
-/** Builds the prompt service from the LibreChat database methods and permission service. */
+/**
+ * Builds the prompt service from the LibreChat database methods and permission service.
+ * Every prompt source LibreChat supports has an adapter here, including Langfuse:
+ * `getAppConfig` builds its source resolver, which reads the deployment's base config
+ * through `db.findConfigByPrincipal`. Configuration, not the caller, decides whether a
+ * Langfuse group's `resolvePrompt` reaches Langfuse or returns
+ * `source_unavailable{reason:'disabled'|'not_configured'|'source_changed'}`.
+ */
export function createPromptService({
db,
grantPermission,
+ getAppConfig,
}: PromptServiceDependencies): PromptService {
return createPromptServiceFromAdapters({
- source: createNativePromptAdapter(db),
+ native: createNativePromptAdapter(db),
+ langfuse: createLangfusePromptAdapter({
+ resolveSource: createLangfuseSourceResolver({
+ findBaseConfig: () =>
+ db.findConfigByPrincipal(PrincipalType.ROLE, BASE_CONFIG_PRINCIPAL_ID),
+ getAppConfig,
+ }),
+ }),
catalog: createPromptCatalogStore(db),
grantCreatorOwnership: async ({ userId, groupId }) => {
await grantPermission({
diff --git a/packages/api/src/prompts/types.ts b/packages/api/src/prompts/types.ts
index 0304d11108..ab87e4f231 100644
--- a/packages/api/src/prompts/types.ts
+++ b/packages/api/src/prompts/types.ts
@@ -1,10 +1,12 @@
import type {
FiltersConfig,
+ PrincipalType,
TCreatePromptRecord,
TDeletePromptResponse,
TMakePromptProductionResponse,
} from 'librechat-data-provider';
import type { PromptGroupSource } from '@librechat/data-schemas';
+import type { StoredBaseConfig } from '../langfuse/promptSync';
import type { ProtectionFinding } from '../protection/types';
export type PromptKind = 'text' | 'chat';
@@ -58,15 +60,30 @@ export interface PromptGroupRecord {
export type PromptSelection =
| { readonly type: 'production' }
- | { readonly type: 'exact'; readonly promptId: string };
+ | { readonly type: 'exact'; readonly promptId: string }
+ /** Langfuse only; the native adapter returns `unsupported_selection` for it. */
+ | { readonly type: 'version'; readonly version: number };
-export interface ResolvedPrompt {
+export interface NativeResolvedPrompt {
+ readonly source: 'native';
readonly groupId: string;
readonly promptId: string;
readonly prompt: string;
readonly type: PromptKind;
}
+/** A Langfuse prompt is always text: a chat prompt is rejected before it reaches here. */
+export interface LangfuseResolvedPrompt {
+ readonly source: 'langfuse';
+ readonly groupId: string;
+ readonly prompt: string;
+ readonly type: 'text';
+ readonly version: number;
+ readonly labels: readonly string[];
+}
+
+export type ResolvedPrompt = NativeResolvedPrompt | LangfuseResolvedPrompt;
+
/** The raw creation body plus the server-supplied creator. */
export type CreatePromptGroupInput = Omit<TCreatePromptRecord, 'authorName'> & {
readonly authorName?: string;
@@ -111,7 +128,19 @@ export type PromptServiceError =
readonly type: 'unavailable_selection';
readonly reason: 'production' | 'revision';
}
- | { readonly type: 'unsupported'; readonly operation: PromptOperation };
+ | { readonly type: 'unsupported'; readonly operation: PromptOperation }
+ /** The selection is not valid for `source` (for example `version` on a native group,
+ * or `exact` on a Langfuse group). */
+ | { readonly type: 'unsupported_selection'; readonly source: PromptGroupSource }
+ /** Returned by the `allowedSources` check in `resolvePrompt`, before any adapter runs. */
+ | { readonly type: 'unsupported_source'; readonly source: PromptGroupSource }
+ | {
+ readonly type: 'source_unavailable';
+ readonly source: 'langfuse';
+ readonly reason: 'disabled' | 'not_configured' | 'source_changed';
+ }
+ | { readonly type: 'source_not_found'; readonly source: 'langfuse' }
+ | { readonly type: 'unsupported_content'; readonly reason: 'chat_prompt' };
export type PromptServiceResult<T> =
| { readonly ok: true; readonly value: T }
@@ -132,16 +161,31 @@ export interface ResolvePromptInput {
readonly loadedGroup?: PromptGroupRecord | null;
readonly loadedRevision?: PromptRecord | null;
readonly filters?: FiltersConfig;
+ /** Restricts dispatch to these sources; any other source returns `unsupported_source`
+ * before an adapter or network call runs. Agent-link resolution passes `['native']`. */
+ readonly allowedSources?: readonly PromptGroupSource[];
}
/**
- * Operations that need source content. Mutations are optional: a source that cannot
- * perform one leaves it out, and the service returns an `unsupported` result.
+ * Resolves a group's content for a selection. One adapter per `PromptGroupSource`; the
+ * service picks it from `group.source` and dispatches the already-resolved `group`, so
+ * an adapter never has to look its own group up.
*/
export interface PromptSourceAdapter {
- /** Returns null when the selection is not available in the group. */
- resolvePrompt(input: Omit<ResolvePromptInput, 'filters'>): Promise<ResolvedPrompt | null>;
- getPromptGroup(groupId: string): Promise<PromptGroupRecord | null>;
+ resolvePrompt(input: {
+ readonly group: PromptGroupRecord;
+ readonly selection: PromptSelection;
+ readonly loadedRevision?: PromptRecord | null;
+ }): Promise<PromptServiceResult<ResolvedPrompt>>;
+}
+
+/**
+ * The native adapter additionally performs every operation that is keyed by revision ID
+ * rather than by group — those stay native-only by construction, since a Langfuse group
+ * has no local `Prompt` rows. Mutations are optional: a source that cannot perform one
+ * leaves it out, and the service returns an `unsupported` result.
+ */
+export interface NativePromptAdapter extends PromptSourceAdapter {
getPrompt(promptId: string): Promise<PromptRecord | null>;
getPrompts(groupId: string): Promise<readonly PromptRecord[]>;
createPromptGroup(input: CreatePromptGroupInput): Promise<PromptCreationResult>;
@@ -156,6 +200,7 @@ export interface PromptSourceAdapter {
/** Local catalog operations that do not depend on the content source. */
export interface PromptCatalogStore {
+ getPromptGroup(groupId: string): Promise<PromptGroupRecord | null>;
getListPromptGroupsByAccess(
input: Pick<PromptListInput, 'accessibleIds' | 'name' | 'category' | 'limit' | 'after'>,
): Promise<PromptListResult>;
@@ -194,14 +239,24 @@ export interface PromptDatabase {
updatePromptGroup(filter: { _id: string }, data: Record<string, unknown>): Promise<object>;
incrementPromptGroupUsage(groupId: string): Promise<{ numberOfGenerations: number }>;
deletePromptGroup(filter: { _id: string }): Promise<{ message: string }>;
+ /** Reads the deployment's base config, which the Langfuse adapter's source resolver
+ * checks for the prompt-sync switch. Returns the plain override document, not the
+ * Mongoose model `~/models` resolves it from. */
+ findConfigByPrincipal(
+ principalType: PrincipalType,
+ principalId: string,
+ ): Promise<StoredBaseConfig | null>;
}
export interface PromptServiceAdapters {
/**
- * The content source for every prompt group. The service does not select a source for
- * each group: a group has no source field, and some operations receive only a revision ID.
+ * The content source for a group whose `source` is `native`, and for every operation
+ * keyed by revision ID rather than by group (`createPromptGroup`, `getPrompt`,
+ * `savePrompt`, `makePromptProduction`, `deletePrompt`), which stay native-only.
*/
- readonly source: PromptSourceAdapter;
+ readonly native: NativePromptAdapter;
+ /** The content source for a group whose `source` is `langfuse`. */
+ readonly langfuse: PromptSourceAdapter;
readonly catalog: PromptCatalogStore;
readonly grantCreatorOwnership: (input: {
readonly userId: string;
diff --git a/packages/data-provider/src/api-endpoints.ts b/packages/data-provider/src/api-endpoints.ts
index bf33ec8ee0..e281f0c310 100644
--- a/packages/data-provider/src/api-endpoints.ts
+++ b/packages/data-provider/src/api-endpoints.ts
@@ -461,6 +461,9 @@ export const getCustomConfigSpeech = () => `${speech()}/config/get`;
export const getPromptGroup = (_id: string) => `${prompts()}/groups/${_id}`;
+export const resolvePromptGroup = (_id: string, version?: number) =>
+ `${getPromptGroup(_id)}/resolve${buildQuery({ version })}`;
+
export const getPromptGroupsWithFilters = (filter: object) => {
let url = `${prompts()}/groups`;
// Filter out undefined/null values
diff --git a/packages/data-provider/src/config.spec.ts b/packages/data-provider/src/config.spec.ts
index 4b22aa5164..f01e1f33bd 100644
--- a/packages/data-provider/src/config.spec.ts
+++ b/packages/data-provider/src/config.spec.ts
@@ -1522,6 +1522,24 @@ describe('agent event runtime config', () => {
});
});
+ it('accepts a configured prompt resolve rate limit', () => {
+ const result = configSchema.safeParse({
+ version: '1.0',
+ rateLimits: {
+ promptResolve: { userMax: 30, userWindowInMinutes: 2 },
+ },
+ });
+
+ expect(result.success).toBe(true);
+ if (!result.success) {
+ return;
+ }
+ expect(result.data.rateLimits?.promptResolve).toEqual({
+ userMax: 30,
+ userWindowInMinutes: 2,
+ });
+ });
+
it('does not let removed checkpoint fields control memory-checkpointer validation', () => {
const result = configSchema.safeParse({
version: '1.0',
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index da7d74b98b..e002bfe315 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -2724,6 +2724,13 @@ export const rateLimitSchema = z.object({
userWindowInMinutes: z.number().positive().optional(),
})
.optional(),
+ /** Limits GET /prompts/groups/:groupId/resolve; keyed by the authenticated user. */
+ promptResolve: z
+ .object({
+ userMax: z.number().int().positive().optional(),
+ userWindowInMinutes: z.number().positive().optional(),
+ })
+ .optional(),
fileUploads: z
.object({
ipMax: z.number().optional(),
diff --git a/packages/data-provider/src/data-service.ts b/packages/data-provider/src/data-service.ts
index 629d9fd586..af7a8cccab 100644
--- a/packages/data-provider/src/data-service.ts
+++ b/packages/data-provider/src/data-service.ts
@@ -1340,6 +1340,13 @@ export function getPromptGroup(id: string): Promise<t.TPromptGroup> {
return request.get(endpoints.getPromptGroup(id));
}
+export function resolvePromptGroup(
+ id: string,
+ version?: number,
+): Promise<t.TResolvedPromptResponse> {
+ return request.get(endpoints.resolvePromptGroup(id, version));
+}
+
export function createPrompt(payload: t.TCreatePrompt): Promise<t.TCreatePromptResponse> {
return request.post(endpoints.postPrompt(), payload);
}
diff --git a/packages/data-provider/src/types.ts b/packages/data-provider/src/types.ts
index ccb25a9a62..d6cceccd7e 100644
--- a/packages/data-provider/src/types.ts
+++ b/packages/data-provider/src/types.ts
@@ -1247,6 +1247,47 @@ export type TGetRandomPromptsRequest = {
skip: number;
};
+/** `GET /api/prompts/groups/:groupId/resolve`. Native resolves the group's
+ * production; Langfuse fetches text content live, by label `production` or
+ * an exact `version`, with no cache. */
+export type TResolvedNativePrompt = {
+ source: 'native';
+ groupId: string;
+ promptId: string;
+ prompt: string;
+ type: TPrompt['type'];
+};
+
+export type TResolvedLangfusePrompt = {
+ source: 'langfuse';
+ groupId: string;
+ prompt: string;
+ type: 'text';
+ version: number;
+ labels: string[];
+};
+
+export type TResolvedPromptResponse = TResolvedNativePrompt | TResolvedLangfusePrompt;
+
+/** `code` values the `/resolve` route returns, including the Langfuse request
+ * failure codes relayed through `toLangfusePromptErrorResponse` (`unauthorized`,
+ * `timeout`, `upstream`, `invalid_response`). A `blocked_content` rejection uses
+ * `ContentFilterBlockResponse` instead, which has no `code` field. Not every
+ * error response carries a `code`: a rate-limited 429 or an unexpected 500
+ * returns only `{ message }`, and the resource-access middleware's 403/404
+ * returns `{ error, message }`. */
+export type TPromptResolveErrorCode =
+ | 'invalid_request'
+ | 'not_found'
+ | 'unsupported_type'
+ | 'not_available'
+ | 'not_configured'
+ | 'source_changed'
+ | 'unauthorized'
+ | 'timeout'
+ | 'upstream'
+ | 'invalid_response';
+
export type TCustomConfigSpeechResponse = { [key: string]: string };
export type TUserTermsResponse = {