🔐 feat: Granular Role-based Permissions + Entra ID Group Discovery (#7804)

WIP: pre-granular-permissions commit

feat: Add category and support contact fields to Agent schema and UI components

Revert "feat: Add category and support contact fields to Agent schema and UI components"

This reverts commit c43a52b4c9.

Fix: Update import for renderHook in useAgentCategories.spec.tsx

fix: Update icon rendering in AgentCategoryDisplay tests to use empty spans

refactor: Improve category synchronization logic and clean up AgentConfig component

refactor: Remove unused UI flow translations from translation.json

feat: agent marketplace features

🔐 feat: Granular Role-based Permissions + Entra ID Group Discovery (#7804)

.env.example

@@ -521,6 +521,21 @@ SAML_IMAGE_URL=
 # SAML_USE_AUTHN_RESPONSE_SIGNED=
 
 
+#===============================================#
+# Microsoft Graph API / Entra ID Integration  #
+#===============================================#
+
+# Enable Entra ID people search integration in permissions/sharing system
+# When enabled, the people picker will search both local database and Entra ID
+USE_ENTRA_ID_FOR_PEOPLE_SEARCH=false
+
+# When enabled, entra id groups owners will be considered as members of the group
+ENTRA_ID_INCLUDE_OWNERS_AS_MEMBERS=false
+
+# Microsoft Graph API scopes needed for people/group search
+# Default scopes provide access to user profiles and group memberships
+OPENID_GRAPH_SCOPES=User.Read,People.Read,GroupMember.Read.All
+
 # LDAP
 LDAP_URL=
 LDAP_BIND_DN=

.vscode/launch.json

@@ -8,7 +8,8 @@
       "skipFiles": ["<node_internals>/**"],
       "program": "${workspaceFolder}/api/server/index.js",
       "env": {
-        "NODE_ENV": "production"
+        "NODE_ENV": "production",
+        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
       },
       "console": "integratedTerminal",
       "envFile": "${workspaceFolder}/.env"

api/models/Agent.js

@@ -4,7 +4,8 @@ const { logger } = require('@librechat/data-schemas');
 const { SystemRoles, Tools, actionDelimiter } = require('librechat-data-provider');
 const { GLOBAL_PROJECT_NAME, EPHEMERAL_AGENT_ID, mcp_delimiter } =
   require('librechat-data-provider').Constants;
-const { CONFIG_STORE, STARTUP_CONFIG } = require('librechat-data-provider').CacheKeys;
+// Default category value for new agents
+const AgentCategory = require('./AgentCategory');
 const {
   getProjectByName,
   addAgentIdsToProject,
@@ -12,7 +13,82 @@ const {
   removeAgentFromAllProjects,
 } = require('./Project');
 const { getCachedTools } = require('~/server/services/Config');
-const getLogStores = require('~/cache/getLogStores');
+
+// Category values are now imported from shared constants
+
+// Add category field to the Agent schema if it doesn't already exist
+if (!agentSchema.paths.category) {
+  agentSchema.add({
+    category: {
+      type: String,
+      trim: true,
+      validate: {
+        validator: async function (value) {
+          if (!value) return true; // Allow empty values (will use default)
+
+          // Check if category exists in database
+          const validCategories = await AgentCategory.getValidCategoryValues();
+          return validCategories.includes(value);
+        },
+        message: function (props) {
+          return `"${props.value}" is not a valid agent category. Please check available categories.`;
+        },
+      },
+      index: true,
+      default: 'general',
+    },
+  });
+}
+
+// Add support_contact field to the Agent schema if it doesn't already exist
+if (!agentSchema.paths.support_contact) {
+  agentSchema.add({
+    support_contact: {
+      type: Object,
+      default: {},
+      name: {
+        type: String,
+        minlength: [3, 'Support contact name must be at least 3 characters.'],
+        trim: true,
+      },
+      email: {
+        type: String,
+        match: [
+          /^\w+([.-]?\w+)*@\w+([.-]?\w+)*(\.\w{2,3})+$/,
+          'Please enter a valid email address.',
+        ],
+        trim: true,
+      },
+    },
+  });
+}
+
+// Add promotion field to the Agent schema if it doesn't already exist
+if (!agentSchema.paths.is_promoted) {
+  agentSchema.add({
+    is_promoted: {
+      type: Boolean,
+      default: false,
+      index: true, // Index for efficient promoted agent queries
+    },
+  });
+}
+
+// Add additional indexes for marketplace functionality
+agentSchema.index({ projectIds: 1, is_promoted: 1, updatedAt: -1 }); // Optimize promoted agents query
+agentSchema.index({ category: 1, projectIds: 1, updatedAt: -1 }); // Optimize category filtering
+agentSchema.index({ projectIds: 1, category: 1 }); // Optimize aggregation pipeline
+
+// Text indexes for search functionality
+agentSchema.index(
+  { name: 'text', description: 'text' },
+  {
+    weights: {
+      name: 3, // Name matches are 3x more important than description matches
+      description: 1,
+    },
+  },
+);
 const { getActions } = require('./Action');
 const { Agent } = require('~/db/models');
 
@@ -23,7 +99,7 @@ const { Agent } = require('~/db/models');
  * @throws {Error} If the agent creation fails.
  */
 const createAgent = async (agentData) => {
-  const { author, ...versionData } = agentData;
+  const { author: _author, ...versionData } = agentData;
   const timestamp = new Date();
   const initialAgentData = {
     ...agentData,
@@ -34,6 +110,7 @@ const createAgent = async (agentData) => {
         updatedAt: timestamp,
       },
     ],
+    category: agentData.category || 'general',
   };
   return (await Agent.create(initialAgentData)).toObject();
 };
@@ -131,29 +208,7 @@ const loadAgent = async ({ req, agent_id, endpoint, model_parameters }) => {
   }
 
   agent.version = agent.versions ? agent.versions.length : 0;
-
-  if (agent.author.toString() === req.user.id) {
   return agent;
-  }
-
-  if (!agent.projectIds) {
-    return null;
-  }
-
-  const cache = getLogStores(CONFIG_STORE);
-  /** @type {TStartupConfig} */
-  const cachedStartupConfig = await cache.get(STARTUP_CONFIG);
-  let { instanceProjectId } = cachedStartupConfig ?? {};
-  if (!instanceProjectId) {
-    instanceProjectId = (await getProjectByName(GLOBAL_PROJECT_NAME, '_id'))._id.toString();
-  }
-
-  for (const projectObjectId of agent.projectIds) {
-    const projectId = projectObjectId.toString();
-    if (projectId === instanceProjectId) {
-      return agent;
-    }
-  }
 };
 
 /**
@@ -183,7 +238,7 @@ const isDuplicateVersion = (updateData, currentData, versions, actionsHash = nul
     'actionsHash', // Exclude actionsHash from direct comparison
   ];
 
-  const { $push, $pull, $addToSet, ...directUpdates } = updateData;
+  const { $push: _$push, $pull: _$pull, $addToSet: _$addToSet, ...directUpdates } = updateData;
 
   if (Object.keys(directUpdates).length === 0 && !actionsHash) {
     return null;
@@ -278,7 +333,14 @@ const updateAgent = async (searchParameter, updateData, options = {}) => {
 
   const currentAgent = await Agent.findOne(searchParameter);
   if (currentAgent) {
-    const { __v, _id, id, versions, author, ...versionData } = currentAgent.toObject();
+    const {
+      __v,
+      _id,
+      id: __id,
+      versions,
+      author: _author,
+      ...versionData
+    } = currentAgent.toObject();
     const { $push, $pull, $addToSet, ...directUpdates } = updateData;
 
     let actionsHash = null;
@@ -462,8 +524,110 @@ const deleteAgent = async (searchParameter) => {
   return agent;
 };
 
+/**
+ * Get agents by accessible IDs with optional cursor-based pagination.
+ * @param {Object} params - The parameters for getting accessible agents.
+ * @param {Array} [params.accessibleIds] - Array of agent ObjectIds the user has ACL access to.
+ * @param {Object} [params.otherParams] - Additional query parameters (including author filter).
+ * @param {number} [params.limit] - Number of agents to return (max 100). If not provided, returns all agents.
+ * @param {string} [params.after] - Cursor for pagination - get agents after this cursor. // base64 encoded JSON string with updatedAt and _id.
+ * @returns {Promise<Object>} A promise that resolves to an object containing the agents data and pagination info.
+ */
+const getListAgentsByAccess = async ({
+  accessibleIds = [],
+  otherParams = {},
+  limit = null,
+  after = null,
+}) => {
+  const isPaginated = limit !== null && limit !== undefined;
+  const normalizedLimit = isPaginated ? Math.min(Math.max(1, parseInt(limit) || 20), 100) : null;
+
+  // Build base query combining ACL accessible agents with other filters
+  const baseQuery = { ...otherParams };
+
+  if (accessibleIds.length > 0) {
+    baseQuery._id = { $in: accessibleIds };
+  }
+
+  // Add cursor condition
+  if (after) {
+    try {
+      const cursor = JSON.parse(Buffer.from(after, 'base64').toString('utf8'));
+      const { updatedAt, _id } = cursor;
+
+      const cursorCondition = {
+        $or: [
+          { updatedAt: { $lt: new Date(updatedAt) } },
+          { updatedAt: new Date(updatedAt), _id: { $gt: mongoose.Types.ObjectId(_id) } },
+        ],
+      };
+
+      // Merge cursor condition with base query
+      if (Object.keys(baseQuery).length > 0) {
+        baseQuery.$and = [{ ...baseQuery }, cursorCondition];
+        // Remove the original conditions from baseQuery to avoid duplication
+        Object.keys(baseQuery).forEach((key) => {
+          if (key !== '$and') delete baseQuery[key];
+        });
+      } else {
+        Object.assign(baseQuery, cursorCondition);
+      }
+    } catch (error) {
+      logger.warn('Invalid cursor:', error.message);
+    }
+  }
+
+  let query = Agent.find(baseQuery, {
+    id: 1,
+    _id: 1,
+    name: 1,
+    avatar: 1,
+    author: 1,
+    projectIds: 1,
+    description: 1,
+    updatedAt: 1,
+  }).sort({ updatedAt: -1, _id: 1 });
+
+  // Only apply limit if pagination is requested
+  if (isPaginated) {
+    query = query.limit(normalizedLimit + 1);
+  }
+
+  const agents = await query.lean();
+
+  const hasMore = isPaginated ? agents.length > normalizedLimit : false;
+  const data = (isPaginated ? agents.slice(0, normalizedLimit) : agents).map((agent) => {
+    if (agent.author) {
+      agent.author = agent.author.toString();
+    }
+    return agent;
+  });
+
+  // Generate next cursor only if paginated
+  let nextCursor = null;
+  if (isPaginated && hasMore && data.length > 0) {
+    const lastAgent = agents[normalizedLimit - 1];
+    nextCursor = Buffer.from(
+      JSON.stringify({
+        updatedAt: lastAgent.updatedAt.toISOString(),
+        _id: lastAgent._id.toString(),
+      }),
+    ).toString('base64');
+  }
+
+  return {
+    object: 'list',
+    data,
+    first_id: data.length > 0 ? data[0].id : null,
+    last_id: data.length > 0 ? data[data.length - 1].id : null,
+    has_more: hasMore,
+    after: nextCursor,
+  };
+};
+
 /**
  * Get all agents.
+ * @deprecated Use getListAgentsByAccess for ACL-aware agent listing
  * @param {Object} searchParameter - The search parameters to find matching agents.
  * @param {string} searchParameter.author - The user ID of the agent's author.
  * @returns {Promise<Object>} A promise that resolves to an object containing the agents data and pagination info.
@@ -482,13 +646,15 @@ const getListAgents = async (searchParameter) => {
   const agents = (
     await Agent.find(query, {
       id: 1,
-      _id: 0,
+      _id: 1,
       name: 1,
       avatar: 1,
       author: 1,
       projectIds: 1,
       description: 1,
+      // @deprecated - isCollaborative replaced by ACL permissions
       isCollaborative: 1,
+      category: 1,
     }).lean()
   ).map((agent) => {
     if (agent.author?.toString() !== author) {
@@ -671,6 +837,7 @@ module.exports = {
   revertAgentVersion,
   updateAgentProjects,
   addAgentResourceFile,
+  getListAgentsByAccess,
   removeAgentResourceFiles,
   generateActionMetadataHash,
 };

api/models/Agent.spec.js

@@ -1612,7 +1612,7 @@ describe('models/Agent', () => {
       expect(result.version).toBe(1);
     });
 
-    test('should return null when user is not author and agent has no projectIds', async () => {
+    test('should return agent even when user is not author (permissions checked at route level)', async () => {
       const authorId = new mongoose.Types.ObjectId();
       const userId = new mongoose.Types.ObjectId();
       const agentId = `agent_${uuidv4()}`;
@@ -1633,7 +1633,11 @@ describe('models/Agent', () => {
         model_parameters: { model: 'gpt-4' },
       });
 
-      expect(result).toBeFalsy();
+      // With the new permission system, loadAgent returns the agent regardless of permissions
+      // Permission checks are handled at the route level via middleware
+      expect(result).toBeTruthy();
+      expect(result.id).toBe(agentId);
+      expect(result.name).toBe('Test Agent');
     });
 
     test('should handle ephemeral agent with no MCP servers', async () => {
@@ -1741,7 +1745,7 @@ describe('models/Agent', () => {
         }
       });
 
-      test('should handle loadAgent with agent from different project', async () => {
+      test('should return agent from different project (permissions checked at route level)', async () => {
         const authorId = new mongoose.Types.ObjectId();
         const userId = new mongoose.Types.ObjectId();
         const agentId = `agent_${uuidv4()}`;
@@ -1764,7 +1768,11 @@ describe('models/Agent', () => {
           model_parameters: { model: 'gpt-4' },
         });
 
-        expect(result).toBeFalsy();
+        // With the new permission system, loadAgent returns the agent regardless of permissions
+        // Permission checks are handled at the route level via middleware
+        expect(result).toBeTruthy();
+        expect(result.id).toBe(agentId);
+        expect(result.name).toBe('Project Agent');
       });
     });
   });

api/models/AgentCategory.js

@@ -0,0 +1,125 @@
+const mongoose = require('mongoose');
+
+/**
+ * AgentCategory Schema - Dynamic agent category management
+ * Focused implementation for core features only
+ */
+const agentCategorySchema = new mongoose.Schema(
+  {
+    // Unique identifier for the category (e.g., 'general', 'hr', 'finance')
+    value: {
+      type: String,
+      required: true,
+      unique: true,
+      trim: true,
+      lowercase: true,
+      index: true,
+    },
+    
+    // Display label for the category
+    label: {
+      type: String,
+      required: true,
+      trim: true,
+    },
+    
+    // Description of the category
+    description: {
+      type: String,
+      trim: true,
+      default: '',
+    },
+    
+    // Display order for sorting categories
+    order: {
+      type: Number,
+      default: 0,
+      index: true,
+    },
+    
+    // Whether the category is active and should be displayed
+    isActive: {
+      type: Boolean,
+      default: true,
+      index: true,
+    },
+  },
+  {
+    timestamps: true,
+  }
+);
+
+// Indexes for performance
+agentCategorySchema.index({ isActive: 1, order: 1 });
+
+/**
+ * Get all active categories sorted by order
+ * @returns {Promise<AgentCategory[]>} Array of active categories
+ */
+agentCategorySchema.statics.getActiveCategories = function() {
+  return this.find({ isActive: true })
+    .sort({ order: 1, label: 1 })
+    .lean();
+};
+
+/**
+ * Get categories with agent counts
+ * @returns {Promise<AgentCategory[]>} Categories with agent counts
+ */
+agentCategorySchema.statics.getCategoriesWithCounts = async function() {
+  const Agent = mongoose.model('agent');
+  
+  // Aggregate to get agent counts per category
+  const categoryCounts = await Agent.aggregate([
+    { $match: { category: { $exists: true, $ne: null } } },
+    { $group: { _id: '$category', count: { $sum: 1 } } },
+  ]);
+  
+  // Create a map for quick lookup
+  const countMap = new Map(categoryCounts.map(c => [c._id, c.count]));
+  
+  // Get all active categories and add counts
+  const categories = await this.getActiveCategories();
+  
+  return categories.map(category => ({
+    ...category,
+    agentCount: countMap.get(category.value) || 0,
+  }));
+};
+
+/**
+ * Get valid category values for Agent model validation
+ * @returns {Promise<string[]>} Array of valid category values
+ */
+agentCategorySchema.statics.getValidCategoryValues = function() {
+  return this.find({ isActive: true })
+    .distinct('value')
+    .lean();
+};
+
+/**
+ * Seed initial categories from existing constants
+ */
+agentCategorySchema.statics.seedCategories = async function(categories) {
+  const operations = categories.map((category, index) => ({
+    updateOne: {
+      filter: { value: category.value },
+      update: {
+        $setOnInsert: {
+          value: category.value,
+          label: category.label || category.value,
+          description: category.description || '',
+          order: category.order || index,
+          isActive: true,
+        },
+      },
+      upsert: true,
+    },
+  }));
+  
+  return this.bulkWrite(operations);
+};
+
+const AgentCategory = mongoose.model('AgentCategory', agentCategorySchema);
+
+module.exports = AgentCategory;

api/package.json

@@ -54,6 +54,7 @@
     "@librechat/data-schemas": "*",
     "@modelcontextprotocol/sdk": "^1.17.1",
     "@node-saml/passport-saml": "^5.1.0",
+    "@microsoft/microsoft-graph-client": "^3.0.7",
     "@waylaidwanderer/fetch-event-source": "^3.0.1",
     "axios": "^1.8.2",
     "bcryptjs": "^2.4.3",

api/server/controllers/PermissionsController.js

@@ -0,0 +1,437 @@
+/**
+ * @import { TUpdateResourcePermissionsRequest, TUpdateResourcePermissionsResponse } from 'librechat-data-provider'
+ */
+
+const mongoose = require('mongoose');
+const { logger } = require('@librechat/data-schemas');
+const {
+  getAvailableRoles,
+  ensurePrincipalExists,
+  getEffectivePermissions,
+  ensureGroupPrincipalExists,
+  bulkUpdateResourcePermissions,
+} = require('~/server/services/PermissionService');
+const { AclEntry } = require('~/db/models');
+const {
+  searchPrincipals: searchLocalPrincipals,
+  sortPrincipalsByRelevance,
+  calculateRelevanceScore,
+} = require('~/models');
+const {
+  searchEntraIdPrincipals,
+  entraIdPrincipalFeatureEnabled,
+} = require('~/server/services/GraphApiService');
+
+/**
+ * Generic controller for resource permission endpoints
+ * Delegates validation and logic to PermissionService
+ */
+
+/**
+ * Bulk update permissions for a resource (grant, update, remove)
+ * @route PUT /api/{resourceType}/{resourceId}/permissions
+ * @param {Object} req - Express request object
+ * @param {Object} req.params - Route parameters
+ * @param {string} req.params.resourceType - Resource type (e.g., 'agent')
+ * @param {string} req.params.resourceId - Resource ID
+ * @param {TUpdateResourcePermissionsRequest} req.body - Request body
+ * @param {Object} res - Express response object
+ * @returns {Promise<TUpdateResourcePermissionsResponse>} Updated permissions response
+ */
+const updateResourcePermissions = async (req, res) => {
+  try {
+    const { resourceType, resourceId } = req.params;
+    /** @type {TUpdateResourcePermissionsRequest} */
+    const { updated, removed, public: isPublic, publicAccessRoleId } = req.body;
+    const { id: userId } = req.user;
+
+    // Prepare principals for the service call
+    const updatedPrincipals = [];
+    const revokedPrincipals = [];
+
+    // Add updated principals
+    if (updated && Array.isArray(updated)) {
+      updatedPrincipals.push(...updated);
+    }
+
+    // Add public permission if enabled
+    if (isPublic && publicAccessRoleId) {
+      updatedPrincipals.push({
+        type: 'public',
+        id: null,
+        accessRoleId: publicAccessRoleId,
+      });
+    }
+
+    // Prepare authentication context for enhanced group member fetching
+    const useEntraId = entraIdPrincipalFeatureEnabled(req.user);
+    const authHeader = req.headers.authorization;
+    const accessToken =
+      authHeader && authHeader.startsWith('Bearer ') ? authHeader.substring(7) : null;
+    const authContext =
+      useEntraId && accessToken
+        ? {
+            accessToken,
+            sub: req.user.openidId,
+          }
+        : null;
+
+    // Ensure updated principals exist in the database before processing permissions
+    const validatedPrincipals = [];
+    for (const principal of updatedPrincipals) {
+      try {
+        let principalId;
+
+        if (principal.type === 'public') {
+          principalId = null; // Public principals don't need database records
+        } else if (principal.type === 'user') {
+          principalId = await ensurePrincipalExists(principal);
+        } else if (principal.type === 'group') {
+          // Pass authContext to enable member fetching for Entra ID groups when available
+          principalId = await ensureGroupPrincipalExists(principal, authContext);
+        } else {
+          logger.error(`Unsupported principal type: ${principal.type}`);
+          continue; // Skip invalid principal types
+        }
+
+        // Update the principal with the validated ID for ACL operations
+        validatedPrincipals.push({
+          ...principal,
+          id: principalId,
+        });
+      } catch (error) {
+        logger.error('Error ensuring principal exists:', {
+          principal: {
+            type: principal.type,
+            id: principal.id,
+            name: principal.name,
+            source: principal.source,
+          },
+          error: error.message,
+        });
+        // Continue with other principals instead of failing the entire operation
+        continue;
+      }
+    }
+
+    // Add removed principals
+    if (removed && Array.isArray(removed)) {
+      revokedPrincipals.push(...removed);
+    }
+
+    // If public is disabled, add public to revoked list
+    if (!isPublic) {
+      revokedPrincipals.push({
+        type: 'public',
+        id: null,
+      });
+    }
+
+    const results = await bulkUpdateResourcePermissions({
+      resourceType,
+      resourceId,
+      updatedPrincipals: validatedPrincipals,
+      revokedPrincipals,
+      grantedBy: userId,
+    });
+
+    /** @type {TUpdateResourcePermissionsResponse} */
+    const response = {
+      message: 'Permissions updated successfully',
+      results: {
+        principals: results.granted,
+        public: isPublic || false,
+        publicAccessRoleId: isPublic ? publicAccessRoleId : undefined,
+      },
+    };
+
+    res.status(200).json(response);
+  } catch (error) {
+    logger.error('Error updating resource permissions:', error);
+    res.status(400).json({
+      error: 'Failed to update permissions',
+      details: error.message,
+    });
+  }
+};
+
+/**
+ * Get principals with their permission roles for a resource (UI-friendly format)
+ * Uses efficient aggregation pipeline to join User/Group data in single query
+ * @route GET /api/permissions/{resourceType}/{resourceId}
+ */
+const getResourcePermissions = async (req, res) => {
+  try {
+    const { resourceType, resourceId } = req.params;
+
+    // Use aggregation pipeline for efficient single-query data retrieval
+    const results = await AclEntry.aggregate([
+      // Match ACL entries for this resource
+      {
+        $match: {
+          resourceType,
+          resourceId: mongoose.Types.ObjectId.isValid(resourceId)
+            ? mongoose.Types.ObjectId.createFromHexString(resourceId)
+            : resourceId,
+        },
+      },
+      // Lookup AccessRole information
+      {
+        $lookup: {
+          from: 'accessroles',
+          localField: 'roleId',
+          foreignField: '_id',
+          as: 'role',
+        },
+      },
+      // Lookup User information (for user principals)
+      {
+        $lookup: {
+          from: 'users',
+          localField: 'principalId',
+          foreignField: '_id',
+          as: 'userInfo',
+        },
+      },
+      // Lookup Group information (for group principals)
+      {
+        $lookup: {
+          from: 'groups',
+          localField: 'principalId',
+          foreignField: '_id',
+          as: 'groupInfo',
+        },
+      },
+      // Project final structure
+      {
+        $project: {
+          principalType: 1,
+          principalId: 1,
+          accessRoleId: { $arrayElemAt: ['$role.accessRoleId', 0] },
+          userInfo: { $arrayElemAt: ['$userInfo', 0] },
+          groupInfo: { $arrayElemAt: ['$groupInfo', 0] },
+        },
+      },
+    ]);
+
+    const principals = [];
+    let publicPermission = null;
+
+    // Process aggregation results
+    for (const result of results) {
+      if (result.principalType === 'public') {
+        publicPermission = {
+          public: true,
+          publicAccessRoleId: result.accessRoleId,
+        };
+      } else if (result.principalType === 'user' && result.userInfo) {
+        principals.push({
+          type: 'user',
+          id: result.userInfo._id.toString(),
+          name: result.userInfo.name || result.userInfo.username,
+          email: result.userInfo.email,
+          avatar: result.userInfo.avatar,
+          source: !result.userInfo._id ? 'entra' : 'local',
+          idOnTheSource: result.userInfo.idOnTheSource || result.userInfo._id.toString(),
+          accessRoleId: result.accessRoleId,
+        });
+      } else if (result.principalType === 'group' && result.groupInfo) {
+        principals.push({
+          type: 'group',
+          id: result.groupInfo._id.toString(),
+          name: result.groupInfo.name,
+          email: result.groupInfo.email,
+          description: result.groupInfo.description,
+          avatar: result.groupInfo.avatar,
+          source: result.groupInfo.source || 'local',
+          idOnTheSource: result.groupInfo.idOnTheSource || result.groupInfo._id.toString(),
+          accessRoleId: result.accessRoleId,
+        });
+      }
+    }
+
+    // Return response in format expected by frontend
+    const response = {
+      resourceType,
+      resourceId,
+      principals,
+      public: publicPermission?.public || false,
+      ...(publicPermission?.publicAccessRoleId && {
+        publicAccessRoleId: publicPermission.publicAccessRoleId,
+      }),
+    };
+
+    res.status(200).json(response);
+  } catch (error) {
+    logger.error('Error getting resource permissions principals:', error);
+    res.status(500).json({
+      error: 'Failed to get permissions principals',
+      details: error.message,
+    });
+  }
+};
+
+/**
+ * Get available roles for a resource type
+ * @route GET /api/{resourceType}/roles
+ */
+const getResourceRoles = async (req, res) => {
+  try {
+    const { resourceType } = req.params;
+
+    const roles = await getAvailableRoles({ resourceType });
+
+    res.status(200).json(
+      roles.map((role) => ({
+        accessRoleId: role.accessRoleId,
+        name: role.name,
+        description: role.description,
+        permBits: role.permBits,
+      })),
+    );
+  } catch (error) {
+    logger.error('Error getting resource roles:', error);
+    res.status(500).json({
+      error: 'Failed to get roles',
+      details: error.message,
+    });
+  }
+};
+
+/**
+ * Get user's effective permission bitmask for a resource
+ * @route GET /api/{resourceType}/{resourceId}/effective
+ */
+const getUserEffectivePermissions = async (req, res) => {
+  try {
+    const { resourceType, resourceId } = req.params;
+    const { id: userId } = req.user;
+
+    const permissionBits = await getEffectivePermissions({
+      userId,
+      resourceType,
+      resourceId,
+    });
+
+    res.status(200).json({
+      permissionBits,
+    });
+  } catch (error) {
+    logger.error('Error getting user effective permissions:', error);
+    res.status(500).json({
+      error: 'Failed to get effective permissions',
+      details: error.message,
+    });
+  }
+};
+
+/**
+ * Search for users and groups to grant permissions
+ * Supports hybrid local database + Entra ID search when configured
+ * @route GET /api/permissions/search-principals
+ */
+const searchPrincipals = async (req, res) => {
+  try {
+    const { q: query, limit = 20, type } = req.query;
+
+    if (!query || query.trim().length === 0) {
+      return res.status(400).json({
+        error: 'Query parameter "q" is required and must not be empty',
+      });
+    }
+
+    if (query.trim().length < 2) {
+      return res.status(400).json({
+        error: 'Query must be at least 2 characters long',
+      });
+    }
+
+    const searchLimit = Math.min(Math.max(1, parseInt(limit) || 10), 50);
+    const typeFilter = ['user', 'group'].includes(type) ? type : null;
+
+    const localResults = await searchLocalPrincipals(query.trim(), searchLimit, typeFilter);
+    let allPrincipals = [...localResults];
+
+    const useEntraId = entraIdPrincipalFeatureEnabled(req.user);
+
+    if (useEntraId && localResults.length < searchLimit) {
+      try {
+        const graphTypeMap = {
+          user: 'users',
+          group: 'groups',
+          null: 'all',
+        };
+
+        const authHeader = req.headers.authorization;
+        const accessToken =
+          authHeader && authHeader.startsWith('Bearer ') ? authHeader.substring(7) : null;
+
+        if (accessToken) {
+          const graphResults = await searchEntraIdPrincipals(
+            accessToken,
+            req.user.openidId,
+            query.trim(),
+            graphTypeMap[typeFilter],
+            searchLimit - localResults.length,
+          );
+
+          const localEmails = new Set(
+            localResults.map((p) => p.email?.toLowerCase()).filter(Boolean),
+          );
+          const localGroupSourceIds = new Set(
+            localResults.map((p) => p.idOnTheSource).filter(Boolean),
+          );
+
+          for (const principal of graphResults) {
+            const isDuplicateByEmail =
+              principal.email && localEmails.has(principal.email.toLowerCase());
+            const isDuplicateBySourceId =
+              principal.idOnTheSource && localGroupSourceIds.has(principal.idOnTheSource);
+
+            if (!isDuplicateByEmail && !isDuplicateBySourceId) {
+              allPrincipals.push(principal);
+            }
+          }
+        }
+      } catch (graphError) {
+        logger.warn('Graph API search failed, falling back to local results:', graphError.message);
+      }
+    }
+    const scoredResults = allPrincipals.map((item) => ({
+      ...item,
+      _searchScore: calculateRelevanceScore(item, query.trim()),
+    }));
+
+    allPrincipals = sortPrincipalsByRelevance(scoredResults)
+      .slice(0, searchLimit)
+      .map((result) => {
+        const { _searchScore, ...resultWithoutScore } = result;
+        return resultWithoutScore;
+      });
+    res.status(200).json({
+      query: query.trim(),
+      limit: searchLimit,
+      type: typeFilter,
+      results: allPrincipals,
+      count: allPrincipals.length,
+      sources: {
+        local: allPrincipals.filter((r) => r.source === 'local').length,
+        entra: allPrincipals.filter((r) => r.source === 'entra').length,
+      },
+    });
+  } catch (error) {
+    logger.error('Error searching principals:', error);
+    res.status(500).json({
+      error: 'Failed to search principals',
+      details: error.message,
+    });
+  }
+};
+
+module.exports = {
+  updateResourcePermissions,
+  getResourcePermissions,
+  getResourceRoles,
+  getUserEffectivePermissions,
+  searchPrincipals,
+};

api/server/controllers/agents/marketplace.js

@@ -0,0 +1,255 @@
+const AgentCategory = require('~/models/AgentCategory');
+const mongoose = require('mongoose');
+const { logger } = require('~/config');
+
+// Get the Agent model
+const Agent = mongoose.model('agent');
+
+// Default page size for agent browsing
+const DEFAULT_PAGE_SIZE = 6;
+
+/**
+ * Common pagination utility for agent queries
+ *
+ * @param {Object} filter - MongoDB filter object
+ * @param {number} page - Page number (1-based)
+ * @param {number} limit - Items per page
+ * @returns {Promise<Object>} Paginated results with agents and pagination info
+ */
+const paginateAgents = async (filter, page = 1, limit = DEFAULT_PAGE_SIZE) => {
+  const skip = (page - 1) * limit;
+
+  // Get total count for pagination
+  const total = await Agent.countDocuments(filter);
+
+  // Get agents with pagination
+  const agents = await Agent.find(filter)
+    .select('id name description avatar category support_contact authorName')
+    .sort({ updatedAt: -1 })
+    .skip(skip)
+    .limit(limit)
+    .lean();
+
+  // Calculate if there are more agents to load
+  const hasMore = total > page * limit;
+
+  return {
+    agents,
+    pagination: {
+      current: page,
+      hasMore,
+      total,
+    },
+  };
+};
+
+/**
+ * Get promoted/top picks agents with pagination
+ * Can also return all agents when showAll=true parameter is provided
+ *
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ */
+const getPromotedAgents = async (req, res) => {
+  try {
+    const page = parseInt(req.query.page) || 1;
+    const limit = parseInt(req.query.limit) || DEFAULT_PAGE_SIZE;
+
+    // Check if this is a request for "all" agents via query parameter
+    const showAllAgents = req.query.showAll === 'true';
+
+    // Base filter for shared agents only
+    const filter = {
+      projectIds: { $exists: true, $ne: [] }, // Only get shared agents
+    };
+
+    // Only add promoted filter if not requesting all agents
+    if (!showAllAgents) {
+      filter.is_promoted = true; // Only get promoted agents
+    }
+
+    const result = await paginateAgents(filter, page, limit);
+    res.status(200).json(result);
+  } catch (error) {
+    logger.error('[/Agents/Marketplace] Error fetching promoted agents:', error);
+    res.status(500).json({
+      error: 'Failed to fetch promoted agents',
+      userMessage: 'Unable to load agents. Please try refreshing the page.',
+      suggestion: 'Try refreshing the page or check your network connection',
+    });
+  }
+};
+
+/**
+ * Get agents by category with pagination
+ *
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ */
+const getAgentsByCategory = async (req, res) => {
+  try {
+    const { category } = req.params;
+    const page = parseInt(req.query.page) || 1;
+    const limit = parseInt(req.query.limit) || DEFAULT_PAGE_SIZE;
+
+    const filter = {
+      category,
+      projectIds: { $exists: true, $ne: [] }, // Only get shared agents
+    };
+
+    const result = await paginateAgents(filter, page, limit);
+
+    // Get category description from database
+    const categoryDoc = await AgentCategory.findOne({ value: category, isActive: true });
+    const categoryInfo = {
+      name: category,
+      description: categoryDoc?.description || '',
+      total: result.pagination.total,
+    };
+
+    res.status(200).json({
+      ...result,
+      category: categoryInfo,
+    });
+  } catch (error) {
+    logger.error(
+      `[/Agents/Marketplace] Error fetching agents for category ${req.params.category}:`,
+      error,
+    );
+    res.status(500).json({
+      error: 'Failed to fetch agents by category',
+      userMessage: `Unable to load agents for this category. Please try a different category.`,
+      suggestion: 'Try selecting a different category or refresh the page',
+    });
+  }
+};
+
+/**
+ * Search agents with filters
+ *
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ */
+const searchAgents = async (req, res) => {
+  try {
+    const { q, category } = req.query;
+    const page = parseInt(req.query.page) || 1;
+    const limit = parseInt(req.query.limit) || DEFAULT_PAGE_SIZE;
+
+    if (!q || q.trim() === '') {
+      return res.status(400).json({
+        error: 'Search query is required',
+        userMessage: 'Please enter a search term to find agents',
+        suggestion: 'Enter a search term to find agents by name or description',
+      });
+    }
+
+    // Build search filter
+    const filter = {
+      projectIds: { $exists: true, $ne: [] }, // Only get shared agents
+      $or: [
+        { name: { $regex: q, $options: 'i' } }, // Case-insensitive name search
+        { description: { $regex: q, $options: 'i' } },
+      ],
+    };
+
+    // Add category filter if provided
+    if (category && category !== 'all') {
+      filter.category = category;
+    }
+
+    const result = await paginateAgents(filter, page, limit);
+
+    res.status(200).json({
+      ...result,
+      query: q,
+    });
+  } catch (error) {
+    logger.error('[/Agents/Marketplace] Error searching agents:', error);
+    res.status(500).json({
+      error: 'Failed to search agents',
+      userMessage: 'Search is temporarily unavailable. Please try again.',
+      suggestion: 'Try a different search term or check your network connection',
+    });
+  }
+};
+
+/**
+ * Get all agent categories with counts
+ *
+ * @param {Object} _req - Express request object (unused)
+ * @param {Object} res - Express response object
+ */
+const getAgentCategories = async (_req, res) => {
+  try {
+    // Get categories with agent counts from database
+    const categories = await AgentCategory.getCategoriesWithCounts();
+
+    // Get count of promoted agents for Top Picks
+    const promotedCount = await Agent.countDocuments({
+      projectIds: { $exists: true, $ne: [] },
+      is_promoted: true,
+    });
+
+    // Convert to marketplace format (TCategory structure)
+    const formattedCategories = categories.map((category) => ({
+      value: category.value,
+      label: category.label,
+      count: category.agentCount,
+      description: category.description,
+    }));
+
+    // Add promoted category if agents exist
+    if (promotedCount > 0) {
+      formattedCategories.unshift({
+        value: 'promoted',
+        label: 'Promoted',
+        count: promotedCount,
+        description: 'Our recommended agents',
+      });
+    }
+
+    // Get total count of all shared agents for "All" category
+    const totalAgents = await Agent.countDocuments({
+      projectIds: { $exists: true, $ne: [] },
+    });
+
+    // Add "All" category at the end
+    formattedCategories.push({
+      value: 'all',
+      label: 'All',
+      count: totalAgents,
+      description: 'All available agents',
+    });
+
+    res.status(200).json(formattedCategories);
+  } catch (error) {
+    logger.error('[/Agents/Marketplace] Error fetching agent categories:', error);
+    res.status(500).json({
+      error: 'Failed to fetch agent categories',
+      userMessage: 'Unable to load categories. Please refresh the page.',
+      suggestion: 'Try refreshing the page or check your network connection',
+    });
+  }
+};
+
+/**
+ * Get all agents with pagination (for "all" category)
+ * This is an alias for getPromotedAgents with showAll=true for backwards compatibility
+ *
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ */
+const getAllAgents = async (req, res) => {
+  // Set showAll parameter and delegate to getPromotedAgents
+  req.query.showAll = 'true';
+  return getPromotedAgents(req, res);
+};
+
+module.exports = {
+  getPromotedAgents,
+  getAgentsByCategory,
+  searchAgents,
+  getAgentCategories,
+  getAllAgents,
+};

api/server/controllers/agents/v1.js

@@ -1,13 +1,12 @@
 const { z } = require('zod');
 const fs = require('fs').promises;
 const { nanoid } = require('nanoid');
-const { logger } = require('@librechat/data-schemas');
+const { logger, PermissionBits } = require('@librechat/data-schemas');
 const { agentCreateSchema, agentUpdateSchema } = require('@librechat/api');
 const {
   Tools,
-  Constants,
-  FileSources,
   SystemRoles,
+  FileSources,
   EToolResources,
   actionDelimiter,
   removeNullishValues,
@@ -17,16 +16,20 @@ const {
   createAgent,
   updateAgent,
   deleteAgent,
-  getListAgents,
+  getListAgentsByAccess,
 } = require('~/models/Agent');
+const {
+  grantPermission,
+  findAccessibleResources,
+  findPubliclyAccessibleResources,
+  hasPublicPermission,
+} = require('~/server/services/PermissionService');
 const { getStrategyFunctions } = require('~/server/services/Files/strategies');
 const { resizeAvatar } = require('~/server/services/Files/images/avatar');
 const { refreshS3Url } = require('~/server/services/Files/S3/crud');
 const { filterFile } = require('~/server/services/Files/process');
 const { updateAction, getActions } = require('~/models/Action');
 const { getCachedTools } = require('~/server/services/Config');
-const { updateAgentProjects } = require('~/models/Agent');
-const { getProjectByName } = require('~/models/Project');
 const { revertAgentVersion } = require('~/models/Agent');
 const { deleteFileByFilter } = require('~/models/File');
 
@@ -67,6 +70,27 @@ const createAgentHandler = async (req, res) => {
     }
 
     const agent = await createAgent(agentData);
+
+    // Automatically grant owner permissions to the creator
+    try {
+      await grantPermission({
+        principalType: 'user',
+        principalId: userId,
+        resourceType: 'agent',
+        resourceId: agent._id,
+        accessRoleId: 'agent_owner',
+        grantedBy: userId,
+      });
+      logger.debug(
+        `[createAgent] Granted owner permissions to user ${userId} for agent ${agent.id}`,
+      );
+    } catch (permissionError) {
+      logger.error(
+        `[createAgent] Failed to grant owner permissions for agent ${agent.id}:`,
+        permissionError,
+      );
+    }
+
     res.status(201).json(agent);
   } catch (error) {
     if (error instanceof z.ZodError) {
@@ -89,21 +113,14 @@ const createAgentHandler = async (req, res) => {
  * @returns {Promise<Agent>} 200 - success response - application/json
  * @returns {Error} 404 - Agent not found
  */
-const getAgentHandler = async (req, res) => {
+const getAgentHandler = async (req, res, expandProperties = false) => {
   try {
     const id = req.params.id;
     const author = req.user.id;
 
-    let query = { id, author };
+    // Permissions are validated by middleware before calling this function
-
+    // Simply load the agent by ID
-    const globalProject = await getProjectByName(Constants.GLOBAL_PROJECT_NAME, ['agentIds']);
+    const agent = await getAgent({ id });
-    if (globalProject && (globalProject.agentIds?.length ?? 0) > 0) {
-      query = {
-        $or: [{ id, $in: globalProject.agentIds }, query],
-      };
-    }
-
-    const agent = await getAgent(query);
 
     if (!agent) {
       return res.status(404).json({ error: 'Agent not found' });
@@ -120,23 +137,45 @@ const getAgentHandler = async (req, res) => {
     }
 
     agent.author = agent.author.toString();
+
+    // @deprecated - isCollaborative replaced by ACL permissions
     agent.isCollaborative = !!agent.isCollaborative;
 
+    // Check if agent is public
+    const isPublic = await hasPublicPermission({
+      resourceType: 'agent',
+      resourceId: agent._id,
+      requiredPermissions: PermissionBits.VIEW,
+    });
+    agent.isPublic = isPublic;
+
     if (agent.author !== author) {
       delete agent.author;
     }
 
-    if (!agent.isCollaborative && agent.author !== author && req.user.role !== SystemRoles.ADMIN) {
+    if (!expandProperties) {
+      // VIEW permission: Basic agent info only
       return res.status(200).json({
+        _id: agent._id,
         id: agent.id,
         name: agent.name,
+        description: agent.description,
         avatar: agent.avatar,
         author: agent.author,
+        provider: agent.provider,
+        model: agent.model,
         projectIds: agent.projectIds,
+        // @deprecated - isCollaborative replaced by ACL permissions
         isCollaborative: agent.isCollaborative,
+        isPublic: agent.isPublic,
         version: agent.version,
+        // Safe metadata
+        createdAt: agent.createdAt,
+        updatedAt: agent.updatedAt,
       });
     }
+
+    // EDIT permission: Full agent details including sensitive configuration
     return res.status(200).json(agent);
   } catch (error) {
     logger.error('[/Agents/:id] Error retrieving agent', error);
@@ -157,43 +196,20 @@ const updateAgentHandler = async (req, res) => {
   try {
     const id = req.params.id;
     const validatedData = agentUpdateSchema.parse(req.body);
-    const { projectIds, removeProjectIds, ...updateData } = removeNullishValues(validatedData);
+    const { _id, ...updateData } = removeNullishValues(validatedData);
-    const isAdmin = req.user.role === SystemRoles.ADMIN;
     const existingAgent = await getAgent({ id });
 
     if (!existingAgent) {
       return res.status(404).json({ error: 'Agent not found' });
     }
 
-    const isAuthor = existingAgent.author.toString() === req.user.id;
-    const hasEditPermission = existingAgent.isCollaborative || isAdmin || isAuthor;
-
-    if (!hasEditPermission) {
-      return res.status(403).json({
-        error: 'You do not have permission to modify this non-collaborative agent',
-      });
-    }
-
-    /** @type {boolean} */
-    const isProjectUpdate = (projectIds?.length ?? 0) > 0 || (removeProjectIds?.length ?? 0) > 0;
-
     let updatedAgent =
       Object.keys(updateData).length > 0
         ? await updateAgent({ id }, updateData, {
             updatingUserId: req.user.id,
-            skipVersioning: isProjectUpdate,
           })
         : existingAgent;
 
-    if (isProjectUpdate) {
-      updatedAgent = await updateAgentProjects({
-        user: req.user,
-        agentId: id,
-        projectIds,
-        removeProjectIds,
-      });
-    }
-
     // Add version count to the response
     updatedAgent.version = updatedAgent.versions ? updatedAgent.versions.length : 0;
 
@@ -321,6 +337,26 @@ const duplicateAgentHandler = async (req, res) => {
     newAgentData.actions = agentActions;
     const newAgent = await createAgent(newAgentData);
 
+    // Automatically grant owner permissions to the duplicator
+    try {
+      await grantPermission({
+        principalType: 'user',
+        principalId: userId,
+        resourceType: 'agent',
+        resourceId: newAgent._id,
+        accessRoleId: 'agent_owner',
+        grantedBy: userId,
+      });
+      logger.debug(
+        `[duplicateAgent] Granted owner permissions to user ${userId} for duplicated agent ${newAgent.id}`,
+      );
+    } catch (permissionError) {
+      logger.error(
+        `[duplicateAgent] Failed to grant owner permissions for duplicated agent ${newAgent.id}:`,
+        permissionError,
+      );
+    }
+
     return res.status(201).json({
       agent: newAgent,
       actions: newActionsList,
@@ -347,7 +383,7 @@ const deleteAgentHandler = async (req, res) => {
     if (!agent) {
       return res.status(404).json({ error: 'Agent not found' });
     }
-    await deleteAgent({ id, author: req.user.id });
+    await deleteAgent({ id });
     return res.json({ message: 'Agent deleted' });
   } catch (error) {
     logger.error('[/Agents/:id] Error deleting Agent', error);
@@ -356,7 +392,7 @@ const deleteAgentHandler = async (req, res) => {
 };
 
 /**
- *
+ * Lists agents using ACL-aware permissions (ownership + explicit shares).
  * @route GET /Agents
  * @param {object} req - Express Request
  * @param {object} req.query - Request query
@@ -365,9 +401,31 @@ const deleteAgentHandler = async (req, res) => {
  */
 const getListAgentsHandler = async (req, res) => {
   try {
-    const data = await getListAgents({
+    const userId = req.user.id;
-      author: req.user.id,
+
+    // Get agent IDs the user has VIEW access to via ACL
+    const accessibleIds = await findAccessibleResources({
+      userId,
+      resourceType: 'agent',
+      requiredPermissions: PermissionBits.VIEW,
     });
+    const publiclyAccessibleIds = await findPubliclyAccessibleResources({
+      resourceType: 'agent',
+      requiredPermissions: PermissionBits.VIEW,
+    });
+    // Use the new ACL-aware function
+    const data = await getListAgentsByAccess({
+      accessibleIds,
+      otherParams: {}, // Can add query params here if needed
+    });
+    if (data?.data?.length) {
+      data.data = data.data.map((agent) => {
+        if (publiclyAccessibleIds.some((id) => id.equals(agent._id))) {
+          agent.isPublic = true;
+        }
+        return agent;
+      });
+    }
     return res.json(data);
   } catch (error) {
     logger.error('[/Agents] Error listing Agents', error);

api/server/index.js

@@ -115,6 +115,8 @@ const startServer = async () => {
   app.use('/api/agents', routes.agents);
   app.use('/api/banner', routes.banner);
   app.use('/api/memories', routes.memories);
+  app.use('/api/permissions', routes.accessPermissions);
+
   app.use('/api/tags', routes.tags);
   app.use('/api/mcp', routes.mcp);
 

api/server/middleware/accessResources/canAccessAgentFromBody.js

@@ -0,0 +1,97 @@
+const { logger } = require('@librechat/data-schemas');
+const { Constants, isAgentsEndpoint } = require('librechat-data-provider');
+const { canAccessResource } = require('./canAccessResource');
+const { getAgent } = require('~/models/Agent');
+
+/**
+ * Agent ID resolver function for agent_id from request body
+ * Resolves custom agent ID (e.g., "agent_abc123") to MongoDB ObjectId
+ * This is used specifically for chat routes where agent_id comes from request body
+ *
+ * @param {string} agentCustomId - Custom agent ID from request body
+ * @returns {Promise<Object|null>} Agent document with _id field, or null if not found
+ */
+const resolveAgentIdFromBody = async (agentCustomId) => {
+  // Handle ephemeral agents - they don't need permission checks
+  if (agentCustomId === Constants.EPHEMERAL_AGENT_ID) {
+    return null; // No permission check needed for ephemeral agents
+  }
+
+  return await getAgent({ id: agentCustomId });
+};
+
+/**
+ * Middleware factory that creates middleware to check agent access permissions from request body.
+ * This middleware is specifically designed for chat routes where the agent_id comes from req.body
+ * instead of route parameters.
+ *
+ * @param {Object} options - Configuration options
+ * @param {number} options.requiredPermission - The permission bit required (1=view, 2=edit, 4=delete, 8=share)
+ * @returns {Function} Express middleware function
+ *
+ * @example
+ * // Basic usage for agent chat (requires VIEW permission)
+ * router.post('/chat',
+ *   canAccessAgentFromBody({ requiredPermission: PermissionBits.VIEW }),
+ *   buildEndpointOption,
+ *   chatController
+ * );
+ */
+const canAccessAgentFromBody = (options) => {
+  const { requiredPermission } = options;
+
+  // Validate required options
+  if (!requiredPermission || typeof requiredPermission !== 'number') {
+    throw new Error('canAccessAgentFromBody: requiredPermission is required and must be a number');
+  }
+
+  return async (req, res, next) => {
+    try {
+      const { endpoint, agent_id } = req.body;
+      let agentId = agent_id;
+
+      if (!isAgentsEndpoint(endpoint)) {
+        agentId = Constants.EPHEMERAL_AGENT_ID;
+      }
+
+      if (!agentId) {
+        return res.status(400).json({
+          error: 'Bad Request',
+          message: 'agent_id is required in request body',
+        });
+      }
+
+      // Skip permission checks for ephemeral agents
+      if (agentId === Constants.EPHEMERAL_AGENT_ID) {
+        return next();
+      }
+
+      const agentAccessMiddleware = canAccessResource({
+        resourceType: 'agent',
+        requiredPermission,
+        resourceIdParam: 'agent_id', // This will be ignored since we use custom resolver
+        idResolver: () => resolveAgentIdFromBody(agentId),
+      });
+
+      const tempReq = {
+        ...req,
+        params: {
+          ...req.params,
+          agent_id: agentId,
+        },
+      };
+
+      return agentAccessMiddleware(tempReq, res, next);
+    } catch (error) {
+      logger.error('Failed to validate agent access permissions', error);
+      return res.status(500).json({
+        error: 'Internal Server Error',
+        message: 'Failed to validate agent access permissions',
+      });
+    }
+  };
+};
+
+module.exports = {
+  canAccessAgentFromBody,
+};

api/server/middleware/accessResources/canAccessAgentResource.js

@@ -0,0 +1,58 @@
+const { getAgent } = require('~/models/Agent');
+const { canAccessResource } = require('./canAccessResource');
+
+/**
+ * Agent ID resolver function
+ * Resolves custom agent ID (e.g., "agent_abc123") to MongoDB ObjectId
+ *
+ * @param {string} agentCustomId - Custom agent ID from route parameter
+ * @returns {Promise<Object|null>} Agent document with _id field, or null if not found
+ */
+const resolveAgentId = async (agentCustomId) => {
+  return await getAgent({ id: agentCustomId });
+};
+
+/**
+ * Agent-specific middleware factory that creates middleware to check agent access permissions.
+ * This middleware extends the generic canAccessResource to handle agent custom ID resolution.
+ *
+ * @param {Object} options - Configuration options
+ * @param {number} options.requiredPermission - The permission bit required (1=view, 2=edit, 4=delete, 8=share)
+ * @param {string} [options.resourceIdParam='id'] - The name of the route parameter containing the agent custom ID
+ * @returns {Function} Express middleware function
+ *
+ * @example
+ * // Basic usage for viewing agents
+ * router.get('/agents/:id',
+ *   canAccessAgentResource({ requiredPermission: 1 }),
+ *   getAgent
+ * );
+ *
+ * @example
+ * // Custom resource ID parameter and edit permission
+ * router.patch('/agents/:agent_id',
+ *   canAccessAgentResource({
+ *     requiredPermission: 2,
+ *     resourceIdParam: 'agent_id'
+ *   }),
+ *   updateAgent
+ * );
+ */
+const canAccessAgentResource = (options) => {
+  const { requiredPermission, resourceIdParam = 'id' } = options;
+
+  if (!requiredPermission || typeof requiredPermission !== 'number') {
+    throw new Error('canAccessAgentResource: requiredPermission is required and must be a number');
+  }
+
+  return canAccessResource({
+    resourceType: 'agent',
+    requiredPermission,
+    resourceIdParam,
+    idResolver: resolveAgentId,
+  });
+};
+
+module.exports = {
+  canAccessAgentResource,
+};

api/server/middleware/accessResources/canAccessAgentResource.spec.js

@@ -0,0 +1,384 @@
+const mongoose = require('mongoose');
+const { MongoMemoryServer } = require('mongodb-memory-server');
+const { canAccessAgentResource } = require('./canAccessAgentResource');
+const { User, Role, AclEntry } = require('~/db/models');
+const { createAgent } = require('~/models/Agent');
+
+describe('canAccessAgentResource middleware', () => {
+  let mongoServer;
+  let req, res, next;
+  let testUser;
+
+  beforeAll(async () => {
+    mongoServer = await MongoMemoryServer.create();
+    const mongoUri = mongoServer.getUri();
+    await mongoose.connect(mongoUri);
+  });
+
+  afterAll(async () => {
+    await mongoose.disconnect();
+    await mongoServer.stop();
+  });
+
+  beforeEach(async () => {
+    await mongoose.connection.dropDatabase();
+    await Role.create({
+      name: 'test-role',
+      permissions: {
+        AGENTS: {
+          USE: true,
+          CREATE: true,
+          SHARED_GLOBAL: false,
+        },
+      },
+    });
+
+    // Create a test user
+    testUser = await User.create({
+      email: 'test@example.com',
+      name: 'Test User',
+      username: 'testuser',
+      role: 'test-role',
+    });
+
+    req = {
+      user: { id: testUser._id.toString(), role: 'test-role' },
+      params: {},
+    };
+    res = {
+      status: jest.fn().mockReturnThis(),
+      json: jest.fn(),
+    };
+    next = jest.fn();
+
+    jest.clearAllMocks();
+  });
+
+  describe('middleware factory', () => {
+    test('should throw error if requiredPermission is not provided', () => {
+      expect(() => canAccessAgentResource({})).toThrow(
+        'canAccessAgentResource: requiredPermission is required and must be a number',
+      );
+    });
+
+    test('should throw error if requiredPermission is not a number', () => {
+      expect(() => canAccessAgentResource({ requiredPermission: '1' })).toThrow(
+        'canAccessAgentResource: requiredPermission is required and must be a number',
+      );
+    });
+
+    test('should create middleware with default resourceIdParam', () => {
+      const middleware = canAccessAgentResource({ requiredPermission: 1 });
+      expect(typeof middleware).toBe('function');
+      expect(middleware.length).toBe(3); // Express middleware signature
+    });
+
+    test('should create middleware with custom resourceIdParam', () => {
+      const middleware = canAccessAgentResource({
+        requiredPermission: 2,
+        resourceIdParam: 'agent_id',
+      });
+      expect(typeof middleware).toBe('function');
+      expect(middleware.length).toBe(3);
+    });
+  });
+
+  describe('permission checking with real agents', () => {
+    test('should allow access when user is the agent author', async () => {
+      // Create an agent owned by the test user
+      const agent = await createAgent({
+        id: `agent_${Date.now()}`,
+        name: 'Test Agent',
+        provider: 'openai',
+        model: 'gpt-4',
+        author: testUser._id,
+      });
+
+      // Create ACL entry for the author (owner permissions)
+      await AclEntry.create({
+        principalType: 'user',
+        principalId: testUser._id,
+        principalModel: 'User',
+        resourceType: 'agent',
+        resourceId: agent._id,
+        permBits: 15, // All permissions (1+2+4+8)
+        grantedBy: testUser._id,
+      });
+
+      req.params.id = agent.id;
+
+      const middleware = canAccessAgentResource({ requiredPermission: 1 }); // VIEW permission
+      await middleware(req, res, next);
+
+      expect(next).toHaveBeenCalled();
+      expect(res.status).not.toHaveBeenCalled();
+    });
+
+    test('should deny access when user is not the author and has no ACL entry', async () => {
+      // Create an agent owned by a different user
+      const otherUser = await User.create({
+        email: 'other@example.com',
+        name: 'Other User',
+        username: 'otheruser',
+        role: 'test-role',
+      });
+
+      const agent = await createAgent({
+        id: `agent_${Date.now()}`,
+        name: 'Other User Agent',
+        provider: 'openai',
+        model: 'gpt-4',
+        author: otherUser._id,
+      });
+
+      // Create ACL entry for the other user (owner)
+      await AclEntry.create({
+        principalType: 'user',
+        principalId: otherUser._id,
+        principalModel: 'User',
+        resourceType: 'agent',
+        resourceId: agent._id,
+        permBits: 15, // All permissions
+        grantedBy: otherUser._id,
+      });
+
+      req.params.id = agent.id;
+
+      const middleware = canAccessAgentResource({ requiredPermission: 1 }); // VIEW permission
+      await middleware(req, res, next);
+
+      expect(next).not.toHaveBeenCalled();
+      expect(res.status).toHaveBeenCalledWith(403);
+      expect(res.json).toHaveBeenCalledWith({
+        error: 'Forbidden',
+        message: 'Insufficient permissions to access this agent',
+      });
+    });
+
+    test('should allow access when user has ACL entry with sufficient permissions', async () => {
+      // Create an agent owned by a different user
+      const otherUser = await User.create({
+        email: 'other2@example.com',
+        name: 'Other User 2',
+        username: 'otheruser2',
+        role: 'test-role',
+      });
+
+      const agent = await createAgent({
+        id: `agent_${Date.now()}`,
+        name: 'Shared Agent',
+        provider: 'openai',
+        model: 'gpt-4',
+        author: otherUser._id,
+      });
+
+      // Create ACL entry granting view permission to test user
+      await AclEntry.create({
+        principalType: 'user',
+        principalId: testUser._id,
+        principalModel: 'User',
+        resourceType: 'agent',
+        resourceId: agent._id,
+        permBits: 1, // VIEW permission
+        grantedBy: otherUser._id,
+      });
+
+      req.params.id = agent.id;
+
+      const middleware = canAccessAgentResource({ requiredPermission: 1 }); // VIEW permission
+      await middleware(req, res, next);
+
+      expect(next).toHaveBeenCalled();
+      expect(res.status).not.toHaveBeenCalled();
+    });
+
+    test('should deny access when ACL permissions are insufficient', async () => {
+      // Create an agent owned by a different user
+      const otherUser = await User.create({
+        email: 'other3@example.com',
+        name: 'Other User 3',
+        username: 'otheruser3',
+        role: 'test-role',
+      });
+
+      const agent = await createAgent({
+        id: `agent_${Date.now()}`,
+        name: 'Limited Access Agent',
+        provider: 'openai',
+        model: 'gpt-4',
+        author: otherUser._id,
+      });
+
+      // Create ACL entry granting only view permission
+      await AclEntry.create({
+        principalType: 'user',
+        principalId: testUser._id,
+        principalModel: 'User',
+        resourceType: 'agent',
+        resourceId: agent._id,
+        permBits: 1, // VIEW permission only
+        grantedBy: otherUser._id,
+      });
+
+      req.params.id = agent.id;
+
+      const middleware = canAccessAgentResource({ requiredPermission: 2 }); // EDIT permission required
+      await middleware(req, res, next);
+
+      expect(next).not.toHaveBeenCalled();
+      expect(res.status).toHaveBeenCalledWith(403);
+      expect(res.json).toHaveBeenCalledWith({
+        error: 'Forbidden',
+        message: 'Insufficient permissions to access this agent',
+      });
+    });
+
+    test('should handle non-existent agent', async () => {
+      req.params.id = 'agent_nonexistent';
+
+      const middleware = canAccessAgentResource({ requiredPermission: 1 });
+      await middleware(req, res, next);
+
+      expect(next).not.toHaveBeenCalled();
+      expect(res.status).toHaveBeenCalledWith(404);
+      expect(res.json).toHaveBeenCalledWith({
+        error: 'Not Found',
+        message: 'agent not found',
+      });
+    });
+
+    test('should use custom resourceIdParam', async () => {
+      const agent = await createAgent({
+        id: `agent_${Date.now()}`,
+        name: 'Custom Param Agent',
+        provider: 'openai',
+        model: 'gpt-4',
+        author: testUser._id,
+      });
+
+      // Create ACL entry for the author
+      await AclEntry.create({
+        principalType: 'user',
+        principalId: testUser._id,
+        principalModel: 'User',
+        resourceType: 'agent',
+        resourceId: agent._id,
+        permBits: 15, // All permissions
+        grantedBy: testUser._id,
+      });
+
+      req.params.agent_id = agent.id; // Using custom param name
+
+      const middleware = canAccessAgentResource({
+        requiredPermission: 1,
+        resourceIdParam: 'agent_id',
+      });
+      await middleware(req, res, next);
+
+      expect(next).toHaveBeenCalled();
+      expect(res.status).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('permission levels', () => {
+    let agent;
+
+    beforeEach(async () => {
+      agent = await createAgent({
+        id: `agent_${Date.now()}`,
+        name: 'Permission Test Agent',
+        provider: 'openai',
+        model: 'gpt-4',
+        author: testUser._id,
+      });
+
+      // Create ACL entry with all permissions for the owner
+      await AclEntry.create({
+        principalType: 'user',
+        principalId: testUser._id,
+        principalModel: 'User',
+        resourceType: 'agent',
+        resourceId: agent._id,
+        permBits: 15, // All permissions (1+2+4+8)
+        grantedBy: testUser._id,
+      });
+
+      req.params.id = agent.id;
+    });
+
+    test('should support view permission (1)', async () => {
+      const middleware = canAccessAgentResource({ requiredPermission: 1 });
+      await middleware(req, res, next);
+      expect(next).toHaveBeenCalled();
+    });
+
+    test('should support edit permission (2)', async () => {
+      const middleware = canAccessAgentResource({ requiredPermission: 2 });
+      await middleware(req, res, next);
+      expect(next).toHaveBeenCalled();
+    });
+
+    test('should support delete permission (4)', async () => {
+      const middleware = canAccessAgentResource({ requiredPermission: 4 });
+      await middleware(req, res, next);
+      expect(next).toHaveBeenCalled();
+    });
+
+    test('should support share permission (8)', async () => {
+      const middleware = canAccessAgentResource({ requiredPermission: 8 });
+      await middleware(req, res, next);
+      expect(next).toHaveBeenCalled();
+    });
+
+    test('should support combined permissions', async () => {
+      const viewAndEdit = 1 | 2; // 3
+      const middleware = canAccessAgentResource({ requiredPermission: viewAndEdit });
+      await middleware(req, res, next);
+      expect(next).toHaveBeenCalled();
+    });
+  });
+
+  describe('integration with agent operations', () => {
+    test('should work with agent CRUD operations', async () => {
+      const agentId = `agent_${Date.now()}`;
+
+      // Create agent
+      const agent = await createAgent({
+        id: agentId,
+        name: 'Integration Test Agent',
+        provider: 'openai',
+        model: 'gpt-4',
+        author: testUser._id,
+        description: 'Testing integration',
+      });
+
+      // Create ACL entry for the author
+      await AclEntry.create({
+        principalType: 'user',
+        principalId: testUser._id,
+        principalModel: 'User',
+        resourceType: 'agent',
+        resourceId: agent._id,
+        permBits: 15, // All permissions
+        grantedBy: testUser._id,
+      });
+
+      req.params.id = agentId;
+
+      // Test view access
+      const viewMiddleware = canAccessAgentResource({ requiredPermission: 1 });
+      await viewMiddleware(req, res, next);
+      expect(next).toHaveBeenCalled();
+      jest.clearAllMocks();
+
+      // Update the agent
+      const { updateAgent } = require('~/models/Agent');
+      await updateAgent({ id: agentId }, { description: 'Updated description' });
+
+      // Test edit access
+      const editMiddleware = canAccessAgentResource({ requiredPermission: 2 });
+      await editMiddleware(req, res, next);
+      expect(next).toHaveBeenCalled();
+    });
+  });
+});

api/server/middleware/accessResources/canAccessResource.js

@@ -0,0 +1,157 @@
+const { logger } = require('@librechat/data-schemas');
+const { SystemRoles } = require('librechat-data-provider');
+const { checkPermission } = require('~/server/services/PermissionService');
+
+/**
+ * Generic base middleware factory that creates middleware to check resource access permissions.
+ * This middleware expects MongoDB ObjectIds as resource identifiers for ACL permission checks.
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} options.resourceType - The type of resource (e.g., 'agent', 'file', 'project')
+ * @param {number} options.requiredPermission - The permission bit required (1=view, 2=edit, 4=delete, 8=share)
+ * @param {string} [options.resourceIdParam='resourceId'] - The name of the route parameter containing the resource ID
+ * @param {Function} [options.idResolver] - Optional function to resolve custom IDs to ObjectIds
+ * @returns {Function} Express middleware function
+ *
+ * @example
+ * // Direct usage with ObjectId (for resources that use MongoDB ObjectId in routes)
+ * router.get('/prompts/:promptId',
+ *   canAccessResource({ resourceType: 'prompt', requiredPermission: 1 }),
+ *   getPrompt
+ * );
+ *
+ * @example
+ * // Usage with custom ID resolver (for resources that use custom string IDs)
+ * router.get('/agents/:id',
+ *   canAccessResource({
+ *     resourceType: 'agent',
+ *     requiredPermission: 1,
+ *     resourceIdParam: 'id',
+ *     idResolver: (customId) => resolveAgentId(customId)
+ *   }),
+ *   getAgent
+ * );
+ */
+const canAccessResource = (options) => {
+  const {
+    resourceType,
+    requiredPermission,
+    resourceIdParam = 'resourceId',
+    idResolver = null,
+  } = options;
+
+  if (!resourceType || typeof resourceType !== 'string') {
+    throw new Error('canAccessResource: resourceType is required and must be a string');
+  }
+
+  if (!requiredPermission || typeof requiredPermission !== 'number') {
+    throw new Error('canAccessResource: requiredPermission is required and must be a number');
+  }
+
+  return async (req, res, next) => {
+    try {
+      // Extract resource ID from route parameters
+      const rawResourceId = req.params[resourceIdParam];
+
+      if (!rawResourceId) {
+        logger.warn(`[canAccessResource] Missing ${resourceIdParam} in route parameters`);
+        return res.status(400).json({
+          error: 'Bad Request',
+          message: `${resourceIdParam} is required`,
+        });
+      }
+
+      // Check if user is authenticated
+      if (!req.user || !req.user.id) {
+        logger.warn(
+          `[canAccessResource] Unauthenticated request for ${resourceType} ${rawResourceId}`,
+        );
+        return res.status(401).json({
+          error: 'Unauthorized',
+          message: 'Authentication required',
+        });
+      }
+      // if system admin let through
+      if (req.user.role === SystemRoles.ADMIN) {
+        return next();
+      }
+      const userId = req.user.id;
+      let resourceId = rawResourceId;
+      let resourceInfo = null;
+
+      // Resolve custom ID to ObjectId if resolver is provided
+      if (idResolver) {
+        logger.debug(
+          `[canAccessResource] Resolving ${resourceType} custom ID ${rawResourceId} to ObjectId`,
+        );
+
+        const resolutionResult = await idResolver(rawResourceId);
+
+        if (!resolutionResult) {
+          logger.warn(`[canAccessResource] ${resourceType} not found: ${rawResourceId}`);
+          return res.status(404).json({
+            error: 'Not Found',
+            message: `${resourceType} not found`,
+          });
+        }
+
+        // Handle different resolver return formats
+        if (typeof resolutionResult === 'string' || resolutionResult._id) {
+          resourceId = resolutionResult._id || resolutionResult;
+          resourceInfo = typeof resolutionResult === 'object' ? resolutionResult : null;
+        } else {
+          resourceId = resolutionResult;
+        }
+
+        logger.debug(
+          `[canAccessResource] Resolved ${resourceType} ${rawResourceId} to ObjectId ${resourceId}`,
+        );
+      }
+
+      // Check permissions using PermissionService with ObjectId
+      const hasPermission = await checkPermission({
+        userId,
+        resourceType,
+        resourceId,
+        requiredPermission,
+      });
+
+      if (hasPermission) {
+        logger.debug(
+          `[canAccessResource] User ${userId} has permission ${requiredPermission} on ${resourceType} ${rawResourceId} (${resourceId})`,
+        );
+
+        req.resourceAccess = {
+          resourceType,
+          resourceId, // MongoDB ObjectId for ACL operations
+          customResourceId: rawResourceId, // Original ID from route params
+          permission: requiredPermission,
+          userId,
+          ...(resourceInfo && { resourceInfo }),
+        };
+
+        return next();
+      }
+
+      logger.warn(
+        `[canAccessResource] User ${userId} denied access to ${resourceType} ${rawResourceId} ` +
+          `(required permission: ${requiredPermission})`,
+      );
+
+      return res.status(403).json({
+        error: 'Forbidden',
+        message: `Insufficient permissions to access this ${resourceType}`,
+      });
+    } catch (error) {
+      logger.error(`[canAccessResource] Error checking access for ${resourceType}:`, error);
+      return res.status(500).json({
+        error: 'Internal Server Error',
+        message: 'Failed to check resource access permissions',
+      });
+    }
+  };
+};
+
+module.exports = {
+  canAccessResource,
+};

api/server/middleware/accessResources/index.js

@@ -0,0 +1,9 @@
+const { canAccessResource } = require('./canAccessResource');
+const { canAccessAgentResource } = require('./canAccessAgentResource');
+const { canAccessAgentFromBody } = require('./canAccessAgentFromBody');
+
+module.exports = {
+  canAccessResource,
+  canAccessAgentResource,
+  canAccessAgentFromBody,
+};

api/server/middleware/index.js

@@ -8,6 +8,7 @@ const concurrentLimiter = require('./concurrentLimiter');
 const validateEndpoint = require('./validateEndpoint');
 const requireLocalAuth = require('./requireLocalAuth');
 const canDeleteAccount = require('./canDeleteAccount');
+const accessResources = require('./accessResources');
 const setBalanceConfig = require('./setBalanceConfig');
 const requireLdapAuth = require('./requireLdapAuth');
 const abortMiddleware = require('./abortMiddleware');
@@ -29,6 +30,7 @@ module.exports = {
   ...validate,
   ...limiters,
   ...roles,
+  ...accessResources,
   noIndex,
   checkBan,
   uaParser,

api/server/middleware/roles/access.spec.js

@@ -0,0 +1,251 @@
+const mongoose = require('mongoose');
+const { MongoMemoryServer } = require('mongodb-memory-server');
+const { checkAccess, generateCheckAccess } = require('./access');
+const { PermissionTypes, Permissions } = require('librechat-data-provider');
+const { Role } = require('~/db/models');
+
+// Mock only the logger
+jest.mock('~/config', () => ({
+  logger: {
+    warn: jest.fn(),
+    error: jest.fn(),
+  },
+}));
+
+describe('Access Middleware', () => {
+  let mongoServer;
+  let req, res, next;
+
+  beforeAll(async () => {
+    mongoServer = await MongoMemoryServer.create();
+    const mongoUri = mongoServer.getUri();
+    await mongoose.connect(mongoUri);
+  });
+
+  afterAll(async () => {
+    await mongoose.disconnect();
+    await mongoServer.stop();
+  });
+
+  beforeEach(async () => {
+    await mongoose.connection.dropDatabase();
+
+    // Create test roles
+    await Role.create({
+      name: 'user',
+      permissions: {
+        [PermissionTypes.AGENTS]: {
+          [Permissions.USE]: true,
+          [Permissions.CREATE]: false,
+          [Permissions.SHARED_GLOBAL]: false,
+        },
+      },
+    });
+
+    await Role.create({
+      name: 'admin',
+      permissions: {
+        [PermissionTypes.AGENTS]: {
+          [Permissions.USE]: true,
+          [Permissions.CREATE]: true,
+          [Permissions.SHARED_GLOBAL]: true,
+        },
+      },
+    });
+
+    req = {
+      user: { id: 'user123', role: 'user' },
+      body: {},
+    };
+    res = {
+      status: jest.fn().mockReturnThis(),
+      json: jest.fn(),
+    };
+    next = jest.fn();
+    jest.clearAllMocks();
+  });
+
+  describe('checkAccess', () => {
+    test('should return false if user is not provided', async () => {
+      const result = await checkAccess(null, PermissionTypes.AGENTS, [Permissions.USE]);
+      expect(result).toBe(false);
+    });
+
+    test('should return true if user has required permission', async () => {
+      const result = await checkAccess(req.user, PermissionTypes.AGENTS, [Permissions.USE]);
+      expect(result).toBe(true);
+    });
+
+    test('should return false if user lacks required permission', async () => {
+      const result = await checkAccess(req.user, PermissionTypes.AGENTS, [Permissions.CREATE]);
+      expect(result).toBe(false);
+    });
+
+    test('should return true if user has any of multiple permissions', async () => {
+      const result = await checkAccess(req.user, PermissionTypes.AGENTS, [
+        Permissions.USE,
+        Permissions.CREATE,
+      ]);
+      expect(result).toBe(true);
+    });
+
+    test('should check body properties when permission is not directly granted', async () => {
+      // User role doesn't have CREATE permission, but bodyProps allows it
+      const bodyProps = {
+        [Permissions.CREATE]: ['agentId', 'name'],
+      };
+
+      const checkObject = { agentId: 'agent123' };
+
+      const result = await checkAccess(
+        req.user,
+        PermissionTypes.AGENTS,
+        [Permissions.CREATE],
+        bodyProps,
+        checkObject,
+      );
+      expect(result).toBe(true);
+    });
+
+    test('should return false if role is not found', async () => {
+      req.user.role = 'nonexistent';
+      const result = await checkAccess(req.user, PermissionTypes.AGENTS, [Permissions.USE]);
+      expect(result).toBe(false);
+    });
+
+    test('should return false if role has no permissions for the requested type', async () => {
+      await Role.create({
+        name: 'limited',
+        permissions: {
+          // Explicitly set AGENTS permissions to false
+          [PermissionTypes.AGENTS]: {
+            [Permissions.USE]: false,
+            [Permissions.CREATE]: false,
+            [Permissions.SHARED_GLOBAL]: false,
+          },
+          // Has permissions for other types
+          [PermissionTypes.PROMPTS]: {
+            [Permissions.USE]: true,
+          },
+        },
+      });
+      req.user.role = 'limited';
+
+      const result = await checkAccess(req.user, PermissionTypes.AGENTS, [Permissions.USE]);
+      expect(result).toBe(false);
+    });
+
+    test('should handle admin role with all permissions', async () => {
+      req.user.role = 'admin';
+
+      const createResult = await checkAccess(req.user, PermissionTypes.AGENTS, [
+        Permissions.CREATE,
+      ]);
+      expect(createResult).toBe(true);
+
+      const shareResult = await checkAccess(req.user, PermissionTypes.AGENTS, [
+        Permissions.SHARED_GLOBAL,
+      ]);
+      expect(shareResult).toBe(true);
+    });
+  });
+
+  describe('generateCheckAccess', () => {
+    test('should call next() when user has required permission', async () => {
+      const middleware = generateCheckAccess(PermissionTypes.AGENTS, [Permissions.USE]);
+      await middleware(req, res, next);
+
+      expect(next).toHaveBeenCalled();
+      expect(res.status).not.toHaveBeenCalled();
+    });
+
+    test('should return 403 when user lacks permission', async () => {
+      const middleware = generateCheckAccess(PermissionTypes.AGENTS, [Permissions.CREATE]);
+      await middleware(req, res, next);
+
+      expect(next).not.toHaveBeenCalled();
+      expect(res.status).toHaveBeenCalledWith(403);
+      expect(res.json).toHaveBeenCalledWith({ message: 'Forbidden: Insufficient permissions' });
+    });
+
+    test('should check body properties when configured', async () => {
+      req.body = { agentId: 'agent123', description: 'test' };
+
+      const bodyProps = {
+        [Permissions.CREATE]: ['agentId'],
+      };
+
+      const middleware = generateCheckAccess(
+        PermissionTypes.AGENTS,
+        [Permissions.CREATE],
+        bodyProps,
+      );
+      await middleware(req, res, next);
+
+      expect(next).toHaveBeenCalled();
+      expect(res.status).not.toHaveBeenCalled();
+    });
+
+    test('should handle database errors gracefully', async () => {
+      // Create a user with an invalid role that will cause getRoleByName to fail
+      req.user.role = { invalid: 'object' }; // This will cause an error when querying
+
+      const middleware = generateCheckAccess(PermissionTypes.AGENTS, [Permissions.USE]);
+      await middleware(req, res, next);
+
+      expect(next).not.toHaveBeenCalled();
+      expect(res.status).toHaveBeenCalledWith(500);
+      expect(res.json).toHaveBeenCalledWith({
+        message: expect.stringContaining('Server error:'),
+      });
+    });
+
+    test('should work with multiple permission types', async () => {
+      req.user.role = 'admin';
+
+      const middleware = generateCheckAccess(PermissionTypes.AGENTS, [
+        Permissions.USE,
+        Permissions.CREATE,
+        Permissions.SHARED_GLOBAL,
+      ]);
+      await middleware(req, res, next);
+
+      expect(next).toHaveBeenCalled();
+    });
+
+    test('should handle missing user gracefully', async () => {
+      req.user = null;
+
+      const middleware = generateCheckAccess(PermissionTypes.AGENTS, [Permissions.USE]);
+      await middleware(req, res, next);
+
+      expect(next).not.toHaveBeenCalled();
+      expect(res.status).toHaveBeenCalledWith(500);
+      expect(res.json).toHaveBeenCalledWith({
+        message: expect.stringContaining('Server error:'),
+      });
+    });
+
+    test('should handle role with no AGENTS permissions', async () => {
+      await Role.create({
+        name: 'noaccess',
+        permissions: {
+          // Explicitly set AGENTS with all permissions false
+          [PermissionTypes.AGENTS]: {
+            [Permissions.USE]: false,
+            [Permissions.CREATE]: false,
+            [Permissions.SHARED_GLOBAL]: false,
+          },
+        },
+      });
+      req.user.role = 'noaccess';
+
+      const middleware = generateCheckAccess(PermissionTypes.AGENTS, [Permissions.USE]);
+      await middleware(req, res, next);
+
+      expect(next).not.toHaveBeenCalled();
+      expect(res.status).toHaveBeenCalledWith(403);
+      expect(res.json).toHaveBeenCalledWith({ message: 'Forbidden: Insufficient permissions' });
+    });
+  });
+});

api/server/routes/accessPermissions.js

@@ -0,0 +1,62 @@
+const express = require('express');
+const { PermissionBits } = require('@librechat/data-schemas');
+const {
+  getUserEffectivePermissions,
+  updateResourcePermissions,
+  getResourcePermissions,
+  getResourceRoles,
+  searchPrincipals,
+} = require('~/server/controllers/PermissionsController');
+const { requireJwtAuth, checkBan, uaParser, canAccessResource } = require('~/server/middleware');
+
+const router = express.Router();
+
+// Apply common middleware
+router.use(requireJwtAuth);
+router.use(checkBan);
+router.use(uaParser);
+
+/**
+ * Generic routes for resource permissions
+ * Pattern: /api/permissions/{resourceType}/{resourceId}
+ */
+
+/**
+ * GET /api/permissions/search-principals
+ * Search for users and groups to grant permissions
+ */
+router.get('/search-principals', searchPrincipals);
+
+/**
+ * GET /api/permissions/{resourceType}/roles
+ * Get available roles for a resource type
+ */
+router.get('/:resourceType/roles', getResourceRoles);
+
+/**
+ * GET /api/permissions/{resourceType}/{resourceId}
+ * Get all permissions for a specific resource
+ */
+router.get('/:resourceType/:resourceId', getResourcePermissions);
+
+/**
+ * PUT /api/permissions/{resourceType}/{resourceId}
+ * Bulk update permissions for a specific resource
+ */
+router.put(
+  '/:resourceType/:resourceId',
+  canAccessResource({
+    resourceType: 'agent',
+    requiredPermission: PermissionBits.SHARE,
+    resourceIdParam: 'resourceId',
+  }),
+  updateResourcePermissions,
+);
+
+/**
+ * GET /api/permissions/{resourceType}/{resourceId}/effective
+ * Get user's effective permissions for a specific resource
+ */
+router.get('/:resourceType/:resourceId/effective', getUserEffectivePermissions);
+
+module.exports = router;

api/server/routes/agents/actions.js

@@ -1,9 +1,8 @@
 const express = require('express');
 const { nanoid } = require('nanoid');
-const { logger } = require('@librechat/data-schemas');
 const { generateCheckAccess } = require('@librechat/api');
+const { logger, PermissionBits } = require('@librechat/data-schemas');
 const {
-  SystemRoles,
   Permissions,
   PermissionTypes,
   actionDelimiter,
@@ -12,6 +11,7 @@ const {
 const { encryptMetadata, domainParser } = require('~/server/services/ActionService');
 const { updateAction, getActions, deleteAction } = require('~/models/Action');
 const { isActionDomainAllowed } = require('~/server/services/domains');
+const { canAccessAgentResource } = require('~/server/middleware');
 const { getAgent, updateAgent } = require('~/models/Agent');
 const { getRoleByName } = require('~/models/Role');
 
@@ -23,12 +23,6 @@ const checkAgentCreate = generateCheckAccess({
   getRoleByName,
 });
 
-// If the user has ADMIN role
-// then action edition is possible even if not owner of the assistant
-const isAdmin = (req) => {
-  return req.user.role === SystemRoles.ADMIN;
-};
-
 /**
  * Retrieves all user's actions
  * @route GET /actions/
@@ -37,9 +31,8 @@ const isAdmin = (req) => {
  */
 router.get('/', async (req, res) => {
   try {
-    const admin = isAdmin(req);
+    // Get all actions for the user (admin permissions handled by middleware if needed)
-    // If admin, get all actions, otherwise only user's actions
+    const searchParams = { user: req.user.id };
-    const searchParams = admin ? {} : { user: req.user.id };
     res.json(await getActions(searchParams));
   } catch (error) {
     res.status(500).json({ error: error.message });
@@ -55,7 +48,14 @@ router.get('/', async (req, res) => {
  * @param {ActionMetadata} req.body.metadata - Metadata for the action.
  * @returns {Object} 200 - success response - application/json
  */
-router.post('/:agent_id', checkAgentCreate, async (req, res) => {
+router.post(
+  '/:agent_id',
+  canAccessAgentResource({
+    requiredPermission: PermissionBits.EDIT,
+    resourceIdParam: 'agent_id',
+  }),
+  checkAgentCreate,
+  async (req, res) => {
     try {
       const { agent_id } = req.params;
 
@@ -80,12 +80,9 @@ router.post('/:agent_id', checkAgentCreate, async (req, res) => {
 
       const action_id = _action_id ?? nanoid();
       const initialPromises = [];
-    const admin = isAdmin(req);
 
-    // If admin, can edit any agent, otherwise only user's agents
+      // Permissions already validated by middleware - load agent directly
-    const agentQuery = admin ? { id: agent_id } : { id: agent_id, author: req.user.id };
+      initialPromises.push(getAgent({ id: agent_id }));
-    // TODO: share agents
-    initialPromises.push(getAgent(agentQuery));
       if (_action_id) {
         initialPromises.push(getActions({ action_id }, true));
       }
@@ -123,7 +120,7 @@ router.post('/:agent_id', checkAgentCreate, async (req, res) => {
 
       // Force version update since actions are changing
       const updatedAgent = await updateAgent(
-      agentQuery,
+        { id: agent_id },
         { tools, actions },
         {
           updatingUserId: req.user.id,
@@ -154,7 +151,8 @@ router.post('/:agent_id', checkAgentCreate, async (req, res) => {
       logger.error(message, error);
       res.status(500).json({ message });
     }
-});
+  },
+);
 
 /**
  * Deletes an action for a specific agent.
@@ -163,14 +161,19 @@ router.post('/:agent_id', checkAgentCreate, async (req, res) => {
  * @param {string} req.params.action_id - The ID of the action to delete.
  * @returns {Object} 200 - success response - application/json
  */
-router.delete('/:agent_id/:action_id', checkAgentCreate, async (req, res) => {
+router.delete(
+  '/:agent_id/:action_id',
+  canAccessAgentResource({
+    requiredPermission: PermissionBits.EDIT,
+    resourceIdParam: 'agent_id',
+  }),
+  checkAgentCreate,
+  async (req, res) => {
     try {
       const { agent_id, action_id } = req.params;
-    const admin = isAdmin(req);
 
-    // If admin, can delete any agent, otherwise only user's agents
+      // Permissions already validated by middleware - load agent directly
-    const agentQuery = admin ? { id: agent_id } : { id: agent_id, author: req.user.id };
+      const agent = await getAgent({ id: agent_id });
-    const agent = await getAgent(agentQuery);
       if (!agent) {
         return res.status(404).json({ message: 'Agent not found for deleting action' });
       }
@@ -196,19 +199,18 @@ router.delete('/:agent_id/:action_id', checkAgentCreate, async (req, res) => {
 
       // Force version update since actions are being removed
       await updateAgent(
-      agentQuery,
+        { id: agent_id },
         { tools: updatedTools, actions: updatedActions },
         { updatingUserId: req.user.id, forceVersion: true },
       );
-    // If admin, can delete any action, otherwise only user's actions
+      await deleteAction({ action_id });
-    const actionQuery = admin ? { action_id } : { action_id, user: req.user.id };
-    await deleteAction(actionQuery);
       res.status(200).json({ message: 'Action deleted successfully' });
     } catch (error) {
       const message = 'Trouble deleting the Agent Action';
       logger.error(message, error);
       res.status(500).json({ message });
     }
-});
+  },
+);
 
 module.exports = router;

api/server/routes/agents/chat.js

@@ -1,4 +1,5 @@
 const express = require('express');
+const { PermissionBits } = require('@librechat/data-schemas');
 const { generateCheckAccess, skipAgentCheck } = require('@librechat/api');
 const { PermissionTypes, Permissions } = require('librechat-data-provider');
 const {
@@ -7,6 +8,7 @@ const {
   // validateModel,
   validateConvoAccess,
   buildEndpointOption,
+  canAccessAgentFromBody,
 } = require('~/server/middleware');
 const { initializeClient } = require('~/server/services/Endpoints/agents');
 const AgentController = require('~/server/controllers/agents/request');
@@ -23,8 +25,12 @@ const checkAgentAccess = generateCheckAccess({
   skipCheck: skipAgentCheck,
   getRoleByName,
 });
+const checkAgentResourceAccess = canAccessAgentFromBody({
+  requiredPermission: PermissionBits.VIEW,
+});
 
 router.use(checkAgentAccess);
+router.use(checkAgentResourceAccess);
 router.use(validateConvoAccess);
 router.use(buildEndpointOption);
 router.use(setHeaders);

api/server/routes/agents/index.js

@@ -10,6 +10,7 @@ const {
 const { isEnabled } = require('~/server/utils');
 const { v1 } = require('./v1');
 const chat = require('./chat');
+const marketplace = require('./marketplace');
 
 const { LIMIT_CONCURRENT_MESSAGES, LIMIT_MESSAGE_IP, LIMIT_MESSAGE_USER } = process.env ?? {};
 
@@ -37,4 +38,7 @@ if (isEnabled(LIMIT_MESSAGE_USER)) {
 chatRouter.use('/', chat);
 router.use('/chat', chatRouter);
 
+// Add marketplace routes
+router.use('/marketplace', marketplace);
+
 module.exports = router;

api/server/routes/agents/marketplace.js

@@ -0,0 +1,46 @@
+const express = require('express');
+const { requireJwtAuth, checkBan, generateCheckAccess } = require('~/server/middleware');
+const { PermissionTypes, Permissions } = require('librechat-data-provider');
+const marketplace = require('~/server/controllers/agents/marketplace');
+
+const router = express.Router();
+
+// Apply middleware for authentication and authorization
+router.use(requireJwtAuth);
+router.use(checkBan);
+
+// Check if user has permission to use agents
+const checkAgentAccess = generateCheckAccess(PermissionTypes.AGENTS, [Permissions.USE]);
+router.use(checkAgentAccess);
+
+/**
+ * Get all agent categories with counts
+ * @route GET /agents/marketplace/categories
+ */
+router.get('/categories', marketplace.getAgentCategories);
+
+/**
+ * Get promoted/top picks agents with pagination
+ * @route GET /agents/marketplace/promoted
+ */
+router.get('/promoted', marketplace.getPromotedAgents);
+
+/**
+ * Get all agents with pagination (for "all" category)
+ * @route GET /agents/marketplace/all
+ */
+router.get('/all', marketplace.getAllAgents);
+
+/**
+ * Search agents with filters
+ * @route GET /agents/marketplace/search
+ */
+router.get('/search', marketplace.searchAgents);
+
+/**
+ * Get agents by category with pagination
+ * @route GET /agents/marketplace/category/:category
+ */
+router.get('/category/:category', marketplace.getAgentsByCategory);
+
+module.exports = router;

api/server/routes/agents/v1.js

@@ -1,7 +1,8 @@
 const express = require('express');
 const { generateCheckAccess } = require('@librechat/api');
+const { PermissionBits } = require('@librechat/data-schemas');
 const { PermissionTypes, Permissions } = require('librechat-data-provider');
-const { requireJwtAuth } = require('~/server/middleware');
+const { requireJwtAuth, canAccessAgentResource } = require('~/server/middleware');
 const v1 = require('~/server/controllers/agents/v1');
 const { getRoleByName } = require('~/models/Role');
 const actions = require('./actions');
@@ -53,13 +54,38 @@ router.use('/tools', tools);
 router.post('/', checkAgentCreate, v1.createAgent);
 
 /**
- * Retrieves an agent.
+ * Retrieves basic agent information (VIEW permission required).
+ * Returns safe, non-sensitive agent data for viewing purposes.
  * @route GET /agents/:id
  * @param {string} req.params.id - Agent identifier.
- * @returns {Agent} 200 - Success response - application/json
+ * @returns {Agent} 200 - Basic agent info - application/json
  */
-router.get('/:id', checkAgentAccess, v1.getAgent);
+router.get(
+  '/:id',
+  checkAgentAccess,
+  canAccessAgentResource({
+    requiredPermission: PermissionBits.VIEW,
+    resourceIdParam: 'id',
+  }),
+  v1.getAgent,
+);
 
+/**
+ * Retrieves full agent details including sensitive configuration (EDIT permission required).
+ * Returns complete agent data for editing/configuration purposes.
+ * @route GET /agents/:id/expanded
+ * @param {string} req.params.id - Agent identifier.
+ * @returns {Agent} 200 - Full agent details - application/json
+ */
+router.get(
+  '/:id/expanded',
+  checkAgentAccess,
+  canAccessAgentResource({
+    requiredPermission: PermissionBits.EDIT,
+    resourceIdParam: 'id',
+  }),
+  (req, res) => v1.getAgent(req, res, true), // Expanded version
+);
 /**
  * Updates an agent.
  * @route PATCH /agents/:id
@@ -67,7 +93,15 @@ router.get('/:id', checkAgentAccess, v1.getAgent);
  * @param {AgentUpdateParams} req.body - The agent update parameters.
  * @returns {Agent} 200 - Success response - application/json
  */
-router.patch('/:id', checkGlobalAgentShare, v1.updateAgent);
+router.patch(
+  '/:id',
+  checkGlobalAgentShare,
+  canAccessAgentResource({
+    requiredPermission: PermissionBits.EDIT,
+    resourceIdParam: 'id',
+  }),
+  v1.updateAgent,
+);
 
 /**
  * Duplicates an agent.
@@ -75,7 +109,15 @@ router.patch('/:id', checkGlobalAgentShare, v1.updateAgent);
  * @param {string} req.params.id - Agent identifier.
  * @returns {Agent} 201 - Success response - application/json
  */
-router.post('/:id/duplicate', checkAgentCreate, v1.duplicateAgent);
+router.post(
+  '/:id/duplicate',
+  checkAgentCreate,
+  canAccessAgentResource({
+    requiredPermission: PermissionBits.VIEW,
+    resourceIdParam: 'id',
+  }),
+  v1.duplicateAgent,
+);
 
 /**
  * Deletes an agent.
@@ -83,7 +125,15 @@ router.post('/:id/duplicate', checkAgentCreate, v1.duplicateAgent);
  * @param {string} req.params.id - Agent identifier.
  * @returns {Agent} 200 - success response - application/json
  */
-router.delete('/:id', checkAgentCreate, v1.deleteAgent);
+router.delete(
+  '/:id',
+  checkAgentCreate,
+  canAccessAgentResource({
+    requiredPermission: PermissionBits.DELETE,
+    resourceIdParam: 'id',
+  }),
+  v1.deleteAgent,
+);
 
 /**
  * Reverts an agent to a previous version.
@@ -110,6 +160,14 @@ router.get('/', checkAgentAccess, v1.getListAgents);
  * @param {string} [req.body.metadata] - Optional metadata for the agent's avatar.
  * @returns {Object} 200 - success response - application/json
  */
-avatar.post('/:agent_id/avatar/', checkAgentAccess, v1.uploadAgentAvatar);
+avatar.post(
+  '/:agent_id/avatar/',
+  checkAgentAccess,
+  canAccessAgentResource({
+    requiredPermission: PermissionBits.EDIT,
+    resourceIdParam: 'agent_id',
+  }),
+  v1.uploadAgentAvatar,
+);
 
 module.exports = { v1: router, avatar };

api/server/routes/index.js

@@ -1,3 +1,4 @@
+const accessPermissions = require('./accessPermissions');
 const assistants = require('./assistants');
 const categories = require('./categories');
 const tokenizer = require('./tokenizer');
@@ -28,6 +29,7 @@ const user = require('./user');
 const mcp = require('./mcp');
 
 module.exports = {
+  mcp,
   edit,
   auth,
   keys,
@@ -55,5 +57,5 @@ module.exports = {
   assistants,
   categories,
   staticRoute,
-  mcp,
+  accessPermissions,
 };

api/server/routes/oauth.js

@@ -12,6 +12,7 @@ const {
   setBalanceConfig,
   checkDomainAllowed,
 } = require('~/server/middleware');
+const { syncUserEntraGroupMemberships } = require('~/server/services/PermissionService');
 const { setAuthTokens, setOpenIDAuthTokens } = require('~/server/services/AuthService');
 
 const router = express.Router();
@@ -36,6 +37,7 @@ const oauthHandler = async (req, res) => {
       req.user.provider == 'openid' &&
       isEnabled(process.env.OPENID_REUSE_TOKENS) === true
     ) {
+      await syncUserEntraGroupMemberships(req.user, req.user.tokenset.access_token);
       setOpenIDAuthTokens(req.user.tokenset, res);
     } else {
       await setAuthTokens(req.user._id, res);

api/server/services/AppService.interface.spec.js

@@ -1,5 +1,6 @@
 jest.mock('~/models', () => ({
   initializeRoles: jest.fn(),
+  seedDefaultRoles: jest.fn(),
 }));
 jest.mock('~/models/Role', () => ({
   updateAccessPermissions: jest.fn(),

api/server/services/AppService.js

@@ -15,6 +15,7 @@ const {
 const { azureAssistantsDefaults, assistantsConfigSetup } = require('./start/assistants');
 const { initializeAzureBlobService } = require('./Files/Azure/initialize');
 const { initializeFirebase } = require('./Files/Firebase/initialize');
+const { seedDefaultRoles, initializeRoles } = require('~/models');
 const loadCustomConfig = require('./Config/loadCustomConfig');
 const handleRateLimits = require('./Config/handleRateLimits');
 const { loadDefaultInterface } = require('./start/interface');
@@ -24,7 +25,6 @@ const { processModelSpecs } = require('./start/modelSpecs');
 const { initializeS3 } = require('./Files/S3/initialize');
 const { loadAndFormatTools } = require('./ToolService');
 const { isEnabled } = require('~/server/utils');
-const { initializeRoles } = require('~/models');
 const { setCachedTools } = require('./Config');
 const paths = require('~/config/paths');
 
@@ -35,6 +35,7 @@ const paths = require('~/config/paths');
  */
 const AppService = async (app) => {
   await initializeRoles();
+  await seedDefaultRoles();
   /** @type {TCustomConfig} */
   const config = (await loadCustomConfig()) ?? {};
   const configDefaults = getConfigDefaults();

api/server/services/AppService.spec.js

@@ -28,6 +28,7 @@ jest.mock('./Files/Firebase/initialize', () => ({
 }));
 jest.mock('~/models', () => ({
   initializeRoles: jest.fn(),
+  seedDefaultRoles: jest.fn(),
 }));
 jest.mock('~/models/Role', () => ({
   updateAccessPermissions: jest.fn(),

api/server/services/GraphApiService.js

@@ -0,0 +1,525 @@
+const client = require('openid-client');
+const { isEnabled } = require('@librechat/api');
+const { logger } = require('@librechat/data-schemas');
+const { CacheKeys } = require('librechat-data-provider');
+const { Client } = require('@microsoft/microsoft-graph-client');
+const { getOpenIdConfig } = require('~/strategies/openidStrategy');
+const getLogStores = require('~/cache/getLogStores');
+
+/**
+ * @import { TPrincipalSearchResult, TGraphPerson, TGraphUser, TGraphGroup, TGraphPeopleResponse, TGraphUsersResponse, TGraphGroupsResponse } from 'librechat-data-provider'
+ */
+
+/**
+ * Checks if Entra ID principal search feature is enabled based on environment variables and user authentication
+ * @param {Object} user - User object from request
+ * @param {string} user.provider - Authentication provider
+ * @param {string} user.openidId - OpenID subject identifier
+ * @returns {boolean} True if Entra ID principal search is enabled and user is authenticated via OpenID
+ */
+const entraIdPrincipalFeatureEnabled = (user) => {
+  return (
+    isEnabled(process.env.USE_ENTRA_ID_FOR_PEOPLE_SEARCH) &&
+    isEnabled(process.env.OPENID_REUSE_TOKENS) &&
+    user?.provider === 'openid' &&
+    user?.openidId
+  );
+};
+
+/**
+ * Creates a Microsoft Graph client with on-behalf-of token exchange
+ * @param {string} accessToken - OpenID Connect access token from user
+ * @param {string} sub - Subject identifier from token claims
+ * @returns {Promise<Client>} Authenticated Graph API client
+ */
+const createGraphClient = async (accessToken, sub) => {
+  try {
+    // Reason: Use existing OpenID configuration and token exchange pattern from openidStrategy.js
+    const openidConfig = getOpenIdConfig();
+    const exchangedToken = await exchangeTokenForGraphAccess(openidConfig, accessToken, sub);
+
+    const graphClient = Client.init({
+      authProvider: (done) => {
+        done(null, exchangedToken);
+      },
+    });
+
+    return graphClient;
+  } catch (error) {
+    logger.error('[createGraphClient] Error creating Graph client:', error);
+    throw error;
+  }
+};
+
+/**
+ * Exchange OpenID token for Graph API access using on-behalf-of flow
+ * Similar to exchangeAccessTokenIfNeeded in openidStrategy.js but for Graph scopes
+ * @param {Configuration} config - OpenID configuration
+ * @param {string} accessToken - Original access token
+ * @param {string} sub - Subject identifier
+ * @returns {Promise<string>} Graph API access token
+ */
+const exchangeTokenForGraphAccess = async (config, accessToken, sub) => {
+  try {
+    const tokensCache = getLogStores(CacheKeys.OPENID_EXCHANGED_TOKENS);
+    const cacheKey = `${sub}:graph`;
+
+    const cachedToken = await tokensCache.get(cacheKey);
+    if (cachedToken) {
+      return cachedToken.access_token;
+    }
+
+    const graphScopes = process.env.OPENID_GRAPH_SCOPES || 'User.Read,People.Read,Group.Read.All';
+    const scopeString = graphScopes
+      .split(',')
+      .map((scope) => `https://graph.microsoft.com/${scope}`)
+      .join(' ');
+
+    const grantResponse = await client.genericGrantRequest(
+      config,
+      'urn:ietf:params:oauth:grant-type:jwt-bearer',
+      {
+        scope: scopeString,
+        assertion: accessToken,
+        requested_token_use: 'on_behalf_of',
+      },
+    );
+
+    await tokensCache.set(
+      cacheKey,
+      {
+        access_token: grantResponse.access_token,
+      },
+      grantResponse.expires_in * 1000,
+    );
+
+    return grantResponse.access_token;
+  } catch (error) {
+    logger.error('[exchangeTokenForGraphAccess] Token exchange failed:', error);
+    throw error;
+  }
+};
+
+/**
+ * Search for principals (people and groups) using Microsoft Graph API
+ * Uses searchContacts first, then searchUsers and searchGroups to fill remaining slots
+ * @param {string} accessToken - OpenID Connect access token
+ * @param {string} sub - Subject identifier
+ * @param {string} query - Search query string
+ * @param {string} type - Type filter ('users', 'groups', or 'all')
+ * @param {number} limit - Maximum number of results
+ * @returns {Promise<TPrincipalSearchResult[]>} Array of principal search results
+ */
+const searchEntraIdPrincipals = async (accessToken, sub, query, type = 'all', limit = 10) => {
+  try {
+    if (!query || query.trim().length < 2) {
+      return [];
+    }
+    const graphClient = await createGraphClient(accessToken, sub);
+    let allResults = [];
+
+    if (type === 'users' || type === 'all') {
+      const contactResults = await searchContacts(graphClient, query, limit);
+      allResults.push(...contactResults);
+    }
+    if (allResults.length >= limit) {
+      return allResults.slice(0, limit);
+    }
+
+    if (type === 'users') {
+      const userResults = await searchUsers(graphClient, query, limit);
+      allResults.push(...userResults);
+    } else if (type === 'groups') {
+      const groupResults = await searchGroups(graphClient, query, limit);
+      allResults.push(...groupResults);
+    } else if (type === 'all') {
+      const [userResults, groupResults] = await Promise.all([
+        searchUsers(graphClient, query, limit),
+        searchGroups(graphClient, query, limit),
+      ]);
+
+      allResults.push(...userResults, ...groupResults);
+    }
+
+    const seenIds = new Set();
+    const uniqueResults = allResults.filter((result) => {
+      if (seenIds.has(result.idOnTheSource)) {
+        return false;
+      }
+      seenIds.add(result.idOnTheSource);
+      return true;
+    });
+
+    return uniqueResults.slice(0, limit);
+  } catch (error) {
+    logger.error('[searchEntraIdPrincipals] Error searching principals:', error);
+    return [];
+  }
+};
+
+/**
+ * Get current user's Entra ID group memberships from Microsoft Graph
+ * Uses /me/memberOf endpoint to get groups the user is a member of
+ * @param {string} accessToken - OpenID Connect access token
+ * @param {string} sub - Subject identifier
+ * @returns {Promise<Array<string>>} Array of group ID strings (GUIDs)
+ */
+const getUserEntraGroups = async (accessToken, sub) => {
+  try {
+    const graphClient = await createGraphClient(accessToken, sub);
+
+    const groupsResponse = await graphClient.api('/me/memberOf').select('id').get();
+
+    return (groupsResponse.value || []).map((group) => group.id);
+  } catch (error) {
+    logger.error('[getUserEntraGroups] Error fetching user groups:', error);
+    return [];
+  }
+};
+
+/**
+ * Get current user's owned Entra ID groups from Microsoft Graph
+ * Uses /me/ownedObjects/microsoft.graph.group endpoint to get groups the user owns
+ * @param {string} accessToken - OpenID Connect access token
+ * @param {string} sub - Subject identifier
+ * @returns {Promise<Array<string>>} Array of group ID strings (GUIDs)
+ */
+const getUserOwnedEntraGroups = async (accessToken, sub) => {
+  try {
+    const graphClient = await createGraphClient(accessToken, sub);
+
+    const groupsResponse = await graphClient
+      .api('/me/ownedObjects/microsoft.graph.group')
+      .select('id')
+      .get();
+
+    return (groupsResponse.value || []).map((group) => group.id);
+  } catch (error) {
+    logger.error('[getUserOwnedEntraGroups] Error fetching user owned groups:', error);
+    return [];
+  }
+};
+
+/**
+ * Get group members from Microsoft Graph API
+ * Recursively fetches all members using pagination (@odata.nextLink)
+ * @param {string} accessToken - OpenID Connect access token
+ * @param {string} sub - Subject identifier
+ * @param {string} groupId - Entra ID group object ID
+ * @returns {Promise<Array>} Array of member IDs (idOnTheSource values)
+ */
+const getGroupMembers = async (accessToken, sub, groupId) => {
+  try {
+    const graphClient = await createGraphClient(accessToken, sub);
+    const allMembers = [];
+    let nextLink = `/groups/${groupId}/members`;
+
+    while (nextLink) {
+      const membersResponse = await graphClient.api(nextLink).select('id').top(999).get();
+
+      const members = membersResponse.value || [];
+      allMembers.push(...members.map((member) => member.id));
+
+      nextLink = membersResponse['@odata.nextLink']
+        ? membersResponse['@odata.nextLink'].split('/v1.0')[1]
+        : null;
+    }
+
+    return allMembers;
+  } catch (error) {
+    logger.error('[getGroupMembers] Error fetching group members:', error);
+    return [];
+  }
+};
+/**
+ * Get group owners from Microsoft Graph API
+ * Recursively fetches all owners using pagination (@odata.nextLink)
+ * @param {string} accessToken - OpenID Connect access token
+ * @param {string} sub - Subject identifier
+ * @param {string} groupId - Entra ID group object ID
+ * @returns {Promise<Array>} Array of owner IDs (idOnTheSource values)
+ */
+const getGroupOwners = async (accessToken, sub, groupId) => {
+  try {
+    const graphClient = await createGraphClient(accessToken, sub);
+    const allOwners = [];
+    let nextLink = `/groups/${groupId}/owners`;
+
+    while (nextLink) {
+      const ownersResponse = await graphClient.api(nextLink).select('id').top(999).get();
+
+      const owners = ownersResponse.value || [];
+      allOwners.push(...owners.map((member) => member.id));
+
+      nextLink = ownersResponse['@odata.nextLink']
+        ? ownersResponse['@odata.nextLink'].split('/v1.0')[1]
+        : null;
+    }
+
+    return allOwners;
+  } catch (error) {
+    logger.error('[getGroupOwners] Error fetching group owners:', error);
+    return [];
+  }
+};
+/**
+ * Search for contacts (users only) using Microsoft Graph /me/people endpoint
+ * Returns mapped TPrincipalSearchResult objects for users only
+ * @param {Client} graphClient - Authenticated Microsoft Graph client
+ * @param {string} query - Search query string
+ * @param {number} limit - Maximum number of results (default: 10)
+ * @returns {Promise<TPrincipalSearchResult[]>} Array of mapped user contact results
+ */
+const searchContacts = async (graphClient, query, limit = 10) => {
+  try {
+    if (!query || query.trim().length < 2) {
+      return [];
+    }
+    if (
+      process.env.OPENID_GRAPH_SCOPES &&
+      !process.env.OPENID_GRAPH_SCOPES.toLowerCase().includes('people.read')
+    ) {
+      logger.warn('[searchContacts] People.Read scope is not enabled, skipping contact search');
+      return [];
+    }
+    // Reason: Search only for OrganizationUser (person) type, not groups
+    const filter = "personType/subclass eq 'OrganizationUser'";
+
+    let apiCall = graphClient
+      .api('/me/people')
+      .search(`"${query}"`)
+      .select(
+        'id,displayName,givenName,surname,userPrincipalName,jobTitle,department,companyName,scoredEmailAddresses,personType,phones',
+      )
+      .header('ConsistencyLevel', 'eventual')
+      .filter(filter)
+      .top(limit);
+
+    const contactsResponse = await apiCall.get();
+    return (contactsResponse.value || []).map(mapContactToTPrincipalSearchResult);
+  } catch (error) {
+    logger.error('[searchContacts] Error searching contacts:', error);
+    return [];
+  }
+};
+
+/**
+ * Search for users using Microsoft Graph /users endpoint
+ * Returns mapped TPrincipalSearchResult objects
+ * @param {Client} graphClient - Authenticated Microsoft Graph client
+ * @param {string} query - Search query string
+ * @param {number} limit - Maximum number of results (default: 10)
+ * @returns {Promise<TPrincipalSearchResult[]>} Array of mapped user results
+ */
+const searchUsers = async (graphClient, query, limit = 10) => {
+  try {
+    if (!query || query.trim().length < 2) {
+      return [];
+    }
+
+    // Reason: Search users by display name, email, and user principal name
+    const usersResponse = await graphClient
+      .api('/users')
+      .search(
+        `"displayName:${query}" OR "userPrincipalName:${query}" OR "mail:${query}" OR "givenName:${query}" OR "surname:${query}"`,
+      )
+      .select(
+        'id,displayName,givenName,surname,userPrincipalName,jobTitle,department,companyName,mail,phones',
+      )
+      .header('ConsistencyLevel', 'eventual')
+      .top(limit)
+      .get();
+
+    return (usersResponse.value || []).map(mapUserToTPrincipalSearchResult);
+  } catch (error) {
+    logger.error('[searchUsers] Error searching users:', error);
+    return [];
+  }
+};
+
+/**
+ * Search for groups using Microsoft Graph /groups endpoint
+ * Returns mapped TPrincipalSearchResult objects, includes all group types
+ * @param {Client} graphClient - Authenticated Microsoft Graph client
+ * @param {string} query - Search query string
+ * @param {number} limit - Maximum number of results (default: 10)
+ * @returns {Promise<TPrincipalSearchResult[]>} Array of mapped group results
+ */
+const searchGroups = async (graphClient, query, limit = 10) => {
+  try {
+    if (!query || query.trim().length < 2) {
+      return [];
+    }
+
+    // Reason: Search all groups by display name and email without filtering group types
+    const groupsResponse = await graphClient
+      .api('/groups')
+      .search(`"displayName:${query}" OR "mail:${query}" OR "mailNickname:${query}"`)
+      .select('id,displayName,mail,mailNickname,description,groupTypes,resourceProvisioningOptions')
+      .header('ConsistencyLevel', 'eventual')
+      .top(limit)
+      .get();
+
+    return (groupsResponse.value || []).map(mapGroupToTPrincipalSearchResult);
+  } catch (error) {
+    logger.error('[searchGroups] Error searching groups:', error);
+    return [];
+  }
+};
+
+/**
+ * Test Graph API connectivity and permissions
+ * @param {string} accessToken - OpenID Connect access token
+ * @param {string} sub - Subject identifier
+ * @returns {Promise<Object>} Test results with available permissions
+ */
+const testGraphApiAccess = async (accessToken, sub) => {
+  try {
+    const graphClient = await createGraphClient(accessToken, sub);
+    const results = {
+      userAccess: false,
+      peopleAccess: false,
+      groupsAccess: false,
+      usersEndpointAccess: false,
+      groupsEndpointAccess: false,
+      errors: [],
+    };
+
+    // Test User.Read permission
+    try {
+      await graphClient.api('/me').select('id,displayName').get();
+      results.userAccess = true;
+    } catch (error) {
+      results.errors.push(`User.Read: ${error.message}`);
+    }
+
+    // Test People.Read permission with OrganizationUser filter
+    try {
+      await graphClient
+        .api('/me/people')
+        .filter("personType/subclass eq 'OrganizationUser'")
+        .top(1)
+        .get();
+      results.peopleAccess = true;
+    } catch (error) {
+      results.errors.push(`People.Read (OrganizationUser): ${error.message}`);
+    }
+
+    // Test People.Read permission with UnifiedGroup filter
+    try {
+      await graphClient
+        .api('/me/people')
+        .filter("personType/subclass eq 'UnifiedGroup'")
+        .top(1)
+        .get();
+      results.groupsAccess = true;
+    } catch (error) {
+      results.errors.push(`People.Read (UnifiedGroup): ${error.message}`);
+    }
+
+    // Test /users endpoint access (requires User.Read.All or similar)
+    try {
+      await graphClient
+        .api('/users')
+        .search('"displayName:test"')
+        .select('id,displayName,userPrincipalName')
+        .top(1)
+        .get();
+      results.usersEndpointAccess = true;
+    } catch (error) {
+      results.errors.push(`Users endpoint: ${error.message}`);
+    }
+
+    // Test /groups endpoint access (requires Group.Read.All or similar)
+    try {
+      await graphClient
+        .api('/groups')
+        .search('"displayName:test"')
+        .select('id,displayName,mail')
+        .top(1)
+        .get();
+      results.groupsEndpointAccess = true;
+    } catch (error) {
+      results.errors.push(`Groups endpoint: ${error.message}`);
+    }
+
+    return results;
+  } catch (error) {
+    logger.error('[testGraphApiAccess] Error testing Graph API access:', error);
+    return {
+      userAccess: false,
+      peopleAccess: false,
+      groupsAccess: false,
+      usersEndpointAccess: false,
+      groupsEndpointAccess: false,
+      errors: [error.message],
+    };
+  }
+};
+
+/**
+ * Map Graph API user object to TPrincipalSearchResult format
+ * @param {TGraphUser} user - Raw user object from Graph API
+ * @returns {TPrincipalSearchResult} Mapped user result
+ */
+const mapUserToTPrincipalSearchResult = (user) => {
+  return {
+    id: null,
+    type: 'user',
+    name: user.displayName,
+    email: user.mail || user.userPrincipalName,
+    username: user.userPrincipalName,
+    source: 'entra',
+    idOnTheSource: user.id,
+  };
+};
+
+/**
+ * Map Graph API group object to TPrincipalSearchResult format
+ * @param {TGraphGroup} group - Raw group object from Graph API
+ * @returns {TPrincipalSearchResult} Mapped group result
+ */
+const mapGroupToTPrincipalSearchResult = (group) => {
+  return {
+    id: null,
+    type: 'group',
+    name: group.displayName,
+    email: group.mail || group.userPrincipalName,
+    description: group.description,
+    source: 'entra',
+    idOnTheSource: group.id,
+  };
+};
+
+/**
+ * Map Graph API /me/people contact object to TPrincipalSearchResult format
+ * Handles both user and group contacts from the people endpoint
+ * @param {TGraphPerson} contact - Raw contact object from Graph API /me/people
+ * @returns {TPrincipalSearchResult} Mapped contact result
+ */
+const mapContactToTPrincipalSearchResult = (contact) => {
+  const isGroup = contact.personType?.class === 'Group';
+  const primaryEmail = contact.scoredEmailAddresses?.[0]?.address;
+
+  return {
+    id: null,
+    type: isGroup ? 'group' : 'user',
+    name: contact.displayName,
+    email: primaryEmail,
+    username: !isGroup ? contact.userPrincipalName : undefined,
+    source: 'entra',
+    idOnTheSource: contact.id,
+  };
+};
+
+module.exports = {
+  getGroupMembers,
+  getGroupOwners,
+  createGraphClient,
+  getUserEntraGroups,
+  getUserOwnedEntraGroups,
+  testGraphApiAccess,
+  searchEntraIdPrincipals,
+  exchangeTokenForGraphAccess,
+  entraIdPrincipalFeatureEnabled,
+};

api/server/services/GraphApiService.spec.js

@@ -0,0 +1,720 @@
+jest.mock('@microsoft/microsoft-graph-client');
+jest.mock('~/strategies/openidStrategy');
+jest.mock('~/cache/getLogStores');
+jest.mock('@librechat/data-schemas', () => ({
+  ...jest.requireActual('@librechat/data-schemas'),
+  logger: {
+    error: jest.fn(),
+    debug: jest.fn(),
+  },
+}));
+jest.mock('~/config', () => ({
+  logger: {
+    error: jest.fn(),
+    debug: jest.fn(),
+  },
+  createAxiosInstance: jest.fn(() => ({
+    create: jest.fn(),
+    defaults: {},
+  })),
+}));
+jest.mock('~/utils', () => ({
+  logAxiosError: jest.fn(),
+}));
+
+jest.mock('~/server/services/Config', () => ({}));
+jest.mock('~/server/services/Files/strategies', () => ({
+  getStrategyFunctions: jest.fn(),
+}));
+
+const mongoose = require('mongoose');
+const client = require('openid-client');
+const { MongoMemoryServer } = require('mongodb-memory-server');
+const { Client } = require('@microsoft/microsoft-graph-client');
+const { getOpenIdConfig } = require('~/strategies/openidStrategy');
+const getLogStores = require('~/cache/getLogStores');
+const GraphApiService = require('./GraphApiService');
+
+describe('GraphApiService', () => {
+  let mongoServer;
+  let mockGraphClient;
+  let mockTokensCache;
+  let mockOpenIdConfig;
+
+  beforeAll(async () => {
+    mongoServer = await MongoMemoryServer.create();
+    const mongoUri = mongoServer.getUri();
+    await mongoose.connect(mongoUri);
+  });
+
+  afterAll(async () => {
+    await mongoose.disconnect();
+    await mongoServer.stop();
+  });
+
+  afterEach(() => {
+    // Clean up environment variables
+    delete process.env.OPENID_GRAPH_SCOPES;
+  });
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    await mongoose.connection.dropDatabase();
+
+    // Set up environment variable for People.Read scope
+    process.env.OPENID_GRAPH_SCOPES = 'User.Read,People.Read,Group.Read.All';
+
+    // Mock Graph client
+    mockGraphClient = {
+      api: jest.fn().mockReturnThis(),
+      search: jest.fn().mockReturnThis(),
+      filter: jest.fn().mockReturnThis(),
+      select: jest.fn().mockReturnThis(),
+      header: jest.fn().mockReturnThis(),
+      top: jest.fn().mockReturnThis(),
+      get: jest.fn(),
+    };
+
+    Client.init.mockReturnValue(mockGraphClient);
+
+    // Mock tokens cache
+    mockTokensCache = {
+      get: jest.fn(),
+      set: jest.fn(),
+    };
+    getLogStores.mockReturnValue(mockTokensCache);
+
+    // Mock OpenID config
+    mockOpenIdConfig = {
+      client_id: 'test-client-id',
+      issuer: 'https://test-issuer.com',
+    };
+    getOpenIdConfig.mockReturnValue(mockOpenIdConfig);
+
+    // Mock openid-client (using the existing jest mock configuration)
+    if (client.genericGrantRequest) {
+      client.genericGrantRequest.mockResolvedValue({
+        access_token: 'mocked-graph-token',
+        expires_in: 3600,
+      });
+    }
+  });
+
+  describe('Dependency Contract Tests', () => {
+    it('should fail if getOpenIdConfig interface changes', () => {
+      // Reason: Ensure getOpenIdConfig returns expected structure
+      const config = getOpenIdConfig();
+
+      expect(config).toBeDefined();
+      expect(typeof config).toBe('object');
+      // Add specific property checks that GraphApiService depends on
+      expect(config).toHaveProperty('client_id');
+      expect(config).toHaveProperty('issuer');
+
+      // Ensure the function is callable
+      expect(typeof getOpenIdConfig).toBe('function');
+    });
+
+    it('should fail if openid-client.genericGrantRequest interface changes', () => {
+      // Reason: Ensure client.genericGrantRequest maintains expected signature
+      if (client.genericGrantRequest) {
+        expect(typeof client.genericGrantRequest).toBe('function');
+
+        // Test that it accepts the expected parameters
+        const mockCall = client.genericGrantRequest(
+          mockOpenIdConfig,
+          'urn:ietf:params:oauth:grant-type:jwt-bearer',
+          {
+            scope: 'test-scope',
+            assertion: 'test-token',
+            requested_token_use: 'on_behalf_of',
+          },
+        );
+
+        expect(mockCall).toBeDefined();
+      }
+    });
+
+    it('should fail if Microsoft Graph Client interface changes', () => {
+      // Reason: Ensure Graph Client maintains expected fluent API
+      expect(typeof Client.init).toBe('function');
+
+      const client = Client.init({ authProvider: jest.fn() });
+      expect(client).toHaveProperty('api');
+      expect(typeof client.api).toBe('function');
+    });
+  });
+
+  describe('createGraphClient', () => {
+    it('should create graph client with exchanged token', async () => {
+      const accessToken = 'test-access-token';
+      const sub = 'test-user-id';
+
+      const result = await GraphApiService.createGraphClient(accessToken, sub);
+
+      expect(getOpenIdConfig).toHaveBeenCalled();
+      expect(Client.init).toHaveBeenCalledWith({
+        authProvider: expect.any(Function),
+      });
+      expect(result).toBe(mockGraphClient);
+    });
+
+    it('should handle token exchange errors gracefully', async () => {
+      if (client.genericGrantRequest) {
+        client.genericGrantRequest.mockRejectedValue(new Error('Token exchange failed'));
+      }
+
+      await expect(GraphApiService.createGraphClient('invalid-token', 'test-user')).rejects.toThrow(
+        'Token exchange failed',
+      );
+    });
+  });
+
+  describe('exchangeTokenForGraphAccess', () => {
+    it('should return cached token if available', async () => {
+      const cachedToken = { access_token: 'cached-token' };
+      mockTokensCache.get.mockResolvedValue(cachedToken);
+
+      const result = await GraphApiService.exchangeTokenForGraphAccess(
+        mockOpenIdConfig,
+        'test-token',
+        'test-user',
+      );
+
+      expect(result).toBe('cached-token');
+      expect(mockTokensCache.get).toHaveBeenCalledWith('test-user:graph');
+      if (client.genericGrantRequest) {
+        expect(client.genericGrantRequest).not.toHaveBeenCalled();
+      }
+    });
+
+    it('should exchange token and cache result', async () => {
+      mockTokensCache.get.mockResolvedValue(null);
+
+      const result = await GraphApiService.exchangeTokenForGraphAccess(
+        mockOpenIdConfig,
+        'test-token',
+        'test-user',
+      );
+
+      if (client.genericGrantRequest) {
+        expect(client.genericGrantRequest).toHaveBeenCalledWith(
+          mockOpenIdConfig,
+          'urn:ietf:params:oauth:grant-type:jwt-bearer',
+          {
+            scope:
+              'https://graph.microsoft.com/User.Read https://graph.microsoft.com/People.Read https://graph.microsoft.com/Group.Read.All',
+            assertion: 'test-token',
+            requested_token_use: 'on_behalf_of',
+          },
+        );
+      }
+
+      expect(mockTokensCache.set).toHaveBeenCalledWith(
+        'test-user:graph',
+        { access_token: 'mocked-graph-token' },
+        3600000,
+      );
+
+      expect(result).toBe('mocked-graph-token');
+    });
+
+    it('should use custom scopes from environment', async () => {
+      const originalEnv = process.env.OPENID_GRAPH_SCOPES;
+      process.env.OPENID_GRAPH_SCOPES = 'Custom.Read,Custom.Write';
+
+      mockTokensCache.get.mockResolvedValue(null);
+
+      await GraphApiService.exchangeTokenForGraphAccess(
+        mockOpenIdConfig,
+        'test-token',
+        'test-user',
+      );
+
+      if (client.genericGrantRequest) {
+        expect(client.genericGrantRequest).toHaveBeenCalledWith(
+          mockOpenIdConfig,
+          'urn:ietf:params:oauth:grant-type:jwt-bearer',
+          {
+            scope:
+              'https://graph.microsoft.com/Custom.Read https://graph.microsoft.com/Custom.Write',
+            assertion: 'test-token',
+            requested_token_use: 'on_behalf_of',
+          },
+        );
+      }
+
+      process.env.OPENID_GRAPH_SCOPES = originalEnv;
+    });
+  });
+
+  describe('searchEntraIdPrincipals', () => {
+    // Mock data used by multiple tests
+    const mockContactsResponse = {
+      value: [
+        {
+          id: 'contact-user-1',
+          displayName: 'John Doe',
+          userPrincipalName: 'john@company.com',
+          mail: 'john@company.com',
+          personType: { class: 'Person', subclass: 'OrganizationUser' },
+          scoredEmailAddresses: [{ address: 'john@company.com', relevanceScore: 0.9 }],
+        },
+        {
+          id: 'contact-group-1',
+          displayName: 'Marketing Team',
+          mail: 'marketing@company.com',
+          personType: { class: 'Group', subclass: 'UnifiedGroup' },
+          scoredEmailAddresses: [{ address: 'marketing@company.com', relevanceScore: 0.8 }],
+        },
+      ],
+    };
+
+    const mockUsersResponse = {
+      value: [
+        {
+          id: 'dir-user-1',
+          displayName: 'Jane Smith',
+          userPrincipalName: 'jane@company.com',
+          mail: 'jane@company.com',
+        },
+      ],
+    };
+
+    const mockGroupsResponse = {
+      value: [
+        {
+          id: 'dir-group-1',
+          displayName: 'Development Team',
+          mail: 'dev@company.com',
+        },
+      ],
+    };
+
+    beforeEach(() => {
+      // Reset mock call history for each test
+      jest.clearAllMocks();
+
+      // Re-apply the Client.init mock after clearAllMocks
+      Client.init.mockReturnValue(mockGraphClient);
+
+      // Re-apply openid-client mock
+      if (client.genericGrantRequest) {
+        client.genericGrantRequest.mockResolvedValue({
+          access_token: 'mocked-graph-token',
+          expires_in: 3600,
+        });
+      }
+
+      // Re-apply cache mock
+      mockTokensCache.get.mockResolvedValue(null); // Force token exchange
+      mockTokensCache.set.mockResolvedValue();
+      getLogStores.mockReturnValue(mockTokensCache);
+      getOpenIdConfig.mockReturnValue(mockOpenIdConfig);
+    });
+
+    it('should return empty results for short queries', async () => {
+      const result = await GraphApiService.searchEntraIdPrincipals('token', 'user', 'a', 'all', 10);
+
+      expect(result).toEqual([]);
+      expect(mockGraphClient.api).not.toHaveBeenCalled();
+    });
+
+    it('should search contacts first and additional users for users type', async () => {
+      // Mock responses for this specific test
+      const contactsFilteredResponse = {
+        value: [
+          {
+            id: 'contact-user-1',
+            displayName: 'John Doe',
+            userPrincipalName: 'john@company.com',
+            mail: 'john@company.com',
+            personType: { class: 'Person', subclass: 'OrganizationUser' },
+            scoredEmailAddresses: [{ address: 'john@company.com', relevanceScore: 0.9 }],
+          },
+        ],
+      };
+
+      mockGraphClient.get
+        .mockResolvedValueOnce(contactsFilteredResponse) // contacts call
+        .mockResolvedValueOnce(mockUsersResponse); // users call
+
+      const result = await GraphApiService.searchEntraIdPrincipals(
+        'token',
+        'user',
+        'john',
+        'users',
+        10,
+      );
+
+      // Should call contacts first with user filter
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/me/people');
+      expect(mockGraphClient.search).toHaveBeenCalledWith('"john"');
+      expect(mockGraphClient.filter).toHaveBeenCalledWith(
+        "personType/subclass eq 'OrganizationUser'",
+      );
+
+      // Should call users endpoint for additional results
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/users');
+      expect(mockGraphClient.search).toHaveBeenCalledWith(
+        '"displayName:john" OR "userPrincipalName:john" OR "mail:john" OR "givenName:john" OR "surname:john"',
+      );
+
+      // Should return TPrincipalSearchResult array
+      expect(Array.isArray(result)).toBe(true);
+      expect(result).toHaveLength(2); // 1 from contacts + 1 from users
+      expect(result[0]).toMatchObject({
+        id: null,
+        type: 'user',
+        name: 'John Doe',
+        email: 'john@company.com',
+        source: 'entra',
+        idOnTheSource: 'contact-user-1',
+      });
+    });
+
+    it('should search groups endpoint only for groups type', async () => {
+      // Mock responses for this specific test - only groups endpoint called
+      mockGraphClient.get.mockResolvedValueOnce(mockGroupsResponse); // only groups call
+
+      const result = await GraphApiService.searchEntraIdPrincipals(
+        'token',
+        'user',
+        'team',
+        'groups',
+        10,
+      );
+
+      // Should NOT call contacts for groups type
+      expect(mockGraphClient.api).not.toHaveBeenCalledWith('/me/people');
+
+      // Should call groups endpoint only
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/groups');
+      expect(mockGraphClient.search).toHaveBeenCalledWith(
+        '"displayName:team" OR "mail:team" OR "mailNickname:team"',
+      );
+
+      expect(Array.isArray(result)).toBe(true);
+      expect(result).toHaveLength(1); // 1 from groups only
+    });
+
+    it('should search all endpoints for all type', async () => {
+      // Mock responses for this specific test
+      mockGraphClient.get
+        .mockResolvedValueOnce(mockContactsResponse) // contacts call (both user and group)
+        .mockResolvedValueOnce(mockUsersResponse) // users call
+        .mockResolvedValueOnce(mockGroupsResponse); // groups call
+
+      const result = await GraphApiService.searchEntraIdPrincipals(
+        'token',
+        'user',
+        'test',
+        'all',
+        10,
+      );
+
+      // Should call contacts first with user filter
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/me/people');
+      expect(mockGraphClient.search).toHaveBeenCalledWith('"test"');
+      expect(mockGraphClient.filter).toHaveBeenCalledWith(
+        "personType/subclass eq 'OrganizationUser'",
+      );
+
+      // Should call both users and groups endpoints
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/users');
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/groups');
+
+      expect(Array.isArray(result)).toBe(true);
+      expect(result).toHaveLength(4); // 2 from contacts + 1 from users + 1 from groups
+    });
+
+    it('should early exit if contacts reach limit', async () => {
+      // Mock contacts to return exactly the limit
+      const limitedContactsResponse = {
+        value: Array(10).fill({
+          id: 'contact-1',
+          displayName: 'Contact User',
+          mail: 'contact@company.com',
+          personType: { class: 'Person', subclass: 'OrganizationUser' },
+        }),
+      };
+
+      mockGraphClient.get.mockResolvedValueOnce(limitedContactsResponse);
+
+      const result = await GraphApiService.searchEntraIdPrincipals(
+        'token',
+        'user',
+        'test',
+        'all',
+        10,
+      );
+
+      // Should call contacts first
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/me/people');
+      expect(mockGraphClient.search).toHaveBeenCalledWith('"test"');
+      // Should not call users endpoint since limit was reached
+      expect(mockGraphClient.api).not.toHaveBeenCalledWith('/users');
+
+      expect(result).toHaveLength(10);
+    });
+
+    it('should deduplicate results based on idOnTheSource', async () => {
+      // Mock responses with duplicate IDs
+      const duplicateContactsResponse = {
+        value: [
+          {
+            id: 'duplicate-id',
+            displayName: 'John Doe',
+            mail: 'john@company.com',
+            personType: { class: 'Person', subclass: 'OrganizationUser' },
+          },
+        ],
+      };
+
+      const duplicateUsersResponse = {
+        value: [
+          {
+            id: 'duplicate-id', // Same ID as contact
+            displayName: 'John Doe',
+            mail: 'john@company.com',
+          },
+        ],
+      };
+
+      mockGraphClient.get
+        .mockResolvedValueOnce(duplicateContactsResponse)
+        .mockResolvedValueOnce(duplicateUsersResponse);
+
+      const result = await GraphApiService.searchEntraIdPrincipals(
+        'token',
+        'user',
+        'john',
+        'users',
+        10,
+      );
+
+      // Should only return one result despite duplicate IDs
+      expect(result).toHaveLength(1);
+      expect(result[0].idOnTheSource).toBe('duplicate-id');
+    });
+
+    it('should handle Graph API errors gracefully', async () => {
+      mockGraphClient.get.mockRejectedValue(new Error('Graph API error'));
+
+      const result = await GraphApiService.searchEntraIdPrincipals(
+        'token',
+        'user',
+        'test',
+        'all',
+        10,
+      );
+
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('getUserEntraGroups', () => {
+    it('should fetch user groups from memberOf endpoint', async () => {
+      const mockGroupsResponse = {
+        value: [
+          {
+            id: 'group-1',
+          },
+          {
+            id: 'group-2',
+          },
+        ],
+      };
+
+      mockGraphClient.get.mockResolvedValue(mockGroupsResponse);
+
+      const result = await GraphApiService.getUserEntraGroups('token', 'user');
+
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/me/memberOf');
+      expect(mockGraphClient.select).toHaveBeenCalledWith('id');
+
+      expect(result).toHaveLength(2);
+      expect(result).toEqual(['group-1', 'group-2']);
+    });
+
+    it('should return empty array on error', async () => {
+      mockGraphClient.get.mockRejectedValue(new Error('API error'));
+
+      const result = await GraphApiService.getUserEntraGroups('token', 'user');
+
+      expect(result).toEqual([]);
+    });
+
+    it('should handle empty response', async () => {
+      const mockGroupsResponse = {
+        value: [],
+      };
+
+      mockGraphClient.get.mockResolvedValue(mockGroupsResponse);
+
+      const result = await GraphApiService.getUserEntraGroups('token', 'user');
+
+      expect(result).toEqual([]);
+    });
+
+    it('should handle missing value property', async () => {
+      mockGraphClient.get.mockResolvedValue({});
+
+      const result = await GraphApiService.getUserEntraGroups('token', 'user');
+
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('testGraphApiAccess', () => {
+    beforeEach(() => {
+      jest.clearAllMocks();
+    });
+
+    it('should test all permissions and return success results', async () => {
+      // Mock successful responses for all tests
+      mockGraphClient.get
+        .mockResolvedValueOnce({ id: 'user-123', displayName: 'Test User' }) // /me test
+        .mockResolvedValueOnce({ value: [] }) // people OrganizationUser test
+        .mockResolvedValueOnce({ value: [] }) // people UnifiedGroup test
+        .mockResolvedValueOnce({ value: [] }) // /users endpoint test
+        .mockResolvedValueOnce({ value: [] }); // /groups endpoint test
+
+      const result = await GraphApiService.testGraphApiAccess('token', 'user');
+
+      expect(result).toEqual({
+        userAccess: true,
+        peopleAccess: true,
+        groupsAccess: true,
+        usersEndpointAccess: true,
+        groupsEndpointAccess: true,
+        errors: [],
+      });
+
+      // Verify all endpoints were tested
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/me');
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/me/people');
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/users');
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/groups');
+      expect(mockGraphClient.filter).toHaveBeenCalledWith(
+        "personType/subclass eq 'OrganizationUser'",
+      );
+      expect(mockGraphClient.filter).toHaveBeenCalledWith("personType/subclass eq 'UnifiedGroup'");
+      expect(mockGraphClient.search).toHaveBeenCalledWith('"displayName:test"');
+    });
+
+    it('should handle partial failures and record errors', async () => {
+      // Mock mixed success/failure responses
+      mockGraphClient.get
+        .mockResolvedValueOnce({ id: 'user-123', displayName: 'Test User' }) // /me success
+        .mockRejectedValueOnce(new Error('People access denied')) // people OrganizationUser fail
+        .mockResolvedValueOnce({ value: [] }) // people UnifiedGroup success
+        .mockRejectedValueOnce(new Error('Users endpoint access denied')) // /users fail
+        .mockResolvedValueOnce({ value: [] }); // /groups success
+
+      const result = await GraphApiService.testGraphApiAccess('token', 'user');
+
+      expect(result).toEqual({
+        userAccess: true,
+        peopleAccess: false,
+        groupsAccess: true,
+        usersEndpointAccess: false,
+        groupsEndpointAccess: true,
+        errors: [
+          'People.Read (OrganizationUser): People access denied',
+          'Users endpoint: Users endpoint access denied',
+        ],
+      });
+    });
+
+    it('should handle complete Graph client creation failure', async () => {
+      // Mock token exchange failure to test error handling
+      if (client.genericGrantRequest) {
+        client.genericGrantRequest.mockRejectedValue(new Error('Token exchange failed'));
+      }
+
+      const result = await GraphApiService.testGraphApiAccess('invalid-token', 'user');
+
+      expect(result).toEqual({
+        userAccess: false,
+        peopleAccess: false,
+        groupsAccess: false,
+        usersEndpointAccess: false,
+        groupsEndpointAccess: false,
+        errors: ['Token exchange failed'],
+      });
+    });
+
+    it('should record all permission errors', async () => {
+      // Mock all requests to fail
+      mockGraphClient.get
+        .mockRejectedValueOnce(new Error('User.Read denied'))
+        .mockRejectedValueOnce(new Error('People.Read OrganizationUser denied'))
+        .mockRejectedValueOnce(new Error('People.Read UnifiedGroup denied'))
+        .mockRejectedValueOnce(new Error('Users directory access denied'))
+        .mockRejectedValueOnce(new Error('Groups directory access denied'));
+
+      const result = await GraphApiService.testGraphApiAccess('token', 'user');
+
+      expect(result).toEqual({
+        userAccess: false,
+        peopleAccess: false,
+        groupsAccess: false,
+        usersEndpointAccess: false,
+        groupsEndpointAccess: false,
+        errors: [
+          'User.Read: User.Read denied',
+          'People.Read (OrganizationUser): People.Read OrganizationUser denied',
+          'People.Read (UnifiedGroup): People.Read UnifiedGroup denied',
+          'Users endpoint: Users directory access denied',
+          'Groups endpoint: Groups directory access denied',
+        ],
+      });
+    });
+
+    it('should test new endpoints with correct search patterns', async () => {
+      // Mock successful responses for endpoint testing
+      mockGraphClient.get
+        .mockResolvedValueOnce({ id: 'user-123', displayName: 'Test User' }) // /me
+        .mockResolvedValueOnce({ value: [] }) // people OrganizationUser
+        .mockResolvedValueOnce({ value: [] }) // people UnifiedGroup
+        .mockResolvedValueOnce({ value: [] }) // /users
+        .mockResolvedValueOnce({ value: [] }); // /groups
+
+      await GraphApiService.testGraphApiAccess('token', 'user');
+
+      // Verify /users endpoint test
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/users');
+      expect(mockGraphClient.search).toHaveBeenCalledWith('"displayName:test"');
+      expect(mockGraphClient.select).toHaveBeenCalledWith('id,displayName,userPrincipalName');
+
+      // Verify /groups endpoint test
+      expect(mockGraphClient.api).toHaveBeenCalledWith('/groups');
+      expect(mockGraphClient.select).toHaveBeenCalledWith('id,displayName,mail');
+    });
+
+    it('should handle endpoint-specific permission failures', async () => {
+      // Mock specific endpoint failures
+      mockGraphClient.get
+        .mockResolvedValueOnce({ id: 'user-123', displayName: 'Test User' }) // /me success
+        .mockResolvedValueOnce({ value: [] }) // people OrganizationUser success
+        .mockResolvedValueOnce({ value: [] }) // people UnifiedGroup success
+        .mockRejectedValueOnce(new Error('Insufficient privileges')) // /users fail (User.Read.All needed)
+        .mockRejectedValueOnce(new Error('Access denied to groups')); // /groups fail (Group.Read.All needed)
+
+      const result = await GraphApiService.testGraphApiAccess('token', 'user');
+
+      expect(result).toEqual({
+        userAccess: true,
+        peopleAccess: true,
+        groupsAccess: true,
+        usersEndpointAccess: false,
+        groupsEndpointAccess: false,
+        errors: [
+          'Users endpoint: Insufficient privileges',
+          'Groups endpoint: Access denied to groups',
+        ],
+      });
+    });
+  });
+});

api/server/services/PermissionService.js

@@ -0,0 +1,721 @@
+const mongoose = require('mongoose');
+const { getTransactionSupport, logger } = require('@librechat/data-schemas');
+const { isEnabled } = require('~/server/utils');
+const {
+  entraIdPrincipalFeatureEnabled,
+  getUserEntraGroups,
+  getUserOwnedEntraGroups,
+  getGroupMembers,
+  getGroupOwners,
+} = require('~/server/services/GraphApiService');
+const {
+  findGroupByExternalId,
+  findRoleByIdentifier,
+  getUserPrincipals,
+  createGroup,
+  createUser,
+  updateUser,
+  findUser,
+  grantPermission: grantPermissionACL,
+  findAccessibleResources: findAccessibleResourcesACL,
+  hasPermission,
+  getEffectivePermissions: getEffectivePermissionsACL,
+  findEntriesByPrincipalsAndResource,
+} = require('~/models');
+const { AclEntry, AccessRole, Group } = require('~/db/models');
+
+/** @type {boolean|null} */
+let transactionSupportCache = null;
+
+/**
+ * @import { TPrincipal } from 'librechat-data-provider'
+ */
+/**
+ * Grant a permission to a principal for a resource using a role
+ * @param {Object} params - Parameters for granting role-based permission
+ * @param {string} params.principalType - 'user', 'group', or 'public'
+ * @param {string|mongoose.Types.ObjectId|null} params.principalId - The ID of the principal (null for 'public')
+ * @param {string} params.resourceType - Type of resource (e.g., 'agent')
+ * @param {string|mongoose.Types.ObjectId} params.resourceId - The ID of the resource
+ * @param {string} params.accessRoleId - The ID of the role (e.g., 'agent_viewer', 'agent_editor')
+ * @param {string|mongoose.Types.ObjectId} params.grantedBy - User ID granting the permission
+ * @param {mongoose.ClientSession} [params.session] - Optional MongoDB session for transactions
+ * @returns {Promise<Object>} The created or updated ACL entry
+ */
+const grantPermission = async ({
+  principalType,
+  principalId,
+  resourceType,
+  resourceId,
+  accessRoleId,
+  grantedBy,
+  session,
+}) => {
+  try {
+    if (!['user', 'group', 'public'].includes(principalType)) {
+      throw new Error(`Invalid principal type: ${principalType}`);
+    }
+
+    if (principalType !== 'public' && !principalId) {
+      throw new Error('Principal ID is required for user and group principals');
+    }
+
+    if (principalId && !mongoose.Types.ObjectId.isValid(principalId)) {
+      throw new Error(`Invalid principal ID: ${principalId}`);
+    }
+
+    if (!resourceId || !mongoose.Types.ObjectId.isValid(resourceId)) {
+      throw new Error(`Invalid resource ID: ${resourceId}`);
+    }
+
+    // Get the role to determine permission bits
+    const role = await findRoleByIdentifier(accessRoleId);
+    if (!role) {
+      throw new Error(`Role ${accessRoleId} not found`);
+    }
+
+    // Ensure the role is for the correct resource type
+    if (role.resourceType !== resourceType) {
+      throw new Error(
+        `Role ${accessRoleId} is for ${role.resourceType} resources, not ${resourceType}`,
+      );
+    }
+    return await grantPermissionACL(
+      principalType,
+      principalId,
+      resourceType,
+      resourceId,
+      role.permBits,
+      grantedBy,
+      session,
+      role._id,
+    );
+  } catch (error) {
+    logger.error(`[PermissionService.grantPermission] Error: ${error.message}`);
+    throw error;
+  }
+};
+
+/**
+ * Check if a user has specific permission bits on a resource
+ * @param {Object} params - Parameters for checking permissions
+ * @param {string|mongoose.Types.ObjectId} params.userId - The ID of the user
+ * @param {string} params.resourceType - Type of resource (e.g., 'agent')
+ * @param {string|mongoose.Types.ObjectId} params.resourceId - The ID of the resource
+ * @param {number} params.requiredPermissions - The permission bits required (e.g., 1 for VIEW, 3 for VIEW+EDIT)
+ * @returns {Promise<boolean>} Whether the user has the required permission bits
+ */
+const checkPermission = async ({ userId, resourceType, resourceId, requiredPermission }) => {
+  try {
+    if (typeof requiredPermission !== 'number' || requiredPermission < 1) {
+      throw new Error('requiredPermission must be a positive number');
+    }
+
+    // Get all principals for the user (user + groups + public)
+    const principals = await getUserPrincipals(userId);
+
+    if (principals.length === 0) {
+      return false;
+    }
+
+    return await hasPermission(principals, resourceType, resourceId, requiredPermission);
+  } catch (error) {
+    logger.error(`[PermissionService.checkPermission] Error: ${error.message}`);
+    // Re-throw validation errors
+    if (error.message.includes('requiredPermission must be')) {
+      throw error;
+    }
+    return false;
+  }
+};
+
+/**
+ * Get effective permission bitmask for a user on a resource
+ * @param {Object} params - Parameters for getting effective permissions
+ * @param {string|mongoose.Types.ObjectId} params.userId - The ID of the user
+ * @param {string} params.resourceType - Type of resource (e.g., 'agent')
+ * @param {string|mongoose.Types.ObjectId} params.resourceId - The ID of the resource
+ * @returns {Promise<number>} Effective permission bitmask
+ */
+const getEffectivePermissions = async ({ userId, resourceType, resourceId }) => {
+  try {
+    // Get all principals for the user (user + groups + public)
+    const principals = await getUserPrincipals(userId);
+
+    if (principals.length === 0) {
+      return 0;
+    }
+    return await getEffectivePermissionsACL(principals, resourceType, resourceId);
+  } catch (error) {
+    logger.error(`[PermissionService.getEffectivePermissions] Error: ${error.message}`);
+    return 0;
+  }
+};
+
+/**
+ * Find all resources of a specific type that a user has access to with specific permission bits
+ * @param {Object} params - Parameters for finding accessible resources
+ * @param {string|mongoose.Types.ObjectId} params.userId - The ID of the user
+ * @param {string} params.resourceType - Type of resource (e.g., 'agent')
+ * @param {number} params.requiredPermissions - The minimum permission bits required (e.g., 1 for VIEW, 3 for VIEW+EDIT)
+ * @returns {Promise<Array>} Array of resource IDs
+ */
+const findAccessibleResources = async ({ userId, resourceType, requiredPermissions }) => {
+  try {
+    if (typeof requiredPermissions !== 'number' || requiredPermissions < 1) {
+      throw new Error('requiredPermissions must be a positive number');
+    }
+
+    // Get all principals for the user (user + groups + public)
+    const principalsList = await getUserPrincipals(userId);
+
+    if (principalsList.length === 0) {
+      return [];
+    }
+    return await findAccessibleResourcesACL(principalsList, resourceType, requiredPermissions);
+  } catch (error) {
+    logger.error(`[PermissionService.findAccessibleResources] Error: ${error.message}`);
+    // Re-throw validation errors
+    if (error.message.includes('requiredPermissions must be')) {
+      throw error;
+    }
+    return [];
+  }
+};
+
+/**
+ * Find all publicly accessible resources of a specific type
+ * @param {Object} params - Parameters for finding publicly accessible resources
+ * @param {string} params.resourceType - Type of resource (e.g., 'agent')
+ * @param {number} params.requiredPermissions - The minimum permission bits required (e.g., 1 for VIEW, 3 for VIEW+EDIT)
+ * @returns {Promise<Array>} Array of resource IDs
+ */
+const findPubliclyAccessibleResources = async ({ resourceType, requiredPermissions }) => {
+  try {
+    if (typeof requiredPermissions !== 'number' || requiredPermissions < 1) {
+      throw new Error('requiredPermissions must be a positive number');
+    }
+
+    // Find all public ACL entries where the public principal has at least the required permission bits
+    const entries = await AclEntry.find({
+      principalType: 'public',
+      resourceType,
+      permBits: { $bitsAllSet: requiredPermissions },
+    }).distinct('resourceId');
+
+    return entries;
+  } catch (error) {
+    logger.error(`[PermissionService.findPubliclyAccessibleResources] Error: ${error.message}`);
+    // Re-throw validation errors
+    if (error.message.includes('requiredPermissions must be')) {
+      throw error;
+    }
+    return [];
+  }
+};
+
+/**
+ * Get available roles for a resource type
+ * @param {Object} params - Parameters for getting available roles
+ * @param {string} params.resourceType - Type of resource (e.g., 'agent')
+ * @returns {Promise<Array>} Array of role definitions
+ */
+const getAvailableRoles = async ({ resourceType }) => {
+  try {
+    return await AccessRole.find({ resourceType }).lean();
+  } catch (error) {
+    logger.error(`[PermissionService.getAvailableRoles] Error: ${error.message}`);
+    return [];
+  }
+};
+
+/**
+ * Ensures a principal exists in the database based on TPrincipal data
+ * Creates user if it doesn't exist locally (for Entra ID users)
+ * @param {Object} principal - TPrincipal object from frontend
+ * @param {string} principal.type - 'user', 'group', or 'public'
+ * @param {string} [principal.id] - Local database ID (null for Entra ID principals not yet synced)
+ * @param {string} principal.name - Display name
+ * @param {string} [principal.email] - Email address
+ * @param {string} [principal.source] - 'local' or 'entra'
+ * @param {string} [principal.idOnTheSource] - Entra ID object ID for external principals
+ * @returns {Promise<string|null>} Returns the principalId for database operations, null for public
+ */
+const ensurePrincipalExists = async function (principal) {
+  if (principal.type === 'public') {
+    return null;
+  }
+
+  if (principal.id) {
+    return principal.id;
+  }
+
+  if (principal.type === 'user' && principal.source === 'entra') {
+    if (!principal.email || !principal.idOnTheSource) {
+      throw new Error('Entra ID user principals must have email and idOnTheSource');
+    }
+
+    let existingUser = await findUser({ idOnTheSource: principal.idOnTheSource });
+
+    if (!existingUser) {
+      existingUser = await findUser({ email: principal.email.toLowerCase() });
+    }
+
+    if (existingUser) {
+      if (!existingUser.idOnTheSource && principal.idOnTheSource) {
+        await updateUser(existingUser._id, {
+          idOnTheSource: principal.idOnTheSource,
+          provider: 'openid',
+        });
+      }
+      return existingUser._id.toString();
+    }
+
+    const userData = {
+      name: principal.name,
+      email: principal.email.toLowerCase(),
+      emailVerified: false,
+      provider: 'openid',
+      idOnTheSource: principal.idOnTheSource,
+    };
+
+    const userId = await createUser(userData, true, false);
+    return userId.toString();
+  }
+
+  if (principal.type === 'group') {
+    throw new Error('Group principals should be handled by group-specific methods');
+  }
+
+  throw new Error(`Unsupported principal type: ${principal.type}`);
+};
+
+/**
+ * Ensures a group principal exists in the database based on TPrincipal data
+ * Creates group if it doesn't exist locally (for Entra ID groups)
+ * For Entra ID groups, always synchronizes member IDs when authentication context is provided
+ * @param {Object} principal - TPrincipal object from frontend
+ * @param {string} principal.type - Must be 'group'
+ * @param {string} [principal.id] - Local database ID (null for Entra ID principals not yet synced)
+ * @param {string} principal.name - Display name
+ * @param {string} [principal.email] - Email address
+ * @param {string} [principal.description] - Group description
+ * @param {string} [principal.source] - 'local' or 'entra'
+ * @param {string} [principal.idOnTheSource] - Entra ID object ID for external principals
+ * @param {Object} [authContext] - Optional authentication context for fetching member data
+ * @param {string} [authContext.accessToken] - Access token for Graph API calls
+ * @param {string} [authContext.sub] - Subject identifier
+ * @returns {Promise<string>} Returns the groupId for database operations
+ */
+const ensureGroupPrincipalExists = async function (principal, authContext = null) {
+  if (principal.type !== 'group') {
+    throw new Error(`Invalid principal type: ${principal.type}. Expected 'group'`);
+  }
+
+  if (principal.source === 'entra') {
+    if (!principal.name || !principal.idOnTheSource) {
+      throw new Error('Entra ID group principals must have name and idOnTheSource');
+    }
+
+    let memberIds = [];
+    if (authContext && authContext.accessToken && authContext.sub) {
+      try {
+        memberIds = await getGroupMembers(
+          authContext.accessToken,
+          authContext.sub,
+          principal.idOnTheSource,
+        );
+
+        // Include group owners as members if feature is enabled
+        if (isEnabled(process.env.ENTRA_ID_INCLUDE_OWNERS_AS_MEMBERS)) {
+          const ownerIds = await getGroupOwners(
+            authContext.accessToken,
+            authContext.sub,
+            principal.idOnTheSource,
+          );
+          if (ownerIds && ownerIds.length > 0) {
+            memberIds.push(...ownerIds);
+            // Remove duplicates
+            memberIds = [...new Set(memberIds)];
+          }
+        }
+      } catch (error) {
+        logger.error('Failed to fetch group members from Graph API:', error);
+      }
+    }
+
+    let existingGroup = await findGroupByExternalId(principal.idOnTheSource, 'entra');
+
+    if (!existingGroup && principal.email) {
+      existingGroup = await Group.findOne({ email: principal.email.toLowerCase() }).lean();
+    }
+
+    if (existingGroup) {
+      const updateData = {};
+      let needsUpdate = false;
+
+      if (!existingGroup.idOnTheSource && principal.idOnTheSource) {
+        updateData.idOnTheSource = principal.idOnTheSource;
+        updateData.source = 'entra';
+        needsUpdate = true;
+      }
+
+      if (principal.description && existingGroup.description !== principal.description) {
+        updateData.description = principal.description;
+        needsUpdate = true;
+      }
+
+      if (principal.email && existingGroup.email !== principal.email.toLowerCase()) {
+        updateData.email = principal.email.toLowerCase();
+        needsUpdate = true;
+      }
+
+      if (authContext && authContext.accessToken && authContext.sub) {
+        updateData.memberIds = memberIds;
+        needsUpdate = true;
+      }
+
+      if (needsUpdate) {
+        await Group.findByIdAndUpdate(existingGroup._id, { $set: updateData }, { new: true });
+      }
+
+      return existingGroup._id.toString();
+    }
+
+    const groupData = {
+      name: principal.name,
+      source: 'entra',
+      idOnTheSource: principal.idOnTheSource,
+      memberIds: memberIds, // Store idOnTheSource values of group members (empty if no auth context)
+    };
+
+    if (principal.email) {
+      groupData.email = principal.email.toLowerCase();
+    }
+
+    if (principal.description) {
+      groupData.description = principal.description;
+    }
+
+    const newGroup = await createGroup(groupData);
+    return newGroup._id.toString();
+  }
+  if (principal.id && authContext == null) {
+    return principal.id;
+  }
+
+  throw new Error(`Unsupported group principal source: ${principal.source}`);
+};
+
+/**
+ * Synchronize user's Entra ID group memberships on sign-in
+ * Gets user's group IDs from GraphAPI and updates memberships only for existing groups in database
+ * Optionally includes groups the user owns if ENTRA_ID_INCLUDE_OWNERS_AS_MEMBERS is enabled
+ * @param {Object} user - User object with authentication context
+ * @param {string} user.openidId - User's OpenID subject identifier
+ * @param {string} user.idOnTheSource - User's Entra ID (oid from token claims)
+ * @param {string} user.provider - Authentication provider ('openid')
+ * @param {string} accessToken - Access token for Graph API calls
+ * @param {mongoose.ClientSession} [session] - Optional MongoDB session for transactions
+ * @returns {Promise<void>}
+ */
+const syncUserEntraGroupMemberships = async (user, accessToken, session = null) => {
+  try {
+    if (!entraIdPrincipalFeatureEnabled(user) || !accessToken || !user.idOnTheSource) {
+      return;
+    }
+
+    const memberGroupIds = await getUserEntraGroups(accessToken, user.openidId);
+    let allGroupIds = [...(memberGroupIds || [])];
+
+    // Include owned groups if feature is enabled
+    if (isEnabled(process.env.ENTRA_ID_INCLUDE_OWNERS_AS_MEMBERS)) {
+      const ownedGroupIds = await getUserOwnedEntraGroups(accessToken, user.openidId);
+      if (ownedGroupIds && ownedGroupIds.length > 0) {
+        allGroupIds.push(...ownedGroupIds);
+        // Remove duplicates
+        allGroupIds = [...new Set(allGroupIds)];
+      }
+    }
+
+    if (!allGroupIds || allGroupIds.length === 0) {
+      return;
+    }
+
+    const sessionOptions = session ? { session } : {};
+
+    await Group.updateMany(
+      {
+        idOnTheSource: { $in: allGroupIds },
+        source: 'entra',
+        memberIds: { $ne: user.idOnTheSource },
+      },
+      { $addToSet: { memberIds: user.idOnTheSource } },
+      sessionOptions,
+    );
+
+    await Group.updateMany(
+      {
+        source: 'entra',
+        memberIds: user.idOnTheSource,
+        idOnTheSource: { $nin: allGroupIds },
+      },
+      { $pull: { memberIds: user.idOnTheSource } },
+      sessionOptions,
+    );
+  } catch (error) {
+    logger.error(`[PermissionService.syncUserEntraGroupMemberships] Error syncing groups:`, error);
+  }
+};
+
+/**
+ * Check if public has a specific permission on a resource
+ * @param {Object} params - Parameters for checking public permission
+ * @param {string} params.resourceType - Type of resource (e.g., 'agent')
+ * @param {string|mongoose.Types.ObjectId} params.resourceId - The ID of the resource
+ * @param {number} params.requiredPermissions - The permission bits required (e.g., 1 for VIEW, 3 for VIEW+EDIT)
+ * @returns {Promise<boolean>} Whether public has the required permission bits
+ */
+const hasPublicPermission = async ({ resourceType, resourceId, requiredPermissions }) => {
+  try {
+    if (typeof requiredPermissions !== 'number' || requiredPermissions < 1) {
+      throw new Error('requiredPermissions must be a positive number');
+    }
+
+    // Use public principal to check permissions
+    const publicPrincipal = [{ principalType: 'public' }];
+
+    const entries = await findEntriesByPrincipalsAndResource(
+      publicPrincipal,
+      resourceType,
+      resourceId,
+    );
+
+    // Check if any entry has the required permission bits
+    return entries.some((entry) => (entry.permBits & requiredPermissions) === requiredPermissions);
+  } catch (error) {
+    logger.error(`[PermissionService.hasPublicPermission] Error: ${error.message}`);
+    // Re-throw validation errors
+    if (error.message.includes('requiredPermissions must be')) {
+      throw error;
+    }
+    return false;
+  }
+};
+
+/**
+ * Bulk update permissions for a resource (grant, update, revoke)
+ * Efficiently handles multiple permission changes in a single transaction
+ *
+ * @param {Object} params - Parameters for bulk permission update
+ * @param {string} params.resourceType - Type of resource (e.g., 'agent')
+ * @param {string|mongoose.Types.ObjectId} params.resourceId - The ID of the resource
+ * @param {Array<TPrincipal>} params.updatedPrincipals - Array of principals to grant/update permissions for
+ * @param {Array<TPrincipal>} params.revokedPrincipals - Array of principals to revoke permissions from
+ * @param {string|mongoose.Types.ObjectId} params.grantedBy - User ID making the changes
+ * @param {mongoose.ClientSession} [params.session] - Optional MongoDB session for transactions
+ * @returns {Promise<Object>} Results object with granted, updated, revoked arrays and error details
+ */
+const bulkUpdateResourcePermissions = async ({
+  resourceType,
+  resourceId,
+  updatedPrincipals = [],
+  revokedPrincipals = [],
+  grantedBy,
+  session,
+}) => {
+  const supportsTransactions = await getTransactionSupport(mongoose, transactionSupportCache);
+  transactionSupportCache = supportsTransactions;
+  let localSession = session;
+  let shouldEndSession = false;
+
+  try {
+    if (!Array.isArray(updatedPrincipals)) {
+      throw new Error('updatedPrincipals must be an array');
+    }
+
+    if (!Array.isArray(revokedPrincipals)) {
+      throw new Error('revokedPrincipals must be an array');
+    }
+
+    if (!resourceId || !mongoose.Types.ObjectId.isValid(resourceId)) {
+      throw new Error(`Invalid resource ID: ${resourceId}`);
+    }
+
+    if (!localSession && supportsTransactions) {
+      localSession = await mongoose.startSession();
+      localSession.startTransaction();
+      shouldEndSession = true;
+    }
+
+    const sessionOptions = localSession ? { session: localSession } : {};
+
+    const roles = await AccessRole.find({ resourceType }).lean();
+    const rolesMap = new Map();
+    roles.forEach((role) => {
+      rolesMap.set(role.accessRoleId, role);
+    });
+
+    const results = {
+      granted: [],
+      updated: [],
+      revoked: [],
+      errors: [],
+    };
+
+    const bulkWrites = [];
+
+    for (const principal of updatedPrincipals) {
+      try {
+        if (!principal.accessRoleId) {
+          results.errors.push({
+            principal,
+            error: 'accessRoleId is required for updated principals',
+          });
+          continue;
+        }
+
+        const role = rolesMap.get(principal.accessRoleId);
+        if (!role) {
+          results.errors.push({
+            principal,
+            error: `Role ${principal.accessRoleId} not found`,
+          });
+          continue;
+        }
+
+        const query = {
+          principalType: principal.type,
+          resourceType,
+          resourceId,
+        };
+
+        if (principal.type !== 'public') {
+          query.principalId = principal.id;
+        }
+
+        const update = {
+          $set: {
+            permBits: role.permBits,
+            roleId: role._id,
+            grantedBy,
+            grantedAt: new Date(),
+          },
+          $setOnInsert: {
+            principalType: principal.type,
+            resourceType,
+            resourceId,
+            ...(principal.type !== 'public' && {
+              principalId: principal.id,
+              principalModel: principal.type === 'user' ? 'User' : 'Group',
+            }),
+          },
+        };
+
+        bulkWrites.push({
+          updateOne: {
+            filter: query,
+            update: update,
+            upsert: true,
+          },
+        });
+
+        results.granted.push({
+          type: principal.type,
+          id: principal.id,
+          name: principal.name,
+          email: principal.email,
+          source: principal.source,
+          avatar: principal.avatar,
+          description: principal.description,
+          idOnTheSource: principal.idOnTheSource,
+          accessRoleId: principal.accessRoleId,
+          memberCount: principal.memberCount,
+          memberIds: principal.memberIds,
+        });
+      } catch (error) {
+        results.errors.push({
+          principal,
+          error: error.message,
+        });
+      }
+    }
+
+    if (bulkWrites.length > 0) {
+      await AclEntry.bulkWrite(bulkWrites, sessionOptions);
+    }
+
+    const deleteQueries = [];
+    for (const principal of revokedPrincipals) {
+      try {
+        const query = {
+          principalType: principal.type,
+          resourceType,
+          resourceId,
+        };
+
+        if (principal.type !== 'public') {
+          query.principalId = principal.id;
+        }
+
+        deleteQueries.push(query);
+
+        results.revoked.push({
+          type: principal.type,
+          id: principal.id,
+          name: principal.name,
+          email: principal.email,
+          source: principal.source,
+          avatar: principal.avatar,
+          description: principal.description,
+          idOnTheSource: principal.idOnTheSource,
+          memberCount: principal.memberCount,
+        });
+      } catch (error) {
+        results.errors.push({
+          principal,
+          error: error.message,
+        });
+      }
+    }
+
+    if (deleteQueries.length > 0) {
+      await AclEntry.deleteMany(
+        {
+          $or: deleteQueries,
+        },
+        sessionOptions,
+      );
+    }
+
+    if (shouldEndSession && supportsTransactions) {
+      await localSession.commitTransaction();
+    }
+
+    return results;
+  } catch (error) {
+    if (shouldEndSession && supportsTransactions) {
+      await localSession.abortTransaction();
+    }
+    logger.error(`[PermissionService.bulkUpdateResourcePermissions] Error: ${error.message}`);
+    throw error;
+  } finally {
+    if (shouldEndSession && localSession) {
+      localSession.endSession();
+    }
+  }
+};
+
+module.exports = {
+  grantPermission,
+  checkPermission,
+  getEffectivePermissions,
+  findAccessibleResources,
+  findPubliclyAccessibleResources,
+  hasPublicPermission,
+  getAvailableRoles,
+  bulkUpdateResourcePermissions,
+  ensurePrincipalExists,
+  ensureGroupPrincipalExists,
+  syncUserEntraGroupMemberships,
+};

api/strategies/openidStrategy.js

@@ -381,6 +381,7 @@ async function setupOpenId() {
               email: userinfo.email || '',
               emailVerified: userinfo.email_verified || false,
               name: fullName,
+              idOnTheSource: userinfo.oid,
             };
 
             const balanceConfig = await getBalanceConfig();
@@ -391,6 +392,7 @@ async function setupOpenId() {
             user.openidId = userinfo.sub;
             user.username = username;
             user.name = fullName;
+            user.idOnTheSource = userinfo.oid;
           }
 
           if (!!userinfo && userinfo.picture && !user.avatar?.includes('manual=true')) {

client/src/common/agents-types.ts

@@ -7,6 +7,7 @@ export type TAgentOption = OptionWithIcon &
     knowledge_files?: Array<[string, ExtendedFile]>;
     context_files?: Array<[string, ExtendedFile]>;
     code_files?: Array<[string, ExtendedFile]>;
+    _id?: string;
   };
 
 export type TAgentCapabilities = {
@@ -17,6 +18,11 @@ export type TAgentCapabilities = {
   [AgentCapabilities.hide_sequential_outputs]?: boolean;
 };
 
+export type SupportContact = {
+  name?: string;
+  email?: string;
+};
+
 export type AgentForm = {
   agent?: TAgentOption;
   id: string;
@@ -30,4 +36,5 @@ export type AgentForm = {
   agent_ids?: string[];
   [AgentCapabilities.artifacts]?: ArtifactModes | string;
   recursion_limit?: number;
+  support_contact?: SupportContact;
 } & TAgentCapabilities;

client/src/components/Chat/Header.tsx

@@ -17,6 +17,7 @@ const defaultInterface = getConfigDefaults().interface;
 export default function Header() {
   const { data: startupConfig } = useGetStartupConfig();
   const { navVisible, setNavVisible } = useOutletContext<ContextType>();
+
   const interfaceConfig = useMemo(
     () => startupConfig?.interface ?? defaultInterface,
     [startupConfig],

client/src/components/Chat/Menus/OpenSidebar.tsx

@@ -16,7 +16,7 @@ export default function OpenSidebar({
           variant="outline"
           data-testid="open-sidebar-button"
           aria-label={localize('com_nav_open_sidebar')}
-          className="rounded-xl border border-border-light bg-surface-secondary p-2 hover:bg-surface-hover max-md:hidden"
+          className="rounded-xl border border-border-light bg-surface-secondary p-2 hover:bg-surface-hover"
           onClick={() =>
             setNavVisible((prev) => {
               localStorage.setItem('navVisible', JSON.stringify(!prev));

client/src/components/Input/ModelSelect/Anthropic.tsx

@@ -1,6 +1,7 @@
-import { SelectDropDown, SelectDropDownPop } from '@librechat/client';
+import { SelectDropDown } from '@librechat/client';
 import type { TModelSelectProps } from '~/common';
-import { cn, cardStyle } from '~/utils/';
+import SelectDropDownPop from '~/components/Input/ModelSelect/SelectDropDownPop';
+import { cn, cardStyle } from '~/utils';
 
 export default function Anthropic({
   conversation,

client/src/components/Input/ModelSelect/ChatGPT.tsx

@@ -1,6 +1,7 @@
-import { SelectDropDown, SelectDropDownPop } from '@librechat/client';
+import { SelectDropDown } from '@librechat/client';
 import type { TModelSelectProps } from '~/common';
-import { cn, cardStyle } from '~/utils/';
+import SelectDropDownPop from '~/components/Input/ModelSelect/SelectDropDownPop';
+import { cn, cardStyle } from '~/utils';
 
 export default function ChatGPT({
   conversation,

client/src/components/Input/ModelSelect/Google.tsx

@@ -1,6 +1,7 @@
-import { SelectDropDown, SelectDropDownPop } from '@librechat/client';
+import { SelectDropDown } from '@librechat/client';
 import type { TModelSelectProps } from '~/common';
-import { cn, cardStyle } from '~/utils/';
+import SelectDropDownPop from '~/components/Input/ModelSelect/SelectDropDownPop';
+import { cn, cardStyle } from '~/utils';
 
 export default function Google({
   conversation,

client/src/components/Input/ModelSelect/OpenAI.tsx

@@ -1,6 +1,7 @@
-import { SelectDropDown, SelectDropDownPop } from '@librechat/clienti';
+import { SelectDropDown } from '@librechat/client';
 import type { TModelSelectProps } from '~/common';
-import { cn, cardStyle } from '~/utils/';
+import SelectDropDownPop from '~/components/Input/ModelSelect/SelectDropDownPop';
+import { cn, cardStyle } from '~/utils';
 
 export default function OpenAI({
   conversation,

client/src/components/Input/ModelSelect/SelectDropDownPop.tsx

@@ -1,10 +1,10 @@
-import React from 'react';
+import React, { useState } from 'react';
 import { useMultiSearch } from '@librechat/client';
 import { Root, Trigger, Content, Portal } from '@radix-ui/react-popover';
-import MenuItem from '~/components/Chat/Menus/UI/MenuItem';
 import type { Option } from '~/common';
+import MenuItem from '~/components/Chat/Menus/UI/MenuItem';
 import { useLocalize } from '~/hooks';
-import { cn } from '~/utils/';
+import { cn } from '~/utils';
 
 type SelectDropDownProps = {
   id?: string;
@@ -32,6 +32,7 @@ function SelectDropDownPop({
   footer,
 }: SelectDropDownProps) {
   const localize = useLocalize();
+  const [open, setOpen] = useState(false);
   const transitionProps = { className: 'top-full mt-3' };
   if (showAbove) {
     transitionProps.className = 'bottom-full mb-3';
@@ -54,8 +55,13 @@ function SelectDropDownPop({
   const hasSearchRender = Boolean(searchRender);
   const options = hasSearchRender ? filteredValues : availableValues;
 
+  const handleSelect = (selectedValue: string) => {
+    setValue(selectedValue);
+    setOpen(false);
+  };
+
   return (
-    <Root>
+    <Root open={open} onOpenChange={setOpen}>
       <div className={'flex items-center justify-center gap-2'}>
         <div className={'relative w-full'}>
           <Trigger asChild>
@@ -108,19 +114,32 @@ function SelectDropDownPop({
               side="bottom"
               align="start"
               className={cn(
-                'mr-3 mt-2 max-h-[52vh] w-full max-w-[85vw] overflow-hidden overflow-y-auto rounded-lg border border-gray-200 bg-white shadow-lg dark:border-gray-700 dark:bg-gray-700 dark:text-white sm:max-w-full lg:max-h-[52vh]',
+                'z-50 mr-3 mt-2 max-h-[52vh] w-full max-w-[85vw] overflow-hidden overflow-y-auto rounded-lg border border-gray-200 bg-white shadow-lg dark:border-gray-700 dark:bg-gray-700 dark:text-white sm:max-w-full lg:max-h-[52vh]',
                 hasSearchRender && 'relative',
               )}
             >
               {searchRender}
               {options.map((option) => {
+                if (typeof option === 'string') {
                   return (
                     <MenuItem
                       key={option}
                       title={option}
                       value={option}
                       selected={!!(value && value === option)}
-                    onClick={() => setValue(option)}
+                      onClick={() => handleSelect(option)}
+                    />
+                  );
+                }
+                return (
+                  <MenuItem
+                    key={option.value}
+                    title={option.label}
+                    description={option.description}
+                    value={option.value}
+                    icon={option.icon}
+                    selected={!!(value && value === option.value)}
+                    onClick={() => handleSelect(option.value)}
                   />
                 );
               })}

client/src/components/Nav/NewChat.tsx

@@ -1,10 +1,11 @@
-import React, { useCallback } from 'react';
+import React, { useCallback, useContext } from 'react';
+import { LayoutGrid } from 'lucide-react';
 import { useNavigate } from 'react-router-dom';
 import { useQueryClient } from '@tanstack/react-query';
-import type { TMessage } from 'librechat-data-provider';
+import { QueryKeys, Constants, Permissions, PermissionTypes } from 'librechat-data-provider';
-import { QueryKeys, Constants } from 'librechat-data-provider';
 import { NewChatIcon, MobileSidebar, Sidebar, TooltipAnchor, Button } from '@librechat/client';
-import { useLocalize, useNewConvo } from '~/hooks';
+import type { TMessage } from 'librechat-data-provider';
+import { useLocalize, useNewConvo, useHasAccess, AuthContext } from '~/hooks';
 import store from '~/store';
 
 export default function NewChat({
@@ -26,6 +27,11 @@ export default function NewChat({
   const navigate = useNavigate();
   const localize = useLocalize();
   const { conversation } = store.useCreateConversationAtom(index);
+  const authContext = useContext(AuthContext);
+  const hasAccessToAgents = useHasAccess({
+    permissionType: PermissionTypes.AGENTS,
+    permission: Permissions.USE,
+  });
 
   const clickHandler: React.MouseEventHandler<HTMLButtonElement> = useCallback(
     (e) => {
@@ -47,6 +53,22 @@ export default function NewChat({
     [queryClient, conversation, newConvo, navigate, toggleNav, isSmallScreen],
   );
 
+  const handleAgentMarketplace = useCallback(() => {
+    navigate('/agents');
+    if (isSmallScreen) {
+      toggleNav();
+    }
+  }, [navigate, isSmallScreen, toggleNav]);
+
+  // Check if auth is ready (avoid race conditions)
+  const authReady =
+    authContext?.isAuthenticated !== undefined &&
+    (authContext?.isAuthenticated === false || authContext?.user !== undefined);
+
+  // Show agent marketplace when auth is ready and user has access
+  // Note: endpointsConfig[agents] is null, but we can still show the marketplace
+  const showAgentMarketplace = authReady && hasAccessToAgents;
+
   return (
     <>
       <div className="flex items-center justify-between py-[2px] md:py-2">
@@ -85,6 +107,29 @@ export default function NewChat({
           />
         </div>
       </div>
+
+      {/* Agent Marketplace button - separate row like ChatGPT */}
+      {showAgentMarketplace && (
+        <div className="flex px-2 pb-4 pt-2 md:px-3">
+          <TooltipAnchor
+            description={localize('com_nav_agents_marketplace')}
+            render={
+              <Button
+                variant="outline"
+                data-testid="nav-agents-marketplace-button"
+                aria-label={localize('com_nav_agents_marketplace')}
+                className="flex w-full items-center justify-start gap-3 rounded-xl border-none bg-transparent p-3 text-left hover:bg-surface-hover"
+                onClick={handleAgentMarketplace}
+              >
+                <LayoutGrid className="h-5 w-5 flex-shrink-0" />
+                <span className="truncate text-base font-medium">
+                  {localize('com_nav_agents_marketplace')}
+                </span>
+              </Button>
+            }
+          />
+        </div>
+      )}
       {subHeaders != null ? subHeaders : null}
     </>
   );

client/src/components/Prompts/Groups/CategoryIcon.tsx

@@ -9,6 +9,10 @@ import {
   PlaneTakeoffIcon,
   GraduationCapIcon,
   TerminalSquareIcon,
+  // NEW: Add these for agent categories
+  Users as UsersIcon,
+  Beaker as BeakerIcon,
+  Settings as SettingsIcon,
 } from 'lucide-react';
 import { cn } from '~/utils';
 
@@ -22,6 +26,13 @@ const categoryIconMap: Record<string, React.ElementType> = {
   code: TerminalSquareIcon,
   travel: PlaneTakeoffIcon,
   teach_or_explain: GraduationCapIcon,
+  // NEW: Agent categories
+  general: BoxIcon,
+  hr: UsersIcon,
+  rd: BeakerIcon,
+  it: TerminalSquareIcon,
+  sales: LineChartIcon,
+  aftersales: SettingsIcon,
 };
 
 const categoryColorMap: Record<string, string> = {
@@ -34,6 +45,13 @@ const categoryColorMap: Record<string, string> = {
   finance: 'text-orange-400',
   roleplay: 'text-orange-400',
   teach_or_explain: 'text-blue-300',
+  // NEW: Agent categories
+  general: 'text-blue-500',
+  hr: 'text-green-500',
+  rd: 'text-purple-500',
+  it: 'text-red-500',
+  sales: 'text-orange-500',
+  aftersales: 'text-yellow-500',
 };
 
 export default function CategoryIcon({

client/src/components/SidePanel/Agents/AgentCard.tsx

@@ -0,0 +1,93 @@
+import React from 'react';
+
+import type t from 'librechat-data-provider';
+
+import useLocalize from '~/hooks/useLocalize';
+import { renderAgentAvatar, getContactDisplayName } from '~/utils/agents';
+import { cn } from '~/utils';
+
+interface AgentCardProps {
+  agent: t.Agent; // The agent data to display
+  onClick: () => void; // Callback when card is clicked
+  className?: string; // Additional CSS classes
+}
+
+/**
+ * Card component to display agent information
+ */
+const AgentCard: React.FC<AgentCardProps> = ({ agent, onClick, className = '' }) => {
+  const localize = useLocalize();
+
+  return (
+    <div
+      className={cn(
+        'group relative flex overflow-hidden rounded-2xl',
+        'cursor-pointer transition-colors duration-200',
+        'aspect-[5/2.5] w-full',
+        'bg-gray-50 hover:bg-gray-100 dark:bg-gray-700 dark:hover:bg-gray-600',
+        className,
+      )}
+      onClick={onClick}
+      aria-label={localize('com_agents_agent_card_label', {
+        name: agent.name,
+        description: agent.description || localize('com_agents_no_description'),
+      })}
+      aria-describedby={`agent-${agent.id}-description`}
+      tabIndex={0}
+      role="button"
+      onKeyDown={(e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          onClick();
+        }
+      }}
+    >
+      <div className="flex h-full gap-2 px-3 py-2 sm:gap-3 sm:px-4 sm:py-3">
+        {/* Agent avatar section - left side, responsive */}
+        <div className="flex flex-shrink-0 items-center">
+          {renderAgentAvatar(agent, { size: 'md' })}
+        </div>
+
+        {/* Agent info section - right side, responsive */}
+        <div className="flex min-w-0 flex-1 flex-col justify-center">
+          {/* Agent name - responsive text sizing */}
+          <h3 className="mb-1 line-clamp-1 text-base font-bold text-gray-900 dark:text-white sm:mb-2 sm:text-lg">
+            {agent.name}
+          </h3>
+
+          {/* Agent description - responsive text sizing and spacing */}
+          <p
+            id={`agent-${agent.id}-description`}
+            className={cn(
+              'mb-1 line-clamp-2 text-xs leading-relaxed text-gray-600 dark:text-gray-300',
+              'sm:mb-2 sm:text-sm',
+            )}
+            aria-label={`Description: ${agent.description || localize('com_agents_no_description')}`}
+          >
+            {agent.description || (
+              <span className="italic text-gray-400">{localize('com_agents_no_description')}</span>
+            )}
+          </p>
+
+          {/* Owner info - responsive text sizing */}
+          {(() => {
+            const displayName = getContactDisplayName(agent);
+
+            if (displayName) {
+              return (
+                <div className="flex items-center text-xs text-gray-500 dark:text-gray-400 sm:text-sm">
+                  <span className="font-light">{localize('com_agents_created_by')}</span>
+                  <span className="ml-1 font-bold">{displayName}</span>
+                </div>
+              );
+            }
+
+            return null;
+          })()}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default AgentCard;

client/src/components/SidePanel/Agents/AgentCategoryDisplay.tsx

@@ -0,0 +1,62 @@
+import React from 'react';
+import { useAgentCategories } from '~/hooks/Agents';
+import { cn } from '~/utils';
+
+interface AgentCategoryDisplayProps {
+  category?: string;
+  className?: string;
+  showIcon?: boolean;
+  iconClassName?: string;
+  showEmptyFallback?: boolean;
+}
+
+/**
+ * Component to display an agent category with proper translation
+ *
+ * @param category - The category value (e.g., "general", "hr", etc.)
+ * @param className - Optional className for the container
+ * @param showIcon - Whether to show the category icon
+ * @param iconClassName - Optional className for the icon
+ * @param showEmptyFallback - Whether to show a fallback for empty categories
+ */
+const AgentCategoryDisplay: React.FC<AgentCategoryDisplayProps> = ({
+  category,
+  className = '',
+  showIcon = true,
+  iconClassName = 'h-4 w-4 mr-2',
+  showEmptyFallback = false,
+}) => {
+  const { categories, emptyCategory } = useAgentCategories();
+
+  // Find the category in our processed categories list
+  const categoryItem = categories.find((c) => c.value === category);
+
+  // Handle empty string case differently than undefined/null
+  if (category === '') {
+    if (!showEmptyFallback) {
+      return null;
+    }
+    // Show the empty category placeholder
+    return (
+      <div className={cn('flex items-center text-gray-400', className)}>
+        <span>{emptyCategory.label}</span>
+      </div>
+    );
+  }
+
+  // No category or unknown category
+  if (!category || !categoryItem) {
+    return null;
+  }
+
+  return (
+    <div className={cn('flex items-center', className)}>
+      {showIcon && categoryItem.icon && (
+        <span className={cn('flex-shrink-0', iconClassName)}>{categoryItem.icon}</span>
+      )}
+      <span>{categoryItem.label}</span>
+    </div>
+  );
+};
+
+export default AgentCategoryDisplay;

client/src/components/SidePanel/Agents/AgentCategorySelector.tsx

@@ -0,0 +1,93 @@
+import React, { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { ControlCombobox } from '@librechat/client';
+import {
+  useWatch,
+  FieldPath,
+  Controller,
+  FieldValues,
+  useFormContext,
+  ControllerRenderProps,
+} from 'react-hook-form';
+import { useAgentCategories } from '~/hooks/Agents';
+
+/**
+ * Custom hook to handle category synchronization
+ */
+const useCategorySync = (agent_id: string | null) => {
+  const [handled, setHandled] = useState(false);
+
+  return {
+    syncCategory: (field: ControllerRenderProps<FieldValues, FieldPath<FieldValues>>) => {
+      // Only run once and only for new agents
+      if (!handled && agent_id === '' && !field.value) {
+        field.onChange('general');
+        setHandled(true);
+      }
+    },
+  };
+};
+
+/**
+ * A component for selecting agent categories with form validation
+ */
+const AgentCategorySelector: React.FC = () => {
+  const { t } = useTranslation();
+  const formContext = useFormContext();
+  const { categories } = useAgentCategories();
+
+  // Always call useWatch
+  const agent_id = useWatch({
+    name: 'id',
+    control: formContext.control,
+  });
+
+  // Use custom hook for category sync
+  const { syncCategory } = useCategorySync(agent_id);
+
+  // Transform categories to the format expected by ControlCombobox
+  const comboboxItems = categories.map((category) => ({
+    label: category.label,
+    value: category.value,
+  }));
+
+  const getCategoryDisplayValue = (value: string) => {
+    const categoryItem = comboboxItems.find((c) => c.value === value);
+    return categoryItem?.label || comboboxItems.find((c) => c.value === 'general')?.label;
+  };
+
+  const searchPlaceholder = t('com_ui_search_agent_category', 'Search categories...');
+  const ariaLabel = t('com_ui_agent_category_selector_aria', "Agent's category selector");
+
+  return (
+    <Controller
+      name="category"
+      control={formContext.control}
+      defaultValue="general"
+      render={({ field }) => {
+        // Sync category if needed (without using useEffect in render)
+        syncCategory(field);
+
+        const displayValue = getCategoryDisplayValue(field.value);
+
+        return (
+          <ControlCombobox
+            selectedValue={field.value}
+            displayValue={displayValue}
+            searchPlaceholder={searchPlaceholder}
+            setValue={(value) => {
+              field.onChange(value);
+            }}
+            items={comboboxItems}
+            className=""
+            ariaLabel={ariaLabel}
+            isCollapsed={false}
+            showCarat={true}
+          />
+        );
+      }}
+    />
+  );
+};
+
+export default AgentCategorySelector;

client/src/components/SidePanel/Agents/AgentConfig.tsx

@@ -13,6 +13,7 @@ import {
 } from '~/utils';
 import { useFileMapContext, useAgentPanelContext } from '~/Providers';
 import useAgentCapabilities from '~/hooks/Agents/useAgentCapabilities';
+import AgentCategorySelector from './AgentCategorySelector';
 import Action from '~/components/SidePanel/Builder/Action';
 import { ToolSelectDialog } from '~/components/Tools';
 import { useGetAgentFiles } from '~/data-provider';
@@ -243,6 +244,13 @@ export default function AgentConfig({ createMutation }: Pick<AgentPanelProps, 'c
             )}
           />
         </div>
+        {/* Category */}
+        <div className="mb-4">
+          <label className={labelClass} htmlFor="category-selector">
+            {localize('com_ui_category')} <span className="text-red-500">*</span>
+          </label>
+          <AgentCategorySelector className="w-full" />
+        </div>
         {/* Instructions */}
         <Instructions />
         {/* Model and Provider */}
@@ -362,6 +370,93 @@ export default function AgentConfig({ createMutation }: Pick<AgentPanelProps, 'c
         </div>
         {/* MCP Section */}
         {/* <MCPSection /> */}
+
+        {/* Support Contact (Optional) */}
+        <div className="mb-4">
+          <div className="mb-1.5 flex items-center gap-2">
+            <span>
+              <label className="text-token-text-primary block font-medium">
+                {localize('com_ui_support_contact')}
+              </label>
+            </span>
+          </div>
+          <div className="space-y-3">
+            {/* Support Contact Name */}
+            <div className="flex flex-col">
+              <label
+                className="mb-1 flex items-center justify-between"
+                htmlFor="support-contact-name"
+              >
+                <span className="text-sm">{localize('com_ui_support_contact_name')}</span>
+              </label>
+              <Controller
+                name="support_contact.name"
+                control={control}
+                rules={{
+                  minLength: {
+                    value: 3,
+                    message: localize('com_ui_support_contact_name_min_length', { minLength: 3 }),
+                  },
+                }}
+                render={({ field, fieldState: { error } }) => (
+                  <>
+                    <input
+                      {...field}
+                      value={field.value ?? ''}
+                      className={cn(inputClass, error ? 'border-2 border-red-500' : '')}
+                      id="support-contact-name"
+                      type="text"
+                      placeholder={localize('com_ui_support_contact_name_placeholder')}
+                      aria-label="Support contact name"
+                    />
+                    {error && (
+                      <span className="text-sm text-red-500 transition duration-300 ease-in-out">
+                        {error.message}
+                      </span>
+                    )}
+                  </>
+                )}
+              />
+            </div>
+            {/* Support Contact Email */}
+            <div className="flex flex-col">
+              <label
+                className="mb-1 flex items-center justify-between"
+                htmlFor="support-contact-email"
+              >
+                <span className="text-sm">{localize('com_ui_support_contact_email')}</span>
+              </label>
+              <Controller
+                name="support_contact.email"
+                control={control}
+                rules={{
+                  pattern: {
+                    value: /^\w+([.-]?\w+)*@\w+([.-]?\w+)*(\.\w{2,3})+$/,
+                    message: localize('com_ui_support_contact_email_invalid'),
+                  },
+                }}
+                render={({ field, fieldState: { error } }) => (
+                  <>
+                    <input
+                      {...field}
+                      value={field.value ?? ''}
+                      className={cn(inputClass, error ? 'border-2 border-red-500' : '')}
+                      id="support-contact-email"
+                      type="email"
+                      placeholder={localize('com_ui_support_contact_email_placeholder')}
+                      aria-label="Support contact email"
+                    />
+                    {error && (
+                      <span className="text-sm text-red-500 transition duration-300 ease-in-out">
+                        {error.message}
+                      </span>
+                    )}
+                  </>
+                )}
+              />
+            </div>
+          </div>
+        </div>
       </div>
       <ToolSelectDialog
         isOpen={showToolDialog}

client/src/components/SidePanel/Agents/AgentDetail.tsx

@@ -0,0 +1,184 @@
+import React, { useRef, useState, useEffect } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { Dialog, Button, DotsIcon, DialogContent, useToastContext } from '@librechat/client';
+import type t from 'librechat-data-provider';
+import { renderAgentAvatar } from '~/utils';
+import { useLocalize } from '~/hooks';
+
+interface SupportContact {
+  name?: string;
+  email?: string;
+}
+
+interface AgentWithSupport extends t.Agent {
+  support_contact?: SupportContact;
+}
+
+interface AgentDetailProps {
+  agent: AgentWithSupport; // The agent data to display
+  isOpen: boolean; // Whether the detail dialog is open
+  onClose: () => void; // Callback when dialog is closed
+}
+
+/**
+ * Dialog for displaying agent details
+ */
+const AgentDetail: React.FC<AgentDetailProps> = ({ agent, isOpen, onClose }) => {
+  const localize = useLocalize();
+  const navigate = useNavigate();
+  const { showToast } = useToastContext();
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+  const [dropdownOpen, setDropdownOpen] = useState(false);
+
+  // Close dropdown when clicking outside the dropdown menu
+  useEffect(() => {
+    const handleClickOutside = (event: MouseEvent) => {
+      if (
+        dropdownOpen &&
+        dropdownRef.current &&
+        !dropdownRef.current.contains(event.target as Node)
+      ) {
+        setDropdownOpen(false);
+      }
+    };
+
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside);
+    };
+  }, [dropdownOpen]);
+
+  /**
+   * Navigate to chat with the selected agent
+   */
+  const handleStartChat = () => {
+    if (agent) {
+      navigate(`/c/new?agent_id=${agent.id}`);
+    }
+  };
+
+  /**
+   * Copy the agent's shareable link to clipboard
+   */
+  const handleCopyLink = () => {
+    const baseUrl = new URL(window.location.origin);
+    const chatUrl = `${baseUrl.origin}/c/new?agent_id=${agent.id}`;
+    navigator.clipboard
+      .writeText(chatUrl)
+      .then(() => {
+        showToast({
+          message: 'Link copied',
+        });
+      })
+      .catch(() => {
+        showToast({
+          message: localize('com_agents_link_copy_failed'),
+        });
+      });
+  };
+
+  /**
+   * Format contact information with mailto links when appropriate
+   */
+  const formatContact = () => {
+    if (!agent?.support_contact) return null;
+
+    const { name, email } = agent.support_contact;
+
+    if (name && email) {
+      return (
+        <a href={`mailto:${email}`} className="text-primary hover:underline">
+          {name}
+        </a>
+      );
+    }
+
+    if (email) {
+      return (
+        <a href={`mailto:${email}`} className="text-primary hover:underline">
+          {email}
+        </a>
+      );
+    }
+
+    if (name) {
+      return <span>{name}</span>;
+    }
+
+    return null;
+  };
+
+  return (
+    <Dialog open={isOpen} onOpenChange={(open) => !open && onClose()}>
+      <DialogContent ref={dialogRef} className="max-h-[90vh] overflow-y-auto py-8 sm:max-w-[450px]">
+        {/* Context menu - top right */}
+        <div ref={dropdownRef} className="absolute right-12 top-5 z-50">
+          <Button
+            variant="ghost"
+            size="icon"
+            className="h-8 w-8 rounded-lg text-text-secondary hover:bg-surface-hover hover:text-text-primary dark:hover:bg-surface-hover"
+            aria-label="More options"
+            aria-expanded={dropdownOpen}
+            aria-haspopup="menu"
+            onClick={(e) => {
+              e.stopPropagation();
+              setDropdownOpen(!dropdownOpen);
+            }}
+          >
+            <DotsIcon className="h-4 w-4" />
+          </Button>
+
+          {/* Simple dropdown menu */}
+          {dropdownOpen && (
+            <div className="absolute right-0 top-10 z-[9999] w-48 rounded-xl border border-border-light bg-surface-primary py-1 shadow-lg dark:bg-surface-secondary dark:shadow-2xl">
+              <button
+                onClick={(e) => {
+                  e.stopPropagation();
+                  setDropdownOpen(false);
+                  handleCopyLink();
+                }}
+                className="w-full px-3 py-2 text-left text-sm text-text-primary transition-colors hover:bg-surface-hover focus:bg-surface-hover focus:outline-none"
+              >
+                {localize('com_agents_copy_link')}
+              </button>
+            </div>
+          )}
+        </div>
+
+        {/* Agent avatar - top center */}
+        <div className="mt-6 flex justify-center">{renderAgentAvatar(agent, { size: 'xl' })}</div>
+
+        {/* Agent name - center aligned below image */}
+        <div className="mt-3 text-center">
+          <h2 className="text-2xl font-bold text-gray-900 dark:text-white">
+            {agent?.name || localize('com_agents_loading')}
+          </h2>
+        </div>
+
+        {/* Contact info - center aligned below name */}
+        {agent?.support_contact && formatContact() && (
+          <div className="mt-1 text-center text-sm text-gray-600 dark:text-gray-400">
+            {localize('com_agents_contact')}: {formatContact()}
+          </div>
+        )}
+
+        {/* Agent description - below contact */}
+        <div className="mt-4 whitespace-pre-wrap px-6 text-center text-base text-gray-700 dark:text-gray-300">
+          {agent?.description || (
+            <span className="italic text-gray-400">{localize('com_agents_no_description')}</span>
+          )}
+        </div>
+
+        {/* Action button */}
+        <div className="mb-4 mt-6 flex justify-center">
+          <Button className="w-full max-w-xs" onClick={handleStartChat} disabled={!agent}>
+            {localize('com_agents_start_chat')}
+          </Button>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+};
+
+export default AgentDetail;

client/src/components/SidePanel/Agents/AgentFooter.tsx

@@ -1,15 +1,20 @@
 import { Spinner } from '@librechat/client';
 import { useWatch, useFormContext } from 'react-hook-form';
-import { SystemRoles, Permissions, PermissionTypes } from 'librechat-data-provider';
+import {
+  SystemRoles,
+  Permissions,
+  PermissionTypes,
+  PERMISSION_BITS,
+} from 'librechat-data-provider';
 import type { AgentForm, AgentPanelProps } from '~/common';
-import { useLocalize, useAuthContext, useHasAccess } from '~/hooks';
+import { useLocalize, useAuthContext, useHasAccess, useResourcePermissions } from '~/hooks';
+import GrantAccessDialog from './Sharing/GrantAccessDialog';
 import { useUpdateAgentMutation } from '~/data-provider';
 import AdvancedButton from './Advanced/AdvancedButton';
 import VersionButton from './Version/VersionButton';
 import DuplicateAgent from './DuplicateAgent';
 import AdminSettings from './AdminSettings';
 import DeleteButton from './DeleteButton';
-import ShareAgent from './ShareAgent';
 import { Panel } from '~/common';
 
 export default function AgentFooter({
@@ -32,12 +37,17 @@ export default function AgentFooter({
   const { control } = methods;
   const agent = useWatch({ control, name: 'agent' });
   const agent_id = useWatch({ control, name: 'id' });
-
   const hasAccessToShareAgents = useHasAccess({
     permissionType: PermissionTypes.AGENTS,
     permission: Permissions.SHARED_GLOBAL,
   });
+  const { hasPermission, isLoading: permissionsLoading } = useResourcePermissions(
+    'agent',
+    agent?._id || '',
+  );
 
+  const canShareThisAgent = hasPermission(PERMISSION_BITS.SHARE);
+  const canDeleteThisAgent = hasPermission(PERMISSION_BITS.DELETE);
   const renderSaveButton = () => {
     if (createMutation.isLoading || updateMutation.isLoading) {
       return <Spinner className="icon-md" aria-hidden="true" />;
@@ -59,18 +69,21 @@ export default function AgentFooter({
       {user?.role === SystemRoles.ADMIN && showButtons && <AdminSettings />}
       {/* Context Button */}
       <div className="flex items-center justify-end gap-2">
+        {(agent?.author === user?.id || user?.role === SystemRoles.ADMIN || canDeleteThisAgent) &&
+          !permissionsLoading && (
             <DeleteButton
               agent_id={agent_id}
               setCurrentAgentId={setCurrentAgentId}
               createMutation={createMutation}
             />
-        {(agent?.author === user?.id || user?.role === SystemRoles.ADMIN) &&
+          )}
-          hasAccessToShareAgents && (
+        {(agent?.author === user?.id || user?.role === SystemRoles.ADMIN || canShareThisAgent) &&
-            <ShareAgent
+          hasAccessToShareAgents &&
-              agent_id={agent_id}
+          !permissionsLoading && (
+            <GrantAccessDialog
+              agentDbId={agent?._id}
+              agentId={agent_id}
               agentName={agent?.name ?? ''}
-              projectIds={agent?.projectIds ?? []}
-              isCollaborative={agent?.isCollaborative}
             />
           )}
         {agent && agent.author === user?.id && <DuplicateAgent agent_id={agent_id} />}

client/src/components/SidePanel/Agents/AgentGrid.tsx

@@ -0,0 +1,273 @@
+import React, { useState } from 'react';
+import { Button, Spinner } from '@librechat/client';
+import type t from 'librechat-data-provider';
+import { useDynamicAgentQuery, useAgentCategories } from '~/hooks/Agents';
+import { SmartLoader, useHasData } from './SmartLoader';
+import useLocalize from '~/hooks/useLocalize';
+import ErrorDisplay from './ErrorDisplay';
+import AgentCard from './AgentCard';
+import { cn } from '~/utils';
+
+interface AgentGridProps {
+  category: string; // Currently selected category
+  searchQuery: string; // Current search query
+  onSelectAgent: (agent: t.Agent) => void; // Callback when agent is selected
+}
+
+// Interface for the actual data structure returned by the API
+interface AgentGridData {
+  agents: t.Agent[];
+  pagination?: {
+    hasMore: boolean;
+    current: number;
+    total: number;
+  };
+}
+
+/**
+ * Component for displaying a grid of agent cards
+ */
+const AgentGrid: React.FC<AgentGridProps> = ({ category, searchQuery, onSelectAgent }) => {
+  const localize = useLocalize();
+  const [page, setPage] = useState(1);
+
+  // Get category data from API
+  const { categories } = useAgentCategories();
+
+  // Single dynamic query that handles all cases - much cleaner!
+  const {
+    data: rawData,
+    isLoading,
+    error,
+    isFetching,
+    refetch,
+  } = useDynamicAgentQuery({
+    category,
+    searchQuery,
+    page,
+    limit: 6,
+  });
+
+  // Type the data properly
+  const data = rawData as AgentGridData | undefined;
+
+  // Check if we have meaningful data to prevent unnecessary loading states
+  const hasData = useHasData(data);
+
+  /**
+   * Get category display name from API data or use fallback
+   */
+  const getCategoryDisplayName = (categoryValue: string) => {
+    const categoryData = categories.find((cat) => cat.value === categoryValue);
+    if (categoryData) {
+      return categoryData.label;
+    }
+
+    // Fallback for special categories or unknown categories
+    if (categoryValue === 'promoted') {
+      return localize('com_agents_top_picks');
+    }
+    if (categoryValue === 'all') {
+      return 'All';
+    }
+
+    // Simple capitalization for unknown categories
+    return categoryValue.charAt(0).toUpperCase() + categoryValue.slice(1);
+  };
+
+  /**
+   * Load more agents when "See More" button is clicked
+   */
+  const handleLoadMore = () => {
+    setPage((prevPage) => prevPage + 1);
+  };
+
+  /**
+   * Reset page when category or search changes
+   */
+  React.useEffect(() => {
+    setPage(1);
+  }, [category, searchQuery]);
+
+  /**
+   * Get the appropriate title for the agents grid based on current state
+   */
+  const getGridTitle = () => {
+    if (searchQuery) {
+      return localize('com_agents_results_for', { query: searchQuery });
+    }
+
+    return getCategoryDisplayName(category);
+  };
+
+  // Loading skeleton component
+  const loadingSkeleton = (
+    <div className="space-y-6">
+      <div className="mb-4">
+        <div className="mb-2 h-6 w-48 animate-pulse rounded-md bg-gray-200 dark:bg-gray-700"></div>
+        <div className="h-4 w-64 animate-pulse rounded-md bg-gray-200 dark:bg-gray-700"></div>
+      </div>
+      <div className="grid grid-cols-1 gap-6 md:grid-cols-2">
+        {Array(6)
+          .fill(0)
+          .map((_, index) => (
+            <div
+              key={index}
+              className={cn(
+                'flex h-[250px] animate-pulse flex-col overflow-hidden rounded-lg',
+                'bg-gray-200 dark:bg-gray-800',
+              )}
+            >
+              <div className="h-40 bg-gray-300 dark:bg-gray-700"></div>
+              <div className="flex-1 p-5">
+                <div className="mb-3 h-4 w-3/4 rounded bg-gray-300 dark:bg-gray-700"></div>
+                <div className="mb-2 h-3 w-full rounded bg-gray-300 dark:bg-gray-700"></div>
+                <div className="h-3 w-2/3 rounded bg-gray-300 dark:bg-gray-700"></div>
+              </div>
+            </div>
+          ))}
+      </div>
+    </div>
+  );
+
+  // Handle error state with enhanced error display
+  if (error) {
+    return (
+      <ErrorDisplay
+        error={error || 'Unknown error occurred'}
+        onRetry={() => refetch()}
+        context={{
+          searchQuery,
+          category,
+        }}
+      />
+    );
+  }
+
+  // Main content component with proper semantic structure
+  const mainContent = (
+    <div
+      className="space-y-6"
+      role="tabpanel"
+      id={`category-panel-${category}`}
+      aria-labelledby={`category-tab-${category}`}
+      aria-live="polite"
+      aria-busy={isLoading && !hasData}
+    >
+      {/* Grid title - only show for search results */}
+      {searchQuery && (
+        <div className="mb-4">
+          <h2
+            className="text-xl font-bold text-gray-900 dark:text-white"
+            id={`category-heading-${category}`}
+            aria-label={`${getGridTitle()}, ${data?.agents?.length || 0} agents available`}
+          >
+            {getGridTitle()}
+          </h2>
+        </div>
+      )}
+
+      {/* Handle empty results with enhanced accessibility */}
+      {(!data?.agents || data.agents.length === 0) && !isLoading && !isFetching ? (
+        <div
+          className="py-12 text-center text-gray-500"
+          role="status"
+          aria-live="polite"
+          aria-label={
+            searchQuery
+              ? localize('com_agents_search_empty_heading')
+              : localize('com_agents_empty_state_heading')
+          }
+        >
+          <h3 className="mb-2 text-lg font-medium">
+            {searchQuery
+              ? localize('com_agents_search_empty_heading')
+              : localize('com_agents_empty_state_heading')}
+          </h3>
+          <p className="text-sm">
+            {searchQuery
+              ? localize('com_agents_no_results')
+              : localize('com_agents_none_in_category')}
+          </p>
+        </div>
+      ) : (
+        <>
+          {/* Announcement for screen readers */}
+          <div id="search-results-count" className="sr-only" aria-live="polite" aria-atomic="true">
+            {localize('com_agents_grid_announcement', {
+              count: data?.agents?.length || 0,
+              category: getCategoryDisplayName(category),
+            })}
+          </div>
+
+          {/* Agent grid - 2 per row with proper semantic structure */}
+          {data?.agents && data.agents.length > 0 && (
+            <div
+              className="grid grid-cols-1 gap-6 md:grid-cols-2"
+              role="grid"
+              aria-label={localize('com_agents_grid_announcement', {
+                count: data.agents.length,
+                category: getCategoryDisplayName(category),
+              })}
+            >
+              {data.agents.map((agent: t.Agent, index: number) => (
+                <div key={`${agent.id}-${index}`} role="gridcell">
+                  <AgentCard agent={agent} onClick={() => onSelectAgent(agent)} />
+                </div>
+              ))}
+            </div>
+          )}
+
+          {/* Loading indicator when fetching more with accessibility */}
+          {isFetching && page > 1 && (
+            <div
+              className="flex justify-center py-4"
+              role="status"
+              aria-live="polite"
+              aria-label={localize('com_agents_loading')}
+            >
+              <Spinner className="h-6 w-6 text-primary" />
+              <span className="sr-only">{localize('com_agents_loading')}</span>
+            </div>
+          )}
+
+          {/* Load more button with enhanced accessibility */}
+          {data?.pagination?.hasMore && !isFetching && (
+            <div className="mt-8 flex justify-center">
+              <Button
+                variant="outline"
+                onClick={handleLoadMore}
+                className={cn(
+                  'min-w-[160px] border-2 border-gray-300 bg-white px-6 py-3 font-medium text-gray-700',
+                  'shadow-sm transition-all duration-200 hover:border-gray-400 hover:bg-gray-50',
+                  'hover:shadow-md focus:ring-2 focus:ring-blue-500 focus:ring-offset-2',
+                  'dark:border-gray-600 dark:bg-gray-800 dark:text-gray-200',
+                  'dark:hover:border-gray-500 dark:hover:bg-gray-700 dark:focus:ring-blue-400',
+                )}
+                aria-label={localize('com_agents_load_more_label', {
+                  category: getCategoryDisplayName(category),
+                })}
+              >
+                {localize('com_agents_see_more')}
+              </Button>
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  );
+
+  // Use SmartLoader to prevent unnecessary loading flashes
+  return (
+    <SmartLoader
+      isLoading={isLoading}
+      hasData={hasData}
+      delay={200} // Show loading only after 200ms delay
+      loadingComponent={loadingSkeleton}
+    >
+      {mainContent}
+    </SmartLoader>
+  );
+};
+
+export default AgentGrid;

client/src/components/SidePanel/Agents/AgentMarketplace.tsx

@@ -0,0 +1,297 @@
+import React, { useState, useEffect, useMemo } from 'react';
+import { useOutletContext } from 'react-router-dom';
+import { useSetRecoilState, useRecoilValue } from 'recoil';
+import { TooltipAnchor, Button, NewChatIcon } from '@librechat/client';
+import { useSearchParams, useParams, useNavigate } from 'react-router-dom';
+import type t from 'librechat-data-provider';
+import type { ContextType } from '~/common';
+import { useGetAgentCategoriesQuery, useGetEndpointsQuery } from '~/data-provider';
+import { MarketplaceProvider } from './MarketplaceContext';
+import { useDocumentTitle, useLocalize } from '~/hooks';
+import { SidePanelGroup } from '~/components/SidePanel';
+import { OpenSidebar } from '~/components/Chat/Menus';
+import CategoryTabs from './CategoryTabs';
+import AgentDetail from './AgentDetail';
+import SearchBar from './SearchBar';
+import AgentGrid from './AgentGrid';
+import store from '~/store';
+
+interface AgentMarketplaceProps {
+  className?: string;
+}
+
+/**
+ * AgentMarketplace - Main component for browsing and discovering agents
+ *
+ * Provides tabbed navigation for different agent categories,
+ * search functionality, and detailed agent view through a modal dialog.
+ * Uses URL parameters for state persistence and deep linking.
+ */
+const AgentMarketplace: React.FC<AgentMarketplaceProps> = ({ className = '' }) => {
+  const localize = useLocalize();
+  const navigate = useNavigate();
+  const [searchParams, setSearchParams] = useSearchParams();
+  const { category } = useParams();
+  const setHideSidePanel = useSetRecoilState(store.hideSidePanel);
+  const hideSidePanel = useRecoilValue(store.hideSidePanel);
+  const { navVisible, setNavVisible } = useOutletContext<ContextType>();
+
+  // Get URL parameters (default to 'promoted' instead of 'all')
+  const activeTab = category || 'promoted';
+  const searchQuery = searchParams.get('q') || '';
+  const selectedAgentId = searchParams.get('agent_id') || '';
+
+  // Local state
+  const [isDetailOpen, setIsDetailOpen] = useState(false);
+  const [selectedAgent, setSelectedAgent] = useState<t.Agent | null>(null);
+
+  // Set page title
+  useDocumentTitle(`${localize('com_agents_marketplace')} | LibreChat`);
+
+  // Ensure right sidebar is always visible in marketplace
+  useEffect(() => {
+    setHideSidePanel(false);
+
+    // Also try to force expand via localStorage
+    localStorage.setItem('hideSidePanel', 'false');
+    localStorage.setItem('fullPanelCollapse', 'false');
+  }, [setHideSidePanel, hideSidePanel]);
+
+  // Ensure endpoints config is loaded first (required for agent queries)
+  useGetEndpointsQuery();
+
+  // Fetch categories using existing query pattern
+  const categoriesQuery = useGetAgentCategoriesQuery({
+    staleTime: 1000 * 60 * 15, // 15 minutes - categories rarely change
+    refetchOnWindowFocus: false,
+    refetchOnReconnect: false,
+    refetchOnMount: false,
+  });
+
+  /**
+   * Handle agent card selection
+   *
+   * @param agent - The selected agent object
+   */
+  const handleAgentSelect = (agent: t.Agent) => {
+    // Update URL with selected agent
+    const newParams = new URLSearchParams(searchParams);
+    newParams.set('agent_id', agent.id);
+    setSearchParams(newParams);
+    setSelectedAgent(agent);
+    setIsDetailOpen(true);
+  };
+
+  /**
+   * Handle closing the agent detail dialog
+   */
+  const handleDetailClose = () => {
+    const newParams = new URLSearchParams(searchParams);
+    newParams.delete('agent_id');
+    setSearchParams(newParams);
+    setSelectedAgent(null);
+    setIsDetailOpen(false);
+  };
+
+  /**
+   * Handle category tab selection changes
+   *
+   * @param tabValue - The selected category value
+   */
+  const handleTabChange = (tabValue: string) => {
+    const currentSearchParams = searchParams.toString();
+    const searchParamsStr = currentSearchParams ? `?${currentSearchParams}` : '';
+
+    // Navigate to the selected category
+    if (tabValue === 'promoted') {
+      navigate(`/agents${searchParamsStr}`);
+    } else {
+      navigate(`/agents/${tabValue}${searchParamsStr}`);
+    }
+  };
+
+  /**
+   * Handle search query changes
+   *
+   * @param query - The search query string
+   */
+  const handleSearch = (query: string) => {
+    const newParams = new URLSearchParams(searchParams);
+    if (query.trim()) {
+      newParams.set('q', query.trim());
+      // Switch to "all" category when starting a new search
+      navigate(`/agents/all?${newParams.toString()}`);
+    } else {
+      newParams.delete('q');
+      // Preserve current category when clearing search
+      const currentCategory = activeTab;
+      if (currentCategory === 'promoted') {
+        navigate(`/agents${newParams.toString() ? `?${newParams.toString()}` : ''}`);
+      } else {
+        navigate(
+          `/agents/${currentCategory}${newParams.toString() ? `?${newParams.toString()}` : ''}`,
+        );
+      }
+    }
+  };
+
+  /**
+   * Handle new chat button click
+   */
+  const handleNewChat = (e: React.MouseEvent<HTMLButtonElement>) => {
+    if (e.button === 0 && (e.ctrlKey || e.metaKey)) {
+      window.open('/c/new', '_blank');
+      return;
+    }
+    navigate('/c/new');
+  };
+
+  // Check if a detail view should be open based on URL
+  useEffect(() => {
+    setIsDetailOpen(!!selectedAgentId);
+  }, [selectedAgentId]);
+
+  // Layout configuration for SidePanelGroup
+  const defaultLayout = useMemo(() => {
+    const resizableLayout = localStorage.getItem('react-resizable-panels:layout');
+    return typeof resizableLayout === 'string' ? JSON.parse(resizableLayout) : undefined;
+  }, []);
+
+  const defaultCollapsed = useMemo(() => {
+    const collapsedPanels = localStorage.getItem('react-resizable-panels:collapsed');
+    return typeof collapsedPanels === 'string' ? JSON.parse(collapsedPanels) : true;
+  }, []);
+
+  const fullCollapse = useMemo(() => localStorage.getItem('fullPanelCollapse') === 'true', []);
+
+  return (
+    <div className={`relative flex w-full grow overflow-hidden bg-presentation ${className}`}>
+      <MarketplaceProvider>
+        <SidePanelGroup
+          defaultLayout={defaultLayout}
+          fullPanelCollapse={fullCollapse}
+          defaultCollapsed={defaultCollapsed}
+        >
+          <main className="flex h-full flex-col overflow-y-auto" role="main">
+            {/* Simplified header for agents marketplace - only show nav controls when needed */}
+            <div className="sticky top-0 z-10 flex h-14 w-full items-center justify-between bg-white p-2 font-semibold text-text-primary dark:bg-gray-800">
+              <div className="mx-1 flex items-center gap-2">
+                {!navVisible && <OpenSidebar setNavVisible={setNavVisible} />}
+                {!navVisible && (
+                  <TooltipAnchor
+                    description={localize('com_ui_new_chat')}
+                    render={
+                      <Button
+                        size="icon"
+                        variant="outline"
+                        data-testid="agents-new-chat-button"
+                        aria-label={localize('com_ui_new_chat')}
+                        className="rounded-xl border border-border-light bg-surface-secondary p-2 hover:bg-surface-hover max-md:hidden"
+                        onClick={handleNewChat}
+                      >
+                        <NewChatIcon />
+                      </Button>
+                    }
+                  />
+                )}
+              </div>
+            </div>
+            <div className="container mx-auto max-w-4xl px-4 py-8">
+              {/* Hero Section - ChatGPT Style */}
+              <div className="mb-8 mt-12 text-center">
+                <h1 className="mb-3 text-5xl font-bold tracking-tight text-gray-900 dark:text-white">
+                  {localize('com_agents_marketplace')}
+                </h1>
+                <p className="mx-auto mb-6 max-w-2xl text-lg text-gray-600 dark:text-gray-300">
+                  {localize('com_agents_marketplace_subtitle')}
+                </p>
+
+                {/* Search bar */}
+                <div className="mx-auto max-w-2xl">
+                  <SearchBar value={searchQuery} onSearch={handleSearch} />
+                </div>
+              </div>
+
+              {/* Category tabs */}
+              <CategoryTabs
+                categories={categoriesQuery.data || []}
+                activeTab={activeTab}
+                isLoading={categoriesQuery.isLoading}
+                onChange={handleTabChange}
+              />
+
+              {/* Category header - only show when not searching */}
+              {!searchQuery && (
+                <div className="mb-6">
+                  {(() => {
+                    // Get category data for display
+                    const getCategoryData = () => {
+                      if (activeTab === 'promoted') {
+                        return {
+                          name: localize('com_agents_top_picks'),
+                          description: localize('com_agents_recommended'),
+                        };
+                      }
+                      if (activeTab === 'all') {
+                        return {
+                          name: 'All Agents',
+                          description: 'Browse all shared agents across all categories',
+                        };
+                      }
+
+                      // Find the category in the API data
+                      const categoryData = categoriesQuery.data?.find(
+                        (cat) => cat.value === activeTab,
+                      );
+                      if (categoryData) {
+                        return {
+                          name: categoryData.label,
+                          description: categoryData.description || '',
+                        };
+                      }
+
+                      // Fallback for unknown categories
+                      return {
+                        name: activeTab.charAt(0).toUpperCase() + activeTab.slice(1),
+                        description: '',
+                      };
+                    };
+
+                    const { name, description } = getCategoryData();
+
+                    return (
+                      <div className="text-left">
+                        <h2 className="text-2xl font-bold text-gray-900 dark:text-white">{name}</h2>
+                        {description && (
+                          <p className="mt-2 text-gray-600 dark:text-gray-300">{description}</p>
+                        )}
+                      </div>
+                    );
+                  })()}
+                </div>
+              )}
+
+              {/* Agent grid */}
+              <AgentGrid
+                category={activeTab}
+                searchQuery={searchQuery}
+                onSelectAgent={handleAgentSelect}
+              />
+            </div>
+
+            {/* Agent detail dialog */}
+            {isDetailOpen && selectedAgent && (
+              <AgentDetail
+                agent={selectedAgent}
+                isOpen={isDetailOpen}
+                onClose={handleDetailClose}
+              />
+            )}
+          </main>
+        </SidePanelGroup>
+      </MarketplaceProvider>
+    </div>
+  );
+};
+
+export default AgentMarketplace;

client/src/components/SidePanel/Agents/AgentPanel.tsx

@@ -8,6 +8,7 @@ import {
   Constants,
   SystemRoles,
   EModelEndpoint,
+  PERMISSION_BITS,
   isAssistantsEndpoint,
 } from 'librechat-data-provider';
 import type { AgentForm, StringOption } from '~/common';
@@ -15,8 +16,10 @@ import {
   useCreateAgentMutation,
   useUpdateAgentMutation,
   useGetAgentByIdQuery,
+  useGetExpandedAgentByIdQuery,
 } from '~/data-provider';
 import { createProviderOption, getDefaultAgentFormValues } from '~/utils';
+import { useResourcePermissions } from '~/hooks/useResourcePermissions';
 import { useSelectAgent, useLocalize, useAuthContext } from '~/hooks';
 import { useAgentPanelContext } from '~/Providers/AgentPanelContext';
 import AgentPanelSkeleton from './AgentPanelSkeleton';
@@ -43,10 +46,29 @@ export default function AgentPanel() {
   const { onSelect: onSelectAgent } = useSelectAgent();
 
   const modelsQuery = useGetModelsQuery();
-  const agentQuery = useGetAgentByIdQuery(current_agent_id ?? '', {
+
+  // Basic agent query for initial permission check
+  const basicAgentQuery = useGetAgentByIdQuery(current_agent_id ?? '', {
     enabled: !!(current_agent_id ?? '') && current_agent_id !== Constants.EPHEMERAL_AGENT_ID,
   });
 
+  const { hasPermission, isLoading: permissionsLoading } = useResourcePermissions(
+    'agent',
+    basicAgentQuery.data?._id || '',
+  );
+
+  const canEdit = hasPermission(PERMISSION_BITS.EDIT);
+
+  const expandedAgentQuery = useGetExpandedAgentByIdQuery(current_agent_id ?? '', {
+    enabled:
+      !!(current_agent_id ?? '') &&
+      current_agent_id !== Constants.EPHEMERAL_AGENT_ID &&
+      canEdit &&
+      !permissionsLoading,
+  });
+
+  const agentQuery = canEdit && expandedAgentQuery.data ? expandedAgentQuery : basicAgentQuery;
+
   const models = useMemo(() => modelsQuery.data ?? {}, [modelsQuery.data]);
   const methods = useForm<AgentForm>({
     defaultValues: getDefaultAgentFormValues(),
@@ -156,6 +178,8 @@ export default function AgentPanel() {
         end_after_tools,
         hide_sequential_outputs,
         recursion_limit,
+        category,
+        support_contact,
       } = data;
 
       const model = _model ?? '';
@@ -178,6 +202,8 @@ export default function AgentPanel() {
             end_after_tools,
             hide_sequential_outputs,
             recursion_limit,
+            category,
+            support_contact,
           },
         });
         return;
@@ -203,6 +229,8 @@ export default function AgentPanel() {
         end_after_tools,
         hide_sequential_outputs,
         recursion_limit,
+        category,
+        support_contact,
       });
     },
     [agent_id, create, update, showToast, localize],
@@ -215,19 +243,16 @@ export default function AgentPanel() {
   }, [agent_id, onSelectAgent]);
 
   const canEditAgent = useMemo(() => {
-    const canEdit =
+    if (!agentQuery.data?.id) {
-      (agentQuery.data?.isCollaborative ?? false)
+      return true;
-        ? true
+    }
-        : agentQuery.data?.author === user?.id || user?.role === SystemRoles.ADMIN;
 
-    return agentQuery.data?.id != null && agentQuery.data.id ? canEdit : true;
+    if (agentQuery.data?.author === user?.id || user?.role === SystemRoles.ADMIN) {
-  }, [
+      return true;
-    agentQuery.data?.isCollaborative,
+    }
-    agentQuery.data?.author,
+
-    agentQuery.data?.id,
+    return canEdit;
-    user?.id,
+  }, [agentQuery.data?.author, agentQuery.data?.id, user?.id, user?.role, canEdit]);
-    user?.role,
-  ]);
 
   return (
     <FormProvider {...methods}>
@@ -236,7 +261,7 @@ export default function AgentPanel() {
         className="scrollbar-gutter-stable h-auto w-full flex-shrink-0 overflow-x-hidden"
         aria-label="Agent configuration form"
       >
-        <div className="mt-2 flex w-full flex-wrap gap-2">
+        <div className="mx-1 mt-2 flex w-full flex-wrap gap-2">
           <div className="w-full">
             <AgentSelect
               createMutation={create}

client/src/components/SidePanel/Agents/AgentSelect.tsx

@@ -43,9 +43,7 @@ export default function AgentSelect({
 
   const resetAgentForm = useCallback(
     (fullAgent: Agent) => {
-      const { instanceProjectId } = startupConfig ?? {};
+      const isGlobal = fullAgent.isPublic ?? false;
-      const isGlobal =
-        (instanceProjectId != null && fullAgent.projectIds?.includes(instanceProjectId)) ?? false;
       const update = {
         ...fullAgent,
         provider: createProviderOption(fullAgent.provider),
@@ -77,6 +75,10 @@ export default function AgentSelect({
         agent: update,
         model: update.model,
         tools: agentTools,
+        // Ensure the category is properly set for the form
+        category: fullAgent.category || 'general',
+        // Make sure support_contact is properly loaded
+        support_contact: fullAgent.support_contact,
       };
 
       Object.entries(fullAgent).forEach(([name, value]) => {

client/src/components/SidePanel/Agents/CategoryTabs.tsx

@@ -0,0 +1,172 @@
+import React from 'react';
+
+import type t from 'librechat-data-provider';
+
+import useLocalize from '~/hooks/useLocalize';
+import { SmartLoader } from './SmartLoader';
+import { cn } from '~/utils';
+
+/**
+ * Props for the CategoryTabs component
+ */
+interface CategoryTabsProps {
+  /** Array of agent categories to display as tabs */
+  categories: t.TMarketplaceCategory[];
+  /** Currently selected tab value */
+  activeTab: string;
+  /** Whether categories are currently loading */
+  isLoading: boolean;
+  /** Callback fired when a tab is selected */
+  onChange: (value: string) => void;
+}
+
+/**
+ * CategoryTabs - Component for displaying category tabs with counts
+ *
+ * Renders a tabbed navigation interface showing agent categories.
+ * Includes loading states, empty state handling, and displays counts for each category.
+ * Uses database-driven category labels with no hardcoded values.
+ */
+const CategoryTabs: React.FC<CategoryTabsProps> = ({
+  categories,
+  activeTab,
+  isLoading,
+  onChange,
+}) => {
+  const localize = useLocalize();
+
+  // Helper function to get category display name from database data
+  const getCategoryDisplayName = (category: t.TCategory) => {
+    // Special cases for system categories
+    if (category.value === 'promoted') {
+      return localize('com_agents_top_picks');
+    }
+    if (category.value === 'all') {
+      return 'All';
+    }
+    // Use database label or fallback to capitalized value
+    return category.label || category.value.charAt(0).toUpperCase() + category.value.slice(1);
+  };
+
+  // Loading skeleton component
+  const loadingSkeleton = (
+    <div className="mb-8">
+      <div className="flex justify-center">
+        <div className="flex flex-wrap items-center justify-center gap-6">
+          {[...Array(6)].map((_, i) => (
+            <div
+              key={i}
+              className="h-6 min-w-[60px] animate-pulse rounded bg-gray-200 dark:bg-gray-700"
+            />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+
+  // Handle keyboard navigation between tabs
+  const handleKeyDown = (e: React.KeyboardEvent, currentCategory: string) => {
+    const currentIndex = categories.findIndex((cat) => cat.value === currentCategory);
+    let newIndex = currentIndex;
+
+    switch (e.key) {
+      case 'ArrowLeft':
+      case 'ArrowUp':
+        e.preventDefault();
+        newIndex = currentIndex > 0 ? currentIndex - 1 : categories.length - 1;
+        break;
+      case 'ArrowRight':
+      case 'ArrowDown':
+        e.preventDefault();
+        newIndex = currentIndex < categories.length - 1 ? currentIndex + 1 : 0;
+        break;
+      case 'Home':
+        e.preventDefault();
+        newIndex = 0;
+        break;
+      case 'End':
+        e.preventDefault();
+        newIndex = categories.length - 1;
+        break;
+      default:
+        return;
+    }
+
+    const newCategory = categories[newIndex];
+    if (newCategory) {
+      onChange(newCategory.value);
+      // Focus the new tab
+      setTimeout(() => {
+        const newTab = document.getElementById(`category-tab-${newCategory.value}`);
+        newTab?.focus();
+      }, 0);
+    }
+  };
+
+  // Early return if no categories available
+  if (!isLoading && (!categories || categories.length === 0)) {
+    return (
+      <div className="mb-8 text-center text-gray-500">{localize('com_agents_no_categories')}</div>
+    );
+  }
+
+  // Main tabs content
+  const tabsContent = (
+    <div className="mb-8">
+      <div className="flex justify-center">
+        {/* Accessible tab navigation with proper ARIA attributes */}
+        <div
+          className="flex flex-wrap items-center justify-center gap-6"
+          role="tablist"
+          aria-label={localize('com_agents_category_tabs_label')}
+          aria-orientation="horizontal"
+        >
+          {categories.map((category, index) => (
+            <button
+              key={category.value}
+              id={`category-tab-${category.value}`}
+              onClick={() => onChange(category.value)}
+              onKeyDown={(e) => handleKeyDown(e, category.value)}
+              className={cn(
+                'relative px-4 py-2 text-sm font-medium transition-colors duration-200',
+                'focus:bg-gray-100 focus:outline-none dark:focus:bg-gray-800',
+                'hover:text-gray-900 dark:hover:text-white',
+                activeTab === category.value
+                  ? 'text-gray-900 dark:text-white'
+                  : 'text-gray-600 dark:text-gray-400',
+              )}
+              role="tab"
+              aria-selected={activeTab === category.value}
+              aria-controls={`tabpanel-${category.value}`}
+              tabIndex={activeTab === category.value ? 0 : -1}
+              aria-label={`${getCategoryDisplayName(category)} tab (${index + 1} of ${categories.length})`}
+            >
+              <span className="truncate">{getCategoryDisplayName(category)}</span>
+              {/* Underline for active tab */}
+              {activeTab === category.value && (
+                <div
+                  className="absolute bottom-0 left-0 right-0 h-0.5 rounded-full bg-gray-900 dark:bg-white"
+                  aria-hidden="true"
+                />
+              )}
+            </button>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+
+  // Use SmartLoader to prevent category loading flashes
+  return (
+    <SmartLoader
+      isLoading={isLoading}
+      hasData={categories?.length > 0}
+      delay={100} // Very short delay since categories should load quickly
+      loadingComponent={loadingSkeleton}
+    >
+      {tabsContent}
+    </SmartLoader>
+  );
+};
+
+export default CategoryTabs;

client/src/components/SidePanel/Agents/ErrorDisplay.tsx

@@ -0,0 +1,238 @@
+import React from 'react';
+import { Button } from '@librechat/client';
+import { useLocalize } from '~/hooks';
+import { cn } from '~/utils';
+
+// Comprehensive error type that handles all possible error structures
+type ApiError =
+  | string
+  | Error
+  | {
+      message?: string;
+      status?: number;
+      code?: string;
+      response?: {
+        data?: {
+          userMessage?: string;
+          suggestion?: string;
+          message?: string;
+        };
+        status?: number;
+      };
+      data?: {
+        userMessage?: string;
+        suggestion?: string;
+        message?: string;
+      };
+    };
+
+interface ErrorDisplayProps {
+  error: ApiError;
+  onRetry?: () => void;
+  context?: {
+    searchQuery?: string;
+    category?: string;
+  };
+}
+
+/**
+ * User-friendly error display component with actionable suggestions
+ */
+export const ErrorDisplay: React.FC<ErrorDisplayProps> = ({ error, onRetry, context }) => {
+  const localize = useLocalize();
+
+  // Type guards
+  const isErrorObject = (err: ApiError): err is { [key: string]: unknown } => {
+    return typeof err === 'object' && err !== null && !(err instanceof Error);
+  };
+
+  const isErrorInstance = (err: ApiError): err is Error => {
+    return err instanceof Error;
+  };
+
+  // Extract user-friendly error information
+  const getErrorInfo = (): { title: string; message: string; suggestion: string } => {
+    // Handle different error types
+    let errorData: unknown;
+
+    if (typeof error === 'string') {
+      errorData = { message: error };
+    } else if (isErrorInstance(error)) {
+      errorData = { message: error.message };
+    } else if (isErrorObject(error)) {
+      // Handle axios error response structure
+      errorData = (error as any)?.response?.data || (error as any)?.data || error;
+    } else {
+      errorData = error;
+    }
+
+    // Use user-friendly message from backend if available
+    if (errorData && typeof errorData === 'object' && (errorData as any)?.userMessage) {
+      return {
+        title: getContextualTitle(),
+        message: (errorData as any).userMessage,
+        suggestion:
+          (errorData as any).suggestion || localize('com_agents_error_suggestion_generic'),
+      };
+    }
+
+    // Handle network errors
+    const errorMessage = isErrorInstance(error)
+      ? error.message
+      : isErrorObject(error) && (error as any)?.message
+        ? (error as any).message
+        : '';
+    const errorCode = isErrorObject(error) ? (error as any)?.code : '';
+    if (errorCode === 'NETWORK_ERROR' || errorMessage?.includes('Network Error')) {
+      return {
+        title: localize('com_agents_error_network_title'),
+        message: localize('com_agents_error_network_message'),
+        suggestion: localize('com_agents_error_network_suggestion'),
+      };
+    }
+
+    // Handle specific HTTP status codes
+    const status = isErrorObject(error) ? (error as any)?.response?.status : null;
+    if (status) {
+      if (status === 404) {
+        return {
+          title: localize('com_agents_error_not_found_title'),
+          message: getNotFoundMessage(),
+          suggestion: localize('com_agents_error_not_found_suggestion'),
+        };
+      }
+
+      if (status === 400) {
+        return {
+          title: localize('com_agents_error_invalid_request'),
+          message:
+            (errorData as any)?.userMessage || localize('com_agents_error_bad_request_message'),
+          suggestion: localize('com_agents_error_bad_request_suggestion'),
+        };
+      }
+
+      if (status >= 500) {
+        return {
+          title: localize('com_agents_error_server_title'),
+          message: localize('com_agents_error_server_message'),
+          suggestion: localize('com_agents_error_server_suggestion'),
+        };
+      }
+    }
+
+    // Fallback to generic error
+    return {
+      title: localize('com_agents_error_title'),
+      message: localize('com_agents_error_generic'),
+      suggestion: localize('com_agents_error_suggestion_generic'),
+    };
+  };
+
+  /**
+   * Get contextual title based on current operation
+   */
+  const getContextualTitle = (): string => {
+    if (context?.searchQuery) {
+      return localize('com_agents_error_search_title');
+    }
+
+    if (context?.category) {
+      return localize('com_agents_error_category_title');
+    }
+
+    return localize('com_agents_error_title');
+  };
+
+  /**
+   * Get context-specific not found message
+   */
+  const getNotFoundMessage = (): string => {
+    if (context?.searchQuery) {
+      return localize('com_agents_search_no_results', { query: context.searchQuery });
+    }
+
+    if (context?.category && context.category !== 'all') {
+      return localize('com_agents_category_empty', { category: context.category });
+    }
+
+    return localize('com_agents_error_not_found_message');
+  };
+
+  const { title, message, suggestion } = getErrorInfo();
+
+  return (
+    <div className="py-12 text-center" role="alert" aria-live="assertive" aria-atomic="true">
+      <div className="mx-auto max-w-md space-y-4">
+        {/* Error icon with proper accessibility */}
+        <div className="flex justify-center">
+          <div
+            className={cn(
+              'flex h-12 w-12 items-center justify-center rounded-full',
+              'bg-red-100 dark:bg-red-900/20',
+            )}
+          >
+            <svg
+              className="h-6 w-6 text-red-600 dark:text-red-400"
+              fill="none"
+              viewBox="0 0 24 24"
+              strokeWidth={2}
+              stroke="currentColor"
+              aria-hidden="true"
+              role="img"
+              aria-label="Error icon"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126zM12 15.75h.007v.008H12v-.008z"
+              />
+            </svg>
+          </div>
+        </div>
+
+        {/* Error content with proper headings and structure */}
+        <div className="space-y-3">
+          <h2 className="text-lg font-semibold text-gray-900 dark:text-white" id="error-title">
+            {title}
+          </h2>
+          <p
+            className="text-gray-600 dark:text-gray-400"
+            id="error-message"
+            aria-describedby="error-title"
+          >
+            {message}
+          </p>
+          <p
+            className="text-sm text-gray-500 dark:text-gray-500"
+            id="error-suggestion"
+            role="note"
+            aria-label={`Suggestion: ${suggestion}`}
+          >
+            💡 {suggestion}
+          </p>
+        </div>
+
+        {/* Retry button with enhanced accessibility */}
+        {onRetry && (
+          <div className="pt-2">
+            <Button
+              onClick={onRetry}
+              variant="outline"
+              size="sm"
+              className={cn(
+                'border-red-300 text-red-700 hover:bg-red-50 focus:ring-2 focus:ring-red-500',
+                'dark:border-red-600 dark:text-red-400 dark:hover:bg-red-900/20 dark:focus:ring-red-400',
+              )}
+              aria-describedby="error-message error-suggestion"
+              aria-label={`Retry action. ${message}`}
+            >
+              {localize('com_agents_error_retry')}
+            </Button>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default ErrorDisplay;

client/src/components/SidePanel/Agents/MarketplaceContext.tsx

@@ -0,0 +1,44 @@
+import React, { useMemo } from 'react';
+
+import { EModelEndpoint } from 'librechat-data-provider';
+
+import { ChatContext } from '~/Providers';
+
+/**
+ * Minimal marketplace provider that provides only what SidePanel actually needs
+ * Replaces the bloated 44-function ChatContext implementation
+ */
+interface MarketplaceProviderProps {
+  children: React.ReactNode;
+}
+
+export const MarketplaceProvider: React.FC<MarketplaceProviderProps> = ({ children }) => {
+  // Create more complete context to prevent FileRow and other component errors
+  // when agents with files are opened in the marketplace
+  const marketplaceContext = useMemo(
+    () => ({
+      conversation: {
+        endpoint: EModelEndpoint.agents,
+        conversationId: 'marketplace',
+        title: 'Agent Marketplace',
+      },
+      // File-related context properties to prevent FileRow errors
+      files: new Map(),
+      setFiles: () => {},
+      setFilesLoading: () => {},
+      // Other commonly used context properties to prevent undefined errors
+      isSubmitting: false,
+      setIsSubmitting: () => {},
+      latestMessage: null,
+      setLatestMessage: () => {},
+      // Minimal functions to prevent errors when components try to use them
+      ask: () => {},
+      regenerate: () => {},
+      stopGenerating: () => {},
+      submitMessage: () => {},
+    }),
+    [],
+  );
+
+  return <ChatContext.Provider value={marketplaceContext as any}>{children}</ChatContext.Provider>;
+};

client/src/components/SidePanel/Agents/SearchBar.tsx

@@ -0,0 +1,109 @@
+import React, { useState, useEffect, useCallback } from 'react';
+import { Search, X } from 'lucide-react';
+import { Input } from '@librechat/client';
+import { useDebounce, useLocalize } from '~/hooks';
+
+/**
+ * Props for the SearchBar component
+ */
+interface SearchBarProps {
+  /** Current search query value */
+  value: string;
+  /** Callback fired when the search query changes */
+  onSearch: (query: string) => void;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+/**
+ * SearchBar - Component for searching agents with debounced input
+ *
+ * Provides a search input with clear button and debounced search functionality.
+ * Includes proper ARIA attributes for accessibility and visual indicators.
+ * Uses 300ms debounce delay to prevent excessive API calls during typing.
+ */
+const SearchBar: React.FC<SearchBarProps> = ({ value, onSearch, className = '' }) => {
+  const localize = useLocalize();
+  const [searchTerm, setSearchTerm] = useState(value);
+
+  // Debounced search value (300ms delay)
+  const debouncedSearchTerm = useDebounce(searchTerm, 300);
+
+  // Update internal state when props change
+  useEffect(() => {
+    setSearchTerm(value);
+  }, [value]);
+
+  // Trigger search when debounced value changes
+  useEffect(() => {
+    // Only trigger search if the debounced value matches current searchTerm
+    // This prevents stale debounced values from triggering after clear
+    if (debouncedSearchTerm !== value && debouncedSearchTerm === searchTerm) {
+      onSearch(debouncedSearchTerm);
+    }
+  }, [debouncedSearchTerm, onSearch, value, searchTerm]);
+
+  /**
+   * Handle search input changes
+   *
+   * @param e - Input change event
+   */
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    setSearchTerm(e.target.value);
+  };
+
+  /**
+   * Clear the search input and reset results
+   */
+  const handleClear = useCallback(() => {
+    // Immediately call parent onSearch to clear the URL parameter
+    onSearch('');
+    // Also clear local state
+    setSearchTerm('');
+  }, [onSearch]);
+
+  return (
+    <div className={`relative w-full max-w-4xl ${className}`} role="search">
+      <label htmlFor="agent-search" className="sr-only">
+        {localize('com_agents_search_instructions')}
+      </label>
+      <Input
+        id="agent-search"
+        type="text"
+        value={searchTerm}
+        onChange={handleChange}
+        placeholder={localize('com_agents_search_placeholder')}
+        className="h-14 rounded-2xl border-2 border-gray-200 bg-white pl-12 pr-12 text-lg text-gray-900 shadow-lg placeholder:text-gray-500 focus:border-gray-300 focus:ring-0 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-100 dark:placeholder:text-gray-400 dark:focus:border-gray-500"
+        aria-label={localize('com_agents_search_aria')}
+        aria-describedby="search-instructions search-results-count"
+        autoComplete="off"
+        spellCheck="false"
+      />
+
+      {/* Search icon with proper accessibility */}
+      <div className="absolute inset-y-0 left-0 flex items-center pl-4" aria-hidden="true">
+        <Search className="h-6 w-6 text-gray-400" />
+      </div>
+
+      {/* Hidden instructions for screen readers */}
+      <div id="search-instructions" className="sr-only">
+        {localize('com_agents_search_instructions')}
+      </div>
+
+      {/* Show clear button only when search has value - Google style */}
+      {searchTerm && (
+        <button
+          type="button"
+          onClick={handleClear}
+          className="group absolute right-3 top-1/2 flex h-6 w-6 -translate-y-1/2 items-center justify-center rounded-full bg-gray-400 transition-colors duration-150 hover:bg-gray-500 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 dark:bg-gray-500 dark:hover:bg-gray-400"
+          aria-label={localize('com_agents_clear_search')}
+          title={localize('com_agents_clear_search')}
+        >
+          <X className="h-3 w-3 text-white group-hover:text-white" strokeWidth={2.5} />
+        </button>
+      )}
+    </div>
+  );
+};
+
+export default SearchBar;

client/src/components/SidePanel/Agents/ShareAgent.tsx

@@ -1,270 +0,0 @@
-import React, { useEffect, useMemo } from 'react';
-import { Share2Icon } from 'lucide-react';
-import { useForm, Controller } from 'react-hook-form';
-import { Permissions } from 'librechat-data-provider';
-import {
-  Button,
-  Switch,
-  OGDialog,
-  OGDialogTitle,
-  OGDialogClose,
-  OGDialogContent,
-  OGDialogTrigger,
-  useToastContext,
-} from '@librechat/client';
-import type { TStartupConfig, AgentUpdateParams } from 'librechat-data-provider';
-import { useUpdateAgentMutation, useGetStartupConfig } from '~/data-provider';
-import { cn, removeFocusOutlines } from '~/utils';
-import { useLocalize } from '~/hooks';
-
-type FormValues = {
-  [Permissions.SHARED_GLOBAL]: boolean;
-  [Permissions.UPDATE]: boolean;
-};
-
-export default function ShareAgent({
-  agent_id = '',
-  agentName,
-  projectIds = [],
-  isCollaborative = false,
-}: {
-  agent_id?: string;
-  agentName?: string;
-  projectIds?: string[];
-  isCollaborative?: boolean;
-}) {
-  const localize = useLocalize();
-  const { showToast } = useToastContext();
-  const { data: startupConfig = {} as TStartupConfig, isFetching } = useGetStartupConfig();
-  const { instanceProjectId } = startupConfig;
-  const agentIsGlobal = useMemo(
-    () => !!projectIds.includes(instanceProjectId),
-    [projectIds, instanceProjectId],
-  );
-
-  const {
-    watch,
-    control,
-    setValue,
-    getValues,
-    handleSubmit,
-    formState: { isSubmitting },
-  } = useForm<FormValues>({
-    mode: 'onChange',
-    defaultValues: {
-      [Permissions.SHARED_GLOBAL]: agentIsGlobal,
-      [Permissions.UPDATE]: isCollaborative,
-    },
-  });
-
-  const sharedGlobalValue = watch(Permissions.SHARED_GLOBAL);
-
-  useEffect(() => {
-    if (!sharedGlobalValue) {
-      setValue(Permissions.UPDATE, false);
-    }
-  }, [sharedGlobalValue, setValue]);
-
-  useEffect(() => {
-    setValue(Permissions.SHARED_GLOBAL, agentIsGlobal);
-    setValue(Permissions.UPDATE, isCollaborative);
-  }, [agentIsGlobal, isCollaborative, setValue]);
-
-  const updateAgent = useUpdateAgentMutation({
-    onSuccess: (data) => {
-      showToast({
-        message: `${localize('com_assistants_update_success')} ${
-          data.name ?? localize('com_ui_agent')
-        }`,
-        status: 'success',
-      });
-    },
-    onError: (err) => {
-      const error = err as Error;
-      showToast({
-        message: `${localize('com_agents_update_error')}${
-          error.message ? ` ${localize('com_ui_error')}: ${error.message}` : ''
-        }`,
-        status: 'error',
-      });
-    },
-  });
-
-  if (!agent_id || !instanceProjectId) {
-    return null;
-  }
-
-  const onSubmit = (data: FormValues) => {
-    if (!agent_id || !instanceProjectId) {
-      return;
-    }
-
-    const payload = {} as AgentUpdateParams;
-
-    if (data[Permissions.UPDATE] !== isCollaborative) {
-      payload.isCollaborative = data[Permissions.UPDATE];
-    }
-
-    if (data[Permissions.SHARED_GLOBAL] !== agentIsGlobal) {
-      if (data[Permissions.SHARED_GLOBAL]) {
-        payload.projectIds = [startupConfig.instanceProjectId];
-      } else {
-        payload.removeProjectIds = [startupConfig.instanceProjectId];
-        payload.isCollaborative = false;
-      }
-    }
-
-    if (Object.keys(payload).length > 0) {
-      updateAgent.mutate({
-        agent_id,
-        data: payload,
-      });
-    } else {
-      showToast({
-        message: localize('com_ui_no_changes'),
-        status: 'info',
-      });
-    }
-  };
-
-  return (
-    <OGDialog>
-      <OGDialogTrigger asChild>
-        <button
-          className={cn(
-            'btn btn-neutral border-token-border-light relative h-9 rounded-lg font-medium',
-            removeFocusOutlines,
-          )}
-          aria-label={localize('com_ui_share_var', {
-            0: agentName != null && agentName !== '' ? `"${agentName}"` : localize('com_ui_agent'),
-          })}
-          type="button"
-        >
-          <div className="flex items-center justify-center gap-2 text-blue-500">
-            <Share2Icon className="icon-md h-4 w-4" />
-          </div>
-        </button>
-      </OGDialogTrigger>
-      <OGDialogContent className="w-11/12 md:max-w-xl">
-        <OGDialogTitle>
-          {localize('com_ui_share_var', {
-            0: agentName != null && agentName !== '' ? `"${agentName}"` : localize('com_ui_agent'),
-          })}
-        </OGDialogTitle>
-        <form
-          className="p-2"
-          onSubmit={(e) => {
-            e.preventDefault();
-            e.stopPropagation();
-            handleSubmit(onSubmit)(e);
-          }}
-        >
-          <div className="flex items-center justify-between gap-2 py-2">
-            <div className="flex items-center">
-              <button
-                type="button"
-                className="mr-2 cursor-pointer"
-                disabled={isFetching || updateAgent.isLoading || !instanceProjectId}
-                onClick={() =>
-                  setValue(Permissions.SHARED_GLOBAL, !getValues(Permissions.SHARED_GLOBAL), {
-                    shouldDirty: true,
-                  })
-                }
-                onKeyDown={(e) => {
-                  if (e.key === 'Enter' || e.key === ' ') {
-                    e.preventDefault();
-                    setValue(Permissions.SHARED_GLOBAL, !getValues(Permissions.SHARED_GLOBAL), {
-                      shouldDirty: true,
-                    });
-                  }
-                }}
-                aria-checked={getValues(Permissions.SHARED_GLOBAL)}
-                role="checkbox"
-              >
-                {localize('com_ui_share_to_all_users')}
-              </button>
-              <label htmlFor={Permissions.SHARED_GLOBAL} className="select-none">
-                {agentIsGlobal && (
-                  <span className="ml-2 text-xs">{localize('com_ui_agent_shared_to_all')}</span>
-                )}
-              </label>
-            </div>
-            <Controller
-              name={Permissions.SHARED_GLOBAL}
-              control={control}
-              disabled={isFetching || updateAgent.isLoading || !instanceProjectId}
-              render={({ field }) => (
-                <Switch
-                  {...field}
-                  checked={field.value}
-                  onCheckedChange={field.onChange}
-                  value={field.value.toString()}
-                />
-              )}
-            />
-          </div>
-          <div className="mb-4 flex items-center justify-between gap-2 py-2">
-            <div className="flex items-center">
-              <button
-                type="button"
-                className="mr-2 cursor-pointer"
-                disabled={
-                  isFetching || updateAgent.isLoading || !instanceProjectId || !sharedGlobalValue
-                }
-                onClick={() =>
-                  setValue(Permissions.UPDATE, !getValues(Permissions.UPDATE), {
-                    shouldDirty: true,
-                  })
-                }
-                onKeyDown={(e) => {
-                  if (e.key === 'Enter' || e.key === ' ') {
-                    e.preventDefault();
-                    setValue(Permissions.UPDATE, !getValues(Permissions.UPDATE), {
-                      shouldDirty: true,
-                    });
-                  }
-                }}
-                aria-checked={getValues(Permissions.UPDATE)}
-                role="checkbox"
-              >
-                {localize('com_agents_allow_editing')}
-              </button>
-              {/* <label htmlFor={Permissions.UPDATE} className="select-none">
-                {agentIsGlobal && (
-                  <span className="ml-2 text-xs">{localize('com_ui_agent_editing_allowed')}</span>
-                )}
-              </label> */}
-            </div>
-            <Controller
-              name={Permissions.UPDATE}
-              control={control}
-              disabled={
-                isFetching || updateAgent.isLoading || !instanceProjectId || !sharedGlobalValue
-              }
-              render={({ field }) => (
-                <Switch
-                  {...field}
-                  checked={field.value}
-                  onCheckedChange={field.onChange}
-                  value={field.value.toString()}
-                />
-              )}
-            />
-          </div>
-          <div className="flex justify-end">
-            <OGDialogClose asChild>
-              <Button
-                variant="submit"
-                size="sm"
-                type="submit"
-                disabled={isSubmitting || isFetching}
-              >
-                {localize('com_ui_save')}
-              </Button>
-            </OGDialogClose>
-          </div>
-        </form>
-      </OGDialogContent>
-    </OGDialog>
-  );
-}

client/src/components/SidePanel/Agents/Sharing/AccessRolesPicker.tsx

@@ -0,0 +1,99 @@
+import React from 'react';
+import { ACCESS_ROLE_IDS } from 'librechat-data-provider';
+import type { AccessRole } from 'librechat-data-provider';
+import { useGetAccessRolesQuery } from 'librechat-data-provider/react-query';
+import SelectDropDownPop from '~/components/Input/ModelSelect/SelectDropDownPop';
+import { useLocalize } from '~/hooks';
+
+interface AccessRolesPickerProps {
+  resourceType?: string;
+  selectedRoleId?: string;
+  onRoleChange: (roleId: string) => void;
+  className?: string;
+}
+
+export default function AccessRolesPicker({
+  resourceType = 'agent',
+  selectedRoleId = ACCESS_ROLE_IDS.AGENT_VIEWER,
+  onRoleChange,
+  className = '',
+}: AccessRolesPickerProps) {
+  const localize = useLocalize();
+
+  // Fetch access roles from API
+  const { data: accessRoles, isLoading: rolesLoading } = useGetAccessRolesQuery(resourceType);
+
+  // Helper function to get localized role name and description
+  const getLocalizedRoleInfo = (roleId: string) => {
+    switch (roleId) {
+      case 'agent_viewer':
+        return {
+          name: localize('com_ui_role_viewer'),
+          description: localize('com_ui_role_viewer_desc'),
+        };
+      case 'agent_editor':
+        return {
+          name: localize('com_ui_role_editor'),
+          description: localize('com_ui_role_editor_desc'),
+        };
+      case 'agent_manager':
+        return {
+          name: localize('com_ui_role_manager'),
+          description: localize('com_ui_role_manager_desc'),
+        };
+      case 'agent_owner':
+        return {
+          name: localize('com_ui_role_owner'),
+          description: localize('com_ui_role_owner_desc'),
+        };
+      default:
+        return {
+          name: localize('com_ui_unknown'),
+          description: localize('com_ui_unknown'),
+        };
+    }
+  };
+
+  // Find the currently selected role
+  const selectedRole = accessRoles?.find((role) => role.accessRoleId === selectedRoleId);
+
+  if (rolesLoading || !accessRoles) {
+    return (
+      <div className={className}>
+        <div className="flex items-center justify-center py-2">
+          <div className="h-4 w-4 animate-spin rounded-full border-2 border-gray-300 border-t-blue-600"></div>
+          <span className="ml-2 text-sm text-gray-500">Loading roles...</span>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className={className}>
+      <SelectDropDownPop
+        availableValues={accessRoles.map((role: AccessRole) => {
+          const localizedInfo = getLocalizedRoleInfo(role.accessRoleId);
+          return {
+            value: role.accessRoleId,
+            label: localizedInfo.name,
+            description: localizedInfo.description,
+          };
+        })}
+        showLabel={false}
+        value={
+          selectedRole
+            ? (() => {
+                const localizedInfo = getLocalizedRoleInfo(selectedRole.accessRoleId);
+                return {
+                  value: selectedRole.accessRoleId,
+                  label: localizedInfo.name,
+                  description: localizedInfo.description,
+                };
+              })()
+            : null
+        }
+        setValue={onRoleChange}
+      />
+    </div>
+  );
+}

client/src/components/SidePanel/Agents/Sharing/GrantAccessDialog.tsx

@@ -0,0 +1,265 @@
+import React, { useState, useEffect } from 'react';
+import { ACCESS_ROLE_IDS } from 'librechat-data-provider';
+import { Share2Icon, Users, Loader, Shield, Link, CopyCheck } from 'lucide-react';
+import {
+  useGetResourcePermissionsQuery,
+  useUpdateResourcePermissionsMutation,
+} from 'librechat-data-provider/react-query';
+import {
+  Button,
+  OGDialog,
+  OGDialogTitle,
+  OGDialogClose,
+  OGDialogContent,
+  OGDialogTrigger,
+  useToastContext,
+} from '@librechat/client';
+import type { TPrincipal } from 'librechat-data-provider';
+import ManagePermissionsDialog from './ManagePermissionsDialog';
+import { useLocalize, useCopyToClipboard } from '~/hooks';
+import PublicSharingToggle from './PublicSharingToggle';
+import PeoplePicker from './PeoplePicker/PeoplePicker';
+import AccessRolesPicker from './AccessRolesPicker';
+import { cn, removeFocusOutlines } from '~/utils';
+
+export default function GrantAccessDialog({
+  agentName,
+  onGrantAccess,
+  resourceType = 'agent',
+  agentDbId,
+  agentId,
+}: {
+  agentDbId?: string | null;
+  agentId?: string | null;
+  agentName?: string;
+  onGrantAccess?: (shares: TPrincipal[], isPublic: boolean, publicRole: string) => void;
+  resourceType?: string;
+}) {
+  const localize = useLocalize();
+  const { showToast } = useToastContext();
+
+  const {
+    data: permissionsData,
+    // isLoading: isLoadingPermissions,
+    // error: permissionsError,
+  } = useGetResourcePermissionsQuery(resourceType, agentDbId!, {
+    enabled: !!agentDbId,
+  });
+
+  const updatePermissionsMutation = useUpdateResourcePermissionsMutation();
+
+  const [newShares, setNewShares] = useState<TPrincipal[]>([]);
+  const [defaultPermissionId, setDefaultPermissionId] = useState<string>(
+    ACCESS_ROLE_IDS.AGENT_VIEWER,
+  );
+  const [isModalOpen, setIsModalOpen] = useState(false);
+  const [isCopying, setIsCopying] = useState(false);
+
+  const agentUrl = `${window.location.origin}/c/new?agent_id=${agentId}`;
+  const copyAgentUrl = useCopyToClipboard({ text: agentUrl });
+
+  const currentShares: TPrincipal[] =
+    permissionsData?.principals?.map((principal) => ({
+      type: principal.type,
+      id: principal.id,
+      name: principal.name,
+      email: principal.email,
+      source: principal.source,
+      avatar: principal.avatar,
+      description: principal.description,
+      accessRoleId: principal.accessRoleId,
+    })) || [];
+
+  const currentIsPublic = permissionsData?.public ?? false;
+  const currentPublicRole = permissionsData?.publicAccessRoleId || ACCESS_ROLE_IDS.AGENT_VIEWER;
+
+  const [isPublic, setIsPublic] = useState(false);
+  const [publicRole, setPublicRole] = useState<string>(ACCESS_ROLE_IDS.AGENT_VIEWER);
+
+  useEffect(() => {
+    if (permissionsData && isModalOpen) {
+      setIsPublic(currentIsPublic ?? false);
+      setPublicRole(currentPublicRole);
+    }
+  }, [permissionsData, isModalOpen, currentIsPublic, currentPublicRole]);
+
+  if (!agentDbId) {
+    return null;
+  }
+
+  const handleGrantAccess = async () => {
+    try {
+      const sharesToAdd = newShares.map((share) => ({
+        ...share,
+        accessRoleId: defaultPermissionId,
+      }));
+
+      const allShares = [...currentShares, ...sharesToAdd];
+
+      await updatePermissionsMutation.mutateAsync({
+        resourceType,
+        resourceId: agentDbId,
+        data: {
+          updated: sharesToAdd,
+          removed: [],
+          public: isPublic,
+          publicAccessRoleId: isPublic ? publicRole : undefined,
+        },
+      });
+
+      if (onGrantAccess) {
+        onGrantAccess(allShares, isPublic, publicRole);
+      }
+
+      showToast({
+        message: `Access granted successfully to ${newShares.length} ${newShares.length === 1 ? 'person' : 'people'}${isPublic ? ' and made public' : ''}`,
+        status: 'success',
+      });
+
+      setNewShares([]);
+      setDefaultPermissionId(ACCESS_ROLE_IDS.AGENT_VIEWER);
+      setIsPublic(false);
+      setPublicRole(ACCESS_ROLE_IDS.AGENT_VIEWER);
+      setIsModalOpen(false);
+    } catch (error) {
+      console.error('Error granting access:', error);
+      showToast({
+        message: 'Failed to grant access. Please try again.',
+        status: 'error',
+      });
+    }
+  };
+
+  const handleCancel = () => {
+    setNewShares([]);
+    setDefaultPermissionId(ACCESS_ROLE_IDS.AGENT_VIEWER);
+    setIsPublic(false);
+    setPublicRole(ACCESS_ROLE_IDS.AGENT_VIEWER);
+    setIsModalOpen(false);
+  };
+
+  const totalCurrentShares = currentShares.length + (currentIsPublic ? 1 : 0);
+  const submitButtonActive =
+    newShares.length > 0 || isPublic !== currentIsPublic || publicRole !== currentPublicRole;
+  return (
+    <OGDialog open={isModalOpen} onOpenChange={setIsModalOpen} modal>
+      <OGDialogTrigger asChild>
+        <button
+          className={cn(
+            'btn btn-neutral border-token-border-light relative h-9 rounded-lg font-medium',
+            removeFocusOutlines,
+          )}
+          aria-label={localize('com_ui_share_var', {
+            0: agentName != null && agentName !== '' ? `"${agentName}"` : localize('com_ui_agent'),
+          })}
+          type="button"
+        >
+          <div className="flex items-center justify-center gap-2 text-blue-500">
+            <Share2Icon className="icon-md h-4 w-4" />
+            {totalCurrentShares > 0 && (
+              <span className="rounded-full bg-blue-100 px-1.5 py-0.5 text-xs font-medium text-blue-800 dark:bg-blue-900 dark:text-blue-300">
+                {totalCurrentShares}
+              </span>
+            )}
+          </div>
+        </button>
+      </OGDialogTrigger>
+
+      <OGDialogContent className="max-h-[90vh] w-11/12 overflow-y-auto md:max-w-3xl">
+        <OGDialogTitle>
+          <div className="flex items-center gap-2">
+            <Users className="h-5 w-5" />
+            {localize('com_ui_share_var', {
+              0:
+                agentName != null && agentName !== '' ? `"${agentName}"` : localize('com_ui_agent'),
+            })}
+          </div>
+        </OGDialogTitle>
+
+        <div className="space-y-6 p-2">
+          <PeoplePicker
+            onSelectionChange={setNewShares}
+            placeholder={localize('com_ui_search_people_placeholder')}
+          />
+
+          <div className="space-y-3">
+            <div className="flex items-center justify-between">
+              <div className="flex items-center gap-2">
+                <Shield className="h-4 w-4 text-text-secondary" />
+                <label className="text-sm font-medium text-text-primary">
+                  {localize('com_ui_permission_level')}
+                </label>
+              </div>
+            </div>
+            <AccessRolesPicker
+              resourceType={resourceType}
+              selectedRoleId={defaultPermissionId}
+              onRoleChange={setDefaultPermissionId}
+            />
+          </div>
+          <PublicSharingToggle
+            isPublic={isPublic}
+            publicRole={publicRole}
+            onPublicToggle={setIsPublic}
+            onPublicRoleChange={setPublicRole}
+            resourceType={resourceType}
+          />
+          <div className="flex justify-between border-t pt-4">
+            <div className="flex gap-2">
+              <ManagePermissionsDialog
+                agentDbId={agentDbId}
+                agentName={agentName}
+                resourceType={resourceType}
+              />
+              {agentId && (
+                <Button
+                  variant="outline"
+                  size="sm"
+                  onClick={() => {
+                    if (isCopying) return;
+                    copyAgentUrl(setIsCopying);
+                    showToast({
+                      message: localize('com_ui_agent_url_copied'),
+                      status: 'success',
+                    });
+                  }}
+                  disabled={isCopying}
+                  className={cn('shrink-0', isCopying ? 'cursor-default' : '')}
+                  aria-label={localize('com_ui_copy_url_to_clipboard')}
+                  title={
+                    isCopying
+                      ? localize('com_ui_agent_url_copied')
+                      : localize('com_ui_copy_url_to_clipboard')
+                  }
+                >
+                  {isCopying ? <CopyCheck className="h-4 w-4" /> : <Link className="h-4 w-4" />}
+                </Button>
+              )}
+            </div>
+            <div className="flex gap-3">
+              <OGDialogClose asChild>
+                <Button variant="outline" onClick={handleCancel}>
+                  {localize('com_ui_cancel')}
+                </Button>
+              </OGDialogClose>
+              <Button
+                onClick={handleGrantAccess}
+                disabled={updatePermissionsMutation.isLoading || !submitButtonActive}
+                className="min-w-[120px]"
+              >
+                {updatePermissionsMutation.isLoading ? (
+                  <div className="flex items-center gap-2">
+                    <Loader className="h-4 w-4 animate-spin" />
+                    {localize('com_ui_granting')}
+                  </div>
+                ) : (
+                  localize('com_ui_grant_access')
+                )}
+              </Button>
+            </div>
+          </div>
+        </div>
+      </OGDialogContent>
+    </OGDialog>
+  );
+}

client/src/components/SidePanel/Agents/Sharing/ManagePermissionsDialog.tsx

@@ -0,0 +1,348 @@
+import React, { useState, useEffect } from 'react';
+import { ACCESS_ROLE_IDS, TPrincipal } from 'librechat-data-provider';
+import { Settings, Users, Loader, UserCheck, Trash2, Shield } from 'lucide-react';
+import {
+  useGetAccessRolesQuery,
+  useGetResourcePermissionsQuery,
+  useUpdateResourcePermissionsMutation,
+} from 'librechat-data-provider/react-query';
+import {
+  Button,
+  OGDialog,
+  OGDialogTitle,
+  OGDialogClose,
+  OGDialogContent,
+  OGDialogTrigger,
+  useToastContext,
+} from '@librechat/client';
+import SelectedPrincipalsList from './PeoplePicker/SelectedPrincipalsList';
+import PublicSharingToggle from './PublicSharingToggle';
+import { cn, removeFocusOutlines } from '~/utils';
+import { useLocalize } from '~/hooks';
+
+export default function ManagePermissionsDialog({
+  agentDbId,
+  agentName,
+  resourceType = 'agent',
+  onUpdatePermissions,
+}: {
+  agentDbId: string;
+  agentName?: string;
+  resourceType?: string;
+  onUpdatePermissions?: (shares: TPrincipal[], isPublic: boolean, publicRole: string) => void;
+}) {
+  const localize = useLocalize();
+  const { showToast } = useToastContext();
+
+  const {
+    data: permissionsData,
+    isLoading: isLoadingPermissions,
+    error: permissionsError,
+  } = useGetResourcePermissionsQuery(resourceType, agentDbId, {
+    enabled: !!agentDbId,
+  });
+  const {
+    data: accessRoles,
+    // isLoading,
+  } = useGetAccessRolesQuery(resourceType);
+
+  const updatePermissionsMutation = useUpdateResourcePermissionsMutation();
+
+  const [managedShares, setManagedShares] = useState<TPrincipal[]>([]);
+  const [managedIsPublic, setManagedIsPublic] = useState(false);
+  const [managedPublicRole, setManagedPublicRole] = useState<string>(ACCESS_ROLE_IDS.AGENT_VIEWER);
+  const [isModalOpen, setIsModalOpen] = useState(false);
+  const [hasChanges, setHasChanges] = useState(false);
+
+  const currentShares: TPrincipal[] = permissionsData?.principals || [];
+
+  const isPublic = permissionsData?.public || false;
+  const publicRole = permissionsData?.publicAccessRoleId || ACCESS_ROLE_IDS.AGENT_VIEWER;
+
+  useEffect(() => {
+    if (permissionsData) {
+      setManagedShares(currentShares);
+      setManagedIsPublic(isPublic);
+      setManagedPublicRole(publicRole);
+      setHasChanges(false);
+    }
+  }, [permissionsData, isModalOpen]);
+
+  if (!agentDbId) {
+    return null;
+  }
+
+  if (permissionsError) {
+    return <div className="text-sm text-red-600">{localize('com_ui_permissions_failed_load')}</div>;
+  }
+
+  const handleRemoveShare = (idOnTheSource: string) => {
+    setManagedShares(managedShares.filter((s) => s.idOnTheSource !== idOnTheSource));
+    setHasChanges(true);
+  };
+
+  const handleRoleChange = (idOnTheSource: string, newRole: string) => {
+    setManagedShares(
+      managedShares.map((s) =>
+        s.idOnTheSource === idOnTheSource ? { ...s, accessRoleId: newRole } : s,
+      ),
+    );
+    setHasChanges(true);
+  };
+
+  const handleSaveChanges = async () => {
+    try {
+      const originalSharesMap = new Map(
+        currentShares.map((share) => [`${share.type}-${share.idOnTheSource}`, share]),
+      );
+      const managedSharesMap = new Map(
+        managedShares.map((share) => [`${share.type}-${share.idOnTheSource}`, share]),
+      );
+
+      const updated = managedShares.filter((share) => {
+        const key = `${share.type}-${share.idOnTheSource}`;
+        const original = originalSharesMap.get(key);
+        return !original || original.accessRoleId !== share.accessRoleId;
+      });
+
+      const removed = currentShares.filter((share) => {
+        const key = `${share.type}-${share.idOnTheSource}`;
+        return !managedSharesMap.has(key);
+      });
+
+      await updatePermissionsMutation.mutateAsync({
+        resourceType,
+        resourceId: agentDbId,
+        data: {
+          updated,
+          removed,
+          public: managedIsPublic,
+          publicAccessRoleId: managedIsPublic ? managedPublicRole : undefined,
+        },
+      });
+
+      if (onUpdatePermissions) {
+        onUpdatePermissions(managedShares, managedIsPublic, managedPublicRole);
+      }
+
+      showToast({
+        message: localize('com_ui_permissions_updated_success'),
+        status: 'success',
+      });
+
+      setIsModalOpen(false);
+    } catch (error) {
+      console.error('Error updating permissions:', error);
+      showToast({
+        message: localize('com_ui_permissions_failed_update'),
+        status: 'error',
+      });
+    }
+  };
+
+  const handleCancel = () => {
+    setManagedShares(currentShares);
+    setManagedIsPublic(isPublic);
+    setManagedPublicRole(publicRole);
+    setIsModalOpen(false);
+  };
+
+  const handleRevokeAll = () => {
+    setManagedShares([]);
+    setManagedIsPublic(false);
+    setHasChanges(true);
+  };
+  const handlePublicToggle = (isPublic: boolean) => {
+    setManagedIsPublic(isPublic);
+    setHasChanges(true);
+    if (!isPublic) {
+      setManagedPublicRole(ACCESS_ROLE_IDS.AGENT_VIEWER);
+    }
+  };
+  const handlePublicRoleChange = (role: string) => {
+    setManagedPublicRole(role);
+    setHasChanges(true);
+  };
+  const totalShares = managedShares.length + (managedIsPublic ? 1 : 0);
+  const originalTotalShares = currentShares.length + (isPublic ? 1 : 0);
+
+  /** Check if there's at least one owner (user, group, or public with owner role) */
+  const hasAtLeastOneOwner =
+    managedShares.some((share) => share.accessRoleId === ACCESS_ROLE_IDS.AGENT_OWNER) ||
+    (managedIsPublic && managedPublicRole === ACCESS_ROLE_IDS.AGENT_OWNER);
+
+  let peopleLabel = localize('com_ui_people');
+  if (managedShares.length === 1) {
+    peopleLabel = localize('com_ui_person');
+  }
+
+  let buttonAriaLabel = localize('com_ui_manage_permissions_for') + ' agent';
+  if (agentName != null && agentName !== '') {
+    buttonAriaLabel = localize('com_ui_manage_permissions_for') + ` "${agentName}"`;
+  }
+
+  let dialogTitle = localize('com_ui_manage_permissions_for') + ' Agent';
+  if (agentName != null && agentName !== '') {
+    dialogTitle = localize('com_ui_manage_permissions_for') + ` "${agentName}"`;
+  }
+
+  let publicSuffix = '';
+  if (managedIsPublic) {
+    publicSuffix = localize('com_ui_and_public');
+  }
+
+  return (
+    <OGDialog open={isModalOpen} onOpenChange={setIsModalOpen}>
+      <OGDialogTrigger asChild>
+        <button
+          className={cn(
+            'btn btn-neutral border-token-border-light relative h-9 rounded-lg font-medium',
+            removeFocusOutlines,
+          )}
+          aria-label={buttonAriaLabel}
+          type="button"
+        >
+          <div className="flex items-center justify-center gap-2 text-blue-500">
+            <Settings className="icon-md h-4 w-4" />
+            <span className="hidden sm:inline">{localize('com_ui_manage')}</span>
+            {originalTotalShares > 0 && `(${originalTotalShares})`}
+          </div>
+        </button>
+      </OGDialogTrigger>
+
+      <OGDialogContent className="max-h-[90vh] w-11/12 overflow-y-auto md:max-w-3xl">
+        <OGDialogTitle>
+          <div className="flex items-center gap-2">
+            <Shield className="h-5 w-5 text-blue-500" />
+            {dialogTitle}
+          </div>
+        </OGDialogTitle>
+
+        <div className="space-y-6 p-2">
+          <div className="rounded-lg bg-surface-tertiary p-4">
+            <div className="flex items-center justify-between">
+              <div>
+                <h3 className="text-sm font-medium text-text-primary">
+                  {localize('com_ui_current_access')}
+                </h3>
+                <p className="text-xs text-text-secondary">
+                  {(() => {
+                    if (totalShares === 0) {
+                      return localize('com_ui_no_users_groups_access');
+                    }
+                    return localize('com_ui_shared_with_count', {
+                      0: managedShares.length,
+                      1: peopleLabel,
+                      2: publicSuffix,
+                    });
+                  })()}
+                </p>
+              </div>
+              {(managedShares.length > 0 || managedIsPublic) && (
+                <Button
+                  variant="outline"
+                  size="sm"
+                  onClick={handleRevokeAll}
+                  className="text-red-600 hover:text-red-700"
+                >
+                  <Trash2 className="mr-2 h-4 w-4" />
+                  {localize('com_ui_revoke_all')}
+                </Button>
+              )}
+            </div>
+          </div>
+
+          {(() => {
+            if (isLoadingPermissions) {
+              return (
+                <div className="flex items-center justify-center p-8">
+                  <Loader className="h-6 w-6 animate-spin" />
+                  <span className="ml-2 text-sm text-text-secondary">
+                    {localize('com_ui_loading_permissions')}
+                  </span>
+                </div>
+              );
+            }
+
+            if (managedShares.length > 0) {
+              return (
+                <div>
+                  <h3 className="mb-3 flex items-center gap-2 text-sm font-medium text-text-primary">
+                    <UserCheck className="h-4 w-4" />
+                    {localize('com_ui_user_group_permissions')} ({managedShares.length})
+                  </h3>
+                  <SelectedPrincipalsList
+                    principles={managedShares}
+                    onRemoveHandler={handleRemoveShare}
+                    availableRoles={accessRoles || []}
+                    onRoleChange={(id, newRole) => handleRoleChange(id, newRole)}
+                  />
+                </div>
+              );
+            }
+
+            return (
+              <div className="rounded-lg border-2 border-dashed border-border-light p-8 text-center">
+                <Users className="mx-auto h-8 w-8 text-text-secondary" />
+                <p className="mt-2 text-sm text-text-secondary">
+                  {localize('com_ui_no_individual_access')}
+                </p>
+              </div>
+            );
+          })()}
+
+          <div>
+            <h3 className="mb-3 text-sm font-medium text-text-primary">
+              {localize('com_ui_public_access')}
+            </h3>
+            <PublicSharingToggle
+              isPublic={managedIsPublic}
+              publicRole={managedPublicRole}
+              onPublicToggle={handlePublicToggle}
+              onPublicRoleChange={handlePublicRoleChange}
+            />
+          </div>
+
+          <div className="flex justify-end gap-3 border-t pt-4">
+            <OGDialogClose asChild>
+              <Button variant="outline" onClick={handleCancel}>
+                {localize('com_ui_cancel')}
+              </Button>
+            </OGDialogClose>
+            <Button
+              onClick={handleSaveChanges}
+              disabled={
+                updatePermissionsMutation.isLoading ||
+                !hasChanges ||
+                isLoadingPermissions ||
+                !hasAtLeastOneOwner
+              }
+              className="min-w-[120px]"
+            >
+              {updatePermissionsMutation.isLoading ? (
+                <div className="flex items-center gap-2">
+                  <Loader className="h-4 w-4 animate-spin" />
+                  {localize('com_ui_saving')}
+                </div>
+              ) : (
+                localize('com_ui_save_changes')
+              )}
+            </Button>
+          </div>
+
+          {hasChanges && (
+            <div className="text-xs text-orange-600 dark:text-orange-400">
+              * {localize('com_ui_unsaved_changes')}
+            </div>
+          )}
+
+          {!hasAtLeastOneOwner && hasChanges && (
+            <div className="text-xs text-red-600 dark:text-red-400">
+              * {localize('com_ui_at_least_one_owner_required')}
+            </div>
+          )}
+        </div>
+      </OGDialogContent>
+    </OGDialog>
+  );
+}

client/src/components/SidePanel/Agents/Sharing/PeoplePicker/PeoplePicker.tsx

@@ -0,0 +1,100 @@
+import React, { useState, useMemo } from 'react';
+import type { TPrincipal, PrincipalSearchParams } from 'librechat-data-provider';
+import { useSearchPrincipalsQuery } from 'librechat-data-provider/react-query';
+import PeoplePickerSearchItem from './PeoplePickerSearchItem';
+import SelectedPrincipalsList from './SelectedPrincipalsList';
+import { SearchPicker } from '~/components/ui/SearchPicker';
+import { useLocalize } from '~/hooks';
+
+interface PeoplePickerProps {
+  onSelectionChange: (principals: TPrincipal[]) => void;
+  placeholder?: string;
+  className?: string;
+}
+
+export default function PeoplePicker({
+  onSelectionChange,
+  placeholder,
+  className = '',
+}: PeoplePickerProps) {
+  const localize = useLocalize();
+  const [searchQuery, setSearchQuery] = useState('');
+  const [selectedShares, setSelectedShares] = useState<TPrincipal[]>([]);
+
+  const searchParams: PrincipalSearchParams = useMemo(
+    () => ({
+      q: searchQuery,
+      limit: 30,
+    }),
+    [searchQuery],
+  );
+
+  const {
+    data: searchResponse,
+    isLoading: queryIsLoading,
+    error,
+  } = useSearchPrincipalsQuery(searchParams, {
+    enabled: searchQuery.length >= 2,
+  });
+
+  const isLoading = searchQuery.length >= 2 && queryIsLoading;
+
+  const selectableResults = useMemo(() => {
+    const results = searchResponse?.results || [];
+
+    return results.filter(
+      (result) => !selectedShares.some((share) => share.idOnTheSource === result.idOnTheSource),
+    );
+  }, [searchResponse?.results, selectedShares]);
+
+  if (error) {
+    console.error('Principal search error:', error);
+  }
+
+  return (
+    <div className={`space-y-3 ${className}`}>
+      <div className="relative">
+        <SearchPicker<TPrincipal & { key: string; value: string }>
+          options={selectableResults.map((s) => {
+            const key = s.idOnTheSource || 'unknown' + 'picker_key';
+            const value = s.idOnTheSource || 'Unknown';
+            return {
+              ...s,
+              id: s.id ?? undefined,
+              key,
+              value,
+            };
+          })}
+          renderOptions={(o) => <PeoplePickerSearchItem principal={o} />}
+          placeholder={placeholder || localize('com_ui_search_default_placeholder')}
+          query={searchQuery}
+          onQueryChange={(query: string) => {
+            setSearchQuery(query);
+          }}
+          onPick={(principal) => {
+            console.log('Selected Principal:', principal);
+            setSelectedShares((prev) => {
+              const newArray = [...prev, principal];
+              onSelectionChange([...newArray]);
+              return newArray;
+            });
+            setSearchQuery('');
+          }}
+          label={localize('com_ui_search_users_groups')}
+          isLoading={isLoading}
+        />
+      </div>
+
+      <SelectedPrincipalsList
+        principles={selectedShares}
+        onRemoveHandler={(idOnTheSource: string) => {
+          setSelectedShares((prev) => {
+            const newArray = prev.filter((share) => share.idOnTheSource !== idOnTheSource);
+            onSelectionChange(newArray);
+            return newArray;
+          });
+        }}
+      />
+    </div>
+  );
+}

client/src/components/SidePanel/Agents/Sharing/PeoplePicker/PeoplePickerSearchItem.tsx

@@ -0,0 +1,57 @@
+import React, { forwardRef } from 'react';
+import type { TPrincipal } from 'librechat-data-provider';
+import { cn } from '~/utils';
+import { useLocalize } from '~/hooks';
+import PrincipalAvatar from '../PrincipalAvatar';
+
+interface PeoplePickerSearchItemProps extends React.HTMLAttributes<HTMLDivElement> {
+  principal: TPrincipal;
+}
+
+const PeoplePickerSearchItem = forwardRef<HTMLDivElement, PeoplePickerSearchItemProps>(
+  function PeoplePickerSearchItem(
+    { principal, className, style, onClick, ...props },
+    forwardedRef,
+  ) {
+    const localize = useLocalize();
+    const { name, email, type } = principal;
+
+    // Display name with fallback
+    const displayName = name || localize('com_ui_unknown');
+    const subtitle = email || `${type} (${principal.source || 'local'})`;
+
+    return (
+      <div
+        {...props}
+        ref={forwardedRef}
+        className={cn('flex items-center gap-3 p-2', className)}
+        style={style}
+        onClick={(event) => {
+          onClick?.(event);
+        }}
+      >
+        <PrincipalAvatar principal={principal} size="md" />
+
+        <div className="min-w-0 flex-1">
+          <div className="truncate text-sm font-medium text-text-primary">{displayName}</div>
+          <div className="truncate text-xs text-text-secondary">{subtitle}</div>
+        </div>
+
+        <div className="flex-shrink-0">
+          <span
+            className={cn(
+              'inline-flex items-center rounded-full px-2 py-1 text-xs font-medium',
+              type === 'user'
+                ? 'bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-300'
+                : 'bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-300',
+            )}
+          >
+            {type === 'user' ? localize('com_ui_user') : localize('com_ui_group')}
+          </span>
+        </div>
+      </div>
+    );
+  },
+);
+
+export default PeoplePickerSearchItem;

client/src/components/SidePanel/Agents/Sharing/PeoplePicker/SelectedPrincipalsList.tsx

@@ -0,0 +1,149 @@
+import React, { useState, useId } from 'react';
+import * as Menu from '@ariakit/react/menu';
+import { Button, DropdownPopup } from '@librechat/client';
+import { Users, X, ExternalLink, ChevronDown } from 'lucide-react';
+import type { TPrincipal, TAccessRole } from 'librechat-data-provider';
+import PrincipalAvatar from '../PrincipalAvatar';
+import { useLocalize } from '~/hooks';
+
+interface SelectedPrincipalsListProps {
+  principles: TPrincipal[];
+  onRemoveHandler: (idOnTheSource: string) => void;
+  onRoleChange?: (idOnTheSource: string, newRoleId: string) => void;
+  availableRoles?: Omit<TAccessRole, 'resourceType'>[];
+  className?: string;
+}
+
+export default function SelectedPrincipalsList({
+  principles,
+  onRemoveHandler,
+  className = '',
+  onRoleChange,
+  availableRoles,
+}: SelectedPrincipalsListProps) {
+  const localize = useLocalize();
+
+  const getPrincipalDisplayInfo = (principal: TPrincipal) => {
+    const displayName = principal.name || localize('com_ui_unknown');
+    const subtitle = principal.email || `${principal.type} (${principal.source || 'local'})`;
+
+    return { displayName, subtitle };
+  };
+
+  if (principles.length === 0) {
+    return (
+      <div className={`space-y-3 ${className}`}>
+        <div className="rounded-lg border border-dashed border-border py-8 text-center text-muted-foreground">
+          <Users className="mx-auto mb-2 h-8 w-8 opacity-50" />
+          <p className="mt-1 text-xs">{localize('com_ui_search_above_to_add')}</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className={`space-y-3 ${className}`}>
+      <div className="space-y-2">
+        {principles.map((share) => {
+          const { displayName, subtitle } = getPrincipalDisplayInfo(share);
+          return (
+            <div
+              key={share.idOnTheSource + '-principalList'}
+              className="bg-surface flex items-center justify-between rounded-lg border border-border p-3"
+            >
+              <div className="flex min-w-0 flex-1 items-center gap-3">
+                <PrincipalAvatar principal={share} size="md" />
+
+                <div className="min-w-0 flex-1">
+                  <div className="truncate text-sm font-medium">{displayName}</div>
+                  <div className="flex items-center gap-1 text-xs text-muted-foreground">
+                    <span>{subtitle}</span>
+                    {share.source === 'entra' && (
+                      <>
+                        <ExternalLink className="h-3 w-3" />
+                        <span>{localize('com_ui_azure_ad')}</span>
+                      </>
+                    )}
+                  </div>
+                </div>
+              </div>
+
+              <div className="flex flex-shrink-0 items-center gap-2">
+                {!!share.accessRoleId && !!onRoleChange && (
+                  <RoleSelector
+                    currentRole={share.accessRoleId}
+                    onRoleChange={(newRole) => {
+                      onRoleChange?.(share.idOnTheSource!, newRole);
+                    }}
+                    availableRoles={availableRoles ?? []}
+                  />
+                )}
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  onClick={() => onRemoveHandler(share.idOnTheSource!)}
+                  className="h-8 w-8 p-0 hover:bg-destructive/10 hover:text-destructive"
+                  aria-label={localize('com_ui_remove_user', { 0: displayName })}
+                >
+                  <X className="h-4 w-4" />
+                </Button>
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+interface RoleSelectorProps {
+  currentRole: string;
+  onRoleChange: (newRole: string) => void;
+  availableRoles: Omit<TAccessRole, 'resourceType'>[];
+}
+
+function RoleSelector({ currentRole, onRoleChange, availableRoles }: RoleSelectorProps) {
+  const menuId = useId();
+  const [isMenuOpen, setIsMenuOpen] = useState(false);
+  const localize = useLocalize();
+
+  const getLocalizedRoleName = (roleId: string) => {
+    switch (roleId) {
+      case 'agent_viewer':
+        return localize('com_ui_role_viewer');
+      case 'agent_editor':
+        return localize('com_ui_role_editor');
+      case 'agent_manager':
+        return localize('com_ui_role_manager');
+      case 'agent_owner':
+        return localize('com_ui_role_owner');
+      default:
+        return localize('com_ui_unknown');
+    }
+  };
+
+  return (
+    <DropdownPopup
+      portal={true}
+      mountByState={true}
+      unmountOnHide={true}
+      preserveTabOrder={true}
+      isOpen={isMenuOpen}
+      setIsOpen={setIsMenuOpen}
+      trigger={
+        <Menu.MenuButton className="flex h-8 items-center gap-2 rounded-md border border-border-medium bg-surface-secondary px-2 py-1 text-sm font-medium transition-colors duration-200 hover:bg-surface-tertiary">
+          <span className="hidden sm:inline">{getLocalizedRoleName(currentRole)}</span>
+          <ChevronDown className="h-3 w-3" />
+        </Menu.MenuButton>
+      }
+      items={availableRoles?.map((role) => ({
+        id: role.accessRoleId,
+        label: getLocalizedRoleName(role.accessRoleId),
+
+        onClick: () => onRoleChange(role.accessRoleId),
+      }))}
+      menuId={menuId}
+      className="z-50 [pointer-events:auto]"
+    />
+  );
+}

client/src/components/SidePanel/Agents/Sharing/PrincipalAvatar.tsx

@@ -0,0 +1,101 @@
+import React from 'react';
+import { Users, User } from 'lucide-react';
+import type { TPrincipal } from 'librechat-data-provider';
+import { cn } from '~/utils';
+
+interface PrincipalAvatarProps {
+  principal: TPrincipal;
+  size?: 'sm' | 'md' | 'lg';
+  className?: string;
+}
+
+export default function PrincipalAvatar({
+  principal,
+  size = 'md',
+  className,
+}: PrincipalAvatarProps) {
+  const { avatar, type, name } = principal;
+  const displayName = name || 'Unknown';
+
+  // Size variants
+  const sizeClasses = {
+    sm: 'h-6 w-6',
+    md: 'h-8 w-8',
+    lg: 'h-10 w-10',
+  };
+
+  const iconSizeClasses = {
+    sm: 'h-3 w-3',
+    md: 'h-4 w-4',
+    lg: 'h-5 w-5',
+  };
+
+  const avatarSizeClass = sizeClasses[size];
+  const iconSizeClass = iconSizeClasses[size];
+
+  // Avatar or icon logic
+  if (avatar) {
+    return (
+      <div className={cn('flex-shrink-0', className)}>
+        <img
+          src={avatar}
+          alt={`${displayName} avatar`}
+          className={cn(avatarSizeClass, 'rounded-full object-cover')}
+          onError={(e) => {
+            // Fallback to icon if image fails to load
+            const target = e.target as HTMLImageElement;
+            target.style.display = 'none';
+            target.nextElementSibling?.classList.remove('hidden');
+          }}
+        />
+        {/* Hidden fallback icon that shows if image fails */}
+        <div className={cn('hidden', avatarSizeClass)}>
+          {type === 'user' ? (
+            <div
+              className={cn(
+                avatarSizeClass,
+                'flex items-center justify-center rounded-full bg-blue-100 dark:bg-blue-900',
+              )}
+            >
+              <User className={cn(iconSizeClass, 'text-blue-600 dark:text-blue-400')} />
+            </div>
+          ) : (
+            <div
+              className={cn(
+                avatarSizeClass,
+                'flex items-center justify-center rounded-full bg-green-100 dark:bg-green-900',
+              )}
+            >
+              <Users className={cn(iconSizeClass, 'text-green-600 dark:text-green-400')} />
+            </div>
+          )}
+        </div>
+      </div>
+    );
+  }
+
+  // Fallback icon based on type
+  return (
+    <div className={cn('flex-shrink-0', className)}>
+      {type === 'user' ? (
+        <div
+          className={cn(
+            avatarSizeClass,
+            'flex items-center justify-center rounded-full bg-blue-100 dark:bg-blue-900',
+          )}
+        >
+          <User className={cn(iconSizeClass, 'text-blue-600 dark:text-blue-400')} />
+        </div>
+      ) : (
+        <div
+          className={cn(
+            avatarSizeClass,
+            'flex items-center justify-center rounded-full bg-green-100 dark:bg-green-900',
+          )}
+        >
+          <Users className={cn(iconSizeClass, 'text-green-600 dark:text-green-400')} />
+        </div>
+      )}
+    </div>
+  );
+}

client/src/components/SidePanel/Agents/Sharing/PublicSharingToggle.tsx

@@ -0,0 +1,59 @@
+import React from 'react';
+import { Globe } from 'lucide-react';
+import { Switch } from '@librechat/client';
+import AccessRolesPicker from './AccessRolesPicker';
+import { useLocalize } from '~/hooks';
+
+interface PublicSharingToggleProps {
+  isPublic: boolean;
+  publicRole: string;
+  onPublicToggle: (isPublic: boolean) => void;
+  onPublicRoleChange: (role: string) => void;
+  className?: string;
+  resourceType?: string;
+}
+
+export default function PublicSharingToggle({
+  isPublic,
+  publicRole,
+  onPublicToggle,
+  onPublicRoleChange,
+  className = '',
+  resourceType = 'agent',
+}: PublicSharingToggleProps) {
+  const localize = useLocalize();
+
+  return (
+    <div className={`space-y-3 border-t pt-4 ${className}`}>
+      <div className="flex items-center justify-between">
+        <div>
+          <h3 className="flex items-center gap-2 text-sm font-medium">
+            <Globe className="h-4 w-4" />
+            {localize('com_ui_share_with_everyone')}
+          </h3>
+          <p className="mt-1 text-xs text-muted-foreground">
+            {localize('com_ui_make_agent_available_all_users')}
+          </p>
+        </div>
+        <Switch
+          checked={isPublic}
+          onCheckedChange={onPublicToggle}
+          aria-label={localize('com_ui_share_with_everyone')}
+        />
+      </div>
+
+      {isPublic && (
+        <div>
+          <label className="mb-2 block text-sm font-medium">
+            {localize('com_ui_public_access_level')}
+          </label>
+          <AccessRolesPicker
+            resourceType={resourceType}
+            selectedRoleId={publicRole}
+            onRoleChange={onPublicRoleChange}
+          />
+        </div>
+      )}
+    </div>
+  );
+}

client/src/components/SidePanel/Agents/SmartLoader.tsx

@@ -0,0 +1,97 @@
+import React, { useState, useEffect } from 'react';
+
+import { cn } from '~/utils';
+
+interface SmartLoaderProps {
+  /** Whether the content is currently loading */
+  isLoading: boolean;
+  /** Whether there is existing data to show */
+  hasData: boolean;
+  /** Delay before showing loading state (in ms) - prevents flashing for quick loads */
+  delay?: number;
+  /** Loading skeleton/spinner component */
+  loadingComponent: React.ReactNode;
+  /** Content to show when loaded */
+  children: React.ReactNode;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+/**
+ * SmartLoader - Intelligent loading wrapper that prevents flashing
+ *
+ * Only shows loading states when:
+ * 1. Actually loading AND no existing data
+ * 2. Loading has lasted longer than the delay threshold
+ *
+ * This prevents brief loading flashes for cached/fast responses
+ */
+export const SmartLoader: React.FC<SmartLoaderProps> = ({
+  isLoading,
+  hasData,
+  delay = 150,
+  loadingComponent,
+  children,
+  className = '',
+}) => {
+  const [shouldShowLoading, setShouldShowLoading] = useState(false);
+
+  useEffect(() => {
+    let timeoutId: NodeJS.Timeout;
+
+    if (isLoading && !hasData) {
+      // Only show loading after delay to prevent flashing
+      timeoutId = setTimeout(() => {
+        setShouldShowLoading(true);
+      }, delay);
+    } else {
+      // Immediately hide loading when done
+      setShouldShowLoading(false);
+    }
+
+    return () => {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    };
+  }, [isLoading, hasData, delay]);
+
+  // Show loading state only if we've determined it should be shown
+  if (shouldShowLoading) {
+    return <div className={className}>{loadingComponent}</div>;
+  }
+
+  // Show content (including when loading but we have existing data)
+  return <div className={className}>{children}</div>;
+};
+
+/**
+ * Hook to determine if we have meaningful data to show
+ * Helps prevent loading states when we already have cached content
+ */
+export const useHasData = (data: unknown): boolean => {
+  if (!data) return false;
+
+  // Type guard for object data
+  if (typeof data === 'object' && data !== null) {
+    // Check for agent list data
+    if ('agents' in data) {
+      const agents = (data as any).agents;
+      return Array.isArray(agents) && agents.length > 0;
+    }
+
+    // Check for single agent data
+    if ('id' in data || 'name' in data) {
+      return true;
+    }
+  }
+
+  // Check for categories data (array)
+  if (Array.isArray(data)) {
+    return data.length > 0;
+  }
+
+  return false;
+};
+
+export default SmartLoader;

client/src/components/SidePanel/Agents/__tests__/Accessibility.spec.tsx

@@ -0,0 +1,422 @@
+import React from 'react';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import CategoryTabs from '../CategoryTabs';
+import AgentGrid from '../AgentGrid';
+import AgentCard from '../AgentCard';
+import SearchBar from '../SearchBar';
+import ErrorDisplay from '../ErrorDisplay';
+
+// Mock matchMedia
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: jest.fn().mockImplementation(() => ({
+    matches: false,
+    media: '',
+    onchange: null,
+    addListener: jest.fn(),
+    removeListener: jest.fn(),
+    addEventListener: jest.fn(),
+    removeEventListener: jest.fn(),
+    dispatchEvent: jest.fn(),
+  })),
+});
+
+// Mock hooks
+jest.mock(
+  '~/hooks/useLocalize',
+  () => () =>
+    jest.fn((key: string, options?: any) => {
+      const translations: Record<string, string> = {
+        com_agents_category_tabs_label: 'Agent Categories',
+        com_agents_category_tab_label: `${options?.category} category, ${options?.position} of ${options?.total}`,
+        com_agents_search_instructions: 'Type to search agents by name or description',
+        com_agents_search_aria: 'Search agents',
+        com_agents_search_placeholder: 'Search agents...',
+        com_agents_clear_search: 'Clear search',
+        com_agents_agent_card_label: `${options?.name} agent. ${options?.description}`,
+        com_agents_no_description: 'No description available',
+        com_agents_grid_announcement: `Showing ${options?.count} agents in ${options?.category} category`,
+        com_agents_load_more_label: `Load more agents from ${options?.category} category`,
+        com_agents_error_retry: 'Try Again',
+        com_agents_loading: 'Loading...',
+        com_agents_empty_state_heading: 'No agents found',
+        com_agents_search_empty_heading: 'No search results',
+      };
+      return translations[key] || key;
+    }),
+);
+
+jest.mock('~/hooks/Agents', () => ({
+  useDynamicAgentQuery: jest.fn(),
+}));
+
+const { useDynamicAgentQuery } = require('~/hooks/Agents');
+
+// Create wrapper with QueryClient
+const createWrapper = () => {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+
+  return ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+};
+
+describe('Accessibility Improvements', () => {
+  beforeEach(() => {
+    useDynamicAgentQuery.mockClear();
+  });
+
+  describe('CategoryTabs Accessibility', () => {
+    const categories = [
+      { name: 'promoted', count: 5 },
+      { name: 'all', count: 20 },
+      { name: 'productivity', count: 8 },
+    ];
+
+    it('implements proper tablist role and ARIA attributes', () => {
+      render(
+        <CategoryTabs
+          categories={categories}
+          activeTab="promoted"
+          isLoading={false}
+          onChange={jest.fn()}
+        />,
+      );
+
+      // Check tablist role
+      const tablist = screen.getByRole('tablist');
+      expect(tablist).toBeInTheDocument();
+      expect(tablist).toHaveAttribute('aria-label', 'Agent Categories');
+      expect(tablist).toHaveAttribute('aria-orientation', 'horizontal');
+
+      // Check individual tabs
+      const tabs = screen.getAllByRole('tab');
+      expect(tabs).toHaveLength(3);
+
+      tabs.forEach((tab, index) => {
+        expect(tab).toHaveAttribute('aria-selected');
+        expect(tab).toHaveAttribute('aria-controls');
+        expect(tab).toHaveAttribute('id');
+      });
+    });
+
+    it('supports keyboard navigation', () => {
+      const onChange = jest.fn();
+      render(
+        <CategoryTabs
+          categories={categories}
+          activeTab="promoted"
+          isLoading={false}
+          onChange={onChange}
+        />,
+      );
+
+      const promotedTab = screen.getByRole('tab', { name: /promoted category/ });
+
+      // Test arrow key navigation
+      fireEvent.keyDown(promotedTab, { key: 'ArrowRight' });
+      expect(onChange).toHaveBeenCalledWith('all');
+
+      fireEvent.keyDown(promotedTab, { key: 'ArrowLeft' });
+      expect(onChange).toHaveBeenCalledWith('productivity');
+
+      fireEvent.keyDown(promotedTab, { key: 'Home' });
+      expect(onChange).toHaveBeenCalledWith('promoted');
+
+      fireEvent.keyDown(promotedTab, { key: 'End' });
+      expect(onChange).toHaveBeenCalledWith('productivity');
+    });
+
+    it('manages focus correctly', () => {
+      const onChange = jest.fn();
+      render(
+        <CategoryTabs
+          categories={categories}
+          activeTab="promoted"
+          isLoading={false}
+          onChange={onChange}
+        />,
+      );
+
+      const promotedTab = screen.getByRole('tab', { name: /promoted category/ });
+      const allTab = screen.getByRole('tab', { name: /all category/ });
+
+      // Active tab should be focusable
+      expect(promotedTab).toHaveAttribute('tabIndex', '0');
+      expect(allTab).toHaveAttribute('tabIndex', '-1');
+    });
+  });
+
+  describe('SearchBar Accessibility', () => {
+    it('provides proper search role and labels', () => {
+      render(<SearchBar value="" onSearch={jest.fn()} />);
+
+      // Check search landmark
+      const searchRegion = screen.getByRole('search');
+      expect(searchRegion).toBeInTheDocument();
+
+      // Check input accessibility
+      const searchInput = screen.getByRole('searchbox');
+      expect(searchInput).toHaveAttribute('id', 'agent-search');
+      expect(searchInput).toHaveAttribute('aria-label', 'Search agents');
+      expect(searchInput).toHaveAttribute(
+        'aria-describedby',
+        'search-instructions search-results-count',
+      );
+
+      // Check hidden label
+      expect(screen.getByText('Type to search agents by name or description')).toHaveClass(
+        'sr-only',
+      );
+    });
+
+    it('provides accessible clear button', () => {
+      render(<SearchBar value="test" onSearch={jest.fn()} />);
+
+      const clearButton = screen.getByRole('button', { name: 'Clear search' });
+      expect(clearButton).toBeInTheDocument();
+      expect(clearButton).toHaveAttribute('aria-label', 'Clear search');
+      expect(clearButton).toHaveAttribute('title', 'Clear search');
+    });
+
+    it('hides decorative icons from screen readers', () => {
+      render(<SearchBar value="" onSearch={jest.fn()} />);
+
+      // Search icon should be hidden
+      const iconContainer = document.querySelector('[aria-hidden="true"]');
+      expect(iconContainer).toBeInTheDocument();
+    });
+  });
+
+  describe('AgentCard Accessibility', () => {
+    const mockAgent = {
+      id: 'test-agent',
+      name: 'Test Agent',
+      description: 'A test agent for testing',
+      authorName: 'Test Author',
+    };
+
+    it('provides comprehensive ARIA labels', () => {
+      render(<AgentCard agent={mockAgent} onClick={jest.fn()} />);
+
+      const card = screen.getByRole('button');
+      expect(card).toHaveAttribute('aria-label', 'Test Agent agent. A test agent for testing');
+      expect(card).toHaveAttribute('aria-describedby', 'agent-test-agent-description');
+      expect(card).toHaveAttribute('role', 'button');
+    });
+
+    it('handles agents without descriptions', () => {
+      const agentWithoutDesc = { ...mockAgent, description: undefined };
+      render(<AgentCard agent={agentWithoutDesc} onClick={jest.fn()} />);
+
+      expect(screen.getByText('No description available')).toBeInTheDocument();
+    });
+
+    it('supports keyboard interaction', () => {
+      const onClick = jest.fn();
+      render(<AgentCard agent={mockAgent} onClick={onClick} />);
+
+      const card = screen.getByRole('button');
+
+      fireEvent.keyDown(card, { key: 'Enter' });
+      expect(onClick).toHaveBeenCalledTimes(1);
+
+      fireEvent.keyDown(card, { key: ' ' });
+      expect(onClick).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('AgentGrid Accessibility', () => {
+    beforeEach(() => {
+      useDynamicAgentQuery.mockReturnValue({
+        data: {
+          agents: [
+            { id: '1', name: 'Agent 1', description: 'First agent' },
+            { id: '2', name: 'Agent 2', description: 'Second agent' },
+          ],
+          pagination: { hasMore: false, total: 2, current: 1 },
+        },
+        isLoading: false,
+        isFetching: false,
+        error: null,
+        refetch: jest.fn(),
+      });
+    });
+
+    it('implements proper tabpanel structure', () => {
+      const Wrapper = createWrapper();
+      render(
+        <Wrapper>
+          <AgentGrid category="all" searchQuery="" onSelectAgent={jest.fn()} />
+        </Wrapper>,
+      );
+
+      // Check tabpanel role
+      const tabpanel = screen.getByRole('tabpanel');
+      expect(tabpanel).toHaveAttribute('id', 'category-panel-all');
+      expect(tabpanel).toHaveAttribute('aria-labelledby', 'category-tab-all');
+      expect(tabpanel).toHaveAttribute('aria-live', 'polite');
+    });
+
+    it('provides grid structure with proper roles', () => {
+      const Wrapper = createWrapper();
+      render(
+        <Wrapper>
+          <AgentGrid category="all" searchQuery="" onSelectAgent={jest.fn()} />
+        </Wrapper>,
+      );
+
+      // Check grid role
+      const grid = screen.getByRole('grid');
+      expect(grid).toBeInTheDocument();
+      expect(grid).toHaveAttribute('aria-label', 'Showing 2 agents in all category');
+
+      // Check gridcells
+      const gridcells = screen.getAllByRole('gridcell');
+      expect(gridcells).toHaveLength(2);
+    });
+
+    it('announces loading states to screen readers', () => {
+      useDynamicAgentQuery.mockReturnValue({
+        data: { agents: [{ id: '1', name: 'Agent 1' }] },
+        isLoading: false,
+        isFetching: true,
+        error: null,
+        refetch: jest.fn(),
+      });
+
+      const Wrapper = createWrapper();
+      render(
+        <Wrapper>
+          <AgentGrid category="all" searchQuery="" onSelectAgent={jest.fn()} />
+        </Wrapper>,
+      );
+
+      // Check for loading announcement
+      const loadingStatus = screen.getByRole('status', { name: 'Loading...' });
+      expect(loadingStatus).toBeInTheDocument();
+      expect(loadingStatus).toHaveAttribute('aria-live', 'polite');
+    });
+
+    it('provides accessible empty states', () => {
+      useDynamicAgentQuery.mockReturnValue({
+        data: { agents: [], pagination: { hasMore: false, total: 0, current: 1 } },
+        isLoading: false,
+        isFetching: false,
+        error: null,
+        refetch: jest.fn(),
+      });
+
+      const Wrapper = createWrapper();
+      render(
+        <Wrapper>
+          <AgentGrid category="all" searchQuery="" onSelectAgent={jest.fn()} />
+        </Wrapper>,
+      );
+
+      // Check empty state accessibility
+      const emptyState = screen.getByRole('status');
+      expect(emptyState).toHaveAttribute('aria-live', 'polite');
+      expect(emptyState).toHaveAttribute('aria-label', 'No agents found');
+    });
+  });
+
+  describe('ErrorDisplay Accessibility', () => {
+    const mockError = {
+      response: {
+        data: {
+          userMessage: 'Unable to load agents. Please try refreshing the page.',
+          suggestion: 'Try refreshing the page or check your network connection',
+        },
+      },
+    };
+
+    it('implements proper alert role and ARIA attributes', () => {
+      render(<ErrorDisplay error={mockError} onRetry={jest.fn()} />);
+
+      // Check alert role
+      const alert = screen.getByRole('alert');
+      expect(alert).toHaveAttribute('aria-live', 'assertive');
+      expect(alert).toHaveAttribute('aria-atomic', 'true');
+
+      // Check heading structure
+      const heading = screen.getByRole('heading', { level: 2 });
+      expect(heading).toHaveAttribute('id', 'error-title');
+    });
+
+    it('provides accessible retry button', () => {
+      const onRetry = jest.fn();
+      render(<ErrorDisplay error={mockError} onRetry={onRetry} />);
+
+      const retryButton = screen.getByRole('button', { name: /retry action/i });
+      expect(retryButton).toHaveAttribute('aria-describedby', 'error-message error-suggestion');
+
+      fireEvent.click(retryButton);
+      expect(onRetry).toHaveBeenCalledTimes(1);
+    });
+
+    it('structures error content with proper semantics', () => {
+      render(<ErrorDisplay error={mockError} />);
+
+      // Check error message structure
+      expect(screen.getByText(/unable to load agents/i)).toHaveAttribute('id', 'error-message');
+
+      // Check suggestion note
+      const suggestion = screen.getByRole('note');
+      expect(suggestion).toHaveAttribute('aria-label', expect.stringContaining('Suggestion:'));
+    });
+  });
+
+  describe('Focus Management', () => {
+    it('maintains proper focus ring styles', () => {
+      const { container } = render(<SearchBar value="" onSearch={jest.fn()} />);
+
+      // Check for focus styles in CSS classes
+      const searchInput = container.querySelector('input');
+      expect(searchInput?.className).toContain('focus:');
+    });
+
+    it('provides visible focus indicators on interactive elements', () => {
+      render(
+        <CategoryTabs
+          categories={[{ name: 'test', count: 1 }]}
+          activeTab="test"
+          isLoading={false}
+          onChange={jest.fn()}
+        />,
+      );
+
+      const tab = screen.getByRole('tab');
+      expect(tab.className).toContain('focus:outline-none');
+      expect(tab.className).toContain('focus:ring-2');
+    });
+  });
+
+  describe('Screen Reader Announcements', () => {
+    it('includes live regions for dynamic content', () => {
+      const Wrapper = createWrapper();
+      render(
+        <Wrapper>
+          <AgentGrid category="all" searchQuery="" onSelectAgent={jest.fn()} />
+        </Wrapper>,
+      );
+
+      // Check for live region
+      const liveRegion = document.querySelector('[aria-live="polite"]');
+      expect(liveRegion).toBeInTheDocument();
+    });
+
+    it('provides screen reader only content', () => {
+      render(<SearchBar value="" onSearch={jest.fn()} />);
+
+      // Check for screen reader only instructions
+      const srOnlyElement = document.querySelector('.sr-only');
+      expect(srOnlyElement).toBeInTheDocument();
+    });
+  });
+});
+
+export default {};

client/src/components/SidePanel/Agents/__tests__/AgentCard.spec.tsx

@@ -0,0 +1,197 @@
+import React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import AgentCard from '../AgentCard';
+import type t from 'librechat-data-provider';
+
+// Mock useLocalize hook
+jest.mock('~/hooks/useLocalize', () => () => (key: string) => {
+  const mockTranslations: Record<string, string> = {
+    com_agents_created_by: 'Created by',
+  };
+  return mockTranslations[key] || key;
+});
+
+describe('AgentCard', () => {
+  const mockAgent: t.Agent = {
+    id: '1',
+    name: 'Test Agent',
+    description: 'A test agent for testing purposes',
+    support_contact: {
+      name: 'Test Support',
+      email: 'test@example.com',
+    },
+    avatar: '/test-avatar.png',
+  } as t.Agent;
+
+  const mockOnClick = jest.fn();
+
+  beforeEach(() => {
+    mockOnClick.mockClear();
+  });
+
+  it('renders agent information correctly', () => {
+    render(<AgentCard agent={mockAgent} onClick={mockOnClick} />);
+
+    expect(screen.getByText('Test Agent')).toBeInTheDocument();
+    expect(screen.getByText('A test agent for testing purposes')).toBeInTheDocument();
+    expect(screen.getByText('Created by')).toBeInTheDocument();
+    expect(screen.getByText('Test Support')).toBeInTheDocument();
+  });
+
+  it('displays avatar when provided as string', () => {
+    render(<AgentCard agent={mockAgent} onClick={mockOnClick} />);
+
+    const avatarImg = screen.getByAltText('Test Agent avatar');
+    expect(avatarImg).toBeInTheDocument();
+    expect(avatarImg).toHaveAttribute('src', '/test-avatar.png');
+  });
+
+  it('displays avatar when provided as object with filepath', () => {
+    const agentWithObjectAvatar = {
+      ...mockAgent,
+      avatar: { filepath: '/object-avatar.png' },
+    };
+
+    render(<AgentCard agent={agentWithObjectAvatar} onClick={mockOnClick} />);
+
+    const avatarImg = screen.getByAltText('Test Agent avatar');
+    expect(avatarImg).toBeInTheDocument();
+    expect(avatarImg).toHaveAttribute('src', '/object-avatar.png');
+  });
+
+  it('displays Bot icon fallback when no avatar is provided', () => {
+    const agentWithoutAvatar = {
+      ...mockAgent,
+      avatar: undefined,
+    };
+
+    render(<AgentCard agent={agentWithoutAvatar} onClick={mockOnClick} />);
+
+    // Check for Bot icon presence by looking for the svg with lucide-bot class
+    const botIcon = document.querySelector('.lucide-bot');
+    expect(botIcon).toBeInTheDocument();
+  });
+
+  it('calls onClick when card is clicked', () => {
+    render(<AgentCard agent={mockAgent} onClick={mockOnClick} />);
+
+    const card = screen.getByRole('button');
+    fireEvent.click(card);
+
+    expect(mockOnClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('calls onClick when Enter key is pressed', () => {
+    render(<AgentCard agent={mockAgent} onClick={mockOnClick} />);
+
+    const card = screen.getByRole('button');
+    fireEvent.keyDown(card, { key: 'Enter' });
+
+    expect(mockOnClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('calls onClick when Space key is pressed', () => {
+    render(<AgentCard agent={mockAgent} onClick={mockOnClick} />);
+
+    const card = screen.getByRole('button');
+    fireEvent.keyDown(card, { key: ' ' });
+
+    expect(mockOnClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not call onClick for other keys', () => {
+    render(<AgentCard agent={mockAgent} onClick={mockOnClick} />);
+
+    const card = screen.getByRole('button');
+    fireEvent.keyDown(card, { key: 'Escape' });
+
+    expect(mockOnClick).not.toHaveBeenCalled();
+  });
+
+  it('applies additional className when provided', () => {
+    render(<AgentCard agent={mockAgent} onClick={mockOnClick} className="custom-class" />);
+
+    const card = screen.getByRole('button');
+    expect(card).toHaveClass('custom-class');
+  });
+
+  it('handles missing support contact gracefully', () => {
+    const agentWithoutContact = {
+      ...mockAgent,
+      support_contact: undefined,
+      authorName: undefined,
+    };
+
+    render(<AgentCard agent={agentWithoutContact} onClick={mockOnClick} />);
+
+    expect(screen.getByText('Test Agent')).toBeInTheDocument();
+    expect(screen.getByText('A test agent for testing purposes')).toBeInTheDocument();
+    expect(screen.queryByText(/Created by/)).not.toBeInTheDocument();
+  });
+
+  it('displays authorName when support_contact is missing', () => {
+    const agentWithAuthorName = {
+      ...mockAgent,
+      support_contact: undefined,
+      authorName: 'John Doe',
+    };
+
+    render(<AgentCard agent={agentWithAuthorName} onClick={mockOnClick} />);
+
+    expect(screen.getByText('Created by')).toBeInTheDocument();
+    expect(screen.getByText('John Doe')).toBeInTheDocument();
+  });
+
+  it('displays support_contact email when name is missing', () => {
+    const agentWithEmailOnly = {
+      ...mockAgent,
+      support_contact: { email: 'contact@example.com' },
+      authorName: undefined,
+    };
+
+    render(<AgentCard agent={agentWithEmailOnly} onClick={mockOnClick} />);
+
+    expect(screen.getByText('Created by')).toBeInTheDocument();
+    expect(screen.getByText('contact@example.com')).toBeInTheDocument();
+  });
+
+  it('prioritizes support_contact name over authorName', () => {
+    const agentWithBoth = {
+      ...mockAgent,
+      support_contact: { name: 'Support Team' },
+      authorName: 'John Doe',
+    };
+
+    render(<AgentCard agent={agentWithBoth} onClick={mockOnClick} />);
+
+    expect(screen.getByText('Created by')).toBeInTheDocument();
+    expect(screen.getByText('Support Team')).toBeInTheDocument();
+    expect(screen.queryByText('John Doe')).not.toBeInTheDocument();
+  });
+
+  it('prioritizes name over email in support_contact', () => {
+    const agentWithNameAndEmail = {
+      ...mockAgent,
+      support_contact: {
+        name: 'Support Team',
+        email: 'support@example.com',
+      },
+      authorName: undefined,
+    };
+
+    render(<AgentCard agent={agentWithNameAndEmail} onClick={mockOnClick} />);
+
+    expect(screen.getByText('Created by')).toBeInTheDocument();
+    expect(screen.getByText('Support Team')).toBeInTheDocument();
+    expect(screen.queryByText('support@example.com')).not.toBeInTheDocument();
+  });
+
+  it('has proper accessibility attributes', () => {
+    render(<AgentCard agent={mockAgent} onClick={mockOnClick} />);
+
+    const card = screen.getByRole('button');
+    expect(card).toHaveAttribute('tabIndex', '0');
+    expect(card).toHaveAttribute('aria-label', 'com_agents_agent_card_label');
+  });
+});

client/src/components/SidePanel/Agents/__tests__/AgentCategoryDisplay.spec.tsx

@@ -0,0 +1,90 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import AgentCategoryDisplay from '../AgentCategoryDisplay';
+
+// Mock the useAgentCategories hook
+jest.mock('~/hooks/Agents', () => ({
+  useAgentCategories: () => ({
+    categories: [
+      {
+        value: 'general',
+        label: 'General',
+        icon: <span data-testid="icon-general">{''}</span>,
+        className: 'w-full',
+      },
+      {
+        value: 'hr',
+        label: 'HR',
+        icon: <span data-testid="icon-hr">{''}</span>,
+        className: 'w-full',
+      },
+      {
+        value: 'rd',
+        label: 'R&D',
+        icon: <span data-testid="icon-rd">{''}</span>,
+        className: 'w-full',
+      },
+      {
+        value: 'finance',
+        label: 'Finance',
+        icon: <span data-testid="icon-finance">{''}</span>,
+        className: 'w-full',
+      },
+    ],
+    emptyCategory: {
+      value: '',
+      label: 'General',
+      className: 'w-full',
+    },
+  }),
+}));
+
+describe('AgentCategoryDisplay', () => {
+  it('should display the proper label for a category', () => {
+    render(<AgentCategoryDisplay category="rd" />);
+    expect(screen.getByText('R&D')).toBeInTheDocument();
+  });
+
+  it('should display the icon when showIcon is true', () => {
+    render(<AgentCategoryDisplay category="finance" showIcon={true} />);
+    expect(screen.getByTestId('icon-finance')).toBeInTheDocument();
+    expect(screen.getByText('Finance')).toBeInTheDocument();
+  });
+
+  it('should not display the icon when showIcon is false', () => {
+    render(<AgentCategoryDisplay category="hr" showIcon={false} />);
+    expect(screen.queryByTestId('icon-hr')).not.toBeInTheDocument();
+    expect(screen.getByText('HR')).toBeInTheDocument();
+  });
+
+  it('should apply custom classnames', () => {
+    render(<AgentCategoryDisplay category="general" className="test-class" />);
+    expect(screen.getByText('General').parentElement).toHaveClass('test-class');
+  });
+
+  it('should not render anything for unknown categories', () => {
+    const { container } = render(<AgentCategoryDisplay category="unknown" />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('should not render anything when no category is provided', () => {
+    const { container } = render(<AgentCategoryDisplay />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('should not render anything for empty category when showEmptyFallback is false', () => {
+    const { container } = render(<AgentCategoryDisplay category="" />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('should render empty category placeholder when showEmptyFallback is true', () => {
+    render(<AgentCategoryDisplay category="" showEmptyFallback={true} />);
+    expect(screen.getByText('General')).toBeInTheDocument();
+  });
+
+  it('should apply custom iconClassName to the icon', () => {
+    render(<AgentCategoryDisplay category="general" iconClassName="custom-icon-class" />);
+    const iconElement = screen.getByTestId('icon-general').parentElement;
+    expect(iconElement).toHaveClass('custom-icon-class');
+  });
+});

client/src/components/SidePanel/Agents/__tests__/AgentDetail.spec.tsx

@@ -0,0 +1,359 @@
+import React from 'react';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { MemoryRouter, useNavigate } from 'react-router-dom';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { RecoilRoot } from 'recoil';
+
+import type t from 'librechat-data-provider';
+
+import AgentDetail from '../AgentDetail';
+import { useToast } from '~/hooks';
+import useLocalize from '~/hooks/useLocalize';
+
+// Mock dependencies
+jest.mock('react-router-dom', () => ({
+  ...jest.requireActual('react-router-dom'),
+  useNavigate: jest.fn(),
+}));
+
+jest.mock('~/hooks', () => ({
+  useToast: jest.fn(),
+}));
+
+jest.mock('~/hooks/useLocalize', () => ({
+  __esModule: true,
+  default: jest.fn(),
+}));
+
+jest.mock('~/utils/agents', () => ({
+  renderAgentAvatar: jest.fn((agent, options) => (
+    <div data-testid="agent-avatar" data-size={options?.size} />
+  )),
+}));
+
+// Mock clipboard API
+Object.assign(navigator, {
+  clipboard: {
+    writeText: jest.fn(),
+  },
+});
+
+const mockNavigate = jest.fn();
+const mockShowToast = jest.fn();
+const mockLocalize = jest.fn((key: string) => key);
+
+const mockAgent: t.Agent = {
+  id: 'test-agent-id',
+  name: 'Test Agent',
+  description: 'This is a test agent for unit testing',
+  avatar: {
+    filepath: '/path/to/avatar.png',
+    source: 'local' as const,
+  },
+  model: 'gpt-4',
+  provider: 'openai',
+  instructions: 'You are a helpful test agent',
+  tools: [],
+  code_interpreter: false,
+  file_search: false,
+  author: 'test-user-id',
+  author_name: 'Test User',
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString(),
+  version: 1,
+  support_contact: {
+    name: 'Support Team',
+    email: 'support@test.com',
+  },
+};
+
+// Helper function to render with providers
+const renderWithProviders = (ui: React.ReactElement, options = {}) => {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false },
+    },
+  });
+
+  const Wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>
+      <RecoilRoot>
+        <MemoryRouter>{children}</MemoryRouter>
+      </RecoilRoot>
+    </QueryClientProvider>
+  );
+
+  return render(ui, { wrapper: Wrapper, ...options });
+};
+
+describe('AgentDetail', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    (useNavigate as jest.Mock).mockReturnValue(mockNavigate);
+    (useToast as jest.Mock).mockReturnValue({ showToast: mockShowToast });
+    (useLocalize as jest.Mock).mockReturnValue(mockLocalize);
+
+    // Reset clipboard mock
+    (navigator.clipboard.writeText as jest.Mock).mockResolvedValue(undefined);
+  });
+
+  const defaultProps = {
+    agent: mockAgent,
+    isOpen: true,
+    onClose: jest.fn(),
+  };
+
+  describe('Rendering', () => {
+    it('should render agent details correctly', () => {
+      renderWithProviders(<AgentDetail {...defaultProps} />);
+
+      expect(screen.getByText('Test Agent')).toBeInTheDocument();
+      expect(screen.getByText('This is a test agent for unit testing')).toBeInTheDocument();
+      expect(screen.getByTestId('agent-avatar')).toBeInTheDocument();
+      expect(screen.getByTestId('agent-avatar')).toHaveAttribute('data-size', 'xl');
+    });
+
+    it('should render contact information when available', () => {
+      renderWithProviders(<AgentDetail {...defaultProps} />);
+
+      expect(screen.getByText('com_agents_contact:')).toBeInTheDocument();
+      expect(screen.getByRole('link', { name: 'Support Team' })).toBeInTheDocument();
+      expect(screen.getByRole('link', { name: 'Support Team' })).toHaveAttribute(
+        'href',
+        'mailto:support@test.com',
+      );
+    });
+
+    it('should not render contact information when not available', () => {
+      const agentWithoutContact = { ...mockAgent };
+      delete (agentWithoutContact as any).support_contact;
+
+      renderWithProviders(<AgentDetail {...defaultProps} agent={agentWithoutContact} />);
+
+      expect(screen.queryByText('com_agents_contact:')).not.toBeInTheDocument();
+    });
+
+    it('should render loading state when agent is null', () => {
+      renderWithProviders(<AgentDetail {...defaultProps} agent={null as any} />);
+
+      expect(screen.getByText('com_agents_loading')).toBeInTheDocument();
+      expect(screen.getByText('com_agents_no_description')).toBeInTheDocument();
+    });
+
+    it('should render 3-dot menu button', () => {
+      renderWithProviders(<AgentDetail {...defaultProps} />);
+
+      const menuButton = screen.getByRole('button', { name: 'More options' });
+      expect(menuButton).toBeInTheDocument();
+      expect(menuButton).toHaveAttribute('aria-haspopup', 'menu');
+    });
+
+    it('should render Start Chat button', () => {
+      renderWithProviders(<AgentDetail {...defaultProps} />);
+
+      const startChatButton = screen.getByRole('button', { name: 'com_agents_start_chat' });
+      expect(startChatButton).toBeInTheDocument();
+      expect(startChatButton).not.toBeDisabled();
+    });
+  });
+
+  describe('Interactions', () => {
+    it('should navigate to chat when Start Chat button is clicked', async () => {
+      const user = userEvent.setup();
+      renderWithProviders(<AgentDetail {...defaultProps} />);
+
+      const startChatButton = screen.getByRole('button', { name: 'com_agents_start_chat' });
+      await user.click(startChatButton);
+
+      expect(mockNavigate).toHaveBeenCalledWith('/c/new?agent_id=test-agent-id');
+    });
+
+    it('should not navigate when agent is null', async () => {
+      const user = userEvent.setup();
+      renderWithProviders(<AgentDetail {...defaultProps} agent={null as any} />);
+
+      const startChatButton = screen.getByRole('button', { name: 'com_agents_start_chat' });
+      expect(startChatButton).toBeDisabled();
+
+      await user.click(startChatButton);
+      expect(mockNavigate).not.toHaveBeenCalled();
+    });
+
+    it('should open dropdown when 3-dot menu is clicked', async () => {
+      const user = userEvent.setup();
+      renderWithProviders(<AgentDetail {...defaultProps} />);
+
+      const menuButton = screen.getByRole('button', { name: 'More options' });
+      await user.click(menuButton);
+
+      expect(screen.getByRole('button', { name: 'com_agents_copy_link' })).toBeInTheDocument();
+    });
+
+    it('should close dropdown when clicking outside', async () => {
+      const user = userEvent.setup();
+      renderWithProviders(<AgentDetail {...defaultProps} />);
+
+      // Open dropdown
+      const menuButton = screen.getByRole('button', { name: 'More options' });
+      await user.click(menuButton);
+
+      expect(screen.getByRole('button', { name: 'com_agents_copy_link' })).toBeInTheDocument();
+
+      // Click outside (on the agent name)
+      const agentName = screen.getByText('Test Agent');
+      await user.click(agentName);
+
+      await waitFor(() => {
+        expect(
+          screen.queryByRole('button', { name: 'com_agents_copy_link' }),
+        ).not.toBeInTheDocument();
+      });
+    });
+
+    it('should copy link and show success toast when Copy Link is clicked', async () => {
+      const user = userEvent.setup();
+      renderWithProviders(<AgentDetail {...defaultProps} />);
+
+      // Open dropdown
+      const menuButton = screen.getByRole('button', { name: 'More options' });
+      await user.click(menuButton);
+
+      // Click copy link
+      const copyLinkButton = screen.getByRole('button', { name: 'com_agents_copy_link' });
+      await user.click(copyLinkButton);
+
+      expect(navigator.clipboard.writeText).toHaveBeenCalledWith(
+        `${window.location.origin}/c/new?agent_id=test-agent-id`,
+      );
+      expect(mockShowToast).toHaveBeenCalledWith({
+        message: 'Link copied',
+      });
+
+      // Dropdown should close
+      await waitFor(() => {
+        expect(
+          screen.queryByRole('button', { name: 'com_agents_copy_link' }),
+        ).not.toBeInTheDocument();
+      });
+    });
+
+    it('should show error toast when clipboard write fails', async () => {
+      const user = userEvent.setup();
+      (navigator.clipboard.writeText as jest.Mock).mockRejectedValue(new Error('Clipboard error'));
+
+      renderWithProviders(<AgentDetail {...defaultProps} />);
+
+      // Open dropdown and click copy link
+      const menuButton = screen.getByRole('button', { name: 'More options' });
+      await user.click(menuButton);
+
+      const copyLinkButton = screen.getByRole('button', { name: 'com_agents_copy_link' });
+      await user.click(copyLinkButton);
+
+      await waitFor(() => {
+        expect(mockShowToast).toHaveBeenCalledWith({
+          message: 'com_agents_link_copy_failed',
+        });
+      });
+    });
+
+    it('should call onClose when dialog is closed', () => {
+      const mockOnClose = jest.fn();
+      render(<AgentDetail {...defaultProps} onClose={mockOnClose} isOpen={false} />);
+
+      // Since we're testing the onOpenChange callback, we need to trigger it
+      // This would normally be done by the Dialog component when ESC is pressed or overlay is clicked
+      // We'll test this by checking that onClose is properly passed to the Dialog
+      expect(mockOnClose).toBeDefined();
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('should have proper ARIA attributes', () => {
+      renderWithProviders(<AgentDetail {...defaultProps} />);
+
+      const menuButton = screen.getByRole('button', { name: 'More options' });
+      expect(menuButton).toHaveAttribute('aria-haspopup', 'menu');
+      expect(menuButton).toHaveAttribute('aria-label', 'More options');
+    });
+
+    it('should support keyboard navigation for dropdown', async () => {
+      const user = userEvent.setup();
+      renderWithProviders(<AgentDetail {...defaultProps} />);
+
+      const menuButton = screen.getByRole('button', { name: 'More options' });
+
+      // Focus and open with Enter key
+      menuButton.focus();
+      await user.keyboard('{Enter}');
+
+      expect(screen.getByRole('button', { name: 'com_agents_copy_link' })).toBeInTheDocument();
+    });
+
+    it('should have proper focus management', async () => {
+      const user = userEvent.setup();
+      renderWithProviders(<AgentDetail {...defaultProps} />);
+
+      const menuButton = screen.getByRole('button', { name: 'More options' });
+      await user.click(menuButton);
+
+      const copyLinkButton = screen.getByRole('button', { name: 'com_agents_copy_link' });
+      expect(copyLinkButton).toHaveClass('focus:bg-surface-hover', 'focus:outline-none');
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle agent with only email contact', () => {
+      const agentWithEmailOnly = {
+        ...mockAgent,
+        support_contact: {
+          email: 'support@test.com',
+        },
+      };
+
+      renderWithProviders(<AgentDetail {...defaultProps} agent={agentWithEmailOnly} />);
+
+      expect(screen.getByRole('link', { name: 'support@test.com' })).toBeInTheDocument();
+    });
+
+    it('should handle agent with only name contact', () => {
+      const agentWithNameOnly = {
+        ...mockAgent,
+        support_contact: {
+          name: 'Support Team',
+        },
+      };
+
+      renderWithProviders(<AgentDetail {...defaultProps} agent={agentWithNameOnly} />);
+
+      expect(screen.getByText('Support Team')).toBeInTheDocument();
+      expect(screen.queryByRole('link')).not.toBeInTheDocument();
+    });
+
+    it('should handle very long description with proper text wrapping', () => {
+      const agentWithLongDescription = {
+        ...mockAgent,
+        description:
+          'This is a very long description that should wrap properly and be displayed in multiple lines when the content exceeds the available width of the container.',
+      };
+
+      renderWithProviders(<AgentDetail {...defaultProps} agent={agentWithLongDescription} />);
+
+      const description = screen.getByText(agentWithLongDescription.description);
+      expect(description).toHaveClass('whitespace-pre-wrap');
+    });
+
+    it('should handle special characters in agent name', () => {
+      const agentWithSpecialChars = {
+        ...mockAgent,
+        name: 'Test Agent™ & Co. (v2.0)',
+      };
+
+      renderWithProviders(<AgentDetail {...defaultProps} agent={agentWithSpecialChars} />);
+
+      expect(screen.getByText('Test Agent™ & Co. (v2.0)')).toBeInTheDocument();
+    });
+  });
+});

client/src/components/SidePanel/Agents/__tests__/AgentFooter.spec.tsx

@@ -1,30 +1,40 @@
 import React from 'react';
+import { SystemRoles } from 'librechat-data-provider';
 import { render, screen } from '@testing-library/react';
+import type { UseMutationResult } from '@tanstack/react-query';
 import '@testing-library/jest-dom/extend-expect';
+import type { Agent, AgentCreateParams, TUser } from 'librechat-data-provider';
 import AgentFooter from '../AgentFooter';
 import { Panel } from '~/common';
-import type { Agent, AgentCreateParams, TUser } from 'librechat-data-provider';
+
-import { SystemRoles } from 'librechat-data-provider';
+const mockUseWatch = jest.fn();
-import * as reactHookForm from 'react-hook-form';
+const mockUseAuthContext = jest.fn();
-import * as hooks from '~/hooks';
+const mockUseHasAccess = jest.fn();
-import type { UseMutationResult } from '@tanstack/react-query';
+const mockUseResourcePermissions = jest.fn();
 
 jest.mock('react-hook-form', () => ({
   useFormContext: () => ({
     control: {},
   }),
-  useWatch: () => {
+  useWatch: (params) => mockUseWatch(params),
+}));
+
+// Default mock implementations
+mockUseWatch.mockImplementation(({ name }) => {
+  if (name === 'agent') {
     return {
-      agent: {
+      _id: 'agent-db-123',
       name: 'Test Agent',
       author: 'user-123',
       projectIds: ['project-1'],
       isCollaborative: false,
-      },
-      id: 'agent-123',
     };
-  },
+  }
-}));
+  if (name === 'id') {
+    return 'agent-123';
+  }
+  return undefined;
+});
 
 const mockUser = {
   id: 'user-123',
@@ -39,15 +49,8 @@ const mockUser = {
   updatedAt: '2023-01-01T00:00:00.000Z',
 } as TUser;
 
-jest.mock('~/hooks', () => ({
+// Default auth context
-  useLocalize: () => (key) => {
+mockUseAuthContext.mockReturnValue({
-    const translations = {
-      com_ui_save: 'Save',
-      com_ui_create: 'Create',
-    };
-    return translations[key] || key;
-  },
-  useAuthContext: () => ({
   user: mockUser,
   token: 'mock-token',
   isAuthenticated: true,
@@ -56,8 +59,27 @@ jest.mock('~/hooks', () => ({
   logout: jest.fn(),
   setError: jest.fn(),
   roles: {},
-  }),
+});
-  useHasAccess: () => true,
+
+// Default access and permissions
+mockUseHasAccess.mockReturnValue(true);
+mockUseResourcePermissions.mockReturnValue({
+  hasPermission: () => true,
+  isLoading: false,
+  permissionBits: 0,
+});
+
+jest.mock('~/hooks', () => ({
+  useLocalize: () => (key) => {
+    const translations = {
+      com_ui_save: 'Save',
+      com_ui_create: 'Create',
+    };
+    return translations[key] || key;
+  },
+  useAuthContext: () => mockUseAuthContext(),
+  useHasAccess: () => mockUseHasAccess(),
+  useResourcePermissions: () => mockUseResourcePermissions(),
 }));
 
 const createBaseMutation = <T = Agent, P = any>(
@@ -126,9 +148,9 @@ jest.mock('../DeleteButton', () => ({
   default: jest.fn(() => <div data-testid="delete-button" />),
 }));
 
-jest.mock('../ShareAgent', () => ({
+jest.mock('../Sharing/GrantAccessDialog', () => ({
   __esModule: true,
-  default: jest.fn(() => <div data-testid="share-agent" />),
+  default: jest.fn(() => <div data-testid="grant-access-dialog" />),
 }));
 
 jest.mock('../DuplicateAgent', () => ({
@@ -186,6 +208,40 @@ describe('AgentFooter', () => {
 
   beforeEach(() => {
     jest.clearAllMocks();
+    // Reset to default mock implementations
+    mockUseWatch.mockImplementation(({ name }) => {
+      if (name === 'agent') {
+        return {
+          _id: 'agent-db-123',
+          name: 'Test Agent',
+          author: 'user-123',
+          projectIds: ['project-1'],
+          isCollaborative: false,
+        };
+      }
+      if (name === 'id') {
+        return 'agent-123';
+      }
+      return undefined;
+    });
+    // Reset auth context to default user
+    mockUseAuthContext.mockReturnValue({
+      user: mockUser,
+      token: 'mock-token',
+      isAuthenticated: true,
+      error: undefined,
+      login: jest.fn(),
+      logout: jest.fn(),
+      setError: jest.fn(),
+      roles: {},
+    });
+    // Reset access and permissions to defaults
+    mockUseHasAccess.mockReturnValue(true);
+    mockUseResourcePermissions.mockReturnValue({
+      hasPermission: () => true,
+      isLoading: false,
+      permissionBits: 0,
+    });
   });
 
   describe('Main Functionality', () => {
@@ -196,8 +252,8 @@ describe('AgentFooter', () => {
       expect(screen.getByTestId('version-button')).toBeInTheDocument();
       expect(screen.getByTestId('delete-button')).toBeInTheDocument();
       expect(screen.queryByTestId('admin-settings')).not.toBeInTheDocument();
-      expect(screen.queryByTestId('share-agent')).not.toBeInTheDocument();
+      expect(screen.getByTestId('grant-access-dialog')).toBeInTheDocument();
-      expect(screen.queryByTestId('duplicate-agent')).not.toBeInTheDocument();
+      expect(screen.getByTestId('duplicate-agent')).toBeInTheDocument();
       expect(document.querySelector('.spinner')).not.toBeInTheDocument();
     });
 
@@ -227,42 +283,125 @@ describe('AgentFooter', () => {
     });
 
     test('adjusts UI based on agent ID existence', () => {
-      jest.spyOn(reactHookForm, 'useWatch').mockImplementation(() => ({
+      mockUseWatch.mockImplementation(({ name }) => {
-        agent: { name: 'Test Agent', author: 'user-123' },
+        if (name === 'agent') {
-        id: undefined,
+          return null; // No agent means no delete/share/duplicate buttons
-      }));
+        }
-
+        if (name === 'id') {
-      render(<AgentFooter {...defaultProps} />);
+          return undefined; // No ID means create mode
-      expect(screen.getByText('Save')).toBeInTheDocument();
+        }
-      expect(screen.getByTestId('version-button')).toBeInTheDocument();
+        return undefined;
       });
 
-    test('adjusts UI based on user role', () => {
+      // When there's no agent, permissions should also return false
-      jest.spyOn(hooks, 'useAuthContext').mockReturnValue(createAuthContext(mockUsers.admin));
+      mockUseResourcePermissions.mockReturnValue({
-      render(<AgentFooter {...defaultProps} />);
+        hasPermission: () => false,
-      expect(screen.queryByTestId('admin-settings')).not.toBeInTheDocument();
+        isLoading: false,
-      expect(screen.queryByTestId('share-agent')).not.toBeInTheDocument();
+        permissionBits: 0,
+      });
 
-      jest.clearAllMocks();
-      jest.spyOn(hooks, 'useAuthContext').mockReturnValue(createAuthContext(mockUsers.different));
       render(<AgentFooter {...defaultProps} />);
-      expect(screen.queryByTestId('share-agent')).not.toBeInTheDocument();
+      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('duplicate-agent')).not.toBeInTheDocument();
     });
 
-    test('adjusts UI based on permissions', () => {
+    test('adjusts UI based on user role', () => {
-      jest.spyOn(hooks, 'useHasAccess').mockReturnValue(false);
+      mockUseAuthContext.mockReturnValue(createAuthContext(mockUsers.admin));
+      const { unmount } = render(<AgentFooter {...defaultProps} />);
+      expect(screen.getByTestId('admin-settings')).toBeInTheDocument();
+      expect(screen.getByTestId('grant-access-dialog')).toBeInTheDocument();
+
+      // Clean up the first render
+      unmount();
+
+      jest.clearAllMocks();
+      mockUseAuthContext.mockReturnValue(createAuthContext(mockUsers.different));
+      mockUseWatch.mockImplementation(({ name }) => {
+        if (name === 'agent') {
+          return { name: 'Test Agent', author: 'different-author', _id: 'agent-123' };
+        }
+        if (name === 'id') {
+          return 'agent-123';
+        }
+        return undefined;
+      });
       render(<AgentFooter {...defaultProps} />);
-      expect(screen.queryByTestId('share-agent')).not.toBeInTheDocument();
+      expect(screen.queryByTestId('grant-access-dialog')).toBeInTheDocument(); // Still shows because hasAccess is true
+      expect(screen.queryByTestId('duplicate-agent')).not.toBeInTheDocument(); // Should not show for different author
+    });
+
+    test('adjusts UI based on permissions', () => {
+      mockUseHasAccess.mockReturnValue(false);
+      // Also need to ensure the agent is not owned by the user and user is not admin
+      mockUseWatch.mockImplementation(({ name }) => {
+        if (name === 'agent') {
+          return {
+            _id: 'agent-db-123',
+            name: 'Test Agent',
+            author: 'different-user', // Different author
+            projectIds: ['project-1'],
+            isCollaborative: false,
+          };
+        }
+        if (name === 'id') {
+          return 'agent-123';
+        }
+        return undefined;
+      });
+      // Mock permissions to not allow sharing
+      mockUseResourcePermissions.mockReturnValue({
+        hasPermission: () => false, // No permissions
+        isLoading: false,
+        permissionBits: 0,
+      });
+      render(<AgentFooter {...defaultProps} />);
+      expect(screen.queryByTestId('grant-access-dialog')).not.toBeInTheDocument();
+    });
+
+    test('hides action buttons when permissions are loading', () => {
+      // Ensure we have an agent that would normally show buttons
+      mockUseWatch.mockImplementation(({ name }) => {
+        if (name === 'agent') {
+          return {
+            _id: 'agent-db-123',
+            name: 'Test Agent',
+            author: 'user-123', // Same as current user
+            projectIds: ['project-1'],
+            isCollaborative: false,
+          };
+        }
+        if (name === 'id') {
+          return 'agent-123';
+        }
+        return undefined;
+      });
+      mockUseResourcePermissions.mockReturnValue({
+        hasPermission: () => true,
+        isLoading: true, // This should hide the buttons
+        permissionBits: 0,
+      });
+      render(<AgentFooter {...defaultProps} />);
+      expect(screen.queryByTestId('delete-button')).not.toBeInTheDocument();
+      expect(screen.queryByTestId('grant-access-dialog')).not.toBeInTheDocument();
+      // Duplicate button should still show as it doesn't depend on permissions loading
+      expect(screen.getByTestId('duplicate-agent')).toBeInTheDocument();
     });
   });
 
   describe('Edge Cases', () => {
     test('handles null agent data', () => {
-      jest.spyOn(reactHookForm, 'useWatch').mockImplementation(() => ({
+      mockUseWatch.mockImplementation(({ name }) => {
-        agent: null,
+        if (name === 'agent') {
-        id: 'agent-123',
+          return null;
-      }));
+        }
+        if (name === 'id') {
+          return 'agent-123';
+        }
+        return undefined;
+      });
 
       render(<AgentFooter {...defaultProps} />);
       expect(screen.getByText('Save')).toBeInTheDocument();

client/src/components/SidePanel/Agents/__tests__/AgentGrid.integration.spec.tsx

@@ -0,0 +1,339 @@
+import React from 'react';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import AgentGrid from '../AgentGrid';
+import { useDynamicAgentQuery } from '~/hooks/Agents';
+import type t from 'librechat-data-provider';
+
+// Mock the dynamic agent query hook
+jest.mock('~/hooks/Agents', () => ({
+  useDynamicAgentQuery: jest.fn(),
+}));
+
+// Mock useLocalize hook
+jest.mock('~/hooks/useLocalize', () => () => (key: string) => {
+  const mockTranslations: Record<string, string> = {
+    com_agents_top_picks: 'Top Picks',
+    com_agents_all: 'All Agents',
+    com_agents_recommended: 'Our recommended agents',
+    com_agents_results_for: 'Results for "{{query}}"',
+    com_agents_see_more: 'See more',
+    com_agents_error_loading: 'Error loading agents',
+    com_agents_error_searching: 'Error searching agents',
+    com_agents_no_results: 'No agents found. Try another search term.',
+    com_agents_none_in_category: 'No agents found in this category',
+  };
+  return mockTranslations[key] || key;
+});
+
+// Mock getCategoryDisplayName and getCategoryDescription
+jest.mock('~/utils/agents', () => ({
+  getCategoryDisplayName: (category: string) => {
+    const names: Record<string, string> = {
+      promoted: 'Top Picks',
+      all: 'All',
+      general: 'General',
+      hr: 'HR',
+      finance: 'Finance',
+    };
+    return names[category] || category;
+  },
+  getCategoryDescription: (category: string) => {
+    const descriptions: Record<string, string> = {
+      promoted: 'Our recommended agents',
+      all: 'Browse all available agents',
+      general: 'General purpose agents',
+      hr: 'HR agents',
+      finance: 'Finance agents',
+    };
+    return descriptions[category] || '';
+  },
+}));
+
+const mockUseDynamicAgentQuery = useDynamicAgentQuery as jest.MockedFunction<
+  typeof useDynamicAgentQuery
+>;
+
+describe('AgentGrid Integration with useDynamicAgentQuery', () => {
+  const mockOnSelectAgent = jest.fn();
+
+  const mockAgents: Partial<t.Agent>[] = [
+    {
+      id: '1',
+      name: 'Test Agent 1',
+      description: 'First test agent',
+      avatar: '/avatar1.png',
+    },
+    {
+      id: '2',
+      name: 'Test Agent 2',
+      description: 'Second test agent',
+      avatar: { filepath: '/avatar2.png' },
+    },
+  ];
+
+  const defaultMockQueryResult = {
+    data: {
+      agents: mockAgents,
+      pagination: {
+        current: 1,
+        hasMore: true,
+        total: 10,
+      },
+    },
+    isLoading: false,
+    error: null,
+    isFetching: false,
+    queryType: 'promoted' as const,
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockUseDynamicAgentQuery.mockReturnValue(defaultMockQueryResult);
+  });
+
+  describe('Query Integration', () => {
+    it('should call useDynamicAgentQuery with correct parameters', () => {
+      render(
+        <AgentGrid category="finance" searchQuery="test query" onSelectAgent={mockOnSelectAgent} />,
+      );
+
+      expect(mockUseDynamicAgentQuery).toHaveBeenCalledWith({
+        category: 'finance',
+        searchQuery: 'test query',
+        page: 1,
+        limit: 6,
+      });
+    });
+
+    it('should update page when "See More" is clicked', async () => {
+      render(<AgentGrid category="hr" searchQuery="" onSelectAgent={mockOnSelectAgent} />);
+
+      const seeMoreButton = screen.getByText('See more');
+      fireEvent.click(seeMoreButton);
+
+      await waitFor(() => {
+        expect(mockUseDynamicAgentQuery).toHaveBeenCalledWith({
+          category: 'hr',
+          searchQuery: '',
+          page: 2,
+          limit: 6,
+        });
+      });
+    });
+
+    it('should reset page when category changes', () => {
+      const { rerender } = render(
+        <AgentGrid category="general" searchQuery="" onSelectAgent={mockOnSelectAgent} />,
+      );
+
+      // Simulate clicking "See More" to increment page
+      const seeMoreButton = screen.getByText('See more');
+      fireEvent.click(seeMoreButton);
+
+      // Change category - should reset page to 1
+      rerender(<AgentGrid category="finance" searchQuery="" onSelectAgent={mockOnSelectAgent} />);
+
+      expect(mockUseDynamicAgentQuery).toHaveBeenLastCalledWith({
+        category: 'finance',
+        searchQuery: '',
+        page: 1,
+        limit: 6,
+      });
+    });
+
+    it('should reset page when search query changes', () => {
+      const { rerender } = render(
+        <AgentGrid category="hr" searchQuery="" onSelectAgent={mockOnSelectAgent} />,
+      );
+
+      // Change search query - should reset page to 1
+      rerender(
+        <AgentGrid category="hr" searchQuery="new search" onSelectAgent={mockOnSelectAgent} />,
+      );
+
+      expect(mockUseDynamicAgentQuery).toHaveBeenLastCalledWith({
+        category: 'hr',
+        searchQuery: 'new search',
+        page: 1,
+        limit: 6,
+      });
+    });
+  });
+
+  describe('Different Query Types Display', () => {
+    it('should display correct title for promoted category', () => {
+      mockUseDynamicAgentQuery.mockReturnValue({
+        ...defaultMockQueryResult,
+        queryType: 'promoted',
+      });
+
+      render(<AgentGrid category="promoted" searchQuery="" onSelectAgent={mockOnSelectAgent} />);
+
+      expect(screen.getByText('Top Picks')).toBeInTheDocument();
+      expect(screen.getByText('Our recommended agents')).toBeInTheDocument();
+    });
+
+    it('should display correct title for search results', () => {
+      mockUseDynamicAgentQuery.mockReturnValue({
+        ...defaultMockQueryResult,
+        queryType: 'search',
+      });
+
+      render(
+        <AgentGrid category="all" searchQuery="test search" onSelectAgent={mockOnSelectAgent} />,
+      );
+
+      expect(screen.getByText('Results for "test search"')).toBeInTheDocument();
+    });
+
+    it('should display correct title for specific category', () => {
+      mockUseDynamicAgentQuery.mockReturnValue({
+        ...defaultMockQueryResult,
+        queryType: 'category',
+      });
+
+      render(<AgentGrid category="finance" searchQuery="" onSelectAgent={mockOnSelectAgent} />);
+
+      expect(screen.getByText('Finance')).toBeInTheDocument();
+      expect(screen.getByText('Finance agents')).toBeInTheDocument();
+    });
+
+    it('should display correct title for all category', () => {
+      mockUseDynamicAgentQuery.mockReturnValue({
+        ...defaultMockQueryResult,
+        queryType: 'all',
+      });
+
+      render(<AgentGrid category="all" searchQuery="" onSelectAgent={mockOnSelectAgent} />);
+
+      expect(screen.getByText('All')).toBeInTheDocument();
+      expect(screen.getByText('Browse all available agents')).toBeInTheDocument();
+    });
+  });
+
+  describe('Loading and Error States', () => {
+    it('should show loading skeleton when isLoading is true and no data', () => {
+      mockUseDynamicAgentQuery.mockReturnValue({
+        ...defaultMockQueryResult,
+        data: undefined,
+        isLoading: true,
+      });
+
+      render(<AgentGrid category="general" searchQuery="" onSelectAgent={mockOnSelectAgent} />);
+
+      // Should show loading skeletons
+      const loadingElements = screen.getAllByRole('generic');
+      const hasLoadingClass = loadingElements.some((el) => el.className.includes('animate-pulse'));
+      expect(hasLoadingClass).toBe(true);
+    });
+
+    it('should show error message when there is an error', () => {
+      mockUseDynamicAgentQuery.mockReturnValue({
+        ...defaultMockQueryResult,
+        data: undefined,
+        error: new Error('Test error'),
+      });
+
+      render(<AgentGrid category="general" searchQuery="" onSelectAgent={mockOnSelectAgent} />);
+
+      expect(screen.getByText('Error loading agents')).toBeInTheDocument();
+    });
+
+    it('should show loading spinner when fetching more data', () => {
+      mockUseDynamicAgentQuery.mockReturnValue({
+        ...defaultMockQueryResult,
+        isFetching: true,
+      });
+
+      render(<AgentGrid category="general" searchQuery="" onSelectAgent={mockOnSelectAgent} />);
+
+      // Should show agents and loading spinner for pagination
+      expect(screen.getByText('Test Agent 1')).toBeInTheDocument();
+      expect(screen.getByText('Test Agent 2')).toBeInTheDocument();
+    });
+  });
+
+  describe('Agent Interaction', () => {
+    it('should call onSelectAgent when agent card is clicked', () => {
+      render(<AgentGrid category="general" searchQuery="" onSelectAgent={mockOnSelectAgent} />);
+
+      const agentCard = screen.getByLabelText('Test Agent 1 agent card');
+      fireEvent.click(agentCard);
+
+      expect(mockOnSelectAgent).toHaveBeenCalledWith(mockAgents[0]);
+    });
+  });
+
+  describe('Pagination', () => {
+    it('should show "See More" button when hasMore is true', () => {
+      mockUseDynamicAgentQuery.mockReturnValue({
+        ...defaultMockQueryResult,
+        data: {
+          agents: mockAgents,
+          pagination: {
+            current: 1,
+            hasMore: true,
+            total: 10,
+          },
+        },
+      });
+
+      render(<AgentGrid category="general" searchQuery="" onSelectAgent={mockOnSelectAgent} />);
+
+      expect(screen.getByText('See more')).toBeInTheDocument();
+    });
+
+    it('should not show "See More" button when hasMore is false', () => {
+      mockUseDynamicAgentQuery.mockReturnValue({
+        ...defaultMockQueryResult,
+        data: {
+          agents: mockAgents,
+          pagination: {
+            current: 1,
+            hasMore: false,
+            total: 2,
+          },
+        },
+      });
+
+      render(<AgentGrid category="general" searchQuery="" onSelectAgent={mockOnSelectAgent} />);
+
+      expect(screen.queryByText('See more')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('Empty States', () => {
+    it('should show empty state for search results', () => {
+      mockUseDynamicAgentQuery.mockReturnValue({
+        ...defaultMockQueryResult,
+        data: {
+          agents: [],
+          pagination: { current: 1, hasMore: false, total: 0 },
+        },
+        queryType: 'search',
+      });
+
+      render(
+        <AgentGrid category="all" searchQuery="no results" onSelectAgent={mockOnSelectAgent} />,
+      );
+
+      expect(screen.getByText('No agents found. Try another search term.')).toBeInTheDocument();
+    });
+
+    it('should show empty state for category with no agents', () => {
+      mockUseDynamicAgentQuery.mockReturnValue({
+        ...defaultMockQueryResult,
+        data: {
+          agents: [],
+          pagination: { current: 1, hasMore: false, total: 0 },
+        },
+        queryType: 'category',
+      });
+
+      render(<AgentGrid category="hr" searchQuery="" onSelectAgent={mockOnSelectAgent} />);
+
+      expect(screen.getByText('No agents found in this category')).toBeInTheDocument();
+    });
+  });
+});

client/src/components/SidePanel/Agents/__tests__/CategoryTabs.spec.tsx

@@ -0,0 +1,229 @@
+import React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import '@testing-library/jest-dom';
+import CategoryTabs from '../CategoryTabs';
+import type t from 'librechat-data-provider';
+
+// Mock useLocalize hook
+jest.mock('~/hooks/useLocalize', () => () => (key: string) => {
+  const mockTranslations: Record<string, string> = {
+    com_agents_top_picks: 'Top Picks',
+    com_agents_all: 'All',
+    com_agents_no_categories: 'No categories available',
+    com_agents_category_tabs_label: 'Agent Categories',
+    com_ui_agent_category_general: 'General',
+    com_ui_agent_category_hr: 'HR',
+    com_ui_agent_category_rd: 'R&D',
+    com_ui_agent_category_finance: 'Finance',
+    com_ui_agent_category_it: 'IT',
+    com_ui_agent_category_sales: 'Sales',
+    com_ui_agent_category_aftersales: 'After Sales',
+  };
+  return mockTranslations[key] || key;
+});
+
+describe('CategoryTabs', () => {
+  const mockCategories: t.TMarketplaceCategory[] = [
+    { value: 'promoted', label: 'Top Picks', description: 'Our recommended agents', count: 5 },
+    { value: 'all', label: 'All', description: 'All available agents', count: 20 },
+    { value: 'general', label: 'General', description: 'General purpose agents', count: 8 },
+    { value: 'hr', label: 'HR', description: 'HR agents', count: 3 },
+    { value: 'finance', label: 'Finance', description: 'Finance agents', count: 4 },
+  ];
+
+  const mockOnChange = jest.fn();
+  const user = userEvent.setup();
+
+  beforeEach(() => {
+    mockOnChange.mockClear();
+  });
+
+  it('renders provided categories', () => {
+    render(
+      <CategoryTabs
+        categories={mockCategories}
+        activeTab="promoted"
+        isLoading={false}
+        onChange={mockOnChange}
+      />,
+    );
+
+    // Check for provided categories
+    expect(screen.getByText('Top Picks')).toBeInTheDocument();
+    expect(screen.getByText('All')).toBeInTheDocument();
+    expect(screen.getByText('General')).toBeInTheDocument();
+    expect(screen.getByText('HR')).toBeInTheDocument();
+    expect(screen.getByText('Finance')).toBeInTheDocument();
+  });
+
+  it('handles loading state properly', () => {
+    render(
+      <CategoryTabs
+        categories={[]}
+        activeTab="promoted"
+        isLoading={true}
+        onChange={mockOnChange}
+      />,
+    );
+
+    // SmartLoader should handle loading behavior correctly
+    // The component should render without crashing during loading
+    expect(screen.queryByText('No categories available')).not.toBeInTheDocument();
+  });
+
+  it('highlights the active tab', () => {
+    render(
+      <CategoryTabs
+        categories={mockCategories}
+        activeTab="general"
+        isLoading={false}
+        onChange={mockOnChange}
+      />,
+    );
+
+    const generalTab = screen.getByText('General').closest('button');
+    expect(generalTab).toHaveClass('text-gray-900');
+
+    // Should have active underline
+    const underline = generalTab?.querySelector('.absolute.bottom-0');
+    expect(underline).toBeInTheDocument();
+  });
+
+  it('calls onChange when a tab is clicked', async () => {
+    render(
+      <CategoryTabs
+        categories={mockCategories}
+        activeTab="promoted"
+        isLoading={false}
+        onChange={mockOnChange}
+      />,
+    );
+
+    const hrTab = screen.getByText('HR');
+    await user.click(hrTab);
+
+    expect(mockOnChange).toHaveBeenCalledWith('hr');
+  });
+
+  it('handles promoted tab click correctly', async () => {
+    render(
+      <CategoryTabs
+        categories={mockCategories}
+        activeTab="general"
+        isLoading={false}
+        onChange={mockOnChange}
+      />,
+    );
+
+    const topPicksTab = screen.getByText('Top Picks');
+    await user.click(topPicksTab);
+
+    expect(mockOnChange).toHaveBeenCalledWith('promoted');
+  });
+
+  it('handles all tab click correctly', async () => {
+    render(
+      <CategoryTabs
+        categories={mockCategories}
+        activeTab="promoted"
+        isLoading={false}
+        onChange={mockOnChange}
+      />,
+    );
+
+    const allTab = screen.getByText('All');
+    await user.click(allTab);
+
+    expect(mockOnChange).toHaveBeenCalledWith('all');
+  });
+
+  it('shows inactive state for non-selected tabs', () => {
+    render(
+      <CategoryTabs
+        categories={mockCategories}
+        activeTab="promoted"
+        isLoading={false}
+        onChange={mockOnChange}
+      />,
+    );
+
+    const generalTab = screen.getByText('General').closest('button');
+    expect(generalTab).toHaveClass('text-gray-600');
+
+    // Should not have active underline
+    const underline = generalTab?.querySelector('.absolute.bottom-0');
+    expect(underline).not.toBeInTheDocument();
+  });
+
+  it('renders with proper accessibility', () => {
+    render(
+      <CategoryTabs
+        categories={mockCategories}
+        activeTab="promoted"
+        isLoading={false}
+        onChange={mockOnChange}
+      />,
+    );
+
+    const tabs = screen.getAllByRole('tab');
+    expect(tabs.length).toBe(5);
+    // Verify all tabs are properly clickable buttons
+    tabs.forEach((tab) => {
+      expect(tab.tagName).toBe('BUTTON');
+    });
+  });
+
+  it('handles keyboard navigation', async () => {
+    render(
+      <CategoryTabs
+        categories={mockCategories}
+        activeTab="promoted"
+        isLoading={false}
+        onChange={mockOnChange}
+      />,
+    );
+
+    const generalTab = screen.getByText('General').closest('button')!;
+
+    // Focus the button and click it
+    generalTab.focus();
+    expect(document.activeElement).toBe(generalTab);
+
+    await user.click(generalTab);
+    expect(mockOnChange).toHaveBeenCalledWith('general');
+  });
+
+  it('shows empty state when categories prop is empty', () => {
+    render(
+      <CategoryTabs
+        categories={[]}
+        activeTab="promoted"
+        isLoading={false}
+        onChange={mockOnChange}
+      />,
+    );
+
+    // Should show empty state message (localized)
+    expect(screen.getByText('No categories available')).toBeInTheDocument();
+  });
+
+  it('maintains consistent ordering of categories', () => {
+    render(
+      <CategoryTabs
+        categories={mockCategories}
+        activeTab="promoted"
+        isLoading={false}
+        onChange={mockOnChange}
+      />,
+    );
+
+    const tabs = screen.getAllByRole('tab');
+    const tabTexts = tabs.map((tab) => tab.textContent);
+
+    // Check that promoted is first and all is second
+    expect(tabTexts[0]).toBe('Top Picks');
+    expect(tabTexts[1]).toBe('All');
+    expect(tabTexts.length).toBe(5);
+  });
+});

client/src/components/SidePanel/Agents/__tests__/ErrorDisplay.spec.tsx

@@ -0,0 +1,302 @@
+import React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { ErrorDisplay } from '../ErrorDisplay';
+
+// Mock matchMedia
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: jest.fn().mockImplementation((query) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: jest.fn(),
+    removeListener: jest.fn(),
+    addEventListener: jest.fn(),
+    removeEventListener: jest.fn(),
+    dispatchEvent: jest.fn(),
+  })),
+});
+
+// Mock the localize hook
+const mockLocalize = jest.fn((key: string, options?: any) => {
+  const translations: Record<string, string> = {
+    com_agents_error_title: 'Something went wrong',
+    com_agents_error_generic: 'We encountered an issue while loading the content.',
+    com_agents_error_suggestion_generic: 'Please try refreshing the page or try again later.',
+    com_agents_error_network_title: 'Connection Problem',
+    com_agents_error_network_message: 'Unable to connect to the server.',
+    com_agents_error_network_suggestion: 'Check your internet connection and try again.',
+    com_agents_error_not_found_title: 'Not Found',
+    com_agents_error_not_found_message: 'The requested content could not be found.',
+    com_agents_error_not_found_suggestion:
+      'Try browsing other options or go back to the marketplace.',
+    com_agents_error_invalid_request: 'Invalid Request',
+    com_agents_error_bad_request_message: 'The request could not be processed.',
+    com_agents_error_bad_request_suggestion: 'Please check your input and try again.',
+    com_agents_error_server_title: 'Server Error',
+    com_agents_error_server_message: 'The server is temporarily unavailable.',
+    com_agents_error_server_suggestion: 'Please try again in a few moments.',
+    com_agents_error_search_title: 'Search Error',
+    com_agents_error_category_title: 'Category Error',
+    com_agents_search_no_results: `No agents found for "${options?.query}"`,
+    com_agents_category_empty: `No agents found in the ${options?.category} category`,
+    com_agents_error_retry: 'Try Again',
+  };
+
+  return translations[key] || key;
+});
+
+jest.mock('~/hooks/useLocalize', () => () => mockLocalize);
+
+describe('ErrorDisplay', () => {
+  beforeEach(() => {
+    mockLocalize.mockClear();
+  });
+
+  describe('Backend error responses', () => {
+    it('displays user-friendly message from backend response', () => {
+      const error = {
+        response: {
+          data: {
+            userMessage: 'Unable to load agents. Please try refreshing the page.',
+            suggestion: 'Try refreshing the page or check your network connection',
+          },
+        },
+      };
+
+      render(<ErrorDisplay error={error} />);
+
+      expect(screen.getByText('Something went wrong')).toBeInTheDocument();
+      expect(
+        screen.getByText('Unable to load agents. Please try refreshing the page.'),
+      ).toBeInTheDocument();
+      expect(
+        screen.getByText('💡 Try refreshing the page or check your network connection'),
+      ).toBeInTheDocument();
+    });
+
+    it('handles search context with backend response', () => {
+      const error = {
+        response: {
+          data: {
+            userMessage: 'Search is temporarily unavailable. Please try again.',
+            suggestion: 'Try a different search term or check your network connection',
+          },
+        },
+      };
+
+      render(<ErrorDisplay error={error} context={{ searchQuery: 'test query' }} />);
+
+      expect(screen.getByText('Search Error')).toBeInTheDocument();
+      expect(
+        screen.getByText('Search is temporarily unavailable. Please try again.'),
+      ).toBeInTheDocument();
+    });
+  });
+
+  describe('Network errors', () => {
+    it('displays network error message', () => {
+      const error = {
+        code: 'NETWORK_ERROR',
+        message: 'Network Error',
+      };
+
+      render(<ErrorDisplay error={error} />);
+
+      expect(screen.getByText('Connection Problem')).toBeInTheDocument();
+      expect(screen.getByText('Unable to connect to the server.')).toBeInTheDocument();
+      expect(
+        screen.getByText('💡 Check your internet connection and try again.'),
+      ).toBeInTheDocument();
+    });
+
+    it('handles timeout errors', () => {
+      const error = {
+        code: 'ECONNABORTED',
+        message: 'timeout of 5000ms exceeded',
+      };
+
+      render(<ErrorDisplay error={error} />);
+
+      expect(mockLocalize).toHaveBeenCalledWith('com_agents_error_timeout_title');
+      expect(mockLocalize).toHaveBeenCalledWith('com_agents_error_timeout_message');
+      expect(mockLocalize).toHaveBeenCalledWith('com_agents_error_timeout_suggestion');
+    });
+  });
+
+  describe('HTTP status codes', () => {
+    it('handles 404 errors with search context', () => {
+      const error = {
+        response: {
+          status: 404,
+          data: {},
+        },
+      };
+
+      render(<ErrorDisplay error={error} context={{ searchQuery: 'nonexistent agent' }} />);
+
+      expect(screen.getByText('Not Found')).toBeInTheDocument();
+      expect(screen.getByText('No agents found for "nonexistent agent"')).toBeInTheDocument();
+    });
+
+    it('handles 404 errors with category context', () => {
+      const error = {
+        response: {
+          status: 404,
+          data: {},
+        },
+      };
+
+      render(<ErrorDisplay error={error} context={{ category: 'productivity' }} />);
+
+      expect(screen.getByText('Not Found')).toBeInTheDocument();
+      expect(screen.getByText('No agents found in the productivity category')).toBeInTheDocument();
+    });
+
+    it('handles 400 bad request errors', () => {
+      const error = {
+        response: {
+          status: 400,
+          data: {
+            error: 'Search query is required',
+            userMessage: 'Please enter a search term to find agents',
+            suggestion: 'Enter a search term to find agents by name or description',
+          },
+        },
+      };
+
+      render(<ErrorDisplay error={error} />);
+
+      expect(screen.getByText('Invalid Request')).toBeInTheDocument();
+      expect(screen.getByText('Please enter a search term to find agents')).toBeInTheDocument();
+      expect(
+        screen.getByText('💡 Enter a search term to find agents by name or description'),
+      ).toBeInTheDocument();
+    });
+
+    it('handles 500 server errors', () => {
+      const error = {
+        response: {
+          status: 500,
+          data: {},
+        },
+      };
+
+      render(<ErrorDisplay error={error} />);
+
+      expect(screen.getByText('Server Error')).toBeInTheDocument();
+      expect(screen.getByText('The server is temporarily unavailable.')).toBeInTheDocument();
+      expect(screen.getByText('💡 Please try again in a few moments.')).toBeInTheDocument();
+    });
+  });
+
+  describe('Retry functionality', () => {
+    it('displays retry button when onRetry is provided', () => {
+      const mockRetry = jest.fn();
+      const error = {
+        response: {
+          data: {
+            userMessage: 'Unable to load agents. Please try refreshing the page.',
+          },
+        },
+      };
+
+      render(<ErrorDisplay error={error} onRetry={mockRetry} />);
+
+      const retryButton = screen.getByText('Try Again');
+      expect(retryButton).toBeInTheDocument();
+
+      fireEvent.click(retryButton);
+      expect(mockRetry).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not display retry button when onRetry is not provided', () => {
+      const error = {
+        response: {
+          data: {
+            userMessage: 'Unable to load agents. Please try refreshing the page.',
+          },
+        },
+      };
+
+      render(<ErrorDisplay error={error} />);
+
+      expect(screen.queryByText('Try Again')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('Context-aware titles', () => {
+    it('shows search error title for search context', () => {
+      const error = { message: 'Some error' };
+
+      render(<ErrorDisplay error={error} context={{ searchQuery: 'test' }} />);
+
+      expect(mockLocalize).toHaveBeenCalledWith('com_agents_error_search_title');
+    });
+
+    it('shows category error title for category context', () => {
+      const error = { message: 'Some error' };
+
+      render(<ErrorDisplay error={error} context={{ category: 'productivity' }} />);
+
+      expect(mockLocalize).toHaveBeenCalledWith('com_agents_error_category_title');
+    });
+
+    it('shows generic error title when no context', () => {
+      const error = { message: 'Some error' };
+
+      render(<ErrorDisplay error={error} />);
+
+      expect(mockLocalize).toHaveBeenCalledWith('com_agents_error_title');
+    });
+  });
+
+  describe('Fallback error handling', () => {
+    it('handles unknown errors gracefully', () => {
+      const error = {
+        message: 'Unknown error occurred',
+      };
+
+      render(<ErrorDisplay error={error} />);
+
+      expect(screen.getByText('Something went wrong')).toBeInTheDocument();
+      expect(
+        screen.getByText('We encountered an issue while loading the content.'),
+      ).toBeInTheDocument();
+      expect(
+        screen.getByText('💡 Please try refreshing the page or try again later.'),
+      ).toBeInTheDocument();
+    });
+
+    it('handles null/undefined errors', () => {
+      render(<ErrorDisplay error={null} />);
+
+      expect(screen.getByText('Something went wrong')).toBeInTheDocument();
+      expect(
+        screen.getByText('We encountered an issue while loading the content.'),
+      ).toBeInTheDocument();
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('renders error icon with proper accessibility', () => {
+      const error = { message: 'Test error' };
+
+      render(<ErrorDisplay error={error} />);
+
+      const errorIcon = screen.getByRole('img', { hidden: true });
+      expect(errorIcon).toBeInTheDocument();
+    });
+
+    it('has proper heading structure', () => {
+      const error = { message: 'Test error' };
+
+      render(<ErrorDisplay error={error} />);
+
+      const heading = screen.getByRole('heading', { level: 3 });
+      expect(heading).toHaveTextContent('Something went wrong');
+    });
+  });
+});
+
+export default {};

client/src/components/SidePanel/Agents/__tests__/MarketplaceContext.spec.tsx

@@ -0,0 +1,134 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { EModelEndpoint } from 'librechat-data-provider';
+import { MarketplaceProvider } from '../MarketplaceContext';
+import { useChatContext } from '~/Providers';
+
+// Mock the ChatContext from Providers
+jest.mock('~/Providers', () => ({
+  ChatContext: {
+    Provider: ({ children, value }: { children: React.ReactNode; value: any }) => (
+      <div data-testid="chat-context-provider" data-value={JSON.stringify(value)}>
+        {children}
+      </div>
+    ),
+  },
+  useChatContext: jest.fn(),
+}));
+
+const mockedUseChatContext = useChatContext as jest.MockedFunction<typeof useChatContext>;
+
+// Test component that consumes the context
+const TestConsumer: React.FC = () => {
+  const context = mockedUseChatContext();
+
+  return (
+    <div>
+      <div data-testid="endpoint">{context?.conversation?.endpoint}</div>
+      <div data-testid="conversation-id">{context?.conversation?.conversationId}</div>
+      <div data-testid="title">{context?.conversation?.title}</div>
+    </div>
+  );
+};
+
+describe('MarketplaceProvider', () => {
+  beforeEach(() => {
+    mockedUseChatContext.mockClear();
+  });
+
+  it('provides correct marketplace context values', () => {
+    const mockContext = {
+      conversation: {
+        endpoint: EModelEndpoint.agents,
+        conversationId: 'marketplace',
+        title: 'Agent Marketplace',
+      },
+    };
+
+    mockedUseChatContext.mockReturnValue(mockContext);
+
+    render(
+      <MarketplaceProvider>
+        <TestConsumer />
+      </MarketplaceProvider>,
+    );
+
+    expect(screen.getByTestId('endpoint')).toHaveTextContent(EModelEndpoint.agents);
+    expect(screen.getByTestId('conversation-id')).toHaveTextContent('marketplace');
+    expect(screen.getByTestId('title')).toHaveTextContent('Agent Marketplace');
+  });
+
+  it('creates ChatContext.Provider with correct structure', () => {
+    render(
+      <MarketplaceProvider>
+        <div>{/* eslint-disable-line i18next/no-literal-string */}Test Child</div>
+      </MarketplaceProvider>,
+    );
+
+    const provider = screen.getByTestId('chat-context-provider');
+    expect(provider).toBeInTheDocument();
+
+    const valueData = JSON.parse(provider.getAttribute('data-value') || '{}');
+    expect(valueData.conversation).toEqual({
+      endpoint: EModelEndpoint.agents,
+      conversationId: 'marketplace',
+      title: 'Agent Marketplace',
+    });
+  });
+
+  it('renders children correctly', () => {
+    render(
+      <MarketplaceProvider>
+        <div data-testid="test-child">
+          {/* eslint-disable-line i18next/no-literal-string */}Test Content
+        </div>
+      </MarketplaceProvider>,
+    );
+
+    expect(screen.getByTestId('test-child')).toBeInTheDocument();
+    expect(screen.getByTestId('test-child')).toHaveTextContent('Test Content');
+  });
+
+  it('provides stable context value (memoization)', () => {
+    const { rerender } = render(
+      <MarketplaceProvider>
+        <TestConsumer />
+      </MarketplaceProvider>,
+    );
+
+    const firstProvider = screen.getByTestId('chat-context-provider');
+    const firstValue = firstProvider.getAttribute('data-value');
+
+    // Rerender should provide the same memoized value
+    rerender(
+      <MarketplaceProvider>
+        <TestConsumer />
+      </MarketplaceProvider>,
+    );
+
+    const secondProvider = screen.getByTestId('chat-context-provider');
+    const secondValue = secondProvider.getAttribute('data-value');
+
+    expect(firstValue).toBe(secondValue);
+  });
+
+  it('provides minimal context without bloated functions', () => {
+    render(
+      <MarketplaceProvider>
+        <div>{/* eslint-disable-line i18next/no-literal-string */}Test</div>
+      </MarketplaceProvider>,
+    );
+
+    const provider = screen.getByTestId('chat-context-provider');
+    const valueData = JSON.parse(provider.getAttribute('data-value') || '{}');
+
+    // Should only have conversation object, not 44 empty functions
+    expect(Object.keys(valueData)).toContain('conversation');
+    expect(valueData.conversation).toEqual({
+      endpoint: EModelEndpoint.agents,
+      conversationId: 'marketplace',
+      title: 'Agent Marketplace',
+    });
+  });
+});

client/src/components/SidePanel/Agents/__tests__/SearchBar.spec.tsx

@@ -0,0 +1,141 @@
+import React from 'react';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import '@testing-library/jest-dom';
+import SearchBar from '../SearchBar';
+
+// Mock useLocalize hook
+jest.mock('~/hooks/useLocalize', () => () => (key: string) => key);
+
+// Mock useDebounce hook
+jest.mock('~/hooks', () => ({
+  useDebounce: (value: string, delay: number) => value, // Return value immediately for testing
+}));
+
+describe('SearchBar', () => {
+  const mockOnSearch = jest.fn();
+  const user = userEvent.setup();
+
+  beforeEach(() => {
+    mockOnSearch.mockClear();
+  });
+
+  it('renders with correct placeholder', () => {
+    render(<SearchBar value="" onSearch={mockOnSearch} />);
+
+    const input = screen.getByRole('textbox');
+    expect(input).toBeInTheDocument();
+    expect(input).toHaveAttribute('placeholder', 'com_agents_search_placeholder');
+  });
+
+  it('displays the provided value', () => {
+    render(<SearchBar value="test query" onSearch={mockOnSearch} />);
+
+    const input = screen.getByDisplayValue('test query');
+    expect(input).toBeInTheDocument();
+  });
+
+  it('calls onSearch when user types', async () => {
+    render(<SearchBar value="" onSearch={mockOnSearch} />);
+
+    const input = screen.getByRole('textbox');
+    await user.type(input, 'test');
+
+    // Should call onSearch for each character due to debounce mock
+    expect(mockOnSearch).toHaveBeenCalled();
+  });
+
+  it('shows clear button when there is text', () => {
+    render(<SearchBar value="test" onSearch={mockOnSearch} />);
+
+    const clearButton = screen.getByRole('button', { name: 'com_agents_clear_search' });
+    expect(clearButton).toBeInTheDocument();
+  });
+
+  it('does not show clear button when text is empty', () => {
+    render(<SearchBar value="" onSearch={mockOnSearch} />);
+
+    const clearButton = screen.queryByRole('button', { name: 'com_agents_clear_search' });
+    expect(clearButton).not.toBeInTheDocument();
+  });
+
+  it('clears search when clear button is clicked', async () => {
+    render(<SearchBar value="test" onSearch={mockOnSearch} />);
+
+    const input = screen.getByRole('textbox');
+    const clearButton = screen.getByRole('button', { name: 'com_agents_clear_search' });
+
+    // Verify initial state
+    expect(input).toHaveValue('test');
+
+    await user.click(clearButton);
+
+    // Verify onSearch is called and input is cleared
+    expect(mockOnSearch).toHaveBeenCalledWith('');
+    expect(input).toHaveValue('');
+  });
+
+  it('updates internal state when value prop changes', () => {
+    const { rerender } = render(<SearchBar value="initial" onSearch={mockOnSearch} />);
+
+    expect(screen.getByDisplayValue('initial')).toBeInTheDocument();
+
+    rerender(<SearchBar value="updated" onSearch={mockOnSearch} />);
+
+    expect(screen.getByDisplayValue('updated')).toBeInTheDocument();
+  });
+
+  it('has proper accessibility attributes', () => {
+    render(<SearchBar value="" onSearch={mockOnSearch} />);
+
+    const input = screen.getByRole('textbox');
+    expect(input).toHaveAttribute('aria-label', 'com_agents_search_aria');
+  });
+
+  it('applies custom className', () => {
+    render(<SearchBar value="" onSearch={mockOnSearch} className="custom-class" />);
+
+    const container = screen.getByRole('textbox').closest('div');
+    expect(container).toHaveClass('custom-class');
+  });
+
+  it('prevents form submission on clear button click', async () => {
+    const handleSubmit = jest.fn();
+
+    render(
+      <form onSubmit={handleSubmit}>
+        <SearchBar value="test" onSearch={mockOnSearch} />
+      </form>,
+    );
+
+    const clearButton = screen.getByRole('button', { name: 'com_agents_clear_search' });
+    await user.click(clearButton);
+
+    expect(handleSubmit).not.toHaveBeenCalled();
+  });
+
+  it('handles rapid typing correctly', async () => {
+    render(<SearchBar value="" onSearch={mockOnSearch} />);
+
+    const input = screen.getByRole('textbox');
+
+    // Type multiple characters quickly
+    await user.type(input, 'quick');
+
+    // Should handle all characters
+    expect(input).toHaveValue('quick');
+  });
+
+  it('maintains focus after clear button click', async () => {
+    render(<SearchBar value="test" onSearch={mockOnSearch} />);
+
+    const input = screen.getByRole('textbox');
+    const clearButton = screen.getByRole('button', { name: 'com_agents_clear_search' });
+
+    input.focus();
+    await user.click(clearButton);
+
+    // Input should still be in the document and ready for new input
+    expect(input).toBeInTheDocument();
+  });
+});

client/src/components/SidePanel/Agents/__tests__/SmartLoader.spec.tsx

@@ -0,0 +1,370 @@
+import React from 'react';
+import { render, screen, waitFor, act } from '@testing-library/react';
+import { SmartLoader, useHasData } from '../SmartLoader';
+
+// Mock setTimeout and clearTimeout for testing
+jest.useFakeTimers();
+
+describe('SmartLoader', () => {
+  const LoadingComponent = () => <div data-testid="loading">Loading...</div>;
+  const ContentComponent = () => (
+    <div data-testid="content">
+      {/* eslint-disable-line i18next/no-literal-string */}Content loaded
+    </div>
+  );
+
+  beforeEach(() => {
+    jest.clearAllTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+    jest.useFakeTimers();
+  });
+
+  describe('Basic functionality', () => {
+    it('shows content immediately when not loading', () => {
+      render(
+        <SmartLoader isLoading={false} hasData={true} loadingComponent={<LoadingComponent />}>
+          <ContentComponent />
+        </SmartLoader>,
+      );
+
+      expect(screen.getByTestId('content')).toBeInTheDocument();
+      expect(screen.queryByTestId('loading')).not.toBeInTheDocument();
+    });
+
+    it('shows content immediately when loading but has existing data', () => {
+      render(
+        <SmartLoader isLoading={true} hasData={true} loadingComponent={<LoadingComponent />}>
+          <ContentComponent />
+        </SmartLoader>,
+      );
+
+      expect(screen.getByTestId('content')).toBeInTheDocument();
+      expect(screen.queryByTestId('loading')).not.toBeInTheDocument();
+    });
+
+    it('shows content initially, then loading after delay when loading with no data', async () => {
+      render(
+        <SmartLoader
+          isLoading={true}
+          hasData={false}
+          delay={150}
+          loadingComponent={<LoadingComponent />}
+        >
+          <ContentComponent />
+        </SmartLoader>,
+      );
+
+      // Initially shows content
+      expect(screen.getByTestId('content')).toBeInTheDocument();
+      expect(screen.queryByTestId('loading')).not.toBeInTheDocument();
+
+      // After delay, shows loading
+      act(() => {
+        jest.advanceTimersByTime(150);
+      });
+
+      await waitFor(() => {
+        expect(screen.getByTestId('loading')).toBeInTheDocument();
+        expect(screen.queryByTestId('content')).not.toBeInTheDocument();
+      });
+    });
+
+    it('prevents loading flash for quick responses', async () => {
+      const { rerender } = render(
+        <SmartLoader
+          isLoading={true}
+          hasData={false}
+          delay={150}
+          loadingComponent={<LoadingComponent />}
+        >
+          <ContentComponent />
+        </SmartLoader>,
+      );
+
+      // Initially shows content
+      expect(screen.getByTestId('content')).toBeInTheDocument();
+
+      // Advance time but not past delay
+      act(() => {
+        jest.advanceTimersByTime(100);
+      });
+
+      // Loading finishes before delay
+      rerender(
+        <SmartLoader
+          isLoading={false}
+          hasData={true}
+          delay={150}
+          loadingComponent={<LoadingComponent />}
+        >
+          <ContentComponent />
+        </SmartLoader>,
+      );
+
+      // Should still show content, never showed loading
+      expect(screen.getByTestId('content')).toBeInTheDocument();
+      expect(screen.queryByTestId('loading')).not.toBeInTheDocument();
+
+      // Advance past original delay to ensure loading doesn't appear
+      act(() => {
+        jest.advanceTimersByTime(100);
+      });
+
+      expect(screen.getByTestId('content')).toBeInTheDocument();
+      expect(screen.queryByTestId('loading')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('Delay behavior', () => {
+    it('respects custom delay times', async () => {
+      render(
+        <SmartLoader
+          isLoading={true}
+          hasData={false}
+          delay={300}
+          loadingComponent={<LoadingComponent />}
+        >
+          <ContentComponent />
+        </SmartLoader>,
+      );
+
+      // Should show content initially
+      expect(screen.getByTestId('content')).toBeInTheDocument();
+
+      // Should not show loading before delay
+      act(() => {
+        jest.advanceTimersByTime(250);
+      });
+      expect(screen.getByTestId('content')).toBeInTheDocument();
+      expect(screen.queryByTestId('loading')).not.toBeInTheDocument();
+
+      // Should show loading after delay
+      act(() => {
+        jest.advanceTimersByTime(60);
+      });
+
+      await waitFor(() => {
+        expect(screen.getByTestId('loading')).toBeInTheDocument();
+      });
+    });
+
+    it('uses default delay when not specified', async () => {
+      render(
+        <SmartLoader isLoading={true} hasData={false} loadingComponent={<LoadingComponent />}>
+          <ContentComponent />
+        </SmartLoader>,
+      );
+
+      // Should show content initially
+      expect(screen.getByTestId('content')).toBeInTheDocument();
+
+      // Should show loading after default delay (150ms)
+      act(() => {
+        jest.advanceTimersByTime(150);
+      });
+
+      await waitFor(() => {
+        expect(screen.getByTestId('loading')).toBeInTheDocument();
+      });
+    });
+  });
+
+  describe('State transitions', () => {
+    it('immediately hides loading when loading completes', async () => {
+      const { rerender } = render(
+        <SmartLoader
+          isLoading={true}
+          hasData={false}
+          delay={100}
+          loadingComponent={<LoadingComponent />}
+        >
+          <ContentComponent />
+        </SmartLoader>,
+      );
+
+      // Advance past delay to show loading
+      act(() => {
+        jest.advanceTimersByTime(100);
+      });
+
+      await waitFor(() => {
+        expect(screen.getByTestId('loading')).toBeInTheDocument();
+      });
+
+      // Loading completes
+      rerender(
+        <SmartLoader
+          isLoading={false}
+          hasData={true}
+          delay={100}
+          loadingComponent={<LoadingComponent />}
+        >
+          <ContentComponent />
+        </SmartLoader>,
+      );
+
+      // Should immediately show content
+      expect(screen.getByTestId('content')).toBeInTheDocument();
+      expect(screen.queryByTestId('loading')).not.toBeInTheDocument();
+    });
+
+    it('handles rapid loading state changes correctly', async () => {
+      const { rerender } = render(
+        <SmartLoader
+          isLoading={true}
+          hasData={false}
+          delay={100}
+          loadingComponent={<LoadingComponent />}
+        >
+          <ContentComponent />
+        </SmartLoader>,
+      );
+
+      // Rapid state changes
+      rerender(
+        <SmartLoader
+          isLoading={false}
+          hasData={true}
+          delay={100}
+          loadingComponent={<LoadingComponent />}
+        >
+          <ContentComponent />
+        </SmartLoader>,
+      );
+
+      rerender(
+        <SmartLoader
+          isLoading={true}
+          hasData={false}
+          delay={100}
+          loadingComponent={<LoadingComponent />}
+        >
+          <ContentComponent />
+        </SmartLoader>,
+      );
+
+      // Should show content throughout rapid changes
+      expect(screen.getByTestId('content')).toBeInTheDocument();
+      expect(screen.queryByTestId('loading')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('CSS classes', () => {
+    it('applies custom className', () => {
+      const { container } = render(
+        <SmartLoader
+          isLoading={false}
+          hasData={true}
+          loadingComponent={<LoadingComponent />}
+          className="custom-class"
+        >
+          <ContentComponent />
+        </SmartLoader>,
+      );
+
+      const wrapper = container.firstChild as HTMLElement;
+      expect(wrapper).toHaveClass('custom-class');
+    });
+
+    it('applies className to both loading and content states', async () => {
+      const { container } = render(
+        <SmartLoader
+          isLoading={true}
+          hasData={false}
+          delay={50}
+          loadingComponent={<LoadingComponent />}
+          className="custom-class"
+        >
+          <ContentComponent />
+        </SmartLoader>,
+      );
+
+      // Content state
+      expect(container.firstChild).toHaveClass('custom-class');
+
+      // Loading state
+      act(() => {
+        jest.advanceTimersByTime(50);
+      });
+
+      await waitFor(() => {
+        expect(container.firstChild).toHaveClass('custom-class');
+      });
+    });
+  });
+});
+
+describe('useHasData', () => {
+  const TestComponent: React.FC<{ data: any }> = ({ data }) => {
+    const hasData = useHasData(data);
+    return <div data-testid="result">{hasData ? 'has-data' : 'no-data'}</div>;
+  };
+
+  it('returns false for null data', () => {
+    render(<TestComponent data={null} />);
+    expect(screen.getByTestId('result')).toHaveTextContent('no-data');
+  });
+
+  it('returns false for undefined data', () => {
+    render(<TestComponent data={undefined} />);
+    expect(screen.getByTestId('result')).toHaveTextContent('no-data');
+  });
+
+  it('detects empty agents array as no data', () => {
+    render(<TestComponent data={{ agents: [] }} />);
+    expect(screen.getByTestId('result')).toHaveTextContent('no-data');
+  });
+
+  it('detects non-empty agents array as has data', () => {
+    render(<TestComponent data={{ agents: [{ id: '1', name: 'Test' }] }} />);
+    expect(screen.getByTestId('result')).toHaveTextContent('has-data');
+  });
+
+  it('detects invalid agents property as no data', () => {
+    render(<TestComponent data={{ agents: 'not-array' }} />);
+    expect(screen.getByTestId('result')).toHaveTextContent('no-data');
+  });
+
+  it('detects empty array as no data', () => {
+    render(<TestComponent data={[]} />);
+    expect(screen.getByTestId('result')).toHaveTextContent('no-data');
+  });
+
+  it('detects non-empty array as has data', () => {
+    render(<TestComponent data={[{ name: 'category1' }]} />);
+    expect(screen.getByTestId('result')).toHaveTextContent('has-data');
+  });
+
+  it('detects agent with id as has data', () => {
+    render(<TestComponent data={{ id: '123', name: 'Test Agent' }} />);
+    expect(screen.getByTestId('result')).toHaveTextContent('has-data');
+  });
+
+  it('detects agent with name only as has data', () => {
+    render(<TestComponent data={{ name: 'Test Agent' }} />);
+    expect(screen.getByTestId('result')).toHaveTextContent('has-data');
+  });
+
+  it('detects object without id or name as no data', () => {
+    render(<TestComponent data={{ description: 'Some description' }} />);
+    expect(screen.getByTestId('result')).toHaveTextContent('no-data');
+  });
+
+  it('handles string data as no data', () => {
+    render(<TestComponent data="some string" />);
+    expect(screen.getByTestId('result')).toHaveTextContent('no-data');
+  });
+
+  it('handles number data as no data', () => {
+    render(<TestComponent data={42} />);
+    expect(screen.getByTestId('result')).toHaveTextContent('no-data');
+  });
+
+  it('handles boolean data as no data', () => {
+    render(<TestComponent data={true} />);
+    expect(screen.getByTestId('result')).toHaveTextContent('no-data');
+  });
+});

client/src/components/ui/SearchPicker.tsx

@@ -0,0 +1,189 @@
+import * as React from 'react';
+import { Search, X } from 'lucide-react';
+import * as Ariakit from '@ariakit/react';
+import { Spinner, Skeleton } from '@librechat/client';
+import { useLocalize } from '~/hooks';
+import { cn } from '~/utils';
+
+type SearchPickerProps<TOption extends { key: string }> = {
+  options: TOption[];
+  renderOptions: (option: TOption) => React.ReactElement;
+  query: string;
+  onQueryChange: (query: string) => void;
+  onPick: (pickedOption: TOption) => void;
+  placeholder?: string;
+  inputClassName?: string;
+  label: string;
+  resetValueOnHide?: boolean;
+  isSmallScreen?: boolean;
+  isLoading?: boolean;
+  minQueryLengthForNoResults?: number;
+};
+
+export function SearchPicker<TOption extends { key: string; value: string }>({
+  options,
+  renderOptions,
+  onPick,
+  onQueryChange,
+  query,
+  label,
+  isSmallScreen = false,
+  placeholder,
+  resetValueOnHide = false,
+  isLoading = false,
+  minQueryLengthForNoResults = 2,
+}: SearchPickerProps<TOption>) {
+  const localize = useLocalize();
+  const [_open, setOpen] = React.useState(false);
+  const inputRef = React.useRef<HTMLInputElement>(null);
+  const combobox = Ariakit.useComboboxStore({
+    resetValueOnHide,
+  });
+  const onPickHandler = (option: TOption) => {
+    onQueryChange('');
+    onPick(option);
+    setOpen(false);
+    if (inputRef.current) {
+      inputRef.current.focus();
+    }
+  };
+  const showClearIcon = query.trim().length > 0;
+  const clearText = () => {
+    onQueryChange('');
+    if (inputRef.current) {
+      inputRef.current.focus();
+    }
+  };
+  return (
+    <Ariakit.ComboboxProvider store={combobox}>
+      <Ariakit.ComboboxLabel className="text-token-text-primary mb-2 block font-medium">
+        {label}
+      </Ariakit.ComboboxLabel>
+      <div className="py-1.5">
+        <div
+          className={cn(
+            'group relative mt-1 flex h-10 cursor-pointer items-center gap-3 rounded-lg border-border-medium px-3 py-2 text-text-primary transition-colors duration-200 focus-within:bg-surface-hover hover:bg-surface-hover',
+            isSmallScreen === true ? 'mb-2 h-14 rounded-2xl' : '',
+          )}
+        >
+          {isLoading ? (
+            <Spinner className="absolute left-3 h-4 w-4 text-text-primary" />
+          ) : (
+            <Search className="absolute left-3 h-4 w-4 text-text-secondary group-focus-within:text-text-primary group-hover:text-text-primary" />
+          )}
+          <Ariakit.Combobox
+            ref={inputRef}
+            onKeyDown={(e) => {
+              if (e.key === 'Escape' && combobox.getState().open) {
+                e.preventDefault();
+                e.stopPropagation();
+                onQueryChange('');
+                setOpen(false);
+              }
+            }}
+            store={combobox}
+            setValueOnClick={false}
+            setValueOnChange={false}
+            onChange={(e) => {
+              onQueryChange(e.target.value);
+            }}
+            value={query}
+            // autoSelect
+            placeholder={placeholder || localize('com_ui_select_options')}
+            className="m-0 mr-0 w-full rounded-md border-none bg-transparent p-0 py-2 pl-9 pr-3 text-sm leading-tight text-text-primary placeholder-text-secondary placeholder-opacity-100 focus:outline-none focus-visible:outline-none group-focus-within:placeholder-text-primary group-hover:placeholder-text-primary"
+          />
+          <button
+            type="button"
+            aria-label={`${localize('com_ui_clear')} ${localize('com_ui_search')}`}
+            className={cn(
+              'absolute right-[7px] flex h-5 w-5 items-center justify-center rounded-full border-none bg-transparent p-0 transition-opacity duration-200',
+              showClearIcon ? 'opacity-100' : 'opacity-0',
+              isSmallScreen === true ? 'right-[16px]' : '',
+            )}
+            onClick={clearText}
+            tabIndex={showClearIcon ? 0 : -1}
+            disabled={!showClearIcon}
+          >
+            <X className="h-5 w-5 cursor-pointer" />
+          </button>
+        </div>
+      </div>
+      <Ariakit.ComboboxPopover
+        portal={false} //todo fix focus when set to true
+        gutter={10}
+        // sameWidth
+        open={
+          isLoading ||
+          options.length > 0 ||
+          (query.trim().length >= minQueryLengthForNoResults && !isLoading)
+        }
+        store={combobox}
+        unmountOnHide
+        autoFocusOnShow={false}
+        modal={false}
+        className={cn(
+          'animate-popover z-[9999] min-w-64 overflow-hidden rounded-xl border border-border-light bg-surface-secondary shadow-lg',
+          '[pointer-events:auto]', // Override body's pointer-events:none when in modal
+        )}
+      >
+        {(() => {
+          if (isLoading) {
+            return (
+              <div className="space-y-2 p-2">
+                {Array.from({ length: 3 }).map((_, index) => (
+                  <div key={index} className="flex items-center gap-3 px-3 py-2">
+                    <Skeleton className="h-8 w-8 rounded-full" />
+                    <div className="flex-1 space-y-1">
+                      <Skeleton className="h-4 w-3/4" />
+                      <Skeleton className="h-3 w-1/2" />
+                    </div>
+                  </div>
+                ))}
+              </div>
+            );
+          }
+
+          if (options.length > 0) {
+            return options.map((o) => (
+              <Ariakit.ComboboxItem
+                key={o.key}
+                focusOnHover
+                // hideOnClick
+                value={o.value}
+                selectValueOnClick={false}
+                onClick={() => onPickHandler(o)}
+                className={cn(
+                  'flex w-full cursor-pointer items-center px-3 text-sm',
+                  'text-text-primary hover:bg-surface-tertiary',
+                  'data-[active-item]:bg-surface-tertiary',
+                )}
+                render={renderOptions(o)}
+              ></Ariakit.ComboboxItem>
+            ));
+          }
+
+          if (query.trim().length >= minQueryLengthForNoResults) {
+            return (
+              <div
+                className={cn(
+                  'flex items-center justify-center px-4 py-8 text-center',
+                  'text-sm text-text-secondary',
+                )}
+              >
+                <div className="flex flex-col items-center gap-2">
+                  <Search className="h-8 w-8 text-text-tertiary opacity-50" />
+                  <div className="font-medium">{localize('com_ui_no_results_found')}</div>
+                  <div className="text-xs text-text-tertiary">
+                    {localize('com_ui_try_adjusting_search')}
+                  </div>
+                </div>
+              </div>
+            );
+          }
+
+          return null;
+        })()}
+      </Ariakit.ComboboxPopover>
+    </Ariakit.ComboboxProvider>
+  );
+}

client/src/constants/agentCategories.ts

@@ -0,0 +1,12 @@
+import { TranslationKeys } from '~/hooks/useLocalize';
+
+export interface AgentCategory {
+  label: TranslationKeys;
+  value: string;
+}
+
+// The empty category placeholder - used for form defaults
+export const EMPTY_AGENT_CATEGORY: AgentCategory = {
+  value: '',
+  label: 'com_ui_agent_category_general',
+};

client/src/data-provider/Agents/mutations.ts

@@ -78,6 +78,10 @@ export const useUpdateAgentMutation = (
         });
 
         queryClient.setQueryData<t.Agent>([QueryKeys.agent, variables.agent_id], updatedAgent);
+        queryClient.setQueryData<t.Agent>(
+          [QueryKeys.agent, variables.agent_id, 'expanded'],
+          updatedAgent,
+        );
         return options?.onSuccess?.(updatedAgent, variables, context);
       },
     },
@@ -116,6 +120,7 @@ export const useDeleteAgentMutation = (
         });
 
         queryClient.removeQueries([QueryKeys.agent, variables.agent_id]);
+        queryClient.removeQueries([QueryKeys.agent, variables.agent_id, 'expanded']);
 
         return options?.onSuccess?.(_data, variables, data);
       },
@@ -236,6 +241,10 @@ export const useUpdateAgentAction = (
       });
 
       queryClient.setQueryData<t.Agent>([QueryKeys.agent, variables.agent_id], updatedAgent);
+      queryClient.setQueryData<t.Agent>(
+        [QueryKeys.agent, variables.agent_id, 'expanded'],
+        updatedAgent,
+      );
       return options?.onSuccess?.(updateAgentActionResponse, variables, context);
     },
   });
@@ -288,8 +297,7 @@ export const useDeleteAgentAction = (
           };
         },
       );
-
+      const updaterFn = (prev) => {
-      queryClient.setQueryData<t.Agent>([QueryKeys.agent, variables.agent_id], (prev) => {
         if (!prev) {
           return prev;
         }
@@ -298,7 +306,12 @@ export const useDeleteAgentAction = (
           ...prev,
           tools: prev.tools?.filter((tool) => !tool.includes(domain ?? '')),
         };
-      });
+      };
+      queryClient.setQueryData<t.Agent>([QueryKeys.agent, variables.agent_id], updaterFn);
+      queryClient.setQueryData<t.Agent>(
+        [QueryKeys.agent, variables.agent_id, 'expanded'],
+        updaterFn,
+      );
       return options?.onSuccess?.(_data, variables, context);
     },
   });

client/src/data-provider/Agents/queries.ts

@@ -54,7 +54,7 @@ export const useListAgentsQuery = <TData = t.AgentListResponse>(
 };
 
 /**
- * Hook for retrieving details about a single agent
+ * Hook for retrieving basic details about a single agent (VIEW permission)
  */
 export const useGetAgentByIdQuery = (
   agent_id: string,
@@ -75,3 +75,163 @@ export const useGetAgentByIdQuery = (
     },
   );
 };
+
+/**
+ * MARKETPLACE QUERIES
+ */
+
+/**
+ * Hook for getting all agent categories with counts
+ */
+export const useGetAgentCategoriesQuery = <TData = t.TMarketplaceCategory[]>(
+  config?: UseQueryOptions<t.TMarketplaceCategory[], unknown, TData>,
+): QueryObserverResult<TData> => {
+  const queryClient = useQueryClient();
+  const endpointsConfig = queryClient.getQueryData<t.TEndpointsConfig>([QueryKeys.endpoints]);
+
+  const enabled = !!endpointsConfig?.[EModelEndpoint.agents];
+  return useQuery<t.TMarketplaceCategory[], unknown, TData>(
+    [QueryKeys.agents, 'categories'],
+    () => dataService.getAgentCategories(),
+    {
+      staleTime: 1000 * 60 * 15, // 15 minutes - categories rarely change
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: false,
+      refetchOnMount: false,
+      retry: false,
+      ...config,
+      enabled: config?.enabled !== undefined ? config.enabled && enabled : enabled,
+    },
+  );
+};
+
+/**
+ * Hook for getting promoted/top picks agents with pagination
+ */
+export const useGetPromotedAgentsQuery = <TData = t.AgentListResponse>(
+  params: { page?: number; limit?: number; showAll?: string } = { page: 1, limit: 6 },
+  config?: UseQueryOptions<t.AgentListResponse, unknown, TData>,
+): QueryObserverResult<TData> => {
+  const queryClient = useQueryClient();
+  const endpointsConfig = queryClient.getQueryData<t.TEndpointsConfig>([QueryKeys.endpoints]);
+
+  const enabled = !!endpointsConfig?.[EModelEndpoint.agents];
+  return useQuery<t.AgentListResponse, unknown, TData>(
+    [QueryKeys.agents, 'promoted', params],
+    () => dataService.getPromotedAgents(params),
+    {
+      staleTime: 1000 * 60, // 1 minute stale time
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: false,
+      refetchOnMount: false,
+      retry: false,
+      keepPreviousData: true,
+      ...config,
+      enabled: config?.enabled !== undefined ? config.enabled && enabled : enabled,
+    },
+  );
+};
+
+/**
+ * Hook for getting all agents with pagination (for "all" category)
+ */
+export const useGetAllAgentsQuery = <TData = t.AgentListResponse>(
+  params: { page?: number; limit?: number } = { page: 1, limit: 6 },
+  config?: UseQueryOptions<t.AgentListResponse, unknown, TData>,
+): QueryObserverResult<TData> => {
+  const queryClient = useQueryClient();
+  const endpointsConfig = queryClient.getQueryData<t.TEndpointsConfig>([QueryKeys.endpoints]);
+
+  const enabled = !!endpointsConfig?.[EModelEndpoint.agents];
+  return useQuery<t.AgentListResponse, unknown, TData>(
+    [QueryKeys.agents, 'all', params],
+    () => dataService.getAllAgents(params),
+    {
+      staleTime: 1000 * 60, // 1 minute stale time
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: false,
+      refetchOnMount: false,
+      retry: false,
+      keepPreviousData: true,
+      ...config,
+      enabled: config?.enabled !== undefined ? config.enabled && enabled : enabled,
+    },
+  );
+};
+
+/**
+ * Hook for getting agents by category with pagination
+ */
+export const useGetAgentsByCategoryQuery = <TData = t.AgentListResponse>(
+  params: { category: string; page?: number; limit?: number },
+  config?: UseQueryOptions<t.AgentListResponse, unknown, TData>,
+): QueryObserverResult<TData> => {
+  const queryClient = useQueryClient();
+  const endpointsConfig = queryClient.getQueryData<t.TEndpointsConfig>([QueryKeys.endpoints]);
+
+  const enabled = !!endpointsConfig?.[EModelEndpoint.agents];
+  return useQuery<t.AgentListResponse, unknown, TData>(
+    [QueryKeys.agents, 'category', params],
+    () => dataService.getAgentsByCategory(params),
+    {
+      staleTime: 1000 * 60, // 1 minute stale time
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: false,
+      refetchOnMount: false,
+      retry: false,
+      keepPreviousData: true,
+      ...config,
+      enabled: config?.enabled !== undefined ? config.enabled && enabled : enabled,
+    },
+  );
+};
+
+/**
+ * Hook for searching agents with pagination and filtering
+ */
+export const useSearchAgentsQuery = <TData = t.AgentListResponse>(
+  params: { q: string; category?: string; page?: number; limit?: number },
+  config?: UseQueryOptions<t.AgentListResponse, unknown, TData>,
+): QueryObserverResult<TData> => {
+  const queryClient = useQueryClient();
+  const endpointsConfig = queryClient.getQueryData<t.TEndpointsConfig>([QueryKeys.endpoints]);
+
+  const enabled = !!endpointsConfig?.[EModelEndpoint.agents] && !!params.q;
+  return useQuery<t.AgentListResponse, unknown, TData>(
+    [QueryKeys.agents, 'search', params],
+    () => dataService.searchAgents(params),
+    {
+      staleTime: 1000 * 60, // 1 minute stale time
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: false,
+      refetchOnMount: false,
+      retry: false,
+      keepPreviousData: true,
+      ...config,
+      enabled: config?.enabled !== undefined ? config.enabled && enabled : enabled,
+    },
+  );
+};
+
+/**
+ * Hook for retrieving full agent details including sensitive configuration (EDIT permission)
+ */
+export const useGetExpandedAgentByIdQuery = (
+  agent_id: string,
+  config?: UseQueryOptions<t.Agent>,
+): QueryObserverResult<t.Agent> => {
+  return useQuery<t.Agent>(
+    [QueryKeys.agent, agent_id, 'expanded'],
+    () =>
+      dataService.getExpandedAgentById({
+        agent_id,
+      }),
+    {
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: false,
+      refetchOnMount: false,
+      retry: false,
+      ...config,
+    },
+  );
+};

client/src/hooks/Agents/__tests__/useAgentCategories.spec.tsx

@@ -0,0 +1,35 @@
+import { renderHook } from '@testing-library/react';
+import useAgentCategories from '../useAgentCategories';
+import { AGENT_CATEGORIES, EMPTY_AGENT_CATEGORY } from '~/constants/agentCategories';
+
+// Mock the useLocalize hook
+jest.mock('~/hooks/useLocalize', () => ({
+  __esModule: true,
+  default: () => (key: string) => {
+    // Simple mock implementation that returns the key as the translation
+    return key === 'com_ui_agent_category_general' ? 'General (Translated)' : key;
+  },
+}));
+
+describe('useAgentCategories', () => {
+  it('should return processed categories with correct structure', () => {
+    const { result } = renderHook(() => useAgentCategories());
+
+    // Check that we have the expected number of categories
+    expect(result.current.categories.length).toBe(AGENT_CATEGORIES.length);
+
+    // Check that the first category has the expected structure
+    const firstCategory = result.current.categories[0];
+    const firstOriginalCategory = AGENT_CATEGORIES[0];
+
+    expect(firstCategory.value).toBe(firstOriginalCategory.value);
+
+    // Check that labels are properly translated
+    expect(firstCategory.label).toBe('General (Translated)');
+    expect(firstCategory.className).toBe('w-full');
+
+    // Check the empty category
+    expect(result.current.emptyCategory.value).toBe(EMPTY_AGENT_CATEGORY.value);
+    expect(result.current.emptyCategory.label).toBeTruthy();
+  });
+});

client/src/hooks/Agents/__tests__/useDynamicAgentQuery.spec.ts

@@ -0,0 +1,360 @@
+import { renderHook } from '@testing-library/react';
+import { useDynamicAgentQuery } from '../useDynamicAgentQuery';
+import {
+  useGetPromotedAgentsQuery,
+  useGetAgentsByCategoryQuery,
+  useSearchAgentsQuery,
+} from '~/data-provider';
+
+// Mock the data provider queries
+jest.mock('~/data-provider', () => ({
+  useGetPromotedAgentsQuery: jest.fn(),
+  useGetAgentsByCategoryQuery: jest.fn(),
+  useSearchAgentsQuery: jest.fn(),
+}));
+
+const mockUseGetPromotedAgentsQuery = useGetPromotedAgentsQuery as jest.MockedFunction<
+  typeof useGetPromotedAgentsQuery
+>;
+const mockUseGetAgentsByCategoryQuery = useGetAgentsByCategoryQuery as jest.MockedFunction<
+  typeof useGetAgentsByCategoryQuery
+>;
+const mockUseSearchAgentsQuery = useSearchAgentsQuery as jest.MockedFunction<
+  typeof useSearchAgentsQuery
+>;
+
+describe('useDynamicAgentQuery', () => {
+  const defaultMockQueryResult = {
+    data: undefined,
+    isLoading: false,
+    error: null,
+    isFetching: false,
+    refetch: jest.fn(),
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    // Set default mock returns
+    mockUseGetPromotedAgentsQuery.mockReturnValue(defaultMockQueryResult as any);
+    mockUseGetAgentsByCategoryQuery.mockReturnValue(defaultMockQueryResult as any);
+    mockUseSearchAgentsQuery.mockReturnValue(defaultMockQueryResult as any);
+  });
+
+  describe('Search Query Type', () => {
+    it('should use search query when searchQuery is provided', () => {
+      const mockSearchResult = {
+        ...defaultMockQueryResult,
+        data: { agents: [], pagination: { hasMore: false } },
+      };
+      mockUseSearchAgentsQuery.mockReturnValue(mockSearchResult as any);
+
+      const { result } = renderHook(() =>
+        useDynamicAgentQuery({
+          category: 'hr',
+          searchQuery: 'test search',
+          page: 1,
+          limit: 6,
+        }),
+      );
+
+      // Should call search query with correct parameters
+      expect(mockUseSearchAgentsQuery).toHaveBeenCalledWith(
+        {
+          q: 'test search',
+          category: 'hr',
+          page: 1,
+          limit: 6,
+        },
+        expect.objectContaining({
+          enabled: true,
+          staleTime: 120000,
+          refetchOnWindowFocus: false,
+          keepPreviousData: true,
+          refetchOnMount: false,
+          refetchOnReconnect: false,
+          retry: 1,
+        }),
+      );
+
+      // Should return search query result
+      expect(result.current.data).toBe(mockSearchResult.data);
+      expect(result.current.queryType).toBe('search');
+    });
+
+    it('should not include category in search when category is "all" or "promoted"', () => {
+      renderHook(() =>
+        useDynamicAgentQuery({
+          category: 'all',
+          searchQuery: 'test search',
+          page: 1,
+          limit: 6,
+        }),
+      );
+
+      expect(mockUseSearchAgentsQuery).toHaveBeenCalledWith(
+        {
+          q: 'test search',
+          page: 1,
+          limit: 6,
+          // No category parameter should be included
+        },
+        expect.any(Object),
+      );
+    });
+  });
+
+  describe('Promoted Query Type', () => {
+    it('should use promoted query when category is "promoted" and no search', () => {
+      const mockPromotedResult = {
+        ...defaultMockQueryResult,
+        data: { agents: [], pagination: { hasMore: false } },
+      };
+      mockUseGetPromotedAgentsQuery.mockReturnValue(mockPromotedResult as any);
+
+      const { result } = renderHook(() =>
+        useDynamicAgentQuery({
+          category: 'promoted',
+          searchQuery: '',
+          page: 2,
+          limit: 8,
+        }),
+      );
+
+      // Should call promoted query with correct parameters (no showAll)
+      expect(mockUseGetPromotedAgentsQuery).toHaveBeenCalledWith(
+        {
+          page: 2,
+          limit: 8,
+        },
+        expect.objectContaining({
+          enabled: true,
+        }),
+      );
+
+      expect(result.current.data).toBe(mockPromotedResult.data);
+      expect(result.current.queryType).toBe('promoted');
+    });
+  });
+
+  describe('All Agents Query Type', () => {
+    it('should use promoted query with showAll when category is "all" and no search', () => {
+      const mockAllResult = {
+        ...defaultMockQueryResult,
+        data: { agents: [], pagination: { hasMore: false } },
+      };
+
+      // Mock the second call to useGetPromotedAgentsQuery (for "all" category)
+      mockUseGetPromotedAgentsQuery
+        .mockReturnValueOnce(defaultMockQueryResult as any) // First call for promoted
+        .mockReturnValueOnce(mockAllResult as any); // Second call for all
+
+      const { result } = renderHook(() =>
+        useDynamicAgentQuery({
+          category: 'all',
+          searchQuery: '',
+          page: 1,
+          limit: 6,
+        }),
+      );
+
+      // Should call promoted query with showAll parameter
+      expect(mockUseGetPromotedAgentsQuery).toHaveBeenCalledWith(
+        {
+          page: 1,
+          limit: 6,
+          showAll: 'true',
+        },
+        expect.objectContaining({
+          enabled: true,
+        }),
+      );
+
+      expect(result.current.queryType).toBe('all');
+    });
+  });
+
+  describe('Category Query Type', () => {
+    it('should use category query for specific categories', () => {
+      const mockCategoryResult = {
+        ...defaultMockQueryResult,
+        data: { agents: [], pagination: { hasMore: false } },
+      };
+      mockUseGetAgentsByCategoryQuery.mockReturnValue(mockCategoryResult as any);
+
+      const { result } = renderHook(() =>
+        useDynamicAgentQuery({
+          category: 'finance',
+          searchQuery: '',
+          page: 3,
+          limit: 10,
+        }),
+      );
+
+      expect(mockUseGetAgentsByCategoryQuery).toHaveBeenCalledWith(
+        {
+          category: 'finance',
+          page: 3,
+          limit: 10,
+        },
+        expect.objectContaining({
+          enabled: true,
+        }),
+      );
+
+      expect(result.current.data).toBe(mockCategoryResult.data);
+      expect(result.current.queryType).toBe('category');
+    });
+  });
+
+  describe('Query Configuration', () => {
+    it('should apply correct query configuration to all queries', () => {
+      renderHook(() =>
+        useDynamicAgentQuery({
+          category: 'hr',
+          searchQuery: '',
+          page: 1,
+          limit: 6,
+        }),
+      );
+
+      const expectedConfig = expect.objectContaining({
+        staleTime: 120000,
+        refetchOnWindowFocus: false,
+        refetchOnReconnect: false,
+        refetchOnMount: false,
+        retry: 1,
+        keepPreviousData: true,
+      });
+
+      expect(mockUseGetAgentsByCategoryQuery).toHaveBeenCalledWith(
+        expect.any(Object),
+        expectedConfig,
+      );
+    });
+
+    it('should enable only the correct query based on query type', () => {
+      renderHook(() =>
+        useDynamicAgentQuery({
+          category: 'hr',
+          searchQuery: '',
+          page: 1,
+          limit: 6,
+        }),
+      );
+
+      // Category query should be enabled
+      expect(mockUseGetAgentsByCategoryQuery).toHaveBeenCalledWith(
+        expect.any(Object),
+        expect.objectContaining({ enabled: true }),
+      );
+
+      // Other queries should be disabled
+      expect(mockUseSearchAgentsQuery).toHaveBeenCalledWith(
+        expect.any(Object),
+        expect.objectContaining({ enabled: false }),
+      );
+
+      expect(mockUseGetPromotedAgentsQuery).toHaveBeenCalledWith(
+        expect.any(Object),
+        expect.objectContaining({ enabled: false }),
+      );
+    });
+  });
+
+  describe('Default Parameters', () => {
+    it('should use default page and limit when not provided', () => {
+      renderHook(() =>
+        useDynamicAgentQuery({
+          category: 'general',
+          searchQuery: '',
+        }),
+      );
+
+      expect(mockUseGetAgentsByCategoryQuery).toHaveBeenCalledWith(
+        {
+          category: 'general',
+          page: 1,
+          limit: 6,
+        },
+        expect.any(Object),
+      );
+    });
+  });
+
+  describe('Return Values', () => {
+    it('should return all necessary query properties', () => {
+      const mockResult = {
+        data: { agents: [{ id: '1', name: 'Test Agent' }] },
+        isLoading: true,
+        error: null,
+        isFetching: false,
+        refetch: jest.fn(),
+      };
+
+      mockUseGetAgentsByCategoryQuery.mockReturnValue(mockResult as any);
+
+      const { result } = renderHook(() =>
+        useDynamicAgentQuery({
+          category: 'it',
+          searchQuery: '',
+          page: 1,
+          limit: 6,
+        }),
+      );
+
+      expect(result.current).toEqual({
+        data: mockResult.data,
+        isLoading: mockResult.isLoading,
+        error: mockResult.error,
+        isFetching: mockResult.isFetching,
+        refetch: mockResult.refetch,
+        queryType: 'category',
+      });
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle empty search query as no search', () => {
+      renderHook(() =>
+        useDynamicAgentQuery({
+          category: 'promoted',
+          searchQuery: '', // Empty string should not trigger search
+          page: 1,
+          limit: 6,
+        }),
+      );
+
+      // Should use promoted query, not search query
+      expect(mockUseGetPromotedAgentsQuery).toHaveBeenCalledWith(
+        expect.any(Object),
+        expect.objectContaining({ enabled: true }),
+      );
+
+      expect(mockUseSearchAgentsQuery).toHaveBeenCalledWith(
+        expect.any(Object),
+        expect.objectContaining({ enabled: false }),
+      );
+    });
+
+    it('should fallback to promoted query for unknown query types', () => {
+      const mockPromotedResult = {
+        ...defaultMockQueryResult,
+        data: { agents: [] },
+      };
+      mockUseGetPromotedAgentsQuery.mockReturnValue(mockPromotedResult as any);
+
+      const { result } = renderHook(() =>
+        useDynamicAgentQuery({
+          category: 'unknown-category',
+          searchQuery: '',
+          page: 1,
+          limit: 6,
+        }),
+      );
+
+      // Should determine this as 'category' type and use category query
+      expect(result.current.queryType).toBe('category');
+    });
+  });
+});

client/src/hooks/Agents/index.ts

@@ -1,4 +1,7 @@
 export { default as useAgentsMap } from './useAgentsMap';
 export { default as useSelectAgent } from './useSelectAgent';
+export { default as useAgentCategories } from './useAgentCategories';
+export { useDynamicAgentQuery } from './useDynamicAgentQuery';
+export type { ProcessedAgentCategory } from './useAgentCategories';
 export { default as useAgentCapabilities } from './useAgentCapabilities';
 export { default as useGetAgentsConfig } from './useGetAgentsConfig';

client/src/hooks/Agents/useAgentCategories.tsx

@@ -0,0 +1,57 @@
+import { useMemo } from 'react';
+
+import useLocalize from '~/hooks/useLocalize';
+import { useGetAgentCategoriesQuery } from '~/data-provider';
+import { EMPTY_AGENT_CATEGORY } from '~/constants/agentCategories';
+
+// This interface matches the structure used by the ControlCombobox component
+export interface ProcessedAgentCategory {
+  label: string; // Translated label
+  value: string; // Category value
+  className?: string;
+}
+
+/**
+ * Custom hook that provides processed and translated agent categories from API
+ *
+ * @returns Object containing categories, emptyCategory, and loading state
+ */
+const useAgentCategories = () => {
+  const localize = useLocalize();
+
+  // Fetch categories from API
+  const categoriesQuery = useGetAgentCategoriesQuery({
+    staleTime: 1000 * 60 * 15, // 15 minutes
+  });
+
+  const categories = useMemo((): ProcessedAgentCategory[] => {
+    if (!categoriesQuery.data) return [];
+
+    // Filter out special categories (promoted, all) and convert to form format
+    return categoriesQuery.data
+      .filter((category) => category.value !== 'promoted' && category.value !== 'all')
+      .map((category) => ({
+        label: category.label || category.value,
+        value: category.value,
+        className: 'w-full',
+      }));
+  }, [categoriesQuery.data]);
+
+  const emptyCategory = useMemo(
+    (): ProcessedAgentCategory => ({
+      label: localize(EMPTY_AGENT_CATEGORY.label),
+      value: EMPTY_AGENT_CATEGORY.value,
+      className: 'w-full',
+    }),
+    [localize],
+  );
+
+  return {
+    categories,
+    emptyCategory,
+    isLoading: categoriesQuery.isLoading,
+    error: categoriesQuery.error,
+  };
+};
+
+export default useAgentCategories;

client/src/hooks/Agents/useDynamicAgentQuery.ts

@@ -0,0 +1,112 @@
+import { useMemo } from 'react';
+
+import type { UseQueryOptions } from '@tanstack/react-query';
+import type t from 'librechat-data-provider';
+
+import {
+  useGetPromotedAgentsQuery,
+  useGetAgentsByCategoryQuery,
+  useSearchAgentsQuery,
+} from '~/data-provider';
+
+interface UseDynamicAgentQueryParams {
+  category: string;
+  searchQuery: string;
+  page?: number;
+  limit?: number;
+}
+
+/**
+ * Single dynamic query hook that replaces 4 separate conditional queries
+ * Determines the appropriate query based on category and search state
+ */
+export const useDynamicAgentQuery = ({
+  category,
+  searchQuery,
+  page = 1,
+  limit = 6,
+}: UseDynamicAgentQueryParams) => {
+  // Shared query configuration optimized to prevent unnecessary loading states
+  const queryConfig: UseQueryOptions<t.AgentListResponse> = useMemo(
+    () => ({
+      staleTime: 1000 * 60 * 2, // 2 minutes - agents don't change frequently
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: false,
+      refetchOnMount: false,
+      retry: 1,
+      keepPreviousData: true,
+      // Removed placeholderData due to TypeScript compatibility - keepPreviousData is sufficient
+    }),
+    [],
+  );
+
+  // Determine query type and parameters based on current state
+  const queryType = useMemo(() => {
+    if (searchQuery) return 'search';
+    if (category === 'promoted') return 'promoted';
+    if (category === 'all') return 'all';
+    return 'category';
+  }, [category, searchQuery]);
+
+  // Search query - when user is searching
+  const searchQuery_result = useSearchAgentsQuery(
+    {
+      q: searchQuery,
+      ...(category !== 'all' && category !== 'promoted' && { category }),
+      page,
+      limit,
+    },
+    {
+      ...queryConfig,
+      enabled: queryType === 'search',
+    },
+  );
+
+  // Promoted agents query - for "Top Picks" tab
+  const promotedQuery = useGetPromotedAgentsQuery(
+    { page, limit },
+    {
+      ...queryConfig,
+      enabled: queryType === 'promoted',
+    },
+  );
+
+  // All agents query - for "All" tab (promoted endpoint with showAll parameter)
+  const allAgentsQuery = useGetPromotedAgentsQuery(
+    { page, limit, showAll: 'true' },
+    {
+      ...queryConfig,
+      enabled: queryType === 'all',
+    },
+  );
+
+  // Category-specific query - for individual categories
+  const categoryQuery = useGetAgentsByCategoryQuery(
+    { category, page, limit },
+    {
+      ...queryConfig,
+      enabled: queryType === 'category',
+    },
+  );
+
+  // Return the active query based on current state
+  const activeQuery = useMemo(() => {
+    switch (queryType) {
+      case 'search':
+        return searchQuery_result;
+      case 'promoted':
+        return promotedQuery;
+      case 'all':
+        return allAgentsQuery;
+      case 'category':
+        return categoryQuery;
+      default:
+        return promotedQuery; // fallback
+    }
+  }, [queryType, searchQuery_result, promotedQuery, allAgentsQuery, categoryQuery]);
+
+  return {
+    ...activeQuery,
+    queryType, // Expose query type for debugging/logging
+  };
+};

client/src/hooks/Endpoint/useEndpoints.ts

@@ -125,8 +125,7 @@ export const useEndpoints = ({
       if (ep === EModelEndpoint.agents && agents.length > 0) {
         result.models = agents.map((agent) => ({
           name: agent.id,
-          isGlobal:
+          isGlobal: agent.isPublic ?? false,
-            (instanceProjectId != null && agent.projectIds?.includes(instanceProjectId)) ?? false,
         }));
         result.agentNames = agents.reduce((acc, agent) => {
           acc[agent.id] = agent.name || '';

client/src/hooks/Nav/useSideNavLinks.ts

@@ -1,13 +1,13 @@
 import { useMemo } from 'react';
 import { Blocks, MCPIcon, AttachmentIcon } from '@librechat/client';
-import { MessageSquareQuote, ArrowRightToLine, Settings2, Database, Bookmark } from 'lucide-react';
+import { Database, Bookmark, Settings2, ArrowRightToLine, MessageSquareQuote } from 'lucide-react';
 import {
-  isAssistantsEndpoint,
+  Permissions,
-  isAgentsEndpoint,
+  EModelEndpoint,
   PermissionTypes,
   isParamEndpoint,
-  EModelEndpoint,
+  isAgentsEndpoint,
-  Permissions,
+  isAssistantsEndpoint,
 } from 'librechat-data-provider';
 import type { TInterfaceConfig, TEndpointsConfig } from 'librechat-data-provider';
 import type { NavLink } from '~/common';

client/src/hooks/index.ts

@@ -31,3 +31,4 @@ export { default as useDocumentTitle } from './useDocumentTitle';
 export { default as useSpeechToText } from './Input/useSpeechToText';
 export { default as useTextToSpeech } from './Input/useTextToSpeech';
 export { default as useGenerationsByLatest } from './useGenerationsByLatest';
+export { useResourcePermissions } from './useResourcePermissions';

client/src/hooks/useResourcePermissions.ts

@@ -0,0 +1,25 @@
+import {
+  useGetEffectivePermissionsQuery,
+  hasPermissions,
+} from 'librechat-data-provider/react-query';
+
+/**
+ * fetches resource permissions once and returns a function to check any permission
+ * More efficient when checking multiple permissions for the same resource
+ * @param resourceType - Type of resource (e.g., 'agent')
+ * @param resourceId - ID of the resource
+ * @returns Object with hasPermission function and loading state
+ */
+export const useResourcePermissions = (resourceType: string, resourceId: string) => {
+  const { data, isLoading } = useGetEffectivePermissionsQuery(resourceType, resourceId);
+
+  const hasPermission = (requiredPermission: number): boolean => {
+    return data ? hasPermissions(data.permissionBits, requiredPermission) : false;
+  };
+
+  return {
+    hasPermission,
+    isLoading,
+    permissionBits: data?.permissionBits || 0,
+  };
+};

client/src/locales/en/translation.json

@@ -4,7 +4,6 @@
   "com_a11y_ai_composing": "The AI is still composing.",
   "com_a11y_end": "The AI has finished their reply.",
   "com_a11y_start": "The AI has started their reply.",
-  "com_agents_allow_editing": "Allow other users to edit your agent",
   "com_agents_by_librechat": "by LibreChat",
   "com_agents_code_interpreter": "When enabled, allows your agent to leverage the LibreChat Code Interpreter API to run generated code, including file processing, securely. Requires a valid API key.",
   "com_agents_code_interpreter_title": "Code Interpreter API",
@@ -37,7 +36,7 @@
   "com_assistants_actions_info": "Let your Assistant retrieve information or take actions via API's",
   "com_assistants_add_actions": "Add Actions",
   "com_assistants_add_tools": "Add Tools",
-  "com_assistants_allow_sites_you_trust": "Only allow sites you trust.",
+  "com_assistants_allow_sites_you_trust": "Only allow sites you trust..",
   "com_assistants_append_date": "Append Current Date & Time",
   "com_assistants_append_date_tooltip": "When enabled, the current client date and time will be appended to the assistant system instructions.",
   "com_assistants_attempt_info": "Assistant wants to send the following:",
@@ -569,10 +568,8 @@
   "com_ui_agent_deleted": "Successfully deleted agent",
   "com_ui_agent_duplicate_error": "There was an error duplicating the agent",
   "com_ui_agent_duplicated": "Agent duplicated successfully",
-  "com_ui_agent_editing_allowed": "Other users can already edit this agent",
   "com_ui_agent_recursion_limit": "Max Agent Steps",
   "com_ui_agent_recursion_limit_info": "Limits how many steps the agent can take in a run before giving a final response. Default is 25 steps. A step is either an AI API request or a tool usage round. For example, a basic tool interaction takes 3 steps: initial request, tool usage, and follow-up request.",
-  "com_ui_agent_shared_to_all": "something needs to go here. was empty",
   "com_ui_agent_var": "{{0}} agent",
   "com_ui_agent_version": "Version",
   "com_ui_agent_version_active": "Active Version",
@@ -658,6 +655,14 @@
   "com_ui_cancel": "Cancel",
   "com_ui_cancelled": "Cancelled",
   "com_ui_category": "Category",
+  "com_ui_agent_category_selector_aria": "Agent's category selector",
+  "com_ui_agent_category_general": "General",
+  "com_ui_agent_category_hr": "HR",
+  "com_ui_agent_category_rd": "R&D",
+  "com_ui_agent_category_finance": "Finance",
+  "com_ui_agent_category_it": "IT",
+  "com_ui_agent_category_sales": "Sales",
+  "com_ui_agent_category_aftersales": "After Sales",
   "com_ui_chat": "Chat",
   "com_ui_chat_history": "Chat History",
   "com_ui_clear": "Clear",
@@ -688,6 +693,19 @@
   "com_ui_copy_code": "Copy code",
   "com_ui_copy_link": "Copy link",
   "com_ui_copy_to_clipboard": "Copy to clipboard",
+  "com_ui_copy_url_to_clipboard": "Copy URL to clipboard",
+  "com_ui_agent_url_copied": "Agent URL copied to clipboard",
+  "com_ui_search_people_placeholder": "Search for people or groups by name or email",
+  "com_ui_permission_level": "Permission Level",
+  "com_ui_grant_access": "Grant Access",
+  "com_ui_granting": "Granting...",
+  "com_ui_search_users_groups": "Search Users and Groups",
+  "com_ui_search_default_placeholder": "Search by name or email (min 2 chars)",
+  "com_ui_user": "User",
+  "com_ui_group": "Group",
+  "com_ui_search_above_to_add": "Search above to add users or groups",
+  "com_ui_azure_ad": "Entra ID",
+  "com_ui_remove_user": "Remove {{0}}",
   "com_ui_create": "Create",
   "com_ui_create_link": "Create link",
   "com_ui_create_memory": "Create Memory",
@@ -918,7 +936,6 @@
   "com_ui_no_backup_codes": "No backup codes available. Please generate new ones",
   "com_ui_no_bookmarks": "it seems like you have no bookmarks yet. Click on a chat and add a new one",
   "com_ui_no_category": "No category",
-  "com_ui_no_changes": "No changes to update",
   "com_ui_no_data": "something needs to go here. was empty",
   "com_ui_no_personalization_available": "No personalization options are currently available",
   "com_ui_no_read_access": "You don't have permission to view memories",
@@ -1001,6 +1018,7 @@
   "com_ui_scope": "Scope",
   "com_ui_search": "Search",
   "com_ui_seconds": "seconds",
+  "com_ui_search_agent_category": "Search categories...",
   "com_ui_secret_key": "Secret Key",
   "com_ui_select": "Select",
   "com_ui_select_all": "Select All",
@@ -1047,6 +1065,13 @@
   "com_ui_stop": "Stop",
   "com_ui_storage": "Storage",
   "com_ui_submit": "Submit",
+  "com_ui_support_contact": "Support Contact",
+  "com_ui_support_contact_name": "Name",
+  "com_ui_support_contact_name_placeholder": "Support contact name",
+  "com_ui_support_contact_name_min_length": "Name must be at least {{minLength}} characters",
+  "com_ui_support_contact_email": "Email",
+  "com_ui_support_contact_email_placeholder": "support@example.com",
+  "com_ui_support_contact_email_invalid": "Please enter a valid email address",
   "com_ui_teach_or_explain": "Learning",
   "com_ui_temporary": "Temporary Chat",
   "com_ui_terms_and_conditions": "Terms and Conditions",
@@ -1134,5 +1159,91 @@
   "com_ui_x_selected": "{{0}} selected",
   "com_ui_yes": "Yes",
   "com_ui_zoom": "Zoom",
-  "com_user_message": "You"
+  "com_user_message": "You",
+  "com_ui_select_options": "Select options...",
+  "com_ui_no_results_found": "No results found",
+  "com_ui_try_adjusting_search": "Try adjusting your search terms",
+  "com_ui_role_viewer": "Viewer",
+  "com_ui_role_editor": "Editor",
+  "com_ui_role_manager": "Manager",
+  "com_ui_role_owner": "Owner",
+  "com_ui_role_viewer_desc": "Can view and use the agent but cannot modify it",
+  "com_ui_role_editor_desc": "Can view and modify the agent",
+  "com_ui_role_manager_desc": "Can view, modify, and delete the agent",
+  "com_ui_role_owner_desc": "Has full control over the agent including sharing it",
+  "com_ui_permissions_failed_load": "Failed to load permissions. Please try again.",
+  "com_ui_permissions_updated_success": "Permissions updated successfully",
+  "com_ui_permissions_failed_update": "Failed to update permissions. Please try again.",
+  "com_ui_manage_permissions_for": "Manage Permissions for",
+  "com_ui_current_access": "Current Access",
+  "com_ui_no_users_groups_access": "No users or groups have access",
+  "com_ui_shared_with_count": "Shared with {{0}} {{1}}{{2}}",
+  "com_ui_person": "person",
+  "com_ui_people": "people",
+  "com_ui_and_public": " and public",
+  "com_ui_revoke_all": "Revoke All",
+  "com_ui_loading_permissions": "Loading permissions...",
+  "com_ui_user_group_permissions": "User & Group Permissions",
+  "com_ui_no_individual_access": "No individual users or groups have access to this agent",
+  "com_ui_public_access": "Public Access",
+  "com_ui_save_changes": "Save Changes",
+  "com_ui_unsaved_changes": "You have unsaved changes",
+  "com_ui_share_with_everyone": "Share with everyone",
+  "com_ui_make_agent_available_all_users": "Make this agent available to all LibreChat users",
+  "com_ui_public_access_level": "Public access level",
+  "com_ui_at_least_one_owner_required": "At least one owner is required",
+  "com_agents_marketplace": "Agent Marketplace",
+  "com_agents_all": "All Agents",
+  "com_agents_top_picks": "Top Picks",
+  "com_agents_recommended": "Our recommended agents",
+  "com_agents_search_placeholder": "Search agents...",
+  "com_agents_search_aria": "Search for agents",
+  "com_agents_clear_search": "Clear search",
+  "com_agents_see_more": "See more",
+  "com_agents_created_by": "by",
+  "com_agents_contact": "Contact",
+  "com_agents_start_chat": "Start Chat",
+  "com_agents_copy_link": "Copy Link",
+  "com_agents_link_copied": "Link copied",
+  "com_agents_link_copy_failed": "Failed to copy link",
+  "com_agents_more_options": "More options",
+  "com_agents_close": "Close",
+  "com_agents_loading": "Loading...",
+  "com_agents_loading_description": "Loading agent description...",
+  "com_agents_error_loading": "Error loading agents",
+  "com_agents_error_searching": "Error searching agents",
+  "com_agents_error_title": "Something went wrong",
+  "com_agents_error_generic": "We encountered an issue while loading the content.",
+  "com_agents_error_suggestion_generic": "Please try refreshing the page or try again later.",
+  "com_agents_error_network_title": "Connection Problem",
+  "com_agents_error_network_message": "Unable to connect to the server.",
+  "com_agents_error_network_suggestion": "Check your internet connection and try again.",
+  "com_agents_error_not_found_title": "Not Found",
+  "com_agents_error_not_found_message": "The requested content could not be found.",
+  "com_agents_error_not_found_suggestion": "Try browsing other options or go back to the marketplace.",
+  "com_agents_error_invalid_request": "Invalid Request",
+  "com_agents_error_bad_request_message": "The request could not be processed.",
+  "com_agents_error_bad_request_suggestion": "Please check your input and try again.",
+  "com_agents_error_server_title": "Server Error",
+  "com_agents_error_server_message": "The server is temporarily unavailable.",
+  "com_agents_error_server_suggestion": "Please try again in a few moments.",
+  "com_agents_error_search_title": "Search Error",
+  "com_agents_error_category_title": "Category Error",
+  "com_agents_search_no_results": "No agents found for \"{{query}}\"",
+  "com_agents_category_empty": "No agents found in the {{category}} category",
+  "com_agents_error_retry": "Try Again",
+  "com_agents_category_tabs_label": "Agent Categories",
+  "com_agents_category_tab_label": "{{category}} category, {{position}} of {{total}}",
+  "com_agents_search_instructions": "Type to search agents by name or description",
+  "com_agents_grid_announcement": "Showing {{count}} agents in {{category}} category",
+  "com_agents_load_more_label": "Load more agents from {{category}} category",
+  "com_agents_agent_card_label": "{{name}} agent. {{description}}",
+  "com_agents_empty_state_heading": "No agents found",
+  "com_agents_search_empty_heading": "No search results",
+  "com_agents_no_description": "No description available",
+  "com_agents_none_in_category": "No agents found in this category",
+  "com_agents_no_results": "No agents found. Try another search term.",
+  "com_agents_results_for": "Results for '{{query}}'",
+  "com_nav_agents_marketplace": "Agent Marketplace",
+  "com_agents_marketplace_subtitle": "Discover and use powerful AI agents to enhance your workflows and productivity"
 }

client/src/routes/Root.tsx

@@ -2,17 +2,17 @@ import React, { useState, useEffect } from 'react';
 import { Outlet } from 'react-router-dom';
 import type { ContextType } from '~/common';
 import {
-  useAuthContext,
+  useSearchEnabled,
   useAssistantsMap,
+  useAuthContext,
   useAgentsMap,
   useFileMap,
-  useSearchEnabled,
 } from '~/hooks';
 import {
-  AgentsMapContext,
   AssistantsMapContext,
-  FileMapContext,
+  AgentsMapContext,
   SetConvoProvider,
+  FileMapContext,
 } from '~/Providers';
 import { useUserTermsQuery, useGetStartupConfig } from '~/data-provider';
 import { TermsAndConditionsModal } from '~/components/ui';

client/src/routes/index.tsx

@@ -18,6 +18,7 @@ import ShareRoute from './ShareRoute';
 import ChatRoute from './ChatRoute';
 import Search from './Search';
 import Root from './Root';
+import AgentMarketplace from '~/components/SidePanel/Agents/AgentMarketplace';
 
 const AuthLayout = () => (
   <AuthContextProvider>
@@ -105,6 +106,14 @@ export const router = createBrowserRouter([
             path: 'search',
             element: <Search />,
           },
+          {
+            path: 'agents',
+            element: <AgentMarketplace />,
+          },
+          {
+            path: 'agents/:category',
+            element: <AgentMarketplace />,
+          },
         ],
       },
     ],

client/src/utils/__tests__/agents.spec.tsx

@@ -0,0 +1,178 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { getAgentAvatarUrl, renderAgentAvatar, getContactDisplayName } from '../agents';
+import type t from 'librechat-data-provider';
+
+// Mock the Bot icon from lucide-react
+jest.mock('lucide-react', () => ({
+  Bot: ({ className, strokeWidth, ...props }: any) => (
+    <svg data-testid="bot-icon" className={className} data-stroke-width={strokeWidth} {...props}>
+      <title>{/* eslint-disable-line i18next/no-literal-string */}Bot Icon</title>
+    </svg>
+  ),
+}));
+
+describe('Agent Utilities', () => {
+  describe('getAgentAvatarUrl', () => {
+    it('should return null for null agent', () => {
+      expect(getAgentAvatarUrl(null)).toBeNull();
+    });
+
+    it('should return null for undefined agent', () => {
+      expect(getAgentAvatarUrl(undefined)).toBeNull();
+    });
+
+    it('should return null for agent without avatar', () => {
+      const agent = { id: '1', name: 'Test Agent' } as t.Agent;
+      expect(getAgentAvatarUrl(agent)).toBeNull();
+    });
+
+    it('should return string avatar directly', () => {
+      const agent = {
+        id: '1',
+        name: 'Test Agent',
+        avatar: '/path/to/avatar.png',
+      } as t.Agent;
+      expect(getAgentAvatarUrl(agent)).toBe('/path/to/avatar.png');
+    });
+
+    it('should extract filepath from object avatar', () => {
+      const agent = {
+        id: '1',
+        name: 'Test Agent',
+        avatar: { filepath: '/path/to/object-avatar.png' },
+      } as t.Agent;
+      expect(getAgentAvatarUrl(agent)).toBe('/path/to/object-avatar.png');
+    });
+
+    it('should return null for object avatar without filepath', () => {
+      const agent = {
+        id: '1',
+        name: 'Test Agent',
+        avatar: { someOtherProperty: 'value' },
+      } as any;
+      expect(getAgentAvatarUrl(agent)).toBeNull();
+    });
+  });
+
+  describe('renderAgentAvatar', () => {
+    it('should render image when avatar URL exists', () => {
+      const agent = {
+        id: '1',
+        name: 'Test Agent',
+        avatar: '/test-avatar.png',
+      } as t.Agent;
+
+      render(<div>{renderAgentAvatar(agent)}</div>);
+
+      const img = screen.getByAltText('Test Agent avatar');
+      expect(img).toBeInTheDocument();
+      expect(img).toHaveAttribute('src', '/test-avatar.png');
+      expect(img).toHaveClass('rounded-full', 'object-cover', 'shadow-lg');
+    });
+
+    it('should render Bot icon fallback when no avatar', () => {
+      const agent = {
+        id: '1',
+        name: 'Test Agent',
+      } as t.Agent;
+
+      render(<div>{renderAgentAvatar(agent)}</div>);
+
+      const botIcon = screen.getByTestId('bot-icon');
+      expect(botIcon).toBeInTheDocument();
+      expect(botIcon).toHaveAttribute('data-stroke-width', '1.5');
+    });
+
+    it('should apply different size classes', () => {
+      const agent = {
+        id: '1',
+        name: 'Test Agent',
+        avatar: '/test-avatar.png',
+      } as t.Agent;
+
+      const { rerender } = render(<div>{renderAgentAvatar(agent, { size: 'sm' })}</div>);
+      expect(screen.getByAltText('Test Agent avatar')).toHaveClass('h-12', 'w-12');
+
+      rerender(<div>{renderAgentAvatar(agent, { size: 'lg' })}</div>);
+      expect(screen.getByAltText('Test Agent avatar')).toHaveClass('h-20', 'w-20');
+
+      rerender(<div>{renderAgentAvatar(agent, { size: 'xl' })}</div>);
+      expect(screen.getByAltText('Test Agent avatar')).toHaveClass('h-24', 'w-24');
+    });
+
+    it('should apply custom className', () => {
+      const agent = {
+        id: '1',
+        name: 'Test Agent',
+        avatar: '/test-avatar.png',
+      } as t.Agent;
+
+      render(<div>{renderAgentAvatar(agent, { className: 'custom-class' })}</div>);
+
+      const container = screen.getByAltText('Test Agent avatar').parentElement;
+      expect(container).toHaveClass('custom-class');
+    });
+
+    it('should handle showBorder option', () => {
+      const agent = {
+        id: '1',
+        name: 'Test Agent',
+        avatar: '/test-avatar.png',
+      } as t.Agent;
+
+      const { rerender } = render(<div>{renderAgentAvatar(agent, { showBorder: true })}</div>);
+      expect(screen.getByAltText('Test Agent avatar')).toHaveClass('border-2');
+
+      rerender(<div>{renderAgentAvatar(agent, { showBorder: false })}</div>);
+      expect(screen.getByAltText('Test Agent avatar')).not.toHaveClass('border-2');
+    });
+  });
+
+  describe('getContactDisplayName', () => {
+    it('should return null for null agent', () => {
+      expect(getContactDisplayName(null)).toBeNull();
+    });
+
+    it('should return null for undefined agent', () => {
+      expect(getContactDisplayName(undefined)).toBeNull();
+    });
+
+    it('should prioritize support_contact name', () => {
+      const agent = {
+        id: '1',
+        support_contact: { name: 'Support Team', email: 'support@example.com' },
+        authorName: 'John Doe',
+      } as any;
+      expect(getContactDisplayName(agent)).toBe('Support Team');
+    });
+
+    it('should use authorName when support_contact name is missing', () => {
+      const agent = {
+        id: '1',
+        support_contact: { email: 'support@example.com' },
+        authorName: 'John Doe',
+      } as any;
+      expect(getContactDisplayName(agent)).toBe('John Doe');
+    });
+
+    it('should use support_contact email when both name and authorName are missing', () => {
+      const agent = {
+        id: '1',
+        support_contact: { email: 'support@example.com' },
+      } as any;
+      expect(getContactDisplayName(agent)).toBe('support@example.com');
+    });
+
+    it('should return null when no contact info is available', () => {
+      const agent = {
+        id: '1',
+        name: 'Test Agent',
+      } as any;
+      expect(getContactDisplayName(agent)).toBeNull();
+    });
+  });
+
+  // Tests for hardcoded category functions removed - now using database-driven categories
+});

client/src/utils/agents.tsx

@@ -0,0 +1,108 @@
+import React from 'react';
+import { Bot } from 'lucide-react';
+import type t from 'librechat-data-provider';
+
+/**
+ * Extracts the avatar URL from an agent's avatar property
+ * Handles both string and object formats
+ */
+export const getAgentAvatarUrl = (agent: t.Agent | null | undefined): string | null => {
+  if (!agent?.avatar) {
+    return null;
+  }
+
+  if (typeof agent.avatar === 'string') {
+    return agent.avatar;
+  }
+
+  if (agent.avatar && typeof agent.avatar === 'object' && 'filepath' in agent.avatar) {
+    return agent.avatar.filepath;
+  }
+
+  return null;
+};
+
+/**
+ * Renders an agent avatar with fallback to Bot icon
+ * Consistent across all agent displays
+ */
+export const renderAgentAvatar = (
+  agent: t.Agent | null | undefined,
+  options: {
+    size?: 'sm' | 'md' | 'lg' | 'xl';
+    className?: string;
+    showBorder?: boolean;
+  } = {},
+): React.ReactElement => {
+  const { size = 'md', className = '', showBorder = true } = options;
+
+  const avatarUrl = getAgentAvatarUrl(agent);
+
+  // Size mappings for responsive design
+  const sizeClasses = {
+    sm: 'h-12 w-12 sm:h-14 sm:w-14',
+    md: 'h-16 w-16 sm:h-20 sm:w-20 md:h-24 md:w-24',
+    lg: 'h-20 w-20 sm:h-24 sm:w-24 md:h-28 md:w-28',
+    xl: 'h-24 w-24',
+  };
+
+  const iconSizeClasses = {
+    sm: 'h-6 w-6 sm:h-7 sm:w-7',
+    md: 'h-6 w-6 sm:h-8 sm:w-8 md:h-10 md:w-10',
+    lg: 'h-8 w-8 sm:h-10 sm:w-10 md:h-12 md:w-12',
+    xl: 'h-10 w-10',
+  };
+
+  const placeholderSizeClasses = {
+    sm: 'h-10 w-10 sm:h-12 sm:w-12',
+    md: 'h-12 w-12 sm:h-16 sm:w-16 md:h-20 md:w-20',
+    lg: 'h-16 w-16 sm:h-20 sm:w-20 md:h-24 md:w-24',
+    xl: 'h-20 w-20',
+  };
+
+  const borderClasses = showBorder ? 'border-2 border-white dark:border-gray-800' : '';
+
+  if (avatarUrl) {
+    return (
+      <div className={`flex items-center justify-center ${sizeClasses[size]} ${className}`}>
+        <img
+          src={avatarUrl}
+          alt={`${agent?.name || 'Agent'} avatar`}
+          className={`${sizeClasses[size]} rounded-full object-cover shadow-lg ${borderClasses}`}
+          loading="lazy"
+        />
+      </div>
+    );
+  }
+
+  // Fallback placeholder with Bot icon
+  return (
+    <div className={`relative flex items-center justify-center ${sizeClasses[size]} ${className}`}>
+      {/* Subtle minimalistic placeholder */}
+      <div className="absolute inset-0 rounded-full border border-gray-300 bg-gray-200 dark:border-gray-600 dark:bg-gray-700"></div>
+      <div
+        className={`relative flex items-center justify-center rounded-full bg-gray-300 dark:bg-gray-600 ${placeholderSizeClasses[size]}`}
+      >
+        <Bot
+          className={`text-gray-500 dark:text-gray-400 ${iconSizeClasses[size]}`}
+          strokeWidth={1.5}
+        />
+      </div>
+    </div>
+  );
+};
+
+/**
+ * Gets the display name for a contact (prioritizes name over email)
+ */
+export const getContactDisplayName = (agent: t.Agent | null | undefined): string | null => {
+  if (!agent) return null;
+
+  const supportName = (agent as any).support_contact?.name;
+  const supportEmail = (agent as any).support_contact?.email;
+  const authorName = (agent as any).authorName;
+
+  return supportName || authorName || supportEmail || null;
+};
+
+// All hardcoded category constants removed - now using database-driven categories

client/src/utils/forms.tsx

@@ -63,8 +63,7 @@ export const processAgentOption = ({
   fileMap?: Record<string, TFile | undefined>;
   instanceProjectId?: string;
 }): TAgentOption => {
-  const isGlobal =
+  const isGlobal = _agent?.isPublic ?? false;
-    (instanceProjectId != null && _agent?.projectIds?.includes(instanceProjectId)) ?? false;
   const agent: TAgentOption = {
     ...(_agent ?? ({} as Agent)),
     label: _agent?.name ?? '',

client/src/utils/index.ts

@@ -5,6 +5,7 @@ export * from './json';
 export * from './files';
 export * from './latex';
 export * from './forms';
+export * from './agents';
 export * from './drafts';
 export * from './convos';
 export * from './presets';

client/test/setupTests.js

@@ -39,6 +39,21 @@ beforeEach(() => {
   jest.clearAllMocks();
 });
 
+// Mock window.matchMedia for tests
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: jest.fn().mockImplementation((query) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: jest.fn(), // deprecated
+    removeListener: jest.fn(), // deprecated
+    addEventListener: jest.fn(),
+    removeEventListener: jest.fn(),
+    dispatchEvent: jest.fn(),
+  })),
+});
+
 jest.mock('react-i18next', () => {
   const actual = jest.requireActual('react-i18next');
   return {

config/migrate-agent-permissions.js

@@ -0,0 +1,273 @@
+//TODO: needs testing and validation before running in production
+console.log('needs testing and validation before running in production...');
+const path = require('path');
+const { logger } = require('@librechat/data-schemas');
+require('module-alias')({ base: path.resolve(__dirname, '..', 'api') });
+
+const { GLOBAL_PROJECT_NAME } = require('librechat-data-provider').Constants;
+const connect = require('./connect');
+
+const { grantPermission } = require('~/server/services/PermissionService');
+const { getProjectByName } = require('~/models/Project');
+const { findRoleByIdentifier } = require('~/models');
+const { Agent } = require('~/db/models');
+
+async function migrateAgentPermissionsEnhanced({ dryRun = true, batchSize = 100 } = {}) {
+  await connect();
+
+  logger.info('Starting Enhanced Agent Permissions Migration', { dryRun, batchSize });
+
+  // Verify required roles exist
+  const ownerRole = await findRoleByIdentifier('agent_owner');
+  const viewerRole = await findRoleByIdentifier('agent_viewer');
+  const editorRole = await findRoleByIdentifier('agent_editor');
+
+  if (!ownerRole || !viewerRole || !editorRole) {
+    throw new Error('Required roles not found. Run role seeding first.');
+  }
+
+  // Get global project agent IDs (stores agent.id, not agent._id)
+  const globalProject = await getProjectByName(GLOBAL_PROJECT_NAME, ['agentIds']);
+  const globalAgentIds = new Set(globalProject?.agentIds || []);
+
+  logger.info(`Found ${globalAgentIds.size} agents in global project`);
+
+  // Find agents without ACL entries using DocumentDB-compatible approach
+  const agentsToMigrate = await Agent.aggregate([
+    {
+      $lookup: {
+        from: 'aclentries',
+        localField: '_id',
+        foreignField: 'resourceId',
+        as: 'aclEntries',
+      },
+    },
+    {
+      $addFields: {
+        userAclEntries: {
+          $filter: {
+            input: '$aclEntries',
+            as: 'aclEntry',
+            cond: {
+              $and: [
+                { $eq: ['$$aclEntry.resourceType', 'agent'] },
+                { $eq: ['$$aclEntry.principalType', 'user'] },
+              ],
+            },
+          },
+        },
+      },
+    },
+    {
+      $match: {
+        author: { $exists: true, $ne: null },
+        userAclEntries: { $size: 0 },
+      },
+    },
+    {
+      $project: {
+        _id: 1,
+        id: 1,
+        name: 1,
+        author: 1,
+        isCollaborative: 1,
+      },
+    },
+  ]);
+
+  const categories = {
+    globalEditAccess: [], // Global project + collaborative -> Public EDIT
+    globalViewAccess: [], // Global project + not collaborative -> Public VIEW
+    privateAgents: [], // Not in global project -> Private (owner only)
+  };
+
+  agentsToMigrate.forEach((agent) => {
+    const isGlobal = globalAgentIds.has(agent.id);
+    const isCollab = agent.isCollaborative;
+
+    if (isGlobal && isCollab) {
+      categories.globalEditAccess.push(agent);
+    } else if (isGlobal && !isCollab) {
+      categories.globalViewAccess.push(agent);
+    } else {
+      categories.privateAgents.push(agent);
+
+      // Log warning if private agent claims to be collaborative
+      if (isCollab) {
+        logger.warn(
+          `Agent "${agent.name}" (${agent.id}) has isCollaborative=true but is not in global project`,
+        );
+      }
+    }
+  });
+
+  logger.info('Agent categorization:', {
+    globalEditAccess: categories.globalEditAccess.length,
+    globalViewAccess: categories.globalViewAccess.length,
+    privateAgents: categories.privateAgents.length,
+    total: agentsToMigrate.length,
+  });
+
+  if (dryRun) {
+    return {
+      migrated: 0,
+      errors: 0,
+      dryRun: true,
+      summary: {
+        globalEditAccess: categories.globalEditAccess.length,
+        globalViewAccess: categories.globalViewAccess.length,
+        privateAgents: categories.privateAgents.length,
+        total: agentsToMigrate.length,
+      },
+      details: {
+        globalEditAccess: categories.globalEditAccess.map((a) => ({
+          name: a.name,
+          id: a.id,
+          permissions: 'Owner + Public EDIT',
+        })),
+        globalViewAccess: categories.globalViewAccess.map((a) => ({
+          name: a.name,
+          id: a.id,
+          permissions: 'Owner + Public VIEW',
+        })),
+        privateAgents: categories.privateAgents.map((a) => ({
+          name: a.name,
+          id: a.id,
+          permissions: 'Owner only',
+        })),
+      },
+    };
+  }
+
+  const results = {
+    migrated: 0,
+    errors: 0,
+    publicViewGrants: 0,
+    publicEditGrants: 0,
+    ownerGrants: 0,
+  };
+
+  // Process in batches
+  for (let i = 0; i < agentsToMigrate.length; i += batchSize) {
+    const batch = agentsToMigrate.slice(i, i + batchSize);
+
+    logger.info(
+      `Processing batch ${Math.floor(i / batchSize) + 1}/${Math.ceil(agentsToMigrate.length / batchSize)}`,
+    );
+
+    for (const agent of batch) {
+      try {
+        const isGlobal = globalAgentIds.has(agent.id);
+        const isCollab = agent.isCollaborative;
+
+        // Always grant owner permission to author
+        await grantPermission({
+          principalType: 'user',
+          principalId: agent.author,
+          resourceType: 'agent',
+          resourceId: agent._id,
+          accessRoleId: 'agent_owner',
+          grantedBy: agent.author,
+        });
+        results.ownerGrants++;
+
+        // Determine public permissions for global project agents only
+        let publicRoleId = null;
+        let description = 'Private';
+
+        if (isGlobal) {
+          if (isCollab) {
+            // Global project + collaborative = Public EDIT access
+            publicRoleId = 'agent_editor';
+            description = 'Global Edit';
+            results.publicEditGrants++;
+          } else {
+            // Global project + not collaborative = Public VIEW access
+            publicRoleId = 'agent_viewer';
+            description = 'Global View';
+            results.publicViewGrants++;
+          }
+
+          // Grant public permission
+          await grantPermission({
+            principalType: 'public',
+            principalId: null,
+            resourceType: 'agent',
+            resourceId: agent._id,
+            accessRoleId: publicRoleId,
+            grantedBy: agent.author,
+          });
+        }
+
+        results.migrated++;
+        logger.debug(`Migrated agent "${agent.name}" [${description}]`, {
+          agentId: agent.id,
+          author: agent.author,
+          isGlobal,
+          isCollab,
+          publicRole: publicRoleId,
+        });
+      } catch (error) {
+        results.errors++;
+        logger.error(`Failed to migrate agent "${agent.name}"`, {
+          agentId: agent.id,
+          author: agent.author,
+          error: error.message,
+        });
+      }
+    }
+
+    // Brief pause between batches
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  logger.info('Enhanced migration completed', results);
+  return results;
+}
+
+if (require.main === module) {
+  const dryRun = process.argv.includes('--dry-run');
+  const batchSize =
+    parseInt(process.argv.find((arg) => arg.startsWith('--batch-size='))?.split('=')[1]) || 100;
+
+  migrateAgentPermissionsEnhanced({ dryRun, batchSize })
+    .then((result) => {
+      if (dryRun) {
+        console.log('\n=== DRY RUN RESULTS ===');
+        console.log(`Total agents to migrate: ${result.summary.total}`);
+        console.log(`- Global Edit Access: ${result.summary.globalEditAccess} agents`);
+        console.log(`- Global View Access: ${result.summary.globalViewAccess} agents`);
+        console.log(`- Private Agents: ${result.summary.privateAgents} agents`);
+
+        if (result.details.globalEditAccess.length > 0) {
+          console.log('\nGlobal Edit Access agents:');
+          result.details.globalEditAccess.forEach((agent, i) => {
+            console.log(`  ${i + 1}. "${agent.name}" (${agent.id})`);
+          });
+        }
+
+        if (result.details.globalViewAccess.length > 0) {
+          console.log('\nGlobal View Access agents:');
+          result.details.globalViewAccess.forEach((agent, i) => {
+            console.log(`  ${i + 1}. "${agent.name}" (${agent.id})`);
+          });
+        }
+
+        if (result.details.privateAgents.length > 0) {
+          console.log('\nPrivate agents:');
+          result.details.privateAgents.forEach((agent, i) => {
+            console.log(`  ${i + 1}. "${agent.name}" (${agent.id})`);
+          });
+        }
+      } else {
+        console.log('\nMigration Results:', JSON.stringify(result, null, 2));
+      }
+      process.exit(0);
+    })
+    .catch((error) => {
+      console.error('Enhanced migration failed:', error);
+      process.exit(1);
+    });
+}
+
+module.exports = { migrateAgentPermissionsEnhanced };