🪣 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.

packages/api/src/agents/avatars.spec.ts

@@ -7,6 +7,16 @@ import {
   refreshListAvatars,
 } from './avatars';
 
+jest.mock('@librechat/data-schemas', () => ({
+  logger: {
+    debug: jest.fn(),
+    info: jest.fn(),
+    error: jest.fn(),
+  },
+}));
+
+import { logger } from '@librechat/data-schemas';
+
 describe('refreshListAvatars', () => {
   let mockRefreshS3Url: jest.MockedFunction<RefreshS3UrlFn>;
   let mockUpdateAgent: jest.MockedFunction<UpdateAgentFn>;
@@ -15,6 +25,7 @@ describe('refreshListAvatars', () => {
   beforeEach(() => {
     mockRefreshS3Url = jest.fn();
     mockUpdateAgent = jest.fn();
+    jest.clearAllMocks();
   });
 
   const createAgent = (overrides: Partial<Agent> = {}): Agent => ({
@@ -44,6 +55,7 @@ describe('refreshListAvatars', () => {
     });
 
     expect(stats.updated).toBe(0);
+    expect(stats.urlCache).toEqual({});
     expect(mockRefreshS3Url).not.toHaveBeenCalled();
     expect(mockUpdateAgent).not.toHaveBeenCalled();
   });
@@ -62,6 +74,7 @@ describe('refreshListAvatars', () => {
 
     expect(stats.not_s3).toBe(1);
     expect(stats.updated).toBe(0);
+    expect(stats.urlCache).toEqual({});
     expect(mockRefreshS3Url).not.toHaveBeenCalled();
   });
 
@@ -109,6 +122,7 @@ describe('refreshListAvatars', () => {
     });
 
     expect(stats.updated).toBe(1);
+    expect(stats.urlCache).toEqual({ agent1: 'new-path.jpg' });
     expect(mockRefreshS3Url).toHaveBeenCalledWith(agent.avatar);
     expect(mockUpdateAgent).toHaveBeenCalledWith(
       { id: 'agent1' },
@@ -130,6 +144,7 @@ describe('refreshListAvatars', () => {
 
     expect(stats.no_change).toBe(1);
     expect(stats.updated).toBe(0);
+    expect(stats.urlCache).toEqual({});
     expect(mockUpdateAgent).not.toHaveBeenCalled();
   });
 
@@ -146,6 +161,7 @@ describe('refreshListAvatars', () => {
 
     expect(stats.s3_error).toBe(1);
     expect(stats.updated).toBe(0);
+    expect(stats.urlCache).toEqual({});
   });
 
   it('should handle database persist errors gracefully', async () => {
@@ -162,6 +178,7 @@ describe('refreshListAvatars', () => {
 
     expect(stats.persist_error).toBe(1);
     expect(stats.updated).toBe(0);
+    expect(stats.urlCache).toEqual({ agent1: 'new-path.jpg' });
   });
 
   it('should process agents in batches', async () => {
@@ -186,10 +203,49 @@ describe('refreshListAvatars', () => {
     });
 
     expect(stats.updated).toBe(25);
+    expect(Object.keys(stats.urlCache)).toHaveLength(25);
     expect(mockRefreshS3Url).toHaveBeenCalledTimes(25);
     expect(mockUpdateAgent).toHaveBeenCalledTimes(25);
   });
 
+  it('should not populate urlCache when refreshS3Url resolves with falsy', async () => {
+    const agent = createAgent();
+    mockRefreshS3Url.mockResolvedValue(undefined);
+
+    const stats = await refreshListAvatars({
+      agents: [agent],
+      userId,
+      refreshS3Url: mockRefreshS3Url,
+      updateAgent: mockUpdateAgent,
+    });
+
+    expect(stats.no_change).toBe(1);
+    expect(stats.urlCache).toEqual({});
+    expect(mockUpdateAgent).not.toHaveBeenCalled();
+  });
+
+  it('should redact urlCache from log output', async () => {
+    const agent = createAgent();
+    mockRefreshS3Url.mockResolvedValue('new-path.jpg');
+    mockUpdateAgent.mockResolvedValue({});
+
+    await refreshListAvatars({
+      agents: [agent],
+      userId,
+      refreshS3Url: mockRefreshS3Url,
+      updateAgent: mockUpdateAgent,
+    });
+
+    const loggerInfo = logger.info as jest.Mock;
+    const summaryCall = loggerInfo.mock.calls.find(([msg]) =>
+      msg.includes('Avatar refresh summary'),
+    );
+    expect(summaryCall).toBeDefined();
+    const loggedPayload = summaryCall[1];
+    expect(loggedPayload).toHaveProperty('urlCacheSize', 1);
+    expect(loggedPayload).not.toHaveProperty('urlCache');
+  });
+
   it('should track mixed statistics correctly', async () => {
     const agents = [
       createAgent({ id: 'agent1' }),
@@ -214,6 +270,7 @@ describe('refreshListAvatars', () => {
     expect(stats.updated).toBe(2); // agent1 and agent2 (other user's agent now refreshed)
     expect(stats.not_s3).toBe(1); // agent3
     expect(stats.no_id).toBe(1); // agent with empty id
+    expect(stats.urlCache).toEqual({ agent1: 'new-path.jpg', agent2: 'new-path.jpg' });
   });
 });
 

packages/api/src/agents/avatars.ts

@@ -29,6 +29,8 @@ export type RefreshStats = {
   no_change: number;
   s3_error: number;
   persist_error: number;
+  /** Maps agentId to the latest valid presigned filepath for re-application on cache hits */
+  urlCache: Record<string, string>;
 };
 
 /**
@@ -55,6 +57,7 @@ export const refreshListAvatars = async ({
     no_change: 0,
     s3_error: 0,
     persist_error: 0,
+    urlCache: {},
   };
 
   if (!agents?.length) {
@@ -86,28 +89,23 @@ export const refreshListAvatars = async ({
           logger.debug('[refreshListAvatars] Refreshing S3 avatar for agent: %s', agent._id);
           const newPath = await refreshS3Url(agent.avatar);
 
-          if (newPath && newPath !== agent.avatar.filepath) {
-            try {
-              await updateAgent(
-                { id: agent.id },
-                {
-                  avatar: {
-                    filepath: newPath,
-                    source: agent.avatar.source,
-                  },
-                },
-                {
-                  updatingUserId: userId,
-                  skipVersioning: true,
-                },
-              );
-              stats.updated++;
-            } catch (persistErr) {
-              logger.error('[refreshListAvatars] Avatar refresh persist error: %o', persistErr);
-              stats.persist_error++;
-            }
-          } else {
+          if (!newPath || newPath === agent.avatar.filepath) {
             stats.no_change++;
+            return;
+          }
+
+          stats.urlCache[agent.id] = newPath;
+
+          try {
+            await updateAgent(
+              { id: agent.id },
+              { avatar: { filepath: newPath, source: agent.avatar.source } },
+              { updatingUserId: userId, skipVersioning: true },
+            );
+            stats.updated++;
+          } catch (persistErr) {
+            logger.error('[refreshListAvatars] Avatar refresh persist error: %o', persistErr);
+            stats.persist_error++;
           }
         } catch (err) {
           logger.error('[refreshListAvatars] S3 avatar refresh error: %o', err);
@@ -117,6 +115,10 @@ export const refreshListAvatars = async ({
     );
   }
 
-  logger.info('[refreshListAvatars] Avatar refresh summary: %o', stats);
+  const { urlCache: _urlCache, ...loggableStats } = stats;
+  logger.info('[refreshListAvatars] Avatar refresh summary: %o', {
+    ...loggableStats,
+    urlCacheSize: Object.keys(_urlCache).length,
+  });
   return stats;
 };