feat: Store and Replay the Provider Output Items of Responses Tool Rounds

api/app/clients/BaseClient.js

@@ -1283,7 +1283,10 @@ class BaseClient {
     }
 
     const messages =
-      (await db.getMessages({ conversationId, user: this.user }, '+privateTextTokens')) ?? [];
+      (await db.getMessages(
+        { conversationId, user: this.user },
+        '+privateTextTokens +providerItems',
+      )) ?? [];
     /** A client that reads beyond the walk below (which stops at a checkpoint
      *  summary) receives every row here; the rest keep nothing. */
     this.onHistoryLoaded?.(messages);

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

@@ -1600,7 +1600,10 @@ describe('BaseClient', () => {
 
       const chatMessages = await TestClient.loadHistory(conversationId, '1');
 
-      expect(getMessages).toHaveBeenCalledWith({ conversationId, user }, '+privateTextTokens');
+      expect(getMessages).toHaveBeenCalledWith(
+        { conversationId, user },
+        '+privateTextTokens +providerItems',
+      );
       expect(chatMessages).toHaveLength(1);
       expect(chatMessages[0].text).toBe('Hello');
     });

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

@@ -1898,3 +1898,47 @@ describe('isStreamWritable', () => {
     expect(isStreamWritable({ headersSent: true, writableEnded: false }, null)).toBe(true);
   });
 });
+
+describe('provider output items', () => {
+  it('stores the items on the tool call parts without emitting them', async () => {
+    const { GenerationJobManager, sendEvent } = require('@librechat/api');
+    const { GraphEvents, createContentAggregator } = jest.requireActual('@librechat/agents');
+    const { getDefaultHandlers } = require('../callbacks');
+    const { contentParts, stepMap, aggregateContent } = createContentAggregator();
+    const handlers = getDefaultHandlers({
+      res: { write: jest.fn() },
+      aggregateContent,
+      contentParts,
+      stepMap,
+      toolEndCallback: jest.fn(),
+      collectedUsage: [],
+      streamId: 'conversation-1',
+      jobCreatedAt: 1234,
+    });
+    await handlers[GraphEvents.ON_RUN_STEP].handle(GraphEvents.ON_RUN_STEP, {
+      id: 'step-1',
+      index: 0,
+      stepDetails: {
+        type: 'tool_calls',
+        tool_calls: [{ id: 'call-1', name: 'lookup', args: '{}' }],
+      },
+    });
+    jest.clearAllMocks();
+
+    const providerItems = {
+      origin: 'origin-digest',
+      items: [
+        { id: 'rs_1', type: 'reasoning', summary: [], encrypted_content: 'opaque' },
+        { id: 'fc_1', type: 'function_call', status: 'completed', call_id: 'call-1' },
+      ],
+    };
+    await handlers[GraphEvents.ON_PROVIDER_OUTPUT_ITEMS].handle(
+      GraphEvents.ON_PROVIDER_OUTPUT_ITEMS,
+      { tool_calls: [{ id: 'call-1', providerItems }] },
+    );
+
+    expect(contentParts[0].tool_call.providerItems).toEqual(providerItems);
+    expect(GenerationJobManager.emitChunk).not.toHaveBeenCalled();
+    expect(sendEvent).not.toHaveBeenCalled();
+  });
+});

api/server/controllers/agents/callbacks.js

@@ -632,6 +632,19 @@ function getDefaultHandlers({
         }
       },
     },
