🪣 fix: Serve Fresh Presigned URLs on Agent List Cache Hits (#11902)

* fix: serve cached presigned URLs on agent list cache hits

  On a cache hit the list endpoint was skipping the S3 refresh and
  returning whatever presigned URL was stored in MongoDB, which could be
  expired if the S3 URL TTL is shorter than the 30-minute cache window.

  refreshListAvatars now collects a urlCache map (agentId -> refreshed
  filepath) alongside its existing stats. The controller stores this map
  in the cache instead of a plain boolean and re-applies it to every
  paginated response, guaranteeing clients always receive a URL that was
  valid as of the last refresh rather than a potentially stale DB value.

* fix: improve avatar refresh cache handling and logging

Updated the avatar refresh logic to validate cached refresh data before proceeding with S3 URL updates. Enhanced logging to exclude sensitive `urlCache` details while still providing relevant statistics. Added error handling for cache invalidation during avatar updates to ensure robustness.

* fix: update avatar refresh logic to clear urlCache on no change

Modified the avatar refresh function to clear the urlCache when no new path is generated, ensuring that stale URLs are not retained. This change improves cache handling and aligns with the updated logic for avatar updates.

* fix: enhance avatar refresh logic to handle legacy cache entries

Updated the avatar refresh logic to accommodate legacy boolean cache entries, ensuring they are treated as cache misses and triggering a refresh. The cache now stores a structured `urlCache` map instead of a boolean, improving cache handling. Added tests to verify correct behavior for cache hits and misses, ensuring clients receive valid URLs based on the latest refresh.

api/server/controllers/agents/v1.js

@@ -530,10 +530,10 @@ const getListAgentsHandler = async (req, res) => {
      */
     const cache = getLogStores(CacheKeys.S3_EXPIRY_INTERVAL);
     const refreshKey = `${userId}:agents_avatar_refresh`;
-    const alreadyChecked = await cache.get(refreshKey);
-    if (alreadyChecked) {
-      logger.debug('[/Agents] S3 avatar refresh already checked, skipping');
-    } else {
+    let cachedRefresh = await cache.get(refreshKey);
+    const isValidCachedRefresh =
+      cachedRefresh != null && typeof cachedRefresh === 'object' && cachedRefresh.urlCache != null;
+    if (!isValidCachedRefresh) {
       try {
         const fullList = await getListAgentsByAccess({
           accessibleIds,
@@ -541,16 +541,19 @@ const getListAgentsHandler = async (req, res) => {
           limit: MAX_AVATAR_REFRESH_AGENTS,
           after: null,
         });
-        await refreshListAvatars({
+        const { urlCache } = await refreshListAvatars({
           agents: fullList?.data ?? [],
           userId,
           refreshS3Url,
           updateAgent,
         });
-        await cache.set(refreshKey, true, Time.THIRTY_MINUTES);
+        cachedRefresh = { urlCache };
+        await cache.set(refreshKey, cachedRefresh, Time.THIRTY_MINUTES);
       } catch (err) {
         logger.error('[/Agents] Error refreshing avatars for full list: %o', err);
       }
+    } else {
+      logger.debug('[/Agents] S3 avatar refresh already checked, skipping');
     }
 
     // Use the new ACL-aware function
@@ -568,11 +571,20 @@ const getListAgentsHandler = async (req, res) => {
 
     const publicSet = new Set(publiclyAccessibleIds.map((oid) => oid.toString()));
 
+    const urlCache = cachedRefresh?.urlCache;
     data.data = agents.map((agent) => {
       try {
         if (agent?._id && publicSet.has(agent._id.toString())) {
           agent.isPublic = true;
         }
+        if (
+          urlCache &&
+          agent?.id &&
+          agent?.avatar?.source === FileSources.s3 &&
+          urlCache[agent.id]
+        ) {
+          agent.avatar = { ...agent.avatar, filepath: urlCache[agent.id] };
+        }
       } catch (e) {
         // Silently ignore mapping errors
         void e;
@@ -658,6 +670,14 @@ const uploadAgentAvatarHandler = async (req, res) => {
     const updatedAgent = await updateAgent({ id: agent_id }, data, {
       updatingUserId: req.user.id,
     });
+
+    try {
+      const avatarCache = getLogStores(CacheKeys.S3_EXPIRY_INTERVAL);
+      await avatarCache.delete(`${req.user.id}:agents_avatar_refresh`);
+    } catch (cacheErr) {
+      logger.error('[/:agent_id/avatar] Error invalidating avatar refresh cache', cacheErr);
+    }
+
     res.status(201).json(updatedAgent);
   } catch (error) {
     const message = 'An error occurred while updating the Agent Avatar';

api/server/controllers/agents/v1.spec.js

@@ -59,6 +59,7 @@ jest.mock('~/models', () => ({
 const mockCache = {
   get: jest.fn(),
   set: jest.fn(),
+  delete: jest.fn(),
 };
 jest.mock('~/cache', () => ({
   getLogStores: jest.fn(() => mockCache),
@@ -1309,7 +1310,7 @@ describe('Agent Controllers - Mass Assignment Protection', () => {
     });
 
     test('should skip avatar refresh if cache hit', async () => {
-      mockCache.get.mockResolvedValue(true);
+      mockCache.get.mockResolvedValue({ urlCache: {} });
       findAccessibleResources.mockResolvedValue([agentWithS3Avatar._id]);
       findPubliclyAccessibleResources.mockResolvedValue([]);
 
@@ -1348,8 +1349,12 @@ describe('Agent Controllers - Mass Assignment Protection', () => {
       // Verify S3 URL was refreshed
       expect(refreshS3Url).toHaveBeenCalled();
 
-      // Verify cache was set
-      expect(mockCache.set).toHaveBeenCalled();
+      // Verify cache was set with urlCache map, not a plain boolean
+      expect(mockCache.set).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({ urlCache: expect.any(Object) }),
+        expect.any(Number),
+      );
 
       // Verify response was returned
       expect(mockRes.json).toHaveBeenCalled();
@@ -1563,5 +1568,83 @@ describe('Agent Controllers - Mass Assignment Protection', () => {
       // Verify that the handler completed successfully
       expect(mockRes.json).toHaveBeenCalled();
     });
+
+    test('should treat legacy boolean cache entry as a miss and run refresh', async () => {
+      // Simulate a cache entry written by the pre-fix code
+      mockCache.get.mockResolvedValue(true);
+      findAccessibleResources.mockResolvedValue([agentWithS3Avatar._id]);
+      findPubliclyAccessibleResources.mockResolvedValue([]);
+      refreshS3Url.mockResolvedValue('new-s3-path.jpg');
+
+      const mockReq = {
+        user: { id: userA.toString(), role: 'USER' },
+        query: {},
+      };
+      const mockRes = {
+        status: jest.fn().mockReturnThis(),
+        json: jest.fn().mockReturnThis(),
+      };
+
+      await getListAgentsHandler(mockReq, mockRes);
+
+      // Boolean true fails the shape guard, so refresh must run
+      expect(refreshS3Url).toHaveBeenCalled();
+      // Cache is overwritten with the proper format
+      expect(mockCache.set).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({ urlCache: expect.any(Object) }),
+        expect.any(Number),
+      );
+    });
+
+    test('should apply cached urlCache filepath to paginated response on cache hit', async () => {
+      const agentId = agentWithS3Avatar.id;
+      const cachedUrl = 'cached-presigned-url.jpg';
+
+      mockCache.get.mockResolvedValue({ urlCache: { [agentId]: cachedUrl } });
+      findAccessibleResources.mockResolvedValue([agentWithS3Avatar._id]);
+      findPubliclyAccessibleResources.mockResolvedValue([]);
+
+      const mockReq = {
+        user: { id: userA.toString(), role: 'USER' },
+        query: {},
+      };
+      const mockRes = {
+        status: jest.fn().mockReturnThis(),
+        json: jest.fn().mockReturnThis(),
+      };
+
+      await getListAgentsHandler(mockReq, mockRes);
+
+      expect(refreshS3Url).not.toHaveBeenCalled();
+
+      const responseData = mockRes.json.mock.calls[0][0];
+      const agent = responseData.data.find((a) => a.id === agentId);
+      // Cached URL is served, not the stale DB value 'old-s3-path.jpg'
+      expect(agent.avatar.filepath).toBe(cachedUrl);
+    });
+
+    test('should preserve DB filepath for agents absent from urlCache on cache hit', async () => {
+      mockCache.get.mockResolvedValue({ urlCache: {} });
+      findAccessibleResources.mockResolvedValue([agentWithS3Avatar._id]);
+      findPubliclyAccessibleResources.mockResolvedValue([]);
+
+      const mockReq = {
+        user: { id: userA.toString(), role: 'USER' },
+        query: {},
+      };
+      const mockRes = {
+        status: jest.fn().mockReturnThis(),
+        json: jest.fn().mockReturnThis(),
+      };
+
+      await getListAgentsHandler(mockReq, mockRes);
+
+      expect(refreshS3Url).not.toHaveBeenCalled();
+
+      const responseData = mockRes.json.mock.calls[0][0];
+      const agent = responseData.data.find((a) => a.id === agentWithS3Avatar.id);
+      expect(agent.avatar.filepath).toBe('old-s3-path.jpg');
+    });
   });
 });