LibreChat/api/server/controllers/agents/responses.js
Dustin Healy a1ac175544
💾 feat: Persist and Continue Stored Agent Responses (#17605)
* 💾 feat: Persist and Continue Stored Agent Responses

* fix: unify response persistence and terminal ownership

* fix: Commit Canonical Responses With Conversation History

* test: Keep Interrupted Erasure Payloads Private

* fix: Fence Canonical Response Materialization During Rolling Upgrades
2026-11-10 21:04:01 -08:00

1668 lines
59 KiB
JavaScript

const { nanoid } = require('nanoid');
const { logger } = require('@librechat/data-schemas');
const { Callback, formatAgentMessages } = require('@librechat/agents');
const {
EModelEndpoint,
ResourceType,
PermissionBits,
hasPermissions,
AgentCapabilities,
} = require('librechat-data-provider');
const {
createRun,
applyContextToAgent,
buildInitialToolSessions,
buildRunToolSet,
AgentRunEnvelopeError,
createAgentRunEnvelope,
createAgentExecutionContext,
createMCPRuntimeRequestBody,
buildAgentScopedContext,
buildInlineMemoryContext,
buildAgentContextAttachmentsByAgentId,
createSafeUser,
initializeAgent,
loadSkillStates,
loadSkillAccess,
getBalanceConfig,
injectSkillPrimes,
extractManualSkills,
recordCollectedUsage,
createSubagentUsageSink,
getTransactionsConfig,
resolveAgentTokenConfig,
resolveSubagentGraphs,
inspectContent,
extractAgentContent,
extractMessageContent,
extractModelParameterContent,
extractSkillContent,
extractToolArgumentContent,
contentFilterBlockResponse,
contentFilterUninspectableResponse,
discoverConnectedAgents,
getBlockedOpaqueFileField,
getContentTraversalFragments,
isContentTraversalProtected,
isContentTraversalLimitError,
prependContentTraversalFragments,
assertModelBoundContent,
reportLocatorTraversalFailure,
hasModelBoundContentProtection,
isContentFilterError,
getSafeErrorMetadata,
getUserFacingProviderError,
getAgentErrorMetadata,
createToolExecuteHandler,
createOwnedToolEndHandler,
resolveRecursionLimit,
getRemoteAgentPermissions,
resolveAgentScopedSkillIds,
// Responses API
buildResponseInputChain,
loadForegroundResponseHistory,
createResponseTurn,
createStoredForegroundResponseReader,
createResponseAccountingSnapshot,
withResponsePersistenceErrors,
createResponseExecutionRuntime,
GenerationJobManager,
getPluginHookSource,
writeDone,
generateResponseId,
isValidationFailure,
emitResponseCreated,
createResponseContext,
createResponseTracker,
setupStreamingResponse,
emitResponseInProgress,
convertInputToMessages,
extractResponseInputFileContent,
validateResponseRequest,
buildAggregatedResponse,
buildResponsesUsage,
createResponseAggregator,
sendResponsesErrorResponse,
createResponsesEventHandlers,
createAggregatorEventHandlers,
createClientToolHandoff,
getLangfuseTraceMessageFields,
stripActivityLabelParts,
stripUnusableSummaryParts,
CHILD_THREAD_READ_ONLY_ERROR,
executeAgentRun,
waitForAgentExecutionWrites,
resolveToolRoleGrants,
resolveApiConversationProject,
resolveAdmittedCodeEnvironmentDecision,
createTerminalRunErrorObserver,
announceReply,
isTemporaryTurn,
getModelEndUsage,
hasEntityEmbeddings,
} = require('@librechat/api');
const {
createResponsesToolEndCallback,
buildSummarizationHandlers,
contextualizeModelUsage,
createToolEndCallback,
agentLogHandlerObj,
} = require('~/server/controllers/agents/callbacks');
const {
loadAgentTools,
loadToolsForExecution,
isFatalAgentInitializationError,
} = require('~/server/services/ToolService');
const {
findAccessibleResources,
getEffectivePermissions,
} = require('~/server/services/PermissionService');
const {
getSkillToolDeps,
getSkillDbMethods,
canAuthorSkillFiles,
withDeploymentSkillIds,
buildAgentToolContext,
resolveMemoryAvailability,
enrichLoadedToolsWithAgentContext,
} = require('~/server/services/Endpoints/agents/skillDeps');
const { createProvisionFilesCallback } = require('~/server/services/Files/provisionCallback');
const { checkSessionsAlive, loadCodeApiKey } = require('~/server/services/Files/provision');
const {
getLinkedInstructionsResolver,
} = require('~/server/services/Endpoints/agents/linkedInstructions');
const { getEndpointModelsConfig } = require('~/server/controllers/ModelController');
const { filterFilesByAgentAccess } = require('~/server/services/Files/permissions');
const { resolveConfigServers, getAccessibleMcpServerNames } = require('~/server/services/MCP');
const { resolveConversationTitle } = require('~/server/services/Endpoints/titlePolicy');
const { getMCPManager } = require('~/config');
const { logViolation } = require('~/cache');
const db = require('~/models');
const filterFilesByRemoteAgentAccess = (params) =>
filterFilesByAgentAccess({ ...params, resourceType: ResourceType.REMOTE_AGENT });
function handleExecutionError({ error, res, appConfig }) {
const protectionEnabled = hasModelBoundContentProtection(
appConfig?.filters,
appConfig?.messageFilter?.pii,
);
const errorMessage = getUserFacingProviderError(error, protectionEnabled);
if (res.headersSent) {
writeDone(res);
res.end();
return;
}
if (isContentFilterError(error)) {
return sendResponsesErrorResponse(
res,
error.statusCode,
error.body.message,
'invalid_request',
error.body.error,
);
}
const errorMetadata = getAgentErrorMetadata(error);
const statusCode = errorMetadata?.status ?? 500;
const errorType = statusCode >= 400 && statusCode < 500 ? 'invalid_request' : 'server_error';
const errorCode = !protectionEnabled ? errorMetadata?.code : undefined;
if (errorCode === undefined) {
sendResponsesErrorResponse(res, statusCode, errorMessage, errorType);
} else {
sendResponsesErrorResponse(res, statusCode, errorMessage, errorType, errorCode);
}
}
/**
* Creates a tool loader function for the agent.
* @param {Object} runtime - Request-backed tool adapter state
* @param {import('express').Request} runtime.req
* @param {import('express').Response} runtime.res
* @param {AbortSignal} runtime.signal - The abort signal
* @param {boolean} [runtime.definitionsOnly=true] - When true, returns only serializable
* tool definitions without creating full tool instances (for event-driven mode)
*/
function createToolLoader({
req,
res,
signal,
definitionsOnly = true,
streamId = null,
jobCreatedAt,
}) {
return async function loadTools({
tools,
model,
agentId,
provider,
tool_options,
tool_resources,
requestBody,
codeExecutionContext,
attachedEnvironmentOptOut,
accessibleMcpServerNames,
}) {
const agent = { id: agentId, tools, provider, model, tool_options };
try {
return await loadAgentTools({
req,
res,
agent,
signal,
requestBody,
tool_resources,
codeExecutionContext,
attachedEnvironmentOptOut,
agentResourceType: ResourceType.REMOTE_AGENT,
definitionsOnly,
accessibleMcpServerNames,
streamId,
jobCreatedAt,
});
} catch (error) {
if (isFatalAgentInitializationError(error, { signal }) || isContentFilterError(error)) {
throw error;
}
logger.error('Error loading tools for agent ' + agentId, getSafeErrorMetadata(error));
}
};
}
/**
* Convert Open Responses input items to internal messages
* @param {import('@librechat/api').InputItem[]} input
* @returns {Array} Internal messages
*/
function convertToInternalMessages(input) {
return convertInputToMessages(input);
}
/**
* Collect file-derived context exactly as it will be exposed to the model.
* Dynamic tool context uses the same synthesis as packages/api/src/agents/run.ts.
* @param {Array} agents
* @returns {Array}
*/
function collectModelBoundAgentFiles(agents) {
const files = [];
const seenFiles = new Set();
for (const agent of agents) {
for (const attachment of [
...(agent?.attachments ?? []),
...(agent?.requestAttachments ?? []),
...(agent?.agentContextAttachments ?? []),
]) {
if (attachment == null || seenFiles.has(attachment)) {
continue;
}
seenFiles.add(attachment);
files.push(attachment);
}
const dynamicToolInstructions = Object.values(agent?.dynamicToolContextMap ?? {})
.filter((value) => typeof value === 'string' && value !== '')
.join('\n')
.trim();
if (dynamicToolInstructions !== '') {
files.push({ content: dynamicToolInstructions });
}
}
return files;
}
function extractResponseRequestContent(request, messageFragments) {
const fragments = [
...extractAgentContent({ instructions: request.instructions }),
...messageFragments,
];
fragments.push(...extractResponseInputFileContent(request.input));
for (const tool of request.tools ?? []) {
if (tool?.type !== 'function') {
continue;
}
fragments.push(
...extractAgentContent({
name: tool.name,
description: tool.description,
}),
);
try {
fragments.push(...extractToolArgumentContent({ arguments: tool.parameters }));
} catch (error) {
if (isContentTraversalLimitError(error)) {
prependContentTraversalFragments(error, fragments);
}
throw error;
}
}
try {
fragments.push(
...extractModelParameterContent({
metadata: request.metadata,
response_format: request.text?.format,
additionalModelRequestFields: {
user: request.user,
tool_choice: request.tool_choice,
reasoning: request.reasoning,
},
}),
);
} catch (error) {
if (isContentTraversalLimitError(error)) {
prependContentTraversalFragments(error, fragments);
}
throw error;
}
return fragments;
}
/**
* Load messages from a previous response/conversation
* @param {string} conversationId - The conversation/response ID
* @param {string} userId - The user ID
* @returns {Promise<Array>} Messages from the conversation
*/
async function loadPreviousMessages(conversationId, userId, previousResponseId) {
return loadForegroundResponseHistory(
{ conversationId, userId, previousResponseId },
{ getMessages: db.getMessages },
);
}
/**
* Convert stored messages to Open Responses output format
* @param {Array} messages - Stored messages
* @returns {Array} Output items
*/
/**
* Runs a validated Responses envelope in the current process.
* Express remains runtime-only state while the envelope is the portable run input.
*
* @param {import('@librechat/api').ResponsesRunEnvelope} envelope
* @param {{req: import('express').Request, res: import('express').Response}} runtime
*/
const executeResponse = async (envelope, { req, res }) => {
const appConfig = req.config;
const requestStartTime = envelope.receivedAt;
const request = envelope.payload;
const { principal } = envelope;
// Request-backed tool adapters still observe the validated envelope payload;
// shared initialization receives the transport-free runtime below.
req.body = request;
if (request.previous_response_id != null && typeof request.previous_response_id !== 'string') {
return sendResponsesErrorResponse(
res,
400,
'previous_response_id must be a string',
'invalid_request',
);
}
const agentId = request.model;
const manualSkills = extractManualSkills(req.body);
const isStreaming = request.stream === true;
const summarizationConfig = appConfig?.summarization;
const uninspectableField = getBlockedOpaqueFileField(appConfig?.filters, request.input);
if (uninspectableField != null) {
const blockResponse = contentFilterUninspectableResponse(uninspectableField);
return sendResponsesErrorResponse(
res,
400,
blockResponse.message,
'invalid_request',
blockResponse.error,
);
}
const inputMessages = convertToInternalMessages(
typeof request.input === 'string' ? request.input : request.input,
);
const messageFragments = [];
const traversalErrors = [];
try {
for (const fragment of extractMessageContent(inputMessages)) {
messageFragments.push(fragment);
}
} catch (error) {
if (!isContentTraversalLimitError(error)) {
throw error;
}
messageFragments.push(...getContentTraversalFragments(error));
traversalErrors.push(error);
}
let requestFragments;
try {
requestFragments = extractResponseRequestContent(request, messageFragments);
} catch (error) {
if (!isContentTraversalLimitError(error)) {
throw error;
}
requestFragments = getContentTraversalFragments(error);
traversalErrors.push(error);
}
const contentFinding = inspectContent(
[...requestFragments, ...(manualSkills ?? []).flatMap((name) => extractSkillContent({ name }))],
{
filters: appConfig?.filters,
legacyPii: appConfig?.messageFilter?.pii,
},
);
if (contentFinding != null) {
const isLegacyFilter = contentFinding.detectorId === 'legacy-pattern';
const blockResponse = contentFilterBlockResponse(contentFinding);
return sendResponsesErrorResponse(
res,
400,
isLegacyFilter
? `Message contains a ${contentFinding.label}. Remove it and try again.`
: blockResponse.message,
'invalid_request',
isLegacyFilter ? 'message_filter_pii_block' : blockResponse.error,
);
}
const traversalError = traversalErrors.find((error) =>
isContentTraversalProtected({
error,
filters: appConfig?.filters,
legacyPii: appConfig?.messageFilter?.pii,
roles: inputMessages.map((message) => message?.role),
}),
);
if (traversalError != null) {
return sendResponsesErrorResponse(
res,
traversalError.statusCode,
traversalError.body.message,
'invalid_request',
traversalError.body.error,
);
}
// Generate IDs
const responseRuntime = createResponseExecutionRuntime(req, res, {
getMessage: db.getMessage,
generateResponseId,
jobs: GenerationJobManager,
pluginHookSource: getPluginHookSource(),
toolApprovalStorage: db,
addConvoToolApprovalAllows: db.addConvoToolApprovalAllows,
});
const responseId = responseRuntime.responseId;
const terminalRunError = createTerminalRunErrorObserver({
maxProviderErrorChars: appConfig?.endpoints?.agents?.maxProviderErrorChars,
logger,
responseMessageId: responseId,
source: '[Responses API]',
protectionEnabled: hasModelBoundContentProtection(
appConfig?.filters,
appConfig?.messageFilter?.pii,
),
});
const context = createResponseContext(request, responseId);
logger.debug(
`[Responses API] Request ${responseId} started for agent ${agentId}, stream: ${isStreaming}`,
);
const { conversationId, parentMessageId: previousMessageId } =
await responseRuntime.resolveContinuation(envelope);
const turn = createResponseTurn({
runtime: responseRuntime,
context,
requestedStore: request.store,
logger,
});
/** @type {Promise<import('librechat-data-provider').TAttachment | null>[]} */
const artifactPromises = [];
let artifactWritesCovered = false;
return executeAgentRun({
captureTerminalOutcome: true,
envelope,
runId: responseId,
conversationId,
connection: responseRuntime.connection,
...turn.hooks,
/** Conversation delete-all uses the shared owner-admission fence. Remote
* execution must observe it after durable enrollment and before provider work. */
isPrincipalActive: db.isSubagentOwnerAdmissible,
beforeSettle: (execution, error) => {
if (!artifactWritesCovered && artifactPromises.length > 0) {
execution.track(
waitForAgentExecutionWrites(artifactPromises).catch((artifactError) => {
logger.warn(
'[Responses API] Error processing artifacts:',
getSafeErrorMetadata(artifactError),
);
}),
);
}
turn.beforeSettle(execution, error);
},
handleExecutionError: (error, signal) => {
terminalRunError.log(error, signal);
return handleExecutionError({ error, res, appConfig });
},
execute: async (execution) => {
const agentPromise = db.getAgent({ id: agentId });
// Validation may return before this promise is awaited; preserve the original
// promise for the later await while avoiding an unhandled speculative rejection.
agentPromise.catch(() => {});
if (request.previous_response_id != null) {
const project = await resolveApiConversationProject(
{
userId: principal.userId,
tenantId: principal.tenantId,
conversationId,
rejectSubagentThread: true,
},
{
getConvo: db.getConvo,
getChatProject: db.getChatProject,
getProjectFiles: db.getProjectFiles,
logger,
logPrefix: '[Responses API]',
},
);
if (!project.ok && project.reason === 'read_only') {
return sendResponsesErrorResponse(
res,
409,
CHILD_THREAD_READ_ONLY_ERROR,
'invalid_request',
'conversation_read_only',
);
}
if (!project.ok) {
return sendResponsesErrorResponse(
res,
project.status,
project.message,
project.reason === 'server_error' ? 'server_error' : 'not_found',
);
}
req.resolvedConversation = project.conversation;
req.chatProjectContext = project.context;
}
const agent = await agentPromise;
if (!agent) {
return sendResponsesErrorResponse(
res,
404,
`Agent not found: ${agentId}`,
'not_found',
'model_not_found',
);
}
req.turnStartedAt = envelope.receivedAt;
const { decision: codeEnvironmentDecision, conversation: admittedConversation } =
await resolveAdmittedCodeEnvironmentDecision({
appConfig,
conversation: req.resolvedConversation,
conversationId,
requestedMode: request.code_environment_mode,
requestedSelections: request.code_workspaces,
readDecision: (id) => db.readAdmittedConvoCodeEnvironmentDecision(principal.userId, id),
});
req.resolvedConversation = admittedConversation;
const agentRuntime = createAgentExecutionContext({
user: req.user,
appConfig,
requestBody: request,
turnStartedAt: envelope.receivedAt,
conversationCreatedAt: req.conversationCreatedAt,
resolvedConversation: req.resolvedConversation,
hasResolvedConversation: Object.prototype.hasOwnProperty.call(req, 'resolvedConversation'),
chatProjectContext: req.chatProjectContext,
});
const mcpRequestBody = createMCPRuntimeRequestBody({
messageId: responseId,
conversationId,
codeEnvironmentMode: codeEnvironmentDecision.mode,
codeWorkspaces: codeEnvironmentDecision.codeWorkspaces,
});
const agentsEConfig = appConfig?.endpoints?.[EModelEndpoint.agents];
const ordinaryToolCancellationEnabled =
agentsEConfig?.backgroundTasks?.ordinaryToolCancellation === true;
const backgroundCompletionResultMaxChars =
agentsEConfig?.backgroundTasks?.completionResultMaxChars;
const previousMessages = request.previous_response_id
? await loadPreviousMessages(conversationId, principal.userId, previousMessageId)
: [];
const inputChain = responseRuntime.inputChain(
buildResponseInputChain(inputMessages, previousMessageId, previousMessages),
);
const parentMessageId = inputChain.parentMessageId;
if (request.previous_response_id) {
assertModelBoundContent({
onTraversalFailure: reportLocatorTraversalFailure,
filters: appConfig?.filters,
legacyPii: appConfig?.messageFilter?.pii,
storedMessages: previousMessages,
});
}
// Build allowed providers set
const allowedProviders = new Set(agentsEConfig?.allowedProviders);
// Create tool loader
const loadTools = createToolLoader({
req,
res,
signal: execution.signal,
...responseRuntime.toolContext(execution),
});
const skillDbMethods = getSkillDbMethods();
// Initialize the agent first to check for disableStreaming
const endpointOption = {
endpoint: agent.provider,
model_parameters: agent.model_parameters ?? {},
};
const dbMethods = {
getProjectFiles: db.getProjectFiles,
getConvoFiles: db.getConvoFiles,
getFiles: db.getFiles,
filterFilesByAgentAccess: filterFilesByRemoteAgentAccess,
getUserKey: db.getUserKey,
getMessages: db.getMessages,
getAccessibleMcpServerNames,
updateFilesUsage: db.updateFilesUsage,
getUserKeyValues: db.getUserKeyValues,
getUserCodeFiles: db.getUserCodeFiles,
getDeferredProvisionFiles: db.getDeferredProvisionFiles,
checkSessionsAlive,
adoptLegacySearchEmbeddings: db.adoptLegacySearchEmbeddings,
hasEntityEmbeddings,
loadCodeApiKey,
getToolFilesByIds: db.getToolFilesByIds,
getCodeGeneratedFiles: db.getCodeGeneratedFiles,
listSkillsByAccess: skillDbMethods.listSkillsByAccess,
listAlwaysApplySkills: skillDbMethods.listAlwaysApplySkills,
getSkillByName: skillDbMethods.getSkillByName,
getRoleByName: db.getRoleByName,
};
const enabledCapabilities = new Set(agentsEConfig?.capabilities);
const codeCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.execute_code);
const fileSearchCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.file_search);
/** Started before the memory read rather than awaited on its own line, so
* the role lookup overlaps that query instead of preceding it. Skipped
* when the deployment has both capabilities off — both flags are false
* either way, so the read would be pure load on every request. One
* lookup answers both. */
const toolRoleGrants =
codeCapabilityEnabled || fileSearchCapabilityEnabled
? resolveToolRoleGrants({ req, getRoleByName: db.getRoleByName })
: null;
const memoryAvailable = await resolveMemoryAvailability({
enabledCapabilities,
memoryConfig: appConfig?.memory,
user: req.user,
getRoleByName: db.getRoleByName,
});
/** The deployment switch AND the role grant: `initializeAgent` rebuilds
* `bash_tool`, `read_file` and the workspace file tools from this flag,
* and forwards the code-environment context to their handlers. */
const codeEnvAvailable = codeCapabilityEnabled && (await toolRoleGrants)?.runCode === true;
/** The same pairing for the other gated tool, read only by the resend-file
* priming: `false` skips re-hydrating prior-turn `file_search` files for
* a tool the loader is about to drop. */
const fileSearchAvailable =
fileSearchCapabilityEnabled && (await toolRoleGrants)?.fileSearch === true;
/** Called by `initializeAgent` only when an agent's built provider config
* turns native web search on. It reaches the initializer with `runtime`
* and no `req`, so this is what lets it join the grants memoized on this
* request instead of issuing its own read. */
const resolveWebSearchGrant = async () =>
(await resolveToolRoleGrants({ req, getRoleByName: db.getRoleByName })).webSearch;
/** Resolves any agent's `instructionsPrompt` link this run encounters — primary
* or handoff. No default resolution path, unlike `resolveWebSearchGrant`. */
const resolveLinkedInstructions = getLinkedInstructionsResolver();
const skillsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.skills);
const ephemeralSkillsToggle = request.ephemeralAgent?.skills === true;
const { accessibleSkillIds, editableSkillIds, skillCreateAllowed } = await loadSkillAccess(
{ enabled: skillsCapabilityEnabled, userId: principal.userId, role: principal.role },
{
findAccessibleResources,
withDeploymentSkillIds,
canCreateSkill: () => getSkillToolDeps().canCreateSkill({ req }),
},
);
const { skillStates, defaultActiveOnShare } = await loadSkillStates({
userId: principal.userId,
appConfig,
getUserById: db.getUserById,
accessibleSkillIds,
});
const primaryScopedSkillIds = resolveAgentScopedSkillIds({
agent,
accessibleSkillIds,
skillsCapabilityEnabled,
ephemeralSkillsToggle,
});
const primaryScopedEditableSkillIds = resolveAgentScopedSkillIds({
agent,
accessibleSkillIds: editableSkillIds,
skillsCapabilityEnabled,
ephemeralSkillsToggle,
});
const primaryConfig = await initializeAgent(
{
runtime: agentRuntime,
loadTools,
requestFiles: [],
conversationId,
parentMessageId,
requestBody: mcpRequestBody,
agent,
endpointOption,
allowedProviders,
isInitialAgent: true,
useChatProjectContext: true,
accessibleSkillIds: primaryScopedSkillIds,
skillAuthoringAvailable: canAuthorSkillFiles({
agent,
scopedEditableSkillIds: primaryScopedEditableSkillIds,
skillCreateAllowed,
skillsCapabilityEnabled,
ephemeralSkillsToggle,
}),
codeEnvAvailable,
fileSearchAvailable,
resolveWebSearchGrant,
resolveLinkedInstructions,
backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
toolIntentsAvailable: enabledCapabilities.has(AgentCapabilities.tool_intents),
statefulSessionsAvailable: enabledCapabilities.has(
AgentCapabilities.stateful_code_sessions,
),
allowedStatefulCodeEnvironments: agentsEConfig?.statefulCodeSessions?.allowedEnvironments,
memoryAvailable,
skillStates,
defaultActiveOnShare,
manualSkills,
signal: execution.signal,
},
dbMethods,
);
/**
* Per-agent tool-execution context map, keyed by agentId. Ensures the
* ON_TOOL_EXECUTE callback routes each sub-agent's tool calls to the
* correct toolRegistry / userMCPAuthMap / tool_resources.
* @type {Map<string, {
* agent: object,
* toolRegistry?: import('@librechat/agents').LCToolRegistry,
* requestScopedConnections?: import('@librechat/api').RequestScopedMCPConnectionStore,
* userMCPAuthMap?: Record<string, Record<string, string>>,
* tool_resources?: object,
* actionsEnabled?: boolean,
* }>}
*/
const agentToolContexts = new Map();
agentToolContexts.set(
primaryConfig.id,
buildAgentToolContext({ agent, config: primaryConfig }),
);
let handoffAgentConfigs = new Map();
let discoveredEdges = [];
let discoveredMCPAuthMap;
const subagentsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.subagents);
const primaryHasGraphSubagents =
subagentsCapabilityEnabled &&
primaryConfig.subagents?.enabled === true &&
(primaryConfig.subagents.graphs?.length ?? 0) > 0;
if (primaryConfig.edges?.length || primaryHasGraphSubagents) {
const discoveryParams = {
req,
res,
signal: execution.signal,
primaryConfig,
endpointOption,
allowedProviders,
getEndpointModels: (endpoint) => getEndpointModelsConfig(req, endpoint),
loadTools,
requestFiles: [],
conversationId,
parentMessageId,
useChatProjectContext: true,
requestBody: mcpRequestBody,
resourceType: ResourceType.REMOTE_AGENT,
computeAccessibleSkillIds: (handoffAgent) =>
resolveAgentScopedSkillIds({
agent: handoffAgent,
accessibleSkillIds,
skillsCapabilityEnabled,
ephemeralSkillsToggle,
}),
computeSkillAuthoringAvailable: (handoffAgent) =>
canAuthorSkillFiles({
agent: handoffAgent,
scopedEditableSkillIds: resolveAgentScopedSkillIds({
agent: handoffAgent,
accessibleSkillIds: editableSkillIds,
skillsCapabilityEnabled,
ephemeralSkillsToggle,
}),
skillCreateAllowed,
skillsCapabilityEnabled,
ephemeralSkillsToggle,
}),
skillStates,
defaultActiveOnShare,
codeEnvAvailable,
fileSearchAvailable,
resolveWebSearchGrant,
resolveLinkedInstructions,
backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
toolIntentsAvailable: enabledCapabilities.has(AgentCapabilities.tool_intents),
statefulSessionsAvailable: enabledCapabilities.has(
AgentCapabilities.stateful_code_sessions,
),
allowedStatefulCodeEnvironments: agentsEConfig?.statefulCodeSessions?.allowedEnvironments,
memoryAvailable,
};
const discoveryDeps = {
getAgent: db.getAgent,
checkPermission: async ({ userId, role, resourceId, requiredPermission }) => {
const permissions = await getRemoteAgentPermissions(
{ getEffectivePermissions },
userId,
role,
resourceId,
);
return hasPermissions(permissions, requiredPermission);
},
logViolation,
db: dbMethods,
onAgentInitialized: (loadedAgentId, loadedAgent, config) => {
agentToolContexts.set(
loadedAgentId,
buildAgentToolContext({ agent: loadedAgent, config }),
);
},
initializeAgent,
};
if (primaryConfig.edges?.length) {
({
agentConfigs: handoffAgentConfigs,
edges: discoveredEdges,
userMCPAuthMap: discoveredMCPAuthMap,
} = await discoverConnectedAgents(discoveryParams, discoveryDeps));
}
if (subagentsCapabilityEnabled) {
discoveredMCPAuthMap = await resolveSubagentGraphs(
{
...discoveryParams,
rootConfigs: [primaryConfig, ...handoffAgentConfigs.values()],
},
discoveryDeps,
);
}
}
primaryConfig.edges = discoveredEdges;
const endpointTokenConfigByAgentId = new Map();
for (const [agentId, context] of agentToolContexts) {
endpointTokenConfigByAgentId.set(agentId, context.endpointTokenConfig);
}
const resolveEndpointTokenConfig = (usage) =>
resolveAgentTokenConfig({
agentId: usage?.agentId,
byAgentId: endpointTokenConfigByAgentId,
fallback: primaryConfig.endpointTokenConfig,
});
const runAgents = [primaryConfig, ...handoffAgentConfigs.values()];
const initialSessions = buildInitialToolSessions({ agents: runAgents });
const modelBoundAgentsById = new Map();
const pendingModelBoundAgents = [...runAgents];
for (let index = 0; index < pendingModelBoundAgents.length; index++) {
const runAgent = pendingModelBoundAgents[index];
if (!runAgent?.id || modelBoundAgentsById.has(runAgent.id)) {
continue;
}
modelBoundAgentsById.set(runAgent.id, runAgent);
for (const subagent of runAgent.subagentAgentConfigs?.values?.() ?? []) {
pendingModelBoundAgents.push(subagent);
}
for (const graph of runAgent.subagentGraphConfigs ?? []) {
pendingModelBoundAgents.push(...graph.memberConfigs);
}
}
const modelBoundAgents = [...modelBoundAgentsById.values()];
const mergedMCPAuthMap = discoveredMCPAuthMap ?? primaryConfig.userMCPAuthMap;
assertModelBoundContent({
onTraversalFailure: reportLocatorTraversalFailure,
filters: appConfig?.filters,
legacyPii: appConfig?.messageFilter?.pii,
agents: modelBoundAgents,
});
const agentContextAttachmentsByAgentId =
buildAgentContextAttachmentsByAgentId(modelBoundAgents);
const agentScopedContext = await buildAgentScopedContext({
agentIds: modelBoundAgents.map(({ id }) => id),
attachmentsByAgentId: agentContextAttachmentsByAgentId,
req,
endpoint: primaryConfig.endpoint,
endpointsByAgentId: new Map(
modelBoundAgents.map((runAgent) => [runAgent.id, { endpoint: runAgent.endpoint }]),
),
});
const mcpManager = getMCPManager();
const configServers = await resolveConfigServers(req);
await Promise.all(
modelBoundAgents.map(async (runAgent) => {
const memoryContext = await buildInlineMemoryContext({
agent: runAgent,
req,
userId: principal.userId,
memoryAvailable,
getFormattedMemories: db.getFormattedMemories,
});
return applyContextToAgent({
agent: runAgent,
agentId: runAgent.id,
logger,
mcpManager,
configServers,
user: req.user,
sharedRunContext: [memoryContext, agentScopedContext.get(runAgent.id)]
.filter(Boolean)
.join('\n\n'),
});
}),
);
// Determine if streaming is enabled (check both request and agent config)
const streamingDisabled = !!primaryConfig.model_parameters?.disableStreaming;
const actuallyStreaming = isStreaming && !streamingDisabled;
// Merge previous messages with new input
const allMessages = [...previousMessages, ...inputMessages];
/** The caller's function tools: declared to the model with no server-side
* executor, handed back when the model calls one, and reported on the
* response as the subset that was actually applied.
*
* Built once every agent of the run is known, because the interception
* matches on tool name across the whole graph: a name a subagent owns
* collides exactly as a primary one does. */
const clientTools = createClientToolHandoff({
tools: request.tools,
agentDefinitions: primaryConfig.toolDefinitions,
serverDefinitions: modelBoundAgents.flatMap((runAgent) => runAgent.toolDefinitions ?? []),
responseId,
});
if (clientTools.error != null) {
return sendResponsesErrorResponse(res, 400, clientTools.error, 'invalid_request');
}
primaryConfig.toolDefinitions = clientTools.toolDefinitions;
context.tools = clientTools.appliedTools;
const toolSet = buildRunToolSet(
primaryConfig,
handoffAgentConfigs.values(),
undefined,
allMessages,
true,
);
const formatted = formatAgentMessages(
stripUnusableSummaryParts(stripActivityLabelParts(allMessages)),
{},
toolSet,
);
const formattedMessages = formatted.messages;
const initialSummary = formatted.summary;
let indexTokenCountMap = formatted.indexTokenCountMap;
/**
* Inject manual + always-apply skill primes so the model sees SKILL.md
* bodies for this turn — parity with AgentClient's chat path. The
* Responses API uses its own response-builder shape, so LibreChat-
* style card SSE events don't apply; only the message-context part
* carries over.
*/
const manualSkillPrimes = primaryConfig.manualSkillPrimes;
const alwaysApplySkillPrimes = primaryConfig.alwaysApplySkillPrimes;
if (
(manualSkillPrimes && manualSkillPrimes.length > 0) ||
(alwaysApplySkillPrimes && alwaysApplySkillPrimes.length > 0)
) {
const primeResult = injectSkillPrimes({
initialMessages: formattedMessages,
indexTokenCountMap,
manualSkillPrimes,
alwaysApplySkillPrimes,
});
indexTokenCountMap = primeResult.indexTokenCountMap;
/* Surface the cap-driven always-apply truncation at the controller
layer too — `injectSkillPrimes` already logs internally, but the
controller-level warn includes endpoint context so operators can
tell at a glance which path hit the cap. Mirrors AgentClient's
warn in `client.js`. */
if (primeResult.alwaysApplyDropped > 0) {
logger.warn(
`[Responses API] Dropped ${primeResult.alwaysApplyDropped} always-apply prime(s) to stay within MAX_PRIMED_SKILLS_PER_TURN.`,
);
}
}
assertModelBoundContent({
onTraversalFailure: reportLocatorTraversalFailure,
filters: appConfig?.filters,
legacyPii: appConfig?.messageFilter?.pii,
submittedMessages: inputMessages,
agents: modelBoundAgents,
skills: [...(manualSkillPrimes ?? []), ...(alwaysApplySkillPrimes ?? [])],
files: collectModelBoundAgentFiles(modelBoundAgents),
});
/* Stable for the turn: the primary prime list is fixed once
`initializeAgent` resolves and is used as the fallback when a
specific agent context is unavailable. `codeEnvAvailable` is read
per-agent from the stored tool context (admin cap AND that
agent's `tools` list includes `execute_code`) — a skills-only
agent never gains sandbox access even if the admin enabled the
capability globally. */
// Create tracker for streaming or aggregator for non-streaming
const tracker = actuallyStreaming ? createResponseTracker() : null;
const aggregator = actuallyStreaming ? null : createResponseAggregator();
responseRuntime.seedAggregator(aggregator);
const collectedUsage = [];
const snapshotAccounting = createResponseAccountingSnapshot({
collectedUsage,
emittedUsage: [],
billingEnabled: getTransactionsConfig(appConfig)?.enabled === true,
billing: {
pricing: { getMultiplier: db.getMultiplier, getCacheMultiplier: db.getCacheMultiplier },
getValueKey: db.getValueKey,
resolveEndpointTokenConfig,
},
});
// Set up response for streaming
if (actuallyStreaming) {
setupStreamingResponse(res);
// Create handler config
const handlerConfig = {
res,
context,
tracker,
/* The run terminates a caller-executed call's item itself: the server
never executes one, so `on_tool_end` cannot. */
clientToolNames: clientTools.clientToolNames,
};
// Emit response.created then response.in_progress per Open Responses spec
emitResponseCreated(handlerConfig);
emitResponseInProgress(handlerConfig);
// Create event handlers
const {
handlers: responsesHandlers,
finalizeStream,
prepareStreamResponse,
failStream,
emitClientToolDeferral,
} = createResponsesEventHandlers(handlerConfig);
// Collect usage for balance tracking
// Artifact promises for processing tool outputs
// Use Responses API-specific callback that emits librechat:attachment events
const toolEndCallback = createResponsesToolEndCallback({
req,
res,
tracker,
artifactPromises,
});
// Create tool execute options for event-driven tool execution
const toolExecuteOptions = {
runSignal: execution.signal,
foregroundRunId: responseId,
ordinaryToolCancellation: ordinaryToolCancellationEnabled,
backgroundCompletionResultMaxChars,
provisionFiles: createProvisionFilesCallback({
req,
agentToolContexts,
resolvePrimaryAgentId: () => primaryConfig.id,
}),
loadTools: async (
toolNames,
agentId,
_configurable,
callerCapabilityProjection,
runSignal,
) => {
const ctx =
agentToolContexts.get(agentId) ?? agentToolContexts.get(primaryConfig.id) ?? {};
const result = await loadToolsForExecution({
...responseRuntime.toolContext(execution),
req,
res,
agentResourceType: ResourceType.REMOTE_AGENT,
conversationId,
requestBody: mcpRequestBody,
toolNames,
agent: ctx.agent ?? agent,
signal: runSignal,
toolRegistry: ctx.toolRegistry,
callerCapabilityProjection,
backgroundToolNames: ctx.backgroundToolNames,
intentToolNames: ctx.intentToolNames,
mcpAvailableTools: ctx.mcpAvailableTools,
requestScopedConnections: ctx.requestScopedConnections,
userMCPAuthMap: ctx.userMCPAuthMap,
tool_resources: ctx.tool_resources,
actionsEnabled: ctx.actionsEnabled,
accessibleMcpServerNames: ctx.accessibleMcpServerNames,
});
return enrichLoadedToolsWithAgentContext({
result,
req,
ctx,
});
},
toolEndCallback,
...getSkillToolDeps(),
};
// Combine handlers
const handlers = {
on_message_delta: responsesHandlers.on_message_delta,
on_reasoning_delta: responsesHandlers.on_reasoning_delta,
on_run_step: clientTools.wrapRunStep(responsesHandlers.on_run_step),
on_run_step_delta: responsesHandlers.on_run_step_delta,
on_chat_model_end: {
handle: (event, data, metadata, graph) => {
responsesHandlers.on_chat_model_end.handle(event, data);
const usage = getModelEndUsage(data?.output);
if (usage) {
const agentContext = graph?.getAgentContext?.(metadata);
const taggedUsage = contextualizeModelUsage(usage, metadata, agentContext);
collectedUsage.push(taggedUsage);
}
},
},
on_tool_end: createOwnedToolEndHandler(toolEndCallback, logger),
on_run_step_completed: responsesHandlers.on_run_step_completed,
on_chain_stream: { handle: () => {} },
on_chain_end: { handle: () => {} },
on_agent_update: { handle: () => {} },
on_custom_event: { handle: () => {} },
/** The deferral answer is emitted as the call's `function_call_output`,
* so a caller can tell an answered call from one handed back to it. */
on_tool_execute: clientTools.wrapToolExecute(
createToolExecuteHandler(toolExecuteOptions),
emitClientToolDeferral,
),
on_agent_log: agentLogHandlerObj,
...(summarizationConfig?.enabled !== false
? buildSummarizationHandlers({ isStreaming: actuallyStreaming, res })
: {}),
};
// Create and run the agent
const userId = principal.userId;
const userMCPAuthMap = mergedMCPAuthMap;
const run = await createRun({
...(await responseRuntime.graphOptions(runAgents)),
agents: runAgents,
messages: responseRuntime.graphMessages(formattedMessages),
indexTokenCountMap,
initialSummary,
runId: responseId,
summarizationConfig,
appConfig,
signal: execution.signal,
customHandlers: handlers,
initialSessions,
requestBody: mcpRequestBody,
user: { ...createSafeUser(req.user), id: userId },
traceContext: { endpoint: EModelEndpoint.agents },
tenantId: principal.tenantId,
isTemporary: isTemporaryTurn(req),
modelCallbacks: [terminalRunError.modelCallback],
clientToolNames: clientTools.clientToolNames,
/** Bills subagent child-run model calls (reported outside the
* streamEvents loop) into the same collectedUsage array. */
subagentUsageSink: createSubagentUsageSink(collectedUsage),
});
if (!run) {
throw new Error('Failed to create agent run');
}
// Process the stream
const config = {
runName: 'AgentRun',
configurable: {
thread_id: conversationId,
user_id: userId,
user: createSafeUser(req.user),
requestBody: mcpRequestBody,
...(userMCPAuthMap != null && { userMCPAuthMap }),
},
recursionLimit: resolveRecursionLimit(agentsEConfig, agent),
signal: execution.signal,
streamMode: 'values',
version: 'v2',
};
await responseRuntime.processRun(run, { messages: formattedMessages }, config, {
callbacks: {
[Callback.TOOL_ERROR]: (graph, error, toolId) => {
logger.error(`[Responses API] Tool Error "${toolId}"`, getSafeErrorMetadata(error));
},
},
});
// Record token usage against balance
const balanceConfig = getBalanceConfig(appConfig);
const transactionsConfig = getTransactionsConfig(appConfig);
execution.track(
recordCollectedUsage(
{
spendTokens: db.spendTokens,
spendStructuredTokens: db.spendStructuredTokens,
pricing: {
getMultiplier: db.getMultiplier,
getCacheMultiplier: db.getCacheMultiplier,
},
bulkWriteOps: {
insertMany: db.bulkInsertTransactions,
updateBalance: db.updateBalance,
},
},
{
user: userId,
conversationId,
collectedUsage,
context: 'message',
messageId: responseId,
balance: balanceConfig,
transactions: transactionsConfig,
model: primaryConfig.model || agent.model_parameters?.model,
endpointTokenConfig: primaryConfig.endpointTokenConfig,
resolveEndpointTokenConfig,
},
).catch((err) => {
logger.error('[Responses API] Error recording usage:', getSafeErrorMetadata(err));
}),
);
const usage = buildResponsesUsage(collectedUsage);
const accountingSnapshot = snapshotAccounting();
const finalResponse = prepareStreamResponse(usage, accountingSnapshot);
await turn.stage(
{
run,
execution,
agents: runAgents,
request: req,
response: finalResponse,
conversationId,
agentId,
agent,
codeEnvironmentDecision,
messages: inputChain.messages,
parentMessageId,
visibleOutputTokens: tracker.usage.outputTokens,
transport: {
type: 'stream',
response: res,
finalize: finalizeStream,
fail: failStream,
},
},
{
saveConvo: db.saveConvo,
saveMessage: db.saveMessage,
announceReply: announceReply.bind(null, db),
resolveTitle: resolveConversationTitle,
traceFields: getLangfuseTraceMessageFields,
},
);
// Register artifact writes before the host drains and publishes the terminal response.
if (artifactPromises.length > 0) {
execution.track(
waitForAgentExecutionWrites(artifactPromises).catch((artifactError) => {
logger.warn(
'[Responses API] Error processing artifacts:',
getSafeErrorMetadata(artifactError),
);
}),
);
artifactWritesCovered = true;
}
} else {
const aggregatorHandlers = createAggregatorEventHandlers(aggregator);
// Collect usage for balance tracking
const toolEndCallback = createToolEndCallback({
req,
res,
artifactPromises,
...responseRuntime.toolContext(execution),
});
const toolExecuteOptions = {
runSignal: execution.signal,
foregroundRunId: responseId,
ordinaryToolCancellation: ordinaryToolCancellationEnabled,
backgroundCompletionResultMaxChars,
provisionFiles: createProvisionFilesCallback({
req,
agentToolContexts,
resolvePrimaryAgentId: () => primaryConfig.id,
}),
loadTools: async (
toolNames,
agentId,
_configurable,
callerCapabilityProjection,
runSignal,
) => {
const ctx =
agentToolContexts.get(agentId) ?? agentToolContexts.get(primaryConfig.id) ?? {};
const result = await loadToolsForExecution({
...responseRuntime.toolContext(execution),
req,
res,
agentResourceType: ResourceType.REMOTE_AGENT,
conversationId,
requestBody: mcpRequestBody,
toolNames,
agent: ctx.agent ?? agent,
signal: runSignal,
toolRegistry: ctx.toolRegistry,
callerCapabilityProjection,
backgroundToolNames: ctx.backgroundToolNames,
intentToolNames: ctx.intentToolNames,
mcpAvailableTools: ctx.mcpAvailableTools,
requestScopedConnections: ctx.requestScopedConnections,
userMCPAuthMap: ctx.userMCPAuthMap,
tool_resources: ctx.tool_resources,
actionsEnabled: ctx.actionsEnabled,
accessibleMcpServerNames: ctx.accessibleMcpServerNames,
});
return enrichLoadedToolsWithAgentContext({
result,
req,
ctx,
});
},
toolEndCallback,
...getSkillToolDeps(),
};
const handlers = {
on_message_delta: aggregatorHandlers.on_message_delta,
on_reasoning_delta: aggregatorHandlers.on_reasoning_delta,
on_run_step: clientTools.wrapRunStep(aggregatorHandlers.on_run_step),
on_run_step_delta: aggregatorHandlers.on_run_step_delta,
on_chat_model_end: {
handle: (event, data, metadata, graph) => {
aggregatorHandlers.on_chat_model_end.handle(event, data);
const usage = getModelEndUsage(data?.output);
if (usage) {
const agentContext = graph?.getAgentContext?.(metadata);
const taggedUsage = contextualizeModelUsage(usage, metadata, agentContext);
collectedUsage.push(taggedUsage);
}
},
},
on_tool_end: createOwnedToolEndHandler(toolEndCallback, logger),
on_run_step_completed: aggregatorHandlers.on_run_step_completed,
on_chain_stream: { handle: () => {} },
on_chain_end: { handle: () => {} },
on_agent_update: { handle: () => {} },
on_custom_event: { handle: () => {} },
on_tool_execute: clientTools.wrapToolExecute(
createToolExecuteHandler(toolExecuteOptions),
(callId, output) => aggregator.toolOutputs.set(callId, output),
),
on_agent_log: agentLogHandlerObj,
...(summarizationConfig?.enabled !== false
? buildSummarizationHandlers({ isStreaming: false, res })
: {}),
};
const userId = principal.userId;
const userMCPAuthMap = mergedMCPAuthMap;
const run = await createRun({
...(await responseRuntime.graphOptions(runAgents)),
agents: runAgents,
messages: responseRuntime.graphMessages(formattedMessages),
indexTokenCountMap,
initialSummary,
runId: responseId,
summarizationConfig,
appConfig,
signal: execution.signal,
customHandlers: handlers,
initialSessions,
requestBody: mcpRequestBody,
user: { ...createSafeUser(req.user), id: userId },
traceContext: { endpoint: EModelEndpoint.agents },
tenantId: principal.tenantId,
isTemporary: isTemporaryTurn(req),
modelCallbacks: [terminalRunError.modelCallback],
clientToolNames: clientTools.clientToolNames,
/** Bills subagent child-run model calls (reported outside the
* streamEvents loop) into the same collectedUsage array. */
subagentUsageSink: createSubagentUsageSink(collectedUsage),
});
if (!run) {
throw new Error('Failed to create agent run');
}
const config = {
runName: 'AgentRun',
configurable: {
thread_id: conversationId,
user_id: userId,
user: createSafeUser(req.user),
requestBody: mcpRequestBody,
...(userMCPAuthMap != null && { userMCPAuthMap }),
},
recursionLimit: resolveRecursionLimit(agentsEConfig, agent),
signal: execution.signal,
streamMode: 'values',
version: 'v2',
};
await responseRuntime.processRun(run, { messages: formattedMessages }, config, {
callbacks: {
[Callback.TOOL_ERROR]: (graph, error, toolId) => {
logger.error(`[Responses API] Tool Error "${toolId}"`, getSafeErrorMetadata(error));
},
},
});
// Record token usage against balance
const balanceConfig = getBalanceConfig(appConfig);
const transactionsConfig = getTransactionsConfig(appConfig);
execution.track(
recordCollectedUsage(
{
spendTokens: db.spendTokens,
spendStructuredTokens: db.spendStructuredTokens,
pricing: {
getMultiplier: db.getMultiplier,
getCacheMultiplier: db.getCacheMultiplier,
},
bulkWriteOps: {
insertMany: db.bulkInsertTransactions,
updateBalance: db.updateBalance,
},
},
{
user: userId,
conversationId,
collectedUsage,
context: 'message',
messageId: responseId,
balance: balanceConfig,
transactions: transactionsConfig,
model: primaryConfig.model || agent.model_parameters?.model,
endpointTokenConfig: primaryConfig.endpointTokenConfig,
resolveEndpointTokenConfig,
},
).catch((err) => {
logger.error('[Responses API] Error recording usage:', getSafeErrorMetadata(err));
}),
);
if (artifactPromises.length > 0) {
try {
await waitForAgentExecutionWrites(artifactPromises);
} catch (artifactError) {
logger.warn(
'[Responses API] Error processing artifacts:',
getSafeErrorMetadata(artifactError),
);
}
artifactWritesCovered = true;
}
const response = buildAggregatedResponse(
context,
aggregator,
buildResponsesUsage(collectedUsage),
snapshotAccounting(),
);
await turn.stage(
{
run,
execution,
agents: runAgents,
request: req,
response: response,
conversationId,
agentId,
agent,
codeEnvironmentDecision,
messages: inputChain.messages,
parentMessageId,
visibleOutputTokens: aggregator.usage.outputTokens,
transport: { type: 'json', response: res },
},
{
saveConvo: db.saveConvo,
saveMessage: db.saveMessage,
announceReply: announceReply.bind(null, db),
resolveTitle: resolveConversationTitle,
traceFields: getLangfuseTraceMessageFields,
},
);
const duration = Date.now() - requestStartTime;
logger.debug(
`[Responses API] Request ${responseId} completed in ${duration}ms (non-streaming)`,
);
}
},
});
};
/**
* Open Responses ingress adapter for agents.
* Authentication and remote-agent authorization have already run in route middleware.
*
* POST /v1/responses
*
* @param {import('express').Request} req
* @param {import('express').Response} res
*/
const createResponse = async (req, res) => {
const receivedAt = Date.now();
const validation = validateResponseRequest(req.body);
if (isValidationFailure(validation)) {
return sendResponsesErrorResponse(res, 400, validation.error);
}
let envelope;
try {
envelope = createAgentRunEnvelope({
protocol: 'responses',
requestId: req.requestId ?? req.id ?? `agent-run-${nanoid()}`,
receivedAt,
principal: req.tenantId == null ? req.user : { ...req.user, tenantId: req.tenantId },
payload: validation.request,
});
} catch (error) {
if (error instanceof AgentRunEnvelopeError) {
return sendResponsesErrorResponse(res, 400, error.message, 'invalid_request');
}
throw error;
}
return executeResponse(envelope, { req, res });
};
/**
* List available agents as models - GET /v1/models (also works with /v1/responses/models)
*
* Returns a list of available agents the user has remote access to.
*
* @param {import('express').Request} req
* @param {import('express').Response} res
*/
const listModels = async (req, res) => {
try {
const userId = req.user?.id;
const userRole = req.user?.role;
if (!userId) {
return sendResponsesErrorResponse(res, 401, 'Authentication required', 'auth_error');
}
// Find agents the user has remote access to (VIEW permission on REMOTE_AGENT)
const accessibleAgentIds = await findAccessibleResources({
userId,
role: userRole,
resourceType: ResourceType.REMOTE_AGENT,
requiredPermissions: PermissionBits.VIEW,
});
// Get the accessible agents
let agents = [];
if (accessibleAgentIds.length > 0) {
agents = await db.getAgentModelSummaries(accessibleAgentIds);
}
// Convert to models format
const models = agents.map((agent) => ({
id: agent.id,
object: 'model',
created: Math.floor(new Date(agent.createdAt).getTime() / 1000),
owned_by: agent.author ?? 'librechat',
// Additional metadata
name: agent.name,
description: agent.description,
provider: agent.provider,
}));
res.json({
object: 'list',
data: models,
});
} catch (error) {
logger.error('[Responses API] Error listing models:', getSafeErrorMetadata(error));
sendResponsesErrorResponse(
res,
500,
error instanceof Error ? error.message : 'Failed to list models',
'server_error',
);
}
};
/**
* Get Response - GET /v1/responses/:id
*
* Retrieves a stored response by its ID.
* The response ID maps to a conversationId in LibreChat's storage.
*
* @param {import('express').Request} req
* @param {import('express').Response} res
*/
const getResponse = createStoredForegroundResponseReader({
getMessage: db.getMessage,
getMessages: db.getMessages,
getConvo: db.getConvo,
logger,
});
module.exports = {
createResponse: withResponsePersistenceErrors(createResponse),
getResponse,
listModels,
};