+    /** Absent from an SDK that predates provider output items. */
+    ...(GraphEvents.ON_PROVIDER_OUTPUT_ITEMS != null && {
+      [GraphEvents.ON_PROVIDER_OUTPUT_ITEMS]: {
+        /**
+         * Registry-only: the provider output items of a finished tool round (OpenAI Responses
+         * ids, status, reasoning). Stored on the tool call parts so the next turn replays the
+         * round as it was sent; they carry encrypted reasoning and are never forwarded.
+         * @param {string} event - The event name.
+         * @param {import('@librechat/agents').ProviderOutputItemsEvent} data - The event data.
+         */
+        handle: (event, data) => aggregateContent({ event, data }),
+      },
+    }),
     [GraphEvents.ON_MESSAGE_DELTA]: {
       /**
        * Handle ON_MESSAGE_DELTA event.

api/server/controllers/agents/client.js

@@ -135,6 +135,7 @@ const {
   agentHasInlineMemoryTools,
   loadAgent: loadAgentFn,
   createMultiAgentMapper,
+  attachProviderItems,
   filterMalformedContentParts,
   countFormattedMessageTokens,
   prependFileContext,
@@ -2372,13 +2373,15 @@ class AgentClient extends BaseClient {
       this.compactionSemanticIndexSnapshot = undefined;
     }
     /** Always pass mapMethod; getMessagesForConversation applies it only to messages with addedConvo flag */
-    const orderedMessages = this.constructor.getMessagesForConversation({
-      messages,
-      parentMessageId,
-      summary: this.shouldSummarize,
-      mapMethod: createMultiAgentMapper(this.options.agent, this.agentConfigs),
-      mapCondition: (message) => message.addedConvo === true,
-    });
+    const orderedMessages = this.constructor
+      .getMessagesForConversation({
+        messages,
+        parentMessageId,
+        summary: this.shouldSummarize,
+        mapMethod: createMultiAgentMapper(this.options.agent, this.agentConfigs),
+        mapCondition: (message) => message.addedConvo === true,
+      })
+      .map(attachProviderItems);
     /**
      * Answers the user gave to earlier `ask_user_question` calls. Read from the
      * rows before `messages` is narrowed to `orderedMessages`; when those rows

api/server/controllers/agents/client.test.js

@@ -7931,6 +7931,90 @@ describe('AgentClient - titleConvo', () => {
         limitType: 'bytes',
       });
     });
+
+    describe('provider items', () => {
+      const toolRound = (extras = {}) => [
+        {
+          messageId: 'msg-1',
+          parentMessageId: null,
+          sender: 'User',
+          text: 'Look it up',
+          isCreatedByUser: true,
+        },
+        {
+          messageId: 'msg-2',
+          parentMessageId: 'msg-1',
+          sender: 'Assistant',
+          text: '',
+          isCreatedByUser: false,
+          content: [
+            { type: ContentTypes.TEXT, text: 'Looking it up.' },
+            {
+              type: ContentTypes.TOOL_CALL,
+              tool_call: { id: 'call_1', name: 'lookup', args: '{}', output: 'ok', progress: 1 },
+            },
+          ],
+          ...extras,
+        },
+        {
+          messageId: 'msg-3',
+          parentMessageId: 'msg-2',
+          sender: 'User',
+          text: 'Thanks',
+          isCreatedByUser: true,
+        },
+      ];
+
+      it('builds the prompt of a tool round as upstream when no provider items are stored', async () => {
+        const result = await client.buildMessages(toolRound(), 'msg-3', {});
+
+        expect(result.prompt).toMatchInlineSnapshot(`
+          [
+            {
+              "content": "Look it up",
+              "messageId": "msg-1",
+              "role": "user",
+            },
+            {
+              "content": [
+                {
+                  "text": "Looking it up.",
+                  "type": "text",
+                },
+                {
+                  "tool_call": {
+                    "args": "{}",
+                    "id": "call_1",
+                    "name": "lookup",
+                    "output": "ok",
+                    "progress": 1,
+                  },
+                  "type": "tool_call",
+                },
+              ],
+              "messageId": "msg-2",
+              "role": "assistant",
+            },
+            {
+              "content": "Thanks",
+              "messageId": "msg-3",
+              "role": "user",
+            },
+          ]
+        `);
+      });
+
+      it('puts the stored provider items back on their tool calls', async () => {
+        const providerItems = { origin: 'digest', items: [{ id: 'rs_1', type: 'reasoning' }] };
+        const history = toolRound({ providerItems: { call_1: providerItems } });
+
+        const result = await client.buildMessages(history, 'msg-3', {});
+
+        const toolCall = result.prompt[1].content.find((part) => part.tool_call)?.tool_call;
+        expect(toolCall.providerItems).toEqual(providerItems);
+        expect(history[1].content[1].tool_call).not.toHaveProperty('providerItems');
+      });
+    });
   });
 
   describe('provider-native YouTube file preflight', () => {

api/server/middleware/abortMiddleware.js

@@ -10,6 +10,7 @@ const {
   sanitizeMessageForTransmit,
   buildAbortedResponseMetadata,
   announceReply,
+  stripProviderItems,
 } = require('@librechat/api');
 const { truncateText, smartTruncateText } = require('~/app/clients/prompts');
 const clearPendingReq = require('~/cache/clearPendingReq');
@@ -131,7 +132,8 @@ async function abortMessage(req, res) {
           isCreatedByUser: true,
         })
       : null,
-    responseMessage,
+    /** The live content still carries provider items; they are server state. */
+    responseMessage: { ...responseMessage, content: stripProviderItems(responseMessage.content) },
   };
 
   logger.debug(`[abortMessage] ID: ${userId} | Aborted request: ${conversationId}`);

