Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🛸 feat: Remote Agent Access with External API Support (#11503)
Danny Avila6279ea8dd7af
diff --git a/api/models/Agent.js b/api/models/Agent.jsindex 11789ca63b..663285183a 100644--- a/api/models/Agent.js+++ b/api/models/Agent.js@@ -589,10 +589,16 @@ const deleteAgent = async (searchParameter) => {const agent = await Agent.findOneAndDelete(searchParameter);if (agent) {await removeAgentFromAllProjects(agent.id);- await removeAllPermissions({- resourceType: ResourceType.AGENT,- resourceId: agent._id,- });+ await Promise.all([+ removeAllPermissions({+ resourceType: ResourceType.AGENT,+ resourceId: agent._id,+ }),+ removeAllPermissions({+ resourceType: ResourceType.REMOTE_AGENT,+ resourceId: agent._id,+ }),+ ]);try {await Agent.updateMany({ 'edges.to': agent.id }, { $pull: { edges: { to: agent.id } } });} catch (error) {@@ -631,7 +637,7 @@ const deleteUserAgents = async (userId) => {}await AclEntry.deleteMany({- resourceType: ResourceType.AGENT,+ resourceType: { $in: [ResourceType.AGENT, ResourceType.REMOTE_AGENT] },resourceId: { $in: agentObjectIds },});diff --git a/api/server/controllers/PermissionsController.js b/api/server/controllers/PermissionsController.jsindex e22e9532c9..51993d083c 100644--- a/api/server/controllers/PermissionsController.js+++ b/api/server/controllers/PermissionsController.js@@ -5,6 +5,7 @@const mongoose = require('mongoose');const { logger } = require('@librechat/data-schemas');const { ResourceType, PrincipalType, PermissionBits } = require('librechat-data-provider');+const { enrichRemoteAgentPrincipals, backfillRemoteAgentPermissions } = require('@librechat/api');const {bulkUpdateResourcePermissions,ensureGroupPrincipalExists,@@ -14,7 +15,6 @@ const {findAccessibleResources,getResourcePermissionsMap,} = require('~/server/services/PermissionService');-const { AclEntry } = require('~/db/models');const {searchPrincipals: searchLocalPrincipals,sortPrincipalsByRelevance,@@ -24,6 +24,7 @@ const {entraIdPrincipalFeatureEnabled,searchEntraIdPrincipals,} = require('~/server/services/GraphApiService');+const { AclEntry, AccessRole } = require('~/db/models');/*** Generic controller for resource permission endpoints@@ -234,7 +235,7 @@ const getResourcePermissions = async (req, res) => {},]);- const principals = [];+ let principals = [];let publicPermission = null;// Process aggregation results@@ -280,6 +281,13 @@ const getResourcePermissions = async (req, res) => {}}+ if (resourceType === ResourceType.REMOTE_AGENT) {+ const enricherDeps = { AclEntry, AccessRole, logger };+ const enrichResult = await enrichRemoteAgentPrincipals(enricherDeps, resourceId, principals);+ principals = enrichResult.principals;+ backfillRemoteAgentPermissions(enricherDeps, resourceId, enrichResult.entriesToBackfill);+ }+// Return response in format expected by frontendconst response = {resourceType,diff --git a/api/server/controllers/UserController.js b/api/server/controllers/UserController.jsindex b0cfd7ede2..0f17b4d3a9 100644--- a/api/server/controllers/UserController.js+++ b/api/server/controllers/UserController.js@@ -22,6 +22,7 @@ const {} = require('~/models');const {ConversationTag,+ AgentApiKey,Transaction,MemoryEntry,Assistant,@@ -256,6 +257,7 @@ const deleteUserController = async (req, res) => {await deleteFiles(null, user.id); // delete database files in case of orphaned files from previous stepsawait deleteToolCalls(user.id); // delete user tool callsawait deleteUserAgents(user.id); // delete user agents+ await AgentApiKey.deleteMany({ user: user._id }); // delete user agent API keysawait Assistant.deleteMany({ user: user.id }); // delete user assistantsawait ConversationTag.deleteMany({ user: user.id }); // delete user conversation tagsawait MemoryEntry.deleteMany({ userId: user.id }); // delete user memory entriesdiff --git a/api/server/controllers/agents/callbacks.js b/api/server/controllers/agents/callbacks.jsindex 490f05f832..c27f89fdf8 100644--- a/api/server/controllers/agents/callbacks.js+++ b/api/server/controllers/agents/callbacks.js@@ -1,7 +1,7 @@const { nanoid } = require('nanoid');const { Constants } = require('@librechat/agents');const { logger } = require('@librechat/data-schemas');-const { sendEvent, GenerationJobManager } = require('@librechat/api');+const { sendEvent, GenerationJobManager, writeAttachmentEvent } = require('@librechat/api');const { Tools, StepTypes, FileContext, ErrorTypes } = require('librechat-data-provider');const {EnvVar,@@ -489,7 +489,226 @@ function createToolEndCallback({ req, res, artifactPromises, streamId = null })};}+/**+ * Helper to write attachment events in Open Responses format (librechat:attachment)+ * @param {ServerResponse} res - The server response object+ * @param {Object} tracker - The response tracker with sequence number+ * @param {Object} attachment - The attachment data+ * @param {Object} metadata - Additional metadata (messageId, conversationId)+ */+function writeResponsesAttachment(res, tracker, attachment, metadata) {+ const sequenceNumber = tracker.nextSequence();+ writeAttachmentEvent(res, sequenceNumber, attachment, {+ messageId: metadata.run_id,+ conversationId: metadata.thread_id,+ });+}++/**+ * Creates a tool end callback specifically for the Responses API.+ * Emits attachments as `librechat:attachment` events per the Open Responses extension spec.+ *+ * @param {Object} params+ * @param {ServerRequest} params.req+ * @param {ServerResponse} params.res+ * @param {Object} params.tracker - Response tracker with sequence number+ * @param {Promise<MongoFile | { filename: string; filepath: string; expires: number;} | null>[]} params.artifactPromises+ * @returns {ToolEndCallback} The tool end callback.+ */+function createResponsesToolEndCallback({ req, res, tracker, artifactPromises }) {+ /**+ * @type {ToolEndCallback}+ */+ return async (data, metadata) => {+ const output = data?.output;+ if (!output) {+ return;+ }++ if (!output.artifact) {+ return;+ }++ if (output.artifact[Tools.file_search]) {+ artifactPromises.push(+ (async () => {+ const user = req.user;+ const attachment = await processFileCitations({+ user,+ metadata,+ appConfig: req.config,+ toolArtifact: output.artifact,+ toolCallId: output.tool_call_id,+ });+ if (!attachment) {+ return null;+ }+ // For Responses API, emit attachment during streaming+ if (res.headersSent && !res.writableEnded) {+ writeResponsesAttachment(res, tracker, attachment, metadata);+ }+ return attachment;+ })().catch((error) => {+ logger.error('Error processing file citations:', error);+ return null;+ }),+ );+ }++ if (output.artifact[Tools.ui_resources]) {+ artifactPromises.push(+ (async () => {+ const attachment = {+ type: Tools.ui_resources,+ toolCallId: output.tool_call_id,+ [Tools.ui_resources]: output.artifact[Tools.ui_resources].data,+ };+ // For Responses API, always emit attachment during streaming+ if (res.headersSent && !res.writableEnded) {+ writeResponsesAttachment(res, tracker, attachment, metadata);+ }+ return attachment;+ })().catch((error) => {+ logger.error('Error processing artifact content:', error);+ return null;+ }),+ );+ }++ if (output.artifact[Tools.web_search]) {+ artifactPromises.push(+ (async () => {+ const attachment = {+ type: Tools.web_search,+ toolCallId: output.tool_call_id,+ [Tools.web_search]: { ...output.artifact[Tools.web_search] },+ };+ // For Responses API, always emit attachment during streaming+ if (res.headersSent && !res.writableEnded) {+ writeResponsesAttachment(res, tracker, attachment, metadata);+ }+ return attachment;+ })().catch((error) => {+ logger.error('Error processing artifact content:', error);+ return null;+ }),+ );+ }++ if (output.artifact.content) {+ /** @type {FormattedContent[]} */+ const content = output.artifact.content;+ for (let i = 0; i < content.length; i++) {+ const part = content[i];+ if (!part) {+ continue;+ }+ if (part.type !== 'image_url') {+ continue;+ }+ const { url } = part.image_url;+ artifactPromises.push(+ (async () => {+ const filename = `${output.name}_img_${nanoid()}`;+ const file_id = output.artifact.file_ids?.[i];+ const file = await saveBase64Image(url, {+ req,+ file_id,+ filename,+ endpoint: metadata.provider,+ context: FileContext.image_generation,+ });+ const fileMetadata = Object.assign(file, {+ toolCallId: output.tool_call_id,+ });++ if (!fileMetadata) {+ return null;+ }++ // For Responses API, emit attachment during streaming+ if (res.headersSent && !res.writableEnded) {+ const attachment = {+ file_id: fileMetadata.file_id,+ filename: fileMetadata.filename,+ type: fileMetadata.type,+ url: fileMetadata.filepath,+ width: fileMetadata.width,+ height: fileMetadata.height,+ tool_call_id: output.tool_call_id,+ };+ writeResponsesAttachment(res, tracker, attachment, metadata);+ }++ return fileMetadata;+ })().catch((error) => {+ logger.error('Error processing artifact content:', error);+ return null;+ }),+ );+ }+ return;+ }++ const isCodeTool =+ output.name === Tools.execute_code || output.name === Constants.PROGRAMMATIC_TOOL_CALLING;+ if (!isCodeTool) {+ return;+ }++ if (!output.artifact.files) {+ return;+ }++ for (const file of output.artifact.files) {+ const { id, name } = file;+ artifactPromises.push(+ (async () => {+ const result = await loadAuthValues({+ userId: req.user.id,+ authFields: [EnvVar.CODE_API_KEY],+ });+ const fileMetadata = await processCodeOutput({+ req,+ id,+ name,+ apiKey: result[EnvVar.CODE_API_KEY],+ messageId: metadata.run_id,+ toolCallId: output.tool_call_id,+ conversationId: metadata.thread_id,+ session_id: output.artifact.session_id,+ });++ if (!fileMetadata) {+ return null;+ }++ // For Responses API, emit attachment during streaming+ if (res.headersSent && !res.writableEnded) {+ const attachment = {+ file_id: fileMetadata.file_id,+ filename: fileMetadata.filename,+ type: fileMetadata.type,+ url: fileMetadata.filepath,+ width: fileMetadata.width,+ height: fileMetadata.height,+ tool_call_id: output.tool_call_id,+ };+ writeResponsesAttachment(res, tracker, attachment, metadata);+ }++ return fileMetadata;+ })().catch((error) => {+ logger.error('Error processing code output:', error);+ return null;+ }),+ );+ }+ };+}+module.exports = {getDefaultHandlers,createToolEndCallback,+ createResponsesToolEndCallback,};diff --git a/api/server/controllers/agents/openai.js b/api/server/controllers/agents/openai.jsnew file mode 100644index 0000000000..331179c7f4--- /dev/null+++ b/api/server/controllers/agents/openai.js@@ -0,0 +1,660 @@+const { nanoid } = require('nanoid');+const { logger } = require('@librechat/data-schemas');+const { EModelEndpoint, ResourceType, PermissionBits } = require('librechat-data-provider');+const {+ Callback,+ ToolEndHandler,+ formatAgentMessages,+ ChatModelStreamHandler,+} = require('@librechat/agents');+const {+ writeSSE,+ createRun,+ createChunk,+ sendFinalChunk,+ createSafeUser,+ validateRequest,+ initializeAgent,+ createErrorResponse,+ buildNonStreamingResponse,+ createOpenAIStreamTracker,+ createOpenAIContentAggregator,+ isChatCompletionValidationFailure,+} = require('@librechat/api');+const { createToolEndCallback } = require('~/server/controllers/agents/callbacks');+const { findAccessibleResources } = require('~/server/services/PermissionService');+const { loadAgentTools } = require('~/server/services/ToolService');+const { getConvoFiles } = require('~/models/Conversation');+const { getAgent, getAgents } = require('~/models/Agent');+const db = require('~/models');++/**+ * Creates a tool loader function for the agent.+ * @param {AbortSignal} signal - The abort signal+ */+function createToolLoader(signal) {+ return async function loadTools({+ req,+ res,+ tools,+ model,+ agentId,+ provider,+ tool_options,+ tool_resources,+ }) {+ const agent = { id: agentId, tools, provider, model, tool_options };+ try {+ return await loadAgentTools({+ req,+ res,+ agent,+ signal,+ tool_resources,+ streamId: null, // No resumable stream for OpenAI compat+ });+ } catch (error) {+ logger.error('Error loading tools for agent ' + agentId, error);+ }+ };+}++/**+ * Convert content part to internal format+ * @param {Object} part - Content part+ * @returns {Object} Converted part+ */+function convertContentPart(part) {+ if (part.type === 'text') {+ return { type: 'text', text: part.text };+ }+ if (part.type === 'image_url') {+ return { type: 'image_url', image_url: part.image_url };+ }+ return part;+}++/**+ * Convert OpenAI messages to internal format+ * @param {Array} messages - OpenAI format messages+ * @returns {Array} Internal format messages+ */+function convertMessages(messages) {+ return messages.map((msg) => {+ let content;+ if (typeof msg.content === 'string') {+ content = msg.content;+ } else if (msg.content) {+ content = msg.content.map(convertContentPart);+ } else {+ content = '';+ }++ return {+ role: msg.role,+ content,+ ...(msg.name && { name: msg.name }),+ ...(msg.tool_calls && { tool_calls: msg.tool_calls }),+ ...(msg.tool_call_id && { tool_call_id: msg.tool_call_id }),+ };+ });+}++/**+ * Send an error response in OpenAI format+ */+function sendErrorResponse(res, statusCode, message, type = 'invalid_request_error', code = null) {+ res.status(statusCode).json(createErrorResponse(message, type, code));+}++/**+ * OpenAI-compatible chat completions controller for agents.+ *+ * POST /v1/chat/completions+ *+ * Request format:+ * {+ * "model": "agent_id_here",+ * "messages": [{"role": "user", "content": "Hello!"}],+ * "stream": true,+ * "conversation_id": "optional",+ * "parent_message_id": "optional"+ * }+ */+const OpenAIChatCompletionController = async (req, res) => {+ const appConfig = req.config;++ // Validate request+ const validation = validateRequest(req.body);+ if (isChatCompletionValidationFailure(validation)) {+ return sendErrorResponse(res, 400, validation.error);+ }++ const request = validation.request;+ const agentId = request.model;++ // Look up the agent+ const agent = await getAgent({ id: agentId });+ if (!agent) {+ return sendErrorResponse(+ res,+ 404,+ `Agent not found: ${agentId}`,+ 'invalid_request_error',+ 'model_not_found',+ );+ }++ // Generate IDs+ const requestId = `chatcmpl-${nanoid()}`;+ const conversationId = request.conversation_id ?? nanoid();+ const parentMessageId = request.parent_message_id ?? null;+ const created = Math.floor(Date.now() / 1000);++ const context = {+ created,+ requestId,+ model: agentId,+ };++ // Set up abort controller+ const abortController = new AbortController();++ // Handle client disconnect+ req.on('close', () => {+ if (!abortController.signal.aborted) {+ abortController.abort();+ logger.debug('[OpenAI API] Client disconnected, aborting');+ }+ });++ try {+ // Build allowed providers set+ const allowedProviders = new Set(+ appConfig?.endpoints?.[EModelEndpoint.agents]?.allowedProviders,+ );++ // Create tool loader+ const loadTools = createToolLoader(abortController.signal);++ // Initialize the agent first to check for disableStreaming+ const endpointOption = {+ endpoint: agent.provider,+ model_parameters: agent.model_parameters ?? {},+ };++ const primaryConfig = await initializeAgent(+ {+ req,+ res,+ loadTools,+ requestFiles: [],+ conversationId,+ parentMessageId,+ agent,+ endpointOption,+ allowedProviders,+ isInitialAgent: true,+ },+ {+ getConvoFiles,+ getFiles: db.getFiles,+ getUserKey: db.getUserKey,+ getMessages: db.getMessages,+ updateFilesUsage: db.updateFilesUsage,+ getUserKeyValues: db.getUserKeyValues,+ getUserCodeFiles: db.getUserCodeFiles,+ getToolFilesByIds: db.getToolFilesByIds,+ getCodeGeneratedFiles: db.getCodeGeneratedFiles,+ },+ );++ // Determine if streaming is enabled (check both request and agent config)+ const streamingDisabled = !!primaryConfig.model_parameters?.disableStreaming;+ const isStreaming = request.stream === true && !streamingDisabled;++ // Create tracker for streaming or aggregator for non-streaming+ const tracker = isStreaming ? createOpenAIStreamTracker() : null;+ const aggregator = isStreaming ? null : createOpenAIContentAggregator();++ // Set up response for streaming+ if (isStreaming) {+ res.setHeader('Content-Type', 'text/event-stream');+ res.setHeader('Cache-Control', 'no-cache');+ res.setHeader('Connection', 'keep-alive');+ res.setHeader('X-Accel-Buffering', 'no');+ res.flushHeaders();++ // Send initial chunk with role+ const initialChunk = createChunk(context, { role: 'assistant' });+ writeSSE(res, initialChunk);+ }++ // Create handler config for OpenAI streaming (only used when streaming)+ const handlerConfig = isStreaming+ ? {+ res,+ context,+ tracker,+ }+ : null;++ // We need custom handlers that stream in OpenAI format+ const collectedUsage = [];+ /** @type {Promise<import('librechat-data-provider').TAttachment | null>[]} */+ const artifactPromises = [];++ // Create tool end callback for processing artifacts (images, file citations, code output)+ const toolEndCallback = createToolEndCallback({ req, res, artifactPromises, streamId: null });++ // Convert messages to internal format+ const openaiMessages = convertMessages(request.messages);++ // Format for agent+ const toolSet = new Set((primaryConfig.tools ?? []).map((tool) => tool && tool.name));+ const { messages: formattedMessages, indexTokenCountMap } = formatAgentMessages(+ openaiMessages,+ {},+ toolSet,+ );++ /**+ * Create a simple handler that processes data+ */+ const createHandler = (processor) => ({+ handle: (_event, data) => {+ if (processor) {+ processor(data);+ }+ },+ });++ /**+ * Stream text content in OpenAI format+ */+ const streamText = (text) => {+ if (!text) {+ return;+ }+ if (isStreaming) {+ tracker.addText();+ writeSSE(res, createChunk(context, { content: text }));+ } else {+ aggregator.addText(text);+ }+ };++ /**+ * Stream reasoning content in OpenAI format (OpenRouter convention)+ */+ const streamReasoning = (text) => {+ if (!text) {+ return;+ }+ if (isStreaming) {+ tracker.addReasoning();+ writeSSE(res, createChunk(context, { reasoning: text }));+ } else {+ aggregator.addReasoning(text);+ }+ };++ // Built-in handler for processing raw model stream chunks+ const chatModelStreamHandler = new ChatModelStreamHandler();++ // Event handlers for OpenAI-compatible streaming+ const handlers = {+ // Process raw model chunks and dispatch message/reasoning deltas+ on_chat_model_stream: {+ handle: async (event, data, metadata, graph) => {+ await chatModelStreamHandler.handle(event, data, metadata, graph);+ },+ },++ // Text content streaming+ on_message_delta: createHandler((data) => {+ const content = data?.delta?.content;+ if (Array.isArray(content)) {+ for (const part of content) {+ if (part.type === 'text' && part.text) {+ streamText(part.text);+ }+ }+ }+ }),++ // Reasoning/thinking content streaming+ on_reasoning_delta: createHandler((data) => {+ const content = data?.delta?.content;+ if (Array.isArray(content)) {+ for (const part of content) {+ const text = part.think || part.text;+ if (text) {+ streamReasoning(text);+ }+ }+ }+ }),++ // Tool call initiation - streams id and name (from on_run_step)+ on_run_step: createHandler((data) => {+ const stepDetails = data?.stepDetails;+ if (stepDetails?.type === 'tool_calls' && stepDetails.tool_calls) {+ for (const tc of stepDetails.tool_calls) {+ const toolIndex = data.index ?? 0;+ const toolId = tc.id ?? '';+ const toolName = tc.name ?? '';+ const toolCall = {+ id: toolId,+ type: 'function',+ function: { name: toolName, arguments: '' },+ };++ // Track tool call in tracker or aggregator+ if (isStreaming) {+ if (!tracker.toolCalls.has(toolIndex)) {+ tracker.toolCalls.set(toolIndex, toolCall);+ }+ // Stream initial tool call chunk (like OpenAI does)+ writeSSE(+ res,+ createChunk(context, {+ tool_calls: [{ index: toolIndex, ...toolCall }],+ }),+ );+ } else {+ if (!aggregator.toolCalls.has(toolIndex)) {+ aggregator.toolCalls.set(toolIndex, toolCall);+ }+ }+ }+ }+ }),++ // Tool call argument streaming (from on_run_step_delta)+ on_run_step_delta: createHandler((data) => {+ const delta = data?.delta;+ if (delta?.type === 'tool_calls' && delta.tool_calls) {+ for (const tc of delta.tool_calls) {+ const args = tc.args ?? '';+ if (!args) {+ continue;+ }++ const toolIndex = tc.index ?? 0;++ // Update tool call arguments+ const targetMap = isStreaming ? tracker.toolCalls : aggregator.toolCalls;+ const tracked = targetMap.get(toolIndex);+ if (tracked) {+ tracked.function.arguments += args;+ }++ // Stream argument delta (only for streaming)+ if (isStreaming) {+ writeSSE(+ res,+ createChunk(context, {+ tool_calls: [+ {+ index: toolIndex,+ function: { arguments: args },+ },+ ],+ }),+ );+ }+ }+ }+ }),++ // Usage tracking+ on_chat_model_end: createHandler((data) => {+ const usage = data?.output?.usage_metadata;+ if (usage) {+ collectedUsage.push(usage);+ const target = isStreaming ? tracker : aggregator;+ target.usage.promptTokens += usage.input_tokens ?? 0;+ target.usage.completionTokens += usage.output_tokens ?? 0;+ }+ }),+ on_run_step_completed: createHandler(),+ // Use proper ToolEndHandler for processing artifacts (images, file citations, code output)+ on_tool_end: new ToolEndHandler(toolEndCallback, logger),+ on_chain_stream: createHandler(),+ on_chain_end: createHandler(),+ on_agent_update: createHandler(),+ on_custom_event: createHandler(),+ };++ // Create and run the agent+ const userId = req.user?.id ?? 'api-user';++ // Extract userMCPAuthMap from primaryConfig (needed for MCP tool connections)+ const userMCPAuthMap = primaryConfig.userMCPAuthMap;++ const run = await createRun({+ agents: [primaryConfig],+ messages: formattedMessages,+ indexTokenCountMap,+ runId: requestId,+ signal: abortController.signal,+ customHandlers: handlers,+ requestBody: {+ messageId: requestId,+ conversationId,+ },+ user: { id: userId },+ });++ 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),+ ...(userMCPAuthMap != null && { userMCPAuthMap }),+ },+ signal: abortController.signal,+ streamMode: 'values',+ version: 'v2',+ };++ await run.processStream({ messages: formattedMessages }, config, {+ callbacks: {+ [Callback.TOOL_ERROR]: (graph, error, toolId) => {+ logger.error(`[OpenAI API] Tool Error "${toolId}"`, error);+ },+ },+ });++ // Finalize response+ if (isStreaming) {+ sendFinalChunk(handlerConfig);+ res.end();++ // Wait for artifact processing after response ends (non-blocking)+ if (artifactPromises.length > 0) {+ Promise.all(artifactPromises).catch((artifactError) => {+ logger.warn('[OpenAI API] Error processing artifacts:', artifactError);+ });+ }+ } else {+ // For non-streaming, wait for artifacts before sending response+ if (artifactPromises.length > 0) {+ try {+ await Promise.all(artifactPromises);+ } catch (artifactError) {+ logger.warn('[OpenAI API] Error processing artifacts:', artifactError);+ }+ }++ // Build usage from aggregated data+ const usage = {+ prompt_tokens: aggregator.usage.promptTokens,+ completion_tokens: aggregator.usage.completionTokens,+ total_tokens: aggregator.usage.promptTokens + aggregator.usage.completionTokens,+ };++ if (aggregator.usage.reasoningTokens > 0) {+ usage.completion_tokens_details = {+ reasoning_tokens: aggregator.usage.reasoningTokens,+ };+ }++ const response = buildNonStreamingResponse(+ context,+ aggregator.getText(),+ aggregator.getReasoning(),+ aggregator.toolCalls,+ usage,+ );+ res.json(response);+ }+ } catch (error) {+ const errorMessage = error instanceof Error ? error.message : 'An error occurred';+ logger.error('[OpenAI API] Error:', error);++ // Check if we already started streaming (headers sent)+ if (res.headersSent) {+ // Headers already sent, send error in stream+ const errorChunk = createChunk(context, { content: `\n\nError: ${errorMessage}` }, 'stop');+ writeSSE(res, errorChunk);+ writeSSE(res, '[DONE]');+ res.end();+ } else {+ sendErrorResponse(res, 500, errorMessage, 'server_error');+ }+ }+};++/**+ * List available agents as models (filtered by remote access permissions)+ *+ * GET /v1/models+ */+const ListModelsController = async (req, res) => {+ try {+ const userId = req.user?.id;+ const userRole = req.user?.role;++ if (!userId) {+ return sendErrorResponse(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 getAgents({ _id: { $in: accessibleAgentIds } });+ }++ const models = agents.map((agent) => ({+ id: agent.id,+ object: 'model',+ created: Math.floor(new Date(agent.createdAt || Date.now()).getTime() / 1000),+ owned_by: 'librechat',+ permission: [],+ root: agent.id,+ parent: null,+ // LibreChat extensions+ name: agent.name,+ description: agent.description,+ provider: agent.provider,+ }));++ res.json({+ object: 'list',+ data: models,+ });+ } catch (error) {+ const errorMessage = error instanceof Error ? error.message : 'Failed to list models';+ logger.error('[OpenAI API] Error listing models:', error);+ sendErrorResponse(res, 500, errorMessage, 'server_error');+ }+};++/**+ * Get a specific model/agent (with remote access permission check)+ *+ * GET /v1/models/:model+ */+const GetModelController = async (req, res) => {+ try {+ const { model } = req.params;+ const userId = req.user?.id;+ const userRole = req.user?.role;++ if (!userId) {+ return sendErrorResponse(res, 401, 'Authentication required', 'auth_error');+ }++ const agent = await getAgent({ id: model });++ if (!agent) {+ return sendErrorResponse(+ res,+ 404,+ `Model not found: ${model}`,+ 'invalid_request_error',+ 'model_not_found',+ );+ }++ // Check if user has remote access to this agent+ const accessibleAgentIds = await findAccessibleResources({+ userId,+ role: userRole,+ resourceType: ResourceType.REMOTE_AGENT,+ requiredPermissions: PermissionBits.VIEW,+ });++ const hasAccess = accessibleAgentIds.some((id) => id.toString() === agent._id.toString());++ if (!hasAccess) {+ return sendErrorResponse(+ res,+ 403,+ `No remote access to model: ${model}`,+ 'permission_error',+ 'access_denied',+ );+ }++ res.json({+ id: agent.id,+ object: 'model',+ created: Math.floor(new Date(agent.createdAt || Date.now()).getTime() / 1000),+ owned_by: 'librechat',+ permission: [],+ root: agent.id,+ parent: null,+ // LibreChat extensions+ name: agent.name,+ description: agent.description,+ provider: agent.provider,+ });+ } catch (error) {+ const errorMessage = error instanceof Error ? error.message : 'Failed to get model';+ logger.error('[OpenAI API] Error getting model:', error);+ sendErrorResponse(res, 500, errorMessage, 'server_error');+ }+};++module.exports = {+ OpenAIChatCompletionController,+ ListModelsController,+ GetModelController,+};diff --git a/api/server/controllers/agents/responses.js b/api/server/controllers/agents/responses.jsnew file mode 100644index 0000000000..bf52edcf7d--- /dev/null+++ b/api/server/controllers/agents/responses.js@@ -0,0 +1,800 @@+const { nanoid } = require('nanoid');+const { v4: uuidv4 } = require('uuid');+const { logger } = require('@librechat/data-schemas');+const { EModelEndpoint, ResourceType, PermissionBits } = require('librechat-data-provider');+const {+ Callback,+ ToolEndHandler,+ formatAgentMessages,+ ChatModelStreamHandler,+} = require('@librechat/agents');+const {+ createRun,+ createSafeUser,+ initializeAgent,+ // Responses API+ writeDone,+ buildResponse,+ generateResponseId,+ isValidationFailure,+ emitResponseCreated,+ createResponseContext,+ createResponseTracker,+ setupStreamingResponse,+ emitResponseInProgress,+ convertInputToMessages,+ validateResponseRequest,+ buildAggregatedResponse,+ createResponseAggregator,+ sendResponsesErrorResponse,+ createResponsesEventHandlers,+ createAggregatorEventHandlers,+} = require('@librechat/api');+const {+ createResponsesToolEndCallback,+ createToolEndCallback,+} = require('~/server/controllers/agents/callbacks');+const { findAccessibleResources } = require('~/server/services/PermissionService');+const { getConvoFiles, saveConvo, getConvo } = require('~/models/Conversation');+const { loadAgentTools } = require('~/server/services/ToolService');+const { getAgent, getAgents } = require('~/models/Agent');+const db = require('~/models');++/** @type {import('@librechat/api').AppConfig | null} */+let appConfig = null;++/**+ * Set the app config for the controller+ * @param {import('@librechat/api').AppConfig} config+ */+function setAppConfig(config) {+ appConfig = config;+}++/**+ * Creates a tool loader function for the agent.+ * @param {AbortSignal} signal - The abort signal+ */+function createToolLoader(signal) {+ return async function loadTools({+ req,+ res,+ tools,+ model,+ agentId,+ provider,+ tool_options,+ tool_resources,+ }) {+ const agent = { id: agentId, tools, provider, model, tool_options };+ try {+ return await loadAgentTools({+ req,+ res,+ agent,+ signal,+ tool_resources,+ streamId: null,+ });+ } catch (error) {+ logger.error('Error loading tools for agent ' + agentId, 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);+}++/**+ * 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) {+ try {+ const messages = await db.getMessages({ conversationId, user: userId });+ if (!messages || messages.length === 0) {+ return [];+ }++ // Convert stored messages to internal format+ return messages.map((msg) => {+ const internalMsg = {+ role: msg.isCreatedByUser ? 'user' : 'assistant',+ content: '',+ messageId: msg.messageId,+ };++ // Handle content - could be string or array+ if (typeof msg.text === 'string') {+ internalMsg.content = msg.text;+ } else if (Array.isArray(msg.content)) {+ // Handle content parts+ internalMsg.content = msg.content;+ } else if (msg.text) {+ internalMsg.content = String(msg.text);+ }++ return internalMsg;+ });+ } catch (error) {+ logger.error('[Responses API] Error loading previous messages:', error);+ return [];+ }+}++/**+ * Save input messages to database+ * @param {import('express').Request} req+ * @param {string} conversationId+ * @param {Array} inputMessages - Internal format messages+ * @param {string} agentId+ * @returns {Promise<void>}+ */+async function saveInputMessages(req, conversationId, inputMessages, agentId) {+ for (const msg of inputMessages) {+ if (msg.role === 'user') {+ await db.saveMessage(+ req,+ {+ messageId: msg.messageId || nanoid(),+ conversationId,+ parentMessageId: null,+ isCreatedByUser: true,+ text: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),+ sender: 'User',+ endpoint: EModelEndpoint.agents,+ model: agentId,+ },+ { context: 'Responses API - save user input' },+ );+ }+ }+}++/**+ * Save response output to database+ * @param {import('express').Request} req+ * @param {string} conversationId+ * @param {string} responseId+ * @param {import('@librechat/api').Response} response+ * @param {string} agentId+ * @returns {Promise<void>}+ */+async function saveResponseOutput(req, conversationId, responseId, response, agentId) {+ // Extract text content from output items+ let responseText = '';+ for (const item of response.output) {+ if (item.type === 'message' && item.content) {+ for (const part of item.content) {+ if (part.type === 'output_text' && part.text) {+ responseText += part.text;+ }+ }+ }+ }++ // Save the assistant message+ await db.saveMessage(+ req,+ {+ messageId: responseId,+ conversationId,+ parentMessageId: null,+ isCreatedByUser: false,+ text: responseText,+ sender: 'Agent',+ endpoint: EModelEndpoint.agents,+ model: agentId,+ finish_reason: response.status === 'completed' ? 'stop' : response.status,+ tokenCount: response.usage?.output_tokens,+ },+ { context: 'Responses API - save assistant response' },+ );+}++/**+ * Save or update conversation+ * @param {import('express').Request} req+ * @param {string} conversationId+ * @param {string} agentId+ * @param {object} agent+ * @returns {Promise<void>}+ */+async function saveConversation(req, conversationId, agentId, agent) {+ await saveConvo(+ req,+ {+ conversationId,+ endpoint: EModelEndpoint.agents,+ agentId,+ title: agent?.name || 'Open Responses Conversation',+ model: agent?.model,+ },+ { context: 'Responses API - save conversation' },+ );+}++/**+ * Convert stored messages to Open Responses output format+ * @param {Array} messages - Stored messages+ * @returns {Array} Output items+ */+function convertMessagesToOutputItems(messages) {+ const output = [];++ for (const msg of messages) {+ if (!msg.isCreatedByUser) {+ output.push({+ type: 'message',+ id: msg.messageId,+ role: 'assistant',+ status: 'completed',+ content: [+ {+ type: 'output_text',+ text: msg.text || '',+ annotations: [],+ },+ ],+ });+ }+ }++ return output;+}++/**+ * Create Response - POST /v1/responses+ *+ * Creates a model response following the Open Responses API specification.+ * Supports both streaming and non-streaming responses.+ *+ * @param {import('express').Request} req+ * @param {import('express').Response} res+ */+const createResponse = async (req, res) => {+ // Validate request+ const validation = validateResponseRequest(req.body);+ if (isValidationFailure(validation)) {+ return sendResponsesErrorResponse(res, 400, validation.error);+ }++ const request = validation.request;+ const agentId = request.model;+ const isStreaming = request.stream === true;++ // Look up the agent+ const agent = await getAgent({ id: agentId });+ if (!agent) {+ return sendResponsesErrorResponse(+ res,+ 404,+ `Agent not found: ${agentId}`,+ 'not_found',+ 'model_not_found',+ );+ }++ // Generate IDs+ const responseId = generateResponseId();+ const conversationId = request.previous_response_id ?? uuidv4();+ const parentMessageId = null;++ // Create response context+ const context = createResponseContext(request, responseId);++ // Set up abort controller+ const abortController = new AbortController();++ // Handle client disconnect+ req.on('close', () => {+ if (!abortController.signal.aborted) {+ abortController.abort();+ logger.debug('[Responses API] Client disconnected, aborting');+ }+ });++ try {+ // Build allowed providers set+ const allowedProviders = new Set(+ appConfig?.endpoints?.[EModelEndpoint.agents]?.allowedProviders,+ );++ // Create tool loader+ const loadTools = createToolLoader(abortController.signal);++ // Initialize the agent first to check for disableStreaming+ const endpointOption = {+ endpoint: agent.provider,+ model_parameters: agent.model_parameters ?? {},+ };++ const primaryConfig = await initializeAgent(+ {+ req,+ res,+ loadTools,+ requestFiles: [],+ conversationId,+ parentMessageId,+ agent,+ endpointOption,+ allowedProviders,+ isInitialAgent: true,+ },+ {+ getConvoFiles,+ getFiles: db.getFiles,+ getUserKey: db.getUserKey,+ getMessages: db.getMessages,+ updateFilesUsage: db.updateFilesUsage,+ getUserKeyValues: db.getUserKeyValues,+ getUserCodeFiles: db.getUserCodeFiles,+ getToolFilesByIds: db.getToolFilesByIds,+ getCodeGeneratedFiles: db.getCodeGeneratedFiles,+ },+ );++ // Determine if streaming is enabled (check both request and agent config)+ const streamingDisabled = !!primaryConfig.model_parameters?.disableStreaming;+ const actuallyStreaming = isStreaming && !streamingDisabled;++ // Load previous messages if previous_response_id is provided+ let previousMessages = [];+ if (request.previous_response_id) {+ const userId = req.user?.id ?? 'api-user';+ previousMessages = await loadPreviousMessages(request.previous_response_id, userId);+ }++ // Convert input to internal messages+ const inputMessages = convertToInternalMessages(+ typeof request.input === 'string' ? request.input : request.input,+ );++ // Merge previous messages with new input+ const allMessages = [...previousMessages, ...inputMessages];++ // Format for agent+ const toolSet = new Set((primaryConfig.tools ?? []).map((tool) => tool && tool.name));+ const { messages: formattedMessages, indexTokenCountMap } = formatAgentMessages(+ allMessages,+ {},+ toolSet,+ );++ // Create tracker for streaming or aggregator for non-streaming+ const tracker = actuallyStreaming ? createResponseTracker() : null;+ const aggregator = actuallyStreaming ? null : createResponseAggregator();++ // Set up response for streaming+ if (actuallyStreaming) {+ setupStreamingResponse(res);++ // Create handler config+ const handlerConfig = {+ res,+ context,+ tracker,+ };++ // Emit response.created then response.in_progress per Open Responses spec+ emitResponseCreated(handlerConfig);+ emitResponseInProgress(handlerConfig);++ // Create event handlers+ const { handlers: responsesHandlers, finalizeStream } =+ createResponsesEventHandlers(handlerConfig);++ // Built-in handler for processing raw model stream chunks+ const chatModelStreamHandler = new ChatModelStreamHandler();++ // Artifact promises for processing tool outputs+ /** @type {Promise<import('librechat-data-provider').TAttachment | null>[]} */+ const artifactPromises = [];+ // Use Responses API-specific callback that emits librechat:attachment events+ const toolEndCallback = createResponsesToolEndCallback({+ req,+ res,+ tracker,+ artifactPromises,+ });++ // Combine handlers+ const handlers = {+ on_chat_model_stream: {+ handle: async (event, data, metadata, graph) => {+ await chatModelStreamHandler.handle(event, data, metadata, graph);+ },+ },+ on_message_delta: responsesHandlers.on_message_delta,+ on_reasoning_delta: responsesHandlers.on_reasoning_delta,+ on_run_step: responsesHandlers.on_run_step,+ on_run_step_delta: responsesHandlers.on_run_step_delta,+ on_chat_model_end: responsesHandlers.on_chat_model_end,+ on_tool_end: new ToolEndHandler(toolEndCallback, logger),+ on_run_step_completed: { handle: () => {} },+ on_chain_stream: { handle: () => {} },+ on_chain_end: { handle: () => {} },+ on_agent_update: { handle: () => {} },+ on_custom_event: { handle: () => {} },+ };++ // Create and run the agent+ const userId = req.user?.id ?? 'api-user';+ const userMCPAuthMap = primaryConfig.userMCPAuthMap;++ const run = await createRun({+ agents: [primaryConfig],+ messages: formattedMessages,+ indexTokenCountMap,+ runId: responseId,+ signal: abortController.signal,+ customHandlers: handlers,+ requestBody: {+ messageId: responseId,+ conversationId,+ },+ user: { id: userId },+ });++ 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),+ ...(userMCPAuthMap != null && { userMCPAuthMap }),+ },+ signal: abortController.signal,+ streamMode: 'values',+ version: 'v2',+ };++ await run.processStream({ messages: formattedMessages }, config, {+ callbacks: {+ [Callback.TOOL_ERROR]: (graph, error, toolId) => {+ logger.error(`[Responses API] Tool Error "${toolId}"`, error);+ },+ },+ });++ // Finalize the stream+ finalizeStream();+ res.end();++ // Save to database if store: true+ if (request.store === true) {+ try {+ // Save conversation+ await saveConversation(req, conversationId, agentId, agent);++ // Save input messages+ await saveInputMessages(req, conversationId, inputMessages, agentId);++ // Build response for saving (use tracker with buildResponse for streaming)+ const finalResponse = buildResponse(context, tracker, 'completed');+ await saveResponseOutput(req, conversationId, responseId, finalResponse, agentId);++ logger.debug(+ `[Responses API] Stored response ${responseId} in conversation ${conversationId}`,+ );+ } catch (saveError) {+ logger.error('[Responses API] Error saving response:', saveError);+ // Don't fail the request if saving fails+ }+ }++ // Wait for artifact processing after response ends (non-blocking)+ if (artifactPromises.length > 0) {+ Promise.all(artifactPromises).catch((artifactError) => {+ logger.warn('[Responses API] Error processing artifacts:', artifactError);+ });+ }+ } else {+ // Non-streaming response+ const aggregatorHandlers = createAggregatorEventHandlers(aggregator);++ // Built-in handler for processing raw model stream chunks+ const chatModelStreamHandler = new ChatModelStreamHandler();++ // Artifact promises for processing tool outputs+ /** @type {Promise<import('librechat-data-provider').TAttachment | null>[]} */+ const artifactPromises = [];+ const toolEndCallback = createToolEndCallback({ req, res, artifactPromises, streamId: null });++ // Combine handlers+ const handlers = {+ on_chat_model_stream: {+ handle: async (event, data, metadata, graph) => {+ await chatModelStreamHandler.handle(event, data, metadata, graph);+ },+ },+ on_message_delta: aggregatorHandlers.on_message_delta,+ on_reasoning_delta: aggregatorHandlers.on_reasoning_delta,+ on_run_step: aggregatorHandlers.on_run_step,+ on_run_step_delta: aggregatorHandlers.on_run_step_delta,+ on_chat_model_end: aggregatorHandlers.on_chat_model_end,+ on_tool_end: new ToolEndHandler(toolEndCallback, logger),+ on_run_step_completed: { handle: () => {} },+ on_chain_stream: { handle: () => {} },+ on_chain_end: { handle: () => {} },+ on_agent_update: { handle: () => {} },+ on_custom_event: { handle: () => {} },+ };++ // Create and run the agent+ const userId = req.user?.id ?? 'api-user';+ const userMCPAuthMap = primaryConfig.userMCPAuthMap;++ const run = await createRun({+ agents: [primaryConfig],+ messages: formattedMessages,+ indexTokenCountMap,+ runId: responseId,+ signal: abortController.signal,+ customHandlers: handlers,+ requestBody: {+ messageId: responseId,+ conversationId,+ },+ user: { id: userId },+ });++ 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),+ ...(userMCPAuthMap != null && { userMCPAuthMap }),+ },+ signal: abortController.signal,+ streamMode: 'values',+ version: 'v2',+ };++ await run.processStream({ messages: formattedMessages }, config, {+ callbacks: {+ [Callback.TOOL_ERROR]: (graph, error, toolId) => {+ logger.error(`[Responses API] Tool Error "${toolId}"`, error);+ },+ },+ });++ // Wait for artifacts before sending response+ if (artifactPromises.length > 0) {+ try {+ await Promise.all(artifactPromises);+ } catch (artifactError) {+ logger.warn('[Responses API] Error processing artifacts:', artifactError);+ }+ }++ // Build and send the response+ const response = buildAggregatedResponse(context, aggregator);++ // Save to database if store: true+ if (request.store === true) {+ try {+ // Save conversation+ await saveConversation(req, conversationId, agentId, agent);++ // Save input messages+ await saveInputMessages(req, conversationId, inputMessages, agentId);++ // Save response output+ await saveResponseOutput(req, conversationId, responseId, response, agentId);++ logger.debug(+ `[Responses API] Stored response ${responseId} in conversation ${conversationId}`,+ );+ } catch (saveError) {+ logger.error('[Responses API] Error saving response:', saveError);+ // Don't fail the request if saving fails+ }+ }++ res.json(response);+ }+ } catch (error) {+ const errorMessage = error instanceof Error ? error.message : 'An error occurred';+ logger.error('[Responses API] Error:', error);++ // Check if we already started streaming (headers sent)+ if (res.headersSent) {+ // Headers already sent, write error event and close+ writeDone(res);+ res.end();+ } else {+ sendResponsesErrorResponse(res, 500, errorMessage, 'server_error');+ }+ }+};++/**+ * 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 getAgents({ _id: { $in: 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:', 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 = async (req, res) => {+ try {+ const responseId = req.params.id;+ const userId = req.user?.id;++ if (!responseId) {+ return sendResponsesErrorResponse(res, 400, 'Response ID is required');+ }++ // The responseId could be either the response ID or the conversation ID+ // Try to find a conversation with this ID+ const conversation = await getConvo(userId, responseId);++ if (!conversation) {+ return sendResponsesErrorResponse(+ res,+ 404,+ `Response not found: ${responseId}`,+ 'not_found',+ 'response_not_found',+ );+ }++ // Load messages for this conversation+ const messages = await db.getMessages({ conversationId: responseId, user: userId });++ if (!messages || messages.length === 0) {+ return sendResponsesErrorResponse(+ res,+ 404,+ `No messages found for response: ${responseId}`,+ 'not_found',+ 'response_not_found',+ );+ }++ // Convert messages to Open Responses output format+ const output = convertMessagesToOutputItems(messages);++ // Find the last assistant message for usage info+ const lastAssistantMessage = messages.filter((m) => !m.isCreatedByUser).pop();++ // Build the response object+ const response = {+ id: responseId,+ object: 'response',+ created_at: Math.floor(new Date(conversation.createdAt || Date.now()).getTime() / 1000),+ completed_at: Math.floor(new Date(conversation.updatedAt || Date.now()).getTime() / 1000),+ status: 'completed',+ incomplete_details: null,+ model: conversation.agentId || conversation.model || 'unknown',+ previous_response_id: null,+ instructions: null,+ output,+ error: null,+ tools: [],+ tool_choice: 'auto',+ truncation: 'disabled',+ parallel_tool_calls: true,+ text: { format: { type: 'text' } },+ temperature: 1,+ top_p: 1,+ presence_penalty: 0,+ frequency_penalty: 0,+ top_logprobs: null,+ reasoning: null,+ user: userId,+ usage: lastAssistantMessage?.tokenCount+ ? {+ input_tokens: 0,+ output_tokens: lastAssistantMessage.tokenCount,+ total_tokens: lastAssistantMessage.tokenCount,+ }+ : null,+ max_output_tokens: null,+ max_tool_calls: null,+ store: true,+ background: false,+ service_tier: 'default',+ metadata: {},+ safety_identifier: null,+ prompt_cache_key: null,+ };++ res.json(response);+ } catch (error) {+ logger.error('[Responses API] Error getting response:', error);+ sendResponsesErrorResponse(+ res,+ 500,+ error instanceof Error ? error.message : 'Failed to get response',+ 'server_error',+ );+ }+};++module.exports = {+ createResponse,+ getResponse,+ listModels,+ setAppConfig,+};diff --git a/api/server/controllers/agents/v1.js b/api/server/controllers/agents/v1.jsindex 9f0a4a2279..34078b2250 100644--- a/api/server/controllers/agents/v1.js+++ b/api/server/controllers/agents/v1.js@@ -11,7 +11,9 @@ const {convertOcrToContextInPlace,} = require('@librechat/api');const {+ Time,Tools,+ CacheKeys,Constants,FileSources,ResourceType,@@ -21,8 +23,6 @@ const {PermissionBits,actionDelimiter,removeNullishValues,- CacheKeys,- Time,} = require('librechat-data-provider');const {getListAgentsByAccess,@@ -94,16 +94,25 @@ const createAgentHandler = async (req, res) => {const agent = await createAgent(agentData);- // Automatically grant owner permissions to the creatortry {- await grantPermission({- principalType: PrincipalType.USER,- principalId: userId,- resourceType: ResourceType.AGENT,- resourceId: agent._id,- accessRoleId: AccessRoleIds.AGENT_OWNER,- grantedBy: userId,- });+ await Promise.all([+ grantPermission({+ principalType: PrincipalType.USER,+ principalId: userId,+ resourceType: ResourceType.AGENT,+ resourceId: agent._id,+ accessRoleId: AccessRoleIds.AGENT_OWNER,+ grantedBy: userId,+ }),+ grantPermission({+ principalType: PrincipalType.USER,+ principalId: userId,+ resourceType: ResourceType.REMOTE_AGENT,+ resourceId: agent._id,+ accessRoleId: AccessRoleIds.REMOTE_AGENT_OWNER,+ grantedBy: userId,+ }),+ ]);logger.debug(`[createAgent] Granted owner permissions to user ${userId} for agent ${agent.id}`,);@@ -396,16 +405,25 @@ const duplicateAgentHandler = async (req, res) => {newAgentData.actions = agentActions;const newAgent = await createAgent(newAgentData);- // Automatically grant owner permissions to the duplicatortry {- await grantPermission({- principalType: PrincipalType.USER,- principalId: userId,- resourceType: ResourceType.AGENT,- resourceId: newAgent._id,- accessRoleId: AccessRoleIds.AGENT_OWNER,- grantedBy: userId,- });+ await Promise.all([+ grantPermission({+ principalType: PrincipalType.USER,+ principalId: userId,+ resourceType: ResourceType.AGENT,+ resourceId: newAgent._id,+ accessRoleId: AccessRoleIds.AGENT_OWNER,+ grantedBy: userId,+ }),+ grantPermission({+ principalType: PrincipalType.USER,+ principalId: userId,+ resourceType: ResourceType.REMOTE_AGENT,+ resourceId: newAgent._id,+ accessRoleId: AccessRoleIds.REMOTE_AGENT_OWNER,+ grantedBy: userId,+ }),+ ]);logger.debug(`[duplicateAgent] Granted owner permissions to user ${userId} for duplicated agent ${newAgent.id}`,);diff --git a/api/server/experimental.js b/api/server/experimental.jsindex 91ef9ef286..4a457abf61 100644--- a/api/server/experimental.js+++ b/api/server/experimental.js@@ -299,6 +299,7 @@ if (cluster.isMaster) {app.use('/api/auth', routes.auth);app.use('/api/actions', routes.actions);app.use('/api/keys', routes.keys);+ app.use('/api/api-keys', routes.apiKeys);app.use('/api/user', routes.user);app.use('/api/search', routes.search);app.use('/api/messages', routes.messages);diff --git a/api/server/index.js b/api/server/index.jsindex d5129c9a7e..fcd0229c9f 100644--- a/api/server/index.js+++ b/api/server/index.js@@ -137,6 +137,7 @@ const startServer = async () => {app.use('/api/admin', routes.adminAuth);app.use('/api/actions', routes.actions);app.use('/api/keys', routes.keys);+ app.use('/api/api-keys', routes.apiKeys);app.use('/api/user', routes.user);app.use('/api/search', routes.search);app.use('/api/messages', routes.messages);diff --git a/api/server/middleware/checkSharePublicAccess.js b/api/server/middleware/checkSharePublicAccess.jsindex c094d54acb..0e95b9f6f8 100644--- a/api/server/middleware/checkSharePublicAccess.js+++ b/api/server/middleware/checkSharePublicAccess.js@@ -9,6 +9,7 @@ const resourceToPermissionType = {[ResourceType.AGENT]: PermissionTypes.AGENTS,[ResourceType.PROMPTGROUP]: PermissionTypes.PROMPTS,[ResourceType.MCPSERVER]: PermissionTypes.MCP_SERVERS,+ [ResourceType.REMOTE_AGENT]: PermissionTypes.REMOTE_AGENTS,};/**diff --git a/api/server/routes/accessPermissions.js b/api/server/routes/accessPermissions.jsindex 79e7f3ddca..45afec133b 100644--- a/api/server/routes/accessPermissions.js+++ b/api/server/routes/accessPermissions.js@@ -53,6 +53,12 @@ const checkResourcePermissionAccess = (requiredPermission) => (req, res, next) =requiredPermission,resourceIdParam: 'resourceId',});+ } else if (resourceType === ResourceType.REMOTE_AGENT) {+ middleware = canAccessResource({+ resourceType: ResourceType.REMOTE_AGENT,+ requiredPermission,+ resourceIdParam: 'resourceId',+ });} else if (resourceType === ResourceType.PROMPTGROUP) {middleware = canAccessResource({resourceType: ResourceType.PROMPTGROUP,diff --git a/api/server/routes/agents/__tests__/abort.spec.js b/api/server/routes/agents/__tests__/abort.spec.jsindex e879d51452..442665d973 100644--- a/api/server/routes/agents/__tests__/abort.spec.js+++ b/api/server/routes/agents/__tests__/abort.spec.js@@ -26,10 +26,12 @@ const mockGenerationJobManager = {const mockSaveMessage = jest.fn();jest.mock('@librechat/data-schemas', () => ({+ ...jest.requireActual('@librechat/data-schemas'),logger: mockLogger,}));jest.mock('@librechat/api', () => ({+ ...jest.requireActual('@librechat/api'),isEnabled: jest.fn().mockReturnValue(false),GenerationJobManager: mockGenerationJobManager,}));diff --git a/api/server/routes/agents/__tests__/responses.spec.js b/api/server/routes/agents/__tests__/responses.spec.jsnew file mode 100644index 0000000000..4d83219b84--- /dev/null+++ b/api/server/routes/agents/__tests__/responses.spec.js@@ -0,0 +1,1125 @@+/**+ * Open Responses API Integration Tests+ *+ * Tests the /v1/responses endpoint against the Open Responses specification+ * compliance tests. Uses real Anthropic API for LLM calls.+ *+ * @see https://openresponses.org/specification+ * @see https://github.com/openresponses/openresponses/blob/main/src/lib/compliance-tests.ts+ */++// Load environment variables from root .env file for API keys+require('dotenv').config({ path: require('path').resolve(__dirname, '../../../../../.env') });++const originalEnv = {+ CREDS_KEY: process.env.CREDS_KEY,+ CREDS_IV: process.env.CREDS_IV,+};++process.env.CREDS_KEY = '0123456789abcdef0123456789abcdef';+process.env.CREDS_IV = '0123456789abcdef';++/** Skip tests if ANTHROPIC_API_KEY is not available */+const SKIP_INTEGRATION_TESTS = !process.env.ANTHROPIC_API_KEY;+if (SKIP_INTEGRATION_TESTS) {+ console.warn('ANTHROPIC_API_KEY not found - skipping integration tests');+}++jest.mock('meilisearch', () => ({+ MeiliSearch: jest.fn().mockImplementation(() => ({+ getIndex: jest.fn().mockRejectedValue(new Error('mocked')),+ index: jest.fn().mockReturnValue({+ getRawInfo: jest.fn().mockResolvedValue({ primaryKey: 'id' }),+ updateSettings: jest.fn().mockResolvedValue({}),+ addDocuments: jest.fn().mockResolvedValue({}),+ updateDocuments: jest.fn().mockResolvedValue({}),+ deleteDocument: jest.fn().mockResolvedValue({}),+ }),+ })),+}));++jest.mock('~/server/services/Config', () => ({+ loadCustomConfig: jest.fn(() => Promise.resolve({})),+ getAppConfig: jest.fn().mockResolvedValue({+ paths: {+ uploads: '/tmp',+ dist: '/tmp/dist',+ fonts: '/tmp/fonts',+ assets: '/tmp/assets',+ },+ fileStrategy: 'local',+ imageOutputType: 'PNG',+ endpoints: {+ agents: {+ allowedProviders: ['anthropic', 'openAI'],+ },+ },+ }),+ setCachedTools: jest.fn(),+ getCachedTools: jest.fn(),+ getMCPServerTools: jest.fn().mockReturnValue([]),+}));++jest.mock('~/app/clients/tools', () => ({+ createOpenAIImageTools: jest.fn(() => []),+ createYouTubeTools: jest.fn(() => []),+ manifestToolMap: {},+ toolkits: [],+}));++jest.mock('~/config', () => ({+ createMCPServersRegistry: jest.fn(),+ createMCPManager: jest.fn().mockResolvedValue({+ getAppToolFunctions: jest.fn().mockResolvedValue({}),+ }),+}));++const express = require('express');+const request = require('supertest');+const mongoose = require('mongoose');+const { v4: uuidv4 } = require('uuid');+const { MongoMemoryServer } = require('mongodb-memory-server');+const { hashToken, getRandomValues, createModels } = require('@librechat/data-schemas');+const {+ SystemRoles,+ ResourceType,+ AccessRoleIds,+ PrincipalType,+ PrincipalModel,+ PermissionBits,+ EModelEndpoint,+} = require('librechat-data-provider');++/** @type {import('mongoose').Model} */+let Agent;+/** @type {import('mongoose').Model} */+let AgentApiKey;+/** @type {import('mongoose').Model} */+let User;+/** @type {import('mongoose').Model} */+let AclEntry;+/** @type {import('mongoose').Model} */+let AccessRole;++/**+ * Parse SSE stream into events+ * @param {string} text - Raw SSE text+ * @returns {Array<{event: string, data: unknown}>}+ */+function parseSSEEvents(text) {+ const events = [];+ const lines = text.split('\n');++ let currentEvent = '';+ let currentData = '';++ for (const line of lines) {+ if (line.startsWith('event:')) {+ currentEvent = line.slice(6).trim();+ } else if (line.startsWith('data:')) {+ currentData = line.slice(5).trim();+ } else if (line === '' && currentData) {+ if (currentData === '[DONE]') {+ events.push({ event: 'done', data: '[DONE]' });+ } else {+ try {+ const parsed = JSON.parse(currentData);+ events.push({+ event: currentEvent || parsed.type || 'unknown',+ data: parsed,+ });+ } catch {+ // Skip unparseable data+ }+ }+ currentEvent = '';+ currentData = '';+ }+ }++ return events;+}++/**+ * Valid streaming event types per Open Responses specification+ * @see https://github.com/openresponses/openresponses/blob/main/src/lib/sse-parser.ts+ */+const VALID_STREAMING_EVENT_TYPES = new Set([+ // Standard Open Responses events+ 'response.created',+ 'response.queued',+ 'response.in_progress',+ 'response.completed',+ 'response.failed',+ 'response.incomplete',+ 'response.output_item.added',+ 'response.output_item.done',+ 'response.content_part.added',+ 'response.content_part.done',+ 'response.output_text.delta',+ 'response.output_text.done',+ 'response.refusal.delta',+ 'response.refusal.done',+ 'response.function_call_arguments.delta',+ 'response.function_call_arguments.done',+ 'response.reasoning_summary_part.added',+ 'response.reasoning_summary_part.done',+ 'response.reasoning.delta',+ 'response.reasoning.done',+ 'response.reasoning_summary_text.delta',+ 'response.reasoning_summary_text.done',+ 'response.output_text.annotation.added',+ 'error',+ // LibreChat extension events (prefixed per Open Responses spec)+ // @see https://openresponses.org/specification#extending-streaming-events+ 'librechat:attachment',+]);++/**+ * Validate a streaming event against Open Responses spec+ * @param {Object} event - Parsed event with data+ * @returns {string[]} Array of validation errors+ */+function validateStreamingEvent(event) {+ const errors = [];+ const data = event.data;++ if (!data || typeof data !== 'object') {+ return errors; // Skip non-object data (e.g., [DONE])+ }++ const eventType = data.type;++ // Check event type is valid+ if (!VALID_STREAMING_EVENT_TYPES.has(eventType)) {+ errors.push(`Invalid event type: ${eventType}`);+ return errors;+ }++ // Validate required fields based on event type+ switch (eventType) {+ case 'response.output_text.delta':+ if (typeof data.sequence_number !== 'number') {+ errors.push('response.output_text.delta: missing sequence_number');+ }+ if (typeof data.item_id !== 'string') {+ errors.push('response.output_text.delta: missing item_id');+ }+ if (typeof data.output_index !== 'number') {+ errors.push('response.output_text.delta: missing output_index');+ }+ if (typeof data.content_index !== 'number') {+ errors.push('response.output_text.delta: missing content_index');+ }+ if (typeof data.delta !== 'string') {+ errors.push('response.output_text.delta: missing delta');+ }+ if (!Array.isArray(data.logprobs)) {+ errors.push('response.output_text.delta: missing logprobs array');+ }+ break;++ case 'response.output_text.done':+ if (typeof data.sequence_number !== 'number') {+ errors.push('response.output_text.done: missing sequence_number');+ }+ if (typeof data.item_id !== 'string') {+ errors.push('response.output_text.done: missing item_id');+ }+ if (typeof data.output_index !== 'number') {+ errors.push('response.output_text.done: missing output_index');+ }+ if (typeof data.content_index !== 'number') {+ errors.push('response.output_text.done: missing content_index');+ }+ if (typeof data.text !== 'string') {+ errors.push('response.output_text.done: missing text');+ }+ if (!Array.isArray(data.logprobs)) {+ errors.push('response.output_text.done: missing logprobs array');+ }+ break;++ case 'response.reasoning.delta':+ if (typeof data.sequence_number !== 'number') {+ errors.push('response.reasoning.delta: missing sequence_number');+ }+ if (typeof data.item_id !== 'string') {+ errors.push('response.reasoning.delta: missing item_id');+ }+ if (typeof data.output_index !== 'number') {+ errors.push('response.reasoning.delta: missing output_index');+ }+ if (typeof data.content_index !== 'number') {+ errors.push('response.reasoning.delta: missing content_index');+ }+ if (typeof data.delta !== 'string') {+ errors.push('response.reasoning.delta: missing delta');+ }+ break;++ case 'response.reasoning.done':+ if (typeof data.sequence_number !== 'number') {+ errors.push('response.reasoning.done: missing sequence_number');+ }+ if (typeof data.item_id !== 'string') {+ errors.push('response.reasoning.done: missing item_id');+ }+ if (typeof data.output_index !== 'number') {+ errors.push('response.reasoning.done: missing output_index');+ }+ if (typeof data.content_index !== 'number') {+ errors.push('response.reasoning.done: missing content_index');+ }+ if (typeof data.text !== 'string') {+ errors.push('response.reasoning.done: missing text');+ }+ break;++ case 'response.in_progress':+ case 'response.completed':+ case 'response.failed':+ if (!data.response || typeof data.response !== 'object') {+ errors.push(`${eventType}: missing response object`);+ }+ break;++ case 'response.output_item.added':+ case 'response.output_item.done':+ if (typeof data.output_index !== 'number') {+ errors.push(`${eventType}: missing output_index`);+ }+ if (!data.item || typeof data.item !== 'object') {+ errors.push(`${eventType}: missing item object`);+ }+ break;+ }++ return errors;+}++/**+ * Validate all streaming events and return errors+ * @param {Array} events - Array of parsed events+ * @returns {string[]} Array of all validation errors+ */+function validateAllStreamingEvents(events) {+ const allErrors = [];+ for (const event of events) {+ const errors = validateStreamingEvent(event);+ allErrors.push(...errors);+ }+ return allErrors;+}++/**+ * Create a test agent with Anthropic provider+ * @param {Object} overrides+ * @returns {Promise<Object>}+ */+async function createTestAgent(overrides = {}) {+ const timestamp = new Date();+ const agentData = {+ id: `agent_${uuidv4().replace(/-/g, '').substring(0, 21)}`,+ name: 'Test Anthropic Agent',+ description: 'An agent for testing Open Responses API',+ instructions: 'You are a helpful assistant. Be concise.',+ provider: EModelEndpoint.anthropic,+ model: 'claude-sonnet-4-5-20250929',+ author: new mongoose.Types.ObjectId(),+ tools: [],+ model_parameters: {},+ ...overrides,+ };++ const versionData = { ...agentData };+ delete versionData.author;++ const initialAgentData = {+ ...agentData,+ versions: [+ {+ ...versionData,+ createdAt: timestamp,+ updatedAt: timestamp,+ },+ ],+ category: 'general',+ };++ return (await Agent.create(initialAgentData)).toObject();+}++/**+ * Create an agent with extended thinking enabled+ * @param {Object} overrides+ * @returns {Promise<Object>}+ */+async function createThinkingAgent(overrides = {}) {+ return createTestAgent({+ name: 'Test Thinking Agent',+ description: 'An agent with extended thinking enabled',+ model_parameters: {+ thinking: {+ type: 'enabled',+ budget_tokens: 5000,+ },+ },+ ...overrides,+ });+}++const describeWithApiKey = SKIP_INTEGRATION_TESTS ? describe.skip : describe;++describeWithApiKey('Open Responses API Integration Tests', () => {+ // Increase timeout for real API calls+ jest.setTimeout(120000);++ let mongoServer;+ let app;+ let testAgent;+ let thinkingAgent;+ let testUser;+ let testApiKey; // The raw API key for Authorization header++ afterAll(() => {+ process.env.CREDS_KEY = originalEnv.CREDS_KEY;+ process.env.CREDS_IV = originalEnv.CREDS_IV;+ });++ beforeAll(async () => {+ // Start MongoDB Memory Server+ mongoServer = await MongoMemoryServer.create();+ const mongoUri = mongoServer.getUri();++ // Connect to MongoDB+ await mongoose.connect(mongoUri);++ // Register all models+ const models = createModels(mongoose);++ // Get models+ Agent = models.Agent;+ AgentApiKey = models.AgentApiKey;+ User = models.User;+ AclEntry = models.AclEntry;+ AccessRole = models.AccessRole;++ // Create minimal Express app with just the responses routes+ app = express();+ app.use(express.json());++ // Mount the responses routes+ const responsesRoutes = require('~/server/routes/agents/responses');+ app.use('/api/agents/v1/responses', responsesRoutes);++ // Create test user+ testUser = await User.create({+ name: 'Test API User',+ username: 'testapiuser',+ email: '[email protected]',+ emailVerified: true,+ provider: 'local',+ role: SystemRoles.ADMIN,+ });++ // Create REMOTE_AGENT access roles (if they don't exist)+ const existingRoles = await AccessRole.find({+ accessRoleId: {+ $in: [+ AccessRoleIds.REMOTE_AGENT_VIEWER,+ AccessRoleIds.REMOTE_AGENT_EDITOR,+ AccessRoleIds.REMOTE_AGENT_OWNER,+ ],+ },+ });++ if (existingRoles.length === 0) {+ await AccessRole.create([+ {+ accessRoleId: AccessRoleIds.REMOTE_AGENT_VIEWER,+ name: 'API Viewer',+ description: 'Can query the agent via API',+ resourceType: ResourceType.REMOTE_AGENT,+ permBits: PermissionBits.VIEW,+ },+ {+ accessRoleId: AccessRoleIds.REMOTE_AGENT_EDITOR,+ name: 'API Editor',+ description: 'Can view and modify the agent via API',+ resourceType: ResourceType.REMOTE_AGENT,+ permBits: PermissionBits.VIEW | PermissionBits.EDIT,+ },+ {+ accessRoleId: AccessRoleIds.REMOTE_AGENT_OWNER,+ name: 'API Owner',+ description: 'Full API access + can grant remote access to others',+ resourceType: ResourceType.REMOTE_AGENT,+ permBits:+ PermissionBits.VIEW |+ PermissionBits.EDIT |+ PermissionBits.DELETE |+ PermissionBits.SHARE,+ },+ ]);+ }++ // Generate and create an API key for the test user+ const rawKey = `sk-${await getRandomValues(32)}`;+ const keyHash = await hashToken(rawKey);+ const keyPrefix = rawKey.substring(0, 8);++ await AgentApiKey.create({+ userId: testUser._id,+ name: 'Test API Key',+ keyHash,+ keyPrefix,+ });++ testApiKey = rawKey;++ // Create test agents with the test user as author+ testAgent = await createTestAgent({ author: testUser._id });+ thinkingAgent = await createThinkingAgent({ author: testUser._id });++ // Grant REMOTE_AGENT permissions for the test agents+ await AclEntry.create([+ {+ principalType: PrincipalType.USER,+ principalModel: PrincipalModel.USER,+ principalId: testUser._id,+ resourceType: ResourceType.REMOTE_AGENT,+ resourceId: testAgent._id,+ accessRoleId: AccessRoleIds.REMOTE_AGENT_OWNER,+ permBits:+ PermissionBits.VIEW | PermissionBits.EDIT | PermissionBits.DELETE | PermissionBits.SHARE,+ },+ {+ principalType: PrincipalType.USER,+ principalModel: PrincipalModel.USER,+ principalId: testUser._id,+ resourceType: ResourceType.REMOTE_AGENT,+ resourceId: thinkingAgent._id,+ accessRoleId: AccessRoleIds.REMOTE_AGENT_OWNER,+ permBits:+ PermissionBits.VIEW | PermissionBits.EDIT | PermissionBits.DELETE | PermissionBits.SHARE,+ },+ ]);+ }, 60000);++ afterAll(async () => {+ await mongoose.disconnect();+ await mongoServer.stop();+ });++ beforeEach(async () => {+ // Clean up any test data between tests if needed+ });++ /* ===========================================================================+ * COMPLIANCE TESTS+ * Based on: https://github.com/openresponses/openresponses/blob/main/src/lib/compliance-tests.ts+ * =========================================================================== */++ /** Helper to add auth header to requests */+ const authRequest = () => ({+ post: (url) => request(app).post(url).set('Authorization', `Bearer ${testApiKey}`),+ get: (url) => request(app).get(url).set('Authorization', `Bearer ${testApiKey}`),+ });++ describe('Compliance Tests', () => {+ describe('basic-response', () => {+ it('should return a valid ResponseResource for a simple text request', async () => {+ const response = await authRequest()+ .post('/api/agents/v1/responses')+ .send({+ model: testAgent.id,+ input: [+ {+ type: 'message',+ role: 'user',+ content: 'Say hello in exactly 3 words.',+ },+ ],+ });++ expect(response.status).toBe(200);+ expect(response.body).toBeDefined();++ // Validate ResponseResource schema+ const body = response.body;+ expect(body.id).toMatch(/^resp_/);+ expect(body.object).toBe('response');+ expect(typeof body.created_at).toBe('number');+ expect(body.status).toBe('completed');+ expect(body.model).toBe(testAgent.id);++ // Validate output+ expect(Array.isArray(body.output)).toBe(true);+ expect(body.output.length).toBeGreaterThan(0);++ // Should have at least one message item+ const messageItem = body.output.find((item) => item.type === 'message');+ expect(messageItem).toBeDefined();+ expect(messageItem.role).toBe('assistant');+ expect(messageItem.status).toBe('completed');+ expect(Array.isArray(messageItem.content)).toBe(true);+ });+ });++ describe('streaming-response', () => {+ it('should return valid SSE streaming events', async () => {+ const response = await authRequest()+ .post('/api/agents/v1/responses')+ .send({+ model: testAgent.id,+ input: [+ {+ type: 'message',+ role: 'user',+ content: 'Count from 1 to 5.',+ },+ ],+ stream: true,+ })+ .buffer(true)+ .parse((res, callback) => {+ let data = '';+ res.on('data', (chunk) => {+ data += chunk.toString();+ });+ res.on('end', () => {+ callback(null, data);+ });+ });++ expect(response.status).toBe(200);+ expect(response.headers['content-type']).toMatch(/text\/event-stream/);++ const events = parseSSEEvents(response.body);+ expect(events.length).toBeGreaterThan(0);++ // Validate all streaming events against Open Responses spec+ // This catches issues like:+ // - Invalid event types (e.g., response.reasoning_text.delta instead of response.reasoning.delta)+ // - Missing required fields (e.g., logprobs on output_text events)+ const validationErrors = validateAllStreamingEvents(events);+ if (validationErrors.length > 0) {+ console.error('Streaming event validation errors:', validationErrors);+ }+ expect(validationErrors).toEqual([]);++ // Validate streaming event types+ const eventTypes = events.map((e) => e.event);++ // Should have response.created first (per Open Responses spec)+ expect(eventTypes).toContain('response.created');++ // Should have response.in_progress+ expect(eventTypes).toContain('response.in_progress');++ // response.created should come before response.in_progress+ const createdIdx = eventTypes.indexOf('response.created');+ const inProgressIdx = eventTypes.indexOf('response.in_progress');+ expect(createdIdx).toBeLessThan(inProgressIdx);++ // Should have response.completed or response.failed+ expect(eventTypes.some((t) => t === 'response.completed' || t === 'response.failed')).toBe(+ true,+ );++ // Should have [DONE]+ expect(eventTypes).toContain('done');++ // Validate response.completed has full response+ const completedEvent = events.find((e) => e.event === 'response.completed');+ if (completedEvent) {+ expect(completedEvent.data.response).toBeDefined();+ expect(completedEvent.data.response.status).toBe('completed');+ expect(completedEvent.data.response.output.length).toBeGreaterThan(0);+ }+ });++ it('should emit valid event types per Open Responses spec', async () => {+ const response = await authRequest()+ .post('/api/agents/v1/responses')+ .send({+ model: testAgent.id,+ input: [+ {+ type: 'message',+ role: 'user',+ content: 'Say hi.',+ },+ ],+ stream: true,+ })+ .buffer(true)+ .parse((res, callback) => {+ let data = '';+ res.on('data', (chunk) => {+ data += chunk.toString();+ });+ res.on('end', () => {+ callback(null, data);+ });+ });++ expect(response.status).toBe(200);++ const events = parseSSEEvents(response.body);++ // Check all event types are valid+ for (const event of events) {+ if (event.data && typeof event.data === 'object' && event.data.type) {+ expect(VALID_STREAMING_EVENT_TYPES.has(event.data.type)).toBe(true);+ }+ }+ });++ it('should include logprobs array in output_text events', async () => {+ const response = await authRequest()+ .post('/api/agents/v1/responses')+ .send({+ model: testAgent.id,+ input: [+ {+ type: 'message',+ role: 'user',+ content: 'Say one word.',+ },+ ],+ stream: true,+ })+ .buffer(true)+ .parse((res, callback) => {+ let data = '';+ res.on('data', (chunk) => {+ data += chunk.toString();+ });+ res.on('end', () => {+ callback(null, data);+ });+ });++ expect(response.status).toBe(200);++ const events = parseSSEEvents(response.body);++ // Find output_text delta/done events and verify logprobs+ const textDeltaEvents = events.filter(+ (e) => e.data && e.data.type === 'response.output_text.delta',+ );+ const textDoneEvents = events.filter(+ (e) => e.data && e.data.type === 'response.output_text.done',+ );++ // Should have at least one output_text event+ expect(textDeltaEvents.length + textDoneEvents.length).toBeGreaterThan(0);++ // All output_text.delta events must have logprobs array+ for (const event of textDeltaEvents) {+ expect(Array.isArray(event.data.logprobs)).toBe(true);+ }++ // All output_text.done events must have logprobs array+ for (const event of textDoneEvents) {+ expect(Array.isArray(event.data.logprobs)).toBe(true);+ }+ });+ });++ describe('system-prompt', () => {+ it('should handle developer role messages in input (as system)', async () => {+ // Note: For Anthropic, system messages must be first and there can only be one.+ // Since the agent already has instructions, we use 'developer' role which+ // gets merged into the system prompt, or we test with a simple user message+ // that instructs the behavior.+ const response = await authRequest()+ .post('/api/agents/v1/responses')+ .send({+ model: testAgent.id,+ input: [+ {+ type: 'message',+ role: 'user',+ content: 'Pretend you are a pirate and say hello in pirate speak.',+ },+ ],+ });++ expect(response.status).toBe(200);+ expect(response.body.status).toBe('completed');+ expect(response.body.output.length).toBeGreaterThan(0);++ // The response should reflect the pirate persona+ const messageItem = response.body.output.find((item) => item.type === 'message');+ expect(messageItem).toBeDefined();+ expect(messageItem.content.length).toBeGreaterThan(0);+ });+ });++ describe('multi-turn', () => {+ it('should handle multi-turn conversation history', async () => {+ const response = await authRequest()+ .post('/api/agents/v1/responses')+ .send({+ model: testAgent.id,+ input: [+ {+ type: 'message',+ role: 'user',+ content: 'My name is Alice.',+ },+ {+ type: 'message',+ role: 'assistant',+ content: 'Hello Alice! Nice to meet you. How can I help you today?',+ },+ {+ type: 'message',+ role: 'user',+ content: 'What is my name?',+ },+ ],+ });++ expect(response.status).toBe(200);+ expect(response.body.status).toBe('completed');++ // The response should reference "Alice"+ const messageItem = response.body.output.find((item) => item.type === 'message');+ expect(messageItem).toBeDefined();++ const textContent = messageItem.content.find((c) => c.type === 'output_text');+ expect(textContent).toBeDefined();+ expect(textContent.text.toLowerCase()).toContain('alice');+ });+ });++ // Note: tool-calling test requires tool setup which may need additional configuration+ // Note: image-input test requires vision-capable model++ describe('string-input', () => {+ it('should accept simple string input', async () => {+ const response = await authRequest().post('/api/agents/v1/responses').send({+ model: testAgent.id,+ input: 'Hello!',+ });++ expect(response.status).toBe(200);+ expect(response.body.status).toBe('completed');+ expect(response.body.output.length).toBeGreaterThan(0);+ });+ });+ });++ /* ===========================================================================+ * EXTENDED THINKING TESTS+ * Tests reasoning output from Claude models with extended thinking enabled+ * =========================================================================== */++ describe('Extended Thinking', () => {+ it('should return reasoning output when thinking is enabled', async () => {+ const response = await authRequest()+ .post('/api/agents/v1/responses')+ .send({+ model: thinkingAgent.id,+ input: [+ {+ type: 'message',+ role: 'user',+ content: 'What is 15 * 7? Think step by step.',+ },+ ],+ });++ expect(response.status).toBe(200);+ expect(response.body.status).toBe('completed');++ // Check for reasoning item in output+ const reasoningItem = response.body.output.find((item) => item.type === 'reasoning');+ // If reasoning is present, validate its structure per Open Responses spec+ // Note: reasoning items do NOT have a 'status' field per the spec+ // @see https://github.com/openresponses/openresponses/blob/main/src/generated/kubb/zod/reasoningBodySchema.ts+ if (reasoningItem) {+ expect(reasoningItem).toHaveProperty('id');+ expect(reasoningItem).toHaveProperty('type', 'reasoning');+ // Note: 'status' is NOT a field on reasoning items per the spec+ expect(reasoningItem).toHaveProperty('summary');+ expect(Array.isArray(reasoningItem.summary)).toBe(true);++ // Validate content items+ if (reasoningItem.content && reasoningItem.content.length > 0) {+ const reasoningContent = reasoningItem.content[0];+ expect(reasoningContent).toHaveProperty('type', 'reasoning_text');+ expect(reasoningContent).toHaveProperty('text');+ }+ }++ const messageItem = response.body.output.find((item) => item.type === 'message');+ expect(messageItem).toBeDefined();+ });++ it('should stream reasoning events when thinking is enabled', async () => {+ const response = await authRequest()+ .post('/api/agents/v1/responses')+ .send({+ model: thinkingAgent.id,+ input: [+ {+ type: 'message',+ role: 'user',+ content: 'What is 12 + 8? Think step by step.',+ },+ ],+ stream: true,+ })+ .buffer(true)+ .parse((res, callback) => {+ let data = '';+ res.on('data', (chunk) => {+ data += chunk.toString();+ });+ res.on('end', () => {+ callback(null, data);+ });+ });++ expect(response.status).toBe(200);++ const events = parseSSEEvents(response.body);++ // Validate all events against Open Responses spec+ const validationErrors = validateAllStreamingEvents(events);+ if (validationErrors.length > 0) {+ console.error('Reasoning streaming event validation errors:', validationErrors);+ }+ expect(validationErrors).toEqual([]);++ // Check for reasoning-related events using correct event types per Open Responses spec+ // Note: The spec uses response.reasoning.delta NOT response.reasoning_text.delta+ const reasoningDeltaEvents = events.filter(+ (e) => e.data && e.data.type === 'response.reasoning.delta',+ );+ const reasoningDoneEvents = events.filter(+ (e) => e.data && e.data.type === 'response.reasoning.done',+ );++ // If reasoning events are present, validate their structure+ if (reasoningDeltaEvents.length > 0) {+ const deltaEvent = reasoningDeltaEvents[0];+ expect(deltaEvent.data).toHaveProperty('item_id');+ expect(deltaEvent.data).toHaveProperty('delta');+ expect(deltaEvent.data).toHaveProperty('output_index');+ expect(deltaEvent.data).toHaveProperty('content_index');+ expect(deltaEvent.data).toHaveProperty('sequence_number');+ }++ if (reasoningDoneEvents.length > 0) {+ const doneEvent = reasoningDoneEvents[0];+ expect(doneEvent.data).toHaveProperty('item_id');+ expect(doneEvent.data).toHaveProperty('text');+ expect(doneEvent.data).toHaveProperty('output_index');+ expect(doneEvent.data).toHaveProperty('content_index');+ expect(doneEvent.data).toHaveProperty('sequence_number');+ }++ // Verify stream completed properly+ const eventTypes = events.map((e) => e.event);+ expect(eventTypes).toContain('response.completed');+ });+ });++ /* ===========================================================================+ * SCHEMA VALIDATION TESTS+ * Verify response schema compliance+ * =========================================================================== */++ describe('Schema Validation', () => {+ it('should include all required fields in response', async () => {+ const response = await authRequest().post('/api/agents/v1/responses').send({+ model: testAgent.id,+ input: 'Test',+ });++ expect(response.status).toBe(200);+ const body = response.body;++ // Required fields per Open Responses spec+ expect(body).toHaveProperty('id');+ expect(body).toHaveProperty('object', 'response');+ expect(body).toHaveProperty('created_at');+ expect(body).toHaveProperty('completed_at');+ expect(body).toHaveProperty('status');+ expect(body).toHaveProperty('model');+ expect(body).toHaveProperty('output');+ expect(body).toHaveProperty('tools');+ expect(body).toHaveProperty('tool_choice');+ expect(body).toHaveProperty('truncation');+ expect(body).toHaveProperty('parallel_tool_calls');+ expect(body).toHaveProperty('text');+ expect(body).toHaveProperty('temperature');+ expect(body).toHaveProperty('top_p');+ expect(body).toHaveProperty('presence_penalty');+ expect(body).toHaveProperty('frequency_penalty');+ expect(body).toHaveProperty('top_logprobs');+ expect(body).toHaveProperty('store');+ expect(body).toHaveProperty('background');+ expect(body).toHaveProperty('service_tier');+ expect(body).toHaveProperty('metadata');++ // top_logprobs must be a number (not null)+ expect(typeof body.top_logprobs).toBe('number');++ // Usage must have required detail fields+ expect(body).toHaveProperty('usage');+ expect(body.usage).toHaveProperty('input_tokens');+ expect(body.usage).toHaveProperty('output_tokens');+ expect(body.usage).toHaveProperty('total_tokens');+ expect(body.usage).toHaveProperty('input_tokens_details');+ expect(body.usage).toHaveProperty('output_tokens_details');+ expect(body.usage.input_tokens_details).toHaveProperty('cached_tokens');+ expect(body.usage.output_tokens_details).toHaveProperty('reasoning_tokens');+ });++ it('should have valid message item structure', async () => {+ const response = await authRequest().post('/api/agents/v1/responses').send({+ model: testAgent.id,+ input: 'Hello',+ });++ expect(response.status).toBe(200);++ const messageItem = response.body.output.find((item) => item.type === 'message');+ expect(messageItem).toBeDefined();++ // Message item required fields+ expect(messageItem).toHaveProperty('type', 'message');+ expect(messageItem).toHaveProperty('id');+ expect(messageItem).toHaveProperty('status');+ expect(messageItem).toHaveProperty('role', 'assistant');+ expect(messageItem).toHaveProperty('content');+ expect(Array.isArray(messageItem.content)).toBe(true);++ // Content part structure - verify all required fields+ if (messageItem.content.length > 0) {+ const textContent = messageItem.content.find((c) => c.type === 'output_text');+ if (textContent) {+ expect(textContent).toHaveProperty('type', 'output_text');+ expect(textContent).toHaveProperty('text');+ expect(textContent).toHaveProperty('annotations');+ expect(textContent).toHaveProperty('logprobs');+ expect(Array.isArray(textContent.annotations)).toBe(true);+ expect(Array.isArray(textContent.logprobs)).toBe(true);+ }+ }++ // Verify reasoning item has required summary field+ const reasoningItem = response.body.output.find((item) => item.type === 'reasoning');+ if (reasoningItem) {+ expect(reasoningItem).toHaveProperty('type', 'reasoning');+ expect(reasoningItem).toHaveProperty('id');+ expect(reasoningItem).toHaveProperty('summary');+ expect(Array.isArray(reasoningItem.summary)).toBe(true);+ }+ });+ });++ /* ===========================================================================+ * RESPONSE STORAGE TESTS+ * Tests for store: true and GET /v1/responses/:id+ * =========================================================================== */++ describe('Response Storage', () => {+ it('should store response when store: true and retrieve it', async () => {+ // Create a stored response+ const createResponse = await authRequest().post('/api/agents/v1/responses').send({+ model: testAgent.id,+ input: 'Remember this: The answer is 42.',+ store: true,+ });++ expect(createResponse.status).toBe(200);+ expect(createResponse.body.status).toBe('completed');++ const responseId = createResponse.body.id;+ expect(responseId).toMatch(/^resp_/);++ // Small delay to ensure database write completes+ await new Promise((resolve) => setTimeout(resolve, 500));++ // Retrieve the stored response+ const getResponseResult = await authRequest().get(`/api/agents/v1/responses/${responseId}`);++ // Note: The response might be stored under conversationId, not responseId+ // If we get 404, that's expected behavior for now since we store by conversationId+ if (getResponseResult.status === 200) {+ expect(getResponseResult.body.object).toBe('response');+ expect(getResponseResult.body.status).toBe('completed');+ expect(getResponseResult.body.output.length).toBeGreaterThan(0);+ }+ });++ it('should return 404 for non-existent response', async () => {+ const response = await authRequest().get('/api/agents/v1/responses/resp_nonexistent123');++ expect(response.status).toBe(404);+ expect(response.body.error).toBeDefined();+ });+ });++ /* ===========================================================================+ * ERROR HANDLING TESTS+ * =========================================================================== */++ describe('Error Handling', () => {+ it('should return error for missing model', async () => {+ const response = await authRequest().post('/api/agents/v1/responses').send({+ input: 'Hello',+ });++ expect(response.status).toBe(400);+ expect(response.body.error).toBeDefined();+ });++ it('should return error for missing input', async () => {+ const response = await authRequest().post('/api/agents/v1/responses').send({+ model: testAgent.id,+ });++ expect(response.status).toBe(400);+ expect(response.body.error).toBeDefined();+ });++ it('should return error for non-existent agent', async () => {+ const response = await authRequest().post('/api/agents/v1/responses').send({+ model: 'agent_nonexistent123456789',+ input: 'Hello',+ });++ expect(response.status).toBe(404);+ expect(response.body.error).toBeDefined();+ });+ });++ /* ===========================================================================+ * MODELS ENDPOINT TESTS+ * =========================================================================== */++ describe('GET /v1/responses/models', () => {+ it('should list available agents as models', async () => {+ const response = await authRequest().get('/api/agents/v1/responses/models');++ expect(response.status).toBe(200);+ expect(response.body.object).toBe('list');+ expect(Array.isArray(response.body.data)).toBe(true);++ // Should include our test agent+ const foundAgent = response.body.data.find((m) => m.id === testAgent.id);+ expect(foundAgent).toBeDefined();+ expect(foundAgent.object).toBe('model');+ expect(foundAgent.name).toBe(testAgent.name);+ });+ });+});diff --git a/api/server/routes/agents/index.js b/api/server/routes/agents/index.jsindex bf790aeee8..f8d39cb4d8 100644--- a/api/server/routes/agents/index.js+++ b/api/server/routes/agents/index.js@@ -10,6 +10,8 @@ const {messageUserLimiter,} = require('~/server/middleware');const { saveMessage } = require('~/models');+const openai = require('./openai');+const responses = require('./responses');const { v1 } = require('./v1');const chat = require('./chat');@@ -17,6 +19,20 @@ const { LIMIT_MESSAGE_IP, LIMIT_MESSAGE_USER } = process.env ?? {};const router = express.Router();+/**+ * Open Responses API routes (API key authentication handled in route file)+ * Mounted at /agents/v1/responses (full path: /api/agents/v1/responses)+ * NOTE: Must be mounted BEFORE /v1 to avoid being caught by the less specific route+ * @see https://openresponses.org/specification+ */+router.use('/v1/responses', responses);++/**+ * OpenAI-compatible API routes (API key authentication handled in route file)+ * Mounted at /agents/v1 (full path: /api/agents/v1/chat/completions)+ */+router.use('/v1', openai);+router.use(requireJwtAuth);router.use(checkBan);router.use(uaParser);diff --git a/api/server/routes/agents/openai.js b/api/server/routes/agents/openai.jsnew file mode 100644index 0000000000..9a0d9a3564--- /dev/null+++ b/api/server/routes/agents/openai.js@@ -0,0 +1,110 @@+/**+ * OpenAI-compatible API routes for LibreChat agents.+ *+ * Provides a /v1/chat/completions compatible interface for+ * interacting with LibreChat agents remotely via API.+ *+ * Usage:+ * POST /v1/chat/completions - Chat with an agent+ * GET /v1/models - List available agents+ * GET /v1/models/:model - Get agent details+ *+ * Request format:+ * {+ * "model": "agent_id_here",+ * "messages": [{"role": "user", "content": "Hello!"}],+ * "stream": true+ * }+ */+const express = require('express');+const { PermissionTypes, Permissions } = require('librechat-data-provider');+const {+ generateCheckAccess,+ createRequireApiKeyAuth,+ createCheckRemoteAgentAccess,+} = require('@librechat/api');+const {+ OpenAIChatCompletionController,+ ListModelsController,+ GetModelController,+} = require('~/server/controllers/agents/openai');+const { getEffectivePermissions } = require('~/server/services/PermissionService');+const { validateAgentApiKey, findUser } = require('~/models');+const { configMiddleware } = require('~/server/middleware');+const { getRoleByName } = require('~/models/Role');+const { getAgent } = require('~/models/Agent');++const router = express.Router();++const requireApiKeyAuth = createRequireApiKeyAuth({+ validateAgentApiKey,+ findUser,+});++const checkRemoteAgentsFeature = generateCheckAccess({+ permissionType: PermissionTypes.REMOTE_AGENTS,+ permissions: [Permissions.USE],+ getRoleByName,+});++const checkAgentPermission = createCheckRemoteAgentAccess({+ getAgent,+ getEffectivePermissions,+});++router.use(requireApiKeyAuth);+router.use(configMiddleware);+router.use(checkRemoteAgentsFeature);++/**+ * @route POST /v1/chat/completions+ * @desc OpenAI-compatible chat completions with agents+ * @access Private (API key auth required)+ *+ * Request body:+ * {+ * "model": "agent_id", // Required: The agent ID to use+ * "messages": [...], // Required: Array of chat messages+ * "stream": true, // Optional: Whether to stream (default: false)+ * "conversation_id": "...", // Optional: Conversation ID for context+ * "parent_message_id": "..." // Optional: Parent message for threading+ * }+ *+ * Response (streaming):+ * - SSE stream with OpenAI chat.completion.chunk format+ * - Includes delta.reasoning for thinking/reasoning content+ *+ * Response (non-streaming):+ * - Standard OpenAI chat.completion format+ */+router.post('/chat/completions', checkAgentPermission, OpenAIChatCompletionController);++/**+ * @route GET /v1/models+ * @desc List available agents as models+ * @access Private (API key auth required)+ *+ * Response:+ * {+ * "object": "list",+ * "data": [+ * {+ * "id": "agent_id",+ * "object": "model",+ * "name": "Agent Name",+ * "provider": "openai",+ * ...+ * }+ * ]+ * }+ */+router.get('/models', ListModelsController);++/**+ * @route GET /v1/models/:model+ * @desc Get details for a specific agent/model+ * @access Private (API key auth required)+ */+router.get('/models/:model', GetModelController);++module.exports = router;diff --git a/api/server/routes/agents/responses.js b/api/server/routes/agents/responses.jsnew file mode 100644index 0000000000..431942e921--- /dev/null+++ b/api/server/routes/agents/responses.js@@ -0,0 +1,144 @@+/**+ * Open Responses API routes for LibreChat agents.+ *+ * Implements the Open Responses specification for a forward-looking,+ * agentic API that uses items as the fundamental unit and semantic+ * streaming events.+ *+ * Usage:+ * POST /v1/responses - Create a response+ * GET /v1/models - List available agents+ *+ * Request format:+ * {+ * "model": "agent_id_here",+ * "input": "Hello!" or [{ type: "message", role: "user", content: "Hello!" }],+ * "stream": true,+ * "previous_response_id": "optional_conversation_id"+ * }+ *+ * @see https://openresponses.org/specification+ */+const express = require('express');+const { PermissionTypes, Permissions } = require('librechat-data-provider');+const {+ generateCheckAccess,+ createRequireApiKeyAuth,+ createCheckRemoteAgentAccess,+} = require('@librechat/api');+const {+ createResponse,+ getResponse,+ listModels,+} = require('~/server/controllers/agents/responses');+const { getEffectivePermissions } = require('~/server/services/PermissionService');+const { validateAgentApiKey, findUser } = require('~/models');+const { configMiddleware } = require('~/server/middleware');+const { getRoleByName } = require('~/models/Role');+const { getAgent } = require('~/models/Agent');++const router = express.Router();++const requireApiKeyAuth = createRequireApiKeyAuth({+ validateAgentApiKey,+ findUser,+});++const checkRemoteAgentsFeature = generateCheckAccess({+ permissionType: PermissionTypes.REMOTE_AGENTS,+ permissions: [Permissions.USE],+ getRoleByName,+});++const checkAgentPermission = createCheckRemoteAgentAccess({+ getAgent,+ getEffectivePermissions,+});++router.use(requireApiKeyAuth);+router.use(configMiddleware);+router.use(checkRemoteAgentsFeature);++/**+ * @route POST /v1/responses+ * @desc Create a model response following Open Responses specification+ * @access Private (API key auth required)+ *+ * Request body:+ * {+ * "model": "agent_id", // Required: The agent ID to use+ * "input": "..." | [...], // Required: String or array of input items+ * "stream": true, // Optional: Whether to stream (default: false)+ * "previous_response_id": "...", // Optional: Previous response for continuation+ * "instructions": "...", // Optional: Additional instructions+ * "tools": [...], // Optional: Additional tools+ * "tool_choice": "auto", // Optional: Tool choice mode+ * "max_output_tokens": 4096, // Optional: Max tokens+ * "temperature": 0.7 // Optional: Temperature+ * }+ *+ * Response (streaming):+ * - SSE stream with semantic events:+ * - response.in_progress+ * - response.output_item.added+ * - response.content_part.added+ * - response.output_text.delta+ * - response.output_text.done+ * - response.function_call_arguments.delta+ * - response.output_item.done+ * - response.completed+ * - [DONE]+ *+ * Response (non-streaming):+ * {+ * "id": "resp_xxx",+ * "object": "response",+ * "created_at": 1234567890,+ * "status": "completed",+ * "model": "agent_id",+ * "output": [...], // Array of output items+ * "usage": { ... }+ * }+ */+router.post('/', checkAgentPermission, createResponse);++/**+ * @route GET /v1/responses/models+ * @desc List available agents as models+ * @access Private (API key auth required)+ *+ * Response:+ * {+ * "object": "list",+ * "data": [+ * {+ * "id": "agent_id",+ * "object": "model",+ * "name": "Agent Name",+ * "provider": "openai",+ * ...+ * }+ * ]+ * }+ */+router.get('/models', listModels);++/**+ * @route GET /v1/responses/:id+ * @desc Retrieve a stored response by ID+ * @access Private (API key auth required)+ *+ * Response:+ * {+ * "id": "resp_xxx",+ * "object": "response",+ * "created_at": 1234567890,+ * "status": "completed",+ * "model": "agent_id",+ * "output": [...],+ * "usage": { ... }+ * }+ */+router.get('/:id', getResponse);++module.exports = router;diff --git a/api/server/routes/apiKeys.js b/api/server/routes/apiKeys.jsnew file mode 100644index 0000000000..29dcc326f5--- /dev/null+++ b/api/server/routes/apiKeys.js@@ -0,0 +1,36 @@+const express = require('express');+const { generateCheckAccess, createApiKeyHandlers } = require('@librechat/api');+const { PermissionTypes, Permissions } = require('librechat-data-provider');+const {+ getAgentApiKeyById,+ createAgentApiKey,+ deleteAgentApiKey,+ listAgentApiKeys,+} = require('~/models');+const { requireJwtAuth } = require('~/server/middleware');+const { getRoleByName } = require('~/models/Role');++const router = express.Router();++const handlers = createApiKeyHandlers({+ createAgentApiKey,+ listAgentApiKeys,+ deleteAgentApiKey,+ getAgentApiKeyById,+});++const checkRemoteAgentsUse = generateCheckAccess({+ permissionType: PermissionTypes.REMOTE_AGENTS,+ permissions: [Permissions.USE],+ getRoleByName,+});++router.post('/', requireJwtAuth, checkRemoteAgentsUse, handlers.createApiKey);++router.get('/', requireJwtAuth, checkRemoteAgentsUse, handlers.listApiKeys);++router.get('/:id', requireJwtAuth, checkRemoteAgentsUse, handlers.getApiKey);++router.delete('/:id', requireJwtAuth, checkRemoteAgentsUse, handlers.deleteApiKey);++module.exports = router;diff --git a/api/server/routes/index.js b/api/server/routes/index.jsindex 785e74bb8f..6a48919db3 100644--- a/api/server/routes/index.js+++ b/api/server/routes/index.js@@ -10,6 +10,7 @@ const presets = require('./presets');const prompts = require('./prompts');const balance = require('./balance');const actions = require('./actions');+const apiKeys = require('./apiKeys');const banner = require('./banner');const search = require('./search');const models = require('./models');@@ -31,6 +32,7 @@ module.exports = {auth,adminAuth,keys,+ apiKeys,user,tags,roles,diff --git a/api/server/routes/roles.js b/api/server/routes/roles.jsindex abb53141bd..12e18c7624 100644--- a/api/server/routes/roles.js+++ b/api/server/routes/roles.js@@ -6,9 +6,10 @@ const {agentPermissionsSchema,promptPermissionsSchema,memoryPermissionsSchema,+ mcpServersPermissionsSchema,marketplacePermissionsSchema,peoplePickerPermissionsSchema,- mcpServersPermissionsSchema,+ remoteAgentsPermissionsSchema,} = require('librechat-data-provider');const { checkAdmin, requireJwtAuth } = require('~/server/middleware');const { updateRoleByName, getRoleByName } = require('~/models/Role');@@ -51,6 +52,11 @@ const permissionConfigs = {permissionType: PermissionTypes.MARKETPLACE,errorMessage: 'Invalid marketplace permissions.',},+ 'remote-agents': {+ schema: remoteAgentsPermissionsSchema,+ permissionType: PermissionTypes.REMOTE_AGENTS,+ errorMessage: 'Invalid remote agents permissions.',+ },};/**@@ -160,4 +166,10 @@ router.put('/:roleName/mcp-servers', checkAdmin, createPermissionUpdateHandler('*/router.put('/:roleName/marketplace', checkAdmin, createPermissionUpdateHandler('marketplace'));+/**+ * PUT /api/roles/:roleName/remote-agents+ * Update remote agents (API) permissions for a specific role+ */+router.put('/:roleName/remote-agents', checkAdmin, createPermissionUpdateHandler('remote-agents'));+module.exports = router;diff --git a/api/server/services/PermissionService.js b/api/server/services/PermissionService.jsindex c35faf7c8d..a843f48f6f 100644--- a/api/server/services/PermissionService.js+++ b/api/server/services/PermissionService.js@@ -141,7 +141,6 @@ const checkPermission = async ({ userId, role, resourceType, resourceId, requirevalidateResourceType(resourceType);- // Get all principals for the user (user + groups + public)const principals = await getUserPrincipals({ userId, role });if (principals.length === 0) {@@ -151,7 +150,6 @@ const checkPermission = async ({ userId, role, resourceType, resourceId, requirereturn await hasPermission(principals, resourceType, resourceId, requiredPermission);} catch (error) {logger.error(`[PermissionService.checkPermission] Error: ${error.message}`);- // Re-throw validation errorsif (error.message.includes('requiredPermission must be')) {throw error;}@@ -172,12 +170,12 @@ const getEffectivePermissions = async ({ userId, role, resourceType, resourceIdtry {validateResourceType(resourceType);- // Get all principals for the user (user + groups + public)const principals = await getUserPrincipals({ userId, role });if (principals.length === 0) {return 0;}+return await getEffectivePermissionsACL(principals, resourceType, resourceId);} catch (error) {logger.error(`[PermissionService.getEffectivePermissions] Error: ${error.message}`);diff --git a/client/src/components/Nav/SettingsTabs/Data/AgentApiKeys.tsx b/client/src/components/Nav/SettingsTabs/Data/AgentApiKeys.tsxnew file mode 100644index 0000000000..f75b93526a--- /dev/null+++ b/client/src/components/Nav/SettingsTabs/Data/AgentApiKeys.tsx@@ -0,0 +1,362 @@+import React, { useState } from 'react';+import {+ useGetAgentApiKeysQuery,+ useCreateAgentApiKeyMutation,+ useDeleteAgentApiKeyMutation,+} from 'librechat-data-provider/react-query';+import { Permissions, PermissionTypes } from 'librechat-data-provider';+import { Plus, Trash2, Copy, CopyCheck, Key, Eye, EyeOff, ShieldEllipsis } from 'lucide-react';+import {+ Button,+ Input,+ Label,+ Spinner,+ OGDialog,+ OGDialogClose,+ OGDialogTitle,+ OGDialogHeader,+ OGDialogContent,+ OGDialogTrigger,+ useToastContext,+} from '@librechat/client';+import type { PermissionConfig } from '~/components/ui';+import { useUpdateRemoteAgentsPermissionsMutation } from '~/data-provider';+import { useLocalize, useCopyToClipboard } from '~/hooks';+import { AdminSettingsDialog } from '~/components/ui';++function CreateKeyDialog({ onKeyCreated }: { onKeyCreated?: () => void }) {+ const localize = useLocalize();+ const { showToast } = useToastContext();+ const [open, setOpen] = useState(false);+ const [name, setName] = useState('');+ const [newKey, setNewKey] = useState<string | null>(null);+ const [showKey, setShowKey] = useState(false);+ const [isCopying, setIsCopying] = useState(false);+ const createMutation = useCreateAgentApiKeyMutation();+ const copyKey = useCopyToClipboard({ text: newKey || '' });++ const handleCreate = async () => {+ if (!name.trim()) {+ showToast({ message: localize('com_ui_api_key_name_required'), status: 'error' });+ return;+ }++ try {+ const result = await createMutation.mutateAsync({ name: name.trim() });+ setNewKey(result.key);+ showToast({ message: localize('com_ui_api_key_created'), status: 'success' });+ onKeyCreated?.();+ } catch {+ showToast({ message: localize('com_ui_api_key_create_error'), status: 'error' });+ }+ };++ const handleClose = () => {+ setName('');+ setNewKey(null);+ setShowKey(false);+ setOpen(false);+ };++ const handleCopy = () => {+ if (isCopying) {+ return;+ }+ copyKey(setIsCopying);+ showToast({ message: localize('com_ui_api_key_copied'), status: 'success' });+ };++ return (+ <OGDialog open={open} onOpenChange={setOpen}>+ <OGDialogTrigger asChild>+ <Button variant="outline" size="sm" className="gap-2">+ <Plus className="h-4 w-4" />+ {localize('com_ui_create_api_key')}+ </Button>+ </OGDialogTrigger>+ <OGDialogContent className="max-w-md">+ <OGDialogTitle>{localize('com_ui_create_api_key')}</OGDialogTitle>+ <div className="space-y-4 py-4">+ {!newKey ? (+ <>+ <div className="space-y-2">+ <Label htmlFor="key-name">{localize('com_ui_api_key_name')}</Label>+ <Input+ id="key-name"+ value={name}+ onChange={(e) => setName(e.target.value)}+ placeholder={localize('com_ui_api_key_name_placeholder')}+ />+ </div>+ <div className="flex justify-end gap-2">+ <OGDialogClose asChild>+ <Button variant="outline" onClick={handleClose}>+ {localize('com_ui_cancel')}+ </Button>+ </OGDialogClose>+ <Button onClick={handleCreate} disabled={createMutation.isLoading}>+ {createMutation.isLoading ? (+ <Spinner className="h-4 w-4" />+ ) : (+ localize('com_ui_create')+ )}+ </Button>+ </div>+ </>+ ) : (+ <>+ <div className="rounded-lg border border-yellow-500/50 bg-yellow-50 p-4 dark:bg-yellow-900/20">+ <p className="text-sm text-yellow-800 dark:text-yellow-200">+ {localize('com_ui_api_key_warning')}+ </p>+ </div>+ <div className="space-y-2">+ <Label>{localize('com_ui_your_api_key')}</Label>+ <div className="flex gap-2">+ <Input+ value={showKey ? newKey : '•'.repeat(newKey.length)}+ readOnly+ className="font-mono text-sm"+ />+ <Button+ variant="outline"+ size="icon"+ onClick={() => setShowKey(!showKey)}+ title={showKey ? localize('com_ui_hide') : localize('com_ui_show')}+ >+ {showKey ? <EyeOff className="h-4 w-4" /> : <Eye className="h-4 w-4" />}+ </Button>+ <Button+ variant="outline"+ size="icon"+ onClick={handleCopy}+ disabled={isCopying}+ title={localize('com_ui_copy')}+ >+ {isCopying ? <CopyCheck className="h-4 w-4" /> : <Copy className="h-4 w-4" />}+ </Button>+ </div>+ </div>+ <div className="flex justify-end">+ <Button onClick={handleClose}>{localize('com_ui_done')}</Button>+ </div>+ </>+ )}+ </div>+ </OGDialogContent>+ </OGDialog>+ );+}++function KeyItem({+ id,+ name,+ keyPrefix,+ createdAt,+ lastUsedAt,+}: {+ id: string;+ name: string;+ keyPrefix: string;+ createdAt: string;+ lastUsedAt?: string;+}) {+ const localize = useLocalize();+ const { showToast } = useToastContext();+ const [confirmDelete, setConfirmDelete] = useState(false);+ const deleteMutation = useDeleteAgentApiKeyMutation();++ const handleDelete = async () => {+ try {+ await deleteMutation.mutateAsync(id);+ showToast({ message: localize('com_ui_api_key_deleted'), status: 'success' });+ } catch {+ showToast({ message: localize('com_ui_api_key_delete_error'), status: 'error' });+ }+ setConfirmDelete(false);+ };++ const formatDate = (dateStr: string) => {+ return new Date(dateStr).toLocaleDateString(undefined, {+ year: 'numeric',+ month: 'short',+ day: 'numeric',+ });+ };++ return (+ <div className="flex items-center justify-between rounded-lg border border-border-light p-3">+ <div className="flex items-center gap-3">+ <Key className="h-5 w-5 text-text-secondary" />+ <div>+ <div className="font-medium">{name}</div>+ <div className="text-sm text-text-secondary">+ <span className="font-mono">{keyPrefix}...</span>+ <span className="mx-2">•</span>+ <span>+ {localize('com_ui_created')} {formatDate(createdAt)}+ </span>+ {lastUsedAt && (+ <>+ <span className="mx-2">•</span>+ <span>+ {localize('com_ui_last_used')} {formatDate(lastUsedAt)}+ </span>+ </>+ )}+ </div>+ </div>+ </div>+ <div>+ {confirmDelete ? (+ <div className="flex gap-2">+ <Button variant="outline" size="sm" onClick={() => setConfirmDelete(false)}>+ {localize('com_ui_cancel')}+ </Button>+ <Button+ variant="destructive"+ size="sm"+ onClick={handleDelete}+ disabled={deleteMutation.isLoading}+ >+ {deleteMutation.isLoading ? (+ <Spinner className="h-4 w-4" />+ ) : (+ localize('com_ui_delete')+ )}+ </Button>+ </div>+ ) : (+ <Button+ variant="ghost"+ size="icon"+ onClick={() => setConfirmDelete(true)}+ title={localize('com_ui_delete')}+ >+ <Trash2 className="h-4 w-4 text-text-secondary hover:text-red-500" />+ </Button>+ )}+ </div>+ </div>+ );+}++function ApiKeysContent({ isOpen }: { isOpen: boolean }) {+ const localize = useLocalize();+ const { data, isLoading, error } = useGetAgentApiKeysQuery({ enabled: isOpen });++ if (error) {+ return <div className="text-sm text-red-500">{localize('com_ui_api_keys_load_error')}</div>;+ }++ return (+ <div className="space-y-4">+ <div className="flex items-center justify-end gap-2">+ <RemoteAgentsAdminSettings />+ <CreateKeyDialog />+ </div>++ <div className="max-h-[400px] space-y-2 overflow-y-auto">+ {isLoading && (+ <div className="flex items-center justify-center py-8">+ <Spinner className="h-6 w-6" />+ </div>+ )}+ {!isLoading &&+ data?.keys &&+ data.keys.length > 0 &&+ data.keys.map((key) => (+ <KeyItem+ key={key.id}+ id={key.id}+ name={key.name}+ keyPrefix={key.keyPrefix}+ createdAt={key.createdAt}+ lastUsedAt={key.lastUsedAt}+ />+ ))}+ {!isLoading && (!data?.keys || data.keys.length === 0) && (+ <div className="rounded-lg border-2 border-dashed border-border-light p-8 text-center">+ <Key className="mx-auto h-8 w-8 text-text-secondary" />+ <p className="mt-2 text-sm text-text-secondary">{localize('com_ui_no_api_keys')}</p>+ </div>+ )}+ </div>+ </div>+ );+}++const remoteAgentsPermissions: PermissionConfig[] = [+ { permission: Permissions.USE, labelKey: 'com_ui_remote_agents_allow_use' },+ { permission: Permissions.CREATE, labelKey: 'com_ui_remote_agents_allow_create' },+ { permission: Permissions.SHARE, labelKey: 'com_ui_remote_agents_allow_share' },+ { permission: Permissions.SHARE_PUBLIC, labelKey: 'com_ui_remote_agents_allow_share_public' },+];++function RemoteAgentsAdminSettings() {+ const localize = useLocalize();+ const { showToast } = useToastContext();++ const mutation = useUpdateRemoteAgentsPermissionsMutation({+ onSuccess: () => {+ showToast({ status: 'success', message: localize('com_ui_saved') });+ },+ onError: () => {+ showToast({ status: 'error', message: localize('com_ui_error_save_admin_settings') });+ },+ });++ const trigger = (+ <Button+ variant="ghost"+ size="icon"+ className="h-8 w-8"+ aria-label={localize('com_ui_admin_settings')}+ >+ <ShieldEllipsis className="h-5 w-5" aria-hidden="true" />+ </Button>+ );++ return (+ <AdminSettingsDialog+ permissionType={PermissionTypes.REMOTE_AGENTS}+ sectionKey="com_ui_remote_agents"+ permissions={remoteAgentsPermissions}+ menuId="remote-agents-role-dropdown"+ mutation={mutation}+ trigger={trigger}+ />+ );+}++export function AgentApiKeys() {+ const localize = useLocalize();+ const [isOpen, setIsOpen] = useState(false);++ return (+ <div className="flex items-center justify-between">+ <Label id="api-keys-label">{localize('com_ui_agent_api_keys')}</Label>++ <OGDialog open={isOpen} onOpenChange={setIsOpen}>+ <OGDialogTrigger asChild>+ <Button aria-labelledby="api-keys-label" variant="outline">+ {localize('com_ui_manage')}+ </Button>+ </OGDialogTrigger>++ <OGDialogContent+ title={localize('com_ui_agent_api_keys')}+ className="w-11/12 max-w-2xl bg-background text-text-primary shadow-2xl"+ >+ <OGDialogHeader>+ <OGDialogTitle>{localize('com_ui_agent_api_keys')}</OGDialogTitle>+ <p className="text-sm text-text-secondary">+ {localize('com_ui_agent_api_keys_description')}+ </p>+ </OGDialogHeader>+ <ApiKeysContent isOpen={isOpen} />+ </OGDialogContent>+ </OGDialog>+ </div>+ );+}diff --git a/client/src/components/Nav/SettingsTabs/Data/Data.tsx b/client/src/components/Nav/SettingsTabs/Data/Data.tsxindex 0bba5a152e..eb8cea98c2 100644--- a/client/src/components/Nav/SettingsTabs/Data/Data.tsx+++ b/client/src/components/Nav/SettingsTabs/Data/Data.tsx@@ -1,15 +1,22 @@import React, { useState, useRef } from 'react';import { useOnClickOutside } from '@librechat/client';+import { Permissions, PermissionTypes } from 'librechat-data-provider';import ImportConversations from './ImportConversations';-import { RevokeKeys } from './RevokeKeys';+import { AgentApiKeys } from './AgentApiKeys';import { DeleteCache } from './DeleteCache';+import { RevokeKeys } from './RevokeKeys';import { ClearChats } from './ClearChats';import SharedLinks from './SharedLinks';+import { useHasAccess } from '~/hooks';function Data() {const dataTabRef = useRef(null);const [confirmClearConvos, setConfirmClearConvos] = useState(false);useOnClickOutside(dataTabRef, () => confirmClearConvos && setConfirmClearConvos(false), []);+ const hasAccessToApiKeys = useHasAccess({+ permissionType: PermissionTypes.REMOTE_AGENTS,+ permission: Permissions.USE,+ });return (<div className="flex flex-col gap-3 p-1 text-sm text-text-primary">@@ -19,6 +26,11 @@ function Data() {<div className="pb-3"><SharedLinks /></div>+ {hasAccessToApiKeys && (+ <div className="pb-3">+ <AgentApiKeys />+ </div>+ )}<div className="pb-3"><RevokeKeys /></div>diff --git a/client/src/components/SidePanel/Agents/AgentFooter.tsx b/client/src/components/SidePanel/Agents/AgentFooter.tsxindex 80a449bb2d..b2fa996596 100644--- a/client/src/components/SidePanel/Agents/AgentFooter.tsx+++ b/client/src/components/SidePanel/Agents/AgentFooter.tsx@@ -1,3 +1,4 @@+import { Globe } from 'lucide-react';import { Spinner } from '@librechat/client';import { useWatch, useFormContext } from 'react-hook-form';import {@@ -44,13 +45,20 @@ export default function AgentFooter({permissionType: PermissionTypes.AGENTS,permission: Permissions.SHARE,});+ const hasAccessToShareRemoteAgents = useHasAccess({+ permissionType: PermissionTypes.REMOTE_AGENTS,+ permission: Permissions.SHARE,+ });const { hasPermission, isLoading: permissionsLoading } = useResourcePermissions(ResourceType.AGENT,agent?._id || '',);+ const { hasPermission: hasRemoteAgentPermission, isLoading: remotePermissionsLoading } =+ useResourcePermissions(ResourceType.REMOTE_AGENT, agent?._id || '');const canShareThisAgent = hasPermission(PermissionBits.SHARE);const canDeleteThisAgent = hasPermission(PermissionBits.DELETE);+ const canShareRemoteAgent = hasRemoteAgentPermission(PermissionBits.SHARE);const isSaving = createMutation.isLoading || updateMutation.isLoading || isAvatarUploading;const renderSaveButton = () => {if (isSaving) {@@ -91,6 +99,25 @@ export default function AgentFooter({resourceType={ResourceType.AGENT}/>)}+ {(agent?.author === user?.id || user?.role === SystemRoles.ADMIN || canShareRemoteAgent) &&+ hasAccessToShareRemoteAgents &&+ !remotePermissionsLoading &&+ agent?._id && (+ <GenericGrantAccessDialog+ resourceDbId={agent?._id}+ resourceId={agent_id}+ resourceName={agent?.name ?? ''}+ resourceType={ResourceType.REMOTE_AGENT}+ >+ <button+ type="button"+ className="btn btn-neutral border-token-border-light h-9 px-3"+ title={localize('com_ui_remote_access')}+ >+ <Globe className="h-4 w-4" aria-hidden="true" />+ </button>+ </GenericGrantAccessDialog>+ )}{agent && agent.author === user?.id && <DuplicateAgent agent_id={agent_id} />}{/* Submit Button */}<buttondiff --git a/client/src/components/SidePanel/Agents/__tests__/AgentFooter.spec.tsx b/client/src/components/SidePanel/Agents/__tests__/AgentFooter.spec.tsxindex 3425f5a75c..8d882bffe8 100644--- a/client/src/components/SidePanel/Agents/__tests__/AgentFooter.spec.tsx+++ b/client/src/components/SidePanel/Agents/__tests__/AgentFooter.spec.tsx@@ -174,7 +174,7 @@ jest.mock('~/components/Sharing', () => ({resourceType: ResourceType;}) => (<div- data-testid="grant-access-dialog"+ data-testid={`grant-access-dialog-${resourceType}`}data-resource-db-id={resourceDbId}data-resource-id={resourceId}data-resource-name={resourceName}@@ -274,7 +274,7 @@ describe('AgentFooter', () => {expect(screen.getByTestId('version-button')).toBeInTheDocument();expect(screen.getByTestId('delete-button')).toBeInTheDocument();expect(screen.queryByTestId('admin-settings')).not.toBeInTheDocument();- expect(screen.getByTestId('grant-access-dialog')).toBeInTheDocument();+ expect(screen.getByTestId('grant-access-dialog-agent')).toBeInTheDocument();expect(screen.getByTestId('duplicate-button')).toBeInTheDocument();expect(screen.queryByTestId('spinner')).not.toBeInTheDocument();});@@ -338,7 +338,7 @@ describe('AgentFooter', () => {expect(screen.getByText('Create')).toBeInTheDocument();expect(screen.queryByTestId('version-button')).not.toBeInTheDocument();expect(screen.queryByTestId('delete-button')).not.toBeInTheDocument();- expect(screen.queryByTestId('grant-access-dialog')).not.toBeInTheDocument();+ expect(screen.queryByTestId('grant-access-dialog-agent')).not.toBeInTheDocument();expect(screen.queryByTestId('duplicate-agent')).not.toBeInTheDocument();});@@ -346,7 +346,7 @@ describe('AgentFooter', () => {mockUseAuthContext.mockReturnValue(createAuthContext(mockUsers.admin));const { unmount } = render(<AgentFooter {...defaultProps} />);expect(screen.getByTestId('admin-settings')).toBeInTheDocument();- expect(screen.getByTestId('grant-access-dialog')).toBeInTheDocument();+ expect(screen.getByTestId('grant-access-dialog-agent')).toBeInTheDocument();// Clean up the first renderunmount();@@ -363,7 +363,7 @@ describe('AgentFooter', () => {return undefined;});render(<AgentFooter {...defaultProps} />);- expect(screen.queryByTestId('grant-access-dialog')).toBeInTheDocument(); // Still shows because hasAccess is true+ expect(screen.queryByTestId('grant-access-dialog-agent')).toBeInTheDocument(); // Still shows because hasAccess is trueexpect(screen.queryByTestId('duplicate-agent')).not.toBeInTheDocument(); // Should not show for different author});@@ -392,7 +392,7 @@ describe('AgentFooter', () => {permissionBits: 0,});render(<AgentFooter {...defaultProps} />);- expect(screen.queryByTestId('grant-access-dialog')).not.toBeInTheDocument();+ expect(screen.queryByTestId('grant-access-dialog-agent')).not.toBeInTheDocument();});test('hides action buttons when permissions are loading', () => {@@ -419,7 +419,7 @@ describe('AgentFooter', () => {});render(<AgentFooter {...defaultProps} />);expect(screen.queryByTestId('delete-button')).not.toBeInTheDocument();- expect(screen.queryByTestId('grant-access-dialog')).not.toBeInTheDocument();+ expect(screen.queryByTestId('grant-access-dialog-agent')).not.toBeInTheDocument();// Duplicate button should still show as it doesn't depend on permissions loadingexpect(screen.getByTestId('duplicate-button')).toBeInTheDocument();});diff --git a/client/src/data-provider/roles.ts b/client/src/data-provider/roles.tsindex 46edcd2dc9..356d9bd145 100644--- a/client/src/data-provider/roles.ts+++ b/client/src/data-provider/roles.ts@@ -4,14 +4,15 @@ import {dataService,promptPermissionsSchema,memoryPermissionsSchema,+ mcpServersPermissionsSchema,marketplacePermissionsSchema,peoplePickerPermissionsSchema,- mcpServersPermissionsSchema,+ remoteAgentsPermissionsSchema,} from 'librechat-data-provider';import type {- UseQueryOptions,- UseMutationResult,QueryObserverResult,+ UseMutationResult,+ UseQueryOptions,} from '@tanstack/react-query';import type * as t from 'librechat-data-provider';@@ -243,3 +244,39 @@ export const useUpdateMarketplacePermissionsMutation = (},);};++export const useUpdateRemoteAgentsPermissionsMutation = (+ options?: t.UpdateRemoteAgentsPermOptions,+): UseMutationResult<+ t.UpdatePermResponse,+ t.TError | undefined,+ t.UpdateRemoteAgentsPermVars,+ unknown+> => {+ const queryClient = useQueryClient();+ const { onMutate, onSuccess, onError } = options ?? {};+ return useMutation(+ (variables) => {+ remoteAgentsPermissionsSchema.partial().parse(variables.updates);+ return dataService.updateRemoteAgentsPermissions(variables);+ },+ {+ onSuccess: (data, variables, context) => {+ queryClient.invalidateQueries([QueryKeys.roles, variables.roleName]);+ if (onSuccess) {+ onSuccess(data, variables, context);+ }+ },+ onError: (...args) => {+ const error = args[0];+ if (error != null) {+ console.error('Failed to update remote agents permissions:', error);+ }+ if (onError) {+ onError(...args);+ }+ },+ onMutate,+ },+ );+};diff --git a/client/src/hooks/Sharing/useCanSharePublic.ts b/client/src/hooks/Sharing/useCanSharePublic.tsindex 699ccc9e73..54355dd9a8 100644--- a/client/src/hooks/Sharing/useCanSharePublic.ts+++ b/client/src/hooks/Sharing/useCanSharePublic.ts@@ -1,10 +1,11 @@import { ResourceType, PermissionTypes, Permissions } from 'librechat-data-provider';import { useHasAccess } from '~/hooks';-const resourceToPermissionMap: Record<ResourceType, PermissionTypes> = {+const resourceToPermissionMap: Partial<Record<ResourceType, PermissionTypes>> = {[ResourceType.AGENT]: PermissionTypes.AGENTS,[ResourceType.PROMPTGROUP]: PermissionTypes.PROMPTS,[ResourceType.MCPSERVER]: PermissionTypes.MCP_SERVERS,+ [ResourceType.REMOTE_AGENT]: PermissionTypes.REMOTE_AGENTS,};/**diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.jsonindex dfb866d690..47ccc04303 100644--- a/client/src/locales/en/translation.json+++ b/client/src/locales/en/translation.json@@ -708,6 +708,21 @@"com_ui_analyzing": "Analyzing","com_ui_analyzing_finished": "Finished analyzing","com_ui_api_key": "API Key",+ "com_ui_api_key_copied": "API key copied to clipboard",+ "com_ui_api_key_create_error": "Failed to create API key",+ "com_ui_api_key_created": "API key created successfully",+ "com_ui_api_key_delete_error": "Failed to delete API key",+ "com_ui_api_key_deleted": "API key deleted successfully",+ "com_ui_api_key_name": "Key Name",+ "com_ui_api_key_name_placeholder": "My API Key",+ "com_ui_api_key_name_required": "API key name is required",+ "com_ui_api_key_warning": "Make sure to copy your API key now. You won't be able to see it again!",+ "com_ui_api_keys_load_error": "Failed to load API keys",+ "com_ui_agent_api_keys": "Agent API Keys",+ "com_ui_agent_api_keys_description": "Create API keys to access agents remotely via the API",+ "com_ui_create_api_key": "Create API Key",+ "com_ui_no_api_keys": "No API keys yet. Create one to get started.",+ "com_ui_your_api_key": "Your API Key","com_ui_archive": "Archive","com_ui_archive_delete_error": "Failed to delete archived conversation","com_ui_archive_error": "Failed to archive conversation",@@ -838,6 +853,7 @@"com_ui_copy_to_clipboard": "Copy to clipboard","com_ui_copy_url_to_clipboard": "Copy URL to clipboard","com_ui_create": "Create",+ "com_ui_created": "Created","com_ui_create_assistant": "Create Assistant","com_ui_create_link": "Create link","com_ui_create_memory": "Create Memory",@@ -1023,6 +1039,7 @@"com_ui_hide_image_details": "Hide Image Details","com_ui_hide_password": "Hide password","com_ui_hide_qr": "Hide QR Code",+ "com_ui_hide": "Hide","com_ui_high": "High","com_ui_host": "Host","com_ui_icon": "Icon",@@ -1044,6 +1061,7 @@"com_ui_instructions": "Instructions","com_ui_key": "Key","com_ui_key_required": "API key is required",+ "com_ui_last_used": "Last used","com_ui_late_night": "Happy late night","com_ui_latest_footer": "Every AI for Everyone.","com_ui_latest_production_version": "Latest production version",@@ -1089,6 +1107,13 @@"com_ui_mcp_server_role_viewer": "MCP Server Viewer","com_ui_mcp_server_role_viewer_desc": "Can view and use MCP servers","com_ui_mcp_server_updated": "MCP server updated successfully",+ "com_ui_remote_access": "Remote Access",+ "com_ui_remote_agent_role_owner": "API Owner",+ "com_ui_remote_agent_role_owner_desc": "Full API access and can grant remote access to others",+ "com_ui_remote_agent_role_editor": "Editor",+ "com_ui_remote_agent_role_editor_desc": "Can view and modify the agent via API",+ "com_ui_remote_agent_role_viewer": "API Viewer",+ "com_ui_remote_agent_role_viewer_desc": "Can query the agent via API","com_ui_mcp_server_url_placeholder": "https://mcp.example.com","com_ui_mcp_servers": "MCP Servers","com_ui_mcp_servers_allow_create": "Allow users to create MCP servers",@@ -1238,6 +1263,11 @@"com_ui_regenerating": "Regenerating...","com_ui_region": "Region","com_ui_reinitialize": "Reinitialize",+ "com_ui_remote_agents": "Remote Agents (API)",+ "com_ui_remote_agents_allow_use": "Allow users to create API keys and query agents remotely",+ "com_ui_remote_agents_allow_create": "Allow users to create agents via API",+ "com_ui_remote_agents_allow_share": "Allow users to grant API access to agents to others",+ "com_ui_remote_agents_allow_share_public": "Allow users to grant API access to agents to all users","com_ui_remove_agent_from_chain": "Remove {{0}} from chain","com_ui_remove_user": "Remove {{0}}","com_ui_rename": "Rename",@@ -1327,6 +1357,7 @@"com_ui_shared_link_not_found": "Shared link not found","com_ui_shared_prompts": "Shared Prompts","com_ui_shop": "Shopping",+ "com_ui_show": "Show","com_ui_show_all": "Show All","com_ui_show_code": "Show Code","com_ui_show_image_details": "Show Image Details",diff --git a/client/src/utils/resources.ts b/client/src/utils/resources.tsindex f7c3586dfb..9b68cef3f6 100644--- a/client/src/utils/resources.ts+++ b/client/src/utils/resources.ts@@ -47,6 +47,19 @@ export const RESOURCE_CONFIGS: Record<ResourceType, ResourceConfig> = {`Manage permissions for ${name && name !== '' ? `"${name}"` : 'MCP server'}`,getCopyUrlMessage: () => 'MCP Server URL copied',},+ [ResourceType.REMOTE_AGENT]: {+ resourceType: ResourceType.REMOTE_AGENT,+ defaultViewerRoleId: AccessRoleIds.REMOTE_AGENT_VIEWER,+ defaultEditorRoleId: AccessRoleIds.REMOTE_AGENT_EDITOR,+ defaultOwnerRoleId: AccessRoleIds.REMOTE_AGENT_OWNER,+ getResourceUrl: () => `${window.location.origin}/api/v1/responses`,+ getResourceName: (name?: string) => (name && name !== '' ? `"${name}"` : 'remote agent'),+ getShareMessage: (name?: string) =>+ name && name !== '' ? `"${name}" (API Access)` : 'remote agent access',+ getManageMessage: (name?: string) =>+ `Manage API access for ${name && name !== '' ? `"${name}"` : 'agent'}`,+ getCopyUrlMessage: () => 'API endpoint copied',+ },};export const getResourceConfig = (resourceType: ResourceType): ResourceConfig | undefined => {diff --git a/client/src/utils/roles.ts b/client/src/utils/roles.tsindex 8bc38b7d52..1e8cb3d3b2 100644--- a/client/src/utils/roles.ts+++ b/client/src/utils/roles.ts@@ -48,6 +48,18 @@ export const ROLE_LOCALIZATIONS = {name: 'com_ui_mcp_server_role_owner' as const,description: 'com_ui_mcp_server_role_owner_desc' as const,} as const,+ remoteAgent_viewer: {+ name: 'com_ui_remote_agent_role_viewer' as const,+ description: 'com_ui_remote_agent_role_viewer_desc' as const,+ } as const,+ remoteAgent_editor: {+ name: 'com_ui_remote_agent_role_editor' as const,+ description: 'com_ui_remote_agent_role_editor_desc' as const,+ } as const,+ remoteAgent_owner: {+ name: 'com_ui_remote_agent_role_owner' as const,+ description: 'com_ui_remote_agent_role_owner_desc' as const,+ } as const,};/**diff --git a/config/delete-user.js b/config/delete-user.jsindex 2d4dea0b37..5ad85577a4 100644--- a/config/delete-user.js+++ b/config/delete-user.js@@ -23,6 +23,7 @@ const {PluginAuth,MemoryEntry,PromptGroup,+ AgentApiKey,Transaction,Conversation,ConversationTag,@@ -79,6 +80,7 @@ async function gracefulExit(code = 0) {const tasks = [Action.deleteMany({ user: uid }),Agent.deleteMany({ author: uid }),+ AgentApiKey.deleteMany({ user: uid }),Assistant.deleteMany({ user: uid }),Balance.deleteMany({ user: uid }),ConversationTag.deleteMany({ user: uid }),diff --git a/packages/api/src/agents/index.ts b/packages/api/src/agents/index.tsindex 77e7f9e2cc..6539db3db1 100644--- a/packages/api/src/agents/index.ts+++ b/packages/api/src/agents/index.ts@@ -6,6 +6,8 @@ export * from './initialize';export * from './legacy';export * from './memory';export * from './migration';+export * from './openai';export * from './resources';+export * from './responses';export * from './run';export * from './validation';diff --git a/packages/api/src/agents/openai/handlers.ts b/packages/api/src/agents/openai/handlers.tsnew file mode 100644index 0000000000..f4e4dff3d2--- /dev/null+++ b/packages/api/src/agents/openai/handlers.ts@@ -0,0 +1,454 @@+/**+ * OpenAI-compatible event handlers for agent streaming.+ *+ * These handlers convert LibreChat's internal graph events into OpenAI-compatible+ * streaming format (SSE with chat.completion.chunk objects).+ */+import type { Response as ServerResponse } from 'express';+import type {+ ChatCompletionChunkChoice,+ OpenAIResponseContext,+ ChatCompletionChunk,+ CompletionUsage,+ ToolCall,+} from './types';++/**+ * Create a chat completion chunk in OpenAI format+ */+export function createChunk(+ context: OpenAIResponseContext,+ delta: ChatCompletionChunkChoice['delta'],+ finishReason: ChatCompletionChunkChoice['finish_reason'] = null,+ usage?: CompletionUsage,+): ChatCompletionChunk {+ return {+ id: context.requestId,+ object: 'chat.completion.chunk',+ created: context.created,+ model: context.model,+ choices: [+ {+ index: 0,+ delta,+ finish_reason: finishReason,+ },+ ],+ ...(usage && { usage }),+ };+}++/**+ * Write an SSE event to the response+ */+export function writeSSE(res: ServerResponse, data: ChatCompletionChunk | string): void {+ if (typeof data === 'string') {+ res.write(`data: ${data}\n\n`);+ } else {+ res.write(`data: ${JSON.stringify(data)}\n\n`);+ }+}++/**+ * Lightweight tracker for streaming responses.+ * Only tracks what's needed for finish_reason and usage - doesn't store content.+ */+export interface OpenAIStreamTracker {+ /** Whether any text content was emitted */+ hasText: boolean;+ /** Whether any reasoning content was emitted */+ hasReasoning: boolean;+ /** Accumulated tool calls by index */+ toolCalls: Map<number, ToolCall>;+ /** Accumulated usage metadata */+ usage: {+ promptTokens: number;+ completionTokens: number;+ reasoningTokens: number;+ };+ /** Mark that text was emitted */+ addText: () => void;+ /** Mark that reasoning was emitted */+ addReasoning: () => void;+}++/**+ * Create a lightweight stream tracker (doesn't store content)+ */+export function createOpenAIStreamTracker(): OpenAIStreamTracker {+ const tracker: OpenAIStreamTracker = {+ hasText: false,+ hasReasoning: false,+ toolCalls: new Map(),+ usage: {+ promptTokens: 0,+ completionTokens: 0,+ reasoningTokens: 0,+ },+ addText: () => {+ tracker.hasText = true;+ },+ addReasoning: () => {+ tracker.hasReasoning = true;+ },+ };+ return tracker;+}++/**+ * Content aggregator for non-streaming responses.+ * Accumulates full text content, reasoning, and tool calls.+ * Uses arrays for O(n) text accumulation instead of O(n²) string concatenation.+ */+export interface OpenAIContentAggregator {+ /** Accumulated text chunks */+ textChunks: string[];+ /** Accumulated reasoning/thinking chunks */+ reasoningChunks: string[];+ /** Accumulated tool calls by index */+ toolCalls: Map<number, ToolCall>;+ /** Accumulated usage metadata */+ usage: {+ promptTokens: number;+ completionTokens: number;+ reasoningTokens: number;+ };+ /** Get accumulated text (joins chunks) */+ getText: () => string;+ /** Get accumulated reasoning (joins chunks) */+ getReasoning: () => string;+ /** Add text chunk */+ addText: (text: string) => void;+ /** Add reasoning chunk */+ addReasoning: (text: string) => void;+}++/**+ * Create a content aggregator for non-streaming responses+ */+export function createOpenAIContentAggregator(): OpenAIContentAggregator {+ const textChunks: string[] = [];+ const reasoningChunks: string[] = [];++ return {+ textChunks,+ reasoningChunks,+ toolCalls: new Map(),+ usage: {+ promptTokens: 0,+ completionTokens: 0,+ reasoningTokens: 0,+ },+ getText: () => textChunks.join(''),+ getReasoning: () => reasoningChunks.join(''),+ addText: (text: string) => textChunks.push(text),+ addReasoning: (text: string) => reasoningChunks.push(text),+ };+}++/**+ * Handler configuration for OpenAI streaming+ */+export interface OpenAIStreamHandlerConfig {+ res: ServerResponse;+ context: OpenAIResponseContext;+ tracker: OpenAIStreamTracker;+}++/**+ * Graph event types from @librechat/agents+ */+export const GraphEvents = {+ CHAT_MODEL_END: 'on_chat_model_end',+ TOOL_END: 'on_tool_end',+ CHAT_MODEL_STREAM: 'on_chat_model_stream',+ ON_RUN_STEP: 'on_run_step',+ ON_RUN_STEP_DELTA: 'on_run_step_delta',+ ON_RUN_STEP_COMPLETED: 'on_run_step_completed',+ ON_MESSAGE_DELTA: 'on_message_delta',+ ON_REASONING_DELTA: 'on_reasoning_delta',+} as const;++/**+ * Step types from librechat-data-provider+ */+export const StepTypes = {+ MESSAGE_CREATION: 'message_creation',+ TOOL_CALLS: 'tool_calls',+} as const;++/**+ * Event data interfaces+ */+export interface MessageDeltaData {+ id?: string;+ content?: Array<{ type: string; text?: string }>;+}++export interface RunStepDeltaData {+ id?: string;+ delta?: {+ type?: string;+ tool_calls?: Array<{+ index?: number;+ id?: string;+ type?: string;+ function?: {+ name?: string;+ arguments?: string;+ };+ }>;+ };+}++export interface ToolEndData {+ output?: {+ name?: string;+ tool_call_id?: string;+ content?: string;+ };+}++export interface ModelEndData {+ output?: {+ usage_metadata?: {+ input_tokens?: number;+ output_tokens?: number;+ model?: string;+ };+ };+}++/**+ * Event handler interface+ */+export interface EventHandler {+ handle(+ event: string,+ data: unknown,+ metadata?: Record<string, unknown>,+ graph?: unknown,+ ): void | Promise<void>;+}++/**+ * Handler for message delta events - streams text content+ */+export class OpenAIMessageDeltaHandler implements EventHandler {+ constructor(private config: OpenAIStreamHandlerConfig) {}++ handle(_event: string, data: MessageDeltaData): void {+ const content = data?.content;+ if (!content || !Array.isArray(content)) {+ return;+ }++ for (const part of content) {+ if (part.type === 'text' && part.text) {+ this.config.tracker.addText();+ const chunk = createChunk(this.config.context, { content: part.text });+ writeSSE(this.config.res, chunk);+ }+ }+ }+}++/**+ * Handler for run step delta events - streams tool calls+ */+export class OpenAIRunStepDeltaHandler implements EventHandler {+ constructor(private config: OpenAIStreamHandlerConfig) {}++ handle(_event: string, data: RunStepDeltaData): void {+ const delta = data?.delta;+ if (!delta || delta.type !== StepTypes.TOOL_CALLS) {+ return;+ }++ const toolCalls = delta.tool_calls;+ if (!toolCalls || !Array.isArray(toolCalls)) {+ return;+ }++ for (const tc of toolCalls) {+ if (tc.index === undefined) {+ continue;+ }++ // Initialize tool call in tracker if needed+ let trackedTc = this.config.tracker.toolCalls.get(tc.index);+ if (!trackedTc && tc.id) {+ trackedTc = {+ id: tc.id,+ type: 'function',+ function: {+ name: '',+ arguments: '',+ },+ };+ this.config.tracker.toolCalls.set(tc.index, trackedTc);+ }++ // Build the streaming delta+ const streamDelta: ChatCompletionChunkChoice['delta'] = {+ tool_calls: [+ {+ index: tc.index,+ ...(tc.id && { id: tc.id }),+ ...(tc.type && { type: tc.type as 'function' }),+ ...(tc.function && {+ function: {+ ...(tc.function.name && { name: tc.function.name }),+ ...(tc.function.arguments && { arguments: tc.function.arguments }),+ },+ }),+ },+ ],+ };++ // Update tracked tool call+ if (trackedTc) {+ if (tc.function?.name) {+ trackedTc.function.name += tc.function.name;+ }+ if (tc.function?.arguments) {+ trackedTc.function.arguments += tc.function.arguments;+ }+ }++ const chunk = createChunk(this.config.context, streamDelta);+ writeSSE(this.config.res, chunk);+ }+ }+}++/**+ * Handler for run step events - sends initial tool call info+ */+export class OpenAIRunStepHandler implements EventHandler {+ constructor(private config: OpenAIStreamHandlerConfig) {}++ handle(_event: string, data: { stepDetails?: { type?: string } }): void {+ // Run step events are primarily for LibreChat UI, we use deltas for streaming+ // This handler is a no-op for OpenAI format+ if (data?.stepDetails?.type === StepTypes.TOOL_CALLS) {+ // Tool calls will be streamed via delta events+ }+ }+}++/**+ * Handler for model end events - captures usage+ */+export class OpenAIModelEndHandler implements EventHandler {+ constructor(private config: OpenAIStreamHandlerConfig) {}++ handle(_event: string, data: ModelEndData): void {+ const usage = data?.output?.usage_metadata;+ if (!usage) {+ return;+ }++ this.config.tracker.usage.promptTokens += usage.input_tokens ?? 0;+ this.config.tracker.usage.completionTokens += usage.output_tokens ?? 0;+ }+}++/**+ * Handler for chat model stream events+ */+export class OpenAIChatModelStreamHandler implements EventHandler {+ handle(): void {+ // Handled by message delta handler+ }+}++/**+ * Handler for tool end events+ */+export class OpenAIToolEndHandler implements EventHandler {+ handle(): void {+ // Tool results don't need to be streamed in OpenAI format+ // They're used internally by the agent+ }+}++/**+ * Handler for reasoning delta events.+ * Streams reasoning/thinking content using the `delta.reasoning` field (OpenRouter convention).+ */+export class OpenAIReasoningDeltaHandler implements EventHandler {+ constructor(private config: OpenAIStreamHandlerConfig) {}++ handle(_event: string, data: MessageDeltaData): void {+ const content = data?.content;+ if (!content || !Array.isArray(content)) {+ return;+ }++ for (const part of content) {+ if (part.type === 'text' && part.text) {+ // Mark that reasoning was emitted+ this.config.tracker.addReasoning();++ // Stream as delta.reasoning (OpenRouter convention)+ const chunk = createChunk(this.config.context, { reasoning: part.text });+ writeSSE(this.config.res, chunk);+ }+ }+ }+}++/**+ * Create all handlers for OpenAI streaming format+ */+export function createOpenAIHandlers(+ config: OpenAIStreamHandlerConfig,+): Record<string, EventHandler> {+ return {+ [GraphEvents.ON_MESSAGE_DELTA]: new OpenAIMessageDeltaHandler(config),+ [GraphEvents.ON_RUN_STEP_DELTA]: new OpenAIRunStepDeltaHandler(config),+ [GraphEvents.ON_RUN_STEP]: new OpenAIRunStepHandler(config),+ [GraphEvents.ON_RUN_STEP_COMPLETED]: new OpenAIRunStepHandler(config),+ [GraphEvents.CHAT_MODEL_END]: new OpenAIModelEndHandler(config),+ [GraphEvents.CHAT_MODEL_STREAM]: new OpenAIChatModelStreamHandler(),+ [GraphEvents.TOOL_END]: new OpenAIToolEndHandler(),+ [GraphEvents.ON_REASONING_DELTA]: new OpenAIReasoningDeltaHandler(config),+ };+}++/**+ * Send the final chunk with finish_reason and optional usage+ */+export function sendFinalChunk(+ config: OpenAIStreamHandlerConfig,+ finishReason: ChatCompletionChunkChoice['finish_reason'] = 'stop',+): void {+ const { res, context, tracker } = config;++ // Determine finish reason based on content+ let reason = finishReason;+ if (tracker.toolCalls.size > 0 && !tracker.hasText) {+ reason = 'tool_calls';+ }++ // Build usage object with reasoning token details (OpenRouter/OpenAI convention)+ const usage: CompletionUsage = {+ prompt_tokens: tracker.usage.promptTokens,+ completion_tokens: tracker.usage.completionTokens,+ total_tokens: tracker.usage.promptTokens + tracker.usage.completionTokens,+ };++ // Add reasoning token breakdown if there are reasoning tokens+ if (tracker.usage.reasoningTokens > 0) {+ usage.completion_tokens_details = {+ reasoning_tokens: tracker.usage.reasoningTokens,+ };+ }++ const finalChunk = createChunk(context, {}, reason, usage);+ writeSSE(res, finalChunk);++ // Send [DONE] marker+ writeSSE(res, '[DONE]');+}diff --git a/packages/api/src/agents/openai/index.ts b/packages/api/src/agents/openai/index.tsnew file mode 100644index 0000000000..3a0a016108--- /dev/null+++ b/packages/api/src/agents/openai/index.ts@@ -0,0 +1,52 @@+/**+ * OpenAI-compatible API for LibreChat agents.+ *+ * This module provides an OpenAI v1/chat/completions compatible interface+ * for interacting with LibreChat agents remotely via API.+ *+ * @example+ * ```typescript+ * import { createAgentChatCompletion, listAgentModels } from '@librechat/api';+ *+ * // POST /v1/chat/completions+ * app.post('/v1/chat/completions', async (req, res) => {+ * await createAgentChatCompletion(req, res, dependencies);+ * });+ *+ * // GET /v1/models+ * app.get('/v1/models', async (req, res) => {+ * await listAgentModels(req, res, { getAgents });+ * });+ * ```+ *+ * Request format:+ * ```json+ * {+ * "model": "agent_id_here",+ * "messages": [+ * {"role": "user", "content": "Hello!"}+ * ],+ * "stream": true+ * }+ * ```+ *+ * The "model" parameter should be the agent ID you want to invoke.+ * Use the /v1/models endpoint to list available agents.+ */++export * from './types';+export * from './handlers';+export {+ createAgentChatCompletion,+ listAgentModels,+ convertMessages,+ validateRequest,+ isChatCompletionValidationFailure,+ createErrorResponse,+ sendErrorResponse,+ buildNonStreamingResponse,+ type ChatCompletionDependencies,+ type ChatCompletionValidationResult,+ type ChatCompletionValidationSuccess,+ type ChatCompletionValidationFailure,+} from './service';diff --git a/packages/api/src/agents/openai/service.ts b/packages/api/src/agents/openai/service.tsnew file mode 100644index 0000000000..3213e0123f--- /dev/null+++ b/packages/api/src/agents/openai/service.ts@@ -0,0 +1,554 @@+/**+ * OpenAI-compatible chat completions service for agents.+ *+ * This service provides an OpenAI v1/chat/completions compatible API for+ * interacting with LibreChat agents. The agent_id is passed as the "model"+ * parameter per OpenAI spec.+ *+ * Usage:+ * ```typescript+ * import { createAgentChatCompletion } from '@librechat/api';+ *+ * // In your Express route handler:+ * app.post('/v1/chat/completions', async (req, res) => {+ * await createAgentChatCompletion(req, res, {+ * getAgent: db.getAgent,+ * // ... other dependencies+ * });+ * });+ * ```+ */+import { nanoid } from 'nanoid';+import type { Response as ServerResponse, Request } from 'express';+import type {+ ChatCompletionResponse,+ OpenAIResponseContext,+ ChatCompletionRequest,+ OpenAIErrorResponse,+ CompletionUsage,+ ChatMessage,+ ToolCall,+} from './types';+import type { OpenAIStreamHandlerConfig, EventHandler } from './handlers';+import {+ createOpenAIContentAggregator,+ createOpenAIStreamTracker,+ createOpenAIHandlers,+ sendFinalChunk,+ createChunk,+ writeSSE,+} from './handlers';++/**+ * Dependencies for the chat completion service+ */+export interface ChatCompletionDependencies {+ /** Get agent by ID */+ getAgent: (params: { id: string }) => Promise<Agent | null>;+ /** Initialize agent for use */+ initializeAgent: (params: InitializeAgentParams) => Promise<InitializedAgent>;+ /** Load agent tools */+ loadAgentTools?: LoadToolsFn;+ /** Get models config */+ getModelsConfig?: (req: Request) => Promise<unknown>;+ /** Validate agent model */+ validateAgentModel?: (+ params: unknown,+ ) => Promise<{ isValid: boolean; error?: { message: string } }>;+ /** Log violation */+ logViolation?: (+ req: Request,+ res: ServerResponse,+ type: string,+ info: unknown,+ score: number,+ ) => Promise<void>;+ /** Create agent run */+ createRun?: CreateRunFn;+ /** App config */+ appConfig?: AppConfig;+}++/**+ * Agent type from librechat-data-provider+ */+interface Agent {+ id: string;+ name?: string;+ model?: string;+ provider: string;+ tools?: string[];+ instructions?: string;+ model_parameters?: Record<string, unknown>;+ tool_resources?: Record<string, unknown>;+ tool_options?: Record<string, unknown>;+ [key: string]: unknown;+}++/**+ * Initialized agent type - note: after initialization, tools become structured tool objects+ */+interface InitializedAgent {+ id: string;+ name?: string;+ model?: string;+ provider: string;+ /** After initialization, tools are structured tool objects, not strings */+ tools: unknown[];+ instructions?: string;+ model_parameters?: Record<string, unknown>;+ tool_resources?: Record<string, unknown>;+ tool_options?: Record<string, unknown>;+ attachments: unknown[];+ toolContextMap: Record<string, unknown>;+ maxContextTokens: number;+ userMCPAuthMap?: Record<string, Record<string, string>>;+ [key: string]: unknown;+}++/**+ * Initialize agent params+ */+interface InitializeAgentParams {+ req: Request;+ res: ServerResponse;+ agent: Agent;+ conversationId?: string | null;+ parentMessageId?: string | null;+ requestFiles?: unknown[];+ loadTools?: LoadToolsFn;+ endpointOption?: Record<string, unknown>;+ allowedProviders: Set<string>;+ isInitialAgent?: boolean;+}++/**+ * Tool loading function type+ */+type LoadToolsFn = (params: {+ req: Request;+ res: ServerResponse;+ provider: string;+ agentId: string;+ tools: string[];+ model: string | null;+ tool_options: unknown;+ tool_resources: unknown;+}) => Promise<{+ tools: unknown[];+ toolContextMap: Record<string, unknown>;+ userMCPAuthMap?: Record<string, Record<string, string>>;+} | null>;++/**+ * Create run function type+ */+type CreateRunFn = (params: {+ agents: unknown[];+ messages: unknown[];+ runId: string;+ signal: AbortSignal;+ customHandlers: Record<string, EventHandler>;+ requestBody: Record<string, unknown>;+ user: Record<string, unknown>;+ tokenCounter?: (message: unknown) => number;+}) => Promise<{+ Graph?: unknown;+ processStream: (+ input: { messages: unknown[] },+ config: Record<string, unknown>,+ options: Record<string, unknown>,+ ) => Promise<void>;+} | null>;++/**+ * App config type+ */+interface AppConfig {+ endpoints?: Record<string, unknown>;+ [key: string]: unknown;+}++/**+ * Convert OpenAI messages to LibreChat format+ */+export function convertMessages(messages: ChatMessage[]): unknown[] {+ return messages.map((msg) => {+ let content: string | unknown[];+ if (typeof msg.content === 'string') {+ content = msg.content;+ } else if (msg.content) {+ content = msg.content.map((part) => {+ if (part.type === 'text') {+ return { type: 'text', text: part.text };+ }+ if (part.type === 'image_url') {+ return { type: 'image_url', image_url: part.image_url };+ }+ return part;+ });+ } else {+ content = '';+ }++ return {+ role: msg.role,+ content,+ ...(msg.name && { name: msg.name }),+ ...(msg.tool_calls && { tool_calls: msg.tool_calls }),+ ...(msg.tool_call_id && { tool_call_id: msg.tool_call_id }),+ };+ });+}++/**+ * Create an error response in OpenAI format+ */+export function createErrorResponse(+ message: string,+ type = 'invalid_request_error',+ code: string | null = null,+): OpenAIErrorResponse {+ return {+ error: {+ message,+ type,+ param: null,+ code,+ },+ };+}++/**+ * Send an error response+ */+export function sendErrorResponse(+ res: ServerResponse,+ statusCode: number,+ message: string,+ type = 'invalid_request_error',+ code: string | null = null,+): void {+ res.status(statusCode).json(createErrorResponse(message, type, code));+}++/**+ * Validation result types for chat completion requests+ */+export type ChatCompletionValidationSuccess = { valid: true; request: ChatCompletionRequest };+export type ChatCompletionValidationFailure = { valid: false; error: string };+export type ChatCompletionValidationResult =+ | ChatCompletionValidationSuccess+ | ChatCompletionValidationFailure;++/**+ * Type guard for validation failure+ */+export function isChatCompletionValidationFailure(+ result: ChatCompletionValidationResult,+): result is ChatCompletionValidationFailure {+ return !result.valid;+}++/**+ * Validate the chat completion request+ */+export function validateRequest(body: unknown): ChatCompletionValidationResult {+ if (!body || typeof body !== 'object') {+ return { valid: false, error: 'Request body is required' };+ }++ const request = body as Record<string, unknown>;++ if (!request.model || typeof request.model !== 'string') {+ return { valid: false, error: 'model (agent_id) is required' };+ }++ if (!request.messages || !Array.isArray(request.messages)) {+ return { valid: false, error: 'messages array is required' };+ }++ if (request.messages.length === 0) {+ return { valid: false, error: 'messages array cannot be empty' };+ }++ // Validate each message has role and content+ for (let i = 0; i < request.messages.length; i++) {+ const msg = request.messages[i] as Record<string, unknown>;+ if (!msg.role || typeof msg.role !== 'string') {+ return { valid: false, error: `messages[${i}].role is required` };+ }+ if (!['system', 'user', 'assistant', 'tool'].includes(msg.role)) {+ return {+ valid: false,+ error: `messages[${i}].role must be one of: system, user, assistant, tool`,+ };+ }+ }++ return { valid: true, request: request as unknown as ChatCompletionRequest };+}++/**+ * Build a non-streaming response from aggregated content+ */+export function buildNonStreamingResponse(+ context: OpenAIResponseContext,+ text: string,+ reasoning: string,+ toolCalls: Map<number, ToolCall>,+ usage: CompletionUsage,+): ChatCompletionResponse {+ const toolCallsArray = Array.from(toolCalls.values());+ const finishReason = toolCallsArray.length > 0 && !text ? 'tool_calls' : 'stop';++ return {+ id: context.requestId,+ object: 'chat.completion',+ created: context.created,+ model: context.model,+ choices: [+ {+ index: 0,+ message: {+ role: 'assistant',+ content: text || null,+ ...(reasoning && { reasoning }),+ ...(toolCallsArray.length > 0 && { tool_calls: toolCallsArray }),+ },+ finish_reason: finishReason,+ },+ ],+ usage,+ };+}++/**+ * Main handler for OpenAI-compatible chat completions with agents.+ *+ * This function:+ * 1. Validates the request+ * 2. Looks up the agent by ID (model parameter)+ * 3. Initializes the agent with tools+ * 4. Runs the agent and streams/returns the response+ *+ * @param req - Express request object+ * @param res - Express response object+ * @param deps - Dependencies for the service+ */+export async function createAgentChatCompletion(+ req: Request,+ res: ServerResponse,+ deps: ChatCompletionDependencies,+): Promise<void> {+ // Validate request+ const validation = validateRequest(req.body);+ if (isChatCompletionValidationFailure(validation)) {+ sendErrorResponse(res, 400, validation.error);+ return;+ }++ const request = validation.request;+ const agentId = request.model;+ const requestedStreaming = request.stream === true;++ // Look up the agent+ const agent = await deps.getAgent({ id: agentId });+ if (!agent) {+ sendErrorResponse(+ res,+ 404,+ `Agent not found: ${agentId}`,+ 'invalid_request_error',+ 'model_not_found',+ );+ return;+ }++ // Generate IDs+ const requestId = `chatcmpl-${nanoid()}`;+ const conversationId = request.conversation_id ?? nanoid();+ const created = Math.floor(Date.now() / 1000);++ // Build response context+ const context: OpenAIResponseContext = {+ created,+ requestId,+ model: agentId,+ };++ // Set up abort controller+ const abortController = new AbortController();++ // Handle client disconnect+ req.on('close', () => {+ abortController.abort();+ });++ try {+ // Build allowed providers set (empty = all allowed)+ const allowedProviders = new Set<string>();++ // Initialize the agent first to check for disableStreaming+ const initializedAgent = await deps.initializeAgent({+ req,+ res,+ agent,+ conversationId,+ parentMessageId: request.parent_message_id,+ loadTools: deps.loadAgentTools,+ endpointOption: {+ endpoint: agent.provider,+ model_parameters: agent.model_parameters ?? {},+ },+ allowedProviders,+ isInitialAgent: true,+ });++ // Determine if streaming is enabled (check both request and agent config)+ const streamingDisabled = !!(initializedAgent.model_parameters as Record<string, unknown>)+ ?.disableStreaming;+ const isStreaming = requestedStreaming && !streamingDisabled;++ // Create tracker for streaming or aggregator for non-streaming+ const tracker = isStreaming ? createOpenAIStreamTracker() : null;+ const aggregator = isStreaming ? null : createOpenAIContentAggregator();++ // Set up response headers for streaming+ if (isStreaming) {+ res.setHeader('Content-Type', 'text/event-stream');+ res.setHeader('Cache-Control', 'no-cache');+ res.setHeader('Connection', 'keep-alive');+ res.setHeader('X-Accel-Buffering', 'no');+ res.flushHeaders();++ // Send initial chunk with role+ const initialChunk = createChunk(context, { role: 'assistant' });+ writeSSE(res, initialChunk);+ }++ // Create handler config (only used for streaming)+ const handlerConfig: OpenAIStreamHandlerConfig | null =+ isStreaming && tracker+ ? {+ res,+ context,+ tracker,+ }+ : null;++ // Create event handlers+ const eventHandlers = isStreaming && handlerConfig ? createOpenAIHandlers(handlerConfig) : {};++ // Convert messages to internal format+ const messages = convertMessages(request.messages);++ // Create and run the agent+ if (deps.createRun) {+ const userId = (req as unknown as { user?: { id?: string } }).user?.id ?? 'api-user';++ const run = await deps.createRun({+ agents: [initializedAgent],+ messages,+ runId: requestId,+ signal: abortController.signal,+ customHandlers: eventHandlers,+ requestBody: {+ messageId: requestId,+ conversationId,+ },+ user: { id: userId },+ });++ if (run) {+ await run.processStream(+ { messages },+ {+ runName: 'AgentRun',+ configurable: {+ thread_id: conversationId,+ user_id: userId,+ },+ signal: abortController.signal,+ streamMode: 'values',+ version: 'v2',+ },+ {},+ );+ }+ }++ // Finalize response+ if (isStreaming && handlerConfig) {+ sendFinalChunk(handlerConfig);+ res.end();+ } else if (aggregator) {+ // Build and send non-streaming response+ const usage: CompletionUsage = {+ prompt_tokens: aggregator.usage.promptTokens,+ completion_tokens: aggregator.usage.completionTokens,+ total_tokens: aggregator.usage.promptTokens + aggregator.usage.completionTokens,+ ...(aggregator.usage.reasoningTokens > 0 && {+ completion_tokens_details: { reasoning_tokens: aggregator.usage.reasoningTokens },+ }),+ };+ const response = buildNonStreamingResponse(+ context,+ aggregator.getText(),+ aggregator.getReasoning(),+ aggregator.toolCalls,+ usage,+ );+ res.json(response);+ }+ } catch (error) {+ const errorMessage = error instanceof Error ? error.message : 'An error occurred';++ // Check if we already started streaming (headers sent)+ if (res.headersSent) {+ // Headers already sent, try to send error in stream format+ const errorChunk = createChunk(context, { content: `\n\nError: ${errorMessage}` }, 'stop');+ writeSSE(res, errorChunk);+ writeSSE(res, '[DONE]');+ res.end();+ } else {+ sendErrorResponse(res, 500, errorMessage, 'server_error');+ }+ }+}++/**+ * List available agents/models+ *+ * This provides a /v1/models compatible endpoint that lists available agents.+ */+export async function listAgentModels(+ _req: Request,+ res: ServerResponse,+ deps: { getAgents: (params: Record<string, unknown>) => Promise<Agent[]> },+): Promise<void> {+ try {+ const agents = await deps.getAgents({});++ const models = agents.map((agent) => ({+ id: agent.id,+ object: 'model',+ created: Math.floor(Date.now() / 1000),+ owned_by: 'librechat',+ permission: [],+ root: agent.id,+ parent: null,+ // Extensions+ name: agent.name,+ provider: agent.provider,+ }));++ res.json({+ object: 'list',+ data: models,+ });+ } catch (error) {+ const errorMessage = error instanceof Error ? error.message : 'Failed to list models';+ sendErrorResponse(res, 500, errorMessage, 'server_error');+ }+}diff --git a/packages/api/src/agents/openai/types.ts b/packages/api/src/agents/openai/types.tsnew file mode 100644index 0000000000..a33d01d085--- /dev/null+++ b/packages/api/src/agents/openai/types.ts@@ -0,0 +1,194 @@+/**+ * OpenAI-compatible types for the agent chat completions API.+ * These types follow the OpenAI API spec for /v1/chat/completions.+ *+ * Note: This API uses agent_id as the "model" parameter per OpenAI spec.+ * In the future, this will be extended to support the Responses API.+ */++/**+ * Content part types for OpenAI format+ */+export interface OpenAITextContentPart {+ type: 'text';+ text: string;+}++export interface OpenAIImageContentPart {+ type: 'image_url';+ image_url: {+ url: string;+ detail?: 'auto' | 'low' | 'high';+ };+}++export type OpenAIContentPart = OpenAITextContentPart | OpenAIImageContentPart;++/**+ * Tool call in OpenAI format+ */+export interface ToolCall {+ id: string;+ type: 'function';+ function: {+ name: string;+ arguments: string;+ };+}++/**+ * OpenAI chat message format+ */+export interface ChatMessage {+ role: 'system' | 'user' | 'assistant' | 'tool';+ content: string | OpenAIContentPart[] | null;+ name?: string;+ tool_calls?: ToolCall[];+ tool_call_id?: string;+}++/**+ * OpenAI chat completion request+ */+export interface ChatCompletionRequest {+ /** Agent ID to invoke (maps to model in OpenAI spec) */+ model: string;+ /** Conversation messages */+ messages: ChatMessage[];+ /** Whether to stream the response */+ stream?: boolean;+ /** Maximum tokens to generate */+ max_tokens?: number;+ /** Temperature for sampling */+ temperature?: number;+ /** Top-p sampling */+ top_p?: number;+ /** Frequency penalty */+ frequency_penalty?: number;+ /** Presence penalty */+ presence_penalty?: number;+ /** Stop sequences */+ stop?: string | string[];+ /** User identifier */+ user?: string;+ /** Conversation ID (LibreChat extension) */+ conversation_id?: string;+ /** Parent message ID (LibreChat extension) */+ parent_message_id?: string;+}++/**+ * Token usage information+ */+export interface CompletionUsage {+ prompt_tokens: number;+ completion_tokens: number;+ total_tokens: number;+ /** Detailed breakdown of output tokens (OpenRouter/OpenAI convention) */+ completion_tokens_details?: {+ reasoning_tokens?: number;+ };+}++/**+ * Non-streaming choice+ */+export interface ChatCompletionChoice {+ index: number;+ message: {+ role: 'assistant';+ content: string | null;+ /** Reasoning/thinking content (OpenRouter convention) */+ reasoning?: string | null;+ tool_calls?: ToolCall[];+ };+ finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;+}++/**+ * Non-streaming response+ */+export interface ChatCompletionResponse {+ id: string;+ object: 'chat.completion';+ created: number;+ model: string;+ choices: ChatCompletionChoice[];+ usage?: CompletionUsage;+}++/**+ * Streaming choice delta+ * Note: `reasoning` field follows OpenRouter convention for streaming reasoning/thinking content+ */+export interface ChatCompletionChunkChoice {+ index: number;+ delta: {+ role?: 'assistant';+ content?: string | null;+ /** Reasoning/thinking content (OpenRouter convention) */+ reasoning?: string | null;+ tool_calls?: Array<{+ index: number;+ id?: string;+ type?: 'function';+ function?: {+ name?: string;+ arguments?: string;+ };+ }>;+ };+ finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;+}++/**+ * Streaming response chunk+ */+export interface ChatCompletionChunk {+ id: string;+ object: 'chat.completion.chunk';+ created: number;+ model: string;+ choices: ChatCompletionChunkChoice[];+ /** Final chunk may include usage */+ usage?: CompletionUsage;+}++/**+ * SSE event wrapper for streaming+ */+export interface SSEEvent {+ data: ChatCompletionChunk | '[DONE]';+}++/**+ * Context for building OpenAI responses+ */+export interface OpenAIResponseContext {+ /** Request ID for the chat completion */+ requestId: string;+ /** Model/agent ID */+ model: string;+ /** Created timestamp */+ created: number;+}++/**+ * Aggregated content for building final response+ */+export interface AggregatedContent {+ text: string;+ toolCalls: ToolCall[];+}++/**+ * Error response in OpenAI format+ */+export interface OpenAIErrorResponse {+ error: {+ message: string;+ type: string;+ param: string | null;+ code: string | null;+ };+}diff --git a/packages/api/src/agents/responses/handlers.ts b/packages/api/src/agents/responses/handlers.tsnew file mode 100644index 0000000000..712be852bd--- /dev/null+++ b/packages/api/src/agents/responses/handlers.ts@@ -0,0 +1,914 @@+/**+ * Open Responses API Handlers+ *+ * Semantic event emitters and response tracking for the Open Responses API.+ * Events follow the Open Responses spec with proper lifecycle management.+ */+import type { Response as ServerResponse } from 'express';+import type {+ Response,+ ResponseContext,+ ResponseEvent,+ OutputItem,+ MessageItem,+ FunctionCallItem,+ FunctionCallOutputItem,+ ReasoningItem,+ OutputTextContent,+ ReasoningTextContent,+ ItemStatus,+ ResponseStatus,+} from './types';++/* =============================================================================+ * RESPONSE TRACKER+ * ============================================================================= */++/**+ * Tracks the state of a response during streaming.+ * Manages items, sequence numbers, and accumulated content.+ */+export interface ResponseTracker {+ /** Current sequence number (monotonically increasing) */+ sequenceNumber: number;+ /** Output items being built */+ items: OutputItem[];+ /** Current message item (if any) */+ currentMessage: MessageItem | null;+ /** Current message content index */+ currentContentIndex: number;+ /** Current reasoning item (if any) */+ currentReasoning: ReasoningItem | null;+ /** Current reasoning content index */+ currentReasoningContentIndex: number;+ /** Map of function call items by call_id */+ functionCalls: Map<string, FunctionCallItem>;+ /** Map of function call outputs by call_id */+ functionCallOutputs: Map<string, FunctionCallOutputItem>;+ /** Accumulated text for current message */+ accumulatedText: string;+ /** Accumulated reasoning text */+ accumulatedReasoningText: string;+ /** Accumulated function call arguments by call_id */+ accumulatedArguments: Map<string, string>;+ /** Token usage */+ usage: {+ inputTokens: number;+ outputTokens: number;+ reasoningTokens: number;+ cachedTokens: number;+ };+ /** Response status */+ status: ResponseStatus;+ /** Get next sequence number */+ nextSequence: () => number;+}++/**+ * Create a new response tracker+ */+export function createResponseTracker(): ResponseTracker {+ const tracker: ResponseTracker = {+ sequenceNumber: 0,+ items: [],+ currentMessage: null,+ currentContentIndex: 0,+ currentReasoning: null,+ currentReasoningContentIndex: 0,+ functionCalls: new Map(),+ functionCallOutputs: new Map(),+ accumulatedText: '',+ accumulatedReasoningText: '',+ accumulatedArguments: new Map(),+ usage: {+ inputTokens: 0,+ outputTokens: 0,+ reasoningTokens: 0,+ cachedTokens: 0,+ },+ status: 'in_progress',+ nextSequence: () => tracker.sequenceNumber++,+ };+ return tracker;+}++/* =============================================================================+ * SSE EVENT WRITING+ * ============================================================================= */++/**+ * Write a semantic SSE event to the response.+ * The `event:` field matches the `type` in the data payload.+ */+export function writeEvent(res: ServerResponse, event: ResponseEvent): void {+ res.write(`event: ${event.type}\n`);+ res.write(`data: ${JSON.stringify(event)}\n\n`);+}++/**+ * Write the terminal [DONE] event+ */+export function writeDone(res: ServerResponse): void {+ res.write('data: [DONE]\n\n');+}++/* =============================================================================+ * RESPONSE BUILDING+ * ============================================================================= */++/**+ * Build a Response object from context and tracker+ * Includes all required fields per Open Responses spec+ */+export function buildResponse(+ context: ResponseContext,+ tracker: ResponseTracker,+ status: ResponseStatus = 'in_progress',+): Response {+ const isCompleted = status === 'completed';++ return {+ // Required fields+ id: context.responseId,+ object: 'response',+ created_at: context.createdAt,+ completed_at: isCompleted ? Math.floor(Date.now() / 1000) : null,+ status,+ incomplete_details: null,+ model: context.model,+ previous_response_id: context.previousResponseId ?? null,+ instructions: context.instructions ?? null,+ output: tracker.items,+ error: null,+ tools: [],+ tool_choice: 'auto',+ truncation: 'disabled',+ parallel_tool_calls: true,+ text: { format: { type: 'text' } },+ temperature: 1,+ top_p: 1,+ presence_penalty: 0,+ frequency_penalty: 0,+ top_logprobs: 0,+ reasoning: null,+ user: null,+ usage: isCompleted+ ? {+ input_tokens: tracker.usage.inputTokens,+ output_tokens: tracker.usage.outputTokens,+ total_tokens: tracker.usage.inputTokens + tracker.usage.outputTokens,+ input_tokens_details: { cached_tokens: tracker.usage.cachedTokens },+ output_tokens_details: { reasoning_tokens: tracker.usage.reasoningTokens },+ }+ : null,+ max_output_tokens: null,+ max_tool_calls: null,+ store: false,+ background: false,+ service_tier: 'default',+ metadata: {},+ safety_identifier: null,+ prompt_cache_key: null,+ };+}++/* =============================================================================+ * ITEM BUILDERS+ * ============================================================================= */++let itemIdCounter = 0;++/**+ * Generate a unique item ID+ */+export function generateItemId(prefix: string): string {+ return `${prefix}_${Date.now().toString(36)}${(itemIdCounter++).toString(36)}`;+}++/**+ * Create a new message item+ */+export function createMessageItem(status: ItemStatus = 'in_progress'): MessageItem {+ return {+ type: 'message',+ id: generateItemId('msg'),+ role: 'assistant',+ status,+ content: [],+ };+}++/**+ * Create a new function call item+ */+export function createFunctionCallItem(+ callId: string,+ name: string,+ status: ItemStatus = 'in_progress',+): FunctionCallItem {+ return {+ type: 'function_call',+ id: generateItemId('fc'),+ call_id: callId,+ name,+ arguments: '',+ status,+ };+}++/**+ * Create a new function call output item+ */+export function createFunctionCallOutputItem(+ callId: string,+ output: string,+ status: ItemStatus = 'completed',+): FunctionCallOutputItem {+ return {+ type: 'function_call_output',+ id: generateItemId('fco'),+ call_id: callId,+ output,+ status,+ };+}++/**+ * Create a new reasoning item+ */+export function createReasoningItem(status: ItemStatus = 'in_progress'): ReasoningItem {+ return {+ type: 'reasoning',+ id: generateItemId('reason'),+ status,+ content: [],+ summary: [],+ };+}++/**+ * Create output text content+ */+export function createOutputTextContent(text: string = ''): OutputTextContent {+ return {+ type: 'output_text',+ text,+ annotations: [],+ logprobs: [],+ };+}++/**+ * Create reasoning text content+ */+export function createReasoningTextContent(text: string = ''): ReasoningTextContent {+ return {+ type: 'reasoning_text',+ text,+ };+}++/* =============================================================================+ * STREAMING EVENT EMITTERS+ * ============================================================================= */++export interface StreamHandlerConfig {+ res: ServerResponse;+ context: ResponseContext;+ tracker: ResponseTracker;+}++/**+ * Emit response.created event+ * This is the first event emitted per the Open Responses spec+ */+export function emitResponseCreated(config: StreamHandlerConfig): void {+ const { res, context, tracker } = config;+ const response = buildResponse(context, tracker, 'in_progress');+ writeEvent(res, {+ type: 'response.created',+ sequence_number: tracker.nextSequence(),+ response,+ });+}++/**+ * Emit response.in_progress event+ */+export function emitResponseInProgress(config: StreamHandlerConfig): void {+ const { res, context, tracker } = config;+ const response = buildResponse(context, tracker, 'in_progress');+ writeEvent(res, {+ type: 'response.in_progress',+ sequence_number: tracker.nextSequence(),+ response,+ });+}++/**+ * Emit response.completed event+ */+export function emitResponseCompleted(config: StreamHandlerConfig): void {+ const { res, context, tracker } = config;+ tracker.status = 'completed';+ const response = buildResponse(context, tracker, 'completed');+ writeEvent(res, {+ type: 'response.completed',+ sequence_number: tracker.nextSequence(),+ response,+ });+}++/**+ * Emit response.failed event+ */+export function emitResponseFailed(+ config: StreamHandlerConfig,+ error: { type: string; message: string; code?: string },+): void {+ const { res, context, tracker } = config;+ tracker.status = 'failed';+ const response = buildResponse(context, tracker, 'failed');+ response.error = {+ type: error.type as+ | 'server_error'+ | 'invalid_request'+ | 'not_found'+ | 'model_error'+ | 'too_many_requests',+ message: error.message,+ code: error.code,+ };+ writeEvent(res, {+ type: 'response.failed',+ sequence_number: tracker.nextSequence(),+ response,+ });+}++/**+ * Emit response.output_item.added event for a message+ */+export function emitMessageItemAdded(config: StreamHandlerConfig): MessageItem {+ const { res, tracker } = config;+ const item = createMessageItem('in_progress');+ tracker.currentMessage = item;+ tracker.currentContentIndex = 0;+ tracker.accumulatedText = '';+ tracker.items.push(item);++ writeEvent(res, {+ type: 'response.output_item.added',+ sequence_number: tracker.nextSequence(),+ output_index: tracker.items.length - 1,+ item,+ });++ return item;+}++/**+ * Emit response.output_item.done event for a message+ */+export function emitMessageItemDone(config: StreamHandlerConfig): void {+ const { res, tracker } = config;+ if (!tracker.currentMessage) {+ return;+ }++ tracker.currentMessage.status = 'completed';+ const outputIndex = tracker.items.indexOf(tracker.currentMessage);++ writeEvent(res, {+ type: 'response.output_item.done',+ sequence_number: tracker.nextSequence(),+ output_index: outputIndex,+ item: tracker.currentMessage,+ });++ tracker.currentMessage = null;+}++/**+ * Emit response.content_part.added for text content+ */+export function emitTextContentPartAdded(config: StreamHandlerConfig): void {+ const { res, tracker } = config;+ if (!tracker.currentMessage) {+ return;+ }++ const part = createOutputTextContent('');+ tracker.currentMessage.content.push(part);+ const outputIndex = tracker.items.indexOf(tracker.currentMessage);++ writeEvent(res, {+ type: 'response.content_part.added',+ sequence_number: tracker.nextSequence(),+ item_id: tracker.currentMessage.id,+ output_index: outputIndex,+ content_index: tracker.currentContentIndex,+ part,+ });+}++/**+ * Emit response.output_text.delta event+ */+export function emitOutputTextDelta(config: StreamHandlerConfig, delta: string): void {+ const { res, tracker } = config;+ if (!tracker.currentMessage) {+ return;+ }++ tracker.accumulatedText += delta;+ const outputIndex = tracker.items.indexOf(tracker.currentMessage);++ writeEvent(res, {+ type: 'response.output_text.delta',+ sequence_number: tracker.nextSequence(),+ item_id: tracker.currentMessage.id,+ output_index: outputIndex,+ content_index: tracker.currentContentIndex,+ delta,+ logprobs: [],+ });+}++/**+ * Emit response.output_text.done event+ */+export function emitOutputTextDone(config: StreamHandlerConfig): void {+ const { res, tracker } = config;+ if (!tracker.currentMessage) {+ return;+ }++ const outputIndex = tracker.items.indexOf(tracker.currentMessage);+ const contentIndex = tracker.currentContentIndex;++ // Update the content part with final text+ if (tracker.currentMessage.content[contentIndex]) {+ (tracker.currentMessage.content[contentIndex] as OutputTextContent).text =+ tracker.accumulatedText;+ }++ writeEvent(res, {+ type: 'response.output_text.done',+ sequence_number: tracker.nextSequence(),+ item_id: tracker.currentMessage.id,+ output_index: outputIndex,+ content_index: contentIndex,+ text: tracker.accumulatedText,+ logprobs: [],+ });+}++/**+ * Emit response.content_part.done for text content+ */+export function emitTextContentPartDone(config: StreamHandlerConfig): void {+ const { res, tracker } = config;+ if (!tracker.currentMessage) {+ return;+ }++ const outputIndex = tracker.items.indexOf(tracker.currentMessage);+ const contentIndex = tracker.currentContentIndex;+ const part = tracker.currentMessage.content[contentIndex];++ if (part) {+ writeEvent(res, {+ type: 'response.content_part.done',+ sequence_number: tracker.nextSequence(),+ item_id: tracker.currentMessage.id,+ output_index: outputIndex,+ content_index: contentIndex,+ part,+ });+ }++ tracker.currentContentIndex++;+}++/* =============================================================================+ * FUNCTION CALL EVENT EMITTERS+ * ============================================================================= */++/**+ * Emit response.output_item.added for a function call+ */+export function emitFunctionCallItemAdded(+ config: StreamHandlerConfig,+ callId: string,+ name: string,+): FunctionCallItem {+ const { res, tracker } = config;+ const item = createFunctionCallItem(callId, name, 'in_progress');+ tracker.functionCalls.set(callId, item);+ tracker.accumulatedArguments.set(callId, '');+ tracker.items.push(item);++ writeEvent(res, {+ type: 'response.output_item.added',+ sequence_number: tracker.nextSequence(),+ output_index: tracker.items.length - 1,+ item,+ });++ return item;+}++/**+ * Emit response.function_call_arguments.delta event+ */+export function emitFunctionCallArgumentsDelta(+ config: StreamHandlerConfig,+ callId: string,+ delta: string,+): void {+ const { res, tracker } = config;+ const item = tracker.functionCalls.get(callId);+ if (!item) {+ return;+ }++ const accumulated = (tracker.accumulatedArguments.get(callId) ?? '') + delta;+ tracker.accumulatedArguments.set(callId, accumulated);+ item.arguments = accumulated;++ const outputIndex = tracker.items.indexOf(item);++ writeEvent(res, {+ type: 'response.function_call_arguments.delta',+ sequence_number: tracker.nextSequence(),+ item_id: item.id,+ output_index: outputIndex,+ call_id: callId,+ delta,+ });+}++/**+ * Emit response.function_call_arguments.done event+ */+export function emitFunctionCallArgumentsDone(config: StreamHandlerConfig, callId: string): void {+ const { res, tracker } = config;+ const item = tracker.functionCalls.get(callId);+ if (!item) {+ return;+ }++ const outputIndex = tracker.items.indexOf(item);+ const args = tracker.accumulatedArguments.get(callId) ?? '';++ writeEvent(res, {+ type: 'response.function_call_arguments.done',+ sequence_number: tracker.nextSequence(),+ item_id: item.id,+ output_index: outputIndex,+ call_id: callId,+ arguments: args,+ });+}++/**+ * Emit response.output_item.done for a function call+ */+export function emitFunctionCallItemDone(config: StreamHandlerConfig, callId: string): void {+ const { res, tracker } = config;+ const item = tracker.functionCalls.get(callId);+ if (!item) {+ return;+ }++ item.status = 'completed';+ const outputIndex = tracker.items.indexOf(item);++ writeEvent(res, {+ type: 'response.output_item.done',+ sequence_number: tracker.nextSequence(),+ output_index: outputIndex,+ item,+ });+}++/**+ * Emit function call output item (internal tool result)+ */+export function emitFunctionCallOutputItem(+ config: StreamHandlerConfig,+ callId: string,+ output: string,+): void {+ const { res, tracker } = config;+ const item = createFunctionCallOutputItem(callId, output, 'completed');+ tracker.functionCallOutputs.set(callId, item);+ tracker.items.push(item);++ // Emit added+ writeEvent(res, {+ type: 'response.output_item.added',+ sequence_number: tracker.nextSequence(),+ output_index: tracker.items.length - 1,+ item,+ });++ // Immediately emit done since it's already complete+ writeEvent(res, {+ type: 'response.output_item.done',+ sequence_number: tracker.nextSequence(),+ output_index: tracker.items.length - 1,+ item,+ });+}++/* =============================================================================+ * REASONING EVENT EMITTERS+ * ============================================================================= */++/**+ * Emit response.output_item.added for reasoning+ */+export function emitReasoningItemAdded(config: StreamHandlerConfig): ReasoningItem {+ const { res, tracker } = config;+ const item = createReasoningItem('in_progress');+ tracker.currentReasoning = item;+ tracker.currentReasoningContentIndex = 0;+ tracker.accumulatedReasoningText = '';+ tracker.items.push(item);++ writeEvent(res, {+ type: 'response.output_item.added',+ sequence_number: tracker.nextSequence(),+ output_index: tracker.items.length - 1,+ item,+ });++ return item;+}++/**+ * Emit response.content_part.added for reasoning+ */+export function emitReasoningContentPartAdded(config: StreamHandlerConfig): void {+ const { res, tracker } = config;+ if (!tracker.currentReasoning) {+ return;+ }++ const part = createReasoningTextContent('');+ if (!tracker.currentReasoning.content) {+ tracker.currentReasoning.content = [];+ }+ tracker.currentReasoning.content.push(part);+ const outputIndex = tracker.items.indexOf(tracker.currentReasoning);++ writeEvent(res, {+ type: 'response.content_part.added',+ sequence_number: tracker.nextSequence(),+ item_id: tracker.currentReasoning.id,+ output_index: outputIndex,+ content_index: tracker.currentReasoningContentIndex,+ part,+ });+}++/**+ * Emit response.reasoning.delta event+ */+export function emitReasoningDelta(config: StreamHandlerConfig, delta: string): void {+ const { res, tracker } = config;+ if (!tracker.currentReasoning) {+ return;+ }++ tracker.accumulatedReasoningText += delta;+ const outputIndex = tracker.items.indexOf(tracker.currentReasoning);++ writeEvent(res, {+ type: 'response.reasoning.delta',+ sequence_number: tracker.nextSequence(),+ item_id: tracker.currentReasoning.id,+ output_index: outputIndex,+ content_index: tracker.currentReasoningContentIndex,+ delta,+ });+}++/**+ * Emit response.reasoning.done event+ */+export function emitReasoningDone(config: StreamHandlerConfig): void {+ const { res, tracker } = config;+ if (!tracker.currentReasoning || !tracker.currentReasoning.content) {+ return;+ }++ const outputIndex = tracker.items.indexOf(tracker.currentReasoning);+ const contentIndex = tracker.currentReasoningContentIndex;++ // Update the content part with final text+ if (tracker.currentReasoning.content[contentIndex]) {+ (tracker.currentReasoning.content[contentIndex] as ReasoningTextContent).text =+ tracker.accumulatedReasoningText;+ }++ writeEvent(res, {+ type: 'response.reasoning.done',+ sequence_number: tracker.nextSequence(),+ item_id: tracker.currentReasoning.id,+ output_index: outputIndex,+ content_index: contentIndex,+ text: tracker.accumulatedReasoningText,+ });+}++/**+ * Emit response.content_part.done for reasoning+ */+export function emitReasoningContentPartDone(config: StreamHandlerConfig): void {+ const { res, tracker } = config;+ if (!tracker.currentReasoning || !tracker.currentReasoning.content) {+ return;+ }++ const outputIndex = tracker.items.indexOf(tracker.currentReasoning);+ const contentIndex = tracker.currentReasoningContentIndex;+ const part = tracker.currentReasoning.content[contentIndex];++ if (part) {+ writeEvent(res, {+ type: 'response.content_part.done',+ sequence_number: tracker.nextSequence(),+ item_id: tracker.currentReasoning.id,+ output_index: outputIndex,+ content_index: contentIndex,+ part,+ });+ }++ tracker.currentReasoningContentIndex++;+}++/**+ * Emit response.output_item.done for reasoning+ */+export function emitReasoningItemDone(config: StreamHandlerConfig): void {+ const { res, tracker } = config;+ if (!tracker.currentReasoning) {+ return;+ }++ tracker.currentReasoning.status = 'completed';+ const outputIndex = tracker.items.indexOf(tracker.currentReasoning);++ writeEvent(res, {+ type: 'response.output_item.done',+ sequence_number: tracker.nextSequence(),+ output_index: outputIndex,+ item: tracker.currentReasoning,+ });++ tracker.currentReasoning = null;+}++/* =============================================================================+ * ERROR HANDLING+ * ============================================================================= */++/**+ * Emit error event+ */+export function emitError(+ config: StreamHandlerConfig,+ error: { type: string; message: string; code?: string },+): void {+ const { res, tracker } = config;++ writeEvent(res, {+ type: 'error',+ sequence_number: tracker.nextSequence(),+ error: {+ type: error.type as 'server_error',+ message: error.message,+ code: error.code,+ },+ });+}++/* =============================================================================+ * LIBRECHAT EXTENSION EVENTS+ * Custom events prefixed with 'librechat:' per Open Responses spec+ * @see https://openresponses.org/specification#extending-streaming-events+ * ============================================================================= */++/**+ * Attachment data for librechat:attachment events+ */+export interface AttachmentData {+ /** File ID in LibreChat storage */+ file_id?: string;+ /** Original filename */+ filename?: string;+ /** MIME type */+ type?: string;+ /** URL to access the file */+ url?: string;+ /** Base64-encoded image data (for inline images) */+ image_url?: string;+ /** Width for images */+ width?: number;+ /** Height for images */+ height?: number;+ /** Associated tool call ID */+ tool_call_id?: string;+ /** Additional metadata */+ [key: string]: unknown;+}++/**+ * Emit librechat:attachment event for file/image attachments+ * This is a LibreChat extension to the Open Responses streaming protocol.+ * External clients can safely ignore these events.+ */+export function emitAttachment(+ config: StreamHandlerConfig,+ attachment: AttachmentData,+ options?: {+ messageId?: string;+ conversationId?: string;+ },+): void {+ const { res, tracker } = config;++ writeEvent(res, {+ type: 'librechat:attachment',+ sequence_number: tracker.nextSequence(),+ attachment,+ message_id: options?.messageId,+ conversation_id: options?.conversationId,+ });+}++/**+ * Write attachment event directly to response (for use outside streaming context)+ * Useful when attachment processing happens asynchronously+ */+export function writeAttachmentEvent(+ res: ServerResponse,+ sequenceNumber: number,+ attachment: AttachmentData,+ options?: {+ messageId?: string;+ conversationId?: string;+ },+): void {+ writeEvent(res, {+ type: 'librechat:attachment',+ sequence_number: sequenceNumber,+ attachment,+ message_id: options?.messageId,+ conversation_id: options?.conversationId,+ });+}++/* =============================================================================+ * NON-STREAMING RESPONSE BUILDER+ * ============================================================================= */++/**+ * Build a complete non-streaming response+ */+export function buildResponsesNonStreamingResponse(+ context: ResponseContext,+ tracker: ResponseTracker,+): Response {+ return buildResponse(context, tracker, 'completed');+}++/**+ * Update tracker usage from collected data+ */+export function updateTrackerUsage(+ tracker: ResponseTracker,+ usage: {+ promptTokens?: number;+ completionTokens?: number;+ reasoningTokens?: number;+ cachedTokens?: number;+ },+): void {+ if (usage.promptTokens != null) {+ tracker.usage.inputTokens = usage.promptTokens;+ }+ if (usage.completionTokens != null) {+ tracker.usage.outputTokens = usage.completionTokens;+ }+ if (usage.reasoningTokens != null) {+ tracker.usage.reasoningTokens = usage.reasoningTokens;+ }+ if (usage.cachedTokens != null) {+ tracker.usage.cachedTokens = usage.cachedTokens;+ }+}diff --git a/packages/api/src/agents/responses/index.ts b/packages/api/src/agents/responses/index.tsnew file mode 100644index 0000000000..ecfb1c2047--- /dev/null+++ b/packages/api/src/agents/responses/index.ts@@ -0,0 +1,183 @@+/**+ * Open Responses API Module+ *+ * Exports for the Open Responses API implementation.+ * @see https://openresponses.org/specification+ */++// Types+export type {+ // Enums+ ItemStatus,+ ResponseStatus,+ MessageRole,+ ToolChoiceValue,+ TruncationValue,+ ServiceTier,+ ReasoningEffort,+ ReasoningSummary,+ // Input content+ InputTextContent,+ InputImageContent,+ InputFileContent,+ InputContent,+ // Output content+ LogProb,+ TopLogProb,+ OutputTextContent,+ RefusalContent,+ ModelContent,+ // Annotations+ UrlCitationAnnotation,+ FileCitationAnnotation,+ Annotation,+ // Reasoning content+ ReasoningTextContent,+ SummaryTextContent,+ ReasoningContent,+ // Input items+ SystemMessageItemParam,+ DeveloperMessageItemParam,+ UserMessageItemParam,+ AssistantMessageItemParam,+ FunctionCallItemParam,+ FunctionCallOutputItemParam,+ ReasoningItemParam,+ ItemReferenceParam,+ InputItem,+ // Output items+ MessageItem,+ FunctionCallItem,+ FunctionCallOutputItem,+ ReasoningItem,+ OutputItem,+ // Tools+ FunctionTool,+ HostedTool,+ Tool,+ FunctionToolChoice,+ ToolChoice,+ // Request+ ReasoningConfig,+ TextConfig,+ StreamOptions,+ Metadata,+ ResponseRequest,+ // Response field types+ TextField,+ // Response+ InputTokensDetails,+ OutputTokensDetails,+ Usage,+ IncompleteDetails,+ ResponseError,+ Response,+ // Streaming events+ BaseEvent,+ ResponseCreatedEvent,+ ResponseInProgressEvent,+ ResponseCompletedEvent,+ ResponseFailedEvent,+ ResponseIncompleteEvent,+ OutputItemAddedEvent,+ OutputItemDoneEvent,+ ContentPartAddedEvent,+ ContentPartDoneEvent,+ OutputTextDeltaEvent,+ OutputTextDoneEvent,+ RefusalDeltaEvent,+ RefusalDoneEvent,+ FunctionCallArgumentsDeltaEvent,+ FunctionCallArgumentsDoneEvent,+ ReasoningDeltaEvent,+ ReasoningDoneEvent,+ ErrorEvent,+ ResponseEvent,+ // LibreChat extensions+ LibreChatAttachmentContent,+ LibreChatAttachmentEvent,+ // Internal+ ResponseContext,+ RequestValidationResult,+} from './types';++// Handlers+export {+ // Tracker+ createResponseTracker,+ type ResponseTracker,+ // SSE+ writeEvent,+ writeDone,+ // Response building+ buildResponse,+ // Item builders+ generateItemId,+ createMessageItem,+ createFunctionCallItem,+ createFunctionCallOutputItem,+ createReasoningItem,+ createOutputTextContent,+ createReasoningTextContent,+ // Stream config+ type StreamHandlerConfig,+ // Response events+ emitResponseCreated,+ emitResponseInProgress,+ emitResponseCompleted,+ emitResponseFailed,+ // Message events+ emitMessageItemAdded,+ emitMessageItemDone,+ emitTextContentPartAdded,+ emitOutputTextDelta,+ emitOutputTextDone,+ emitTextContentPartDone,+ // Function call events+ emitFunctionCallItemAdded,+ emitFunctionCallArgumentsDelta,+ emitFunctionCallArgumentsDone,+ emitFunctionCallItemDone,+ emitFunctionCallOutputItem,+ // Reasoning events+ emitReasoningItemAdded,+ emitReasoningContentPartAdded,+ emitReasoningDelta,+ emitReasoningDone,+ emitReasoningContentPartDone,+ emitReasoningItemDone,+ // Error events+ emitError,+ // LibreChat extension events+ emitAttachment,+ writeAttachmentEvent,+ type AttachmentData,+ // Non-streaming+ buildResponsesNonStreamingResponse,+ updateTrackerUsage,+} from './handlers';++// Service+export {+ // Validation+ validateResponseRequest,+ isValidationFailure,+ // Input conversion+ convertInputToMessages,+ mergeMessagesWithInput,+ type InternalMessage,+ // Error response+ sendResponsesErrorResponse,+ // Context+ generateResponseId,+ createResponseContext,+ // Streaming setup+ setupStreamingResponse,+ // Event handlers+ createResponsesEventHandlers,+ // Non-streaming+ createResponseAggregator,+ buildAggregatedResponse,+ createAggregatorEventHandlers,+ type ResponseAggregator,+} from './service';diff --git a/packages/api/src/agents/responses/service.ts b/packages/api/src/agents/responses/service.tsnew file mode 100644index 0000000000..842db86679--- /dev/null+++ b/packages/api/src/agents/responses/service.ts@@ -0,0 +1,869 @@+/**+ * Open Responses API Service+ *+ * Core service for processing Open Responses API requests.+ * Handles input conversion, message formatting, and request validation.+ */+import type { Response as ServerResponse } from 'express';+import type {+ ResponseRequest,+ RequestValidationResult,+ InputItem,+ InputContent,+ ResponseContext,+ Response,+} from './types';+import {+ writeDone,+ emitResponseCompleted,+ emitMessageItemAdded,+ emitMessageItemDone,+ emitTextContentPartAdded,+ emitOutputTextDelta,+ emitOutputTextDone,+ emitTextContentPartDone,+ emitFunctionCallItemAdded,+ emitFunctionCallArgumentsDelta,+ emitFunctionCallArgumentsDone,+ emitFunctionCallItemDone,+ emitFunctionCallOutputItem,+ emitReasoningItemAdded,+ emitReasoningContentPartAdded,+ emitReasoningDelta,+ emitReasoningDone,+ emitReasoningContentPartDone,+ emitReasoningItemDone,+ updateTrackerUsage,+ type StreamHandlerConfig,+} from './handlers';++/* =============================================================================+ * REQUEST VALIDATION+ * ============================================================================= */++/**+ * Validate a request body+ */+export function validateResponseRequest(body: unknown): RequestValidationResult {+ if (!body || typeof body !== 'object') {+ return { valid: false, error: 'Request body is required' };+ }++ const request = body as Record<string, unknown>;++ // Required: model+ if (!request.model || typeof request.model !== 'string') {+ return { valid: false, error: 'model is required and must be a string' };+ }++ // Required: input (string or array)+ if (request.input === undefined || request.input === null) {+ return { valid: false, error: 'input is required' };+ }++ if (typeof request.input !== 'string' && !Array.isArray(request.input)) {+ return { valid: false, error: 'input must be a string or array of items' };+ }++ // Optional validations+ if (request.stream !== undefined && typeof request.stream !== 'boolean') {+ return { valid: false, error: 'stream must be a boolean' };+ }++ if (request.temperature !== undefined) {+ const temp = request.temperature as number;+ if (typeof temp !== 'number' || temp < 0 || temp > 2) {+ return { valid: false, error: 'temperature must be a number between 0 and 2' };+ }+ }++ if (request.max_output_tokens !== undefined) {+ if (typeof request.max_output_tokens !== 'number' || request.max_output_tokens < 1) {+ return { valid: false, error: 'max_output_tokens must be a positive number' };+ }+ }++ return { valid: true, request: request as unknown as ResponseRequest };+}++/**+ * Check if validation failed+ */+export function isValidationFailure(+ result: RequestValidationResult,+): result is { valid: false; error: string } {+ return !result.valid;+}++/* =============================================================================+ * INPUT CONVERSION+ * ============================================================================= */++/** Internal message format (LibreChat-compatible) */+export interface InternalMessage {+ role: 'system' | 'user' | 'assistant' | 'tool';+ content: string | Array<{ type: string; text?: string; image_url?: unknown }>;+ name?: string;+ tool_call_id?: string;+ tool_calls?: Array<{+ id: string;+ type: 'function';+ function: { name: string; arguments: string };+ }>;+}++/**+ * Convert Open Responses input to internal message format.+ * Handles both string input and array of items.+ */+export function convertInputToMessages(input: string | InputItem[]): InternalMessage[] {+ // Simple string input becomes a user message+ if (typeof input === 'string') {+ return [{ role: 'user', content: input }];+ }++ const messages: InternalMessage[] = [];++ for (const item of input) {+ if (item.type === 'item_reference') {+ // Skip item references - they're handled by previous_response_id+ continue;+ }++ if (item.type === 'message') {+ const messageItem = item as {+ type: 'message';+ role: string;+ content: string | InputContent[];+ };++ let content: InternalMessage['content'];++ if (typeof messageItem.content === 'string') {+ content = messageItem.content;+ } else if (Array.isArray(messageItem.content)) {+ content = messageItem.content.map((part) => {+ if (part.type === 'input_text') {+ return { type: 'text', text: part.text };+ }+ if (part.type === 'input_image') {+ return {+ type: 'image_url',+ image_url: {+ url: (part as { image_url?: string }).image_url,+ detail: (part as { detail?: string }).detail,+ },+ };+ }+ return { type: part.type };+ });+ } else {+ content = '';+ }++ // Map developer role to system (LibreChat convention)+ let role: InternalMessage['role'];+ if (messageItem.role === 'developer') {+ role = 'system';+ } else if (messageItem.role === 'user') {+ role = 'user';+ } else if (messageItem.role === 'assistant') {+ role = 'assistant';+ } else if (messageItem.role === 'system') {+ role = 'system';+ } else {+ role = 'user';+ }++ messages.push({ role, content });+ }++ if (item.type === 'function_call') {+ // Function call items represent prior tool calls from assistant+ const fcItem = item as {+ type: 'function_call';+ call_id: string;+ name: string;+ arguments: string;+ };++ // Add as assistant message with tool_calls+ messages.push({+ role: 'assistant',+ content: '',+ tool_calls: [+ {+ id: fcItem.call_id,+ type: 'function',+ function: { name: fcItem.name, arguments: fcItem.arguments },+ },+ ],+ });+ }++ if (item.type === 'function_call_output') {+ // Function call output items represent tool results+ const fcoItem = item as { type: 'function_call_output'; call_id: string; output: string };++ messages.push({+ role: 'tool',+ content: fcoItem.output,+ tool_call_id: fcoItem.call_id,+ });+ }++ // Reasoning items are typically not passed back as input+ // They're model-generated and may be encrypted+ }++ return messages;+}++/**+ * Merge previous conversation messages with new input+ */+export function mergeMessagesWithInput(+ previousMessages: InternalMessage[],+ newInput: InternalMessage[],+): InternalMessage[] {+ return [...previousMessages, ...newInput];+}++/* =============================================================================+ * ERROR RESPONSE+ * ============================================================================= */++/**+ * Send an error response in Open Responses format+ */+export function sendResponsesErrorResponse(+ res: ServerResponse,+ statusCode: number,+ message: string,+ type: string = 'invalid_request',+ code?: string,+): void {+ res.status(statusCode).json({+ error: {+ type,+ message,+ code: code ?? null,+ param: null,+ },+ });+}++/* =============================================================================+ * RESPONSE CONTEXT+ * ============================================================================= */++/**+ * Generate a unique response ID+ */+export function generateResponseId(): string {+ return `resp_${Date.now().toString(36)}${Math.random().toString(36).substring(2, 8)}`;+}++/**+ * Create a response context from request+ */+export function createResponseContext(+ request: ResponseRequest,+ responseId?: string,+): ResponseContext {+ return {+ responseId: responseId ?? generateResponseId(),+ model: request.model,+ createdAt: Math.floor(Date.now() / 1000),+ previousResponseId: request.previous_response_id,+ instructions: request.instructions,+ };+}++/* =============================================================================+ * STREAMING SETUP+ * ============================================================================= */++/**+ * Set up streaming response headers+ */+export function setupStreamingResponse(res: ServerResponse): void {+ res.setHeader('Content-Type', 'text/event-stream');+ res.setHeader('Cache-Control', 'no-cache');+ res.setHeader('Connection', 'keep-alive');+ res.setHeader('X-Accel-Buffering', 'no');+ res.flushHeaders();+}++/* =============================================================================+ * STREAM HANDLER FACTORY+ * ============================================================================= */++/**+ * State for tracking streaming progress+ */+interface StreamState {+ messageStarted: boolean;+ messageContentStarted: boolean;+ reasoningStarted: boolean;+ reasoningContentStarted: boolean;+ activeToolCalls: Set<string>;+ completedToolCalls: Set<string>;+}++/**+ * Create LibreChat event handlers that emit Open Responses events+ */+export function createResponsesEventHandlers(config: StreamHandlerConfig): {+ handlers: Record<string, { handle: (event: string, data: unknown) => void }>;+ state: StreamState;+ finalizeStream: () => void;+} {+ const state: StreamState = {+ messageStarted: false,+ messageContentStarted: false,+ reasoningStarted: false,+ reasoningContentStarted: false,+ activeToolCalls: new Set(),+ completedToolCalls: new Set(),+ };++ /**+ * Ensure message item is started+ */+ const ensureMessageStarted = (): void => {+ if (!state.messageStarted) {+ emitMessageItemAdded(config);+ state.messageStarted = true;+ }+ };++ /**+ * Ensure message content part is started+ */+ const ensureMessageContentStarted = (): void => {+ ensureMessageStarted();+ if (!state.messageContentStarted) {+ emitTextContentPartAdded(config);+ state.messageContentStarted = true;+ }+ };++ /**+ * Ensure reasoning item is started+ */+ const ensureReasoningStarted = (): void => {+ if (!state.reasoningStarted) {+ emitReasoningItemAdded(config);+ state.reasoningStarted = true;+ }+ };++ /**+ * Ensure reasoning content part is started+ */+ const ensureReasoningContentStarted = (): void => {+ ensureReasoningStarted();+ if (!state.reasoningContentStarted) {+ emitReasoningContentPartAdded(config);+ state.reasoningContentStarted = true;+ }+ };++ /**+ * Close any open content streams+ */+ const closeOpenStreams = (): void => {+ // Close message content if open+ if (state.messageContentStarted) {+ emitOutputTextDone(config);+ emitTextContentPartDone(config);+ state.messageContentStarted = false;+ }++ // Close message item if open+ if (state.messageStarted) {+ emitMessageItemDone(config);+ state.messageStarted = false;+ }++ // Close reasoning content if open+ if (state.reasoningContentStarted) {+ emitReasoningDone(config);+ emitReasoningContentPartDone(config);+ state.reasoningContentStarted = false;+ }++ // Close reasoning item if open+ if (state.reasoningStarted) {+ emitReasoningItemDone(config);+ state.reasoningStarted = false;+ }+ };++ const handlers = {+ /**+ * Handle text message deltas+ */+ on_message_delta: {+ handle: (_event: string, data: unknown): void => {+ const deltaData = data as { delta?: { content?: Array<{ type: string; text?: string }> } };+ const content = deltaData?.delta?.content;++ if (Array.isArray(content)) {+ for (const part of content) {+ if (part.type === 'text' && part.text) {+ ensureMessageContentStarted();+ emitOutputTextDelta(config, part.text);+ }+ }+ }+ },+ },++ /**+ * Handle reasoning deltas+ */+ on_reasoning_delta: {+ handle: (_event: string, data: unknown): void => {+ const deltaData = data as {+ delta?: { content?: Array<{ type: string; text?: string; think?: string }> };+ };+ const content = deltaData?.delta?.content;++ if (Array.isArray(content)) {+ for (const part of content) {+ const text = part.think || part.text;+ if (text) {+ ensureReasoningContentStarted();+ emitReasoningDelta(config, text);+ }+ }+ }+ },+ },++ /**+ * Handle run step (tool call initiation)+ */+ on_run_step: {+ handle: (_event: string, data: unknown): void => {+ const stepData = data as {+ stepDetails?: { type: string; tool_calls?: Array<{ id?: string; name?: string }> };+ };+ const stepDetails = stepData?.stepDetails;++ if (stepDetails?.type === 'tool_calls' && stepDetails.tool_calls) {+ // Close any open message/reasoning before tool calls+ closeOpenStreams();++ for (const tc of stepDetails.tool_calls) {+ const callId = tc.id ?? '';+ const name = tc.name ?? '';++ if (callId && !state.activeToolCalls.has(callId)) {+ state.activeToolCalls.add(callId);+ emitFunctionCallItemAdded(config, callId, name);+ }+ }+ }+ },+ },++ /**+ * Handle run step delta (tool call argument streaming)+ */+ on_run_step_delta: {+ handle: (_event: string, data: unknown): void => {+ const deltaData = data as {+ delta?: { type: string; tool_calls?: Array<{ index?: number; args?: string }> };+ };+ const delta = deltaData?.delta;++ if (delta?.type === 'tool_calls' && delta.tool_calls) {+ for (const tc of delta.tool_calls) {+ const args = tc.args ?? '';+ if (!args) {+ continue;+ }++ // Find the call_id for this tool call by index+ const toolCallsArray = Array.from(state.activeToolCalls);+ const callId = toolCallsArray[tc.index ?? 0];++ if (callId) {+ emitFunctionCallArgumentsDelta(config, callId, args);+ }+ }+ }+ },+ },++ /**+ * Handle tool end (tool execution complete)+ */+ on_tool_end: {+ handle: (_event: string, data: unknown): void => {+ const toolData = data as { tool_call_id?: string; output?: string };+ const callId = toolData?.tool_call_id;+ const output = toolData?.output ?? '';++ if (callId && state.activeToolCalls.has(callId) && !state.completedToolCalls.has(callId)) {+ state.completedToolCalls.add(callId);++ // Complete the function call item+ emitFunctionCallArgumentsDone(config, callId);+ emitFunctionCallItemDone(config, callId);++ // Emit the function call output (internal tool result)+ emitFunctionCallOutputItem(config, callId, output);+ }+ },+ },++ /**+ * Handle chat model end (usage collection)+ */+ on_chat_model_end: {+ handle: (_event: string, data: unknown): void => {+ const endData = data as {+ output?: {+ usage_metadata?: {+ input_tokens?: number;+ output_tokens?: number;+ // OpenAI format+ input_token_details?: {+ cache_creation?: number;+ cache_read?: number;+ };+ // Anthropic format+ cache_creation_input_tokens?: number;+ cache_read_input_tokens?: number;+ };+ };+ };++ const usage = endData?.output?.usage_metadata;+ if (usage) {+ // Extract cached tokens from either OpenAI or Anthropic format+ const cachedTokens =+ (usage.input_token_details?.cache_read ?? 0) + (usage.cache_read_input_tokens ?? 0);++ updateTrackerUsage(config.tracker, {+ promptTokens: usage.input_tokens,+ completionTokens: usage.output_tokens,+ cachedTokens,+ });+ }+ },+ },+ };++ /**+ * Finalize the stream - close open items and emit completed+ */+ const finalizeStream = (): void => {+ closeOpenStreams();+ emitResponseCompleted(config);+ writeDone(config.res);+ };++ return { handlers, state, finalizeStream };+}++/* =============================================================================+ * NON-STREAMING AGGREGATOR+ * ============================================================================= */++/**+ * Aggregator for non-streaming responses+ */+export interface ResponseAggregator {+ textChunks: string[];+ reasoningChunks: string[];+ toolCalls: Map<+ string,+ {+ id: string;+ name: string;+ arguments: string;+ }+ >;+ toolOutputs: Map<string, string>;+ usage: {+ inputTokens: number;+ outputTokens: number;+ reasoningTokens: number;+ cachedTokens: number;+ };+ addText: (text: string) => void;+ addReasoning: (text: string) => void;+ getText: () => string;+ getReasoning: () => string;+}++/**+ * Create an aggregator for non-streaming responses+ */+export function createResponseAggregator(): ResponseAggregator {+ const aggregator: ResponseAggregator = {+ textChunks: [],+ reasoningChunks: [],+ toolCalls: new Map(),+ toolOutputs: new Map(),+ usage: {+ inputTokens: 0,+ outputTokens: 0,+ reasoningTokens: 0,+ cachedTokens: 0,+ },+ addText: (text: string) => {+ aggregator.textChunks.push(text);+ },+ addReasoning: (text: string) => {+ aggregator.reasoningChunks.push(text);+ },+ getText: () => aggregator.textChunks.join(''),+ getReasoning: () => aggregator.reasoningChunks.join(''),+ };+ return aggregator;+}++/**+ * Build a non-streaming response from aggregator+ * Includes all required fields per Open Responses spec+ */+export function buildAggregatedResponse(+ context: ResponseContext,+ aggregator: ResponseAggregator,+): Response {+ const output: Response['output'] = [];++ // Add reasoning item if present+ const reasoningText = aggregator.getReasoning();+ if (reasoningText) {+ output.push({+ type: 'reasoning',+ id: `reason_${Date.now().toString(36)}`,+ status: 'completed',+ content: [{ type: 'reasoning_text', text: reasoningText }],+ summary: [],+ });+ }++ // Add function calls and outputs+ for (const [callId, tc] of aggregator.toolCalls) {+ output.push({+ type: 'function_call',+ id: `fc_${Date.now().toString(36)}${Math.random().toString(36).substring(2, 6)}`,+ call_id: callId,+ name: tc.name,+ arguments: tc.arguments,+ status: 'completed',+ });++ const toolOutput = aggregator.toolOutputs.get(callId);+ if (toolOutput) {+ output.push({+ type: 'function_call_output',+ id: `fco_${Date.now().toString(36)}${Math.random().toString(36).substring(2, 6)}`,+ call_id: callId,+ output: toolOutput,+ status: 'completed',+ });+ }+ }++ // Add message item if there's text (or always add one if no other output)+ const text = aggregator.getText();+ if (text || output.length === 0) {+ output.push({+ type: 'message',+ id: `msg_${Date.now().toString(36)}`,+ role: 'assistant',+ status: 'completed',+ content: text ? [{ type: 'output_text', text, annotations: [], logprobs: [] }] : [],+ });+ }++ return {+ // Required fields per Open Responses spec+ id: context.responseId,+ object: 'response',+ created_at: context.createdAt,+ completed_at: Math.floor(Date.now() / 1000),+ status: 'completed',+ incomplete_details: null,+ model: context.model,+ previous_response_id: context.previousResponseId ?? null,+ instructions: context.instructions ?? null,+ output,+ error: null,+ tools: [],+ tool_choice: 'auto',+ truncation: 'disabled',+ parallel_tool_calls: true,+ text: { format: { type: 'text' } },+ temperature: 1,+ top_p: 1,+ presence_penalty: 0,+ frequency_penalty: 0,+ top_logprobs: 0,+ reasoning: null,+ user: null,+ usage: {+ input_tokens: aggregator.usage.inputTokens,+ output_tokens: aggregator.usage.outputTokens,+ total_tokens: aggregator.usage.inputTokens + aggregator.usage.outputTokens,+ input_tokens_details: { cached_tokens: aggregator.usage.cachedTokens },+ output_tokens_details: { reasoning_tokens: aggregator.usage.reasoningTokens },+ },+ max_output_tokens: null,+ max_tool_calls: null,+ store: false,+ background: false,+ service_tier: 'default',+ metadata: {},+ safety_identifier: null,+ prompt_cache_key: null,+ };+}++/**+ * Create event handlers for non-streaming aggregation+ */+export function createAggregatorEventHandlers(aggregator: ResponseAggregator): Record<+ string,+ {+ handle: (event: string, data: unknown) => void;+ }+> {+ const activeToolCalls = new Set<string>();++ return {+ on_message_delta: {+ handle: (_event: string, data: unknown): void => {+ const deltaData = data as { delta?: { content?: Array<{ type: string; text?: string }> } };+ const content = deltaData?.delta?.content;++ if (Array.isArray(content)) {+ for (const part of content) {+ if (part.type === 'text' && part.text) {+ aggregator.addText(part.text);+ }+ }+ }+ },+ },++ on_reasoning_delta: {+ handle: (_event: string, data: unknown): void => {+ const deltaData = data as {+ delta?: { content?: Array<{ type: string; text?: string; think?: string }> };+ };+ const content = deltaData?.delta?.content;++ if (Array.isArray(content)) {+ for (const part of content) {+ const text = part.think || part.text;+ if (text) {+ aggregator.addReasoning(text);+ }+ }+ }+ },+ },++ on_run_step: {+ handle: (_event: string, data: unknown): void => {+ const stepData = data as {+ stepDetails?: { type: string; tool_calls?: Array<{ id?: string; name?: string }> };+ };+ const stepDetails = stepData?.stepDetails;++ if (stepDetails?.type === 'tool_calls' && stepDetails.tool_calls) {+ for (const tc of stepDetails.tool_calls) {+ const callId = tc.id ?? '';+ const name = tc.name ?? '';++ if (callId && !activeToolCalls.has(callId)) {+ activeToolCalls.add(callId);+ aggregator.toolCalls.set(callId, { id: callId, name, arguments: '' });+ }+ }+ }+ },+ },++ on_run_step_delta: {+ handle: (_event: string, data: unknown): void => {+ const deltaData = data as {+ delta?: { type: string; tool_calls?: Array<{ index?: number; args?: string }> };+ };+ const delta = deltaData?.delta;++ if (delta?.type === 'tool_calls' && delta.tool_calls) {+ for (const tc of delta.tool_calls) {+ const args = tc.args ?? '';+ if (!args) {+ continue;+ }++ const toolCallsArray = Array.from(activeToolCalls);+ const callId = toolCallsArray[tc.index ?? 0];++ if (callId) {+ const existing = aggregator.toolCalls.get(callId);+ if (existing) {+ existing.arguments += args;+ }+ }+ }+ }+ },+ },++ on_tool_end: {+ handle: (_event: string, data: unknown): void => {+ const toolData = data as { tool_call_id?: string; output?: string };+ const callId = toolData?.tool_call_id;+ const output = toolData?.output ?? '';++ if (callId) {+ aggregator.toolOutputs.set(callId, output);+ }+ },+ },++ on_chat_model_end: {+ handle: (_event: string, data: unknown): void => {+ const endData = data as {+ output?: {+ usage_metadata?: {+ input_tokens?: number;+ output_tokens?: number;+ // OpenAI format+ input_token_details?: {+ cache_creation?: number;+ cache_read?: number;+ };+ // Anthropic format+ cache_creation_input_tokens?: number;+ cache_read_input_tokens?: number;+ };+ };+ };++ const usage = endData?.output?.usage_metadata;+ if (usage) {+ aggregator.usage.inputTokens = usage.input_tokens ?? 0;+ aggregator.usage.outputTokens = usage.output_tokens ?? 0;++ // Extract cached tokens from either OpenAI or Anthropic format+ aggregator.usage.cachedTokens =+ (usage.input_token_details?.cache_read ?? 0) + (usage.cache_read_input_tokens ?? 0);+ }+ },+ },+ };+}diff --git a/packages/api/src/agents/responses/types.ts b/packages/api/src/agents/responses/types.tsnew file mode 100644index 0000000000..65e5887ab8--- /dev/null+++ b/packages/api/src/agents/responses/types.ts@@ -0,0 +1,779 @@+/**+ * Open Responses API Types+ *+ * Types following the Open Responses specification for building multi-provider,+ * interoperable LLM interfaces. Items are the fundamental unit of context,+ * and streaming uses semantic events rather than simple deltas.+ *+ * @see https://openresponses.org/specification+ */++/* =============================================================================+ * ENUMS+ * ============================================================================= */++/** Item status lifecycle */+export type ItemStatus = 'in_progress' | 'incomplete' | 'completed';++/** Response status lifecycle */+export type ResponseStatus = 'in_progress' | 'completed' | 'failed' | 'incomplete';++/** Message roles */+export type MessageRole = 'user' | 'assistant' | 'system' | 'developer';++/** Tool choice options */+export type ToolChoiceValue = 'none' | 'auto' | 'required';++/** Truncation options */+export type TruncationValue = 'auto' | 'disabled';++/** Service tier options */+export type ServiceTier = 'auto' | 'default' | 'flex' | 'priority';++/** Reasoning effort levels */+export type ReasoningEffort = 'none' | 'low' | 'medium' | 'high' | 'xhigh';++/** Reasoning summary options */+export type ReasoningSummary = 'concise' | 'detailed' | 'auto';++/* =============================================================================+ * INPUT CONTENT TYPES+ * ============================================================================= */++/** Text input content */+export interface InputTextContent {+ type: 'input_text';+ text: string;+}++/** Image input content */+export interface InputImageContent {+ type: 'input_image';+ image_url?: string;+ file_id?: string;+ detail?: 'auto' | 'low' | 'high';+}++/** File input content */+export interface InputFileContent {+ type: 'input_file';+ file_id?: string;+ file_data?: string;+ filename?: string;+}++/** Union of all input content types */+export type InputContent = InputTextContent | InputImageContent | InputFileContent;++/* =============================================================================+ * OUTPUT CONTENT TYPES+ * ============================================================================= */++/** Log probability for a token */+export interface LogProb {+ token: string;+ logprob: number;+ bytes?: number[];+ top_logprobs?: TopLogProb[];+}++/** Top log probability entry */+export interface TopLogProb {+ token: string;+ logprob: number;+ bytes?: number[];+}++/** Text output content */+export interface OutputTextContent {+ type: 'output_text';+ text: string;+ annotations: Annotation[];+ logprobs: LogProb[];+}++/** Refusal content */+export interface RefusalContent {+ type: 'refusal';+ refusal: string;+}++/** Union of model output content types */+export type ModelContent = OutputTextContent | RefusalContent;++/* =============================================================================+ * ANNOTATIONS+ * ============================================================================= */++/** URL citation annotation */+export interface UrlCitationAnnotation {+ type: 'url_citation';+ url: string;+ title?: string;+ start_index: number;+ end_index: number;+}++/** File citation annotation */+export interface FileCitationAnnotation {+ type: 'file_citation';+ file_id: string;+ start_index: number;+ end_index: number;+}++/** Union of annotation types */+export type Annotation = UrlCitationAnnotation | FileCitationAnnotation;++/* =============================================================================+ * REASONING CONTENT+ * ============================================================================= */++/** Reasoning text content */+export interface ReasoningTextContent {+ type: 'reasoning_text';+ text: string;+}++/** Summary text content */+export interface SummaryTextContent {+ type: 'summary_text';+ text: string;+}++/** Reasoning content union */+export type ReasoningContent = ReasoningTextContent;++/* =============================================================================+ * INPUT ITEMS (for request)+ * ============================================================================= */++/** System message input item */+export interface SystemMessageItemParam {+ type: 'message';+ role: 'system';+ content: string | InputContent[];+}++/** Developer message input item */+export interface DeveloperMessageItemParam {+ type: 'message';+ role: 'developer';+ content: string | InputContent[];+}++/** User message input item */+export interface UserMessageItemParam {+ type: 'message';+ role: 'user';+ content: string | InputContent[];+}++/** Assistant message input item */+export interface AssistantMessageItemParam {+ type: 'message';+ role: 'assistant';+ content: string | ModelContent[];+}++/** Function call input item (for providing context) */+export interface FunctionCallItemParam {+ type: 'function_call';+ id: string;+ call_id: string;+ name: string;+ arguments: string;+ status?: ItemStatus;+}++/** Function call output input item (for providing tool results) */+export interface FunctionCallOutputItemParam {+ type: 'function_call_output';+ call_id: string;+ output: string;+ status?: ItemStatus;+}++/** Reasoning input item */+export interface ReasoningItemParam {+ type: 'reasoning';+ id?: string;+ content?: ReasoningContent[];+ encrypted_content?: string;+ summary?: SummaryTextContent[];+ status?: ItemStatus;+}++/** Item reference (for referencing existing items) */+export interface ItemReferenceParam {+ type: 'item_reference';+ id: string;+}++/** Union of all input item types */+export type InputItem =+ | SystemMessageItemParam+ | DeveloperMessageItemParam+ | UserMessageItemParam+ | AssistantMessageItemParam+ | FunctionCallItemParam+ | FunctionCallOutputItemParam+ | ReasoningItemParam+ | ItemReferenceParam;++/* =============================================================================+ * OUTPUT ITEMS (in response)+ * ============================================================================= */++/** Message output item */+export interface MessageItem {+ type: 'message';+ id: string;+ role: 'assistant';+ status: ItemStatus;+ content: ModelContent[];+}++/** Function call output item */+export interface FunctionCallItem {+ type: 'function_call';+ id: string;+ call_id: string;+ name: string;+ arguments: string;+ status: ItemStatus;+}++/** Function call output result item (internal tool execution result) */+export interface FunctionCallOutputItem {+ type: 'function_call_output';+ id: string;+ call_id: string;+ output: string;+ status: ItemStatus;+}++/** Reasoning output item */+export interface ReasoningItem {+ type: 'reasoning';+ id: string;+ status?: ItemStatus;+ content?: ReasoningContent[];+ encrypted_content?: string;+ /** Required per Open Responses spec - summary content parts */+ summary: SummaryTextContent[];+}++/** Union of all output item types */+export type OutputItem = MessageItem | FunctionCallItem | FunctionCallOutputItem | ReasoningItem;++/* =============================================================================+ * TOOLS+ * ============================================================================= */++/** Function tool definition */+export interface FunctionTool {+ type: 'function';+ name: string;+ description?: string;+ parameters?: Record<string, unknown>;+ strict?: boolean;+}++/** Hosted tool (provider-specific) */+export interface HostedTool {+ type: string; // e.g., 'librechat:web_search'+ [key: string]: unknown;+}++/** Union of tool types */+export type Tool = FunctionTool | HostedTool;++/** Specific function tool choice */+export interface FunctionToolChoice {+ type: 'function';+ name: string;+}++/** Tool choice parameter */+export type ToolChoice = ToolChoiceValue | FunctionToolChoice;++/* =============================================================================+ * REQUEST+ * ============================================================================= */++/** Reasoning configuration */+export interface ReasoningConfig {+ effort?: ReasoningEffort;+ summary?: ReasoningSummary;+}++/** Text output configuration */+export interface TextConfig {+ format?: {+ type: 'text' | 'json_object' | 'json_schema';+ json_schema?: Record<string, unknown>;+ };+}++/** Stream options */+export interface StreamOptions {+ include_usage?: boolean;+}++/** Metadata (key-value pairs) */+export type Metadata = Record<string, string>;++/** Open Responses API Request */+export interface ResponseRequest {+ /** Model/agent ID to use */+ model: string;++ /** Input context - string or array of items */+ input: string | InputItem[];++ /** Previous response ID for conversation continuation */+ previous_response_id?: string;++ /** Tools available to the model */+ tools?: Tool[];++ /** Tool choice configuration */+ tool_choice?: ToolChoice;++ /** Whether to stream the response */+ stream?: boolean;++ /** Stream options */+ stream_options?: StreamOptions;++ /** Additional instructions */+ instructions?: string;++ /** Maximum output tokens */+ max_output_tokens?: number;++ /** Maximum tool calls */+ max_tool_calls?: number;++ /** Sampling temperature */+ temperature?: number;++ /** Top-p sampling */+ top_p?: number;++ /** Presence penalty */+ presence_penalty?: number;++ /** Frequency penalty */+ frequency_penalty?: number;++ /** Reasoning configuration */+ reasoning?: ReasoningConfig;++ /** Text output configuration */+ text?: TextConfig;++ /** Truncation behavior */+ truncation?: TruncationValue;++ /** Service tier */+ service_tier?: ServiceTier;++ /** Whether to store the response */+ store?: boolean;++ /** Metadata */+ metadata?: Metadata;++ /** Whether model can call multiple tools in parallel */+ parallel_tool_calls?: boolean;++ /** User identifier for safety */+ user?: string;+}++/* =============================================================================+ * RESPONSE+ * ============================================================================= */++/** Token usage details */+export interface InputTokensDetails {+ cached_tokens: number;+}++/** Output tokens details */+export interface OutputTokensDetails {+ reasoning_tokens: number;+}++/** Token usage statistics */+export interface Usage {+ input_tokens: number;+ output_tokens: number;+ total_tokens: number;+ input_tokens_details: InputTokensDetails;+ output_tokens_details: OutputTokensDetails;+}++/** Incomplete details */+export interface IncompleteDetails {+ reason: 'max_output_tokens' | 'max_tool_calls' | 'content_filter' | 'other';+}++/** Error object */+export interface ResponseError {+ type: 'server_error' | 'invalid_request' | 'not_found' | 'model_error' | 'too_many_requests';+ code?: string;+ message: string;+ param?: string;+}++/** Text field configuration */+export interface TextField {+ format?: {+ type: 'text' | 'json_object' | 'json_schema';+ json_schema?: Record<string, unknown>;+ };+}++/** Open Responses API Response - All required fields per spec */+export interface Response {+ /** Response ID */+ id: string;++ /** Object type - always "response" */+ object: 'response';++ /** Creation timestamp (Unix seconds) */+ created_at: number;++ /** Completion timestamp (Unix seconds) - null if not completed */+ completed_at: number | null;++ /** Response status */+ status: ResponseStatus;++ /** Incomplete details - null if not incomplete */+ incomplete_details: IncompleteDetails | null;++ /** Model that generated the response */+ model: string;++ /** Previous response ID - null if not a continuation */+ previous_response_id: string | null;++ /** Instructions used - null if none */+ instructions: string | null;++ /** Output items */+ output: OutputItem[];++ /** Error - null if no error */+ error: ResponseError | null;++ /** Tools available */+ tools: Tool[];++ /** Tool choice setting */+ tool_choice: ToolChoice;++ /** Truncation setting used */+ truncation: TruncationValue;++ /** Whether parallel tool calls were allowed */+ parallel_tool_calls: boolean;++ /** Text configuration used */+ text: TextField;++ /** Temperature used */+ temperature: number;++ /** Top-p used */+ top_p: number;++ /** Presence penalty used */+ presence_penalty: number;++ /** Frequency penalty used */+ frequency_penalty: number;++ /** Top logprobs - number of most likely tokens to return */+ top_logprobs: number;++ /** Reasoning configuration - null if none */+ reasoning: ReasoningConfig | null;++ /** User identifier - null if none */+ user: string | null;++ /** Token usage - null if not available */+ usage: Usage | null;++ /** Max output tokens - null if not set */+ max_output_tokens: number | null;++ /** Max tool calls - null if not set */+ max_tool_calls: number | null;++ /** Whether response was stored */+ store: boolean;++ /** Whether request was run in background */+ background: boolean;++ /** Service tier used */+ service_tier: string;++ /** Metadata */+ metadata: Metadata;++ /** Safety identifier - null if none */+ safety_identifier: string | null;++ /** Prompt cache key - null if none */+ prompt_cache_key: string | null;+}++/* =============================================================================+ * STREAMING EVENTS+ * ============================================================================= */++/** Base event structure */+export interface BaseEvent {+ type: string;+ sequence_number: number;+}++/** Response created event (first event in stream) */+export interface ResponseCreatedEvent extends BaseEvent {+ type: 'response.created';+ response: Response;+}++/** Response in_progress event */+export interface ResponseInProgressEvent extends BaseEvent {+ type: 'response.in_progress';+ response: Response;+}++/** Response completed event */+export interface ResponseCompletedEvent extends BaseEvent {+ type: 'response.completed';+ response: Response;+}++/** Response failed event */+export interface ResponseFailedEvent extends BaseEvent {+ type: 'response.failed';+ response: Response;+}++/** Response incomplete event */+export interface ResponseIncompleteEvent extends BaseEvent {+ type: 'response.incomplete';+ response: Response;+}++/** Output item added event */+export interface OutputItemAddedEvent extends BaseEvent {+ type: 'response.output_item.added';+ output_index: number;+ item: OutputItem;+}++/** Output item done event */+export interface OutputItemDoneEvent extends BaseEvent {+ type: 'response.output_item.done';+ output_index: number;+ item: OutputItem;+}++/** Content part added event */+export interface ContentPartAddedEvent extends BaseEvent {+ type: 'response.content_part.added';+ item_id: string;+ output_index: number;+ content_index: number;+ part: ModelContent | ReasoningContent;+}++/** Content part done event */+export interface ContentPartDoneEvent extends BaseEvent {+ type: 'response.content_part.done';+ item_id: string;+ output_index: number;+ content_index: number;+ part: ModelContent | ReasoningContent;+}++/** Output text delta event */+export interface OutputTextDeltaEvent extends BaseEvent {+ type: 'response.output_text.delta';+ item_id: string;+ output_index: number;+ content_index: number;+ delta: string;+ logprobs: LogProb[];+}++/** Output text done event */+export interface OutputTextDoneEvent extends BaseEvent {+ type: 'response.output_text.done';+ item_id: string;+ output_index: number;+ content_index: number;+ text: string;+ logprobs: LogProb[];+}++/** Refusal delta event */+export interface RefusalDeltaEvent extends BaseEvent {+ type: 'response.refusal.delta';+ item_id: string;+ output_index: number;+ content_index: number;+ delta: string;+}++/** Refusal done event */+export interface RefusalDoneEvent extends BaseEvent {+ type: 'response.refusal.done';+ item_id: string;+ output_index: number;+ content_index: number;+ refusal: string;+}++/** Function call arguments delta event */+export interface FunctionCallArgumentsDeltaEvent extends BaseEvent {+ type: 'response.function_call_arguments.delta';+ item_id: string;+ output_index: number;+ call_id: string;+ delta: string;+}++/** Function call arguments done event */+export interface FunctionCallArgumentsDoneEvent extends BaseEvent {+ type: 'response.function_call_arguments.done';+ item_id: string;+ output_index: number;+ call_id: string;+ arguments: string;+}++/** Reasoning delta event */+export interface ReasoningDeltaEvent extends BaseEvent {+ type: 'response.reasoning.delta';+ item_id: string;+ output_index: number;+ content_index: number;+ delta: string;+}++/** Reasoning done event */+export interface ReasoningDoneEvent extends BaseEvent {+ type: 'response.reasoning.done';+ item_id: string;+ output_index: number;+ content_index: number;+ text: string;+}++/** Error event */+export interface ErrorEvent extends BaseEvent {+ type: 'error';+ error: ResponseError;+}++/* =============================================================================+ * LIBRECHAT EXTENSION TYPES+ * Per Open Responses spec, custom types MUST be prefixed with implementor slug+ * @see https://openresponses.org/specification#extending-streaming-events+ * ============================================================================= */++/** Attachment content types for LibreChat extensions */+export interface LibreChatAttachmentContent {+ /** File ID in LibreChat storage */+ file_id?: string;+ /** Original filename */+ filename?: string;+ /** MIME type */+ type?: string;+ /** URL to access the file */+ url?: string;+ /** Base64-encoded image data (for inline images) */+ image_url?: string;+ /** Width for images */+ width?: number;+ /** Height for images */+ height?: number;+ /** Associated tool call ID */+ tool_call_id?: string;+ /** Additional metadata */+ [key: string]: unknown;+}++/**+ * LibreChat attachment event - custom streaming event for file/image attachments+ * Follows Open Responses extension pattern with librechat: prefix+ */+export interface LibreChatAttachmentEvent extends BaseEvent {+ type: 'librechat:attachment';+ /** The attachment data */+ attachment: LibreChatAttachmentContent;+ /** Associated message ID */+ message_id?: string;+ /** Associated conversation ID */+ conversation_id?: string;+}++/** Union of all streaming events (including LibreChat extensions) */+export type ResponseEvent =+ | ResponseCreatedEvent+ | ResponseInProgressEvent+ | ResponseCompletedEvent+ | ResponseFailedEvent+ | ResponseIncompleteEvent+ | OutputItemAddedEvent+ | OutputItemDoneEvent+ | ContentPartAddedEvent+ | ContentPartDoneEvent+ | OutputTextDeltaEvent+ | OutputTextDoneEvent+ | RefusalDeltaEvent+ | RefusalDoneEvent+ | FunctionCallArgumentsDeltaEvent+ | FunctionCallArgumentsDoneEvent+ | ReasoningDeltaEvent+ | ReasoningDoneEvent+ | ErrorEvent+ // LibreChat extensions (prefixed per Open Responses spec)+ | LibreChatAttachmentEvent;++/* =============================================================================+ * INTERNAL TYPES+ * ============================================================================= */++/** Context for building responses */+export interface ResponseContext {+ /** Response ID */+ responseId: string;+ /** Model/agent ID */+ model: string;+ /** Creation timestamp */+ createdAt: number;+ /** Previous response ID */+ previousResponseId?: string;+ /** Instructions */+ instructions?: string;+}++/** Validation result for requests */+export interface RequestValidationResult {+ valid: boolean;+ request?: ResponseRequest;+ error?: string;+}diff --git a/packages/api/src/apiKeys/handlers.ts b/packages/api/src/apiKeys/handlers.tsnew file mode 100644index 0000000000..61d23ccde9--- /dev/null+++ b/packages/api/src/apiKeys/handlers.ts@@ -0,0 +1,129 @@+import type { Request, Response } from 'express';+import type { Types } from 'mongoose';+import { logger } from '@librechat/data-schemas';++export interface ApiKeyHandlerDependencies {+ createAgentApiKey: (params: {+ userId: string | Types.ObjectId;+ name: string;+ expiresAt?: Date | null;+ }) => Promise<{+ id: string;+ name: string;+ key: string;+ keyPrefix: string;+ createdAt: Date;+ expiresAt?: Date;+ }>;+ listAgentApiKeys: (userId: string | Types.ObjectId) => Promise<+ Array<{+ id: string;+ name: string;+ keyPrefix: string;+ lastUsedAt?: Date;+ expiresAt?: Date;+ createdAt: Date;+ }>+ >;+ deleteAgentApiKey: (+ keyId: string | Types.ObjectId,+ userId: string | Types.ObjectId,+ ) => Promise<boolean>;+ getAgentApiKeyById: (+ keyId: string | Types.ObjectId,+ userId: string | Types.ObjectId,+ ) => Promise<{+ id: string;+ name: string;+ keyPrefix: string;+ lastUsedAt?: Date;+ expiresAt?: Date;+ createdAt: Date;+ } | null>;+}++interface AuthenticatedRequest extends Request {+ user?: {+ id: string;+ _id: Types.ObjectId;+ };+}++export function createApiKeyHandlers(deps: ApiKeyHandlerDependencies) {+ async function createApiKey(req: AuthenticatedRequest, res: Response) {+ try {+ const { name, expiresAt } = req.body;++ if (!name || typeof name !== 'string' || name.trim() === '') {+ return res.status(400).json({+ error: 'API key name is required',+ });+ }++ const result = await deps.createAgentApiKey({+ userId: req.user?.id || '',+ name: name.trim(),+ expiresAt: expiresAt ? new Date(expiresAt) : null,+ });++ res.status(201).json({+ id: result.id,+ name: result.name,+ key: result.key,+ keyPrefix: result.keyPrefix,+ createdAt: result.createdAt,+ expiresAt: result.expiresAt,+ });+ } catch (error) {+ logger.error('[createApiKey] Error creating API key:', error);+ res.status(500).json({ error: 'Failed to create API key' });+ }+ }++ async function listApiKeys(req: AuthenticatedRequest, res: Response) {+ try {+ const keys = await deps.listAgentApiKeys(req.user?.id || '');+ res.status(200).json({ keys });+ } catch (error) {+ logger.error('[listApiKeys] Error listing API keys:', error);+ res.status(500).json({ error: 'Failed to list API keys' });+ }+ }++ async function getApiKey(req: AuthenticatedRequest, res: Response) {+ try {+ const key = await deps.getAgentApiKeyById(req.params.id, req.user?.id || '');++ if (!key) {+ return res.status(404).json({ error: 'API key not found' });+ }++ res.status(200).json(key);+ } catch (error) {+ logger.error('[getApiKey] Error getting API key:', error);+ res.status(500).json({ error: 'Failed to get API key' });+ }+ }++ async function deleteApiKey(req: AuthenticatedRequest, res: Response) {+ try {+ const deleted = await deps.deleteAgentApiKey(req.params.id, req.user?.id || '');++ if (!deleted) {+ return res.status(404).json({ error: 'API key not found' });+ }++ res.status(204).send();+ } catch (error) {+ logger.error('[deleteApiKey] Error deleting API key:', error);+ res.status(500).json({ error: 'Failed to delete API key' });+ }+ }++ return {+ createApiKey,+ listApiKeys,+ getApiKey,+ deleteApiKey,+ };+}diff --git a/packages/api/src/apiKeys/index.ts b/packages/api/src/apiKeys/index.tsnew file mode 100644index 0000000000..69fd7b5c1a--- /dev/null+++ b/packages/api/src/apiKeys/index.ts@@ -0,0 +1,4 @@+export * from './service';+export * from './middleware';+export * from './handlers';+export * from './permissions';diff --git a/packages/api/src/apiKeys/middleware.ts b/packages/api/src/apiKeys/middleware.tsnew file mode 100644index 0000000000..2a50353648--- /dev/null+++ b/packages/api/src/apiKeys/middleware.ts@@ -0,0 +1,163 @@+import { logger } from '@librechat/data-schemas';+import { ResourceType, PermissionBits, hasPermissions } from 'librechat-data-provider';+import type { Request, Response, NextFunction } from 'express';+import type { IUser } from '@librechat/data-schemas';+import type { Types } from 'mongoose';+import { getRemoteAgentPermissions } from './service';++export interface ApiKeyAuthDependencies {+ validateAgentApiKey: (apiKey: string) => Promise<{+ userId: Types.ObjectId;+ keyId: Types.ObjectId;+ } | null>;+ findUser: (query: { _id: string | Types.ObjectId }) => Promise<IUser | null>;+}++export interface RemoteAgentAccessDependencies {+ getAgent: (query: {+ id: string;+ }) => Promise<{ _id: Types.ObjectId; [key: string]: unknown } | null>;+ getEffectivePermissions: (params: {+ userId: string;+ role?: string;+ resourceType: ResourceType;+ resourceId: string | Types.ObjectId;+ }) => Promise<number>;+}++export interface ApiKeyAuthRequest extends Request {+ user?: IUser & { id: string };+ apiKeyId?: Types.ObjectId;+}++export interface RemoteAgentAccessRequest extends ApiKeyAuthRequest {+ agent?: { _id: Types.ObjectId; [key: string]: unknown };+ agentPermissions?: number;+}++export function createRequireApiKeyAuth(deps: ApiKeyAuthDependencies) {+ return async (req: ApiKeyAuthRequest, res: Response, next: NextFunction) => {+ const authHeader = req.headers.authorization;++ if (!authHeader || !authHeader.startsWith('Bearer ')) {+ return res.status(401).json({+ error: {+ message: 'Missing or invalid Authorization header. Expected: Bearer <api_key>',+ type: 'invalid_request_error',+ code: 'missing_api_key',+ },+ });+ }++ const apiKey = authHeader.slice(7);++ if (!apiKey || apiKey.trim() === '') {+ return res.status(401).json({+ error: {+ message: 'API key is required',+ type: 'invalid_request_error',+ code: 'missing_api_key',+ },+ });+ }++ try {+ const keyValidation = await deps.validateAgentApiKey(apiKey);++ if (!keyValidation) {+ return res.status(401).json({+ error: {+ message: 'Invalid API key',+ type: 'invalid_request_error',+ code: 'invalid_api_key',+ },+ });+ }++ const user = await deps.findUser({ _id: keyValidation.userId });++ if (!user) {+ return res.status(401).json({+ error: {+ message: 'User not found for this API key',+ type: 'invalid_request_error',+ code: 'invalid_api_key',+ },+ });+ }++ user.id = (user._id as Types.ObjectId).toString();+ req.user = user as IUser & { id: string };+ req.apiKeyId = keyValidation.keyId;++ next();+ } catch (error) {+ logger.error('[requireApiKeyAuth] Error validating API key:', error);+ return res.status(500).json({+ error: {+ message: 'Internal server error during authentication',+ type: 'server_error',+ code: 'internal_error',+ },+ });+ }+ };+}++export function createCheckRemoteAgentAccess(deps: RemoteAgentAccessDependencies) {+ return async (req: RemoteAgentAccessRequest, res: Response, next: NextFunction) => {+ const agentId = req.body?.model || req.params?.model;++ if (!agentId) {+ return res.status(400).json({+ error: {+ message: 'Model (agent ID) is required',+ type: 'invalid_request_error',+ code: 'missing_model',+ },+ });+ }++ try {+ const agent = await deps.getAgent({ id: agentId });++ if (!agent) {+ return res.status(404).json({+ error: {+ message: `Agent not found: ${agentId}`,+ type: 'invalid_request_error',+ code: 'model_not_found',+ },+ });+ }++ const userId = req.user?.id || '';++ const permissions = await getRemoteAgentPermissions(deps, userId, req.user?.role, agent._id);++ if (!hasPermissions(permissions, PermissionBits.VIEW)) {+ return res.status(403).json({+ error: {+ message: `No remote access to agent: ${agentId}`,+ type: 'permission_error',+ code: 'access_denied',+ },+ });+ }++ req.agent = agent;+ req.agentPermissions = permissions;++ next();+ } catch (error) {+ logger.error('[checkRemoteAgentAccess] Error checking agent access:', error);+ return res.status(500).json({+ error: {+ message: 'Internal server error while checking agent access',+ type: 'server_error',+ code: 'internal_error',+ },+ });+ }+ };+}diff --git a/packages/api/src/apiKeys/permissions.ts b/packages/api/src/apiKeys/permissions.tsnew file mode 100644index 0000000000..2556f25b57--- /dev/null+++ b/packages/api/src/apiKeys/permissions.ts@@ -0,0 +1,169 @@+import {+ ResourceType,+ PrincipalType,+ PermissionBits,+ AccessRoleIds,+} from 'librechat-data-provider';+import type { Types, Model } from 'mongoose';++export interface Principal {+ type: string;+ id: string;+ name: string;+ email?: string;+ avatar?: string;+ source?: string;+ idOnTheSource?: string;+ accessRoleId: string;+ isImplicit?: boolean;+}++export interface EnricherDependencies {+ AclEntry: Model<{+ principalType: string;+ principalId: Types.ObjectId;+ resourceType: string;+ resourceId: Types.ObjectId;+ permBits: number;+ roleId: Types.ObjectId;+ grantedBy: Types.ObjectId;+ grantedAt: Date;+ }>;+ AccessRole: Model<{+ accessRoleId: string;+ permBits: number;+ }>;+ logger: { error: (msg: string, ...args: unknown[]) => void };+}++export interface EnrichResult {+ principals: Principal[];+ entriesToBackfill: Types.ObjectId[];+}++/** Enriches REMOTE_AGENT principals with implicit AGENT owners */+export async function enrichRemoteAgentPrincipals(+ deps: EnricherDependencies,+ resourceId: string | Types.ObjectId,+ principals: Principal[],+): Promise<EnrichResult> {+ const { AclEntry } = deps;++ const resourceObjectId =+ typeof resourceId === 'string' && /^[a-f\d]{24}$/i.test(resourceId)+ ? deps.AclEntry.base.Types.ObjectId.createFromHexString(resourceId)+ : resourceId;++ const agentOwnerEntries = await AclEntry.aggregate([+ {+ $match: {+ resourceType: ResourceType.AGENT,+ resourceId: resourceObjectId,+ principalType: PrincipalType.USER,+ permBits: { $bitsAllSet: PermissionBits.SHARE },+ },+ },+ {+ $lookup: {+ from: 'users',+ localField: 'principalId',+ foreignField: '_id',+ as: 'userInfo',+ },+ },+ {+ $project: {+ principalId: 1,+ userInfo: { $arrayElemAt: ['$userInfo', 0] },+ },+ },+ ]);++ const enrichedPrincipals = [...principals];+ const entriesToBackfill: Types.ObjectId[] = [];++ for (const entry of agentOwnerEntries) {+ if (!entry.userInfo) {+ continue;+ }++ const alreadyIncluded = enrichedPrincipals.some(+ (p) => p.type === PrincipalType.USER && p.id === entry.principalId.toString(),+ );++ if (!alreadyIncluded) {+ enrichedPrincipals.unshift({+ type: PrincipalType.USER,+ id: entry.userInfo._id.toString(),+ name: entry.userInfo.name || entry.userInfo.username,+ email: entry.userInfo.email,+ avatar: entry.userInfo.avatar,+ source: 'local',+ idOnTheSource: entry.userInfo.idOnTheSource || entry.userInfo._id.toString(),+ accessRoleId: AccessRoleIds.REMOTE_AGENT_OWNER,+ isImplicit: true,+ });++ entriesToBackfill.push(entry.principalId);+ }+ }++ return { principals: enrichedPrincipals, entriesToBackfill };+}++/** Backfills REMOTE_AGENT ACL entries for AGENT owners (fire-and-forget) */+export function backfillRemoteAgentPermissions(+ deps: EnricherDependencies,+ resourceId: string | Types.ObjectId,+ entriesToBackfill: Types.ObjectId[],+): void {+ if (entriesToBackfill.length === 0) {+ return;+ }++ const { AclEntry, AccessRole, logger } = deps;++ const resourceObjectId =+ typeof resourceId === 'string' && /^[a-f\d]{24}$/i.test(resourceId)+ ? AclEntry.base.Types.ObjectId.createFromHexString(resourceId)+ : resourceId;++ AccessRole.findOne({ accessRoleId: AccessRoleIds.REMOTE_AGENT_OWNER })+ .lean()+ .then((role) => {+ if (!role) {+ logger.error('[backfillRemoteAgentPermissions] REMOTE_AGENT_OWNER role not found');+ return;+ }++ const bulkOps = entriesToBackfill.map((principalId) => ({+ updateOne: {+ filter: {+ principalType: PrincipalType.USER,+ principalId,+ resourceType: ResourceType.REMOTE_AGENT,+ resourceId: resourceObjectId,+ },+ update: {+ $setOnInsert: {+ principalType: PrincipalType.USER,+ principalId,+ principalModel: 'User',+ resourceType: ResourceType.REMOTE_AGENT,+ resourceId: resourceObjectId,+ permBits: role.permBits,+ roleId: role._id,+ grantedBy: principalId,+ grantedAt: new Date(),+ },+ },+ upsert: true,+ },+ }));++ return AclEntry.bulkWrite(bulkOps, { ordered: false });+ })+ .catch((err) => {+ logger.error('[backfillRemoteAgentPermissions] Failed to backfill:', err);+ });+}diff --git a/packages/api/src/apiKeys/service.ts b/packages/api/src/apiKeys/service.tsnew file mode 100644index 0000000000..30ae0afb53--- /dev/null+++ b/packages/api/src/apiKeys/service.ts@@ -0,0 +1,146 @@+import { createMethods } from '@librechat/data-schemas';+import { ResourceType, PermissionBits, hasPermissions } from 'librechat-data-provider';+import type { AllMethods, IUser } from '@librechat/data-schemas';+import type { Types } from 'mongoose';++export interface ApiKeyServiceDependencies {+ validateAgentApiKey: AllMethods['validateAgentApiKey'];+ createAgentApiKey: AllMethods['createAgentApiKey'];+ listAgentApiKeys: AllMethods['listAgentApiKeys'];+ deleteAgentApiKey: AllMethods['deleteAgentApiKey'];+ getAgentApiKeyById: AllMethods['getAgentApiKeyById'];+ findUser: (query: { _id: string | Types.ObjectId }) => Promise<IUser | null>;+}++export interface RemoteAgentAccessResult {+ hasAccess: boolean;+ permissions: number;+ agent: { _id: Types.ObjectId; [key: string]: unknown } | null;+}++export class AgentApiKeyService {+ private deps: ApiKeyServiceDependencies;++ constructor(deps: ApiKeyServiceDependencies) {+ this.deps = deps;+ }++ async validateApiKey(apiKey: string): Promise<{+ userId: Types.ObjectId;+ keyId: Types.ObjectId;+ } | null> {+ return this.deps.validateAgentApiKey(apiKey);+ }++ async createApiKey(params: {+ userId: string | Types.ObjectId;+ name: string;+ expiresAt?: Date | null;+ }) {+ return this.deps.createAgentApiKey(params);+ }++ async listApiKeys(userId: string | Types.ObjectId) {+ return this.deps.listAgentApiKeys(userId);+ }++ async deleteApiKey(keyId: string | Types.ObjectId, userId: string | Types.ObjectId) {+ return this.deps.deleteAgentApiKey(keyId, userId);+ }++ async getApiKeyById(keyId: string | Types.ObjectId, userId: string | Types.ObjectId) {+ return this.deps.getAgentApiKeyById(keyId, userId);+ }++ async getUserFromApiKey(apiKey: string): Promise<IUser | null> {+ const keyValidation = await this.validateApiKey(apiKey);+ if (!keyValidation) {+ return null;+ }++ return this.deps.findUser({ _id: keyValidation.userId });+ }+}++export function createApiKeyServiceDependencies(+ mongoose: typeof import('mongoose'),+): ApiKeyServiceDependencies {+ const methods = createMethods(mongoose);+ return {+ validateAgentApiKey: methods.validateAgentApiKey,+ createAgentApiKey: methods.createAgentApiKey,+ listAgentApiKeys: methods.listAgentApiKeys,+ deleteAgentApiKey: methods.deleteAgentApiKey,+ getAgentApiKeyById: methods.getAgentApiKeyById,+ findUser: methods.findUser,+ };+}++export interface GetRemoteAgentPermissionsDeps {+ getEffectivePermissions: (params: {+ userId: string;+ role?: string;+ resourceType: ResourceType;+ resourceId: string | Types.ObjectId;+ }) => Promise<number>;+}++/** AGENT owners automatically have full REMOTE_AGENT permissions */+export async function getRemoteAgentPermissions(+ deps: GetRemoteAgentPermissionsDeps,+ userId: string,+ role: string | undefined,+ resourceId: string | Types.ObjectId,+): Promise<number> {+ const agentPerms = await deps.getEffectivePermissions({+ userId,+ role,+ resourceType: ResourceType.AGENT,+ resourceId,+ });++ if (hasPermissions(agentPerms, PermissionBits.SHARE)) {+ return PermissionBits.VIEW | PermissionBits.EDIT | PermissionBits.DELETE | PermissionBits.SHARE;+ }++ return deps.getEffectivePermissions({+ userId,+ role,+ resourceType: ResourceType.REMOTE_AGENT,+ resourceId,+ });+}++export async function checkRemoteAgentAccess(params: {+ userId: string;+ role?: string;+ agentId: string;+ getAgent: (query: {+ id: string;+ }) => Promise<{ _id: Types.ObjectId; [key: string]: unknown } | null>;+ getEffectivePermissions: (params: {+ userId: string;+ role?: string;+ resourceType: ResourceType;+ resourceId: string | Types.ObjectId;+ }) => Promise<number>;+}): Promise<RemoteAgentAccessResult> {+ const { userId, role, agentId, getAgent, getEffectivePermissions } = params;++ const agent = await getAgent({ id: agentId });++ if (!agent) {+ return { hasAccess: false, permissions: 0, agent: null };+ }++ const permissions = await getRemoteAgentPermissions(+ { getEffectivePermissions },+ userId,+ role,+ agent._id,+ );++ const hasAccess = hasPermissions(permissions, PermissionBits.VIEW);++ return { hasAccess, permissions, agent };+}diff --git a/packages/api/src/app/permissions.spec.ts b/packages/api/src/app/permissions.spec.tsindex b84ad63498..a787c0c3a3 100644--- a/packages/api/src/app/permissions.spec.ts+++ b/packages/api/src/app/permissions.spec.ts@@ -100,6 +100,12 @@ describe('updateInterfacePermissions - permissions', () => {[Permissions.SHARE]: false,[Permissions.SHARE_PUBLIC]: false,},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: false,+ [Permissions.CREATE]: false,+ [Permissions.SHARE]: false,+ [Permissions.SHARE_PUBLIC]: false,+ },};const expectedPermissionsForAdmin = {@@ -141,6 +147,12 @@ describe('updateInterfacePermissions - permissions', () => {[Permissions.SHARE]: false,[Permissions.SHARE_PUBLIC]: false,},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: true,+ [Permissions.CREATE]: true,+ [Permissions.SHARE]: true,+ [Permissions.SHARE_PUBLIC]: true,+ },};expect(mockUpdateAccessPermissions).toHaveBeenCalledTimes(2);@@ -246,6 +258,12 @@ describe('updateInterfacePermissions - permissions', () => {[Permissions.SHARE]: false,[Permissions.SHARE_PUBLIC]: false,},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: false,+ [Permissions.CREATE]: false,+ [Permissions.SHARE]: false,+ [Permissions.SHARE_PUBLIC]: false,+ },};const expectedPermissionsForAdmin = {@@ -287,6 +305,12 @@ describe('updateInterfacePermissions - permissions', () => {[Permissions.SHARE]: false,[Permissions.SHARE_PUBLIC]: false,},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: true,+ [Permissions.CREATE]: true,+ [Permissions.SHARE]: true,+ [Permissions.SHARE_PUBLIC]: true,+ },};expect(mockUpdateAccessPermissions).toHaveBeenCalledTimes(2);@@ -378,6 +402,12 @@ describe('updateInterfacePermissions - permissions', () => {[Permissions.SHARE]: false,[Permissions.SHARE_PUBLIC]: false,},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: false,+ [Permissions.CREATE]: false,+ [Permissions.SHARE]: false,+ [Permissions.SHARE_PUBLIC]: false,+ },};const expectedPermissionsForAdmin = {@@ -419,6 +449,12 @@ describe('updateInterfacePermissions - permissions', () => {[Permissions.SHARE]: true,[Permissions.SHARE_PUBLIC]: true,},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: true,+ [Permissions.CREATE]: true,+ [Permissions.SHARE]: true,+ [Permissions.SHARE_PUBLIC]: true,+ },};expect(mockUpdateAccessPermissions).toHaveBeenCalledTimes(2);@@ -523,6 +559,12 @@ describe('updateInterfacePermissions - permissions', () => {[Permissions.SHARE]: false,[Permissions.SHARE_PUBLIC]: false,},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: false,+ [Permissions.CREATE]: false,+ [Permissions.SHARE]: false,+ [Permissions.SHARE_PUBLIC]: false,+ },};const expectedPermissionsForAdmin = {@@ -564,6 +606,12 @@ describe('updateInterfacePermissions - permissions', () => {[Permissions.SHARE]: true,[Permissions.SHARE_PUBLIC]: true,},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: true,+ [Permissions.CREATE]: true,+ [Permissions.SHARE]: true,+ [Permissions.SHARE_PUBLIC]: true,+ },};expect(mockUpdateAccessPermissions).toHaveBeenCalledTimes(2);@@ -655,6 +703,12 @@ describe('updateInterfacePermissions - permissions', () => {[Permissions.SHARE]: false,[Permissions.SHARE_PUBLIC]: false,},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: false,+ [Permissions.CREATE]: false,+ [Permissions.SHARE]: false,+ [Permissions.SHARE_PUBLIC]: false,+ },};const expectedPermissionsForAdmin = {@@ -696,6 +750,12 @@ describe('updateInterfacePermissions - permissions', () => {[Permissions.SHARE]: true,[Permissions.SHARE_PUBLIC]: true,},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: true,+ [Permissions.CREATE]: true,+ [Permissions.SHARE]: true,+ [Permissions.SHARE_PUBLIC]: true,+ },};expect(mockUpdateAccessPermissions).toHaveBeenCalledTimes(2);@@ -784,6 +844,12 @@ describe('updateInterfacePermissions - permissions', () => {[Permissions.SHARE]: false,[Permissions.SHARE_PUBLIC]: false,},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: false,+ [Permissions.CREATE]: false,+ [Permissions.SHARE]: false,+ [Permissions.SHARE_PUBLIC]: false,+ },};const expectedPermissionsForAdmin = {@@ -813,6 +879,12 @@ describe('updateInterfacePermissions - permissions', () => {[Permissions.SHARE]: true,[Permissions.SHARE_PUBLIC]: true,},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: true,+ [Permissions.CREATE]: true,+ [Permissions.SHARE]: true,+ [Permissions.SHARE_PUBLIC]: true,+ },};expect(mockUpdateAccessPermissions).toHaveBeenCalledTimes(2);@@ -920,6 +992,12 @@ describe('updateInterfacePermissions - permissions', () => {[Permissions.SHARE]: false,[Permissions.SHARE_PUBLIC]: false,},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: false,+ [Permissions.CREATE]: false,+ [Permissions.SHARE]: false,+ [Permissions.SHARE_PUBLIC]: false,+ },};const expectedPermissionsForAdmin = {@@ -955,6 +1033,12 @@ describe('updateInterfacePermissions - permissions', () => {[Permissions.SHARE]: true,[Permissions.SHARE_PUBLIC]: true,},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: true,+ [Permissions.CREATE]: true,+ [Permissions.SHARE]: true,+ [Permissions.SHARE_PUBLIC]: true,+ },};expect(mockUpdateAccessPermissions).toHaveBeenCalledTimes(2);diff --git a/packages/api/src/app/permissions.ts b/packages/api/src/app/permissions.tsindex bfa49e6bbd..8f97236823 100644--- a/packages/api/src/app/permissions.ts+++ b/packages/api/src/app/permissions.ts@@ -43,6 +43,8 @@ function hasExplicitConfig(return interfaceConfig?.fileCitations !== undefined;case PermissionTypes.MCP_SERVERS:return interfaceConfig?.mcpServers !== undefined;+ case PermissionTypes.REMOTE_AGENTS:+ return interfaceConfig?.remoteAgents !== undefined;default:return false;}@@ -101,7 +103,9 @@ export async function updateInterfacePermissions({const defaultPerms = roleDefaults[roleName]?.permissions;const existingRole = await getRoleByName(roleName);- const existingPermissions = existingRole?.permissions;+ const existingPermissions = existingRole?.permissions as+ | Partial<Record<PermissionTypes, Record<string, boolean | undefined>>>+ | undefined;const permissionsToUpdate: Partial<Record<PermissionTypes, Record<string, boolean | undefined>>> = {};@@ -335,6 +339,28 @@ export async function updateInterfacePermissions({defaults.mcpServers?.public,),},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: getPermissionValue(+ loadedInterface.remoteAgents?.use,+ defaultPerms[PermissionTypes.REMOTE_AGENTS]?.[Permissions.USE],+ defaults.remoteAgents?.use,+ ),+ [Permissions.CREATE]: getPermissionValue(+ loadedInterface.remoteAgents?.create,+ defaultPerms[PermissionTypes.REMOTE_AGENTS]?.[Permissions.CREATE],+ defaults.remoteAgents?.create,+ ),+ [Permissions.SHARE]: getPermissionValue(+ loadedInterface.remoteAgents?.share,+ defaultPerms[PermissionTypes.REMOTE_AGENTS]?.[Permissions.SHARE],+ defaults.remoteAgents?.share,+ ),+ [Permissions.SHARE_PUBLIC]: getPermissionValue(+ loadedInterface.remoteAgents?.public,+ defaultPerms[PermissionTypes.REMOTE_AGENTS]?.[Permissions.SHARE_PUBLIC],+ defaults.remoteAgents?.public,+ ),+ },};// Check and add each permission type if neededdiff --git a/packages/api/src/index.ts b/packages/api/src/index.tsindex 492b59f232..fefdafaefd 100644--- a/packages/api/src/index.ts+++ b/packages/api/src/index.ts@@ -2,6 +2,8 @@ export * from './app';export * from './cdn';/* Auth */export * from './auth';+/* API Keys */+export * from './apiKeys';/* MCP */export * from './mcp/registry/MCPServersRegistry';export * from './mcp/MCPManager';diff --git a/packages/data-provider/src/accessPermissions.ts b/packages/data-provider/src/accessPermissions.tsindex 5fa288e4b3..f2431fcf9a 100644--- a/packages/data-provider/src/accessPermissions.ts+++ b/packages/data-provider/src/accessPermissions.ts@@ -46,6 +46,7 @@ export enum ResourceType {AGENT = 'agent',PROMPTGROUP = 'promptGroup',MCPSERVER = 'mcpServer',+ REMOTE_AGENT = 'remoteAgent',}/**@@ -75,6 +76,9 @@ export enum AccessRoleIds {MCPSERVER_VIEWER = 'mcpServer_viewer',MCPSERVER_EDITOR = 'mcpServer_editor',MCPSERVER_OWNER = 'mcpServer_owner',+ REMOTE_AGENT_VIEWER = 'remoteAgent_viewer',+ REMOTE_AGENT_EDITOR = 'remoteAgent_editor',+ REMOTE_AGENT_OWNER = 'remoteAgent_owner',}// ===== ZOD SCHEMAS =====@@ -310,11 +314,22 @@ export function permBitsToAccessLevel(permBits: number): TAccessLevel {export function accessRoleToPermBits(accessRoleId: string): number {switch (accessRoleId) {case AccessRoleIds.AGENT_VIEWER:+ case AccessRoleIds.PROMPTGROUP_VIEWER:+ case AccessRoleIds.MCPSERVER_VIEWER:+ case AccessRoleIds.REMOTE_AGENT_VIEWER:return PermissionBits.VIEW;case AccessRoleIds.AGENT_EDITOR:+ case AccessRoleIds.PROMPTGROUP_EDITOR:+ case AccessRoleIds.MCPSERVER_EDITOR:+ case AccessRoleIds.REMOTE_AGENT_EDITOR:return PermissionBits.VIEW | PermissionBits.EDIT;case AccessRoleIds.AGENT_OWNER:- return PermissionBits.VIEW | PermissionBits.EDIT | PermissionBits.DELETE;+ case AccessRoleIds.PROMPTGROUP_OWNER:+ case AccessRoleIds.MCPSERVER_OWNER:+ case AccessRoleIds.REMOTE_AGENT_OWNER:+ return (+ PermissionBits.VIEW | PermissionBits.EDIT | PermissionBits.DELETE | PermissionBits.SHARE+ );default:return PermissionBits.VIEW;}diff --git a/packages/data-provider/src/api-endpoints.ts b/packages/data-provider/src/api-endpoints.tsindex ef7e0d6cfb..d49535b094 100644--- a/packages/data-provider/src/api-endpoints.ts+++ b/packages/data-provider/src/api-endpoints.ts@@ -95,6 +95,12 @@ export const revokeUserKey = (name: string) => `${keysEndpoint}/${name}`;export const revokeAllUserKeys = () => `${keysEndpoint}?all=true`;+const apiKeysEndpoint = `${BASE_URL}/api/api-keys`;++export const apiKeys = () => apiKeysEndpoint;++export const apiKeyById = (id: string) => `${apiKeysEndpoint}/${id}`;+export const conversationsRoot = `${BASE_URL}/api/convos`;export const conversations = (params: q.ConversationListParams) => {@@ -329,6 +335,8 @@ export const updateAgentPermissions = (roleName: string) => `${getRole(roleName)export const updatePeoplePickerPermissions = (roleName: string) =>`${getRole(roleName)}/people-picker`;export const updateMCPServersPermissions = (roleName: string) => `${getRole(roleName)}/mcp-servers`;+export const updateRemoteAgentsPermissions = (roleName: string) =>+ `${getRole(roleName)}/remote-agents`;export const updateMarketplacePermissions = (roleName: string) =>`${getRole(roleName)}/marketplace`;diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.tsindex 4eb143f414..c609de0e41 100644--- a/packages/data-provider/src/config.ts+++ b/packages/data-provider/src/config.ts@@ -660,6 +660,14 @@ export const interfaceSchema = z.optional(),fileSearch: z.boolean().optional(),fileCitations: z.boolean().optional(),+ remoteAgents: z+ .object({+ use: z.boolean().optional(),+ create: z.boolean().optional(),+ share: z.boolean().optional(),+ public: z.boolean().optional(),+ })+ .optional(),}).default({endpointsMenu: true,@@ -699,6 +707,12 @@ export const interfaceSchema = z},fileSearch: true,fileCitations: true,+ remoteAgents: {+ use: false,+ create: false,+ share: false,+ public: false,+ },});export type TInterfaceConfig = z.infer<typeof interfaceSchema>;diff --git a/packages/data-provider/src/data-service.ts b/packages/data-provider/src/data-service.tsindex 911cc7863c..8919e2589b 100644--- a/packages/data-provider/src/data-service.ts+++ b/packages/data-provider/src/data-service.ts@@ -81,6 +81,20 @@ export function updateUserKey(payload: t.TUpdateUserKeyRequest) {return request.put(endpoints.keys(), payload);}+export function getAgentApiKeys(): Promise<t.TAgentApiKeyListResponse> {+ return request.get(endpoints.apiKeys());+}++export function createAgentApiKey(+ payload: t.TAgentApiKeyCreateRequest,+): Promise<t.TAgentApiKeyCreateResponse> {+ return request.post(endpoints.apiKeys(), payload);+}++export function deleteAgentApiKey(id: string): Promise<void> {+ return request.delete(endpoints.apiKeyById(id));+}+export function getPresets(): Promise<s.TPreset[]> {return request.get(endpoints.presets());}@@ -877,6 +891,15 @@ export function updateMCPServersPermissions(return request.put(endpoints.updateMCPServersPermissions(variables.roleName), variables.updates);}+export function updateRemoteAgentsPermissions(+ variables: m.UpdateRemoteAgentsPermVars,+): Promise<m.UpdatePermResponse> {+ return request.put(+ endpoints.updateRemoteAgentsPermissions(variables.roleName),+ variables.updates,+ );+}+export function updateMarketplacePermissions(variables: m.UpdateMarketplacePermVars,): Promise<m.UpdatePermResponse> {diff --git a/packages/data-provider/src/keys.ts b/packages/data-provider/src/keys.tsindex 235baf4ebe..a5e67878ed 100644--- a/packages/data-provider/src/keys.ts+++ b/packages/data-provider/src/keys.ts@@ -62,6 +62,8 @@ export enum QueryKeys {mcpServer = 'mcpServer',/* Active Jobs */activeJobs = 'activeJobs',+ /* Agent API Keys */+ agentApiKeys = 'agentApiKeys',}// Dynamic query keys that require parameters@@ -70,6 +72,8 @@ export const DynamicQueryKeys = {} as const;export enum MutationKeys {+ createAgentApiKey = 'createAgentApiKey',+ deleteAgentApiKey = 'deleteAgentApiKey',fileUpload = 'fileUpload',fileDelete = 'fileDelete',updatePreset = 'updatePreset',diff --git a/packages/data-provider/src/permissions.ts b/packages/data-provider/src/permissions.tsindex 0d53dbe29b..7a3144c82d 100644--- a/packages/data-provider/src/permissions.ts+++ b/packages/data-provider/src/permissions.ts@@ -56,6 +56,10 @@ export enum PermissionTypes {* Type for MCP Server Permissions*/MCP_SERVERS = 'MCP_SERVERS',+ /**+ * Type for Remote Agent (API) Permissions+ */+ REMOTE_AGENTS = 'REMOTE_AGENTS',}/**@@ -157,6 +161,14 @@ export const mcpServersPermissionsSchema = z.object({});export type TMcpServersPermissions = z.infer<typeof mcpServersPermissionsSchema>;+export const remoteAgentsPermissionsSchema = z.object({+ [Permissions.USE]: z.boolean().default(false),+ [Permissions.CREATE]: z.boolean().default(false),+ [Permissions.SHARE]: z.boolean().default(false),+ [Permissions.SHARE_PUBLIC]: z.boolean().default(false),+});+export type TRemoteAgentsPermissions = z.infer<typeof remoteAgentsPermissionsSchema>;+// Define a single permissions schema that holds all permission types.export const permissionsSchema = z.object({[PermissionTypes.PROMPTS]: promptPermissionsSchema,@@ -172,4 +184,5 @@ export const permissionsSchema = z.object({[PermissionTypes.FILE_SEARCH]: fileSearchPermissionsSchema,[PermissionTypes.FILE_CITATIONS]: fileCitationsPermissionsSchema,[PermissionTypes.MCP_SERVERS]: mcpServersPermissionsSchema,+ [PermissionTypes.REMOTE_AGENTS]: remoteAgentsPermissionsSchema,});diff --git a/packages/data-provider/src/react-query/react-query-service.ts b/packages/data-provider/src/react-query/react-query-service.tsindex cd259fb50c..9d08d9d56a 100644--- a/packages/data-provider/src/react-query/react-query-service.ts+++ b/packages/data-provider/src/react-query/react-query-service.ts@@ -524,3 +524,43 @@ export const useMCPServerConnectionStatusQuery = (},);};++export const useGetAgentApiKeysQuery = (+ config?: UseQueryOptions<t.TAgentApiKeyListResponse>,+): QueryObserverResult<t.TAgentApiKeyListResponse> => {+ return useQuery<t.TAgentApiKeyListResponse>(+ [QueryKeys.agentApiKeys],+ () => dataService.getAgentApiKeys(),+ {+ refetchOnWindowFocus: false,+ refetchOnReconnect: false,+ refetchOnMount: false,+ ...config,+ },+ );+};++export const useCreateAgentApiKeyMutation = (): UseMutationResult<+ t.TAgentApiKeyCreateResponse,+ unknown,+ t.TAgentApiKeyCreateRequest+> => {+ const queryClient = useQueryClient();+ return useMutation(+ (payload: t.TAgentApiKeyCreateRequest) => dataService.createAgentApiKey(payload),+ {+ onSuccess: () => {+ queryClient.invalidateQueries([QueryKeys.agentApiKeys]);+ },+ },+ );+};++export const useDeleteAgentApiKeyMutation = (): UseMutationResult<void, unknown, string> => {+ const queryClient = useQueryClient();+ return useMutation((id: string) => dataService.deleteAgentApiKey(id), {+ onSuccess: () => {+ queryClient.invalidateQueries([QueryKeys.agentApiKeys]);+ },+ });+};diff --git a/packages/data-provider/src/roles.ts b/packages/data-provider/src/roles.tsindex b3d44a49d9..b494ee5817 100644--- a/packages/data-provider/src/roles.ts+++ b/packages/data-provider/src/roles.ts@@ -11,10 +11,11 @@ import {webSearchPermissionsSchema,fileSearchPermissionsSchema,multiConvoPermissionsSchema,- temporaryChatPermissionsSchema,+ mcpServersPermissionsSchema,peoplePickerPermissionsSchema,+ remoteAgentsPermissionsSchema,+ temporaryChatPermissionsSchema,fileCitationsPermissionsSchema,- mcpServersPermissionsSchema,} from './permissions';/**@@ -96,6 +97,12 @@ const defaultRolesSchema = z.object({[Permissions.SHARE]: z.boolean().default(true),[Permissions.SHARE_PUBLIC]: z.boolean().default(true),}),+ [PermissionTypes.REMOTE_AGENTS]: remoteAgentsPermissionsSchema.extend({+ [Permissions.USE]: z.boolean().default(true),+ [Permissions.CREATE]: z.boolean().default(true),+ [Permissions.SHARE]: z.boolean().default(true),+ [Permissions.SHARE_PUBLIC]: z.boolean().default(true),+ }),}),}),[SystemRoles.USER]: roleSchema.extend({@@ -162,6 +169,12 @@ export const roleDefaults = defaultRolesSchema.parse({[Permissions.SHARE]: true,[Permissions.SHARE_PUBLIC]: true,},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: true,+ [Permissions.CREATE]: true,+ [Permissions.SHARE]: true,+ [Permissions.SHARE_PUBLIC]: true,+ },},},[SystemRoles.USER]: {@@ -186,6 +199,7 @@ export const roleDefaults = defaultRolesSchema.parse({[PermissionTypes.FILE_SEARCH]: {},[PermissionTypes.FILE_CITATIONS]: {},[PermissionTypes.MCP_SERVERS]: {},+ [PermissionTypes.REMOTE_AGENTS]: {},},},});diff --git a/packages/data-provider/src/types.ts b/packages/data-provider/src/types.tsindex d9050a07f0..2190b2cfe1 100644--- a/packages/data-provider/src/types.ts+++ b/packages/data-provider/src/types.ts@@ -235,6 +235,33 @@ export type TUpdateUserKeyRequest = {expiresAt: string;};+export type TAgentApiKeyCreateRequest = {+ name: string;+ expiresAt?: string | null;+};++export type TAgentApiKeyCreateResponse = {+ id: string;+ name: string;+ key: string;+ keyPrefix: string;+ createdAt: string;+ expiresAt?: string;+};++export type TAgentApiKeyListItem = {+ id: string;+ name: string;+ keyPrefix: string;+ lastUsedAt?: string;+ expiresAt?: string;+ createdAt: string;+};++export type TAgentApiKeyListResponse = {+ keys: TAgentApiKeyListItem[];+};+export type TUpdateConversationRequest = {conversationId: string;title: string;diff --git a/packages/data-provider/src/types/mutations.ts b/packages/data-provider/src/types/mutations.tsindex 1a7211edfa..15f0cd2329 100644--- a/packages/data-provider/src/types/mutations.ts+++ b/packages/data-provider/src/types/mutations.ts@@ -313,6 +313,15 @@ export type UpdateMCPServersPermOptions = MutationOptions<types.TError | null | undefined>;+export type UpdateRemoteAgentsPermVars = UpdatePermVars<p.TRemoteAgentsPermissions>;++export type UpdateRemoteAgentsPermOptions = MutationOptions<+ UpdatePermResponse,+ UpdateRemoteAgentsPermVars,+ unknown,+ types.TError | null | undefined+>;+export type UpdateMarketplacePermVars = UpdatePermVars<p.TMarketplacePermissions>;export type UpdateMarketplacePermOptions = MutationOptions<diff --git a/packages/data-schemas/src/methods/accessRole.spec.ts b/packages/data-schemas/src/methods/accessRole.spec.tsindex b0f7ba70ef..6919e6c7df 100644--- a/packages/data-schemas/src/methods/accessRole.spec.ts+++ b/packages/data-schemas/src/methods/accessRole.spec.ts@@ -203,6 +203,9 @@ describe('AccessRole Model Tests', () => {AccessRoleIds.MCPSERVER_EDITOR,AccessRoleIds.MCPSERVER_OWNER,AccessRoleIds.MCPSERVER_VIEWER,+ AccessRoleIds.REMOTE_AGENT_EDITOR,+ AccessRoleIds.REMOTE_AGENT_OWNER,+ AccessRoleIds.REMOTE_AGENT_VIEWER,].sort(),);diff --git a/packages/data-schemas/src/methods/accessRole.ts b/packages/data-schemas/src/methods/accessRole.tsindex 0971c0f9e8..ab2cffbad8 100644--- a/packages/data-schemas/src/methods/accessRole.ts+++ b/packages/data-schemas/src/methods/accessRole.ts@@ -167,6 +167,27 @@ export function createAccessRoleMethods(mongoose: typeof import('mongoose')) {resourceType: ResourceType.MCPSERVER,permBits: RoleBits.OWNER,},+ {+ accessRoleId: AccessRoleIds.REMOTE_AGENT_VIEWER,+ name: 'com_ui_remote_agent_role_viewer',+ description: 'com_ui_remote_agent_role_viewer_desc',+ resourceType: ResourceType.REMOTE_AGENT,+ permBits: RoleBits.VIEWER,+ },+ {+ accessRoleId: AccessRoleIds.REMOTE_AGENT_EDITOR,+ name: 'com_ui_remote_agent_role_editor',+ description: 'com_ui_remote_agent_role_editor_desc',+ resourceType: ResourceType.REMOTE_AGENT,+ permBits: RoleBits.EDITOR,+ },+ {+ accessRoleId: AccessRoleIds.REMOTE_AGENT_OWNER,+ name: 'com_ui_remote_agent_role_owner',+ description: 'com_ui_remote_agent_role_owner_desc',+ resourceType: ResourceType.REMOTE_AGENT,+ permBits: RoleBits.OWNER,+ },];const result: Record<string, IAccessRole> = {};diff --git a/packages/data-schemas/src/methods/agentApiKey.ts b/packages/data-schemas/src/methods/agentApiKey.tsnew file mode 100644index 0000000000..3462f9ff84--- /dev/null+++ b/packages/data-schemas/src/methods/agentApiKey.ts@@ -0,0 +1,164 @@+import type { Types } from 'mongoose';+import type {+ AgentApiKeyCreateResult,+ AgentApiKeyCreateData,+ AgentApiKeyListItem,+ IAgentApiKey,+} from '~/types';+import { hashToken, getRandomValues } from '~/crypto';+import logger from '~/config/winston';++const API_KEY_PREFIX = 'sk-';+const API_KEY_LENGTH = 32;++export function createAgentApiKeyMethods(mongoose: typeof import('mongoose')) {+ async function generateApiKey(): Promise<{ key: string; keyHash: string; keyPrefix: string }> {+ const randomPart = await getRandomValues(API_KEY_LENGTH);+ const key = `${API_KEY_PREFIX}${randomPart}`;+ const keyHash = await hashToken(key);+ const keyPrefix = key.slice(0, 8);+ return { key, keyHash, keyPrefix };+ }++ async function createAgentApiKey(data: AgentApiKeyCreateData): Promise<AgentApiKeyCreateResult> {+ try {+ const AgentApiKey = mongoose.models.AgentApiKey;+ const { key, keyHash, keyPrefix } = await generateApiKey();++ const apiKeyDoc = await AgentApiKey.create({+ userId: data.userId,+ name: data.name,+ keyHash,+ keyPrefix,+ expiresAt: data.expiresAt || undefined,+ });++ return {+ id: apiKeyDoc._id.toString(),+ name: apiKeyDoc.name,+ keyPrefix,+ key,+ createdAt: apiKeyDoc.createdAt,+ expiresAt: apiKeyDoc.expiresAt,+ };+ } catch (error) {+ logger.error('[createAgentApiKey] Error creating API key:', error);+ throw error;+ }+ }++ async function validateAgentApiKey(+ apiKey: string,+ ): Promise<{ userId: Types.ObjectId; keyId: Types.ObjectId } | null> {+ try {+ const AgentApiKey = mongoose.models.AgentApiKey;+ const keyHash = await hashToken(apiKey);++ const keyDoc = (await AgentApiKey.findOne({ keyHash }).lean()) as IAgentApiKey | null;++ if (!keyDoc) {+ return null;+ }++ if (keyDoc.expiresAt && new Date(keyDoc.expiresAt) < new Date()) {+ return null;+ }++ await AgentApiKey.updateOne({ _id: keyDoc._id }, { $set: { lastUsedAt: new Date() } });++ return {+ userId: keyDoc.userId,+ keyId: keyDoc._id as Types.ObjectId,+ };+ } catch (error) {+ logger.error('[validateAgentApiKey] Error validating API key:', error);+ return null;+ }+ }++ async function listAgentApiKeys(userId: string | Types.ObjectId): Promise<AgentApiKeyListItem[]> {+ try {+ const AgentApiKey = mongoose.models.AgentApiKey;+ const keys = (await AgentApiKey.find({ userId })+ .sort({ createdAt: -1 })+ .lean()) as unknown as IAgentApiKey[];++ return keys.map((key) => ({+ id: (key._id as Types.ObjectId).toString(),+ name: key.name,+ keyPrefix: key.keyPrefix,+ lastUsedAt: key.lastUsedAt,+ expiresAt: key.expiresAt,+ createdAt: key.createdAt,+ }));+ } catch (error) {+ logger.error('[listAgentApiKeys] Error listing API keys:', error);+ throw error;+ }+ }++ async function deleteAgentApiKey(+ keyId: string | Types.ObjectId,+ userId: string | Types.ObjectId,+ ): Promise<boolean> {+ try {+ const AgentApiKey = mongoose.models.AgentApiKey;+ const result = await AgentApiKey.deleteOne({ _id: keyId, userId });+ return result.deletedCount > 0;+ } catch (error) {+ logger.error('[deleteAgentApiKey] Error deleting API key:', error);+ throw error;+ }+ }++ async function deleteAllAgentApiKeys(userId: string | Types.ObjectId): Promise<number> {+ try {+ const AgentApiKey = mongoose.models.AgentApiKey;+ const result = await AgentApiKey.deleteMany({ userId });+ return result.deletedCount;+ } catch (error) {+ logger.error('[deleteAllAgentApiKeys] Error deleting all API keys:', error);+ throw error;+ }+ }++ async function getAgentApiKeyById(+ keyId: string | Types.ObjectId,+ userId: string | Types.ObjectId,+ ): Promise<AgentApiKeyListItem | null> {+ try {+ const AgentApiKey = mongoose.models.AgentApiKey;+ const keyDoc = (await AgentApiKey.findOne({+ _id: keyId,+ userId,+ }).lean()) as IAgentApiKey | null;++ if (!keyDoc) {+ return null;+ }++ return {+ id: (keyDoc._id as Types.ObjectId).toString(),+ name: keyDoc.name,+ keyPrefix: keyDoc.keyPrefix,+ lastUsedAt: keyDoc.lastUsedAt,+ expiresAt: keyDoc.expiresAt,+ createdAt: keyDoc.createdAt,+ };+ } catch (error) {+ logger.error('[getAgentApiKeyById] Error getting API key:', error);+ throw error;+ }+ }++ return {+ createAgentApiKey,+ validateAgentApiKey,+ listAgentApiKeys,+ deleteAgentApiKey,+ deleteAllAgentApiKeys,+ getAgentApiKeyById,+ };+}++export type AgentApiKeyMethods = ReturnType<typeof createAgentApiKeyMethods>;diff --git a/packages/data-schemas/src/methods/index.ts b/packages/data-schemas/src/methods/index.tsindex b6f1be64e9..2f20b67fec 100644--- a/packages/data-schemas/src/methods/index.ts+++ b/packages/data-schemas/src/methods/index.ts@@ -10,6 +10,8 @@ import { createFileMethods, type FileMethods } from './file';import { createMemoryMethods, type MemoryMethods } from './memory';/* Agent Categories */import { createAgentCategoryMethods, type AgentCategoryMethods } from './agentCategory';+/* Agent API Keys */+import { createAgentApiKeyMethods, type AgentApiKeyMethods } from './agentApiKey';/* MCP Servers */import { createMCPServerMethods, type MCPServerMethods } from './mcpServer';/* Plugin Auth */@@ -28,6 +30,7 @@ export type AllMethods = UserMethods &FileMethods &MemoryMethods &AgentCategoryMethods &+ AgentApiKeyMethods &MCPServerMethods &UserGroupMethods &AclEntryMethods &@@ -49,6 +52,7 @@ export function createMethods(mongoose: typeof import('mongoose')): AllMethods {...createFileMethods(mongoose),...createMemoryMethods(mongoose),...createAgentCategoryMethods(mongoose),+ ...createAgentApiKeyMethods(mongoose),...createMCPServerMethods(mongoose),...createAccessRoleMethods(mongoose),...createUserGroupMethods(mongoose),@@ -67,6 +71,7 @@ export type {FileMethods,MemoryMethods,AgentCategoryMethods,+ AgentApiKeyMethods,MCPServerMethods,UserGroupMethods,AclEntryMethods,diff --git a/packages/data-schemas/src/models/agentApiKey.ts b/packages/data-schemas/src/models/agentApiKey.tsnew file mode 100644index 0000000000..70387a2cef--- /dev/null+++ b/packages/data-schemas/src/models/agentApiKey.ts@@ -0,0 +1,7 @@+import agentApiKeySchema, { IAgentApiKey } from '~/schema/agentApiKey';++export function createAgentApiKeyModel(mongoose: typeof import('mongoose')) {+ return (+ mongoose.models.AgentApiKey || mongoose.model<IAgentApiKey>('AgentApiKey', agentApiKeySchema)+ );+}diff --git a/packages/data-schemas/src/models/index.ts b/packages/data-schemas/src/models/index.tsindex 45516d5a7c..ca1a6259be 100644--- a/packages/data-schemas/src/models/index.ts+++ b/packages/data-schemas/src/models/index.ts@@ -5,6 +5,7 @@ import { createBalanceModel } from './balance';import { createConversationModel } from './convo';import { createMessageModel } from './message';import { createAgentModel } from './agent';+import { createAgentApiKeyModel } from './agentApiKey';import { createAgentCategoryModel } from './agentCategory';import { createMCPServerModel } from './mcpServer';import { createRoleModel } from './role';@@ -39,6 +40,7 @@ export function createModels(mongoose: typeof import('mongoose')) {Conversation: createConversationModel(mongoose),Message: createMessageModel(mongoose),Agent: createAgentModel(mongoose),+ AgentApiKey: createAgentApiKeyModel(mongoose),AgentCategory: createAgentCategoryModel(mongoose),MCPServer: createMCPServerModel(mongoose),Role: createRoleModel(mongoose),diff --git a/packages/data-schemas/src/schema/accessRole.ts b/packages/data-schemas/src/schema/accessRole.tsindex 082c28a5f0..52f9e796c0 100644--- a/packages/data-schemas/src/schema/accessRole.ts+++ b/packages/data-schemas/src/schema/accessRole.ts@@ -16,7 +16,7 @@ const accessRoleSchema = new Schema<IAccessRole>(description: String,resourceType: {type: String,- enum: ['agent', 'project', 'file', 'promptGroup', 'mcpServer'],+ enum: ['agent', 'project', 'file', 'promptGroup', 'mcpServer', 'remoteAgent'],required: true,default: 'agent',},diff --git a/packages/data-schemas/src/schema/agentApiKey.ts b/packages/data-schemas/src/schema/agentApiKey.tsnew file mode 100644index 0000000000..d7037f857f--- /dev/null+++ b/packages/data-schemas/src/schema/agentApiKey.ts@@ -0,0 +1,59 @@+import mongoose, { Schema, Document, Types } from 'mongoose';++export interface IAgentApiKey extends Document {+ userId: Types.ObjectId;+ name: string;+ keyHash: string;+ keyPrefix: string;+ lastUsedAt?: Date;+ expiresAt?: Date;+ createdAt: Date;+ updatedAt: Date;+}++const agentApiKeySchema: Schema<IAgentApiKey> = new Schema(+ {+ userId: {+ type: mongoose.Schema.Types.ObjectId,+ ref: 'User',+ required: true,+ index: true,+ },+ name: {+ type: String,+ required: true,+ trim: true,+ maxlength: 100,+ },+ keyHash: {+ type: String,+ required: true,+ select: false,+ index: true,+ },+ keyPrefix: {+ type: String,+ required: true,+ index: true,+ },+ lastUsedAt: {+ type: Date,+ },+ expiresAt: {+ type: Date,+ },+ },+ { timestamps: true },+);++agentApiKeySchema.index({ userId: 1, name: 1 });++/**+ * TTL index for automatic cleanup of expired keys.+ * MongoDB deletes documents when expiresAt passes (expireAfterSeconds: 0 means immediate).+ * Note: Expired keys are permanently removed, not soft-deleted.+ * If audit trails are needed, remove this index and check expiration programmatically.+ */+agentApiKeySchema.index({ expiresAt: 1 }, { expireAfterSeconds: 0 });++export default agentApiKeySchema;diff --git a/packages/data-schemas/src/schema/index.ts b/packages/data-schemas/src/schema/index.tsindex 2d94db5301..454780b8bf 100644--- a/packages/data-schemas/src/schema/index.ts+++ b/packages/data-schemas/src/schema/index.ts@@ -1,5 +1,6 @@export { default as actionSchema } from './action';export { default as agentSchema } from './agent';+export { default as agentApiKeySchema } from './agentApiKey';export { default as agentCategorySchema } from './agentCategory';export { default as assistantSchema } from './assistant';export { default as balanceSchema } from './balance';diff --git a/packages/data-schemas/src/schema/role.ts b/packages/data-schemas/src/schema/role.tsindex 3ac0a7f8a2..e4821ba405 100644--- a/packages/data-schemas/src/schema/role.ts+++ b/packages/data-schemas/src/schema/role.ts@@ -61,6 +61,12 @@ const rolePermissionsSchema = new Schema([Permissions.SHARE]: { type: Boolean },[Permissions.SHARE_PUBLIC]: { type: Boolean },},+ [PermissionTypes.REMOTE_AGENTS]: {+ [Permissions.USE]: { type: Boolean },+ [Permissions.CREATE]: { type: Boolean },+ [Permissions.SHARE]: { type: Boolean },+ [Permissions.SHARE_PUBLIC]: { type: Boolean },+ },},{ _id: false },);diff --git a/packages/data-schemas/src/types/agentApiKey.ts b/packages/data-schemas/src/types/agentApiKey.tsnew file mode 100644index 0000000000..968937a717--- /dev/null+++ b/packages/data-schemas/src/types/agentApiKey.ts@@ -0,0 +1,46 @@+import { Document, Types } from 'mongoose';++export interface IAgentApiKey extends Document {+ userId: Types.ObjectId;+ name: string;+ keyHash: string;+ keyPrefix: string;+ lastUsedAt?: Date;+ expiresAt?: Date;+ createdAt: Date;+ updatedAt: Date;+}++export interface AgentApiKeyCreateData {+ userId: Types.ObjectId | string;+ name: string;+ expiresAt?: Date | null;+}++export interface AgentApiKeyCreateResult {+ id: string;+ name: string;+ keyPrefix: string;+ key: string;+ createdAt: Date;+ expiresAt?: Date;+}++export interface AgentApiKeyListItem {+ id: string;+ name: string;+ keyPrefix: string;+ lastUsedAt?: Date;+ expiresAt?: Date;+ createdAt: Date;+}++export interface AgentApiKeyQuery {+ userId?: Types.ObjectId | string;+ keyPrefix?: string;+ id?: string;+}++export interface AgentApiKeyDeleteResult {+ deletedCount?: number;+}diff --git a/packages/data-schemas/src/types/index.ts b/packages/data-schemas/src/types/index.tsindex 828cdf9c8f..38f9f22b50 100644--- a/packages/data-schemas/src/types/index.ts+++ b/packages/data-schemas/src/types/index.ts@@ -10,6 +10,7 @@ export * from './balance';export * from './banner';export * from './message';export * from './agent';+export * from './agentApiKey';export * from './agentCategory';export * from './role';export * from './action';diff --git a/packages/data-schemas/src/types/role.ts b/packages/data-schemas/src/types/role.tsindex fc6340da2c..e70e29204a 100644--- a/packages/data-schemas/src/types/role.ts+++ b/packages/data-schemas/src/types/role.ts@@ -59,6 +59,12 @@ export interface IRole extends Document {[Permissions.SHARE]?: boolean;[Permissions.SHARE_PUBLIC]?: boolean;};+ [PermissionTypes.REMOTE_AGENTS]?: {+ [Permissions.USE]?: boolean;+ [Permissions.CREATE]?: boolean;+ [Permissions.SHARE]?: boolean;+ [Permissions.SHARE_PUBLIC]?: boolean;+ };};}