diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.js index 746cb5b7e4..493f9444f4 100644 --- a/api/server/controllers/agents/client.js +++ b/api/server/controllers/agents/client.js @@ -11,6 +11,7 @@ const { sanitizeTitle, payloadParser, createSafeUser, + createSafeAgent, initializeAgent, resolveConfigHeaders, resolveRequestTenantId, @@ -3478,6 +3479,7 @@ class AgentClient extends BaseClient { req: this.options.req, res: this.options.res, user: createSafeUser(this.options.req.user), + primaryAgent: createSafeAgent(this.options.agent), tenantId: resolveRequestTenantId(this.options.req), }); @@ -6293,6 +6295,7 @@ class AgentClient extends BaseClient { conversationId: this.conversationId, parentMessageId: this.parentMessageId, }, + agent: createSafeAgent(this.options.agent), }); try { diff --git a/librechat.example.yaml b/librechat.example.yaml index 28ff605949..1c17999aed 100644 --- a/librechat.example.yaml +++ b/librechat.example.yaml @@ -999,11 +999,12 @@ endpoints: # (optional) Custom request headers for the built-in OpenAI / Google endpoints. # Forwarded on every request to the provider (or an AI gateway / reverse proxy # in front of it) while keeping provider-native request shaping intact. Values - # support env vars (${VAR}), user fields ({{LIBRECHAT_USER_*}}), and request-body - # fields ({{LIBRECHAT_BODY_CONVERSATIONID}}). Set the same `headers:` block under - # `endpoints.all` to apply globally across endpoints (endpoint values win on key - # collisions). NOTE: send metadata headers like these only behind a gateway that - # consumes them — native provider APIs ignore unknown headers. + # support env vars (${VAR}), user fields ({{LIBRECHAT_USER_*}}), request-body + # fields ({{LIBRECHAT_BODY_CONVERSATIONID}}), and the active agent id + # ({{LIBRECHAT_AGENT_ID}}). Set the same `headers:` block under `endpoints.all` + # to apply globally across endpoints (endpoint values win on key collisions). + # NOTE: send metadata headers like these only behind a gateway that consumes + # them — native provider APIs ignore unknown headers. # openAI: # headers: # cf-aig-metadata: '{"user_email":"{{LIBRECHAT_USER_EMAIL}}","app":"librechat"}' diff --git a/packages/api/src/agents/__tests__/run-agentHeaders.test.ts b/packages/api/src/agents/__tests__/run-agentHeaders.test.ts new file mode 100644 index 0000000000..c9562c595d --- /dev/null +++ b/packages/api/src/agents/__tests__/run-agentHeaders.test.ts @@ -0,0 +1,160 @@ +import { createRun } from '~/agents/run'; + +/** + * Guards `{{LIBRECHAT_AGENT_ID}}` resolution in `createRun`. The id must be the + * root agent's on every built input, subagents included, so a forwarded header + * matches the id persisted on the response message by + * `BaseClient.getResponseModel` — a gateway attributing spend per agent would + * otherwise bill a delegated step to a different agent than the database records. + * Ephemeral runs must resolve to nothing rather than leaking preset text. + */ + +jest.mock('winston', () => ({ + createLogger: jest.fn(() => ({ + debug: jest.fn(), + warn: jest.fn(), + error: jest.fn(), + info: jest.fn(), + })), + format: Object.assign( + jest.fn((fn) => () => ({ transform: fn })), + { + combine: jest.fn(), + colorize: jest.fn(), + simple: jest.fn(), + label: jest.fn(), + timestamp: jest.fn(), + printf: jest.fn(), + errors: jest.fn(), + splat: jest.fn(), + json: jest.fn(), + }, + ), + addColors: jest.fn(), + transports: { Console: jest.fn(), DailyRotateFile: jest.fn(), File: jest.fn() }, +})); + +jest.mock('@librechat/data-schemas', () => ({ + ...jest.requireActual('@librechat/data-schemas'), + logger: { debug: jest.fn(), warn: jest.fn(), error: jest.fn(), info: jest.fn() }, +})); + +jest.mock('@librechat/agents', () => { + const actual = jest.requireActual('@librechat/agents'); + return { + ...actual, + Run: { + create: jest.fn().mockResolvedValue({ + processStream: jest.fn().mockResolvedValue(undefined), + }), + }, + }; +}); + +jest.mock('~/agents/checkpointer', () => ({ + getAgentCheckpointer: jest.fn().mockResolvedValue({}), +})); + +import { Run } from '@librechat/agents'; + +const AGENT_ID_HEADER = 'X-Agent-Id'; + +/** + * Each agent gets its OWN `configuration.defaultHeaders` object. Sharing one + * reference would let the idempotency `WeakSet` in `resolveConfigHeaders` skip + * the second resolution and return the first agent's already-resolved map, + * which would pass the subagent assertion without ever resolving its headers. + */ +function makeAgent(overrides?: Record) { + return { + id: 'agent_root', + provider: 'openAI', + endpoint: 'openAI', + model: 'gpt-4o', + tools: [], + model_parameters: { + model: 'gpt-4o', + configuration: { + defaultHeaders: { [AGENT_ID_HEADER]: '{{LIBRECHAT_AGENT_ID}}' }, + }, + }, + maxContextTokens: 100_000, + toolContextMap: {}, + ...overrides, + }; +} + +type CapturedInput = Record & { + agentId?: string; + clientOptions?: { configuration?: { defaultHeaders?: Record } }; + subagentConfigs?: Array<{ type?: string; agentInputs?: CapturedInput }>; +}; + +async function captureAgentInputs( + agents: Array>, +): Promise { + await createRun({ + agents: agents as never, + signal: new AbortController().signal, + streaming: true, + streamUsage: true, + }); + const createMock = Run.create as jest.Mock; + expect(createMock).toHaveBeenCalledTimes(1); + const callArgs = createMock.mock.calls[0][0] as { + graphConfig: { agents: CapturedInput[] }; + }; + return callArgs.graphConfig.agents; +} + +function headerOf(input: CapturedInput | undefined): string | undefined { + return input?.clientOptions?.configuration?.defaultHeaders?.[AGENT_ID_HEADER]; +} + +describe('createRun agent-id header resolution', () => { + beforeEach(() => jest.clearAllMocks()); + + it('resolves the placeholder to the running agent id', async () => { + const [rootInput] = await captureAgentInputs([makeAgent()]); + + expect(headerOf(rootInput)).toBe('agent_root'); + }); + + it('resolves a subagent step to the ROOT agent id, not the subagent own id', async () => { + const child = makeAgent({ id: 'agent_child', name: 'Child' }); + const root = makeAgent({ + subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_child'] }, + subagentAgentConfigs: [child], + }); + + const [rootInput] = await captureAgentInputs([root]); + const childInput = rootInput.subagentConfigs?.find( + (config) => config.type === 'agent_child', + )?.agentInputs; + + /** The subagent really is a different agent... */ + expect(childInput?.agentId).toBe('agent_child'); + /** ...yet the forwarded header carries the id the turn is attributed to. */ + expect(headerOf(childInput)).toBe('agent_root'); + expect(headerOf(rootInput)).toBe('agent_root'); + }); + + it('resolves to an empty value for an ephemeral (plain-chat) run', async () => { + const [rootInput] = await captureAgentInputs([makeAgent({ id: 'openAI__gpt-4o___My Preset' })]); + + expect(headerOf(rootInput)).toBe(''); + }); + + it('leaves headers without the placeholder untouched', async () => { + const [rootInput] = await captureAgentInputs([ + makeAgent({ + model_parameters: { + model: 'gpt-4o', + configuration: { defaultHeaders: { 'X-Static': 'value' } }, + }, + }), + ]); + + expect(rootInput.clientOptions?.configuration?.defaultHeaders).toEqual({ 'X-Static': 'value' }); + }); +}); diff --git a/packages/api/src/agents/__tests__/run-summarization.test.ts b/packages/api/src/agents/__tests__/run-summarization.test.ts index 86ed5ed27e..9d1a284d6f 100644 --- a/packages/api/src/agents/__tests__/run-summarization.test.ts +++ b/packages/api/src/agents/__tests__/run-summarization.test.ts @@ -1683,6 +1683,56 @@ describe('Azure deployment alias', () => { expect(azure.headers.get('api-key')).toBe('expanded-azure-key'); }); + it('forwards the primary agent id on OpenAI and Azure summarizer headers', async () => { + jest.replaceProperty(process, 'env', { ...process.env, OPENAI_API_KEY: 'openai-summary-key' }); + const appConfig = makeAppConfig([]); + appConfig.endpoints!.all = { headers: { 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}' } }; + appConfig.endpoints![EModelEndpoint.azureOpenAI] = { + isValid: true, + errors: [], + modelNames: ['gpt-6-astra', 'gpt-4.1-mini'], + modelGroupMap: { 'gpt-6-astra': { group: 'main' }, 'gpt-4.1-mini': { group: 'summary' } }, + groupMap: { + main: { + apiKey: 'test-azure-key', + instanceName: 'test-instance', + version: '2025-04-01-preview', + models: { 'gpt-6-astra': { deploymentName: 'production-deployment' } }, + }, + summary: { + apiKey: 'summary-key', + instanceName: 'summary-instance', + version: '2024-10-21', + models: { 'gpt-4.1-mini': { deploymentName: 'summary-production' } }, + }, + }, + }; + const compact = async (summarizationConfig: SummarizationConfig) => { + (Run.create as jest.Mock).mockClear(); + const agents = await callAndCapture({ + agents: [azureAstraAgent()], + appConfig, + summarizeOnly: true, + summarizationConfig, + }); + const { requests } = await compactSummary(agents); + expect(requests).toHaveLength(1); + return requests[0]; + }; + + const openAI = await compact({ + provider: EModelEndpoint.openAI, + model: 'gpt-4.1-mini', + parameters: { streaming: false }, + }); + expect(openAI.url.origin).toBe('https://api.openai.com'); + expect(openAI.headers.get('X-Agent-Id')).toBe('agent_1'); + + const azure = await compact({ model: 'gpt-4.1-mini', parameters: { streaming: false } }); + expect(azure.url.origin).toBe('https://summary-instance.openai.azure.com'); + expect(azure.headers.get('X-Agent-Id')).toBe('agent_1'); + }); + it("leaves Azure's reserved URL templates to the summary deployment", async () => { jest.replaceProperty(process, 'env', { ...process.env, @@ -2387,6 +2437,28 @@ describe('custom-endpoint provider resolution', () => { expect(configuration.defaultHeaders).toEqual({ 'X-Tenant-ID': 'request-tenant' }); }); + it('forwards the primary agent id in custom-endpoint summarization headers', async () => { + const appConfig = makeAppConfig([ + { + name: 'Agent Gateway', + baseURL: 'https://gateway.example.com/v1', + apiKey: 'gateway-key', + headers: { 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}' }, + }, + ]); + const agents = await callAndCapture({ + agents: [makeAgent({ id: 'agent_gateway' })], + summarizationConfig: { provider: 'Agent Gateway', model: 'summary-model' }, + appConfig, + }); + + const config = agents[0].summarizationConfig as Record; + const parameters = config.parameters as Record; + const configuration = parameters.configuration as Record; + + expect(configuration.defaultHeaders).toEqual({ 'X-Agent-Id': 'agent_gateway' }); + }); + it('forwards PROXY env var into summarization client configuration', async () => { const originalProxy = process.env.PROXY; process.env.PROXY = 'http://proxy.internal:3128'; diff --git a/packages/api/src/agents/activityLabels/host.ts b/packages/api/src/agents/activityLabels/host.ts index 3fdd3e42e6..b2c1f713c4 100644 --- a/packages/api/src/agents/activityLabels/host.ts +++ b/packages/api/src/agents/activityLabels/host.ts @@ -7,10 +7,10 @@ import type { ClientOptions } from '@librechat/agents'; import type { EndpointDbMethods, OpenAIConfiguration, ServerRequest } from '~/types'; import type { ActivityLabelLLM } from './runtime'; import { getProviderConfig } from '~/endpoints/config/providers'; +import { createSafeUser, createSafeAgent } from '~/utils/env'; import { resolveRequestTenantId } from '~/middleware/tenant'; import { resolveConfigHeaders } from '~/utils/headers'; import { omitTitleOptions } from '~/agents/client'; -import { createSafeUser } from '~/utils/env'; /** Additive label fields may precede the rebuilt data-provider artifact in a * package-local typecheck, so keep the endpoint view structural here. */ @@ -111,6 +111,7 @@ export function mapCollectedMetadataToUsage( /** The agent fields the label model resolution needs. */ export interface ActivityLabelAgent { + id?: string; endpoint?: string; provider?: string; model?: string; @@ -485,6 +486,7 @@ export async function resolveActivityLabelModel({ user: createSafeUser(req.user as IUser | undefined), tenantId: resolveRequestTenantId(req), body: ids, + agent: createSafeAgent(agent), }); return { provider, diff --git a/packages/api/src/agents/memory.ts b/packages/api/src/agents/memory.ts index 1e4db22263..8023408623 100644 --- a/packages/api/src/agents/memory.ts +++ b/packages/api/src/agents/memory.ts @@ -31,7 +31,7 @@ import type { IUser, FormattedMemoriesResult, } from '@librechat/data-schemas'; -import type { TAttachment, FiltersConfig, MemoryArtifact } from 'librechat-data-provider'; +import type { Agent, TAttachment, FiltersConfig, MemoryArtifact } from 'librechat-data-provider'; import type { BaseMessage, ToolMessage } from '@librechat/agents/langchain/messages'; import type { DynamicStructuredTool } from '@librechat/agents/langchain/tools'; import type { Response as ServerResponse } from 'express'; @@ -777,6 +777,7 @@ export async function processMemory({ streamId = null, jobCreatedAt, user, + primaryAgent, tenantId, }: { res: ServerResponse; @@ -785,6 +786,7 @@ export async function processMemory({ userId: string | ObjectId; /** Agent partition; omit for the shared personal pool */ agentId?: string; + primaryAgent?: Partial; memory: string; messageId: string; conversationId: string; @@ -936,6 +938,7 @@ ${memory ?? 'No existing memories'}`; user: user ? createSafeUser(user) : undefined, tenantId, body: { conversationId, messageId }, + agent: primaryAgent, }); const artifactPromises: Promise[] = []; @@ -1050,6 +1053,7 @@ export async function createMemoryProcessor({ streamId = null, jobCreatedAt, user, + primaryAgent, tenantId, }: { res: ServerResponse; @@ -1058,6 +1062,8 @@ export async function createMemoryProcessor({ userId: string | ObjectId; /** Agent partition; omit for the shared personal pool */ agentId?: string; + /** The primary agent whose turn triggered extraction — see {@link processMemory}. */ + primaryAgent?: Partial; memoryMethods: RequiredMemoryMethods; /** Reuses the request-scoped formatted snapshot for the chat context. */ req?: object; @@ -1139,6 +1145,7 @@ export async function createMemoryProcessor({ setMemory: memoryMethods.setMemory, deleteMemory: memoryMethods.deleteMemory, user, + primaryAgent, tenantId, }); } catch (error) { diff --git a/packages/api/src/agents/run.ts b/packages/api/src/agents/run.ts index 0867a483e1..226bd0fc2c 100644 --- a/packages/api/src/agents/run.ts +++ b/packages/api/src/agents/run.ts @@ -128,6 +128,7 @@ import { buildEffectiveToolApprovalPolicy } from '~/agents/hitl/allow'; import { prepareQueuedCodeFileContext } from '~/files/code/queued'; import { getBuiltInBaseURL } from '~/endpoints/openai/initialize'; import { getProviderConfig } from '~/endpoints/config/providers'; +import { createSafeUser, createSafeAgent } from '~/utils/env'; import { buildToolApprovalHooks } from '~/agents/hitl/hooks'; import { getAgentCheckpointer } from '~/agents/checkpointer'; import { getPluginHookSource } from '~/agents/hooks/source'; @@ -137,7 +138,6 @@ import { buildHITLRunWiring } from '~/agents/hitl/runtime'; import { buildLangfuseConfig } from '~/langfuse/config'; import { applyTestRunHook } from '~/agents/testHook'; import { isUserProvided } from '~/utils/common'; -import { createSafeUser } from '~/utils/env'; /** Expected shape of JSON tool search results */ interface ToolSearchJsonResult { @@ -908,7 +908,12 @@ function resolveOpenAISummarization( model: string, appConfig: AppConfig | undefined, parameters: SummarizationConfig['parameters'], - headerContext: { user?: IUser; tenantId?: string; requestBody?: t.RequestBody }, + headerContext: { + user?: IUser; + tenantId?: string; + requestBody?: t.RequestBody; + agent?: Partial; + }, ): { provider: string; clientOverrides: SummarizationClientOverrides } | undefined { const overrides = summarizationTransportOverrides(parameters); const baseURL = overrides.baseURL ?? getBuiltInBaseURL(EModelEndpoint.openAI); @@ -947,6 +952,7 @@ function resolveOpenAISummarization( user: createSafeUser(headerContext.user), tenantId: headerContext.tenantId, body: headerContext.requestBody, + agent: headerContext.agent, }), transportTimeouts: resolveModelTransportTimeouts(appConfig?.endpoints?.agents), }, @@ -1040,7 +1046,12 @@ function resolveAzureSummarization( model: string, appConfig: AppConfig | undefined, parameters: SummarizationConfig['parameters'], - headerContext: { user?: IUser; tenantId?: string; requestBody?: t.RequestBody }, + headerContext: { + user?: IUser; + tenantId?: string; + requestBody?: t.RequestBody; + agent?: Partial; + }, source?: RunAgent, ): { provider: string; clientOverrides: SummarizationClientOverrides } | undefined { const sourceOptions = source?.model_parameters as Partial | undefined; @@ -1088,6 +1099,7 @@ function resolveAzureSummarization( user: createSafeUser(headerContext.user), tenantId: headerContext.tenantId, body: headerContext.requestBody, + agent: headerContext.agent, }); const { llmConfig, configOptions } = getOpenAIConfig( azureOptions.azureOpenAIApiKey, @@ -1173,7 +1185,12 @@ function resolveAzureSummarization( function resolveSummarizationProvider( rawProvider: string, appConfig: AppConfig | undefined, - headerContext: { user?: IUser; tenantId?: string; requestBody?: t.RequestBody }, + headerContext: { + user?: IUser; + tenantId?: string; + requestBody?: t.RequestBody; + agent?: Partial; + }, target: { model?: string; parameters?: SummarizationConfig['parameters']; @@ -1239,6 +1256,7 @@ function resolveSummarizationProvider( user: createSafeUser(headerContext.user), tenantId: headerContext.tenantId, body: headerContext.requestBody, + agent: headerContext.agent, }) : undefined; /** @@ -1351,7 +1369,12 @@ function shapeSummarizationConfig( fallbackModel: string | undefined, appConfig: AppConfig | undefined, agentEndpoint: string | undefined, - headerContext: { user?: IUser; tenantId?: string; requestBody?: t.RequestBody }, + headerContext: { + user?: IUser; + tenantId?: string; + requestBody?: t.RequestBody; + agent?: Partial; + }, agent?: RunAgent, ) { const rawProvider = config?.provider ?? fallbackProvider; @@ -2379,6 +2402,9 @@ export async function createRun({ /** Admin kill switch for the ask tool — see {@link isAskUserQuestionAdminDisabled}. */ const askToolAdminDisabled = isAskUserQuestionAdminDisabled(appConfig); + /** Resolves `{{LIBRECHAT_AGENT_ID}}`; derived once so subagent steps share the turn's id. */ + const safePrimaryAgent = createSafeAgent(agents[0]); + // Independently initialized agents must reserve the same live paths before advertising uploads. const codeFileAgents = new Map(); const visitedCodeFileAgents = new Set(); @@ -2442,6 +2468,7 @@ export async function createRun({ user: createSafeUser(user), tenantId, body: requestBody, + agent: safePrimaryAgent, }); const modelParameters = normalizeAgentModelParameters(agent.model_parameters); @@ -2451,7 +2478,7 @@ export async function createRun({ selfModel, appConfig, agent.endpoint ?? undefined, - { user, tenantId, requestBody }, + { user, tenantId, requestBody, agent: safePrimaryAgent }, agent, ); const summarization = modelCallbacks?.length diff --git a/packages/api/src/utils/env.spec.ts b/packages/api/src/utils/env.spec.ts index c4597f8da9..0abc6839dd 100644 --- a/packages/api/src/utils/env.spec.ts +++ b/packages/api/src/utils/env.spec.ts @@ -1,9 +1,10 @@ import { Types } from 'mongoose'; import { TokenExchangeMethodEnum } from 'librechat-data-provider'; -import type { MCPOptions } from 'librechat-data-provider'; +import type { Agent, MCPOptions } from 'librechat-data-provider'; import type { IUser } from '@librechat/data-schemas'; import { createSafeUser, + createSafeAgent, resolveHeaders, resolveNestedObject, processMCPEnv, @@ -2656,3 +2657,161 @@ describe('processMCPEnv OpenID re-authentication signalling', () => { } }); }); + +describe('createSafeAgent', () => { + it('returns an empty object for null/undefined agents', () => { + expect(createSafeAgent(null)).toEqual({}); + expect(createSafeAgent(undefined)).toEqual({}); + }); + + it('projects only allowlisted fields, dropping everything else', () => { + const safeAgent = createSafeAgent({ + id: 'agent_HTbJ5rDW0kOOK1a5MPBSt', + name: 'Support Bot', + instructions: 'internal system prompt', + author: 'user-123', + } as Partial); + + expect(safeAgent).toEqual({ id: 'agent_HTbJ5rDW0kOOK1a5MPBSt' }); + }); + + it('omits an absent or null id rather than emitting a null value', () => { + expect(createSafeAgent({})).toEqual({}); + expect(createSafeAgent({ id: null })).toEqual({}); + }); + + it('passes an ephemeral id through — the gate belongs to resolution, not projection', () => { + expect(createSafeAgent({ id: 'openAI__gpt-4o___My Preset' })).toEqual({ + id: 'openAI__gpt-4o___My Preset', + }); + }); +}); + +describe('resolveHeaders agent placeholders', () => { + const agentHeaders = { 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}' }; + const persistedAgent = { id: 'agent_HTbJ5rDW0kOOK1a5MPBSt' }; + + it('resolves the agent id for a persisted agent', () => { + const result = resolveHeaders({ + headers: { ...agentHeaders }, + agent: persistedAgent, + stripUnresolved: true, + }); + + expect(result['X-Agent-Id']).toBe('agent_HTbJ5rDW0kOOK1a5MPBSt'); + }); + + it('resolves alongside user and body placeholders without interfering', () => { + const result = resolveHeaders({ + headers: { + 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}', + 'X-User-Id': '{{LIBRECHAT_USER_ID}}', + 'X-Convo': '{{LIBRECHAT_BODY_CONVERSATIONID}}', + 'Content-Type': 'application/json', + }, + user: { id: 'user-123' }, + body: { conversationId: 'convo-abc' }, + agent: persistedAgent, + stripUnresolved: true, + }); + + expect(result).toEqual({ + 'X-Agent-Id': 'agent_HTbJ5rDW0kOOK1a5MPBSt', + 'X-User-Id': 'user-123', + 'X-Convo': 'convo-abc', + 'Content-Type': 'application/json', + }); + }); + + it('replaces every occurrence within a composite value', () => { + const result = resolveHeaders({ + headers: { 'X-Meta': 'agent={{LIBRECHAT_AGENT_ID}};ref={{LIBRECHAT_AGENT_ID}}' }, + agent: persistedAgent, + stripUnresolved: true, + }); + + expect(result['X-Meta']).toBe( + 'agent=agent_HTbJ5rDW0kOOK1a5MPBSt;ref=agent_HTbJ5rDW0kOOK1a5MPBSt', + ); + }); + + it('strips the placeholder when no agent context is available', () => { + const result = resolveHeaders({ + headers: { ...agentHeaders }, + user: { id: 'user-123' }, + stripUnresolved: true, + }); + + expect(result['X-Agent-Id']).toBe(''); + }); + + it('strips the placeholder for an ephemeral agent id', () => { + const result = resolveHeaders({ + headers: { ...agentHeaders }, + agent: { id: 'openAI__gpt-4o___My Preset' }, + stripUnresolved: true, + }); + + expect(result['X-Agent-Id']).toBe(''); + }); + + it('never forwards user-authored preset text from an ephemeral id', () => { + const result = resolveHeaders({ + headers: { ...agentHeaders }, + agent: { id: 'openAI__gpt-4o___Marić\r\nX-Injected: 1' }, + stripUnresolved: true, + }); + + expect(result['X-Agent-Id']).toBe(''); + }); + + it('strips the placeholder when the agent id is empty', () => { + const result = resolveHeaders({ + headers: { ...agentHeaders }, + agent: { id: '' }, + stripUnresolved: true, + }); + + expect(result['X-Agent-Id']).toBe(''); + }); + + it('preserves the placeholder by default so staged flows can resolve later', () => { + const result = resolveHeaders({ headers: { ...agentHeaders } }); + + expect(result['X-Agent-Id']).toBe('{{LIBRECHAT_AGENT_ID}}'); + }); + + it('leaves headers without the placeholder untouched', () => { + const result = resolveHeaders({ + headers: { 'Content-Type': 'application/json', 'X-Static': 'value' }, + agent: persistedAgent, + stripUnresolved: true, + }); + + expect(result).toEqual({ 'Content-Type': 'application/json', 'X-Static': 'value' }); + }); + + it('resolves from a full agent projected through createSafeAgent', () => { + const result = resolveHeaders({ + headers: { ...agentHeaders }, + agent: createSafeAgent({ + id: 'agent_HTbJ5rDW0kOOK1a5MPBSt', + name: 'Support Bot', + instructions: 'internal system prompt', + } as Partial), + stripUnresolved: true, + }); + + expect(result['X-Agent-Id']).toBe('agent_HTbJ5rDW0kOOK1a5MPBSt'); + }); + + it('does not resolve an unknown agent field', () => { + const result = resolveHeaders({ + headers: { 'X-Agent-Name': '{{LIBRECHAT_AGENT_NAME}}' }, + agent: persistedAgent, + stripUnresolved: true, + }); + + expect(result['X-Agent-Name']).toBe('{{LIBRECHAT_AGENT_NAME}}'); + }); +}); diff --git a/packages/api/src/utils/env.ts b/packages/api/src/utils/env.ts index 70573ae982..67acc70ef8 100644 --- a/packages/api/src/utils/env.ts +++ b/packages/api/src/utils/env.ts @@ -1,6 +1,6 @@ import { logger } from '@librechat/data-schemas'; -import { extractEnvVariable } from 'librechat-data-provider'; -import type { MCPOptions } from 'librechat-data-provider'; +import { extractEnvVariable, isEphemeralAgentId } from 'librechat-data-provider'; +import type { Agent, MCPOptions } from 'librechat-data-provider'; import type { IUser } from '@librechat/data-schemas'; import type { RequestBody } from '~/types'; import { @@ -150,19 +150,62 @@ export function createSafeUser( */ export const ALLOWED_BODY_FIELDS = ['conversationId', 'parentMessageId', 'messageId'] as const; +/** + * List of allowed agent fields that can be used in header placeholders. Kept to + * identifiers the agent owns rather than user-authored content. + */ +const ALLOWED_AGENT_FIELDS = ['id'] as const; + +type AllowedAgentField = (typeof ALLOWED_AGENT_FIELDS)[number]; +type SafeAgent = Pick; + +/** + * Any object carrying agent identity fields, so the projection below accepts a + * full `Agent`, a run-shaped agent, or the narrower agent objects the auxiliary + * generation paths pass around, without those callers coupling to `Agent` itself. + */ +type AgentLike = { [K in AllowedAgentField]?: Agent[K] | null }; + +/** + * Creates a safe agent object containing only allowed fields, mirroring + * `createSafeUser` — call sites project at the boundary rather than hand-building + * a literal, so the allowlist stays the one place that decides what an agent may + * contribute to a header. + * + * @param agent - The agent object to extract safe fields from + * @returns A new object containing only allowed fields + */ +export function createSafeAgent(agent?: AgentLike | null): Partial { + if (!agent) { + return {}; + } + + const safeAgent: Partial = {}; + for (const field of ALLOWED_AGENT_FIELDS) { + const value = agent[field]; + if (value != null) { + Object.assign(safeAgent, { [field]: value }); + } + } + + return safeAgent; +} + const OPENID_PLACEHOLDER_NAMES = `LIBRECHAT_OPENID_(?:${OPENID_TOKEN_FIELDS.join('|')}|TOKEN)`; /** * Matches every placeholder this module knows how to resolve: the enumerated - * `{{LIBRECHAT_USER_*}}`, `{{LIBRECHAT_BODY_*}}`, and `{{LIBRECHAT_OPENID_*}}` - * names. Deliberately excludes unknown names (a typo'd placeholder staying - * literal is diagnosable) and `{{LIBRECHAT_GRAPH_ACCESS_TOKEN}}`, which is - * resolved asynchronously via the OBO flow outside this pipeline. + * `{{LIBRECHAT_USER_*}}`, `{{LIBRECHAT_BODY_*}}`, `{{LIBRECHAT_AGENT_*}}`, and + * `{{LIBRECHAT_OPENID_*}}` names. Deliberately excludes unknown names (a typo'd + * placeholder staying literal is diagnosable) and + * `{{LIBRECHAT_GRAPH_ACCESS_TOKEN}}`, which is resolved asynchronously via the + * OBO flow outside this pipeline. */ const RESOLVABLE_PLACEHOLDER_PATTERN = new RegExp( [ `LIBRECHAT_USER_(?:${ALLOWED_USER_FIELDS.map((field) => field.toUpperCase()).join('|')})`, `LIBRECHAT_BODY_(?:${ALLOWED_BODY_FIELDS.map((field) => field.toUpperCase()).join('|')})`, + `LIBRECHAT_AGENT_(?:${ALLOWED_AGENT_FIELDS.map((field) => field.toUpperCase()).join('|')})`, OPENID_PLACEHOLDER_NAMES, ] .map((names) => `\\{\\{(?:${names})\\}\\}`) @@ -286,6 +329,34 @@ function processBodyPlaceholders(value: string, body: RequestBody): string { return value; } +/** + * Replaces agent field placeholders within a string. + * Recognized placeholders: `{{LIBRECHAT_AGENT_}}` where `` ∈ ALLOWED_AGENT_FIELDS. + * Only persisted agents resolve; ephemeral ids are left for a final pass to strip. + * + * @param value - The string value to process + * @param agent - The agent serving the request + * @returns The processed string with placeholders replaced + */ +function processAgentPlaceholders(value: string, agent: Partial): string { + if (typeof value !== 'string' || !agent.id || isEphemeralAgentId(agent.id)) { + return value; + } + + for (const field of ALLOWED_AGENT_FIELDS) { + const placeholder = `{{LIBRECHAT_AGENT_${field.toUpperCase()}}}`; + if (!value.includes(placeholder)) { + continue; + } + + const fieldValue = agent[field]; + const replacementValue = fieldValue == null ? '' : String(fieldValue); + value = value.replace(new RegExp(placeholder, 'g'), replacementValue); + } + + return value; +} + /** * Processes a single string value by replacing various types of placeholders * @@ -293,6 +364,7 @@ function processBodyPlaceholders(value: string, body: RequestBody): string { * @param customUserVars - Optional custom user variables to replace placeholders * @param user - Optional user object for replacing user field placeholders * @param body - Optional request body object for replacing body field placeholders + * @param agent - Optional agent object for replacing agent field placeholders * @param isHeader - Whether this value will be used in an HTTP header (enables encoding) * @returns The processed string with all placeholders replaced */ @@ -301,6 +373,7 @@ function processSingleValue({ customUserVars, user, body = undefined, + agent = undefined, isHeader = false, dbSourced = false, beforeCredentialResolution, @@ -309,6 +382,7 @@ function processSingleValue({ customUserVars?: Record; user?: Partial; body?: RequestBody; + agent?: Partial; isHeader?: boolean; /** When true, only resolve customUserVars — skip env vars, user/OpenID/body placeholders */ dbSourced?: boolean; @@ -373,6 +447,10 @@ function processSingleValue({ value = processBodyPlaceholders(value, body); } + if (agent) { + value = processAgentPlaceholders(value, agent); + } + return value; } @@ -632,6 +710,8 @@ export function resolveNestedObject(options?: { * @param options.headers - The headers object to process * @param options.user - Optional user object for replacing user field placeholders (can be partial with just id) * @param options.body - Optional request body object for replacing body field placeholders + * @param options.agent - Optional agent serving the request, for replacing agent field + * placeholders. Only persisted agents resolve; see `processAgentPlaceholders`. * @param options.customUserVars - Optional custom user variables to replace placeholders * @param options.stripUnresolved - When true (final resolution passes only), replaces any * remaining resolvable placeholders with an empty string so internal template syntax is @@ -643,10 +723,11 @@ export function resolveHeaders(options?: { headers: Record | undefined; user?: Partial | { id: string }; body?: RequestBody; + agent?: Partial; customUserVars?: Record; stripUnresolved?: boolean; }): Record { - const { headers, user, body, customUserVars, stripUnresolved = false } = options ?? {}; + const { headers, user, body, agent, customUserVars, stripUnresolved = false } = options ?? {}; const inputHeaders = headers ?? {}; const resolvedHeaders: Record = { ...inputHeaders }; @@ -658,6 +739,7 @@ export function resolveHeaders(options?: { customUserVars, user: user as IUser, body, + agent, isHeader: true, // Important: Enable header encoding }); if (!stripUnresolved) { diff --git a/packages/api/src/utils/headers.spec.ts b/packages/api/src/utils/headers.spec.ts index d534b3ebc3..2cd4bc67f8 100644 --- a/packages/api/src/utils/headers.spec.ts +++ b/packages/api/src/utils/headers.spec.ts @@ -1,5 +1,10 @@ import type { RunLLMConfig } from '~/types'; -import { mediaTypeEssence, mergeHeaders, resolveConfigHeaders } from './headers'; +import { + mergeHeaders, + mediaTypeEssence, + resolveModelHeaders, + resolveConfigHeaders, +} from './headers'; describe('mediaTypeEssence', () => { it('returns the bare type for a header with no parameters', () => { @@ -211,6 +216,26 @@ describe('resolveConfigHeaders', () => { expect(llmConfig.configuration?.defaultHeaders).toEqual({ 'X-Tenant-ID': '' }); }); + it('resolves the agent id alongside the tenant in one model header', () => { + const llmConfig = { + configuration: { + defaultHeaders: { 'X-Attribution': '{{LIBRECHAT_USER_TENANT_ID}}/{{LIBRECHAT_AGENT_ID}}' }, + }, + } as unknown as RunLLMConfig; + + resolveConfigHeaders({ + llmConfig, + user, + tenantId: 'request-tenant', + body, + agent: { id: 'agent_abc' }, + }); + + expect(llmConfig.configuration?.defaultHeaders).toEqual({ + 'X-Attribution': 'request-tenant/agent_abc', + }); + }); + it('leaves configs without header maps untouched', () => { const llmConfig = { model: 'gpt-4o', configuration: {} } as unknown as RunLLMConfig; expect(() => resolveConfigHeaders({ llmConfig, user, body })).not.toThrow(); @@ -249,3 +274,18 @@ describe('resolveConfigHeaders', () => { expect(llmConfig.configuration?.defaultHeaders).toEqual({ 'X-LibreChat-User': '' }); }); }); + +describe('resolveModelHeaders', () => { + it('resolves the agent id in a standalone header map without mutating it', () => { + const headers = { 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}' }; + + const resolved = resolveModelHeaders({ + headers, + user: { id: 'user-123' }, + agent: { id: 'agent_abc' }, + }); + + expect(resolved).toEqual({ 'X-Agent-Id': 'agent_abc' }); + expect(headers).toEqual({ 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}' }); + }); +}); diff --git a/packages/api/src/utils/headers.ts b/packages/api/src/utils/headers.ts index 70806d3bb7..78767d3618 100644 --- a/packages/api/src/utils/headers.ts +++ b/packages/api/src/utils/headers.ts @@ -1,4 +1,5 @@ import type { AnthropicClientOptions } from '@librechat/agents'; +import type { Agent } from 'librechat-data-provider'; import type { IUser } from '@librechat/data-schemas'; import type { RequestBody, RunLLMConfig } from '~/types'; import { resolveHeaders } from './env'; @@ -111,18 +112,21 @@ export function resolveModelHeaders({ user, tenantId, body, + agent, customUserVars, }: { headers: Record | undefined; user?: Partial | { id: string }; tenantId?: string; body?: RequestBody; + agent?: Partial; customUserVars?: Record; }): Record { const resolved = resolveHeaders({ headers, user, body, + agent, customUserVars, stripUnresolved: true, }); @@ -165,6 +169,7 @@ export function resolveConfigHeaders({ user, tenantId, body, + agent, customUserVars, }: { /** Partial: this only reads the three provider header carriers, so @@ -176,6 +181,7 @@ export function resolveConfigHeaders({ /** Authoritative request tenant used only for model-header templates. */ tenantId?: string; body?: RequestBody; + agent?: Partial; customUserVars?: Record; }): void { if (llmConfig == null) { @@ -186,7 +192,7 @@ export function resolveConfigHeaders({ if (resolvedHeaderMaps.has(headers)) { return headers; } - const resolved = resolveModelHeaders({ headers, user, tenantId, body, customUserVars }); + const resolved = resolveModelHeaders({ headers, user, tenantId, body, agent, customUserVars }); resolvedHeaderMaps.add(resolved); return resolved; };