refactor: Assemble the System Prompt from Structured, Kind-Classified Parts

api/app/clients/BaseClient.js

@@ -33,6 +33,7 @@ const {
   needsRetentionConversation,
   getConversationWriteContext,
   savePrivateTextMessage,
+  getTurnUserMessageCreatedAt,
   stampPrivateTextMessage,
   deferPrivateTextStart,
   requirePrivateTextPersistence,
@@ -1372,6 +1373,8 @@ class BaseClient {
       req.resolvedConversation = await db.getConvo(req.user.id, message.conversationId);
     }
     const reqCtx = getConversationWriteContext(req);
+    const createdAtOnInsert =
+      message.isCreatedByUser === true ? getTurnUserMessageCreatedAt(req) : undefined;
     const savedMessage = await savePrivateTextMessage(
       db.saveMessage,
       req,
@@ -1383,7 +1386,10 @@ class BaseClient {
         user,
         ...(hasAddedConvo && { addedConvo: true }),
       },
-      { context: 'api/app/clients/BaseClient.js - saveMessageToDatabase #saveMessage' },
+      {
+        context: 'api/app/clients/BaseClient.js - saveMessageToDatabase #saveMessage',
+        ...(createdAtOnInsert && { createdAtOnInsert }),
+      },
     );
 
     /** Only a reply that is actually in the message history may light an indicator: a write

api/app/clients/specs/BaseClient.test.js

@@ -2595,6 +2595,53 @@ describe('BaseClient', () => {
       expect(getConvo).not.toHaveBeenCalled();
     });
 
+    test('saveMessageToDatabase inserts the turn user message at the turn start time', async () => {
+      const user = { id: 'user-id' };
+      const turnStartedAt = Date.parse('2026-03-10T09:00:00.000Z');
+      const req = {
+        user,
+        body: {},
+        turnStartedAt,
+        config: { endpoints: { agents: { promptCache: { stableContext: true } } } },
+      };
+      saveMessage.mockReset().mockResolvedValue({ messageId: 'msg-1' });
+      saveConvo.mockReset().mockResolvedValue({ conversationId: 'convo-id' });
+
+      TestClient = initializeFakeClient(apiKey, { ...options, endpoint: 'openai', req }, []);
+
+      await TestClient.saveMessageToDatabase(
+        { messageId: 'msg-1', conversationId: 'convo-id', isCreatedByUser: true, text: 'hi' },
+        { endpoint: 'openai' },
+        user,
+      );
+      expect(saveMessage).toHaveBeenLastCalledWith(
+        expect.any(Object),
+        expect.any(Object),
+        expect.objectContaining({ createdAtOnInsert: new Date(turnStartedAt) }),
+      );
+
+      await TestClient.saveMessageToDatabase(
+        { messageId: 'response-1', conversationId: 'convo-id', text: 'reply' },
+        { endpoint: 'openai' },
+        user,
+      );
+      expect(saveMessage.mock.lastCall[2]).not.toHaveProperty('createdAtOnInsert');
+
+      TestClient = initializeFakeClient(
+        apiKey,
+        { ...options, endpoint: 'openai', req: { ...req, config: {} } },
+        [],
+      );
+      await TestClient.saveMessageToDatabase(
+        { messageId: 'msg-2', conversationId: 'convo-id', isCreatedByUser: true, text: 'hi' },
+        { endpoint: 'openai' },
+        user,
+      );
+      expect(saveMessage.mock.lastCall[2]).not.toHaveProperty('createdAtOnInsert');
+      saveMessage.mockReset();
+      saveConvo.mockReset();
+    });
+
     test('userMessagePromise is awaited before saving response message', async () => {
       // Mock the saveMessageToDatabase method
       TestClient.saveMessageToDatabase = jest.fn().mockImplementation(() => {

api/app/clients/tools/util/handleTools.js

@@ -27,6 +27,7 @@ const {
   ASK_USER_QUESTION_TOOL_NAME,
   resolveWebSearchSSRFAgents,
   buildWebSearchDynamicContext,
+  isStableContextEnabled,
   codeExecutionAuthHeaders,
   getCodeFileLocation,
   withRequestCodeInputs,
@@ -406,8 +407,14 @@ const loadTools = async ({
         webSearch?.allowedAddresses,
       );
       requestedTools[tool] = async () => {
-        toolContextMap[tool] = buildWebSearchContext();
-        dynamicToolContextMap[tool] = buildWebSearchDynamicContext(options.req?.turnStartedAt);
+        const stableContext = isStableContextEnabled(options.req?.config);
+        toolContextMap[tool] = buildWebSearchContext(stableContext);
+        dynamicToolContextMap[tool] = buildWebSearchDynamicContext({
+          turnStartedAt: options.req?.turnStartedAt,
+          conversationStartedAt: options.req?.conversationCreatedAt,
+          timezone: options.req?.body?.timezone,
+          stableContext,
+        });
         return createSearchTool({
           ...result.authResult,
           httpAgent,

api/server/controllers/agents/__tests__/openai.spec.js

@@ -825,7 +825,9 @@ describe('OpenAIChatCompletionController', () => {
     expect(mockApplyContextToAgent).toHaveBeenCalledWith(
       expect.objectContaining({
         agent,
-        sharedRunContext: expect.stringContaining(memoryInstructions),
+        runContext: expect.objectContaining({
+          memory: expect.stringContaining(memoryInstructions),
+        }),
       }),
     );
     expect(require('~/models').getFormattedMemories).toHaveBeenCalledWith({

api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js

@@ -257,6 +257,8 @@ jest.mock('@librechat/data-schemas', () => ({
 
 jest.mock('@librechat/api', () => ({
   savePrivateTextMessage: (save, _req, ...args) => save(...args),
+  getTurnUserMessageCreatedAt: (...args) =>
+    jest.requireActual('@librechat/api').getTurnUserMessageCreatedAt(...args),
   savePrivateTextErrorTurn: (...args) =>
     jest.requireActual('@librechat/api').savePrivateTextErrorTurn(...args),
   stampPreliminaryPrivateTextMessage: (_req, message) => message,
@@ -3302,7 +3304,7 @@ describe('ResumableAgentController resume metadata', () => {
         conversationId: 'conversation-123',
         endpointOption: { endpoint: 'agents', modelOptions: { model: 'gpt-4.1' } },
       },
-      config: {},
+      config: { endpoints: { agents: { promptCache: { stableContext: true } } } },
     };
 
     await AgentController(
@@ -3317,7 +3319,10 @@ describe('ResumableAgentController resume metadata', () => {
     expect(mockSaveMessage).toHaveBeenCalledWith(
       expect.objectContaining({ userId: 'user-123' }),
       userMessage,
-      expect.objectContaining({ context: expect.stringContaining('resumable user message') }),
+      expect.objectContaining({
+        context: expect.stringContaining('resumable user message'),
+        createdAtOnInsert: new Date(req.turnStartedAt),
+      }),
     );
     expect(mockGenerationJobManager.steering.consumeRecovered).not.toHaveBeenCalled();
     expect(mockGenerationJobManager.publishTerminalClaim).toHaveBeenCalledWith(
@@ -3371,7 +3376,7 @@ describe('ResumableAgentController resume metadata', () => {
         conversationId: 'conversation-123',
         endpointOption: { endpoint: 'agents', modelOptions: { model: 'gpt-4.1' } },
       },
-      config: {},
+      config: { endpoints: { agents: { promptCache: { stableContext: true } } } },
     };
 
     await AgentController(
@@ -3387,7 +3392,10 @@ describe('ResumableAgentController resume metadata', () => {
     expect(mockSaveMessage).toHaveBeenCalledWith(
       expect.objectContaining({ userId: 'user-123' }),
       userMessage,
-      expect.objectContaining({ context: expect.stringContaining('before HITL pause') }),
+      expect.objectContaining({
+        context: expect.stringContaining('before HITL pause'),
+        createdAtOnInsert: new Date(req.turnStartedAt),
+      }),
     );
     expect(mockGenerationJobManager.steering.consumeRecovered).not.toHaveBeenCalled();
     expect(failArgs).toEqual([

api/server/controllers/agents/__tests__/responses.unit.spec.js

@@ -849,7 +849,9 @@ describe('createResponse controller', () => {
     expect(mockApplyContextToAgent).toHaveBeenCalledWith(
       expect.objectContaining({
         agent,
-        sharedRunContext: expect.stringContaining(memoryInstructions),
+        runContext: expect.objectContaining({
+          memory: expect.stringContaining(memoryInstructions),
+        }),
       }),
     );
     expect(require('~/models').getFormattedMemories).toHaveBeenCalledWith({
@@ -2497,7 +2499,7 @@ describe('createResponse controller', () => {
         expect.objectContaining({
           agent: expect.objectContaining({ id: 'agent-123' }),
           agentId: 'agent-123',
-          sharedRunContext: 'PDF context: ocr_file.pdf',
+          runContext: expect.objectContaining({ agentFiles: 'PDF context: ocr_file.pdf' }),
         }),
       );
     });
@@ -2540,7 +2542,7 @@ describe('createResponse controller', () => {
       expect(mockApplyContextToAgent).toHaveBeenCalledWith(
         expect.objectContaining({
           agentId: 'agent-handoff',
-          sharedRunContext: 'Handoff context',
+          runContext: expect.objectContaining({ agentFiles: 'Handoff context' }),
         }),
       );
     });

api/server/controllers/agents/client.js

@@ -140,6 +140,7 @@ const {
   prependQuotes,
   applyAttachmentOnlyText,
   hydrateMissingIndexTokenCounts,
+  createHistoryContextUpdates,
   injectSkillPrimes,
   buildAgentEventActorSkillMessages,
   collectFreshSkillPrimeNames,
@@ -2653,6 +2654,12 @@ class AgentClient extends BaseClient {
     };
     /** Memory copies built for canonical recounts, reused by the memory payload pass. */
     const memoryFormattedMessages = [];
+    /** Date-change and send-time notes, prepended to the prompt copy only. */
+    const historyContext = createHistoryContextUpdates({
+      req: this.options.req,
+      messages: orderedMessages,
+      agents: allAgents.map(({ agent }) => agent),
+    });
 
     const formattedMessages = orderedMessages.map((message, i) => {
       const formattedMessage = formatMessage({
@@ -2701,6 +2708,8 @@ class AgentClient extends BaseClient {
       const turnFiles = this.message_file_map?.[message.messageId] ?? message.files;
       applyAttachmentOnlyText(formattedMessage, turnFiles);
 
+      const contextUpdate = historyContext.apply(formattedMessage, i);
+
       /**
        * A summarize round that errored or was cut off never reaches the model:
        * the formatter would take its partial text as the history boundary and
@@ -2711,6 +2720,8 @@ class AgentClient extends BaseClient {
        * canonical recount reads an unstripped surface instead.
        */
       const droppedPromptSummary = dropUnusableSummaryParts(formattedMessage);
+      const promptDiffersFromStored =
+        Boolean(message.fileContext) || droppedPromptSummary || contextUpdate != null;
 
       const dbTokenCount = Number(orderedMessages[i].tokenCount);
       const hasDbTokenCount = Number.isFinite(dbTokenCount) && dbTokenCount > 0;
@@ -2730,20 +2741,19 @@ class AgentClient extends BaseClient {
       if (needsCanonicalTokenCount) {
         /** Without fileContext the memory copy is content-identical to the
          *  prompt copy, so the prompt copy is the counting surface; with it (or
-         *  with a dropped summary), the canonical count must be taken from the
-         *  message as stored. */
+         *  with a dropped summary or a context update), the canonical count must
+         *  be taken from the message as stored. */
         let countSurface = formattedMessage;
-        if (message.fileContext || droppedPromptSummary) {
+        if (promptDiffersFromStored) {
           memoryFormattedMessages[i] = buildMemoryFormattedMessage(message);
           countSurface = memoryFormattedMessages[i];
         }
         canonicalTokenCount = countFormattedMessageTokens(countSurface, encoding);
       }
 
-      const promptMessageTokenCount =
-        message.fileContext || droppedPromptSummary
-          ? countFormattedMessageTokens(formattedMessage, encoding)
-          : canonicalTokenCount;
+      const promptMessageTokenCount = promptDiffersFromStored
+        ? countFormattedMessageTokens(formattedMessage, encoding)
+        : canonicalTokenCount;
 
       /* If message has files, calculate image token cost */
       if (this.message_file_map && this.message_file_map[message.messageId]) {
@@ -2904,7 +2914,8 @@ class AgentClient extends BaseClient {
     }
     /** After the steer stamp, which adds replayed steers' documents of its own. */
     dedupeDocumentNames(payload);
-    if (hasFileContext) {
+    const hasPromptOnlyContext = hasFileContext || historyContext.hasUpdates;
+    if (hasPromptOnlyContext) {
       for (let i = 0; i < orderedMessages.length; i++) {
         memoryPayload.push(
           memoryFormattedMessages[i] ?? buildMemoryFormattedMessage(orderedMessages[i]),
@@ -2930,7 +2941,7 @@ class AgentClient extends BaseClient {
         });
       }
     }
-    this.memoryPayload = hasFileContext ? memoryPayload : null;
+    this.memoryPayload = hasPromptOnlyContext ? memoryPayload : null;
     messages = orderedMessages;
     promptTokens = promptTokenTotal;
 
@@ -2940,7 +2951,6 @@ class AgentClient extends BaseClient {
      * user message above; only side-channel context belongs here.
      * Memory context is handled separately and applied per-agent based on config.
      */
-    const sharedRunContextParts = [];
     const [augmentedPrompt, [memories, configServers], agentScopedContext] = await Promise.all([
       this.contextHandlers?.createContext(),
       earlySharedContextPromise,
@@ -2954,7 +2964,6 @@ class AgentClient extends BaseClient {
     this.augmentedPrompt = augmentedPrompt;
     if (this.augmentedPrompt) {
       modelBoundFileContexts.add(this.augmentedPrompt);
-      sharedRunContextParts.push(this.augmentedPrompt);
     }
 
     /** Memory context (user preferences/memories). Keyed context (with memory
@@ -3008,7 +3017,6 @@ class AgentClient extends BaseClient {
       return canonicalMemoryCache.get(cacheKey);
     };
 
-    const sharedRunContext = sharedRunContextParts.join('\n\n');
     const memoryAgentEnabled = isMemoryAgentEnabled(this.options.req.config?.memory);
 
     const configuredContextAttachments = this.options.agentContextAttachmentsByAgentId;
@@ -3082,7 +3090,7 @@ class AgentClient extends BaseClient {
       assertLateBoundContent = false,
     ) => {
       normalizeInstructions(agent);
-      const agentRunContextParts = [sharedRunContext];
+      const runContext = { rag: this.augmentedPrompt };
       const agentMemoryContexts = [];
       const agentHasMemory = agentHasInlineMemoryTools(agent);
       if (agentId === this.options.agent.id || memoryAgentEnabled || agentHasMemory) {
@@ -3105,13 +3113,11 @@ class AgentClient extends BaseClient {
         const agentMemoryContext = formatMemoryContext(
           agentHasMemory ? partitionMemories?.withKeys : partitionMemories?.withoutKeys,
         );
-        if (agentMemoryContext) {
-          agentRunContextParts.push(agentMemoryContext);
-        }
+        runContext.memory = agentMemoryContext;
       }
       if (scopedContext) {
         modelBoundFileContexts.add(scopedContext);
-        agentRunContextParts.push(scopedContext);
+        runContext.agentFiles = scopedContext;
       }
 
       await applyContextToAgent({
@@ -3120,7 +3126,7 @@ class AgentClient extends BaseClient {
         logger,
         mcpManager,
         configServers,
-        sharedRunContext: agentRunContextParts.filter(Boolean).join('\n\n'),
+        runContext,
         ephemeralAgent: agentId === this.options.agent.id ? ephemeralAgent : undefined,
       });
       if (assertLateBoundContent) {
@@ -5663,7 +5669,7 @@ class AgentClient extends BaseClient {
               logger,
               mcpManager: resumeMcpManager,
               configServers: resumeConfigServers,
-              sharedRunContext: scopedContext ?? '',
+              runContext: { agentFiles: scopedContext },
               ephemeralAgent:
                 agent === this.options.agent ? this.options.req.body.ephemeralAgent : undefined,
             });
@@ -5765,7 +5771,7 @@ class AgentClient extends BaseClient {
                   logger,
                   mcpManager: resumeMcpManager,
                   configServers: resumeConfigServers,
-                  sharedRunContext: scopedContext ?? '',
+                  runContext: { agentFiles: scopedContext },
                 });
                 assertModelBoundContent({
                   onTraversalFailure: reportLocatorTraversalFailure,