From fb3b299de627c14df2116ef0ed9d1b9fe22d116e Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Fri, 13 Nov 2026 13:02:39 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=AA=AA=20feat:=20Add=20Agent=20Identity?= =?UTF-8?q?=20to=20Provider=20and=20MCP=20Header=20Templates=20(#18113)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: resolve executing agent ids in MCP header templates * test: preserve MCP config source literal types * πŸͺͺ feat: Forward the Active Agent Id in Request Header Placeholders A gateway in front of LibreChat sees the user, the conversation and the message, but not which agent is running β€” so it cannot attribute spend per agent, apply per-agent limits, or tell agent traffic from plain chat. Adds `{{LIBRECHAT_AGENT_ID}}` as its own namespace beside the user / body / OpenID ones, resolving wherever the existing request placeholders already work. The value is the primary agent's, derived once per run, so subagent steps and auxiliary calls (summarization, titles, activity labels, memory extraction) forward the id of the turn they belong to rather than their own. Only persisted agents resolve: ephemeral ids embed user-authored preset text that is unsafe in a header value, so ephemeral runs and non-agent requests resolve to an empty value rather than forwarding literal template text. No behaviour change unless the placeholder is configured. The MCP surface (#14303) is not covered β€” its connection classification derives from `ALLOWED_BODY_FIELDS`, so a new namespace needs a follow-up. (cherry picked from commit 8a3f1016f0dcdde2bdf3b43a3c90283130ce3b55) * test: cover shared provider and MCP agent header resolution * docs: clarify absent agent placeholder resolution * fix: preserve agent header boundaries across transport lifecycles * fix: retain Google header provenance during agent resolution --------- Co-authored-by: JiΕ™Γ­ Krejčí <51734696+krejcji@users.noreply.github.com> --- api/server/controllers/agents/client.js | 3 + api/server/services/MCP.js | 18 +- api/server/services/MCP.spec.js | 112 ++++++----- librechat.example.yaml | 14 +- .../agents/__tests__/run-agentHeaders.test.ts | 160 +++++++++++++++ .../__tests__/run-summarization.test.ts | 72 +++++++ .../api/src/agents/activityLabels/host.ts | 4 +- packages/api/src/agents/memory.ts | 9 +- packages/api/src/agents/run.ts | 39 +++- .../src/endpoints/google/initialize.spec.ts | 68 +++++++ .../api/src/endpoints/google/initialize.ts | 1 + packages/api/src/endpoints/google/llm.ts | 6 +- packages/api/src/index.ts | 1 + packages/api/src/mcp/MCPManager.ts | 15 +- packages/api/src/mcp/UserConnectionManager.ts | 12 +- .../api/src/mcp/__tests__/MCPManager.test.ts | 34 ++++ packages/api/src/mcp/__tests__/agent.test.ts | 113 +++++++++++ packages/api/src/mcp/agent.ts | 26 +++ packages/api/src/mcp/request.ts | 9 + packages/api/src/mcp/utils.ts | 20 +- packages/api/src/types/http.ts | 2 + packages/api/src/utils/env.spec.ts | 188 +++++++++++++++++- packages/api/src/utils/env.ts | 112 ++++++++++- packages/api/src/utils/headers.spec.ts | 63 +++++- packages/api/src/utils/headers.ts | 42 +++- 25 files changed, 1041 insertions(+), 102 deletions(-) create mode 100644 packages/api/src/agents/__tests__/run-agentHeaders.test.ts create mode 100644 packages/api/src/mcp/__tests__/agent.test.ts create mode 100644 packages/api/src/mcp/agent.ts diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.js index c924a03d51..f9637dfb39 100644 --- a/api/server/controllers/agents/client.js +++ b/api/server/controllers/agents/client.js @@ -12,6 +12,7 @@ const { sanitizeTitle, payloadParser, createSafeUser, + createSafeAgent, initializeAgent, resolveConfigHeaders, resolveRequestTenantId, @@ -3498,6 +3499,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), }); @@ -6290,6 +6292,7 @@ class AgentClient extends BaseClient { conversationId: this.conversationId, parentMessageId: this.parentMessageId, }, + agent: createSafeAgent(this.options.agent), }); try { diff --git a/api/server/services/MCP.js b/api/server/services/MCP.js index c5f5f13900..4ac0606158 100644 --- a/api/server/services/MCP.js +++ b/api/server/services/MCP.js @@ -23,6 +23,7 @@ const { resolveJsonSchemaRefs, sanitizeGeminiSchema, processMCPEnv, + createAgentMCPTool, preProcessGraphTokens, createMCPReauthenticationPrompt, createMCPInitializationOAuthPrompts, @@ -848,7 +849,11 @@ async function reconnectServer({ * @param {import('librechat-data-provider').TMCPAppsPolicy} [params.mcpApps] - Request-admitted MCP Apps policy. * @returns { Promise unknown}>> } An object with `_call` method to execute the tool input. */ -async function createMCPTools({ +function createMCPTools(params) { + return createAgentMCPTool(params, createMCPToolsImpl); +} + +async function createMCPToolsImpl({ agentId, res, mcpPermissionContext, @@ -1002,7 +1007,12 @@ async function createMCPTools({ * @param {number} [params.jobCreatedAt] - The generation epoch that owns emitted events. * @returns { Promise unknown}> } An object with `_call` method to execute the tool input. */ -async function createMCPTool({ +function createMCPTool(params) { + return createAgentMCPTool(params, createMCPToolImpl); +} + +async function createMCPToolImpl({ + invokeTool, agentId, res, mcpPermissionContext, @@ -1192,6 +1202,7 @@ async function createMCPTool({ } return createToolInstance({ + invokeTool, scheduledBearerInvocation: bindScheduledMCPBearerInvocation( requestScopedConnections, agentId, @@ -1231,6 +1242,7 @@ async function createMCPTool({ } function createToolInstance({ + invokeTool, scheduledBearerInvocation, scheduledMCPInvocation, res, @@ -1358,7 +1370,7 @@ function createToolInstance({ * as the jwt-bearer assertion. */ return await oauthPrompt.run(() => - mcpManager.callTool({ + invokeTool(mcpManager, { scheduledBearerInvocation, scheduledMCPInvocation, serverName, diff --git a/api/server/services/MCP.spec.js b/api/server/services/MCP.spec.js index 2a32fb71cf..f2482aac37 100644 --- a/api/server/services/MCP.spec.js +++ b/api/server/services/MCP.spec.js @@ -2779,64 +2779,70 @@ describe('User parameter passing tests', () => { expect(mockCallTool).toHaveBeenCalledTimes(2); }); - it('should pass the captured user to MCPManager.callTool when invocation config omits configurable.user', async () => { - const mockUser = { id: 'captured-user', email: 'captured@example.com', role: 'USER' }; - const mockRes = { write: jest.fn(), flush: jest.fn() }; - const { getRoleByName } = require('~/models'); - getRoleByName.mockResolvedValue({ - permissions: { - [PermissionTypes.MCP_SERVERS]: { - [Permissions.USE]: true, - }, - }, - }); - - const mockCallTool = jest.fn().mockResolvedValue(['ok', null]); - mockGetMCPManager.mockReturnValue({ - callTool: mockCallTool, - }); - - const mcpTool = await createMCPTool({ - res: mockRes, - user: mockUser, - toolKey: `test-tool${D}test-server`, - provider: 'openai', - userMCPAuthMap: {}, - availableTools: { - [`test-tool${D}test-server`]: { - function: { - description: 'Cached tool', - parameters: { type: 'object', properties: {} }, + it.each(['agent_root', 'agent_child'])( + 'passes captured user and tool owner %s when invocation context changes', + async (agentId) => { + const mockUser = { id: 'captured-user', email: 'captured@example.com', role: 'USER' }; + const mockRes = { write: jest.fn(), flush: jest.fn() }; + const { getRoleByName } = require('~/models'); + getRoleByName.mockResolvedValue({ + permissions: { + [PermissionTypes.MCP_SERVERS]: { + [Permissions.USE]: true, }, }, - }, - }); + }); - await expect( - mcpTool.invoke( - {}, - { - configurable: { - user_id: mockUser.id, - }, - metadata: { - provider: 'openai', - thread_id: 'thread-1', - run_id: 'run-1', - }, - toolCall: {}, - }, - ), - ).resolves.toBe('ok'); + const mockCallTool = jest.fn().mockResolvedValue(['ok', null]); + mockGetMCPManager.mockReturnValue({ + callTool: mockCallTool, + }); - expect(mockCallTool).toHaveBeenCalledWith( - expect.objectContaining({ - serverName: 'test-server', - toolName: 'test-tool', + const mcpTool = await createMCPTool({ + agentId, + res: mockRes, user: mockUser, - }), - ); - }); + toolKey: `test-tool${D}test-server`, + provider: 'openai', + userMCPAuthMap: {}, + availableTools: { + [`test-tool${D}test-server`]: { + function: { + description: 'Cached tool', + parameters: { type: 'object', properties: {} }, + }, + }, + }, + }); + + await expect( + mcpTool.invoke( + {}, + { + configurable: { + user_id: mockUser.id, + requestBody: { conversationId: 'conversation', agentId: 'agent_spoofed' }, + }, + metadata: { + provider: 'openai', + thread_id: 'thread-1', + run_id: 'run-1', + }, + toolCall: {}, + }, + ), + ).resolves.toBe('ok'); + + expect(mockCallTool).toHaveBeenCalledWith( + expect.objectContaining({ + serverName: 'test-server', + toolName: 'test-tool', + user: mockUser, + requestBody: { conversationId: 'conversation', agentId }, + }), + ); + }, + ); it('should pass captured request body when invocation config omits requestBody', async () => { const mockUser = { id: 'captured-body-user', email: 'captured@example.com', role: 'USER' }; diff --git a/librechat.example.yaml b/librechat.example.yaml index e787b91954..9bd3f21ac7 100644 --- a/librechat.example.yaml +++ b/librechat.example.yaml @@ -769,6 +769,9 @@ actions: # # a `{{LIBRECHAT_BODY_*}}` placeholder here no longer hides the server's tool list. # requestHeaders: # X-Conversation-Id: "{{LIBRECHAT_BODY_CONVERSATIONID}}" +# # Persisted agent that owns the executing tool, including a subagent's own tools. +# # Empty for plain chat or an ephemeral agent. Available on operator-defined servers. +# X-Agent-Id: "{{LIBRECHAT_AGENT_ID}}" # puppeteer: # type: stdio # command: npx @@ -1157,11 +1160,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 097291c6d5..3038b8b2d0 100644 --- a/packages/api/src/agents/__tests__/run-summarization.test.ts +++ b/packages/api/src/agents/__tests__/run-summarization.test.ts @@ -2505,6 +2505,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, @@ -3324,6 +3374,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 a44d1f1b33..31f8f8cdbe 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; @@ -481,6 +482,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 c20cc81971..2bb6867e3d 100644 --- a/packages/api/src/agents/memory.ts +++ b/packages/api/src/agents/memory.ts @@ -32,7 +32,7 @@ import type { FormattedMemoriesResult, AppConfig, } 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'; @@ -785,6 +785,7 @@ export async function processMemory({ streamId = null, jobCreatedAt, user, + primaryAgent, tenantId, appConfig, isTemporary, @@ -796,6 +797,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; @@ -950,6 +952,7 @@ ${memory ?? 'No existing memories'}`; user: user ? createSafeUser(user) : undefined, tenantId, body: { conversationId, messageId }, + agent: primaryAgent, }); const artifactPromises: Promise[] = []; @@ -1081,6 +1084,7 @@ export async function createMemoryProcessor({ streamId = null, jobCreatedAt, user, + primaryAgent, tenantId, appConfig, isTemporary, @@ -1092,6 +1096,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; @@ -1176,6 +1182,7 @@ export async function createMemoryProcessor({ setMemory: memoryMethods.setMemory, deleteMemory: memoryMethods.deleteMemory, user, + primaryAgent, tenantId, appConfig, isTemporary, diff --git a/packages/api/src/agents/run.ts b/packages/api/src/agents/run.ts index c18fa322bb..9b90a9bde4 100644 --- a/packages/api/src/agents/run.ts +++ b/packages/api/src/agents/run.ts @@ -134,6 +134,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 { shareDeferredDefinitions } from '~/agents/deferral'; import { buildToolApprovalHooks } from '~/agents/hitl/hooks'; import { getAgentCheckpointer } from '~/agents/checkpointer'; @@ -146,7 +147,6 @@ import { getCustomEndpointConfig } from '~/app/config'; import { applyTestRunHook } from '~/agents/testHook'; import { frameDynamicInstructions } from './tail'; import { isUserProvided } from '~/utils/common'; -import { createSafeUser } from '~/utils/env'; /** Expected shape of JSON tool search results */ interface ToolSearchJsonResult { @@ -943,7 +943,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); @@ -983,6 +988,7 @@ function resolveOpenAISummarization( user: createSafeUser(headerContext.user), tenantId: headerContext.tenantId, body: headerContext.requestBody, + agent: headerContext.agent, }), transportTimeouts: resolveModelTransportTimeouts(appConfig?.endpoints?.agents), }, @@ -1076,7 +1082,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; @@ -1124,6 +1135,7 @@ function resolveAzureSummarization( user: createSafeUser(headerContext.user), tenantId: headerContext.tenantId, body: headerContext.requestBody, + agent: headerContext.agent, }); const { llmConfig, configOptions } = getOpenAIConfig( azureOptions.azureOpenAIApiKey, @@ -1209,7 +1221,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']; @@ -1280,6 +1297,7 @@ function resolveSummarizationProvider( user: createSafeUser(headerContext.user), tenantId: headerContext.tenantId, body: headerContext.requestBody, + agent: headerContext.agent, }) : undefined; /** @@ -1402,7 +1420,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; @@ -2505,6 +2528,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(); @@ -2568,6 +2594,7 @@ export async function createRun({ user: createSafeUser(user), tenantId, body: requestBody, + agent: safePrimaryAgent, }); const modelParameters = normalizeAgentModelParameters(agent.model_parameters); @@ -2577,7 +2604,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/endpoints/google/initialize.spec.ts b/packages/api/src/endpoints/google/initialize.spec.ts index 6645cd7978..0c176dc241 100644 --- a/packages/api/src/endpoints/google/initialize.spec.ts +++ b/packages/api/src/endpoints/google/initialize.spec.ts @@ -26,6 +26,7 @@ jest.mock('~/utils', () => ({ })); import { initializeGoogle } from './initialize'; +import { resolveConfigHeaders } from '~/utils/headers'; function createDb(): EndpointDbMethods { return { @@ -70,6 +71,73 @@ describe('initializeGoogle', () => { process.env = originalEnv; }); + it.each(['google', 'all'])( + 'resolves %s agent headers after initialization without touching provider auth', + async (endpoint) => { + const apiKey = 'literal-${NOT_AN_ENV_VAR}-{{LIBRECHAT_AGENT_ID}}'; + process.env.GOOGLE_KEY = apiKey; + process.env.GOOGLE_AUTH_HEADER = 'true'; + mockIsEnabled.mockImplementation((value) => value === 'true'); + mockGetGoogleConfig.mockImplementationOnce((credentials, options) => + jest.requireActual('./llm').getGoogleConfig(credentials, options), + ); + const req = createReq(); + if (!req.config) throw new Error('Expected initialized test config'); + const configuredHeaders = { 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}' }; + req.config.endpoints = + endpoint === 'google' + ? { google: { headers: configuredHeaders } } + : { all: { headers: configuredHeaders } }; + const result = await initializeGoogle({ + req, + endpoint: EModelEndpoint.google, + model_parameters: { model: 'gemini-2.5-flash' }, + db: createDb(), + }); + const headers = (result.llmConfig as { customHeaders?: Record }) + .customHeaders; + expect(headers?.['X-Agent-Id']).toBe('{{LIBRECHAT_AGENT_ID}}'); + expect(headers?.Authorization).toBe(`Bearer ${apiKey}`); + resolveConfigHeaders({ llmConfig: result.llmConfig, agent: { id: 'agent_root' } }); + const resolved = (result.llmConfig as { customHeaders?: Record }) + .customHeaders; + expect(resolved?.['X-Agent-Id']).toBe('agent_root'); + expect(resolved?.Authorization).toBe(`Bearer ${apiKey}`); + }, + ); + + it.each([ + ['google', 'Authorization'], + ['google', 'authorization'], + ['all', 'Authorization'], + ['all', 'authorization'], + ])('resolves operator %s %s without provider-managed auth', async (endpoint, name) => { + process.env.GOOGLE_KEY = 'test-key'; + mockIsEnabled.mockImplementation((value) => value === 'true'); + mockGetGoogleConfig.mockImplementationOnce((credentials, options) => + jest.requireActual('./llm').getGoogleConfig(credentials, options), + ); + const req = createReq(); + if (!req.config) throw new Error('Expected initialized test config'); + const headers = { [name]: 'Bearer {{LIBRECHAT_USER_TENANT_ID}}/{{LIBRECHAT_AGENT_ID}}' }; + req.config.endpoints = endpoint === 'google' ? { google: { headers } } : { all: { headers } }; + const result = await initializeGoogle({ + req, + endpoint: EModelEndpoint.google, + model_parameters: { model: 'gemini-2.5-flash' }, + db: createDb(), + }); + const runConfig = { ...result.llmConfig }; + resolveConfigHeaders({ + llmConfig: runConfig, + tenantId: 'tenant-one', + agent: { id: 'agent_root' }, + }); + expect((runConfig as { customHeaders?: Record }).customHeaders?.[name]).toBe( + 'Bearer tenant-one/agent_root', + ); + }); + it('forces Vertex AI ADC config and ignores GOOGLE_KEY for vertexai endpoint', async () => { process.env.GOOGLE_KEY = 'test-api-key'; process.env.VERTEX_PROJECT_ID = 'fiery-catwalk-385918'; diff --git a/packages/api/src/endpoints/google/initialize.ts b/packages/api/src/endpoints/google/initialize.ts index 3af58cedb8..f3b54b89bc 100644 --- a/packages/api/src/endpoints/google/initialize.ts +++ b/packages/api/src/endpoints/google/initialize.ts @@ -107,6 +107,7 @@ export async function initializeGoogle( user, body: requestBody, stripUnresolved: true, + preserveAgentId: true, }) : undefined; diff --git a/packages/api/src/endpoints/google/llm.ts b/packages/api/src/endpoints/google/llm.ts index f3fc121cdf..4f9d5695df 100644 --- a/packages/api/src/endpoints/google/llm.ts +++ b/packages/api/src/endpoints/google/llm.ts @@ -4,7 +4,7 @@ import { googleSettings, AuthKeys, removeNullishValues } from 'librechat-data-pr import type { GoogleClientOptions, VertexAIClientOptions } from '@librechat/agents'; import type { GoogleAIToolType } from '@librechat/agents/langchain/google-common'; import type * as t from '~/types'; -import { mergeHeaders } from '~/utils/headers'; +import { mergeGoogleHeaders } from '~/utils/headers'; import { isEnabled } from '~/utils'; type GoogleThinkingLevel = 'THINKING_LEVEL_UNSPECIFIED' | 'MINIMAL' | 'LOW' | 'MEDIUM' | 'HIGH'; @@ -660,8 +660,8 @@ export function getGoogleConfig( * `options.headers` are already resolved by `initializeGoogle`, keeping the * key-derived `Authorization` out of placeholder/env expansion. */ - if (options.headers && Object.keys(options.headers).length > 0) { - (llmConfig as GoogleClientOptions).customHeaders = mergeHeaders( + if (options.headers || (llmConfig as GoogleClientOptions).customHeaders) { + (llmConfig as GoogleClientOptions).customHeaders = mergeGoogleHeaders( options.headers, (llmConfig as GoogleClientOptions).customHeaders as Record | undefined, ); diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts index 69419260b5..74e0fcad23 100644 --- a/packages/api/src/index.ts +++ b/packages/api/src/index.ts @@ -49,6 +49,7 @@ export * from './mcp/authorization'; export * from './mcp/authorizationRetry'; export * from './mcp/assistants'; export * from './mcp/request'; +export * from './mcp/agent'; export * from './mcp/reinitialize'; export * from './mcp/icons'; /* Utilities */ diff --git a/packages/api/src/mcp/MCPManager.ts b/packages/api/src/mcp/MCPManager.ts index 95938476d7..1923817da4 100644 --- a/packages/api/src/mcp/MCPManager.ts +++ b/packages/api/src/mcp/MCPManager.ts @@ -80,6 +80,7 @@ import { MCPConnectionFactory } from './MCPConnectionFactory'; import { processMCPEnv, isPluginSourced } from '~/utils/env'; import { guardUnattendedOAuth } from './oauth/unattended'; import { OAuthLifecycleRelay } from './oauth/pending'; +import { getMCPAgentConnectionKey } from './utils'; import { isOwnedAbortError } from '~/utils/errors'; import { markMCPToolResultError } from './status'; import { withMCPRequestSignal } from './signal'; @@ -350,7 +351,11 @@ export class MCPManager extends UserConnectionManager { } const capabilityProfile = opts.capabilityProfile ?? STANDARD_MCP_CAPABILITY_PROFILE; - const connectionKey = getMCPUserConnectionPoolKey(userId, opts.serverName, capabilityProfile); + const connectionKey = getMCPAgentConnectionKey( + getMCPUserConnectionPoolKey(userId, opts.serverName, capabilityProfile), + connectionTarget.serverConfig, + opts.requestBody, + ); const requestConnection = opts.requestScopedConnections?.connections.get(connectionKey) as | MCPConnection | undefined; @@ -1183,10 +1188,10 @@ Please follow these instructions when using tools from the respective MCP server connection.stopReconnecting(); await this.waitForConnectionBorrowersToDrain(connection); recoverySignal.throwIfAborted(); - const requestConnectionKey = getMCPUserConnectionPoolKey( - user.id, - serverName, - capabilityProfile, + const requestConnectionKey = getMCPAgentConnectionKey( + getMCPUserConnectionPoolKey(user.id, serverName, capabilityProfile), + serverConfig, + requestBody, ); if (requestScopedConnections?.connections.get(requestConnectionKey) === connection) { requestScopedConnections.connections.delete(requestConnectionKey); diff --git a/packages/api/src/mcp/UserConnectionManager.ts b/packages/api/src/mcp/UserConnectionManager.ts index 33f1c48034..8c36a4de0b 100644 --- a/packages/api/src/mcp/UserConnectionManager.ts +++ b/packages/api/src/mcp/UserConnectionManager.ts @@ -7,6 +7,7 @@ import { canUseAppConnection, canBackfillSharedServerInstructions, getMissingRuntimeBodyPlaceholderFields, + getMCPAgentConnectionKey, hasRuntimeUrlPlaceholders, isUserSourced, requiresEphemeralUserConnection, @@ -513,7 +514,12 @@ export abstract class UserConnectionManager { ? getMCPRequestSignal(requestScopedConnections) : opts.signal; opts.signal?.throwIfAborted(); - const requestConnectionKey = getUserConnectionKey(userId, serverName, capabilityProfile); + const baseConnectionKey = getUserConnectionKey(userId, serverName, capabilityProfile); + const requestConnectionKey = getMCPAgentConnectionKey( + baseConnectionKey, + config, + opts.requestBody, + ); const existing = requestScopedConnections.connections.get(requestConnectionKey) as | MCPConnection | undefined; @@ -574,7 +580,7 @@ export abstract class UserConnectionManager { logPrefix: `[MCP][User: ${userId}][${serverName}]`, }); const creationGuard: ConnectionCreationGuard = { cancelledBy: null }; - this.registerConnectionCreation(requestConnectionKey, creationGuard); + this.registerConnectionCreation(baseConnectionKey, creationGuard); const connectionPromise = this.createUserConnectionWithLifecycleRestarts( { ...opts, @@ -608,7 +614,7 @@ export abstract class UserConnectionManager { return connection; }) .finally(() => { - this.unregisterConnectionCreation(requestConnectionKey, creationGuard); + this.unregisterConnectionCreation(baseConnectionKey, creationGuard); if (requestScopedConnections.pending.get(requestConnectionKey) === connectionPromise) requestScopedConnections.pending.delete(requestConnectionKey); }); diff --git a/packages/api/src/mcp/__tests__/MCPManager.test.ts b/packages/api/src/mcp/__tests__/MCPManager.test.ts index bf2fb4fdff..ae2d36e1d4 100644 --- a/packages/api/src/mcp/__tests__/MCPManager.test.ts +++ b/packages/api/src/mcp/__tests__/MCPManager.test.ts @@ -7491,6 +7491,40 @@ describe('MCPManager', () => { expect(clearRecoveryState).toHaveBeenCalledTimes(3); }); + it.each(['server', 'user'] as const)( + 'fences agent-scoped creation during %s teardown', + async (scope) => { + mockAppConnections({ has: jest.fn().mockResolvedValue(false) }); + (mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({ + type: 'streamable-http', + url: 'https://mcp.example.com/mcp', + headers: { 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}' }, + }); + const manager = await MCPManager.createInstance(newMCPServersConfig()); + const context = { connections: new Map(), pending: new Map() }; + (MCPConnectionFactory.create as jest.Mock).mockReset(); + (MCPConnectionFactory.create as jest.Mock).mockImplementation(async () => { + const connection = newUserConnection(); + if (scope === 'server') { + await manager.disconnectUserConnection(userId, serverName, { reason: 'lifecycle' }); + } else { + await manager.disconnectUserConnections(userId, { reason: 'lifecycle' }); + } + return connection; + }); + await expect( + manager.getUserConnection({ + serverName, + user: mockUser, + requestBody: { agentId: 'agent_child' }, + requestScopedConnections: context, + }), + ).rejects.toThrow('Connection creation was cancelled during teardown'); + expect(context.connections.size).toBe(0); + expect(context.pending.size).toBe(0); + }, + ); + it('fails a creation that a lifecycle teardown keeps cancelling on every attempt', async () => { mockAppConnections({ has: jest.fn().mockResolvedValue(false) }); (mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({ diff --git a/packages/api/src/mcp/__tests__/agent.test.ts b/packages/api/src/mcp/__tests__/agent.test.ts new file mode 100644 index 0000000000..07861242f5 --- /dev/null +++ b/packages/api/src/mcp/__tests__/agent.test.ts @@ -0,0 +1,113 @@ +import type { MCPOptions } from 'librechat-data-provider'; +import { + getMCPRequestScope, + getMCPAgentConnectionKey, + requiresEphemeralUserConnection, + getMissingRuntimeBodyPlaceholderFields, +} from '../utils'; +import { withMCPAgentContext } from '../request'; +import { createAgentMCPTool } from '../agent'; +import { processMCPEnv } from '~/utils/env'; + +const config: MCPOptions = { + type: 'streamable-http', + url: 'https://mcp.example.com/mcp', + headers: { 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}' }, +}; + +describe('MCP executing agent context', () => { + it.each(['agent_root', 'agent_child'])( + 'binds construction and invocation for %s in TypeScript', + async (agentId) => { + const input = { + agentId, + requestBody: { agentId: 'agent_spoofed', conversationId: 'conversation' }, + }; + const callTool = jest.fn().mockResolvedValue(['ok', null]); + const tool = createAgentMCPTool(input, ({ requestBody, invokeTool }) => ({ + requestBody, + invoke: () => + invokeTool( + { callTool }, + { + serverName: 'analytics', + toolName: 'select', + provider: 'openai', + flowManager: {} as Parameters[1]['flowManager'], + requestBody: { agentId: 'agent_override', messageId: 'runtime' }, + }, + ), + })); + expect(tool.requestBody.agentId).toBe(agentId); + await expect(tool.invoke()).resolves.toEqual(['ok', null]); + expect(callTool).toHaveBeenCalledWith( + expect.objectContaining({ + requestBody: { agentId, messageId: 'runtime' }, + }), + ); + expect(input.requestBody.agentId).toBe('agent_spoofed'); + }, + ); + + it('replaces browser-supplied identity with the tool owner without mutating the request', () => { + const body = { conversationId: 'conversation', agentId: 'agent_spoofed' }; + const root = withMCPAgentContext(body, 'agent_root'); + const child = withMCPAgentContext(body, 'agent_child'); + expect(body.agentId).toBe('agent_spoofed'); + expect(root.agentId).toBe('agent_root'); + expect(child.agentId).toBe('agent_child'); + expect(processMCPEnv({ options: config, body: root })).toMatchObject({ + headers: { 'X-Agent-Id': 'agent_root' }, + }); + expect(processMCPEnv({ options: config, body: child })).toMatchObject({ + headers: { 'X-Agent-Id': 'agent_child' }, + }); + expect(config).toMatchObject({ headers: { 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}' } }); + }); + + it.each([undefined, '', 'ephemeral:my preset', 'agent_bad\r\nInjected: header'])( + 'omits absent or unsafe identity: %s', + (agentId) => { + const body = withMCPAgentContext({ agentId: 'agent_spoofed' }, agentId); + expect(processMCPEnv({ options: config, body })).toMatchObject({ + headers: { 'X-Agent-Id': '' }, + }); + expect(getMissingRuntimeBodyPlaceholderFields(config, body)).toEqual([]); + }, + ); + + it('scopes connections by runtime agent identity', () => { + const root = getMCPAgentConnectionKey('connection', config, { agentId: 'agent_root' }); + const child = getMCPAgentConnectionKey('connection', config, { agentId: 'agent_child' }); + expect(root).not.toBe(child); + expect(getMCPAgentConnectionKey('connection', config, { agentId: 'agent_root' })).toBe(root); + expect(getMCPAgentConnectionKey('connection', { ...config, headers: {} })).toBe('connection'); + expect(getMCPRequestScope(config)).toEqual({ + requestScoped: true, + requiredBodyFields: ['agentId'], + }); + expect(requiresEphemeralUserConnection(config)).toBe(true); + }); + + it('does not let a custom user variable replace the tool owner', () => { + expect( + processMCPEnv({ + options: config, + body: withMCPAgentContext({}, 'agent_root'), + customUserVars: { LIBRECHAT_AGENT_ID: 'agent_spoofed' }, + }), + ).toMatchObject({ headers: { 'X-Agent-Id': 'agent_root' } }); + }); + + it('preserves plugin and user-sourced template boundaries', () => { + for (const source of ['plugin', 'user'] as const) { + const options = { ...config, source }; + expect(processMCPEnv({ options, body: withMCPAgentContext({}, 'agent_root') })).toMatchObject( + { + headers: { 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}' }, + }, + ); + expect(getMCPRequestScope(options).requestScoped).toBe(false); + } + }); +}); diff --git a/packages/api/src/mcp/agent.ts b/packages/api/src/mcp/agent.ts new file mode 100644 index 0000000000..39d640effe --- /dev/null +++ b/packages/api/src/mcp/agent.ts @@ -0,0 +1,26 @@ +import type { MCPManager } from './MCPManager'; +import type { RequestBody } from '~/types'; +import { withMCPAgentContext } from './request'; + +type ToolInvocation = Parameters[0]; +export type AgentMCPToolInvoker = ( + manager: Pick, + invocation: ToolInvocation, +) => ReturnType; + +/** Own the tool identity across construction, runtime overrides, and invocation retries. */ +export function createAgentMCPTool( + input: T, + construct: (bound: T & { invokeTool: AgentMCPToolInvoker }) => R, +): R { + const agentId = input.agentId; + return construct({ + ...input, + requestBody: withMCPAgentContext(input.requestBody, agentId), + invokeTool: (manager, invocation) => + manager.callTool({ + ...invocation, + requestBody: withMCPAgentContext(invocation.requestBody, agentId), + }), + }); +} diff --git a/packages/api/src/mcp/request.ts b/packages/api/src/mcp/request.ts index ab700d07bd..fc673cbb96 100644 --- a/packages/api/src/mcp/request.ts +++ b/packages/api/src/mcp/request.ts @@ -2,9 +2,18 @@ import { logger } from '@librechat/data-schemas'; import { Constants } from 'librechat-data-provider'; import type { MCPRuntimeRequestBody, RequestScopedMCPConnectionStore } from './types'; +import type { RequestBody } from '~/types'; export type { MCPRuntimeRequestBody } from './types'; +/** Bind MCP templates to the agent that owns the tool, without mutating shared request data. */ +export function withMCPAgentContext(body: RequestBody | undefined, agentId?: string): RequestBody { + return { + ...body, + agentId: agentId && /^agent_[A-Za-z0-9_-]+$/.test(agentId) ? agentId : undefined, + }; +} + /** * Builds the complete request context that runtime MCP placeholders may resolve. * An explicit null parent means a known root turn and becomes the root sentinel. diff --git a/packages/api/src/mcp/utils.ts b/packages/api/src/mcp/utils.ts index decc5a24c1..96fc18b043 100644 --- a/packages/api/src/mcp/utils.ts +++ b/packages/api/src/mcp/utils.ts @@ -193,10 +193,10 @@ const BODY_PLACEHOLDER_FIELDS = Object.fromEntries( ) as Record; const RUNTIME_BODY_FIELD_NAMES = Object.keys(BODY_PLACEHOLDER_FIELDS).join('|'); const RUNTIME_BODY_PLACEHOLDER_PATTERN = new RegExp( - `\\{\\{LIBRECHAT_BODY_(?:${RUNTIME_BODY_FIELD_NAMES})\\}\\}`, + `\\{\\{LIBRECHAT_(?:BODY_(?:${RUNTIME_BODY_FIELD_NAMES})|AGENT_ID)\\}\\}`, ); const RUNTIME_BODY_PLACEHOLDER_CAPTURE_PATTERN = new RegExp( - `\\{\\{LIBRECHAT_BODY_(${RUNTIME_BODY_FIELD_NAMES})\\}\\}`, + `\\{\\{LIBRECHAT_(?:BODY_(${RUNTIME_BODY_FIELD_NAMES})|(AGENT_ID))\\}\\}`, 'g', ); @@ -347,6 +347,10 @@ function addRuntimeBodyPlaceholderFields( if (typeof value === 'string') { for (const candidate of new Set([value, extractEnvVariable(value)])) { for (const match of candidate.matchAll(RUNTIME_BODY_PLACEHOLDER_CAPTURE_PATTERN)) { + if (match[2] === 'AGENT_ID') { + fields.add('agentId'); + continue; + } const placeholderKey = match[1]; const field = placeholderKey ? BODY_PLACEHOLDER_FIELDS[placeholderKey] : undefined; if (field) { @@ -413,6 +417,17 @@ export function getMCPRequestScope(config: UserScopedConnectionConfig): MCPReque return { requestScoped: fields.length > 0, requiredBodyFields: fields }; } +/** Keep initialization, tool discovery, and recovery on the same agent's connection. */ +export function getMCPAgentConnectionKey( + baseKey: string, + config: UserScopedConnectionConfig | undefined, + body?: RequestBody, +): string { + return config && getMCPRequestScope(config).requiredBodyFields.includes('agentId') + ? `${baseKey}:agent:${JSON.stringify(body?.agentId ?? null)}` + : baseKey; +} + /** * Folds the operator's chat-only `requestHeaders` into `headers`, so everything * downstream β€” direct-bearer detection, Graph preprocessing, `processMCPEnv`, @@ -477,6 +492,7 @@ export function getMissingRuntimeBodyPlaceholderFields( requestBody?: RequestBody, ): string[] { return getMCPRequestScope(config).requiredBodyFields.filter((field) => { + if (field === 'agentId') return false; const value = requestBody?.[field]; return value == null || (typeof value === 'string' && value.trim() === ''); }); diff --git a/packages/api/src/types/http.ts b/packages/api/src/types/http.ts index d71957e99f..b6495b52ea 100644 --- a/packages/api/src/types/http.ts +++ b/packages/api/src/types/http.ts @@ -17,6 +17,8 @@ import type { BranchLinks } from '../messages/history'; * (have to use type alias because you can't extend indexed access types like Request['body']) */ export type RequestBody = { + /** Server-assigned MCP tool owner; overwrite browser input at tool construction and invocation. */ + agentId?: string; messageId?: string; fileTokenLimit?: number; conversationId?: string; diff --git a/packages/api/src/utils/env.spec.ts b/packages/api/src/utils/env.spec.ts index b11e72ba81..47906c1b79 100644 --- a/packages/api/src/utils/env.spec.ts +++ b/packages/api/src/utils/env.spec.ts @@ -1,8 +1,14 @@ 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, resolveHeaders, processMCPEnv, encodeHeaderValue } from './env'; +import { + createSafeUser, + createSafeAgent, + resolveHeaders, + processMCPEnv, + encodeHeaderValue, +} from './env'; import { applyRequestHeaders } from '~/mcp/utils'; function isStdioOptions(options: MCPOptions): options is Extract { @@ -2355,3 +2361,181 @@ 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('preserves the template until the provider agent context is available', () => { + const pending = resolveHeaders({ headers: agentHeaders }); + expect(pending).toEqual(agentHeaders); + expect( + resolveHeaders({ headers: pending, agent: persistedAgent, stripUnresolved: true }), + ).toEqual({ 'X-Agent-Id': persistedAgent.id }); + }); + + it('uses the provider agent ahead of body fields and custom variables', () => { + expect( + resolveHeaders({ + headers: agentHeaders, + agent: persistedAgent, + body: { agentId: 'agent_spoofed' }, + customUserVars: { LIBRECHAT_AGENT_ID: 'agent_spoofed' }, + stripUnresolved: true, + }), + ).toEqual({ 'X-Agent-Id': persistedAgent.id }); + }); + + 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 950d578c14..b708d9b3a2 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 { @@ -151,19 +151,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})\\}\\}`) @@ -188,8 +231,10 @@ const OPENID_ACCESS_CREDENTIAL_PLACEHOLDER_PATTERN = * users under that one string). Only for final resolution passes β€” staged * flows that resolve again later with more context must not strip. */ -export function stripUnresolvedPlaceholders(value: string): string { - return value.replace(RESOLVABLE_PLACEHOLDER_PATTERN, ''); +export function stripUnresolvedPlaceholders(value: string, preserveAgentId = false): string { + return value.replace(RESOLVABLE_PLACEHOLDER_PATTERN, (placeholder) => + preserveAgentId && placeholder === '{{LIBRECHAT_AGENT_ID}}' ? placeholder : '', + ); } /** @@ -276,6 +321,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; missing or ephemeral identities become an empty value. + * + * @param value - The string value to process + * @param agent - The agent serving the request + * @returns The processed string with placeholders replaced + */ +export function processAgentPlaceholders(value: string, agent: Partial): string { + if (!agent.id || isEphemeralAgentId(agent.id) || !/^agent_[A-Za-z0-9_-]+$/.test(agent.id)) { + return value.replaceAll('{{LIBRECHAT_AGENT_ID}}', ''); + } + + 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 * @@ -283,6 +356,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 */ @@ -291,6 +365,7 @@ function processSingleValue({ customUserVars, user, body = undefined, + agent = undefined, isHeader = false, dbSourced = false, beforeCredentialResolution, @@ -299,6 +374,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; @@ -320,6 +396,7 @@ function processSingleValue({ */ if (!dbSourced) { value = extractEnvVariable(value); + if (agent) value = processAgentPlaceholders(value, agent); } /** Runs for both dbSourced and non-dbSourced β€” it is the only resolution DB-stored servers get */ @@ -393,6 +470,7 @@ export function processMCPEnv(params: { beforeCredentialResolution?: (value: string) => string; }): MCPOptions { const { options, user, body, beforeCredentialResolution } = params; + const agent = createSafeAgent({ id: body?.agentId }); if (options === null || options === undefined) { return options; @@ -412,7 +490,7 @@ export function processMCPEnv(params: { } /** Derive dbSourced from explicit param OR from dbId on the options (failsafe for callers that forget the flag) */ - const dbSourced = params.dbSourced ?? !!options.dbId; + const dbSourced = params.dbSourced === true || !!options.dbId || options.source === 'user'; /** A shared-server editor can inject old auth-field names into any template. Only * server-declared variables may resolve, including destination-bound API key fields. */ @@ -441,6 +519,7 @@ export function processMCPEnv(params: { const processedEnv: Record = {}; for (const [key, originalValue] of Object.entries(newObj.env)) { processedEnv[key] = processSingleValue({ + agent, user, body, dbSourced, @@ -457,6 +536,7 @@ export function processMCPEnv(params: { for (const originalValue of newObj.args) { processedArgs.push( processSingleValue({ + agent, originalValue, customUserVars, user, @@ -475,6 +555,7 @@ export function processMCPEnv(params: { const processedHeaders: Record = {}; for (const [key, originalValue] of Object.entries(newObj.headers)) { processedHeaders[key] = processSingleValue({ + agent, user, body, dbSourced, @@ -492,6 +573,7 @@ export function processMCPEnv(params: { const processedOAuthHeaders: Record = {}; for (const [key, originalValue] of Object.entries(newObj.oauth_headers)) { processedOAuthHeaders[key] = processSingleValue({ + agent, user, body, dbSourced, @@ -507,6 +589,7 @@ export function processMCPEnv(params: { // Process URL if it exists (for WebSocket, SSE, StreamableHTTP types) if ('url' in newObj && newObj.url) { newObj.url = processSingleValue({ + agent, user, body, dbSourced, @@ -529,6 +612,7 @@ export function processMCPEnv(params: { // token_exchange_method is an enum and shouldn't be processed if (typeof originalValue === 'string') { processedOAuth[key] = processSingleValue({ + agent, user, body, dbSourced, @@ -554,6 +638,8 @@ export function processMCPEnv(params: { * @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 @@ -565,10 +651,13 @@ export function resolveHeaders(options?: { headers: Record | undefined; user?: Partial | { id: string }; body?: RequestBody; + agent?: Partial; customUserVars?: Record; stripUnresolved?: boolean; + /** Google initialization resolves credentials before the agent identity is available. */ + preserveAgentId?: 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 }; @@ -580,6 +669,7 @@ export function resolveHeaders(options?: { customUserVars, user: user as IUser, body, + agent, isHeader: true, // Important: Enable header encoding }); if (!stripUnresolved) { @@ -597,7 +687,7 @@ export function resolveHeaders(options?: { return; } - resolvedHeaders[key] = stripUnresolvedPlaceholders(processed); + resolvedHeaders[key] = stripUnresolvedPlaceholders(processed, options?.preserveAgentId); }); } diff --git a/packages/api/src/utils/headers.spec.ts b/packages/api/src/utils/headers.spec.ts index d534b3ebc3..8afb6a390b 100644 --- a/packages/api/src/utils/headers.spec.ts +++ b/packages/api/src/utils/headers.spec.ts @@ -1,5 +1,11 @@ import type { RunLLMConfig } from '~/types'; -import { mediaTypeEssence, mergeHeaders, resolveConfigHeaders } from './headers'; +import { + mergeHeaders, + mergeGoogleHeaders, + mediaTypeEssence, + resolveModelHeaders, + resolveConfigHeaders, +} from './headers'; describe('mediaTypeEssence', () => { it('returns the bare type for a header with no parameters', () => { @@ -34,6 +40,26 @@ describe('mediaTypeEssence', () => { }); describe('mergeHeaders', () => { + it.each([false, true])( + 'resolves configured Google auth templates while preserving managed credentials: %s', + (hasManagedAuth) => { + const credential = 'Bearer {{LIBRECHAT_USER_TENANT_ID}}/{{LIBRECHAT_AGENT_ID}}'; + const configured = { authorization: credential, 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}' }; + const customHeaders = mergeGoogleHeaders( + configured, + hasManagedAuth ? { Authorization: credential } : undefined, + ); + const llmConfig = { customHeaders }; + resolveConfigHeaders({ llmConfig, tenantId: 'tenant-one', agent: { id: 'agent_root' } }); + expect(llmConfig.customHeaders?.['X-Agent-Id']).toBe('agent_root'); + if (hasManagedAuth) { + expect(llmConfig.customHeaders?.Authorization).toBe(credential); + expect(llmConfig.customHeaders?.authorization).toBeUndefined(); + } else { + expect(llmConfig.customHeaders?.authorization).toBe('Bearer tenant-one/agent_root'); + } + }, + ); it('returns undefined when neither side has headers', () => { expect(mergeHeaders(undefined, undefined)).toBeUndefined(); }); @@ -211,6 +237,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 +295,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..ec7528e2a8 100644 --- a/packages/api/src/utils/headers.ts +++ b/packages/api/src/utils/headers.ts @@ -1,7 +1,8 @@ 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'; +import { resolveHeaders, processAgentPlaceholders } from './env'; const TENANT_ID_HEADER_PLACEHOLDERS = [ '{{LIBRECHAT_USER_TENANTID}}', @@ -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, }); @@ -141,15 +145,31 @@ export function resolveModelHeaders({ * nothing carries across requests. */ const resolvedHeaderMaps = new WeakSet(); +const googleManagedHeaders = new WeakMap>(); + +/** Retain header provenance while layering provider credentials over operator templates. */ +export function mergeGoogleHeaders( + configured?: Record, + managed?: Record, +): Record | undefined { + const merged = mergeHeaders(configured, managed); + if (merged) { + googleManagedHeaders.set( + merged, + new Set(Object.keys(managed ?? {}).map((name) => name.toLowerCase())), + ); + } + return merged; +} /** * Resolves placeholder templates in the outbound request headers of a built LLM * config, mutating it in place. Handles the OpenAI-compatible * `configuration.defaultHeaders` (OpenAI / Azure / custom) and the native * Anthropic `clientOptions.defaultHeaders` (including Vertex) carriers, plus - * tenant-only substitution in native Google `customHeaders`. Google's map is - * otherwise resolved at initialization so provider-managed authorization never - * passes through environment or user-template expansion. + * tenant and agent substitution in native Google `customHeaders`. Google's + * credential and user templates resolve at initialization; provider-managed + * authorization stays opaque during this final pass. * * Resolution runs at request time so request-body placeholders (e.g. * `{{LIBRECHAT_BODY_CONVERSATIONID}}`) resolve against the live request. It is a @@ -165,6 +185,7 @@ export function resolveConfigHeaders({ user, tenantId, body, + agent, customUserVars, }: { /** Partial: this only reads the three provider header carriers, so @@ -176,6 +197,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 +208,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; }; @@ -207,7 +229,15 @@ export function resolveConfigHeaders({ if (customHeadersContainer.customHeaders != null) { const headers = customHeadersContainer.customHeaders; if (!resolvedHeaderMaps.has(headers)) { - customHeadersContainer.customHeaders = resolveTenantPlaceholders(headers, tenantId); + const resolved = resolveTenantPlaceholders(headers, tenantId); + const managed = googleManagedHeaders.get(headers); + for (const [name, value] of Object.entries(headers)) { + resolved[name] = + (managed?.has(name.toLowerCase()) ?? name.toLowerCase() === 'authorization') + ? value + : processAgentPlaceholders(resolved[name], agent ?? {}); + } + customHeadersContainer.customHeaders = resolved; resolvedHeaderMaps.add(customHeadersContainer.customHeaders); } }