api/server/middleware/abortMiddleware.spec.js

@@ -33,6 +33,7 @@ jest.mock('@librechat/api', () => ({
   hasPersistableAbortContent: jest.requireActual('@librechat/api').hasPersistableAbortContent,
   announceReply: jest.requireActual('@librechat/api').announceReply,
   abortOwnedGeneration: jest.requireActual('@librechat/api').abortOwnedGeneration,
+  stripProviderItems: jest.requireActual('@librechat/api').stripProviderItems,
   countTokens: jest.fn().mockResolvedValue(100),
   isEnabled: jest.fn().mockReturnValue(false),
   sendEvent: jest.fn(),
@@ -327,6 +328,27 @@ describe('abortMiddleware - handleAbort billing', () => {
     expect(finalEvent.responseMessage.contextMeta).toEqual(contextMeta);
   });
 
+  it('keeps provider items out of the response sent to the client', async () => {
+    const part = {
+      type: 'tool_call',
+      tool_call: { id: 'call_1', name: 'x', providerItems: { origin: 'o', items: [] } },
+    };
+    GenerationJobManager.abortJob.mockResolvedValue({
+      success: true,
+      jobData: buildJobData(),
+      content: [part],
+      text: 'partial',
+      collectedUsage: [],
+    });
+    const res = buildRes();
+
+    await handleAbort()(buildReq(), res);
+
+    const finalEvent = JSON.parse(res.send.mock.calls[0][0]);
+    expect(finalEvent.responseMessage.content[0].tool_call.providerItems).toBeUndefined();
+    expect(finalEvent.responseMessage.content[0].tool_call.id).toBe('call_1');
+  });
+
   it('unsets context meta on a stopped response when the job carries none', async () => {
     GenerationJobManager.abortJob.mockResolvedValue({
       success: true,

api/server/routes/__tests__/messages-get.spec.js

@@ -69,6 +69,8 @@ jest.mock('@librechat/api', () => {
     stripPrivateMessageFields: jest.requireActual(
       '../../../../packages/api/src/protection/private/view',
     ).stripPrivateMessageFields,
+    stripProviderItems: jest.requireActual('../../../../packages/api/src/utils/message')
+      .stripProviderItems,
     createContentFilter: jest.fn(() => (req, res, next) => next()),
     inspectContent,
     extractChatContent,
@@ -590,6 +592,38 @@ describe('message route conversation ownership filters', () => {
     );
   });
 
+  it('does not accept tool call provider items from a client', async () => {
+    const conversationId = '11111111-1111-4111-8111-111111111111';
+    const toolCall = (providerItems) => ({
+      type: 'tool_call',
+      agentId: 'agent-1',
+      tool_call: {
+        id: 'call_1',
+        name: 'lookup',
+        args: '{}',
+        ...(providerItems && { providerItems }),
+      },
+    });
+    const providerItems = {
+      origin: 'digest',
+      items: [{ id: 'rs_1', encrypted_content: 'opaque' }],
+    };
+    saveMessage.mockImplementation(async (_ctx, message) => message);
+    saveConvo.mockResolvedValue({ conversationId });
+
+    const saved = await request(app)
+      .post(`/api/messages/${conversationId}`)
+      .send({
+        messageId: 'message-1',
+        text: '',
+        content: [toolCall(providerItems)],
+        providerItems: { call_1: providerItems },
+      });
+    expect(saved.status).toBe(201);
+    expect(saveMessage.mock.calls[0][1].content).toEqual([toolCall()]);
+    expect(JSON.stringify(saved.body)).not.toContain('opaque');
+  });
+
   it('should filter conversation message reads by authenticated user', async () => {
     getMessages.mockResolvedValue([{ messageId: 'message-1', conversationId: 'convo-1' }]);
 

api/server/routes/__tests__/messages-retention.spec.js

@@ -16,6 +16,8 @@ jest.mock('@librechat/api', () => ({
   stripPrivateMessageFields: jest.requireActual(
     '../../../../packages/api/src/protection/private/view',
   ).stripPrivateMessageFields,
+  stripProviderItems: jest.requireActual('../../../../packages/api/src/utils/message')
+    .stripProviderItems,
   unescapeLaTeX: jest.fn((value) => value),
   countTokens: jest.fn().mockResolvedValue(10),
   createContentFilter: jest.fn(() => (_req, _res, next) => next()),

api/server/routes/agents/__tests__/streamTenant.spec.js

@@ -166,6 +166,38 @@ describe('SSE stream tenant isolation', () => {
       );
     });
 
+    it('writes stream events and the final event without tool call provider items', async () => {
+      const toolCall = { id: 'call_1', name: 'lookup', args: '{}' };
+      const content = [
+        {
+          type: 'tool_call',
+          tool_call: { ...toolCall, providerItems: { origin: 'digest', items: [] } },
+        },
+      ];
+      mockGenerationJobManager.subscribe.mockImplementation((_streamId, writeEvent, onDone) => {
+        process.nextTick(() => {
+          writeEvent({ sync: true, resumeState: { aggregatedContent: content } });
+          onDone({ final: true, responseMessage: { content } });
+        });
+        return { unsubscribe: jest.fn() };
+      });
+      mockGenerationJobManager.getJob.mockResolvedValue({
+        metadata: { userId: 'user-123' },
+        status: 'running',
+        createdAt: 1000,
+      });
+
+      const res = await request(app).get('/agents/chat/stream/stream-123?generationCreatedAt=1000');
+
+      expect(res.status).toBe(200);
+      const [sync, final] = res.text
+        .split('\n\n')
+        .filter((frame) => frame.includes('data: '))
+        .map((frame) => JSON.parse(frame.split('data: ')[1]));
+      expect(sync.resumeState.aggregatedContent[0].tool_call).toEqual(toolCall);
+      expect(final.responseMessage.content[0].tool_call).toEqual(toolCall);
+    });
+
     it('pins an unfenced legacy subscription to the generation that passed authorization', async () => {
       mockSubscribeSuccess();
       mockGenerationJobManager.getJob.mockResolvedValue({
@@ -640,6 +672,29 @@ describe('SSE stream tenant isolation', () => {
       expect(res.body.active).toBe(true);
     });
 
+    it('leaves the provider items of live tool calls out of the status', async () => {
+      mockUserId = 'user-123';
+      mockTenantId = 'tenant-a';
+      mockGenerationJobManager.getJob.mockResolvedValue({
+        metadata: { userId: 'user-123', tenantId: 'tenant-a' },
+        status: 'running',
+        createdAt: 1000,
+      });
+      const toolCall = { id: 'call_1', name: 'lookup', args: '{}' };
+      const providerItems = { origin: 'digest', items: [{ id: 'rs_1', encrypted_content: 'x' }] };
+      mockGenerationJobManager.getResumeState.mockResolvedValue({
+        runSteps: [],
+        aggregatedContent: [{ type: 'tool_call', tool_call: { ...toolCall, providerItems } }],
+      });
+
+      const res = await request(app).get('/agents/chat/status/conv-123');
+
+      expect(res.status).toBe(200);
+      const expected = [{ type: 'tool_call', tool_call: toolCall }];
+      expect(res.body.aggregatedContent).toEqual(expected);
+      expect(res.body.resumeState.aggregatedContent).toEqual(expected);
+    });
+
     it.each([true, false])(
       'reports the run temporary state %s recorded at admission',
       async (isTemporary) => {